Merge remote-tracking branch 'origin/worktree/ci-native-windows-20260808' into worktree/ci-native-windows-coverage-20260808

packages/boot/app-boot/README.i18n.yaml

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

packages/boot/app-boot/README.md

@@ -0,0 +1,58 @@
+# `@deepseek-ai/dsh-app-boot`
+
+English | [中文](README.zh.md)
+
+Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md) and [`dsh-acp-demo`](../../examples/acp-demo/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so loader-failure behavior has one owner instead of drifting between published artifacts.
+
+| Export | Role |
+|---|---|
+| `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) |
+| `loadLayeredEnv(binName, cwd?, warn?)` | Build the product CLI's frozen inherited > project `.env` > user `.env` snapshot, reject bootstrap-only file variables, and materialize accepted file values without replacing inherited ones |
+| `installFailLoud(binName, proc?, release?)` | Turn an unhandled boot or later Loader rejection into one labelled stderr line + `exit(1)`; the optional `release` teardown is awaited between the two (bounded by `FAIL_LOUD_RELEASE_TIMEOUT_MS`) so a terminal-owning surface restores the terminal before exit; returns the uninstaller |
+| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | How long `installFailLoud` waits for its `release` hook; a wedged disposer delays the fatal exit, never cancels it |
+| `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 |
+| `loadOptionalPatches(binName, file)` | Parse an optional patch-list file (a profile's `cordis.patch.yml`) — 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; a missing file also throws, because the caller named it |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | Mount the statically imported Include builtin and retain the exact root entry used by user patch-layer HMR |
+| `watchUserPatches(ctx, options)` | Register the named patch file 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 user layer) and returns an async disposer |
+| `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile machinery (see [Profiles](#profiles)) |
+| `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), 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 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 |
+
+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.
+
+The Loader mounts entries concurrently, so a surface can already own the terminal when something else fails: exiting without the tree's own teardown would leave raw mode, bracketed paste, and the keyboard protocol set on the user's shell, and an in-flight terminal query's reply would land as literal text at the next prompt. A config-tree failure settles through `boot()`, whose disposal of the partial context runs the surface's own shutdown before the labelled rejection. For the rejections `boot()` cannot see — a plugin's detached async work rejecting during or after mounting — a terminal-owning bin passes `release` to dispose the tree before the exit commits; `dsh` captures the root context in `boot()`'s `prepare` hook rather than from its return value so the hook covers the whole mounting window. While a release is in flight the handler stays installed and latched: the first rejection is the reported one, and later rejections (teardown's own included) are swallowed rather than becoming uncaught and killing the process mid-teardown.
+
+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 shipped raw/Web bare plugin to appear in the resolver manifest's `dependencies`.
+
+This package carries no loader hooks and no dev-mode surface. The [`dsh` app](../../../apps/cli/README.md) owns its Node source-launch hook and consumes these helpers for the boot sequence; built consumers continue to use plain Node package resolution.
+
+## Profiles
+
+A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home resolves through [`resolveDshHome`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) holding a `package.json` — out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list — and the user's own `cordis.patch.yml`. A bundle is an npm package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves each `dsh.profile.bundles` name two-anchored (the dsh installation first, then the profile directory) and fails loud on a listed package without a bundle declaration. `composeEntries` applies patch layers over an empty entry list through the include's own `applyEntryPatches`, so composition, flag derivation, and config dumps can never drift from what boots. `healProfilesModuleFallback` maintains the flat `$DSH_HOME/profiles/node_modules` directory — one symlink per package the installation's app and bundles depend on — so bare plugin names in any profile resolve through Node's ordinary parent-walk without pnpm ever managing in-box packages. `PROFILE_TEMPLATES` (`web`, `headless`) auto-initialize on first use; other names fail loud until `initProfile` creates them (the `dsh plugin` path).
+
+User-level machine-local preferences also live in the Harness home:
+
+- **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects [bootstrap-only file variables](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision) case-insensitively, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
+- **`cordis.patch.yml`** (home level) and **`profiles/<name>/cordis.patch.yml`** — the user patch layers, applied after every bundle layer (per-profile first, then the home-level file, which therefore outranks it): 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 composed tree is a stderr warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the layer with `[]`.
+
+Long-lived surfaces keep `cordis.patch.yml` live through `watchUserPatches`; one-shot runs read only the startup value. The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlay/flag 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.
+
+## Model Experience
+
+Indirectly, through the plugin tree it loads, which determines the prompts, schemas, messages, and model adapter in the resulting application; the one export that contributes model-visible text, `addHarnessSourceSection`, does so only when a consumer calls it after boot.
+
+#### KV Cache effect
+
+No direct invalidation from `boot()`; a consumer that calls `addHarnessSourceSection` places one short line near the system prompt's head, before per-request content, so it does not invalidate the cache across turns, and any other request-prefix change is owned by the named consumer.
+
+## Known Limitations and Deferred Work
+
+- **Bare package specifiers depend on Loader internals** — production bins need Loader's optional native helper; an in-process caller without it must use resolvable relative/file specifiers or provide its own module-resolution hook.
+- **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
+- **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins.
+- **User patch layers are patch-shaped** — an id-targeted patch replaces the entry's whole `config` rather than deep-merging, so a profile override restates the bundle fields it keeps.

packages/boot/app-boot/README.zh.md

@@ -0,0 +1,58 @@
+# `@deepseek-ai/dsh-app-boot`
+
+[English](README.md) | 中文
+
+供 app bin（[`dsh`](../../../apps/cli/README.md) 与 [`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
+
+| 导出 | 职责 |
+|---|---|
+| `resolveConfigPath(path, snapshotMode, cwd?)` | 生成绝对配置路径；当 `snapshotMode === 'replay'` 时，把 basename 为 `cordis.yml`/`.yaml` 的文件替换为同级 `cordis.snapshot.yml` |
+| `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
+| `loadLayeredEnv(binName, cwd?, warn?)` | 构建产品 CLI（命令行界面）冻结的「继承环境 > 项目 `.env` > 用户 `.env`」快照，拒绝文件中的 bootstrap-only 变量，并在不替换继承值的前提下物化其余文件值 |
+| `installFailLoud(binName, proc?, release?)` | 将启动期或后续未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数 |
+| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
+| `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
+| `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
+| `loadOptionalPatches(binName, file)` | 解析一份可选的 patch 列表文件（即 profile 的 `cordis.patch.yml`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
+| `loadOverlayPatches(binName, file)` | 解析一份形状相同的必需 patch 列表文件；文件缺失同样抛出异常，因为该文件是调用方指名的 |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项 |
+| `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
+| `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
+| `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
+| `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
+
+Loader 结算会在导入或生命周期失败时 reject，并携带失败的配置项与阶段；`boot()` 会 dispose 部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
+
+Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前释放整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间处理函数保持注册并加闩：被报告的始终是第一个 rejection，后续 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 源码；其配置门禁要求每个已交付的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
+
+此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md)持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
+
+## Profile
+
+profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。
+
+用户级的机器本地偏好同样位于 Harness home 中：
+
+- **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝 [bootstrap-only 文件变量](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision)，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
+- **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
+
+长期运行的 surface 会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
+
+## 模型体验
+
+模型通过此包加载的插件树间接受到影响；该树决定最终应用中的提示词、schema、消息和模型适配器。唯一贡献模型可见文本的导出 `addHarnessSourceSection`，也只有在消费方启动后调用它时才会产生影响。
+
+#### KV Cache 影响
+
+`boot()` 不会直接使缓存失效；消费方调用 `addHarnessSourceSection` 时，会在系统提示词靠前位置、逐请求内容之前添加一行短文本，因此不会使跨轮次缓存失效。请求前缀的其他任何变化均由相应的具名消费方持有。
+
+## 已知限制与延期工作
+
+- **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生 helper；没有该 helper 的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
+- **快照回放替换仅识别特定 basename**：只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
+- **环境发现以启动为界**：`loadLayeredEnv` 只读取一次调用目录与 Harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。
+- **用户 patch 层采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此 profile 覆盖必须重述需要保留的组合包字段。

packages/boot/app-boot/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@deepseek-ai/dsh-app-boot",
+  "description": "Shared boot glue for the app bins: .env loading, fail-loud Loader guards, snapshot-aware config resolution, and the Loader boot sequence",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "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-environment": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-paths": "^0.0.1",
+    "@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-environment": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-paths": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@types/js-yaml": "^4.0.9",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/boot/app-boot/src/index.ts

@@ -0,0 +1,802 @@
+/**
+ * Shared boot glue for the app bins (`dsh`, `dsh-acp-demo`): load the gitignored
+ * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
+ * optional user patch layers from the Harness home (`~/.dsh`), expose its path resolver to
+ * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
+ * @module @deepseek-ai/dsh-app-boot
+ */
+
+import { pathToFileURL } from 'node:url'
+import { readFileSync } from 'node:fs'
+import { parseEnv } from 'node:util'
+import { basename, dirname, resolve } from 'node:path'
+import * as yaml from 'js-yaml'
+import { Context, type FiberState } from 'cordis'
+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 { createEnvironmentSnapshot, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
+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'
+
+declare module 'cordis' {
+  interface Context {
+    /** Harness-home path resolver available to Loader `!!js` config expressions. */
+    dshHomePath?: typeof dshHomePath
+  }
+}
+
+export {
+  composeEntries,
+  DEFAULT_PROFILE_BUNDLES,
+  healProfilesModuleFallback,
+  initProfile,
+  loadProfile,
+  PROFILE_PATCH_FILENAME,
+  PROFILE_TEMPLATES,
+  PROFILES_DIR,
+  readProfileManifest,
+  resolveBundleDir,
+  resolveProfileDir,
+  writeProfileManifest,
+  type DshBundleManifest,
+  type DshManifestSection,
+  type DshProfileManifest,
+  type Profile,
+  type ProfileLayer,
+  type ProfileManifest,
+} from './profile.ts'
+
+/**
+ * Resolve the config to boot. Replay swaps a `cordis.yml` basename for
+ * `cordis.snapshot.yml` in the same directory; every other mode keeps the path.
+ * @param configPath - the requested config path (absolute, or relative to `cwd`).
+ * @param snapshotMode - the bin's `$DSH_SNAPSHOT` value; only `'replay'` swaps the
+ *   basename.
+ * @param cwd - the base a relative `configPath` resolves against.
+ * @returns the absolute path of the config to boot.
+ */
+export function resolveConfigPath(
+  configPath: string, snapshotMode: string | undefined, cwd: string = process.cwd(),
+): string {
+  const absolute = resolve(cwd, configPath)
+  if (snapshotMode !== 'replay') return absolute
+  const dir = dirname(absolute)
+  const replayName = basename(absolute).replace(/cordis\.ya?ml$/, 'cordis.snapshot.yml')
+  return resolve(dir, replayName)
+}
+
+/**
+ * Load the optional gitignored `.env` from `dir`. Missing files fall back to the
+ * ambient environment; other read failures are reported through `warn`.
+ * @param binName - the diagnostic prefix on the warn line.
+ * @param dir - the directory whose `.env` to load.
+ * @param warn - sink for the one-line misconfiguration diagnostic.
+ */
+export function loadEnv(
+  binName: string, dir: string = process.cwd(),
+  warn: (line: string) => void = line => void process.stderr.write(line),
+): void {
+  try {
+    process.loadEnvFile(resolve(dir, '.env'))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
+      warn(`${binName}: failed to load .env: ${String(error)}\n`)
+    }
+    // ENOENT (no .env) is fine — rely on the ambient environment.
+  }
+}
+
+/** Exact names no discovered file may set. */
+const BOOTSTRAP_NAMES = new Set([
+  // Process launch and module resolution.
+  'PATH', 'HOME', 'USERPROFILE', 'SHELL',
+  'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
+  'LD_PRELOAD', 'LD_LIBRARY_PATH', 'LD_AUDIT',
+  // Interpreter startup hooks.
+  'BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS',
+  'PERL5OPT', 'PERL5LIB', 'PYTHONSTARTUP', 'PYTHONPATH', 'RUBYOPT', 'RUBYLIB',
+  'JAVA_TOOL_OPTIONS', '_JAVA_OPTIONS', 'JDK_JAVA_OPTIONS',
+  'PYTHONHOME',
+  // Version-control command hooks and config redirects.
+  'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_EXTERNAL_DIFF', 'GIT_PAGER', 'GIT_EDITOR',
+  'GIT_ASKPASS', 'SSH_ASKPASS',
+  'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_COUNT',
+  'EDITOR', 'VISUAL', 'PAGER',
+  // Network reach and trust.
+  'SSL_CERT_FILE', 'SSL_CERT_DIR',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
+  'NODE_TLS_REJECT_UNAUTHORIZED',
+])
+
+/** Name prefixes no discovered file may set. */
+const BOOTSTRAP_PREFIXES = ['DSH_', 'XDG_', 'DYLD_', 'BASH_FUNC_']
+
+/**
+ * Whether a variable may come only from the inherited process environment
+ * because it changes process, runtime, VCS, or network bootstrap.
+ * @param name - the variable name.
+ * @returns true when only the inherited environment may supply it.
+ */
+function isBootstrapOnly(name: string): boolean {
+  const upper = name.toUpperCase()
+  return BOOTSTRAP_NAMES.has(upper) || BOOTSTRAP_PREFIXES.some(prefix => upper.startsWith(prefix))
+}
+
+/**
+ * Parse one directory's `.env` without applying it, rejecting bootstrap-only
+ * names before any value is materialized.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param dir - the directory whose `.env` to read.
+ * @param warn - sink for the one-line unreadable-file diagnostic.
+ * @returns the parsed entries, or `undefined` when the file is absent or unreadable.
+ * @throws when the file declares a name {@link isBootstrapOnly} rejects.
+ */
+function readEnvLayer(
+  binName: string, dir: string, warn: (line: string) => void,
+): { path: string; values: Record<string, string> } | undefined {
+  const path = resolve(dir, '.env')
+  let content: string
+  try {
+    content = readFileSync(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
+      warn(`${binName}: failed to load .env: ${String(error)}\n`)
+    }
+    // ENOENT (no .env) is fine — rely on the ambient environment.
+    return undefined
+  }
+  // Parse once so validation and materialization use exactly the same entries.
+  const values = parseEnv(content) as Record<string, string>
+  for (const name of Object.keys(values)) {
+    if (!isBootstrapOnly(name)) continue
+    throw new Error(
+      `${binName}: ${path} sets "${name}", which only the launching environment may set`
+      + ' (it decides how this process starts, where its code and instructions load from, or how it'
+      + ` reaches the network); export ${name} instead of putting it in a .env file`,
+    )
+  }
+  return { path, values }
+}
+
+/**
+ * Load the product CLI's inherited > invoking-directory `.env` > Harness-home
+ * `.env` snapshot. The Harness home resolves before either file; both files
+ * are checked before either is applied, and accepted values are materialized
+ * without replacing inherited ones. The snapshot preserves source provenance.
+ * @param binName - the diagnostic prefix on the diagnostics.
+ * @param cwd - the invoking directory whose `.env` is the project layer.
+ * @param warn - sink for the one-line misconfiguration diagnostics.
+ * @returns this run's frozen environment snapshot.
+ * @throws when either file declares a bootstrap-only variable.
+ */
+export function loadLayeredEnv(
+  binName: string, cwd: string = process.cwd(),
+  warn: (line: string) => void = line => void process.stderr.write(line),
+): EnvironmentSnapshot {
+  const home = resolveDshHome()
+  const inherited = { ...process.env } as Record<string, string>
+  // Parse both layers first: a rejection must not leave one file applied.
+  const project = readEnvLayer(binName, cwd, warn)
+  const user = home === resolve(cwd) ? undefined : readEnvLayer(binName, home, warn)
+  // Apply the checked values without replacing a higher-ranked name.
+  for (const layer of [project, user]) {
+    if (layer === undefined) continue
+    for (const [name, value] of Object.entries(layer.values)) {
+      if (process.env[name] === undefined) process.env[name] = value
+    }
+  }
+  return createEnvironmentSnapshot([
+    { source: 'process', values: inherited },
+    ...project === undefined ? [] : [{ source: 'project-env' as const, path: project.path, values: project.values }],
+    ...user === undefined ? [] : [{ source: 'user-env' as const, path: user.path, values: user.values }],
+  ])
+}
+
+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
+// from what the include mounts. User patch layers share it so they may
+// reference `process.env`.
+const userPatchesSchema = entryListSchema
+
+/** Options for live user patch-layer reconciliation. */
+export interface UserPatchWatchOptions {
+  /** Diagnostic prefix used by {@link loadOptionalPatches}. */
+  binName: string
+  /** Absolute path of the watched patch file (a profile's `cordis.patch.yml`). */
+  filename: string
+  /**
+   * Compose the full patch list for a fresh user-layer generation —
+   * the same composition the app booted with, so a reload can interleave the
+   * new user patches between app-owned layers (bundle layers below,
+   * overlay/flag patches above). Identity when omitted: the user layer
+   * is the whole patch list.
+   */
+  compose?: (userPatches: PatchOptions[]) => PatchOptions[]
+}
+
+/**
+ * Watch the user patch layer 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, file, 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 watchUserPatches(
+  ctx: Context,
+  options: UserPatchWatchOptions,
+): Promise<() => Promise<void>> {
+  const { binName, filename, compose = (patches: PatchOptions[]) => patches } = options
+  const hmr = ctx.get('hmr')
+  if (hmr === undefined) throw new Error(`${binName}: user patch-layer watching requires the Cordis HMR service`)
+  const entry = bootstrapIncludes.get(ctx)
+  if (entry === undefined) throw new Error(`${binName}: user patch-layer watching requires the root Include entry`)
+  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 user-layer reload.
+    const { patches: _previousPatches, ...includeConfig } = entry.options.config as Include.Config
+    const userPatches = loadOptionalPatches(binName, filename) ?? []
+    const patches = compose(userPatches)
+    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;
+    // the HMR effect registration then fails with INACTIVE_EFFECT. That is the
+    // app exiting exactly as asked, not a watch failure, so return a no-op
+    // disposer instead of crashing.
+    if ((error as { code?: string } | null)?.code === 'INACTIVE_EFFECT') return async () => {}
+    throw error
+  }
+}
+
+/**
+ * Load an optional patch-list file: a top-level YAML array of loader patch
+ * entries (`@cordisjs/plugin-include`'s `PatchOptions`): id-targeted config
+ * overrides and `insert` lists, with `!!js` expressions allowed. A missing
+ * file means "no layer"; an unreadable, unparsable, or non-array file throws —
+ * a present patch file that cannot apply is a misconfiguration and must fail
+ * loud at boot, never be silently skipped.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param file - absolute path of the patch file.
+ * @returns the parsed patches, or `undefined` when the file does not exist.
+ */
+export function loadOptionalPatches(binName: string, file: string): PatchOptions[] | undefined {
+  let content: string
+  try {
+    content = readFileSync(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return undefined
+    throw new Error(`${binName}: failed to read patches ${file}: ${String(error)}`)
+  }
+  return parsePatchList(binName, file, content, 'patches')
+}
+
+/**
+ * Load a required overlay patch list: a bundle's `cordis.patch.yml` or a
+ * `--patch <path>` overlay. Same file format as {@link loadOptionalPatches},
+ * but a missing file throws, because the caller named this file — its absence
+ * is a misconfiguration, not "no overlay".
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param file - absolute path of the overlay file.
+ * @returns the parsed patch list.
+ */
+export function loadOverlayPatches(binName: string, file: string): PatchOptions[] {
+  let content: string
+  try {
+    content = readFileSync(file, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read overlay ${file}: ${String(error)}`)
+  }
+  return parsePatchList(binName, file, content, 'overlay')
+}
+/**
+ * Parse one loader patch list: a top-level YAML array of
+ * `@cordisjs/plugin-include` `PatchOptions` (id-targeted config overrides and
+ * `insert` lists, `!!js` expressions allowed). Every shape failure throws,
+ * because a patch file that cannot be applied at all is a misconfiguration; a
+ * single patch whose target row is absent stays a per-entry Loader warning, so
+ * one overlay shared across surfaces does not have to match every tree.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param file - the source path, quoted in errors.
+ * @param content - the file's text.
+ * @param label - what to call this list in errors (`patches`, `overlay`).
+ * @returns the parsed patch list.
+ */
+function parsePatchList(
+  binName: string, file: string, content: string, label: string,
+): PatchOptions[] {
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content, { schema: userPatchesSchema })
+  } catch (error) {
+    throw new Error(`${binName}: failed to parse ${label} ${file}: ${String(error)}`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${binName}: ${label} ${file} must be a top-level YAML array of loader patch entries`)
+  }
+  parsed.forEach((entry, index) => {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      throw new Error(`${binName}: ${label} entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
+    }
+  })
+  return parsed as PatchOptions[]
+}
+
+/** One overlay patch list with the label provenance comments print for it. */
+export interface ConfigDumpLayer {
+  /** Source name shown in provenance comments (a file basename or path). */
+  label: string
+  /** The layer's patches, from {@link loadOverlayPatches} / {@link loadOptionalPatches}. */
+  patches: PatchOptions[]
+}
+
+/**
+ * Compose the effective entry list exactly as `boot()` would mount it: parse
+ * the base config file with the include's entry-list dialect, apply every
+ * layer's patches as ONE flattened list through the include's own patch
+ * algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so
+ * even patch-visibility corner cases (a later layer targeting a group child a
+ * plain config replacement introduced, which the single-pass id index never
+ * sees) compose identically — then render the result as YAML in the same
+ * dialect (`!!js` expressions print verbatim, unevaluated).
+ *
+ * Every run of rows with the same provenance is preceded by a `# ==` comment
+ * naming the file that contributed the rows and any layers that patched them,
+ * so the output stays a loadable YAML document while showing which section
+ * comes from which file. Provenance is derived from single-call prefix
+ * snapshots (base + layers 1..k), diffed positionally: the patch algorithm
+ * only rewrites rows in place or appends, so a top-level index identifies one
+ * row across snapshots, and a layer whose addition changes the row (config
+ * replacement, disable, group insert) is listed as having patched it.
+ *
+ * A patch that matches no row is reported through `warn` with its layer
+ * label, mirroring the Loader's boot-time warning. Earlier layers' patches
+ * see an identical preceding state in every snapshot that includes them, so
+ * each snapshot's warning list extends the previous one and the new tail
+ * belongs to the added layer.
+ * @param binName - the diagnostic prefix on read/parse errors.
+ * @param absoluteConfigPath - the base config file `boot()` would include.
+ * @param layers - overlay layers in application order (later wins).
+ * @param warn - sink for skipped-patch diagnostics; defaults to stderr.
+ * @returns the composed entry list rendered as a YAML document with
+ * provenance comment separators.
+ */
+export function renderConfigDump(
+  binName: string,
+  absoluteConfigPath: string,
+  layers: ConfigDumpLayer[],
+  warn: (line: string) => void = line => void process.stderr.write(`${line}\n`),
+): string {
+  let content: string
+  try {
+    content = readFileSync(absoluteConfigPath, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content, { schema: entryListSchema })
+  } catch (error) {
+    throw new Error(`${binName}: failed to parse config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${binName}: config ${absoluteConfigPath} must be a top-level YAML array of entries`)
+  }
+  const baseLabel = basename(absoluteConfigPath)
+  // The YAML boundary yields untyped rows; the include validates entry shape
+  // at mount, and the dump prints whatever the file holds, so `EntryOptions`
+  // here is structural trust in the same file `boot()` would include.
+  const base = parsed as Parameters<typeof applyEntryPatches>[0]
+  // snapshot_k = ONE application of layers 1..k flattened — boot's exact call
+  // shape for that prefix. snapshot_N is therefore the mounted composition.
+  // The patches are cloned per call: applyEntryPatches detaches the entry
+  // list but pushes `insert` rows by reference from the patch list, so
+  // sharing patch objects across snapshot calls would leak a later
+  // snapshot's mutations into an earlier one's result.
+  const snapshot = (count: number, warnings: string[]): ReturnType<typeof applyEntryPatches> => {
+    const flattened = structuredClone(layers.slice(0, count).flatMap(layer => layer.patches))
+    return applyEntryPatches(base, flattened, (message: string, ...args: unknown[]) => {
+      // The include logs through cordis's printf-style logger (`%C` = code); a
+      // dump has no logger, so substitute inline for a plain line.
+      let index = 0
+      warnings.push(message.replace(/%C/g, () => JSON.stringify(args[index++])))
+    })
+  }
+  let previous = base
+  let previousWarnings: string[] = []
+  const provenance: { origin: string; patchedBy: string[] }[] = base.map(() => ({ origin: baseLabel, patchedBy: [] }))
+  let composed = base
+  for (let count = 1; count <= layers.length; count += 1) {
+    const layer = layers[count - 1]
+    /* v8 ignore next -- count iterates 1..length, so the slot exists */
+    if (layer === undefined) continue
+    const warnings: string[] = []
+    composed = snapshot(count, warnings)
+    for (const line of warnings.slice(previousWarnings.length)) {
+      warn(`${binName}: [${layer.label}] ${line}`)
+    }
+    const before = previous.map(entry => JSON.stringify(entry))
+    for (let index = 0; index < composed.length; index += 1) {
+      if (index >= before.length) provenance.push({ origin: layer.label, patchedBy: [] })
+      else if (JSON.stringify(composed[index]) !== before[index]) provenance[index]?.patchedBy.push(layer.label)
+    }
+    previous = composed
+    previousWarnings = warnings
+  }
+  return groupedDump(composed, provenance)
+}
+
+/** Render the composed rows grouped under one provenance comment per contiguous run. */
+function groupedDump(
+  composed: readonly unknown[],
+  provenance: readonly { origin: string; patchedBy: string[] }[],
+): string {
+  const lines: string[] = []
+  let currentLabel: string | undefined
+  let group: unknown[] = []
+  const flush = (): void => {
+    if (currentLabel === undefined || group.length === 0) return
+    lines.push(`# == ${currentLabel}`)
+    lines.push(yaml.dump(group, { schema: entryListSchema, noRefs: true }).trimEnd())
+    group = []
+  }
+  for (let index = 0; index < composed.length; index += 1) {
+    const record = provenance[index]
+    /* v8 ignore next -- provenance is index-aligned with composed by construction */
+    if (record === undefined) continue
+    const label = record.patchedBy.length === 0
+      ? record.origin
+      : `${record.origin}, patched by ${record.patchedBy.join(', ')}`
+    if (label !== currentLabel) {
+      flush()
+      currentLabel = label
+    }
+    group.push(composed[index])
+  }
+  flush()
+  return lines.join('\n') + '\n'
+}
+
+/**
+ * Mount and remember the exact root Include entry used by app boot and user patch-layer HMR.
+ * @param ctx - context carrying an initialized Loader service.
+ * @param absoluteConfigPath - absolute YAML or JSON configuration path.
+ * @param patches - initial app and user 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.
+ */
+export interface FailLoudProcess {
+  on(event: 'unhandledRejection', handler: (err: unknown) => void): unknown
+  off(event: 'unhandledRejection', handler: (err: unknown) => void): unknown
+  stderr: { write(chunk: string): unknown }
+  /**
+   * Terminate the process. Callers treat this as the end of the run, as
+   * `process.exit` is; a fake that returns lets the caller continue, which only
+   * a test observes.
+   */
+  exit(code: number): void
+}
+
+// Loader rc.5 derives and drops a rejected promise after a fiber fails. Keep
+// exact reasons already folded into the boot diagnostic visible through the
+// next process rejection checkpoint so the process guard can coalesce them.
+const assembledActivationRejections = new Map<unknown, number>()
+
+function retainAssembledRejection(reason: unknown): void {
+  assembledActivationRejections.set(reason, (assembledActivationRejections.get(reason) ?? 0) + 1)
+}
+
+function releaseAssembledRejection(reason: unknown): void {
+  const count = assembledActivationRejections.get(reason)
+  if (count === undefined || count === 1) {
+    assembledActivationRejections.delete(reason)
+  } else {
+    assembledActivationRejections.set(reason, count - 1)
+  }
+}
+
+async function observeLoaderRejectionCheckpoint(reasons: readonly unknown[]): Promise<void> {
+  for (const reason of reasons) retainAssembledRejection(reason)
+  try {
+    await new Promise<void>(resolve => setImmediate(resolve))
+  } finally {
+    for (const reason of reasons) releaseAssembledRejection(reason)
+  }
+}
+
+/**
+ * How long {@link installFailLoud} waits for its `release` hook before exiting
+ * anyway. A wedged disposer must delay the fatal exit, never cancel it.
+ */
+export const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2_000
+
+/**
+ * Install before boot to turn a late unhandled plugin-init rejection into one
+ * labelled stderr diagnostic and `exit(1)`. A rejection already included by
+ * {@link assertEntriesActivated} is ignored during its process checkpoint;
+ * every other rejection remains fatal. Stdout remains untouched for ACP; the
+ * returned function removes the handler.
+ *
+ * The Loader mounts entries concurrently, so a surface that owns the terminal
+ * can already hold it when a sibling entry rejects. Exiting straight from the
+ * handler would strand raw mode, bracketed paste, and the keyboard protocol on
+ * the user's shell, and leave an in-flight terminal query's reply to land as
+ * literal text at the next prompt. `release` is the terminal owner's chance to
+ * hand it back; it is awaited under {@link FAIL_LOUD_RELEASE_TIMEOUT_MS}, whose
+ * timer stays referenced so a never-settling disposer cannot let Node reach an
+ * empty event loop and exit 0 instead of failing.
+ *
+ * The diagnostic is written before the release so a hanging or failing disposer
+ * cannot swallow the reason. The handler stays installed while the release runs
+ * — removing it would let a second concurrent rejection become uncaught and kill
+ * the process mid-teardown, stranding exactly the terminal state this restores —
+ * so a latch keeps the first rejection the reported one and lets later
+ * rejections (including the release's own) fall through to the pending exit.
+ * @param binName - the diagnostic prefix on the fatal-failure line.
+ * @param proc - the process slice to register on; tests inject a fake.
+ * @param release - optional teardown awaited before exit, used by a
+ *   terminal-owning surface to restore the terminal. Its own failure is
+ *   swallowed because the pending fatal exit already owns the outcome.
+ * @returns the uninstaller that removes the rejection handler.
+ */
+export function installFailLoud(
+  binName: string,
+  proc: FailLoudProcess = process,
+  release?: () => Promise<void> | void,
+): () => void {
+  let exiting = false
+  const handler = (err: unknown): void => {
+    if (assembledActivationRejections.has(err)) return
+    // A release in flight already owns the exit. Swallow later rejections
+    // (teardown's own included) rather than reporting a second failure over the
+    // real one or letting Node kill the process before the terminal is back.
+    if (exiting) return
+    exiting = true
+    proc.stderr.write(`${binName}: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
+    if (release === undefined) {
+      proc.exit(1)
+      return
+    }
+    void (async () => {
+      // Definitely assigned: the timeout promise's executor runs synchronously
+      // while the race is being constructed, before the first await.
+      let timer!: ReturnType<typeof setTimeout>
+      try {
+        await Promise.race([
+          (async () => release())(),
+          new Promise<void>((resolve) => {
+            timer = setTimeout(resolve, FAIL_LOUD_RELEASE_TIMEOUT_MS)
+          }),
+        ])
+      } catch {
+        // The terminal release failed; the fatal exit below is the outcome that
+        // matters, and no reporter runs after it.
+      }
+      clearTimeout(timer)
+      proc.exit(1)
+    })()
+  }
+  const uninstall = (): void => void proc.off('unhandledRejection', handler)
+  proc.on('unhandledRejection', handler)
+  return uninstall
+}
+
+/**
+ * After the tree settles, reject entries with no fiber and name every plugin
+ * whose module failed to resolve. Disabled entries are the only valid
+ * fiber-less state.
+ * @param ctx - the settled context whose loader entries to audit.
+ * @param binName - the diagnostic prefix on the thrown error.
+ */
+export function assertEntriesLoaded(ctx: Context, binName: string): void {
+  const failed = [...ctx.loader.entries()].filter(entry => entry.fiber === undefined && !entry.disabled)
+  if (failed.length > 0) {
+    const names = failed.map(entry => entry.options.name).join(', ')
+    throw new Error(`${binName}: plugin(s) failed to load: ${names}; Cordis startup failed because these plugin(s) could not be resolved (see the error(s) logged above)`)
+  }
+}
+
+/**
+ * Value mirrors used because Cordis's const enum has no runtime object to import.
+ * Keep aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts` and
+ * `packages/client/web/src/loader-status.ts`.
+ */
+const FIBER_PENDING = 0 as FiberState.PENDING
+const FIBER_ACTIVE = 2 as FiberState.ACTIVE
+const FIBER_FAILED = 3 as FiberState.FAILED
+
+/** Render a thrown plugin value without discarding an Error's original stack. */
+function formatActivationError(error: unknown): string {
+  return error instanceof Error ? error.stack ?? error.message : String(error)
+}
+
+/**
+ * Reject a settled Loader tree when an enabled entry failed or remains inactive.
+ * Plugin failures include the original thrown stack; pending entries name their
+ * unresolved services because no plugin error exists for that state. Active
+ * entries require no further wait; only failed fibers are awaited to recover
+ * their private rejection reason.
+ * @param ctx - the settled context whose Loader entries to audit.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @returns nothing when every enabled entry is active.
+ * @throws after one process rejection checkpoint when an entry failed to
+ * import, rejected during activation, or did not become active.
+ */
+export async function assertEntriesActivated(ctx: Context, binName: string): Promise<void> {
+  assertEntriesLoaded(ctx, binName)
+  const failures: string[] = []
+  const rejectionReasons: unknown[] = []
+  for (const entry of ctx.loader.entries()) {
+    const fiber = entry.fiber
+    if (fiber === undefined || entry.disabled) continue
+    const state = fiber.state
+    if (state === FIBER_ACTIVE) continue
+    if (state === FIBER_FAILED) {
+      try {
+        await fiber.await()
+      } catch (error) {
+        rejectionReasons.push(error)
+        failures.push(`${entry.options.name}: ${formatActivationError(error)}`)
+      }
+      continue
+    }
+    if (state === FIBER_PENDING) {
+      const missing = Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined)
+      const subject = missing.length === 1 ? 'service' : 'services'
+      failures.push(`${entry.options.name}: pending (waiting for ${subject}: ${missing.join(', ') || 'unknown'})`)
+    } else {
+      failures.push(`${entry.options.name}: fiber state ${String(state)}`)
+    }
+  }
+  if (failures.length > 0) {
+    if (rejectionReasons.length > 0) {
+      await observeLoaderRejectionCheckpoint(rejectionReasons)
+    }
+    const noun = failures.length === 1 ? 'entry' : 'entries'
+    throw new Error(`${binName}: ${String(failures.length)} ${noun} did not activate\n${failures.join('\n')}`)
+  }
+}
+
+/**
+ * Boot the Loader against `absoluteConfigPath` and return only after the whole
+ * tree settles. Entry names load through the Loader's internal module loader
+ * against `baseUrl` (the config directory), which may live outside
+ * `node_modules` reach and, unbuilt, cannot load vendored source; the
+ * bootstrap include is therefore statically imported and mounted as the
+ * `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. 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}).
+ * @param patches - optional overlay patches applied over the included tree
+ * (see {@link loadOptionalPatches}); an empty list mounts none.
+ * @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,
+  absoluteConfigPath: string,
+  patches?: PatchOptions[],
+  prepare?: (ctx: Context) => Promise<void> | void,
+): Promise<Context> {
+  const ctx = new Context()
+  // 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, before the last entry settles. 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 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
+ * that plugin drops it until the next boot.
+ * @param ctx - the settled boot context whose global system prompt to augment.
+ * @param sourceRoot - the absolute path to the harness checkout root.
+ * @returns the section disposer, or `undefined` when no `systemPrompt` service is mounted.
+ */
+export function addHarnessSourceSection(ctx: Context, sourceRoot: string): (() => void) | undefined {
+  const systemPrompt = ctx.get('systemPrompt')
+  if (systemPrompt === undefined) return undefined
+  return systemPrompt.section({
+    name: HARNESS_SOURCE_SECTION,
+    order: -99,
+    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.`,
+  })
+}

packages/boot/app-boot/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-app-boot`.
+ * @module @deepseek-ai/dsh-app-boot/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-app-boot'
+
+/** Cordis companion plugin name. */
+export const name = 'app-boot-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this presentation adapter owns no durable package-local event stream;
+ * boundary and replay tests cover its protocol mapping.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/boot/app-boot/src/profile.ts

@@ -0,0 +1,388 @@
+/**
+ * Profile discovery, initialization, and patch-layer composition for the
+ * `dsh --profile` launcher family.
+ *
+ * A profile is a directory under `$DSH_HOME/profiles/<name>` holding a
+ * `package.json` (out-of-tree plugin dependencies plus the profile manifest
+ * `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml`
+ * (the user's own patch layer, applied after every bundle layer). Bundles are
+ * npm packages whose manifest declares
+ * `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the tree is
+ * composed by applying each bundle's patch list in `dsh.profile.bundles` order over
+ * an empty entry list, then the profile's own patches, then any launcher
+ * layers (`--patch` files and flag-derived patches).
+ *
+ * Module resolution is two-anchor by construction: a bundle name resolves
+ * first from the dsh installation (the launcher's own package), then from the
+ * profile directory. The Loader's `baseUrl` is the profile directory, whose
+ * `node_modules` pnpm manages for out-of-tree plugins, while the maintained
+ * flat fallback directory `$DSH_HOME/profiles/node_modules` (one symlink per
+ * package the installation's app and bundles depend on) makes every in-box
+ * plugin Node-resolvable from any profile through the ordinary parent-walk.
+ * @module @deepseek-ai/dsh-app-boot/profile
+ */
+
+import { createRequire } from 'node:module'
+import {
+  existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync,
+} from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import type { EntryOptions } from '@cordisjs/plugin-loader'
+import { applyEntryPatches, type PatchOptions } from '@cordisjs/plugin-include'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { loadOverlayPatches } from './index.ts'
+
+/** Directory under the Harness home holding every profile. */
+export const PROFILES_DIR = 'profiles'
+
+/** The user patch layer inside a profile directory (hot-reloaded on long-lived surfaces). */
+export const PROFILE_PATCH_FILENAME = 'cordis.patch.yml'
+
+/** The bundle half of the `dsh` manifest section: what a bundle package exports. */
+export interface DshBundleManifest {
+  /** The patch layer this bundle exports, relative to its package root. */
+  patch: string
+}
+
+/** The profile half of the `dsh` manifest section: what a profile directory composes. */
+export interface DshProfileManifest {
+  /** Ordered bundle layer list (package names). */
+  bundles?: string[]
+}
+
+/**
+ * The `dsh`-owned manifest section of a package.json. The nested key names
+ * the manifest kind: a bundle package declares `bundle`, a profile directory
+ * declares `profile`; nothing declares both.
+ */
+export interface DshManifestSection {
+  /** Present on bundle packages only. */
+  bundle?: DshBundleManifest
+  /** Present on profile manifests only. */
+  profile?: DshProfileManifest
+}
+
+/** The slice of package.json both profiles and bundles use. */
+export interface ProfileManifest {
+  name?: string
+  dependencies?: Record<string, string>
+  peerDependencies?: Record<string, string>
+  dsh?: DshManifestSection
+}
+
+/** One resolved bundle layer of a profile. */
+export interface ProfileLayer {
+  /** The bundle's package name, as listed in `dsh.profile.bundles`. */
+  packageName: string
+  /** Absolute directory of the resolved bundle package. */
+  packageDir: string
+  /** Absolute path of the bundle's patch file. */
+  patchPath: string
+  /** The parsed patch list. */
+  patches: PatchOptions[]
+}
+
+/** A loaded profile: resolved bundle layers plus the user's own patch layer. */
+export interface Profile {
+  /** The profile name (its directory basename). */
+  name: string
+  /** Absolute profile directory. */
+  dir: string
+  /** Bundle layers in `dsh.profile.bundles` order. */
+  layers: ProfileLayer[]
+  /** Absolute path of the profile's own patch file. */
+  patchPath: string
+  /** The profile's own patches; empty when the file is absent. */
+  patches: PatchOptions[]
+}
+
+/**
+ * Resolve a profile's directory under the Harness home.
+ * @param name - the profile name (`dsh --profile <name>`).
+ * @param home - the Harness home; defaults to {@link resolveDshHome}.
+ * @returns the absolute profile directory (which may not exist yet).
+ */
+export function resolveProfileDir(name: string, home: string = resolveDshHome()): string {
+  if (name === '' || name.includes('/') || name.includes('\\') || name === '.' || name === '..'
+    // The launcher-maintained flat module fallback lives at this sibling path.
+    || name === 'node_modules') {
+    throw new Error(`dsh: invalid profile name ${JSON.stringify(name)}`)
+  }
+  return join(home, PROFILES_DIR, name)
+}
+
+/** The shipped profile templates auto-initialized on first use, by name. */
+export const PROFILE_TEMPLATES: Record<string, readonly string[]> = {
+  web: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'],
+  headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'],
+}
+
+/** The bundle list a `dsh plugin` init uses for a name with no shipped template. */
+export const DEFAULT_PROFILE_BUNDLES: readonly string[] = ['@deepseek-ai/dsh-base']
+
+const PROFILE_PATCH_TEMPLATE = `# Your patch layer for this dsh profile, applied after every bundle layer:
+# a top-level YAML array of loader patch entries (id-targeted config
+# overrides, disables, and insert lists; \`!!js\` expressions allowed).
+[]
+`
+
+// The hoisted linker gives out-of-tree plugins a flat node_modules whose
+// missing peers (cordis and friends) fall through to the healed
+// profiles/node_modules installation fallback, so every plugin shares the
+// installation's single cordis instance instead of a duplicate. pnpm ≥10
+// reads its settings from pnpm-workspace.yaml, not .npmrc.
+const PROFILE_PNPM_WORKSPACE = `packages:
+  - .
+
+nodeLinker: hoisted
+autoInstallPeers: false
+`
+
+/**
+ * Initialize a profile directory: manifest, empty user patch layer, and the
+ * pnpm settings out-of-tree plugins need. Existing files are never touched,
+ * so re-running is a no-op on an initialized profile.
+ * @param dir - the profile directory from {@link resolveProfileDir}.
+ * @param bundles - the initial `dsh.profile.bundles` layer list.
+ */
+export function initProfile(dir: string, bundles: readonly string[]): void {
+  mkdirSync(dir, { recursive: true })
+  const manifestPath = join(dir, 'package.json')
+  if (!existsSync(manifestPath)) {
+    const manifest: ProfileManifest & { private: boolean } = {
+      name: `dsh-profile-${basename(dir)}`,
+      private: true,
+      dependencies: {},
+      dsh: { profile: { bundles: [...bundles] } },
+    }
+    writeFileSync(manifestPath, JSON.stringify(manifest, undefined, 2) + '\n')
+  }
+  const patchPath = join(dir, PROFILE_PATCH_FILENAME)
+  if (!existsSync(patchPath)) writeFileSync(patchPath, PROFILE_PATCH_TEMPLATE)
+  const workspacePath = join(dir, 'pnpm-workspace.yaml')
+  if (!existsSync(workspacePath)) writeFileSync(workspacePath, PROFILE_PNPM_WORKSPACE)
+}
+
+/** Ensure `link` is a symlink to `target`, replacing a wrong or dangling link; a real directory throws. */
+function ensureSymlink(link: string, target: string): void {
+  let stat
+  try {
+    stat = lstatSync(link)
+  } catch {
+    // Missing link (first run) — created below. Any other lstat failure on a
+    // path we just created the parent of would resurface on symlinkSync.
+    stat = undefined
+  }
+  if (stat !== undefined) {
+    if (!stat.isSymbolicLink()) {
+      throw new Error(`dsh: ${link} exists and is not a symlink; remove it so dsh can manage the installation fallback`)
+    }
+    if (readlinkSync(link) === target) return
+    rmSync(link)
+  }
+  try {
+    symlinkSync(target, link, 'junction')
+  } catch (error) {
+    // Concurrent launches heal the same fallback; losing the race to a
+    // process writing the identical link is success, anything else is not.
+    // The window between the lstat miss above and this write cannot be
+    // staged deterministically from the public surface.
+    /* v8 ignore next 4 */
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST'
+      || !lstatSync(link).isSymbolicLink() || readlinkSync(link) !== target) {
+      throw error
+    }
+  }
+}
+
+/**
+ * Maintain the flat module fallback `$DSH_HOME/profiles/node_modules`: one
+ * symlink per package in the dsh app's resolvable dependency CLOSURE (BFS
+ * over `dependencies` from the app manifest), each resolved from its own
+ * real location. Node's parent-directory walk from any profile finds this
+ * directory after the profile's own `node_modules`, so every in-box plugin
+ * resolves without pnpm ever managing it — the exact "bundles come from the
+ * installation" contract. The closure (not just direct dependencies) is
+ * required for out-of-tree plugins: their peer dependencies name seam
+ * packages (`dsh-compact`, `dsh-invariants`, ...) that the app reaches only
+ * through its implementation packages. Symlinked packages resolve their own
+ * dependencies from their real directories (Node's default
+ * symlink-following), so each package needs only its one flat link.
+ * Idempotent: correct links are kept and moved installations are
+ * re-pointed; a stale link to a vanished package stays until its name is
+ * reused (dangling links are invisible to resolution).
+ * @param installAnchor - absolute path of the dsh app's package.json.
+ * @param home - the Harness home; defaults to {@link resolveDshHome}.
+ */
+export function healProfilesModuleFallback(installAnchor: string, home: string = resolveDshHome()): void {
+  const profilesDir = join(home, PROFILES_DIR)
+  const modulesDir = join(profilesDir, 'node_modules')
+  mkdirSync(modulesDir, { recursive: true })
+  const appManifest = JSON.parse(readFileSync(installAnchor, 'utf8')) as ProfileManifest
+  const links = new Map<string, string>()
+  /* v8 ignore next -- a real app manifest always declares its name */
+  if (appManifest.name !== undefined) links.set(appManifest.name, dirname(installAnchor))
+  // BFS over the resolvable dependency graph; the visited set is the link
+  // map itself (first resolution wins, matching Node's own nearest-wins).
+  const queue: { anchor: string; manifest: ProfileManifest }[] = [{ anchor: installAnchor, manifest: appManifest }]
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    // Peer dependencies participate: seam packages (dsh-subprocess,
+    // dsh-compact, ...) are peers of their implementations, never plain
+    // dependencies, yet out-of-tree plugins import them directly.
+    /* v8 ignore next -- a real app manifest always declares dependencies */
+    for (const dep of [...Object.keys(next.manifest.dependencies ?? {}), ...Object.keys(next.manifest.peerDependencies ?? {})]) {
+      if (links.has(dep)) continue
+      const dir = packageDirFromAnchor(next.anchor, dep)
+      // A declared-but-uninstalled dependency cannot be a loader-visible
+      // plugin; skip it rather than fail the whole boot.
+      if (dir === undefined) continue
+      links.set(dep, dir)
+      const manifestPath = join(dir, 'package.json')
+      queue.push({ anchor: manifestPath, manifest: JSON.parse(readFileSync(manifestPath, 'utf8')) as ProfileManifest })
+    }
+  }
+  for (const [packageName, target] of links) {
+    const link = join(modulesDir, packageName)
+    mkdirSync(dirname(link), { recursive: true })
+    ensureSymlink(link, target)
+  }
+}
+
+/**
+ * Read a profile's manifest.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param dir - the profile directory.
+ * @returns the parsed manifest.
+ */
+export function readProfileManifest(binName: string, dir: string): ProfileManifest {
+  const path = join(dir, 'package.json')
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read profile manifest ${path}: ${String(error)}`)
+  }
+  // File boundary: the shape check below validates what the parse type asserts.
+  const parsed = JSON.parse(raw) as ProfileManifest | null
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${binName}: profile manifest ${path} must hold a JSON object`)
+  }
+  return parsed
+}
+
+/**
+ * Write a profile's manifest back (2-space JSON, trailing newline).
+ * @param dir - the profile directory.
+ * @param manifest - the manifest value to persist.
+ */
+export function writeProfileManifest(dir: string, manifest: ProfileManifest): void {
+  writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest, undefined, 2) + '\n')
+}
+
+/**
+ * Resolve a package's root directory from one anchor without depending on the
+ * package exporting `./package.json` (`require.resolve` would need that):
+ * probe the require resolution paths for a directory holding the named
+ * manifest. This is Node's own node_modules lookup order, so the result
+ * matches what the Loader would import from the same anchor, and
+ * `existsSync` follows the symlinks pnpm's isolated layout uses.
+ */
+function packageDirFromAnchor(anchor: string, packageName: string): string | undefined {
+  // resolve.paths returns null only for builtins, which no bundle name is.
+  /* v8 ignore next */
+  for (const searchPath of createRequire(anchor).resolve.paths(packageName) ?? []) {
+    const candidate = join(searchPath, packageName)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Resolve one bundle package's directory: installation anchor first, then the
+ * profile directory. The installation-first order is the contract that
+ * `@deepseek-ai/dsh-base` (and every other in-box bundle) always comes from
+ * the same installation as the running dsh, never from a profile-local copy.
+ * Resolution does not require the package to export `./package.json`.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param packageName - the bundle's package name from `dsh.profile.bundles`.
+ * @param installAnchor - absolute path of a file inside the dsh app package (its package.json).
+ * @param profileDir - the profile directory (second anchor).
+ * @returns the bundle package's absolute directory.
+ */
+export function resolveBundleDir(
+  binName: string, packageName: string, installAnchor: string, profileDir: string,
+): string {
+  for (const anchor of [installAnchor, join(profileDir, 'package.json')]) {
+    const dir = packageDirFromAnchor(anchor, packageName)
+    if (dir !== undefined) return dir
+  }
+  throw new Error(
+    `${binName}: cannot resolve profile bundle ${JSON.stringify(packageName)} from the dsh installation or ${profileDir}; `
+    + `run 'dsh plugin --profile ${basename(profileDir)} install' if its dependency is not installed`,
+  )
+}
+
+/**
+ * Load a profile: resolve every `dsh.profile.bundles` entry to its patch
+ * layer and parse the profile's own patch file. A listed bundle without a
+ * `dsh.bundle` manifest fails loud — naming a bundle-less package as a layer
+ * is a misconfiguration, not "no patches".
+ * @param binName - the diagnostic prefix on thrown errors.
+ * @param name - the profile name.
+ * @param installAnchor - absolute path of the dsh app's package.json (first resolution anchor).
+ * @param home - the Harness home; defaults to {@link resolveDshHome}.
+ * @param options - `userLayer: false` skips reading `cordis.patch.yml`, so a
+ * bundles-only consumer (`--dump-default-config`, a recovery diagnostic)
+ * cannot fail on a broken user layer.
+ * @returns the loaded profile (empty `patches` when the user layer is skipped).
+ */
+export function loadProfile(
+  binName: string, name: string, installAnchor: string, home: string = resolveDshHome(),
+  options: { userLayer?: boolean } = {},
+): Profile {
+  const dir = resolveProfileDir(name, home)
+  if (!existsSync(join(dir, 'package.json'))) {
+    const template = PROFILE_TEMPLATES[name]
+    if (template === undefined) {
+      throw new Error(
+        `${binName}: profile ${JSON.stringify(name)} does not exist; create it with 'dsh plugin --profile ${name} add <package>'`,
+      )
+    }
+    initProfile(dir, template)
+  }
+  const manifest = readProfileManifest(binName, dir)
+  // A hand-written profile manifest may omit the dsh section entirely.
+  const bundles = manifest.dsh?.profile?.bundles ?? []
+  const layers = bundles.map((packageName): ProfileLayer => {
+    const packageDir = resolveBundleDir(binName, packageName, installAnchor, dir)
+    const bundleManifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')) as ProfileManifest
+    const declared = bundleManifest.dsh?.bundle?.patch
+    if (declared === undefined) {
+      throw new Error(`${binName}: profile bundle ${JSON.stringify(packageName)} declares no dsh.bundle in its package.json`)
+    }
+    const patchPath = join(packageDir, declared)
+    return { packageName, packageDir, patchPath, patches: loadOverlayPatches(binName, patchPath) }
+  })
+  const patchPath = join(dir, PROFILE_PATCH_FILENAME)
+  const patches = options.userLayer !== false && existsSync(patchPath)
+    ? loadOverlayPatches(binName, patchPath)
+    : []
+  return { name, dir, layers, patchPath, patches }
+}
+
+/**
+ * Compose patch layers into the effective entry list over an empty root —
+ * the same single `applyEntryPatches` call the boot include makes, so flag
+ * derivation and config dumps see exactly what mounts.
+ * @param layers - patch lists in application order.
+ * @param warn - sink for skipped-patch diagnostics; defaults to silent (boot repeats them).
+ * @returns the composed entry list.
+ */
+export function composeEntries(
+  layers: readonly PatchOptions[][], warn: (message: string) => void = () => {},
+): EntryOptions[] {
+  return applyEntryPatches([], structuredClone(layers.flat()), (message: string, ...args: unknown[]) => {
+    let index = 0
+    warn(message.replace(/%C/g, () => JSON.stringify(args[index++])))
+  })
+}

packages/boot/app-boot/tests/app-boot.spec.ts

@@ -0,0 +1,737 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
+import {
+  addHarnessSourceSection, assertEntriesActivated, assertEntriesLoaded, boot,
+  FAIL_LOUD_RELEASE_TIMEOUT_MS, HARNESS_SOURCE_SECTION,
+  installFailLoud, loadEnv, loadLayeredEnv, loadOverlayPatches, resolveConfigPath, type FailLoudProcess,
+} from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-app-boot-'))
+
+describe('resolveConfigPath', () => {
+  it('resolves relative to the given cwd outside replay mode', () => {
+    expect(resolveConfigPath('./cordis.yml', undefined, `${sep}base`)).toBe(resolve(`${sep}base`, 'cordis.yml'))
+    expect(resolveConfigPath('conf/app.yaml', 'record', `${sep}base`)).toBe(resolve(`${sep}base`, 'conf/app.yaml'))
+  })
+
+  it('swaps a cordis.yml/.yaml basename for cordis.snapshot.yml in replay mode', () => {
+    expect(resolveConfigPath('./cordis.yml', 'replay', `${sep}base`)).toBe(resolve(`${sep}base`, 'cordis.snapshot.yml'))
+    expect(resolveConfigPath('deep/cordis.yaml', 'replay', `${sep}base`)).toBe(resolve(`${sep}base`, 'deep/cordis.snapshot.yml'))
+  })
+
+  it('leaves a non-cordis basename alone in replay mode and defaults cwd to the process cwd', () => {
+    expect(resolveConfigPath('custom.yml', 'replay', `${sep}base`)).toBe(resolve(`${sep}base`, 'custom.yml'))
+    expect(resolveConfigPath('./x.yml', undefined)).toBe(resolve(process.cwd(), 'x.yml'))
+  })
+})
+
+describe('loadEnv', () => {
+  it('loads variables from .env in the given dir', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, '.env'), 'DSH_APP_BOOT_SPEC_VAR=loaded\n')
+    const warn = vi.fn()
+    loadEnv(NAME, dir, warn)
+    expect(process.env['DSH_APP_BOOT_SPEC_VAR']).toBe('loaded')
+    expect(warn).not.toHaveBeenCalled()
+    delete process.env['DSH_APP_BOOT_SPEC_VAR']
+  })
+
+  it('stays silent when no .env exists (ambient environment wins)', () => {
+    const warn = vi.fn()
+    loadEnv(NAME, tmp(), warn)
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('warns (labelled, single line) when .env exists but cannot be loaded', () => {
+    const dir = tmp()
+    mkdirSync(join(dir, '.env')) // a directory named .env: present, unreadable as a file
+    const warn = vi.fn()
+    loadEnv(NAME, dir, warn)
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(warn.mock.calls[0]?.[0]).toMatch(new RegExp(`^${NAME}: failed to load \\.env: `))
+  })
+
+  it('defaults dir to the process cwd and warn to a stderr write', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, '.env'), 'DSH_APP_BOOT_SPEC_DEFAULTS=yes\n')
+    const previous = process.cwd()
+    process.chdir(dir)
+    try {
+      loadEnv(NAME) // happy path: the default warn sink is never invoked
+    } finally {
+      process.chdir(previous)
+    }
+    expect(process.env['DSH_APP_BOOT_SPEC_DEFAULTS']).toBe('yes')
+    delete process.env['DSH_APP_BOOT_SPEC_DEFAULTS']
+    // The default warn sink itself: point it at a broken .env with stderr
+    // spied, so the arrow body runs without polluting the test output.
+    const broken = tmp()
+    mkdirSync(join(broken, '.env'))
+    const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+    let written: string[]
+    try {
+      loadEnv(NAME, broken)
+      written = write.mock.calls.map(call => String(call[0]))
+    } finally {
+      write.mockRestore()
+    }
+    expect(written).toHaveLength(1)
+    expect(written[0]).toContain(`${NAME}: failed to load .env: `)
+  })
+})
+
+describe('loadLayeredEnv', () => {
+  const NAMES = ['APP_BOOT_LAYERED_SHARED', 'APP_BOOT_LAYERED_USER', 'APP_BOOT_LAYERED_PROJECT'] as const
+
+  function clear(): void {
+    for (const name of NAMES) Reflect.deleteProperty(process.env, name)
+  }
+
+  it('layers user under project under the inherited environment', () => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(home, '.env'), [
+      `${NAMES[0]}=user`,
+      `${NAMES[1]}=user-only`,
+      'APP_BOOT_LAYERED_INHERITED=user-loses',
+      '',
+    ].join('\n'))
+    writeFileSync(join(project, '.env'), [
+      `${NAMES[0]}=project`,
+      `${NAMES[2]}=project-only`,
+      'APP_BOOT_LAYERED_INHERITED=project-loses',
+      '',
+    ].join('\n'))
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    vi.stubEnv('APP_BOOT_LAYERED_INHERITED', 'inherited')
+    const warn = vi.fn()
+    try {
+      loadLayeredEnv(NAME, project, warn)
+      expect(process.env[NAMES[0]]).toBe('project')
+      expect(process.env[NAMES[1]]).toBe('user-only')
+      expect(process.env[NAMES[2]]).toBe('project-only')
+      expect(process.env['APP_BOOT_LAYERED_INHERITED']).toBe('inherited')
+      expect(warn).not.toHaveBeenCalled()
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it.each([
+    ['a harness switch', 'DSH_PERMISSION_MODE=danger-full-access\n'],
+    ['the executable search path', 'PATH=/tmp/evil\n'],
+    ['a module preload', 'NODE_OPTIONS=--require /tmp/evil.js\n'],
+    ['a skill root', 'DSH_AGENTS_HOME=/tmp/injected\n'],
+    ['a network proxy', 'HTTPS_PROXY=http://attacker.example\n'],
+    ['a lowercase network proxy', 'https_proxy=http://attacker.example\n'],
+  ])('refuses to launch when a .env sets %s, before applying anything', (_case, content) => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(project, '.env'), `${NAMES[1]}=applied-anyway\n${content}`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    try {
+      expect(() => loadLayeredEnv(NAME, project, vi.fn())).toThrow(/only the launching environment may set/)
+      expect(process.env[NAMES[1]]).toBeUndefined()
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('reports each file value with its absolute path', () => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(home, '.env'), `${NAMES[1]}=u\n`)
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=p\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    try {
+      const snapshot = loadLayeredEnv(NAME, project, vi.fn())
+      expect(snapshot.get(NAMES[1])).toEqual({ value: 'u', source: 'user-env', path: join(home, '.env') })
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'p', source: 'project-env', path: join(project, '.env') })
+      expect(snapshot.getFrom(NAMES[2], ['process', 'user-env'])).toBeUndefined()
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('resolves the harness home from the inherited environment, never from a file', () => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(home, '.env'), `${NAMES[1]}=real-home\n`)
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=set-by-project\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    try {
+      loadLayeredEnv(NAME, project, vi.fn())
+      expect(process.env[NAMES[1]]).toBe('real-home')
+      expect(process.env[NAMES[2]]).toBe('set-by-project')
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('warns and continues when a layer exists but cannot be read', () => {
+    const home = tmp()
+    const project = tmp()
+    // A directory named `.env` is a present-but-unreadable layer.
+    mkdirSync(join(home, '.env'))
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=project-only\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    const warn = vi.fn()
+    try {
+      const snapshot = loadLayeredEnv(NAME, project, warn)
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining(`${NAME}: failed to load .env`))
+      expect(snapshot.get(NAMES[1])).toBeUndefined()
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'project-only', source: 'project-env', path: join(project, '.env') })
+      expect(process.env[NAMES[2]]).toBe('project-only')
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('reports to stderr when the caller supplies no reporter', () => {
+    const home = tmp()
+    const project = tmp()
+    mkdirSync(join(home, '.env'))
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=project-only\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    try {
+      const snapshot = loadLayeredEnv(NAME, project)
+      expect(write).toHaveBeenCalledWith(expect.stringContaining(`${NAME}: failed to load .env`))
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'project-only', source: 'project-env', path: join(project, '.env') })
+      expect(process.env[NAMES[2]]).toBe('project-only')
+    } finally {
+      write.mockRestore()
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('passes over an absent layer without reporting it', () => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=project-only\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    const warn = vi.fn()
+    try {
+      const snapshot = loadLayeredEnv(NAME, project, warn)
+      expect(warn).not.toHaveBeenCalled()
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'project-only', source: 'project-env', path: join(project, '.env') })
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('carries only the inherited environment when neither file exists', () => {
+    const home = tmp()
+    const project = tmp()
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    vi.stubEnv('APP_BOOT_LAYERED_INHERITED', 'inherited')
+    try {
+      const snapshot = loadLayeredEnv(NAME, project, vi.fn())
+      expect(snapshot.get('APP_BOOT_LAYERED_INHERITED')).toEqual({ value: 'inherited', source: 'process' })
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('reads a harness home that is also the invocation directory exactly once', () => {
+    const both = tmp()
+    writeFileSync(join(both, '.env'), `${NAMES[2]}=one-file\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', both)
+    try {
+      const snapshot = loadLayeredEnv(NAME, both, vi.fn())
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'one-file', source: 'project-env', path: join(both, '.env') })
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+})
+
+describe('installFailLoud', () => {
+  function fakeProc(): FailLoudProcess & { handlers: Array<(err: unknown) => void>; written: string[]; exits: number[] } {
+    const handlers: Array<(err: unknown) => void> = []
+    const written: string[] = []
+    const exits: number[] = []
+    return {
+      handlers, written, exits,
+      on: (_event, handler) => { handlers.push(handler) },
+      off: (_event, handler) => { handlers.splice(handlers.indexOf(handler), 1) },
+      stderr: { write: (chunk: string) => { written.push(chunk) } },
+      exit: (code: number) => { exits.push(code) },
+    }
+  }
+
+  it('writes one labelled line with the stack and exits 1 on an Error rejection', () => {
+    const proc = fakeProc()
+    installFailLoud(NAME, proc)
+    const error = new Error('boom')
+    proc.handlers[0]!(error)
+    expect(proc.written[0]).toContain(`${NAME}: fatal load failure: `)
+    expect(proc.written[0]).toContain(error.stack)
+    expect(proc.exits).toEqual([1])
+  })
+
+  // One rejection is reported per install: the first is the diagnosis, so each
+  // formatting case needs its own handler rather than reusing a latched one.
+  it('stringifies a non-Error rejection and an Error without a stack falls back to its message', () => {
+    const plain = fakeProc()
+    installFailLoud(NAME, plain)
+    plain.handlers[0]!('plain failure')
+    expect(plain.written[0]).toContain('plain failure')
+    expect(plain.exits).toEqual([1])
+
+    const stackless = new Error('no stack')
+    delete (stackless as { stack?: string }).stack
+    const bare = fakeProc()
+    installFailLoud(NAME, bare)
+    bare.handlers[0]!(stackless)
+    expect(bare.written[0]).toContain('no stack')
+    expect(bare.exits).toEqual([1])
+  })
+
+  it('returns an uninstaller that removes the handler (and defaults to the real process)', () => {
+    const proc = fakeProc()
+    const uninstall = installFailLoud(NAME, proc)
+    expect(proc.handlers).toHaveLength(1)
+    uninstall()
+    expect(proc.handlers).toHaveLength(0)
+    // Default-proc arm: install on the real process, then immediately uninstall
+    // so the suite leaks no handler and can never exit the runner.
+    const before = process.listenerCount('unhandledRejection')
+    const uninstallReal = installFailLoud(NAME)
+    expect(process.listenerCount('unhandledRejection')).toBe(before + 1)
+    uninstallReal()
+    expect(process.listenerCount('unhandledRejection')).toBe(before)
+  })
+
+  it('does not report an activation rejection shared by entries in the boot audit', async () => {
+    const proc = fakeProc()
+    installFailLoud(NAME, proc)
+    const error = new Error('assembled activation failure')
+    const audit = assertEntriesActivated({
+      loader: {
+        entries: () => ['broken-a', 'broken-b'].map(name => ({
+          options: { name },
+          fiber: {
+            state: 3,
+            inject: {},
+            ctx: { get: () => undefined },
+            await: async () => { throw error },
+          },
+        })),
+      },
+    } as unknown as Context, NAME)
+    await Promise.resolve()
+    await Promise.resolve()
+    proc.handlers[0]!(error)
+    expect(proc.written).toEqual([])
+    expect(proc.exits).toEqual([])
+    await expect(audit).rejects.toThrow('assembled activation failure')
+    proc.handlers[0]!(error)
+    expect(proc.exits).toEqual([1])
+  })
+
+  // The Loader mounts entries concurrently, so a terminal-owning surface can
+  // already hold raw mode when a sibling entry rejects. Exiting without running
+  // its teardown strands the terminal on the user's shell.
+  it('awaits the release hook before exiting so the terminal owner can restore it', async () => {
+    const proc = fakeProc()
+    const order: string[] = []
+    installFailLoud(NAME, proc, async () => {
+      await Promise.resolve()
+      order.push('released')
+    })
+    proc.handlers[0]!(new Error('sibling entry rejected'))
+    expect(proc.written[0]).toContain(`${NAME}: fatal load failure: `)
+    // The release is in flight, so the exit has not committed yet.
+    expect(proc.exits).toEqual([])
+    await vi.waitFor(() => { expect(proc.exits).toEqual([1]) })
+    expect(order).toEqual(['released'])
+  })
+
+  it('still exits when the release hook rejects', async () => {
+    const proc = fakeProc()
+    installFailLoud(NAME, proc, () => Promise.reject(new Error('terminal stop failed')))
+    proc.handlers[0]!(new Error('boom'))
+    await vi.waitFor(() => { expect(proc.exits).toEqual([1]) })
+  })
+
+  it('exits without waiting when a release hook never settles', async () => {
+    vi.useFakeTimers()
+    try {
+      const proc = fakeProc()
+      installFailLoud(NAME, proc, () => new Promise<void>(() => {}))
+      proc.handlers[0]!(new Error('boom'))
+      expect(proc.exits).toEqual([])
+      await vi.advanceTimersByTimeAsync(FAIL_LOUD_RELEASE_TIMEOUT_MS)
+      expect(proc.exits).toEqual([1])
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  // Loader failures arrive in bursts, and teardown's own disposers may reject.
+  // Only the first rejection is the diagnosis; the handler must stay installed
+  // so a later one cannot become uncaught and kill the process mid-teardown.
+  it('reports only the first rejection and keeps handling later ones during the release', async () => {
+    const proc = fakeProc()
+    let released = false
+    installFailLoud(NAME, proc, async () => {
+      await Promise.resolve()
+      released = true
+    })
+    proc.handlers[0]!(new Error('first rejection'))
+    proc.handlers[0]!(new Error('second rejection'))
+    expect(proc.handlers).toHaveLength(1)
+    expect(proc.written).toHaveLength(1)
+    expect(proc.written[0]).toContain('first rejection')
+    await vi.waitFor(() => { expect(proc.exits).toEqual([1]) })
+    expect(released).toBe(true)
+  })
+})
+
+describe('assertEntriesLoaded', () => {
+  const ctxWith = (entries: Array<{ fiber?: unknown; disabled?: boolean; options: { name?: string } }>): Context =>
+    ({ loader: { entries: () => entries } }) as unknown as Context
+
+  it('passes when every enabled entry has a fiber', () => {
+    expect(() => { assertEntriesLoaded(ctxWith([
+      { fiber: {}, options: { name: 'a' } },
+      { disabled: true, options: { name: 'off' } },
+    ]), NAME) }).not.toThrow()
+  })
+
+  it('throws naming every enabled fiber-less entry', () => {
+    expect(() => { assertEntriesLoaded(ctxWith([
+      { fiber: {}, options: { name: 'ok' } },
+      { options: { name: 'broken-a' } },
+      { options: { name: 'broken-b' } },
+    ]), NAME) }).toThrow(`${NAME}: plugin(s) failed to load: broken-a, broken-b`)
+  })
+})
+
+describe('assertEntriesActivated', () => {
+  interface FakeFiber {
+    state: number
+    inject: Record<string, unknown>
+    ctx: { get(name: string): unknown }
+    await(): Promise<unknown>
+  }
+
+  const ctxWith = (entries: Array<{ fiber?: FakeFiber; disabled?: boolean; options: { name: string } }>): Context => ({
+    loader: { entries: () => entries },
+  }) as unknown as Context
+
+  const fiber = (
+    state: number,
+    error?: unknown,
+    inject: Record<string, unknown> = {},
+    services: string[] = [],
+  ): FakeFiber => ({
+    state,
+    inject,
+    ctx: { get: name => services.includes(name) ? {} : undefined },
+    await: error === undefined ? async () => undefined : async () => { throw error },
+  })
+
+  it('passes active entries and ignores disabled entries', async () => {
+    let awaitCalls = 0
+    const active = fiber(2)
+    active.await = async () => {
+      awaitCalls++
+      return undefined
+    }
+    const disabled = fiber(3, new Error('disabled failure'))
+    disabled.await = async () => {
+      awaitCalls++
+      throw new Error('disabled failure')
+    }
+    await expect(assertEntriesActivated(ctxWith([
+      { fiber: active, options: { name: 'active' } },
+      { fiber: disabled, disabled: true, options: { name: 'disabled' } },
+    ]), NAME)).resolves.toBeUndefined()
+    expect(awaitCalls).toBe(0)
+  })
+
+  it('reports the plugin name and original activation stack instead of fiber state 3', async () => {
+    const original = new Error('actual plugin failure')
+    await expect(assertEntriesActivated(ctxWith([
+      { fiber: fiber(3, original), options: { name: 'broken-plugin' } },
+    ]), NAME)).rejects.toThrow(`${NAME}: 1 entry did not activate\nbroken-plugin: ${original.stack!}`)
+  })
+
+  it('formats stackless and non-Error activation failures', async () => {
+    const stackless = new Error('stackless failure')
+    delete (stackless as { stack?: string }).stack
+    await expect(assertEntriesActivated(ctxWith([
+      { fiber: fiber(3, stackless), options: { name: 'stackless' } },
+      { fiber: fiber(3, 'plain failure'), options: { name: 'plain' } },
+    ]), NAME)).rejects.toThrow(`${NAME}: 2 entries did not activate\nstackless: stackless failure\nplain: plain failure`)
+  })
+
+  it('reports unresolved services for pending entries', async () => {
+    let awaitCalls = 0
+    const expected = [
+      `${NAME}: 3 entries did not activate`,
+      'waiting: pending (waiting for services: missingA, missingB)',
+      'single-wait: pending (waiting for service: missing)',
+      'unknown-wait: pending (waiting for services: unknown)',
+    ].join('\n')
+    const waiting = fiber(0, undefined, { ready: {}, missingA: {}, missingB: {} }, ['ready'])
+    const singleWait = fiber(0, undefined, { missing: {} })
+    const unknownWait = fiber(0)
+    for (const item of [waiting, singleWait, unknownWait]) {
+      item.await = async () => {
+        awaitCalls++
+        return undefined
+      }
+    }
+    await expect(assertEntriesActivated(ctxWith([
+      { fiber: waiting, options: { name: 'waiting' } },
+      { fiber: singleWait, options: { name: 'single-wait' } },
+      { fiber: unknownWait, options: { name: 'unknown-wait' } },
+    ]), NAME)).rejects.toThrow(expected)
+    expect(awaitCalls).toBe(0)
+  })
+
+  it('retains the numeric diagnostic for a settled unexpected state', async () => {
+    await expect(assertEntriesActivated(ctxWith([
+      { fiber: fiber(4), options: { name: 'disposed' } },
+    ]), NAME)).rejects.toThrow('disposed: fiber state 4')
+  })
+})
+
+describe('loadOverlayPatches', () => {
+  it('loads expressions and rejects missing, malformed, non-array, and non-mapping overlays', () => {
+    const dir = tmp()
+    const valid = join(dir, 'valid.yml')
+    writeFileSync(valid, '- id: target\n  config:\n    value: !!js process.env.VALUE\n')
+    expect(loadOverlayPatches(NAME, valid)).toEqual([{ id: 'target', config: { value: { __jsExpr: 'process.env.VALUE' } } }])
+    expect(() => loadOverlayPatches(NAME, join(dir, 'missing.yml'))).toThrow(`${NAME}: failed to read overlay`)
+    const malformed = join(dir, 'malformed.yml')
+    writeFileSync(malformed, ': bad')
+    expect(() => loadOverlayPatches(NAME, malformed)).toThrow(`${NAME}: failed to parse overlay`)
+    const mapping = join(dir, 'mapping.yml')
+    writeFileSync(mapping, 'id: target\n')
+    expect(() => loadOverlayPatches(NAME, mapping)).toThrow('must be a top-level YAML array')
+    const scalar = join(dir, 'scalar.yml')
+    writeFileSync(scalar, '- scalar\n')
+    expect(() => loadOverlayPatches(NAME, scalar)).toThrow('entry 1')
+  })
+})
+
+describe('boot', () => {
+  it('boots a leaf config through the real Loader and settles the tree', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+    try {
+      const entries = [...ctx.loader.entries()]
+      expect(entries.some(entry => entry.options.name === './noop.mjs' && entry.fiber !== undefined)).toBe(true)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('runs host preparation before the Loader tree mounts', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
+    const prepared: Context[] = []
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'), undefined, (hostCtx) => {
+      expect(hostCtx.loader).toBeDefined()
+      expect([...hostCtx.loader.entries()]).toEqual([])
+      prepared.push(hostCtx)
+    })
+    try {
+      expect(prepared).toEqual([ctx])
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  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')
+    vi.stubEnv('DSH_HOME', dshHome)
+    writeFileSync(join(dir, 'capture.mjs'), [
+      'export const name = "capture"',
+      'export function apply(ctx, config) {',
+      '  ctx.provide("capturedPath", config.path)',
+      '}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: capture',
+      '  name: ./capture.mjs',
+      '  config:',
+      "    path: !!js dshHomePath('sessions')",
+      '',
+    ].join('\n'))
+    let ctx: Context | undefined
+    try {
+      ctx = await boot(NAME, join(dir, 'cordis.yml'))
+      expect(ctx.get('capturedPath')).toBe(join(dshHome, 'sessions'))
+    } finally {
+      await ctx?.fiber.dispose()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('returns instead of asserting over a tree a surface disposed mid-startup', async () => {
+    // A surface can dispose the root fiber while boot() is still awaiting the
+    // Loader, before the last entry settles. The Loader service goes with the
+    // tree, so reading it for the post-boot assertions would crash an app that
+    // exited exactly as the user asked.
+    const dir = tmp()
+    writeFileSync(join(dir, 'exiting.mjs'), [
+      'export const name = "exiting"',
+      'export function apply(ctx) {',
+      '  void ctx.root.fiber.dispose()',
+      '}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'cordis.yml'), '- id: exiting\n  name: ./exiting.mjs\n')
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+    expect(ctx.get('loader')).toBeUndefined()
+  })
+
+  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 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 () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'waiting.mjs'), 'export const inject = ["neverProvided"]\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'cordis.yml'), '- id: waiting\n  name: ./waiting.mjs\n')
+    await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow([
+      `${NAME}: 1 entry did not activate`,
+      './waiting.mjs: pending (waiting for service: neverProvided)',
+    ].join('\n'))
+  })
+})
+
+describe('addHarnessSourceSection', () => {
+  const SOURCE_ROOT = `${sep}opt${sep}harness-src`
+  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('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.' })
+      const dispose = addHarnessSourceSection(ctx, SOURCE_ROOT)
+      expect(dispose).toBeTypeOf('function')
+      const systemPrompt = ctx.get('systemPrompt')!
+      const rendered = renderPrompt(await systemPrompt.assemble())
+      expect(rendered).toContain(EXPECTED)
+      // Harness-owned opener (-100) → source (-99) → persona (0). The >= 0 guards
+      // keep a drifted opener/persona string from a false pass through `-1 < n`.
+      const identityAt = rendered.indexOf('You are an AI agent powered by the DeepSeek Harness SDK.')
+      const sourceAt = rendered.indexOf(EXPECTED)
+      const personaAt = rendered.indexOf('You are a coding agent.')
+      expect(identityAt).toBeGreaterThanOrEqual(0)
+      expect(personaAt).toBeGreaterThanOrEqual(0)
+      expect(identityAt).toBeLessThan(sourceAt)
+      expect(sourceAt).toBeLessThan(personaAt)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('is a no-op returning undefined when no systemPrompt service is mounted', async () => {
+    const ctx = new Context()
+    try {
+      expect(addHarnessSourceSection(ctx, SOURCE_ROOT)).toBeUndefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('disposes the section it added, so a systemPrompt reload leaves no residue', async () => {
+    const ctx = new Context()
+    try {
+      await ctx.plugin(SystemPrompt, {})
+      const systemPrompt = ctx.get('systemPrompt')!
+      const dispose = addHarnessSourceSection(ctx, SOURCE_ROOT)!
+      const present = await systemPrompt.assemble()
+      expect(present.sections.some(section => section.name === HARNESS_SOURCE_SECTION)).toBe(true)
+      dispose()
+      const gone = await systemPrompt.assemble()
+      expect(gone.sections.some(section => section.name === HARNESS_SOURCE_SECTION)).toBe(false)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})

packages/boot/app-boot/tests/config-dump.spec.ts

@@ -0,0 +1,187 @@
+/**
+ * `renderConfigDump` behavior: the offline composition must equal what
+ * `boot()` mounts (same parser, same patch algorithm), print `!!js`
+ * expressions verbatim, separate provenance runs with comment lines while
+ * staying one loadable YAML document, and report skipped patches through
+ * `warn` instead of failing — mirroring the Loader's boot-time warning for a
+ * shared overlay whose row exists only on another surface.
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import * as yaml from 'js-yaml'
+import { entryListSchema } from '@cordisjs/plugin-include'
+import { loadOverlayPatches, renderConfigDump } from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-config-dump-'))
+
+function writeBase(dir: string): string {
+  const base = join(dir, 'base.yml')
+  writeFileSync(base, [
+    '- id: shared',
+    '  name: ./noop.mjs',
+    '  config:',
+    '    value: base',
+    '    key: !!js process.env.DSH_DUMP_SPEC',
+    '- id: untouched',
+    '  name: ./noop.mjs',
+    '',
+  ].join('\n'))
+  return base
+}
+
+describe('renderConfigDump', () => {
+  it('composes overlay layers in order, prints !!js verbatim, and labels each section with its provenance', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const surface = join(dir, 'surface.yml')
+    writeFileSync(surface, [
+      '- id: shared',
+      '  config:',
+      '    value: surface',
+      '    key: !!js process.env.DSH_DUMP_SPEC',
+      '- insert:',
+      '    - id: surface-extra',
+      '      name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const user = join(dir, 'user.yml')
+    writeFileSync(user, [
+      '- id: surface-extra',
+      '  config:',
+      '    value: user',
+      '',
+    ].join('\n'))
+
+    const dump = renderConfigDump(NAME, base, [
+      { label: 'surface.yml', patches: loadOverlayPatches(NAME, surface) },
+      { label: 'user.yml', patches: loadOverlayPatches(NAME, user) },
+    ], () => {})
+    // Comments do not break loadability: the dump parses as one document
+    // equal to what boot() would mount.
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as {
+      id: string
+      config?: Record<string, unknown>
+    }[]
+    expect(parsed).toEqual([
+      {
+        id: 'shared',
+        name: './noop.mjs',
+        config: { value: 'surface', key: { __jsExpr: 'process.env.DSH_DUMP_SPEC' } },
+      },
+      { id: 'untouched', name: './noop.mjs' },
+      { id: 'surface-extra', name: './noop.mjs', config: { value: 'user' } },
+    ])
+    // Unevaluated: the expression text round-trips as a !!js scalar.
+    expect(dump).toContain('!!js process.env.DSH_DUMP_SPEC')
+    // Provenance separators: origin file, plus every layer that changed the
+    // row; an inserted row carries the inserting layer as its origin.
+    expect(dump).toContain('# == base.yml, patched by surface.yml')
+    expect(dump).toContain('# == base.yml\n- id: untouched')
+    expect(dump).toContain('# == surface.yml, patched by user.yml\n- id: surface-extra')
+    expect(dump.indexOf('# == base.yml, patched by surface.yml')).toBeLessThan(dump.indexOf('# == base.yml\n- id: untouched'))
+  })
+
+  it('groups contiguous same-provenance rows under one separator', () => {
+    const dir = tmp()
+    const base = join(dir, 'base.yml')
+    writeFileSync(base, [
+      '- id: a',
+      '  name: ./noop.mjs',
+      '- id: b',
+      '  name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const dump = renderConfigDump(NAME, base, [], () => {})
+    expect(dump.match(/# == base\.yml/g)).toHaveLength(1)
+    expect(dump).toContain('# == base.yml\n- id: a')
+  })
+
+  it('composes all layers as one flattened patch list, exactly like boot()', () => {
+    // boot() flattens every layer into ONE applyEntryPatches call, whose id
+    // index sees inserted rows but NOT children introduced by a plain group
+    // `config` replacement. A per-layer composition would rebuild the index
+    // between layers and let the second layer patch that child — a tree the
+    // real boot never mounts. Pin the single-call semantics: the child patch
+    // is skipped (with the layer-labeled warning), matching boot.
+    const dir = tmp()
+    const base = join(dir, 'base.yml')
+    writeFileSync(base, [
+      '- id: g',
+      '  name: ./group.mjs',
+      '  group: true',
+      '  config: []',
+      '',
+    ].join('\n'))
+    const warnings: string[] = []
+    const dump = renderConfigDump(NAME, base, [
+      {
+        label: 'a.yml',
+        patches: [{ id: 'g', config: [{ id: 'child', name: './noop.mjs', config: { v: 1 } }] }],
+      },
+      { label: 'b.yml', patches: [{ id: 'child', config: { v: 2 } }] },
+    ], line => void warnings.push(line))
+    expect(warnings).toEqual([`${NAME}: [b.yml] patch: entry "child" not found`])
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as {
+      config?: { config?: { v?: number } }[]
+    }[]
+    expect(parsed[0]?.config?.[0]?.config?.v).toBe(1)
+    // The skipped layer did not change the row, so it is not in provenance.
+    expect(dump).toContain('# == base.yml, patched by a.yml\n- id: g')
+    expect(dump).not.toContain('b.yml\n- id: g')
+  })
+
+  it('reports a patch whose target row is absent through warn with its layer label and keeps composing', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const overlay = join(dir, 'overlay.yml')
+    writeFileSync(overlay, [
+      '- id: only-on-another-surface',
+      '  config:',
+      '    value: ignored',
+      '- id: shared',
+      '  config:',
+      '    value: patched',
+      '',
+    ].join('\n'))
+    const warnings: string[] = []
+    const dump = renderConfigDump(
+      NAME, base,
+      [{ label: 'overlay.yml', patches: loadOverlayPatches(NAME, overlay) }],
+      line => void warnings.push(line),
+    )
+    expect(warnings).toEqual([`${NAME}: [overlay.yml] patch: entry "only-on-another-surface" not found`])
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as { config?: { value?: string } }[]
+    expect(parsed[0]?.config?.value).toBe('patched')
+  })
+
+  it('defaults its warn sink to one stderr line per skipped patch', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    try {
+      renderConfigDump(NAME, base, [{ label: 'x.yml', patches: [{ id: 'absent', config: {} }] }])
+      expect(write).toHaveBeenCalledWith(`${NAME}: [x.yml] patch: entry "absent" not found\n`)
+    } finally {
+      write.mockRestore()
+    }
+  })
+
+  it('fails loud on a missing, unparsable, or non-array base config', () => {
+    const dir = tmp()
+    expect(() => renderConfigDump(NAME, join(dir, 'absent.yml'), [], () => {}))
+      .toThrow(new RegExp(`^${NAME}: failed to read config `))
+    const invalid = join(dir, 'invalid.yml')
+    writeFileSync(invalid, 'invalid: [unclosed\n')
+    expect(() => renderConfigDump(NAME, invalid, [], () => {}))
+      .toThrow(new RegExp(`^${NAME}: failed to parse config `))
+    const scalar = join(dir, 'scalar.yml')
+    writeFileSync(scalar, 'id: not-a-list\n')
+    expect(() => renderConfigDump(NAME, scalar, [], () => {}))
+      .toThrow('must be a top-level YAML array of entries')
+  })
+})

packages/boot/app-boot/tests/config-reload.spec.ts

@@ -0,0 +1,388 @@
+/**
+ * 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'
+import { tmpdir } from 'node:os'
+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'
+
+const NOOP_PLUGIN = 'export const name = "noop"\nexport function apply() {}\n'
+
+interface TreeFixture {
+  ctx: Context
+  dir: string
+  include: Include
+}
+
+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)
+  if (entry?.subtree === undefined) throw new Error('booted tree has no include entry')
+  return { ctx, dir, include: entry.subtree as Include }
+}
+
+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('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()).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()).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')
+      await include.refresh()
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 2 })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
+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-'))
+    writeFileSync(join(dir, 'noop.mjs'), NOOP_PLUGIN)
+    writeFileSync(join(dir, 'base.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: base',
+      "  name: 'cordis:include'",
+      '  config:',
+      '    path: ./base.yml',
+      '    patches:',
+      '      - id: noop',
+      '        name: ./noop.mjs',
+      '        config:',
+      '          value: patched',
+      '      - insert:',
+      '          - id: extra',
+      '            name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+    try {
+      const entry = [...ctx.loader.entries()].find(candidate => candidate.options.id === 'base')
+      if (entry?.subtree === undefined) throw new Error('overlay tree has no base include entry')
+      const include = entry.subtree as Include
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched' })
+      expect(entryConfig(ctx, 'extra')).toBeUndefined()
+      expect([...ctx.loader.entries()].some(candidate => candidate.options.id === 'extra')).toBe(true)
+
+      writeFileSync(join(dir, 'base.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: edited\n')
+      await include.refresh()
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched' })
+      expect([...ctx.loader.entries()].some(candidate => candidate.options.id === 'extra')).toBe(true)
+
+      // Hot-update of the include entry's own config (the `internal/update`
+      // path): the new patches must apply now AND stick for later re-reads —
+      // the listener vetoes the fiber restart, so it must persist the new
+      // config itself or the next refresh() re-applies the old overlay.
+      await entry.update({ config: { path: './base.yml', patches: [{ id: 'noop', name: './noop.mjs', config: { value: 'patched-v2' } }] } })
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched-v2' })
+      expect([...ctx.loader.entries()].some(candidate => candidate.options.id === 'extra')).toBe(false)
+
+      writeFileSync(join(dir, 'base.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: edited-2\n')
+      await include.refresh()
+      await ctx.loader.await()
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched-v2' })
+
+      // 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 {
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
+describe('include patches layered over one base', () => {
+  it('lets a later patch configure or disable a row an earlier patch inserted', async () => {
+    // The bundle/user-layer/`--patch` composition: `dsh` includes one root
+    // and applies each source as its own patch list at the SAME include
+    // level, because patches never cross an include boundary. A later layer
+    // must therefore be able to reach a row an earlier layer inserted, or
+    // bundle-only rows would be invisible to the user's patch layer.
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-config-layered-'))
+    writeFileSync(join(dir, 'noop.mjs'), NOOP_PLUGIN)
+    writeFileSync(join(dir, 'base.yml'), '- id: shared\n  name: ./noop.mjs\n  config:\n    value: base\n')
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: base',
+      "  name: 'cordis:include'",
+      '  config:',
+      '    path: ./base.yml',
+      '    patches:',
+      // Layer 1 (a bundle layer): patch a base row and add two of its own.
+      '      - id: shared',
+      '        config:',
+      '          value: bundle',
+      '      - insert:',
+      '          - id: bundle-kept',
+      '            name: ./noop.mjs',
+      '            config:',
+      '              value: bundle-default',
+      '          - id: bundle-dropped',
+      '            name: ./noop.mjs',
+      // Layer 2 (the user): reconfigure one inserted row and disable the other.
+      '      - id: bundle-kept',
+      '        config:',
+      '          value: user',
+      '      - id: bundle-dropped',
+      '        disabled: true',
+      '',
+    ].join('\n'))
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+    try {
+      expect(entryConfig(ctx, 'shared')).toEqual({ value: 'bundle' })
+      expect(entryConfig(ctx, 'bundle-kept')).toEqual({ value: 'user' })
+      const dropped = [...ctx.loader.entries()].find(entry => entry.options.id === 'bundle-dropped')
+      expect(dropped?.options.disabled).toBe(true)
+      expect(dropped?.fiber).toBeUndefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})

packages/boot/app-boot/tests/hmr-config.spec.ts

@@ -0,0 +1,182 @@
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, 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, root: 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 module changes when its watch base is a filesystem alias', { timeout: 20_000 }, async () => {
+    const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-module-canonical-'))
+    const alias = `${target}-alias`
+    const filename = join(alias, 'module.ts')
+    symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    writeFileSync(filename, 'export const generation = 0\n')
+    const ctx = await bootHmr(alias, ['.'])
+    const expected = pathToFileURL(filename).href
+    const observed: string[] = []
+    ctx.on('hmr/change', (url) => { observed.push(url) })
+    try {
+      const deadline = Date.now() + 10_000
+      for (let generation = 1; !observed.includes(expected); generation += 1) {
+        if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
+        writeFileSync(filename, `export const generation = ${generation}\n`)
+        await new Promise(resolve => setTimeout(resolve, 20))
+      }
+    } finally {
+      await ctx.fiber.dispose()
+      rmSync(alias, { force: true })
+      rmSync(target, { recursive: true, force: true })
+    }
+  })
+
+  it('collapses filesystem aliases before registering an exact watch', async () => {
+    const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-canonical-'))
+    const alias = `${target}-alias`
+    symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    const ctx = await bootHmr(alias)
+    try {
+      await ctx.hmr.registerConfig('plugins.yml', () => {})
+      await expect(ctx.hmr.registerConfig(join(realpathSync(target), 'plugins.yml'), () => {}))
+        .rejects.toThrow('config path already registered')
+    } finally {
+      await ctx.fiber.dispose()
+      rmSync(alias, { force: true })
+      rmSync(target, { recursive: true, force: true })
+    }
+  })
+
+  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()
+    }
+  })
+})

packages/boot/app-boot/tests/profile.spec.ts

@@ -0,0 +1,245 @@
+/**
+ * Profile machinery of `dsh-app-boot`: directory resolution and init,
+ * manifest round-trips, two-anchor bundle resolution, patch-layer loading,
+ * empty-root composition, and the installation module-fallback healing.
+ */
+
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  composeEntries,
+  healProfilesModuleFallback,
+  initProfile,
+  loadProfile,
+  PROFILE_PATCH_FILENAME,
+  PROFILE_TEMPLATES,
+  readProfileManifest,
+  resolveBundleDir,
+  resolveProfileDir,
+  writeProfileManifest,
+} from '../src/index.ts'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-profile-'))
+
+/** Stage a fake installed app: package.json with deps and a node_modules holding bundles. */
+function stageInstallation(bundles: Record<string, { patch?: string; deps?: Record<string, string> }>): string {
+  const root = tmp()
+  const appDir = join(root, 'app')
+  mkdirSync(join(appDir, 'node_modules'), { recursive: true })
+  const appDeps: Record<string, string> = {}
+  for (const [name, spec] of Object.entries(bundles)) {
+    appDeps[name] = '0.0.0'
+    const dir = join(appDir, 'node_modules', name)
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      name,
+      version: '0.0.0',
+      dependencies: spec.deps ?? {},
+      ...spec.patch === undefined ? {} : { dsh: { bundle: { patch: './cordis.patch.yml' } } },
+    }))
+    if (spec.patch !== undefined) writeFileSync(join(dir, 'cordis.patch.yml'), spec.patch)
+  }
+  writeFileSync(join(appDir, 'package.json'), JSON.stringify({ name: 'dsh-app', dependencies: appDeps }))
+  return join(appDir, 'package.json')
+}
+
+describe('resolveProfileDir', () => {
+  it('joins the home and rejects traversal-shaped names', () => {
+    const home = tmp()
+    expect(resolveProfileDir('tui', home)).toBe(join(home, 'profiles', 'tui'))
+    for (const bad of ['', '.', '..', 'a/b', 'a\\b']) {
+      expect(() => resolveProfileDir(bad, home)).toThrow('invalid profile name')
+    }
+  })
+})
+
+describe('initProfile', () => {
+  it('creates manifest, user patch layer, and pnpm workspace once, never overwriting', () => {
+    const home = tmp()
+    const dir = resolveProfileDir('tui', home)
+    initProfile(dir, ['@deepseek-ai/dsh-base'])
+    const manifest = readProfileManifest('t', dir)
+    expect(manifest.dsh?.profile?.bundles).toEqual(['@deepseek-ai/dsh-base'])
+    expect(readFileSync(join(dir, PROFILE_PATCH_FILENAME), 'utf8')).toContain('[]')
+    expect(readFileSync(join(dir, 'pnpm-workspace.yaml'), 'utf8')).toContain('nodeLinker: hoisted')
+    // Re-init keeps user edits.
+    writeFileSync(join(dir, PROFILE_PATCH_FILENAME), '- id: x\n  config: {}\n')
+    initProfile(dir, ['other'])
+    expect(readProfileManifest('t', dir).dsh?.profile?.bundles).toEqual(['@deepseek-ai/dsh-base'])
+    expect(readFileSync(join(dir, PROFILE_PATCH_FILENAME), 'utf8')).toContain('- id: x')
+  })
+})
+
+describe('manifest round-trip', () => {
+  it('writes and reads back, and fails loud on a broken manifest', () => {
+    const dir = tmp()
+    writeProfileManifest(dir, { name: 'p', dsh: { profile: { bundles: ['a'] } } })
+    expect(readProfileManifest('t', dir).dsh?.profile?.bundles).toEqual(['a'])
+    writeFileSync(join(dir, 'package.json'), '[]')
+    expect(() => readProfileManifest('t', dir)).toThrow('must hold a JSON object')
+    expect(() => readProfileManifest('t', join(dir, 'nope'))).toThrow('failed to read profile manifest')
+  })
+})
+
+describe('resolveBundleDir', () => {
+  it('prefers the installation anchor, falls back to the profile, and fails loud', () => {
+    const anchor = stageInstallation({ 'in-box': { patch: '[]\n' } })
+    const profileDir = tmp()
+    mkdirSync(join(profileDir, 'node_modules', 'local-only'), { recursive: true })
+    writeFileSync(join(profileDir, 'package.json'), '{}')
+    writeFileSync(join(profileDir, 'node_modules', 'local-only', 'package.json'), JSON.stringify({ name: 'local-only', version: '0.0.0' }))
+    expect(resolveBundleDir('t', 'in-box', anchor, profileDir)).toContain('in-box')
+    expect(resolveBundleDir('t', 'local-only', anchor, profileDir)).toContain('local-only')
+    expect(() => resolveBundleDir('t', 'absent', anchor, profileDir)).toThrow('cannot resolve profile bundle')
+  })
+
+  it('resolves a package whose exports map omits ./package.json', () => {
+    // Common on npm: an exports map without "./package.json" makes
+    // require.resolve('<pkg>/package.json') throw ERR_PACKAGE_PATH_NOT_EXPORTED;
+    // resolution must fall through to the paths probe instead of misreporting
+    // the installed package as missing.
+    const anchor = stageInstallation({})
+    const profileDir = tmp()
+    writeFileSync(join(profileDir, 'package.json'), '{}')
+    const dir = join(profileDir, 'node_modules', 'sealed-bundle')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      name: 'sealed-bundle',
+      version: '0.0.0',
+      exports: { '.': './index.js' },
+      dsh: { bundle: { patch: './cordis.patch.yml' } },
+    }))
+    writeFileSync(join(dir, 'index.js'), '')
+    writeFileSync(join(dir, 'cordis.patch.yml'), '[]\n')
+    expect(resolveBundleDir('t', 'sealed-bundle', anchor, profileDir)).toBe(dir)
+  })
+})
+
+describe('loadProfile', () => {
+  it('resolves each dsh.profile.bundles entry to its patch layer in order, plus the user layer', () => {
+    const anchor = stageInstallation({
+      'bundle-a': { patch: '- insert:\n    - id: a\n      name: pkg-a\n' },
+      'bundle-b': { patch: '- id: a\n  config:\n    v: 2\n' },
+    })
+    const home = tmp()
+    const dir = resolveProfileDir('demo', home)
+    initProfile(dir, ['bundle-a', 'bundle-b'])
+    writeFileSync(join(dir, PROFILE_PATCH_FILENAME), '- id: a\n  config:\n    v: 3\n')
+    const profile = loadProfile('t', 'demo', anchor, home)
+    expect(profile.layers.map(layer => layer.packageName)).toEqual(['bundle-a', 'bundle-b'])
+    expect(profile.patches).toHaveLength(1)
+    const entries = composeEntries([
+      ...profile.layers.map(layer => layer.patches),
+      profile.patches,
+    ])
+    expect(entries).toEqual([{ id: 'a', name: 'pkg-a', config: { v: 3 } }])
+    // A hand-made profile without the user layer file or dsh section: empty layers, no throw.
+    rmSync(join(dir, PROFILE_PATCH_FILENAME))
+    expect(loadProfile('t', 'demo', anchor, home).patches).toEqual([])
+    writeProfileManifest(dir, { name: 'bare' })
+    const bare = loadProfile('t', 'demo', anchor, home)
+    expect(bare.layers).toEqual([])
+  })
+
+  it('auto-initializes only shipped templates and fails loud otherwise', () => {
+    const anchor = stageInstallation({})
+    const home = tmp()
+    expect(() => loadProfile('t', 'custom', anchor, home))
+      .toThrow('profile "custom" does not exist')
+    // The web template auto-initializes on first load. Bundle resolution
+    // cannot be asserted to fail here: the source-plane test runner resolves
+    // @deepseek-ai/* through tsconfig paths regardless of the staged anchor.
+    expect(PROFILE_TEMPLATES.web).toContain('@deepseek-ai/dsh-base')
+    try {
+      loadProfile('t', 'web', anchor, home)
+    } catch {
+      // Resolution failure is the plain-Node outcome for this empty anchor.
+    }
+    expect(readProfileManifest('t', resolveProfileDir('web', home)).dsh?.profile?.bundles)
+      .toEqual([...PROFILE_TEMPLATES.web ?? []])
+  })
+
+  it('fails loud when a listed bundle declares no dsh.bundle', () => {
+    const anchor = stageInstallation({ 'not-a-bundle': {} })
+    const home = tmp()
+    const dir = resolveProfileDir('demo', home)
+    initProfile(dir, ['not-a-bundle'])
+    expect(() => loadProfile('t', 'demo', anchor, home)).toThrow('declares no dsh.bundle')
+  })
+})
+
+describe('composeEntries', () => {
+  it('applies layers over an empty root and reports skipped patches', () => {
+    const warnings: string[] = []
+    const entries = composeEntries([
+      [{ insert: [{ id: 'x', name: 'pkg-x', config: { a: 1 } }] }],
+      [{ id: 'x', config: { a: 2 } }, { id: 'missing', config: {} }],
+    ], message => warnings.push(message))
+    expect(entries).toEqual([{ id: 'x', name: 'pkg-x', config: { a: 2 } }])
+    expect(warnings.join('\n')).toContain('"missing"')
+    // Default warn sink: skipped patches are silently dropped (boot repeats them).
+    expect(composeEntries([[{ id: 'missing', config: {} }]])).toEqual([])
+  })
+})
+
+describe('healProfilesModuleFallback', () => {
+  it('links the app and bundle dependency surface flat under profiles/node_modules', () => {
+    const anchor = stageInstallation({
+      'bundle-a': { patch: '[]\n', deps: { 'dep-of-a': '0.0.0', 'ghost-dep': '0.0.0' } },
+      'plain-lib': {},
+    })
+    // An app dependency that is declared but not installed: skipped, not fatal.
+    const appManifest = JSON.parse(readFileSync(anchor, 'utf8')) as { dependencies: Record<string, string> }
+    appManifest.dependencies['never-installed'] = '0.0.0'
+    writeFileSync(anchor, JSON.stringify(appManifest))
+    // dep-of-a lives in the installation's node_modules too.
+    const modules = join(anchor, '..', 'node_modules')
+    mkdirSync(join(modules, 'dep-of-a'), { recursive: true })
+    writeFileSync(join(modules, 'dep-of-a', 'package.json'), JSON.stringify({ name: 'dep-of-a', version: '0.0.0' }))
+    const home = tmp()
+    healProfilesModuleFallback(anchor, home)
+    const fallback = join(home, 'profiles', 'node_modules')
+    // App deps, the bundle's own deps, and the bundle itself are linked; the
+    // plain library is linked as an app dep (harmless), the app itself too.
+    for (const name of ['bundle-a', 'plain-lib', 'dep-of-a', 'dsh-app']) {
+      expect(lstatSync(join(fallback, name)).isSymbolicLink(), name).toBe(true)
+    }
+    // Idempotent, and a moved target is re-pointed.
+    healProfilesModuleFallback(anchor, home)
+    const before = readlinkSync(join(fallback, 'dep-of-a'))
+    expect(before).toContain('dep-of-a')
+  })
+
+  it('throws when a fallback entry is a real directory', () => {
+    const anchor = stageInstallation({})
+    const home = tmp()
+    mkdirSync(join(home, 'profiles', 'node_modules', 'dsh-app'), { recursive: true })
+    expect(() => { healProfilesModuleFallback(anchor, home) }).toThrow('is not a symlink')
+  })
+
+  it('replaces a wrong symlink', () => {
+    const anchor = stageInstallation({})
+    const home = tmp()
+    const fallback = join(home, 'profiles', 'node_modules')
+    mkdirSync(fallback, { recursive: true })
+    symlinkSync(tmp(), join(fallback, 'dsh-app'), 'junction')
+    healProfilesModuleFallback(anchor, home)
+    expect(readlinkSync(join(fallback, 'dsh-app'))).toContain('app')
+  })
+
+  it('tolerates losing the concurrent-heal race to an identical link and rejects a different one', () => {
+    // The EEXIST arm: a second process wrote the link between our lstat miss
+    // and symlinkSync. Simulated by pre-creating the correct link and calling
+    // the internal path through a stale-lstat shim is not possible from
+    // outside, so probe the observable contract: healing twice concurrently
+    // is a no-op, and a foreign REAL directory still fails loud.
+    const anchor = stageInstallation({})
+    const home = tmp()
+    healProfilesModuleFallback(anchor, home)
+    healProfilesModuleFallback(anchor, home) // second healer sees the correct link
+    const fallback = join(home, 'profiles', 'node_modules')
+    expect(lstatSync(join(fallback, 'dsh-app')).isSymbolicLink()).toBe(true)
+  })
+})

packages/boot/app-boot/tests/repository-cache.spec.ts

@@ -0,0 +1,162 @@
+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[] = []
+
+/** Normalize Git's platform checkout line endings for source-content assertions. */
+const lf = (text: string): string => text.replace(/\r\n/g, '\n')
+
+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')
+    expect(lf(await readFile(join(installed, 'dsh-plugin-assets/skills/0/fixture/SKILL.md'), 'utf8')))
+      .toBe('repository skill source\n')
+    await expect(readFile(join(installed, 'package.json'), 'utf8'))
+      .resolves.toContain('repository-plugin-fixture')
+  })
+})

packages/boot/app-boot/tests/user-patches.spec.ts

@@ -0,0 +1,263 @@
+/**
+ * User patch-layer behavior of `dsh-app-boot`: the optional patch-list loader
+ * (a profile's `cordis.patch.yml`) and `boot()` applying the user layer over
+ * a real Loader tree, kept live through transactional HMR.
+ */
+
+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 { Context } from 'cordis'
+import Hmr from '@cordisjs/plugin-hmr'
+import Loader from '@cordisjs/plugin-loader'
+import Timer from '@cordisjs/plugin-timer'
+import {
+  boot,
+  loadOptionalPatches,
+  PROFILE_PATCH_FILENAME,
+  watchUserPatches,
+} from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-user-patches-'))
+
+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('loadOptionalPatches', () => {
+  afterEach(() => {
+    delete process.env.DSH_HOME
+  })
+
+  it('returns undefined when no user patch file exists', () => {
+    expect(loadOptionalPatches(NAME, join(tmp(), PROFILE_PATCH_FILENAME))).toBeUndefined()
+  })
+
+  it('parses a patch list and preserves !!js expressions as loader expression nodes', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, PROFILE_PATCH_FILENAME), [
+      '- id: agent-loop',
+      "  name: '@deepseek-ai/dsh-agent-loop'",
+      '  config:',
+      '    model: !!js process.env.DSH_SPEC_MODEL',
+      '- insert:',
+      '    - id: llm',
+      "      name: '@deepseek-ai/dsh-llm-pi-ai'",
+      '',
+    ].join('\n'))
+    const patches = loadOptionalPatches(NAME, join(dir, PROFILE_PATCH_FILENAME))
+    expect(patches).toHaveLength(2)
+    expect(patches?.[0]).toMatchObject({
+      id: 'agent-loop',
+      config: { model: { __jsExpr: 'process.env.DSH_SPEC_MODEL' } },
+    })
+    expect(patches?.[1]?.insert).toHaveLength(1)
+  })
+
+  it('fails loud on an unreadable file (a present user patch layer is never skipped)', () => {
+    const dir = tmp()
+    mkdirSync(join(dir, PROFILE_PATCH_FILENAME)) // a directory: present, unreadable as a file
+    expect(() => loadOptionalPatches(NAME, join(dir, PROFILE_PATCH_FILENAME)))
+      .toThrow(new RegExp(`^${NAME}: failed to read patches `))
+  })
+
+  it('fails loud on unparsable YAML and on a !!js tag with no expression body', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, PROFILE_PATCH_FILENAME), 'invalid: [unclosed\n')
+    expect(() => loadOptionalPatches(NAME, join(dir, PROFILE_PATCH_FILENAME)))
+      .toThrow(new RegExp(`^${NAME}: failed to parse patches `))
+    writeFileSync(join(dir, PROFILE_PATCH_FILENAME), '- id: x\n  config:\n    a: !!js\n')
+    expect(() => loadOptionalPatches(NAME, join(dir, PROFILE_PATCH_FILENAME)))
+      .toThrow(new RegExp(`^${NAME}: failed to parse patches `))
+  })
+
+  it('fails loud when the file is not a top-level array or an entry is not an object', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, PROFILE_PATCH_FILENAME), 'id: not-a-list\n')
+    expect(() => loadOptionalPatches(NAME, join(dir, PROFILE_PATCH_FILENAME)))
+      .toThrow('must be a top-level YAML array of loader patch entries')
+    writeFileSync(join(dir, PROFILE_PATCH_FILENAME), '- just-a-string\n')
+    expect(() => loadOptionalPatches(NAME, join(dir, PROFILE_PATCH_FILENAME)))
+      .toThrow(`${NAME}: patches entry 1 in`)
+  })
+})
+
+describe('boot with user patches', () => {
+  function writeTree(dir: string): string {
+    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')
+  }
+
+  function entryConfig(ctx: Context, id: string): unknown {
+    return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
+  }
+
+  it('applies id-targeted overrides, inserts, and interpolates !!js from the environment', async () => {
+    const dir = tmp()
+    const userDir = tmp()
+    writeFileSync(join(userDir, PROFILE_PATCH_FILENAME), [
+      '- id: noop',
+      '  name: ./noop.mjs',
+      '  config:',
+      '    value: !!js process.env.DSH_APP_BOOT_USER_SPEC',
+      '- insert:',
+      '    - id: user-extra',
+      '      name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    process.env['DSH_APP_BOOT_USER_SPEC'] = 'user-value'
+    const ctx = await boot(NAME, writeTree(dir), loadOptionalPatches(NAME, join(userDir, PROFILE_PATCH_FILENAME)))
+    try {
+      const noop = [...ctx.loader.entries()].find(entry => entry.options.id === 'noop')
+      // The mounted plugin received the interpolated environment value.
+      expect(noop?.fiber?.config).toEqual({ value: 'user-value' })
+      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'user-extra')).toBe(true)
+    } finally {
+      await ctx.fiber.dispose()
+      delete process.env['DSH_APP_BOOT_USER_SPEC']
+    }
+  })
+
+  it('mounts no patch layer for an absent or empty user layer', async () => {
+    const dir = tmp()
+    const ctx = await boot(NAME, writeTree(dir), loadOptionalPatches(NAME, join(tmp(), PROFILE_PATCH_FILENAME)))
+    try {
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'base' })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+    const empty = tmp()
+    writeFileSync(join(empty, PROFILE_PATCH_FILENAME), '[]\n')
+    const ctxEmpty = await boot(NAME, writeTree(tmp()), loadOptionalPatches(NAME, join(empty, PROFILE_PATCH_FILENAME)))
+    try {
+      expect(entryConfig(ctxEmpty, 'noop')).toEqual({ value: 'base' })
+    } finally {
+      await ctxEmpty.fiber.dispose()
+    }
+  })
+
+  it('watches add, failure, recovery, and removal through transactional HMR', { timeout: 20_000 }, async () => {
+    const dir = tmp()
+    const userDir = tmp()
+    const filename = join(userDir, PROFILE_PATCH_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 watchUserPatches(ctx, {
+      binName: NAME,
+      filename,
+      compose: userPatches => [...basePatches, ...userPatches],
+    })
+    try {
+      writeFileSync(filename, '- id: noop\n  config:\n    value: live\n')
+      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'live', 'user patch 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', 'user patch removal did not restore the app-owned patch')
+      expect(failures).toHaveLength(2)
+      await settleChokidarChangeThrottle()
+
+      // Default compose: the user layer IS the whole patch list, so a
+      // fresh generation replaces the app-owned layer instead of stacking on it.
+      await dispose()
+      const disposeDefault = await watchUserPatches(ctx, { binName: NAME, filename })
+      try {
+        writeFileSync(filename, '- id: noop\n  config:\n    value: identity\n')
+        await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'identity', 'default-compose user 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(watchUserPatches(withoutHmr, { binName: NAME, filename: join(tmp(), PROFILE_PATCH_FILENAME) })).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(watchUserPatches(withoutInclude, { binName: NAME, filename: join(tmp(), PROFILE_PATCH_FILENAME) })).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 surface can dispose 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 watchUserPatches(ctx, { binName: NAME, filename: join(tmp(), PROFILE_PATCH_FILENAME) })
+      await expect(dispose()).resolves.toBeUndefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('propagates registration failures other than mid-teardown', async () => {
+    const dir = tmp()
+    const filename = join(tmp(), PROFILE_PATCH_FILENAME)
+    const ctx = await boot(NAME, writeTree(dir))
+    try {
+      await ctx.plugin(Timer)
+      await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+      const dispose = await watchUserPatches(ctx, { binName: NAME, filename })
+      // Same user-layer path registered twice: HMR refuses; not a teardown race.
+      await expect(watchUserPatches(ctx, { binName: NAME, filename })).rejects.toThrow('already registered')
+      await dispose()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})

packages/boot/app-boot/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../../vendor/include"
+    },
+    {
+      "path": "../../../vendor/hmr"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../util/environment"
+    },
+    {
+      "path": "../../util/paths"
+    }
+  ]
+}

packages/boot/app-boot/tsdown.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * Embed Include while keeping Loader external so the built include tree and
+ * app host bind to one Loader peer.
+ */
+export default defineConfig({
+  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+  deps: {
+    alwaysBundle: ['@cordisjs/plugin-include'],
+  },
+})