fix(cordis): make config reload transactional

2026-07-30 03:11:16 +08:00
parent f8eb6a9b84
commit 195f7fa9af
33 changed files with 1020 additions and 268 deletions
--- a/packages/host/directory-picker-auto/src/index.ts
+++ b/packages/host/directory-picker-auto/src/index.ts
@@ -61,11 +61,9 @@ export async function apply(ctx: Context): Promise<void> {
      // nothing is left to unmount or await then.
      const entry = ctx.loader.store[id]
      if (entry === undefined) return
-      const fiber = entry.fiber
-      ctx.loader.remove(id)
-      // remove() only starts the fiber's dispose; join it so the chooser's
-      // unload signals completion only after the backend quiesced.
-      await fiber?.dispose()
+      // remove() disposes the entry transactionally, so the chooser's unload
+      // signals completion only after the backend quiesced.
+      await ctx.loader.remove(id)
    }
  }, 'directory-picker-auto: backend entry')
 }
--- a/packages/host/directory-picker-auto/tests/loader-composition.spec.ts
+++ b/packages/host/directory-picker-auto/tests/loader-composition.spec.ts
@@ -167,7 +167,7 @@ describe('real Loader composition', () => {
    const { ctx, configPath } = await loadComposition('127.0.0.1')

    const backendEntry = [...ctx.loader.entries()].find(entry => entry.options.name === NATIVE)!
-    ctx.loader.remove(backendEntry.id)
+    await ctx.loader.remove(backendEntry.id)
    const autoEntry = [...ctx.loader.entries()].find(entry => entry.options.name === AUTO)!
    await expect(autoEntry.fiber!.dispose()).resolves.not.toThrow()
    expect(entryNames(ctx)).not.toContain(NATIVE)
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/webserver/README.md
-README.md: ace8c09e43dd8544a28d300f97b04610be78bc69
-README.zh.md: b9948e3d387a5da393ff62b9eeacfe310516f46a
+README.md: c3c7b222683bc7731a6c21f2fffd325225099bab
+README.zh.md: 99c0560eb74dc8076772ba1deef3034000f5f0db
--- a/packages/host/webserver/README.md
+++ b/packages/host/webserver/README.md
@@ -6,7 +6,7 @@ Plain HTTP route-registration plugin (default-exported `HttpServerService`, conf

 The package knows no harness concepts: the `/api` bridge is the connection plugin's route, plugin bundles and the HMR event stream are the modules/hmr plugins' routes. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); `distIndex` is an assembly fact the composing app resolves and injects, never self-resolved (dist location is workspace knowledge of the app). Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell.

-A listen failure (EADDRINUSE…) throws out of activation — a FAILED fiber the boot's fail-loud sweep reports. A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and logged as a warning; it never exits the process. Disposal pairs `close()` with `closeAllConnections()` because held-open responses (SSE) never end on their own.
+A listen failure (EADDRINUSE…) throws out of activation and rejects Loader composition with the bind diagnostic; the failed candidate fiber is disposed. A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and logged as a warning; it never exits the process. Disposal pairs `close()` with `closeAllConnections()` because held-open responses (SSE) never end on their own.

 In development, the client-plugin registry synchronously captures each built bundle's stat baseline before it returns, then polls those baselines and re-hashes changed content. Each rescan stages its candidate table, graph, and watch map before publishing them, so a baseline failure preserves the prior graph. An immediate rebuild therefore cannot disappear into an asynchronously established watch baseline; a rename window marks the path dirty, retains the last successful baseline, and forces a re-hash when the bundle reappears even with identical metadata.

--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -6,7 +6,7 @@

 该包不了解任何 harness 概念：`/api` 桥接是 connection 插件的路由，插件 bundle 与 HMR（热模块替换）事件流则是 modules／hmr 插件的路由。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）；`distIndex` 是由组合应用解析并注入的组装事实，绝不会自行解析，因为 dist 位置属于应用的工作区知识。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。

-监听失败（EADDRINUSE……）会从激活过程抛出，使 fiber 进入 FAILED 状态并由启动流程的快速失败扫描报告。处理请求时抛错（例如格式错误的百分号转义传入 `decodeURIComponent`，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。资源释放会把 `close()` 与 `closeAllConnections()` 配对，因为一直保持打开的响应（SSE）不会自行结束。
+监听失败（EADDRINUSE……）会从激活过程抛出，以 bind 诊断使 Loader 组合 reject；失败的候选 fiber 会被 dispose（资源释放）。处理请求时抛错（例如格式错误的百分号转义传入 `decodeURIComponent`，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。资源释放会把 `close()` 与 `closeAllConnections()` 配对，因为一直保持打开的 SSE（Server-Sent Events）响应不会自行结束。

 在开发环境中，客户端插件注册表会在返回前同步捕获每个已构建 bundle 的 stat 基线，随后轮询这些基线，并在内容变化后重新计算哈希。每次重新扫描都会先暂存候选表、图和监听 map，再统一发布，因此基线失败会保留先前的图。这样，即时重建不会消失在异步建立的监听基线中；重命名窗口会把路径标记为脏，保留最近一次成功基线，并在 bundle 重新出现时强制重新计算哈希，即使其元数据完全相同也不例外。

--- a/packages/host/webserver/tests/webserver.spec.ts
+++ b/packages/host/webserver/tests/webserver.spec.ts
@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
-import { Context, FiberState } from 'cordis'
+import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Include from '@cordisjs/plugin-include'
 import HttpServer from '../src/index.ts'
@@ -142,25 +142,17 @@ describe('real Loader composition', () => {
    const firstRoot = root
    root = undefined // keep the first composition's files until the end

-    // loader.await() never rejects (allSettled); the bind failure surfaces as
-    // a FAILED fiber whose error escapes as a late rejection — the shape the
-    // boot's installFailLoud is contracted to catch. Capture it here the same
-    // way, and assert it really is the bind error.
-    const rejections: unknown[] = []
-    const onUnhandled = (err: unknown): void => { rejections.push(err) }
-    process.on('unhandledRejection', onUnhandled)
    let second: Context | undefined
    try {
-      second = await loadComposition(takenPort)
-      const entry = [...second.loader.entries()].find(e => e.options.name === '@deepseek-ai/dsh-host-webserver')
-      expect(entry?.fiber?.state).toBe(FiberState.FAILED)
-      // The rejection escapes a tick after loader.await() settles; bounded poll.
-      for (let i = 0; i < 100 && rejections.length === 0; i++) {
-        await new Promise(resolve => setTimeout(resolve, 10))
+      let failure: unknown
+      try {
+        await loadComposition(takenPort)
+      } catch (error) {
+        failure = error
      }
-      expect(rejections.map(String).join('\n')).toContain('EADDRINUSE')
+      second = context
+      expect(String(failure)).toMatch(/failed to apply loader entry.*EADDRINUSE/)
    } finally {
-      process.off('unhandledRejection', onUnhandled)
      await second?.fiber.dispose()
      context = first
      if (root !== undefined) await rm(root, { recursive: true, force: true })
--- a/packages/typert/loader/tests/loader.spec.ts
+++ b/packages/typert/loader/tests/loader.spec.ts
@@ -147,12 +147,12 @@ describe('typert loader', () => {
    await new Promise(resolve => setTimeout(resolve, 20))
    expect(ctx.typert.list()).toHaveLength(1)

-    ctx.loader.remove(id)
+    await ctx.loader.remove(id)
    await ctx.loader.await()
    // The unmount reconciliation rides a queued microtask flush.
    await new Promise(resolve => setTimeout(resolve, 20))
    expect(ctx.typert.get('@fixture/with-typert#Thing')).toBeUndefined()
-    ctx.loader.remove(plainId)
+    await ctx.loader.remove(plainId)
    await ctx.loader.await()
    await new Promise(resolve => setTimeout(resolve, 20))

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

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

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

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

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

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

--- a/packages/ui/app-boot/package.json
+++ b/packages/ui/app-boot/package.json
@@ -38,8 +38,10 @@
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
+    "@cordisjs/plugin-hmr": "workspace:^",
    "@cordisjs/plugin-include": "workspace:^",
    "@cordisjs/plugin-loader": "workspace:^",
+    "@cordisjs/plugin-timer": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-paths": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -11,7 +11,7 @@ import { readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
+import Loader, { type EntryOptions } from '@cordisjs/plugin-loader'
 import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
 import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
@@ -430,12 +430,13 @@ export async function assertEntriesActivated(ctx: Context, binName: string): Pro
 * `cordis:include` builtin, loading through the ambient module pipeline
 * (vite/tsx/plain ESM) while the included tree's own specifiers stay
 * config-relative. The package build embeds Include while leaving Loader
- * external, so the built include tree and host share one Loader peer. A
- * missing fiber rejects here; a later init rejection is rethrown with its
- * original stack by {@link assertEntriesActivated}; later unhandled
- * rejections remain covered by {@link installFailLoud}. Built bins need the
- * Loader's native helper for bare plugin specifiers; relative specifiers do
- * not.
+ * external, so the built include tree and host share one Loader peer. Loader
+ * settlement rejects startup failures, which `boot` wraps after disposing the
+ * partial context; a missing fiber or never-activating entry is rejected by
+ * the final audit, {@link assertEntriesActivated}, which rethrows a plugin's
+ * init rejection with its original stack; later unhandled rejections remain
+ * covered by {@link installFailLoud}. Built bins need the Loader's native
+ * helper for bare plugin specifiers; relative specifiers do not.
 * @param binName - the diagnostic prefix for load-failure errors.
 * @param absoluteConfigPath - the config to include; must already be absolute
 * (see {@link resolveConfigPath}).
@@ -444,6 +445,7 @@ export async function assertEntriesActivated(ctx: Context, binName: string): Pro
 * @param prepare - optional host setup run after Loader installation and before any config-tree entry mounts.
 * @returns the root context once every entry has started, or as soon as a
 * surface disposed the tree while startup was still in flight.
+ * @throws a labelled load error after disposing the partial context.
 */
 export async function boot(
  binName: string,
@@ -452,28 +454,49 @@ export async function boot(
  prepare?: (ctx: Context) => Promise<void> | void,
 ): Promise<Context> {
  const ctx = new Context()
-  ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
-  ctx.provide('dshHomePath', dshHomePath)
-  await ctx.plugin(Loader)
-  ctx.loader.builtins.include = Include
-  await prepare?.(ctx)
-  await ctx.loader.create({
-    name: 'cordis:include',
-    config: {
-      path: pathToFileURL(absoluteConfigPath).href,
-      ...patches !== undefined && patches.length > 0 ? { patches } : {},
-    },
-  })
-  await ctx.loader.await()
-  // A surface can finish and dispose the whole tree while that await is still
-  // pending: the TUI renders as soon as its own fiber starts, so an `/exit`
-  // typed before the last entry settles tears the context down under us. The
-  // Loader service goes with it, and the activation audit describes a live
-  // tree — reading `ctx.loader` here would throw a TypeError over an app that
-  // exited exactly as asked.
-  if (ctx.get('loader') === undefined) return ctx
-  await assertEntriesActivated(ctx, binName)
-  return ctx
+  try {
+    ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
+    ctx.provide('dshHomePath', dshHomePath)
+    await ctx.plugin(Loader)
+    ctx.loader.builtins.include = Include
+    await prepare?.(ctx)
+    // 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 !== undefined && patches.length > 0 ? { patches } : {},
+      },
+    }
+    await ctx.loader.create(rootInclude)
+    // A surface can finish and dispose the whole tree while startup is still
+    // in flight: the TUI renders as soon as its own fiber starts, so an `/exit`
+    // typed before the last entry settles tears the context down under us. The
+    // Loader service goes with it, and the activation audit describes a live
+    // tree — reading `ctx.loader` past this point would throw a TypeError over
+    // an app that exited exactly as asked. Transactional group updates settle
+    // lifecycle inside the mount, so the teardown can land before it returns;
+    // re-check after every await.
+    await ctx.get('loader')?.await()
+    if (ctx.get('loader') === undefined) return ctx
+    await assertEntriesActivated(ctx, binName)
+    return ctx
+  } catch (cause) {
+    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}: plugin tree failed to load: ${detail}${stack}`, { cause })
+  }
 }

 /** Prompt-section name for the harness-source location line an app bin adds after boot. */
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -325,6 +325,22 @@ describe('boot', () => {
    }
  })

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

  it('reports a pending real Loader fiber and the service unresolved in its own context', async () => {
--- a/packages/ui/app-boot/tests/config-reload.spec.ts
+++ b/packages/ui/app-boot/tests/config-reload.spec.ts
@@ -1,12 +1,7 @@
 /**
- * Config hot-reload resilience of the booted include tree. `dsh-app-boot`
- * installs a fail-loud unhandled-rejection handler, so a `refresh()` that
- * rethrows a config-file parse error would kill a live app on one bad
- * `cordis.yml` edit (the HMR watcher awaits `refresh()` in an async event
- * callback nobody else catches). These tests pin the vendored
- * `@cordisjs/plugin-include` contract that boot relies on: an invalid file
- * keeps the last good tree, and a valid re-read re-applies overlay patches
- * exactly like the initial load.
+ * Transactional config replacement through the booted Include and Loader tree.
+ * HMR contains rejected refreshes; direct callers receive the error after the
+ * previous generation has been retained or restored.
 */

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

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

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

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

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

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

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

+describe('loader entry replacement', () => {
+  it('imports a changed name before replacing the running plugin', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./old.mjs\n', {
+      'old.mjs': plugin('oldPlugin'),
+      'new.mjs': plugin('newPlugin'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      await entry.update({ name: './new.mjs' })
+      expect(entry.options.name).toBe('./new.mjs')
+      expect(entry.parent.data.find(options => options.id === 'target')).toBe(entry.options)
+      expect(entry.fiber?.runtime?.callback.name).toBe('newPlugin')
+      expect(entry.options.disabled).toBeUndefined()
+      await entry.fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('retains the running plugin when the replacement cannot be imported', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./old.mjs\n', {
+      'old.mjs': plugin('oldPlugin'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const fiber = entry.fiber
+      await expectUpdateFailure(entry.update({ name: './missing.mjs' }), 'import')
+      expect(entry.options.name).toBe('./old.mjs')
+      expect(entry.fiber === fiber).toBe(true)
+      await fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('restores the previous plugin after replacement application fails', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./old.mjs\n', {
+      'old.mjs': plugin('oldPlugin'),
+      'bad.mjs': plugin('badPlugin', 'throw new Error("candidate apply failed")'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const previous = entry.fiber
+      await expectUpdateFailure(entry.update({ name: './bad.mjs' }), 'apply')
+      expect(entry.options.name).toBe('./old.mjs')
+      expect(entry.fiber === previous).toBe(false)
+      expect(entry.fiber?.runtime?.callback.name).toBe('oldPlugin')
+      expect(entry.options.disabled).toBeUndefined()
+      await entry.fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('restores the previous config when an in-place restart fails', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./configurable.mjs\n  config:\n    fail: false\n', {
+      'configurable.mjs': plugin('configurablePlugin', 'if (config.fail) throw new Error("candidate config failed")'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const fiber = entry.fiber
+      await expectUpdateFailure(entry.update({ config: { fail: true } }), 'apply')
+      expect(entry.options.config).toEqual({ fail: false })
+      expect(entry.fiber === fiber).toBe(true)
+      await fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('does not persist a failed direct fiber update', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./configurable.mjs\n  config:\n    fail: false\n', {
+      'configurable.mjs': plugin('configurablePlugin', 'if (config.fail) throw new Error("candidate config failed")'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const fiber = entry.fiber
+      if (!fiber) throw new Error('target entry has no fiber')
+      await expect(fiber.update({ fail: true })).rejects.toThrow('candidate config failed')
+      expect(entry.options.config).toEqual({ fail: false })
+      expect(entry.parent.data.find(options => options.id === 'target')).toBe(entry.options)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
+describe('loader tree replacement', () => {
+  it('rolls back earlier updates and additions when a later entry fails', async () => {
+    const { ctx, dir, include } = await bootTree([
+      '- id: existing',
+      '  name: ./configurable.mjs',
+      '  config:',
+      '    value: old',
+      '',
+    ].join('\n'), {
+      'configurable.mjs': plugin('configurablePlugin'),
+      'bad.mjs': plugin('badPlugin', 'throw new Error("candidate apply failed")'),
+    })
+    try {
+      writeFileSync(join(dir, 'cordis.yml'), [
+        '- id: existing',
+        '  name: ./configurable.mjs',
+        '  config:',
+        '    value: candidate',
+        '- id: added',
+        '  name: ./noop.mjs',
+        '- id: bad',
+        '  name: ./bad.mjs',
+        '',
+      ].join('\n'))
+      await expect(include.refresh()).rejects.toThrow('failed to apply loader entry bad')
+      expect(entryConfig(ctx, 'existing')).toEqual({ value: 'old' })
+      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'added')).toBe(false)
+      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'bad')).toBe(false)
+
+      writeFileSync(join(dir, 'cordis.yml'), [
+        '- id: existing',
+        '  name: ./configurable.mjs',
+        '  config:',
+        '    value: committed',
+        '- id: added',
+        '  name: ./noop.mjs',
+        '',
+      ].join('\n'))
+      await include.refresh()
+      expect(entryConfig(ctx, 'existing')).toEqual({ value: 'committed' })
+      expect(entryById(ctx, 'added').fiber).toBeDefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('stops and restores descendants when an ancestor group is disabled and re-enabled', async () => {
+    const { ctx, dir, include } = await bootTree('- id: noop\n  name: ./noop.mjs\n')
+    ctx.loader.builtins.group = Group
+    try {
+      const config = (disabled: boolean) => [
+        '- id: parent',
+        '  name: cordis:group',
+        '  group: true',
+        `  disabled: ${disabled}`,
+        '  config:',
+        '    - id: child',
+        '      name: ./noop.mjs',
+        '',
+      ].join('\n')
+
+      writeFileSync(join(dir, 'cordis.yml'), config(false))
+      await include.refresh()
+      expect(entryById(ctx, 'child').fiber).toBeDefined()
+
+      writeFileSync(join(dir, 'cordis.yml'), config(true))
+      await include.refresh()
+      expect(entryById(ctx, 'child').fiber).toBeUndefined()
+
+      writeFileSync(join(dir, 'cordis.yml'), config(false))
+      await include.refresh()
+      expect(entryById(ctx, 'child').fiber).toBeDefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('restores a programmatic entry move when its update fails', async () => {
+    const { ctx } = await bootTree('- id: noop\n  name: ./noop.mjs\n', {
+      'movable.mjs': plugin('movablePlugin', 'if (config.fail) throw new Error("candidate config failed")'),
+    })
+    ctx.loader.builtins.group = Group
+    try {
+      const groupId = await ctx.loader.create({ name: 'cordis:group', group: true, config: [] })
+      const targetId = await ctx.loader.create({ name: './movable.mjs', config: { fail: false } })
+      const target = entryById(ctx, targetId)
+      const source = target.parent
+      const sourceIndex = source.data.indexOf(target.options)
+      const destination = entryById(ctx, groupId).subgroup
+      if (!destination) throw new Error('created loader group has no subgroup')
+
+      await expectUpdateFailure(
+        ctx.loader.update(targetId, { config: { fail: true } }, groupId),
+        'apply',
+      )
+
+      expect(target.parent).toBe(source)
+      expect(Object.getPrototypeOf(target.ctx)).toBe(source.ctx)
+      expect(source.data.indexOf(target.options)).toBe(sourceIndex)
+      expect(destination.data).not.toContain(target.options)
+      expect(target.options.config).toEqual({ fail: false })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
 describe('include refresh with overlay patches', () => {
  it('re-applies entry patches and inserted entries on every re-read (parity with initial load)', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'dsh-config-reload-overlay-'))
--- a/packages/ui/app-boot/tests/hmr-config.spec.ts
+++ b/packages/ui/app-boot/tests/hmr-config.spec.ts
@@ -0,0 +1,142 @@
+import { mkdirSync, mkdtempSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Context } from 'cordis'
+import Hmr from '@cordisjs/plugin-hmr'
+import Loader from '@cordisjs/plugin-loader'
+import Timer from '@cordisjs/plugin-timer'
+import { describe, expect, it } from 'vitest'
+
+async function bootHmr(dir: string): Promise<Context> {
+  const ctx = new Context()
+  ctx.baseUrl = pathToFileURL(dir).href + '/'
+  await ctx.plugin(Loader)
+  await ctx.plugin(Timer)
+  await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+  return ctx
+}
+
+async function eventually(test: () => boolean, message: string): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (!test()) {
+    if (Date.now() >= deadline) throw new Error(message)
+    await new Promise(resolve => setTimeout(resolve, 10))
+  }
+}
+
+describe('HMR exact config paths', () => {
+  it('observes add, change, and unlink outside its module roots', { timeout: 20_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const filename = join(dir, 'plugins.yml')
+    const ctx = await bootHmr(dir)
+    const observed: string[] = []
+    try {
+      await ctx.hmr.registerConfig(filename, () => {
+        try {
+          observed.push(readFileSync(filename, 'utf8'))
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+          observed.push('missing')
+        }
+      })
+
+      writeFileSync(filename, 'one', { flag: 'wx' })
+      await eventually(() => observed.includes('one'), 'HMR did not observe config creation')
+      writeFileSync(filename, 'two')
+      await eventually(() => observed.includes('two'), 'HMR did not observe config change')
+      unlinkSync(filename)
+      await eventually(() => observed.includes('missing'), 'HMR did not observe config removal')
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('observes creation when the config parent did not exist at registration', { timeout: 20_000 }, async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const dir = join(root, 'later')
+    const filename = join(dir, 'plugins.yml')
+    const ctx = await bootHmr(root)
+    const observed: string[] = []
+    try {
+      await ctx.hmr.registerConfig(filename, () => {
+        observed.push(readFileSync(filename, 'utf8'))
+      })
+      mkdirSync(dir)
+      writeFileSync(filename, 'created')
+      await eventually(() => observed.includes('created'), 'HMR did not observe config creation under a new parent')
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('serializes refreshes and waits for them during disposal', { timeout: 20_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const filename = join(dir, 'plugins.yml')
+    writeFileSync(filename, 'one')
+    const ctx = await bootHmr(dir)
+    const started = Promise.withResolvers<undefined>()
+    const release = Promise.withResolvers<undefined>()
+    const observed: string[] = []
+    let active = 0
+    let maxActive = 0
+    try {
+      const dispose = await ctx.hmr.registerConfig(filename, async () => {
+        active += 1
+        maxActive = Math.max(maxActive, active)
+        observed.push(readFileSync(filename, 'utf8'))
+        if (observed.length === 1) {
+          started.resolve(undefined)
+          await release.promise
+        }
+        active -= 1
+      })
+      await started.promise
+      writeFileSync(filename, 'two')
+      // Chokidar coalesces atomic writes for 100 ms by default. Wait beyond
+      // that window so this edit is queued before registration disposal.
+      await new Promise(resolve => setTimeout(resolve, 250))
+
+      let disposed = false
+      const disposal = dispose().then(() => { disposed = true })
+      await Promise.resolve()
+      expect(disposed).toBe(false)
+      release.resolve(undefined)
+      await disposal
+      expect(maxActive).toBe(1)
+      expect(observed).toEqual(['one', 'two'])
+    } finally {
+      release.resolve(undefined)
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('normalizes refresh failures and broadcasts them without escaping the watcher', { timeout: 20_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const filename = join(dir, 'plugins.yml')
+    const ctx = await bootHmr(dir)
+    const failure = Promise.withResolvers<{ filename: string; error: Error }>()
+    let failureCount = 0
+    try {
+      ctx.on('hmr/config-update-failed', () => {
+        throw new Error('observer failed')
+      })
+      ctx.on('hmr/config-update-failed', (failedFilename, error) => {
+        failureCount += 1
+        failure.resolve({ filename: failedFilename, error })
+      })
+      await ctx.hmr.registerConfig(filename, () => { throw 42 })
+      writeFileSync(filename, 'invalid')
+
+      const observed = await failure.promise
+      expect(observed.filename).toBe(filename)
+      expect(observed.error).toBeInstanceOf(Error)
+      expect(observed.error.message).toBe('42')
+
+      writeFileSync(filename, 'invalid again')
+      await eventually(() => failureCount === 2, 'HMR stopped broadcasting after an observer rejected')
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})