@deepseek-ai/dsh-hmr 0.2.1-alpha.2 → 0.2.1-alpha.4

package/README.i18n.yaml

@@ -18,11 +18,11 @@
   en: 9fd376ac44e7f515
   zh: 83bd165982e99d2a
 /deepseek-ai-dsh-hmr/use-this-package/configuration:
-  en: 45ee194ad781d603
-  zh: b3d7fcd8ed73717c
+  en: 11ef18c6d08f39f3
+  zh: 2911cdd03ff3747d
 /deepseek-ai-dsh-hmr/understand-the-implementation:
-  en: 227c3c99c3c4b597
-  zh: 853b656340cb8bce
+  en: bd608f418630317f
+  zh: 053fa77a3fa571a9
 /deepseek-ai-dsh-hmr/model-experience:
   en: 215e7ba838619b7b
   zh: a311da3843709f90
@@ -39,8 +39,8 @@
   en: 89e0624fafd701fb
   zh: 19d36a33c1d9af9d
 /deepseek-ai-dsh-hmr/known-limitations-and-deferred-work:
-  en: 0f46d4df1dab7f3b
-  zh: d172835159a20cce
+  en: 709368e0d6a644c2
+  zh: 2d0f76c2cece79dc
 /deepseek-ai-dsh-hmr/known-limitations-and-deferred-work/dev-note:
   en: 7972e4b2005ec9a4
   zh: 754c49ec538c164c

package/README.md

@@ -46,6 +46,8 @@ Existing configurations replace the module name `@deepseek-ai/cordis-plugin-hmr`
 
 Chokidar options, including polling, retain their existing meaning. Exact configuration watches also observe additions, removals and initially missing parent directories. They default to `awaitWriteFinish: true`: edits wait for Chokidar's 2-second write-stability window, avoiding its lossy change-event throttle. Configure `awaitWriteFinish` to adjust that window; disabling it can miss rapid consecutive edits. Direct Plugin Manager operations apply without waiting for file events.
 
+Profile recompositions run by HMR's profile watches and by Plugin Manager also replace plugins whose loaded files below the profile directory changed on disk. This covers installed packages below `node_modules` and the targets of linked packages. A package whose files changed in place, such as a linked package whose build output changed or a dependency another installation upgraded, therefore takes effect without a restart at the next such recomposition; source watching through `root` is not required. A replacement that fails to load stops the previous plugin and is reported as `failed` with its load error instead of as a restart, which would load the same files; every later recomposition imports it again, so it starts once its files or dependencies are corrected.
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -54,10 +56,20 @@ Chokidar options, including polling, retain their existing meaning. Exact config
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-`watchConfig()` registers an awaited configuration handler. `runExclusive()` serializes configuration changes and Loader updates with automatic reloads and rejects nested transactions. Package installation and removal run outside this queue. HMR does not acquire the package writer lock; manifest notifications reload only when the ordered `dsh.profile.bundles` list changes. Profile and home patch changes also trigger recomposition. File events received during a configuration transaction are processed afterward. Include refreshes and profile reconciliation reach plugins through ordinary Loader entry updates; Loader commits volatile-only changes in place.
+`watchConfig()` registers an awaited configuration handler and watches only its target path and required parent directories; sibling files, including temporary writer locks, are excluded before native watcher creation. `runExclusive()` serializes configuration changes and Loader updates with automatic reloads and rejects nested transactions. Package installation and removal run outside this queue. HMR does not acquire the package writer lock; manifest notifications reload only when the ordered `dsh.profile.bundles` list changes. Profile and home patch changes also trigger recomposition. File events received during a configuration transaction are processed afterward. Include refreshes and profile reconciliation reach plugins through ordinary Loader entry updates; Loader commits volatile-only changes in place.
 
 App-boot owns profile parsing and patch precedence. HMR reads the launcher’s data-only `profileContext`, registers the profile manifest and both user patch watches during initialization, and waits for application readiness before processing changes. Its disposal closes the watchers and cancels reloads waiting for startup. Configuration watchers start outside the active transaction context so later notifications can enter the queue.
 
+`reconcileProfile()` is shared by HMR’s profile watches and Plugin Manager; callers hold `runExclusive()`. Config Editor recomposes through app-boot without replacing modules. App-boot prepares and preflights the generation before caches or running entries change.
+
+File comparison covers the profile directory and linked package targets, recorded when the application becomes ready. [ModuleFiles](src/module-files.ts) records inode, size and modification time; adding a hard link alone does not invalidate a module. Existing modules retain the identities read before replacement, preserving later writes. Newly loaded modules are recorded at settlement so a subsequent installation does not restart them merely because they are recent.
+
+Replacement follows ES module links and every CommonJS parent’s `children`. A module's plugins are read from its ES module namespace and from the CommonJS exports Node already cached, without evaluating anything, so a CommonJS plugin registered outside a Loader entry keeps its cache. Host dependencies and plugins outside the traversable Loader tree stay pending. The remaining changed modules and their importers are evicted without a backup, and the Loader entries running affected plugins stop. HMR imports no replacement code itself: the Loader imports the current files when the generation starts an entry, so disabled, removed and incompatible rows never execute it, and dynamic `disabled` expressions and nested Includes are evaluated as at startup.
+
+Affected runtimes stop without making their entries disabled, and `reconcileProfile()` passes them to app-boot's single `recomposeProfile()` call, which starts them, including those below an unchanged Include and those outside the profile composition, without importing an entry twice. A failure before any stop leaves every plugin running; stopped plugins start again with the current resolution when no generation applied. After eviction, a replacement that fails to import or start is an activation failure and rejects the operation; its previous code no longer runs. Every recomposition imports entries whose import failed again, after expiring the package configuration below the profile roots and evicting modules whose links failed, so a corrected file or a dependency installed later takes effect without a restart. [ProfileReconciliation](../../../docs/subsystems/boot.md#profile-reconciliation) lists changes requiring a restart. A module first loaded during a recomposition whose file was written after the comparison stays stale, so a write during activation is loaded next time; comparison or cache-inspection failure requires a restart even when no changed URL is known. HMR’s watches log the result.
+
+After each recomposition, HMR evicts the loaded modules below the directories of the mappings the recomposition dropped and expires their package configuration, so the packages a removed or deselected bundle depends on, including those it imports dynamically, are imported afresh when it returns. A bundle package is not a mapping: its own files are replaced when they changed on disk, and a bundle switched off while its files stay unchanged keeps its modules loaded. A publication the runtime resolution rejects, such as a retained profile mapping that moved to another directory, stops and starts again the rows the generation would drop and leaves the composition as it was; the result has `restartReason: 'package-moved'`.
+
 A changed `package.json` outside `node_modules` expires that package's cached configuration. A configuration-only manifest triggers no module reload; a manifest imported as a JSON module retains dependency-driven reloads, and one in the host dependency graph retains host reloads. Dedicated configuration watches keep their existing ownership. A new package entry takes effect when its Loader entry restarts.
 
 Loader entries retain their raw import results. HMR retains every distinct imported namespace for each entry name and configuration-tree base URL; an uninitialized entry does not overwrite another entry's namespace. HMR matches those objects to cached ModuleJob namespaces instead of resolving entry names again. Names without an imported namespace and `cordis:` builtins keep name-based resolution. Source reloads therefore use the loaded modules after `exports` or `main` changes.
@@ -94,7 +106,16 @@ Reloading a contributing plugin can change later request prefixes; HMR does not
 <a id="known-limitations-and-deferred-work"></a>
 
 - Module replacement requires Node loader internals. Framework dependency changes call the host-provided `loader.exit()` hook; HMR itself does not restart the process.
-- Replacing installed package versions still requires a restart through Plugin Manager; manifests below `node_modules` keep Node's cached configuration. The browser Client module graph retains its separate browser-side loading mechanism.
+- A change confined to `package.json` is not detected. Watcher notifications for manifests below `node_modules` are still ignored. The browser Client module graph retains its separate browser-side loading mechanism.
+- Replacement follows static imports. A dynamic `import()` of a stale module evaluates the new file on its next call while its importer keeps running; existing Workers and the TSX loader thread keep their module caches.
+- Every symbolic link below the profile's `node_modules` widens the comparison scope. Linking a package that the process entry point, located through the real path of a bin link, imports statically, such as `dsh-app-boot`, Cordis or the Loader from a dsh checkout, brings host modules into scope; their changes stay pending, and Plugin Manager reports `restart-required` for later operations until the process restarts. Linked dsh packages that Loader entries import are replaced like other plugins.
+- The comparison records belong to one HMR instance. A recomposition that restarts the `hmr` entry itself records the current files again, so changes pending at that point are no longer reported or retried.
+- A replacement that fails to import or start stays inactive until its files or dependencies are corrected; the previous version is not restored.
+- Compatibility checks run only where DSH composes rows: startup, profile recomposition and preset mounting; the Loader checks nothing when it imports a module. A replaced profile row passes the recomposition's preflight, but a row outside the profile composition, such as a preset row or an entry added through `ctx.loader.create()`, restarts with replaced code without a check. Plugin Manager refuses incompatible versions, so this affects packages changed outside it, such as a manual `pnpm add` in the profile directory or a rebuilt `link:` package.
+- The [packed worker loader](../../experimental/webworker-runtime/src/module-system/module-loader.ts) exposes neither Node’s `loadCache` nor `require.cache`; configuration recomposition remains available, but code replacement requires a restart. Native Node retains these caches even with asynchronous module hooks. The [packed worker browser test](../../../apps/web/tests/preview-boot.e2e.ts) exercises this deployment.
+- A newly loaded file is first recorded after recomposition settles and counts as changed when its modification time follows the comparison. The comparison time is the modification time of a marker file HMR writes in the temporary directory, so on one machine both come from the clock local file writes are stamped with; an edit within the timestamp granularity of the profile's filesystem after the comparison counts as earlier and can be missed, and network filesystems stamp writes with the server's clock.
+- A file replaced by a hard link to an older store file keeps an older modification time; when its module was first loaded after the last recording, the change is not detected.
+- Profile recomposition caused by HMR's own watches does not run for dependency-only manifest changes, so an install performed outside Plugin Manager takes effect at the next recomposition or restart.
 - TSX loaders and ordinary application-created Workers are outside the supported package-cache refresh scope.
 - CommonJS requests must be resolvable by Node's default resolver. Synchronous hooks may postprocess the resulting filenames, as Desktop's Office resolver does; hooks requiring the original request name or introducing virtual requests are unsupported. Builtins retain Node's original loading behavior.
 - Future work: retain package invalidation across HMR disposal and replacement. Restoring the native readers can expose their older cached configuration again.

package/README.zh.md

@@ -46,6 +46,8 @@ kind: "package-reference"
 
 Chokidar 选项（包括轮询）保持原有含义。精确配置监听同时观察新增、删除及初始不存在的父目录。它们默认使用 `awaitWriteFinish: true`：编辑后等待 Chokidar 的 2 秒写入稳定窗口，避免其变化事件节流丢失通知。可通过 `awaitWriteFinish` 调整窗口；禁用它可能漏掉快速连续编辑。直接通过 Plugin Manager 发起的操作无需等待文件事件即可应用。
 
+HMR 的 profile 监听和 Plugin Manager 执行的 profile 重新组合，还会替换 profile 目录下已加载文件在磁盘上发生变化的插件。这包括 `node_modules` 之下的已安装包，以及已链接包的目标。因此，文件被原地更改的包，例如构建输出发生变化的已链接包，或被另一次安装升级的依赖，会在下一次此类重新组合时生效，无需重启；不要求通过 `root` 监听源码。替换版本加载失败时，原插件被停止，并以 `failed` 及其加载错误报告，而不是报告为需要重启，因为重启会加载相同的文件；此后每次重新组合都会再次导入它，因此其文件或依赖被修正后它即启动。
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -54,10 +56,20 @@ Chokidar 选项（包括轮询）保持原有含义。精确配置监听同时
 <details>
 <summary>实现细节——点击展开</summary>
 
-`watchConfig()` 注册会被等待的配置处理器。`runExclusive()` 将配置变更、Loader 更新与自动重载串行化，并拒绝嵌套事务。包安装和删除在该队列之外执行。HMR 不获取包操作写锁；manifest 通知仅在有序的 `dsh.profile.bundles` 列表变化时触发重载。profile 与 home patch 变化也会触发重新组合。配置事务期间收到的文件事件在事务结束后处理。 Include 刷新和 profile 重载都通过普通的 Loader 条目更新到达插件；仅 volatile 变化由 Loader 就地提交。
+`watchConfig()` 注册会被等待的配置处理器，仅监听目标路径及必要的父目录；同级文件（包括临时写锁）在创建原生 watcher 前即被排除。`runExclusive()` 将配置变更、Loader 更新与自动重载串行化，并拒绝嵌套事务。包安装和删除在该队列之外执行。HMR 不获取包操作写锁；manifest 通知仅在有序的 `dsh.profile.bundles` 列表变化时触发重载。profile 与 home patch 变化也会触发重新组合。配置事务期间收到的文件事件在事务结束后处理。 Include 刷新和 profile 重载都通过普通的 Loader 条目更新到达插件；仅 volatile 变化由 Loader 就地提交。
 
 App-boot 负责 profile 解析和 patch 优先级规则。HMR 读取启动器提供的纯数据 `profileContext`，在初始化时注册 profile manifest 和两份用户 patch 的监听，并等待应用就绪后处理更改。销毁 HMR 时会关闭监听器并取消等待启动的重载。配置监听器在当前事务上下文之外启动，使后续通知可以进入队列。
 
+`reconcileProfile()` 由 HMR 的 profile 监听和 Plugin Manager 共用；调用方持有 `runExclusive()`。Config Editor 通过 app-boot 重新组合，不替换模块。app-boot 在缓存或运行中条目发生变化前准备新一代组合并执行预检。
+
+文件比较覆盖 profile 目录及已链接包的目标，在应用就绪时记录。[ModuleFiles](src/module-files.ts) 记录 inode、大小和修改时间；仅添加硬链接不会使模块失效。已有模块保留替换前读取的身份，以检测之后的写入。新加载的模块在结算时记录，因此后续安装不会仅因其文件较新而将其重启。
+
+替换沿 ES 模块链接以及每个 CommonJS 父模块的 `children` 传播。模块的插件从其 ES 模块命名空间以及 Node 已缓存的 CommonJS exports 中读取，不求值任何代码，因此在 Loader entry 之外注册的 CommonJS 插件保留其缓存。宿主依赖及可遍历 Loader 树之外的插件保持待处理。其余已变化模块及其导入方被逐出且不保留备份，运行受影响插件的 Loader entry 被停止。HMR 本身不导入替换代码：新一代组合启动条目时，Loader 导入当前文件，因此停用、删除和不兼容的行永远不会执行替换代码，动态 `disabled` 表达式和嵌套 Include 按启动时的方式求值。
+
+受影响的运行时停止，但其条目不会被标记为停用；`reconcileProfile()` 把它们传给 app-boot 的单次 `recomposeProfile()` 调用，由该调用启动它们，包括未变化 Include 之下的条目和 profile 组合之外的条目，且不会重复导入同一条目。任何插件停止之前发生的失败会让所有插件继续运行；没有新一代组合被应用时，已停止的插件以当前 resolution 重新启动。逐出之后，导入或启动失败的替换版本属于激活失败，使操作失败；其旧代码不再运行。每次重新组合都会先让 profile 根目录下的包配置失效并逐出链接失败的模块，再次导入此前导入失败的条目，因此修正后的文件或之后安装的依赖无需重启即生效。[ProfileReconciliation](../../../docs/subsystems/boot.zh.md#profile-reconciliation) 列出需要重启的变化。在重新组合期间首次加载、且其文件在比较之后被写入的模块保持陈旧，因此激活期间的写入会在下一次加载；比较或缓存检查失败时，即使无法确定已变化的 URL，也要求重启。HMR 的监听记录这些结果。
+
+每次重新组合之后，HMR 逐出重新组合删除的映射所在目录之下的已加载模块，并使这些包的配置过期，因此已删除或取消选入的组合包连同其动态导入的依赖，在它再次出现时重新导入。组合包的包本身不是映射：其文件在磁盘上变化时被替换；关闭组合包而其文件未变化时，它的模块保持加载。runtime resolution 拒绝的发布（例如移动到其他目录的保留 profile 映射）会停止并重新启动新一代组合将删除的行，组合保持不变；结果带有 `restartReason: 'package-moved'`。
+
 `node_modules` 之外的 `package.json` 变化使该包的配置缓存失效。仅作为配置的 manifest 不触发模块重载；作为 JSON 模块导入的 manifest 保留依赖驱动重载，位于宿主依赖图中的 manifest 保留宿主重载。专属配置监听保留原有归属。新包入口在 Loader entry 重启时生效。
 
 Loader entry 保留原始导入结果。HMR 为每个 entry 名称与配置树 base URL 保留所有不同的已导入命名空间；尚未初始化的 entry 不会覆盖其他 entry 的命名空间。HMR 将这些对象与缓存中 ModuleJob 的模块命名空间按对象身份匹配，不再重新解析 entry 名称。没有已导入命名空间的名称和 `cordis:` 内置入口仍按名称解析。因此 `exports` 或 `main` 改变后，源码重载仍使用已加载模块。
@@ -94,7 +106,16 @@ Loader entry 保留原始导入结果。HMR 为每个 entry 名称与配置树 b
 <a id="known-limitations-and-deferred-work"></a>
 
 - 模块替换需要 Node loader 内部接口。框架依赖变化调用宿主提供的 `loader.exit()` 钩子；HMR 本身不重启进程。
-- 通过插件管理器替换已安装包版本仍需要重启；`node_modules` 之下的 manifest 保留 Node 缓存的配置。浏览器 Client 模块图保留独立的浏览器侧加载机制。
+- 仅限于 `package.json` 的变化不会被检测到。`node_modules` 之下 manifest 的监听通知仍被忽略。浏览器 Client 模块图保留独立的浏览器侧加载机制。
+- 替换沿静态导入传播。对陈旧模块的动态 `import()` 在下次调用时求值新文件，而其导入方继续运行；已存在的 Worker 和 TSX loader 线程保留各自的模块缓存。
+- profile 的 `node_modules` 之下的每个符号链接都会扩大比较范围。链接进程入口（通过 bin 链接的真实路径定位）静态导入的包（例如来自 dsh checkout 的 `dsh-app-boot`、Cordis 或 Loader）会把宿主模块纳入范围；这些模块的变化保持待处理，Plugin Manager 对后续操作报告 `restart-required`，直到进程重启。Loader entry 导入的已链接 dsh 包与其他插件一样被替换。
+- 比较记录属于单个 HMR 实例。重启 `hmr` 条目本身的重新组合会重新记录当前文件，因此此时待处理的变化不再被报告或重试。
+- 导入或启动失败的替换版本保持未激活，直到其文件或依赖被修正；旧版本不会被恢复。
+- 兼容性检查只在 DSH 组合行时运行：启动、profile 重新组合和 preset 挂载；Loader 导入模块时不做任何检查。被替换的 profile 行会通过重新组合的预检，但 profile 组合之外的行（例如 preset 行，或通过 `ctx.loader.create()` 添加的条目）以替换后的代码重启，不经检查。Plugin Manager 拒绝不兼容的版本，因此这只影响在它之外变化的包，例如在 profile 目录中手动执行 `pnpm add`，或重新构建的 `link:` 包。
+- [打包 worker loader](../../experimental/webworker-runtime/src/module-system/module-loader.ts) 不暴露 Node 的 `loadCache` 或 `require.cache`；配置重新组合仍可执行，但代码替换需要重启。原生 Node 即使使用异步模块 hook 也保留这些缓存。[打包 worker 浏览器测试](../../../apps/web/tests/preview-boot.e2e.ts) 覆盖此部署。
+- 新加载文件首次在重新组合结算后记录，其修改时间晚于比较时间时计为已变化。比较时间是 HMR 在临时目录中写入的标记文件的修改时间，因此在同一台机器上，两者都来自为本地文件写入记时的时钟；在比较之后、处于 profile 所在文件系统时间戳精度之内的修改被视为更早，可能被漏检；网络文件系统使用服务器的时钟为写入记时。
+- 若文件被替换为指向较旧 store 文件的硬链接，它保留较旧的修改时间；当其模块在上次记录之后才首次加载时，该变化不会被检测到。
+- HMR 自身监听触发的 profile 重新组合不会因仅涉及依赖的 manifest 变化而执行，因此在 Plugin Manager 之外执行的安装在下一次重新组合或重启时生效。
 - TSX loader 和普通应用自行创建的 Worker 不在包缓存刷新支持范围内。
 - CommonJS 请求必须能由 Node 默认 resolver 解析。同步 hook 可以像 Desktop 的 Office resolver 一样处理解析后的文件名；依赖原始请求名或引入虚拟请求的 hook 不受支持。内置模块保留 Node 原有的加载行为。
 - 后续工作：跨 HMR 销毁和替换保留包配置失效状态。恢复原生 reader 后，其旧配置缓存可能重新可见。

package/lib/index.js

@@ -5,11 +5,12 @@ import { basename, dirname, join, relative, resolve, sep, toNamespacedPath } fro
 import { realpath, stat } from "node:fs/promises";
 import { watch } from "chokidar";
 import { Inject, Service } from "@deepseek-ai/cordis";
-import { readFileSync, realpathSync } from "node:fs";
-import { PROFILE_PATCH_FILENAME, readProfileManifest, readProfilePatches, reconcileProfilePatches } from "@deepseek-ai/dsh-app-boot";
+import { existsSync, lstatSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { PROFILE_PATCH_FILENAME, readProfileManifest, readProfilePatches, recomposeProfile } from "@deepseek-ai/dsh-app-boot";
 import { codeFrameColumns } from "@babel/code-frame";
 import { isUtf8 } from "node:buffer";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { tmpdir } from "node:os";
 import picomatch from "picomatch";
 import z from "@deepseek-ai/schemastery";
 //#region lib/types/watch-config.js
@@ -35,7 +36,8 @@ async function findWatchRoot(filename) {
 	}
 }
 /**
-* Watch one patch path, including missing parents, and serialize refresh callbacks.
+* Watch one patch path and its parent chain without subscribing to sibling files or directories.
+* Missing parents are observed as they appear; refresh callbacks run serially.
 * @param ctx Context that owns watcher disposal and receives refresh failures.
 * @param filename Absolute patch-file path.
 * @param options Deployment watcher options; configuration watches enable write stabilization by default.
@@ -54,7 +56,11 @@ async function watchConfig(ctx, filename, options, refresh, inTransaction = () =
 		awaitWriteFinish: true,
 		...watchOptions,
 		depth: target.depth,
-		ignoreInitial: false
+		ignoreInitial: false,
+		ignored: (path) => {
+			const remainder = relative(resolve(path), target.filename);
+			return remainder === ".." || remainder.startsWith(`..${sep}`);
+		}
 	});
 	paths.add(target.filename);
 	const state = { dirty: false };
@@ -392,6 +398,112 @@ var PackageManifests = class {
 	}
 };
 //#endregion
+//#region lib/types/module-files.js
+/** Disk identities of loaded module files, used to find modules whose files changed after loading. */
+/**
+* Coarsest file timestamp resolution among supported filesystems (FAT stores modification times in 2-second units).
+* An unrecorded file modified within this interval before the last observation is treated as possibly changed.
+*/
+const TIMESTAMP_RESOLUTION_MS = 2e3;
+function identityOf(url) {
+	let stats;
+	try {
+		stats = statSync(fileURLToPath(url));
+	} catch (_error) {
+		return;
+	}
+	return {
+		key: `${String(stats.ino)}:${String(stats.size)}:${String(stats.mtimeMs)}`,
+		modifiedAt: stats.mtimeMs
+	};
+}
+/**
+* Records the inode, size and modification time of loaded `file:` modules. A module is stale when its file
+* disappeared or its identity differs from the recorded one. Change time is not recorded: creating a hard link to a
+* file, as pnpm does when it imports from its store, changes it without changing content. A module first loaded after
+* the last observation has no record; it is stale when its file was modified at or after that observation, less the
+* timestamp resolution, so a reinstall between loading and the next comparison is detected at the cost of reloading a
+* module that was first loaded after such a write.
+*/
+var ModuleFiles = class {
+	/** Identity per recorded module; `undefined` marks a stale module, such as a pending one first loaded after the last observation. */
+	records = /* @__PURE__ */ new Map();
+	observedAt = Date.now();
+	/**
+	* The current time of the clock the operating system stamps local file writes with, read from a new marker file that is
+	* removed again. The system clock and file timestamps can differ by a clock tick in either direction, so module files
+	* are compared with this time; when no marker can be created, the system clock is used.
+	* @returns Epoch milliseconds.
+	*/
+	now() {
+		let directory;
+		try {
+			directory = mkdtempSync(join(tmpdir(), "dsh-hmr-clock-"));
+		} catch (_error) {
+			return Date.now();
+		}
+		try {
+			const marker = join(directory, "now");
+			writeFileSync(marker, "");
+			return statSync(marker).mtimeMs;
+		} finally {
+			rmSync(directory, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	/**
+	* Compare loaded file modules with disk.
+	* @param urls `file:` URLs of the loaded modules to compare.
+	* @returns URLs of stale modules, and the identity read for each compared URL (`undefined` for a missing file).
+	*/
+	compare(urls) {
+		const stale = /* @__PURE__ */ new Set();
+		const seen = /* @__PURE__ */ new Map();
+		for (const url of urls) {
+			const identity = identityOf(url);
+			seen.set(url, identity?.key);
+			if (identity === void 0) {
+				stale.add(url);
+				continue;
+			}
+			if (this.records.has(url) ? this.records.get(url) !== identity.key : identity.modifiedAt >= this.observedAt - TIMESTAMP_RESOLUTION_MS) stale.add(url);
+		}
+		return {
+			stale,
+			seen
+		};
+	}
+	/**
+	* Replace every record with the identities of the given loaded modules.
+	* @param urls `file:` URLs of the loaded modules to record.
+	* @param options `seen` supplies identities read earlier for modules whose cache entry has not changed since, so a
+	* later write stays detectable; other modules are read now, and stay stale when their file was modified after `at`.
+	* `retained` modules keep their record, or are marked stale when they have none. `at` is the observation time from
+	* {@link now} used for unrecorded modules.
+	*/
+	observe(urls, options = {}) {
+		const { seen = /* @__PURE__ */ new Map(), retained = /* @__PURE__ */ new Set(), at = this.now() } = options;
+		const records = /* @__PURE__ */ new Map();
+		for (const url of urls) if (retained.has(url)) records.set(url, this.records.get(url));
+		else if (seen.has(url)) records.set(url, seen.get(url));
+		else {
+			const identity = identityOf(url);
+			records.set(url, identity === void 0 || identity.modifiedAt > at ? void 0 : identity.key);
+		}
+		this.records = records;
+		this.observedAt = at;
+	}
+	/**
+	* Record the current identity of modules just evaluated again, leaving every other record unchanged.
+	* @param urls `file:` URLs of the re-evaluated modules.
+	*/
+	refresh(urls) {
+		for (const url of urls) this.records.set(url, identityOf(url)?.key);
+	}
+};
+//#endregion
 //#region lib/types/index.js
 /** Serialized module and profile-configuration reloads. */
 var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
@@ -444,16 +556,16 @@ function canonicalPath(filename) {
 }
 /**
 * Recursively collect all module dependencies from a ModuleJob.
-* Skips node: builtins and node_modules to focus on user code.
+* Skips node: builtins, and node_modules unless `includeNodeModules` is set, to focus on user code.
 */
-async function loadDependencies(job, ignored = /* @__PURE__ */ new Set()) {
+async function loadDependencies(job, ignored = /* @__PURE__ */ new Set(), includeNodeModules = false) {
 	const dependencies = /* @__PURE__ */ new Set();
 	async function traverse(job) {
 		if (ignored.has(job.url) || dependencies.has(job.url)) return;
-		if (job.url.startsWith("node:") || job.url.includes("/node_modules/")) return;
+		if (job.url.startsWith("node:") || !includeNodeModules && job.url.includes("/node_modules/")) return;
 		dependencies.add(job.url);
-		const children = await job.linked;
-		await Promise.all(Array.prototype.map.call(children, traverse));
+		const children = await linkedJobs(job);
+		await Promise.all(children.map(traverse));
 	}
 	await traverse(job);
 	return dependencies;
@@ -626,6 +738,9 @@ let Hmr = (() => {
 		closing = false;
 		configPaths = /* @__PURE__ */ new Set();
 		manifests = new PackageManifests();
+		files = new ModuleFiles();
+		/** Every module statically reachable from the process entry point, including those under node_modules; collected on first use. */
+		hostModules;
 		/** Serialize a caller-owned mutation with all automatic reload paths.
 		* @param operation Work that must not overlap module or configuration replacement.
 		* @returns The operation result after its asynchronous work completes.
@@ -672,7 +787,40 @@ let Hmr = (() => {
 			this.internal = this.ctx.loader.internal;
 			this.baseDir = fileURLToPath(new URL(config.base || ".", ctx.baseUrl));
 		}
+		/**
+		* The cached ES module job for a URL. The packed worker loader exposes no Node module cache; native Node
+		* retains this cache even when asynchronous module hooks run in a separate thread.
+		*/
+		esmJob(url) {
+			return this.hasEsmCache() ? this.internal.loadCache.get(url) : void 0;
+		}
+		/** Whether this thread keeps a Node ES module cache; the packed worker loader keeps none. */
+		hasEsmCache() {
+			return Reflect.get(this.internal, "loadCache") !== void 0;
+		}
+		/** Whether the ES module cache holds a job for a URL; `false` when this thread keeps no ES module cache. */
+		esmHas(url, type) {
+			return this.hasEsmCache() && (type === void 0 ? this.internal.loadCache.has(url) : this.internal.loadCache.has(url, type));
+		}
+		/** ES module cache keys, empty when this thread keeps no ES module cache. */
+		esmUrls() {
+			return this.hasEsmCache() ? [...Map.prototype.keys.call(this.internal.loadCache)] : [];
+		}
+		/** ES module cache keys and CommonJS cache filenames as URLs. */
+		*loadedUrls() {
+			yield* this.esmUrls();
+			for (const filename of Object.keys(commonJsCache())) yield pathToFileURL(filename).href;
+		}
+		/** The module job of the process entry point, when the loader cached it under the entry's real path. */
+		mainJob() {
+			const entry = process.argv[1];
+			if (entry === void 0) return void 0;
+			return this.esmJob(pathToFileURL(canonicalPath(resolve(entry))).href);
+		}
 		async *[Service.init]() {
+			const mainJob = this.mainJob();
+			let host;
+			this.hostModules = () => host ??= mainJob === void 0 ? Promise.resolve(/* @__PURE__ */ new Set()) : loadDependencies(mainJob, /* @__PURE__ */ new Set(), true);
 			yield async () => {
 				this.closing = true;
 				await this.watcher?.close();
@@ -686,6 +834,11 @@ let Hmr = (() => {
 				const started = Promise.withResolvers();
 				this.applicationReady = started.promise;
 				const unsubscribe = ready.onReady(() => {
+					try {
+						this.files.observe(this.profileModules(profileRoots(profile.dir)));
+					} catch (error) {
+						this.ctx.logger.warn(error);
+					}
 					started.resolve(true);
 				});
 				yield () => {
@@ -709,8 +862,9 @@ let Hmr = (() => {
 						}
 					})]);
 					if (inputs === lastInputs) return;
-					const patches = readProfilePatches("dsh", profile);
-					const warnings = await reconcileProfilePatches(this.ownerContext.root, patches, "dsh");
+					const { warnings, pending, restartReason } = await this.reconcileProfile();
+					if (restartReason !== void 0) this.ctx.logger.warn("restart required: %s", restartReason);
+					if (pending.length > 0) this.ctx.logger.warn("changed modules keep running their previous code until a restart: %o", pending);
 					lastInputs = inputs;
 					lastBundles = bundles;
 					for (const diagnostic of warnings) this.ctx.logger.warn(diagnostic);
@@ -724,7 +878,6 @@ let Hmr = (() => {
 			else this.ctx.logger.info("watching %o in %s", root, this.baseDir);
 			const match = picomatch(ignored);
 			const watchBaseDir = realpathSync(this.baseDir);
-			const mainJob = process.argv[1] === void 0 ? void 0 : this.internal.loadCache.get(pathToFileURL(resolve(process.argv[1])).href);
 			if (mainJob) this.externals = await loadDependencies(mainJob);
 			else this.externals = /* @__PURE__ */ new Set();
 			this.watcher = watch(root, {
@@ -752,7 +905,7 @@ let Hmr = (() => {
 							fullReload = true;
 							continue;
 						}
-						if (this.internal.loadCache.has(url) || this.internal.loadCache.has(url, "json")) {
+						if (this.esmHas(url) || this.esmHas(url, "json")) {
 							this.stashed.add(url);
 							continue;
 						}
@@ -805,7 +958,7 @@ let Hmr = (() => {
 		* @returns Linked module URLs, or an empty list for an uncached module.
 		*/
 		async getLinked(url) {
-			const job = this.internal.loadCache.get(url);
+			const job = this.esmJob(url);
 			if (!job) return [];
 			const linked = await job.linked;
 			return Array.prototype.map.call(linked, (job) => job.url);
@@ -875,7 +1028,7 @@ let Hmr = (() => {
 			for (const [baseUrl, names] of nameMap) for (const [name, moduleNamespace] of names) try {
 				const { url } = await names.resolve(name, baseUrl, moduleNamespace);
 				if (this.declined.has(url)) continue;
-				const job = this.internal.loadCache.get(url);
+				const job = this.esmJob(url);
 				const plugin = this.ctx.loader.unwrapExports(job?.module?.getNamespace());
 				if (!job || !plugin) continue;
 				pending.set(job, plugin);
@@ -902,41 +1055,7 @@ let Hmr = (() => {
 				});
 			}
 			for (const [job, plugin] of pending) if (ReloadModules.include(reloads, plugin, job, this.ctx.registry.get(plugin))) this.accepted.add(job.url);
-			/**
-			* Clear module caches for all accepted files before re-importing.
-			*
-			* We need to clear both:
-			* 1. ESM loadCache — managed by Node's internal ModuleLoader
-			* 2. CJS Module._cache — for CJS modules that were imported via import()
-			*
-			* In Node 24, CJS modules loaded via import() appear in both caches.
-			* If we only clear loadCache, the CJS cache may serve stale modules.
-			*
-			* We use Map.prototype methods directly on loadCache because:
-			* - In Node 22/23, loadCache is a plain Map<url, ModuleJob>
-			* - In Node 24, loadCache is a LoadCache extends Map<url, { [type]: ModuleJob }>
-			*   where .delete() only sets the type slot to undefined (doesn't remove the entry)
-			* Using Map.prototype.delete ensures complete removal in both versions.
-			*/
-			const esmBackup = /* @__PURE__ */ new Map();
-			const cjsBackup = /* @__PURE__ */ new Map();
-			const require = createRequire(import.meta.url);
-			for (const filename of this.accepted) {
-				const job = Map.prototype.get.call(this.internal.loadCache, filename);
-				esmBackup.set(filename, job);
-				Map.prototype.delete.call(this.internal.loadCache, filename);
-				try {
-					const filepath = fileURLToPath(filename);
-					if (require.cache[filepath]) {
-						cjsBackup.set(filepath, require.cache[filepath]);
-						Reflect.deleteProperty(require.cache, filepath);
-					}
-				} catch {}
-			}
-			const rollback = () => {
-				for (const [filename, job] of esmBackup) Map.prototype.set.call(this.internal.loadCache, filename, job);
-				for (const [filepath, module] of cjsBackup) require.cache[filepath] = module;
-			};
+			const rollback = this.evict(this.accepted);
 			const generations = [...reloads].map(([previous, info]) => ({
 				...info,
 				previous,
@@ -1025,13 +1144,322 @@ let Hmr = (() => {
 			await this.ctx.loader.await();
 			for (const { replacements } of attempts) replacements.updateEntries(this.ctx.loader);
 			this.ctx.emit("hmr/reload", reloads);
+			this.files.refresh(this.accepted);
 			this.stashed = /* @__PURE__ */ new Set();
 		}
+		/**
+		* Remove modules from the ES module and CommonJS caches so the next import evaluates their files again.
+		*
+		* CommonJS modules loaded through `import()` appear in both caches. Node's `LoadCache` maps each URL to per-type
+		* jobs, and its own `delete()` only clears one type slot, so whole entries are removed through `Map.prototype`.
+		* @returns Restores the removed cache entries.
+		*/
+		evict(urls) {
+			const esmBackup = /* @__PURE__ */ new Map();
+			const cjsBackup = /* @__PURE__ */ new Map();
+			const cache = commonJsCache();
+			const list = [...urls];
+			const cached = new Set(this.esmUrls());
+			for (const url of list) if (cached.has(url)) {
+				esmBackup.set(url, Map.prototype.get.call(this.internal.loadCache, url));
+				Map.prototype.delete.call(this.internal.loadCache, url);
+			}
+			for (const filepath of list.filter((url) => url.startsWith("file:")).map((url) => fileURLToPath(url))) {
+				const module = cache[filepath];
+				if (module !== void 0) {
+					cjsBackup.set(filepath, module);
+					Reflect.deleteProperty(cache, filepath);
+				}
+			}
+			return () => {
+				for (const [url, job] of esmBackup) Map.prototype.set.call(this.internal.loadCache, url, job);
+				for (const [filepath, module] of cjsBackup) cache[filepath] = module;
+			};
+		}
+		/** Loaded `file:` modules below the given profile roots. */
+		profileModules(roots) {
+			return [...this.loadedUrls()].filter((url) => {
+				if (!url.startsWith("file:")) return false;
+				const filename = fileURLToPath(url);
+				return roots.some((root) => filename.startsWith(root));
+			});
+		}
+		/** Static import edges between loaded modules, across ES module links and CommonJS `require` children. */
+		async moduleGraph() {
+			const importers = /* @__PURE__ */ new Map();
+			const add = (parent, child) => {
+				importers.set(child, (importers.get(child) ?? /* @__PURE__ */ new Set()).add(parent));
+			};
+			await Promise.all([...moduleJobs(this.internal)].map(async (job) => {
+				for (const child of await linkedJobs(job)) add(job.url, child.url);
+			}));
+			for (const [filename, module] of Object.entries(commonJsCache())) {
+				/* v8 ignore next -- Node stores no undefined values in require.cache; the index type admits them */
+				const children = module === void 0 ? void 0 : Reflect.get(module, "children");
+				if (!Array.isArray(children)) continue;
+				for (const child of children) add(pathToFileURL(filename).href, pathToFileURL(child.filename).href);
+			}
+			return importers;
+		}
+		/**
+		* Plan the replacement of changed modules without changing anything. A changed module whose importers reach the
+		* process entry point's static graph, or a plugin that no affected Loader entry starts, stays loaded with its
+		* importers and is pending. The other changed modules and every module importing them are evicted by
+		* {@link stopPlanned}, which also expires the manifests from each changed file up to its root and stops the Loader
+		* entries running affected plugins.
+		* @param stale Changed module URLs.
+		* @param roots Directories, with a trailing separator, that bound the expired manifests.
+		* @returns The pending modules and the replacement of the others.
+		*/
+		async planReplacement(stale, roots) {
+			const importers = await this.moduleGraph();
+			const host = await this.hostModules();
+			const managed = new Set(this.ctx.loader.entries());
+			const plan = {
+				pending: [],
+				evicted: /* @__PURE__ */ new Set(),
+				manifests: /* @__PURE__ */ new Set(),
+				plugins: /* @__PURE__ */ new Set(),
+				fibers: /* @__PURE__ */ new Set()
+			};
+			for (const url of stale) {
+				const affected = new Set([url]);
+				for (const module of affected) for (const importer of importers.get(module) ?? []) affected.add(importer);
+				const running = [...new Set([...affected].flatMap((module) => this.pluginsOf(module)))].flatMap((plugin) => [...this.ctx.registry.get(plugin)?.fibers ?? []].map((fiber) => ({
+					plugin,
+					fiber
+				})));
+				const affectedFibers = new Set(running.map(({ fiber }) => fiber));
+				/** The Loader entry whose own fiber runs an affected plugin and starts this fiber directly or through its ancestors. */
+				const owner = (fiber) => {
+					for (let current = fiber; current.uid !== 0; current = current.parent.fiber) {
+						const entry = current.entry;
+						if (entry?.fiber === current && managed.has(entry) && affectedFibers.has(current)) return entry;
+					}
+				};
+				const entries = running.flatMap(({ fiber }) => owner(fiber) ?? []);
+				const reason = [...affected].some((module) => host.has(module)) ? "host-module" : entries.length < running.length ? "unmanaged-plugin" : void 0;
+				if (reason !== void 0) {
+					plan.pending.push({
+						url,
+						reason
+					});
+					continue;
+				}
+				for (const manifest of packageManifests(url, roots)) plan.manifests.add(manifest);
+				for (const module of affected) plan.evicted.add(module);
+				for (const { plugin, fiber } of running) {
+					plan.plugins.add(plugin);
+					plan.fibers.add(fiber);
+				}
+			}
+			return plan;
+		}
+		/**
+		* The plugins a loaded module exports, read from the ES module namespace and the CommonJS exports Node cached for it
+		* without evaluating anything.
+		* @param url Loaded module URL.
+		* @returns The exported plugins.
+		*/
+		pluginsOf(url) {
+			const namespace = namespaceOf(this.esmJob(url));
+			const required = url.startsWith("file:") ? commonJsCache()[fileURLToPath(url)] : void 0;
+			return [namespace, required?.loaded === true ? required.exports : void 0].filter((value) => value !== void 0).map((value) => this.ctx.loader.unwrapExports(value));
+		}
+		/**
+		* Carry out a planned replacement: expire its manifests, evict its modules without a backup, and stop its Loader
+		* entries, so applying the generation imports the current files when it starts them.
+		* @param plan The planned replacement.
+		*/
+		async stopPlanned(plan) {
+			for (const manifest of plan.manifests) this.manifests.invalidate(manifest);
+			this.evict(plan.evicted);
+			for (const plugin of plan.plugins) this.ctx.registry.delete(plugin);
+			await Promise.allSettled([...plan.fibers].map((fiber) => fiber.await()));
+		}
+		/**
+		* Evict the loaded modules below the directories of mappings a recomposition dropped and expire their package
+		* configuration, so a disabled or removed package that is installed or enabled again is imported afresh. Modules of
+		* DSH's own static graph, and those below a directory that is still mapped, stay loaded.
+		* @param dropped Real directories, with a trailing separator, of the dropped mappings.
+		* @param kept Real directories, with a trailing separator, of the mappings that stay.
+		*/
+		async evictDropped(dropped, kept) {
+			if (dropped.length === 0) return;
+			const host = new Set(await this.hostModules());
+			const urls = this.profileModules(dropped).filter((url) => {
+				const filename = fileURLToPath(url);
+				return !host.has(url) && ![...kept].some((dir) => filename.startsWith(dir));
+			});
+			for (const url of urls) for (const manifest of packageManifests(url, dropped)) this.manifests.invalidate(manifest);
+			this.evict(urls);
+		}
+		/** Report a failed replacement step and retain the caller’s fallback outcome. */
+		async contained(step, operation, fallback) {
+			try {
+				return await operation();
+			} catch (error) {
+				this.ctx.logger.warn("%s failed; module replacement was not completed", step);
+				this.ctx.logger.warn(error);
+				return fallback;
+			}
+		}
+		/**
+		* Recompose the profile from its manifest and patch files, replacing running plugins whose loaded files below the
+		* profile directory or its linked package targets changed on disk, and publishing its runtime resolution. Changed
+		* modules are evicted and the Loader entries running them stop; app-boot's {@link recomposeProfile} then publishes the
+		* resolution, applies the generation, starts the stopped entries with the current files and configuration,
+		* imports entries whose import failed again, and judges activation. Afterwards the modules below the mappings the
+		* recomposition dropped are evicted, so a removed or deselected package is imported afresh when it returns. Callers run
+		* inside {@link runExclusive}.
+		* @param requiredIds Entry ids whose inactive state is reported as a failure even when it predates this call.
+		* @returns Inactive-entry diagnostics, the changed modules that load after a restart, and a profile-wide restart reason.
+		* @throws The patch read, publication, preparation, apply, or activation failure of the recomposition, including a
+		* replacement plugin that fails to load or start, whose previous code no longer runs.
+		*/
+		async reconcileProfile(requiredIds = []) {
+			if (this.executing.getStore() !== true) throw new Error("HMR profile reconciliation must run inside runExclusive");
+			const profile = this.ownerContext.get("profileContext");
+			if (profile === void 0) throw new Error("HMR profile reconciliation requires profileContext");
+			const running = [...this.ctx.loader.entries()].filter((entry) => entry.fiber?.state === 2);
+			const mapped = mappedDirectories(this.ownerContext.get("pluginPackages")?.resolution);
+			let comparison;
+			let comparedAt = 0;
+			let pending = [];
+			try {
+				const patches = readProfilePatches("dsh", profile);
+				comparedAt = this.files.now();
+				comparison = await this.contained("comparing loaded modules with disk", () => {
+					const roots = profileRoots(profile.dir);
+					return Promise.resolve({
+						roots,
+						...this.files.compare(this.profileModules(roots))
+					});
+				}, void 0);
+				pending = [...comparison?.stale ?? []].map((url) => ({
+					url,
+					reason: "module-comparison"
+				}));
+				const compared = comparison;
+				const unavailable = !this.hasEsmCache();
+				if (!unavailable && compared !== void 0 && pending.length > 0) pending = await this.contained("planning module replacement", async () => {
+					const plan = await this.planReplacement(compared.stale, compared.roots);
+					await this.stopPlanned(plan);
+					return plan.pending;
+				}, pending);
+				await this.contained("expiring failed imports", () => {
+					if (unavailable) return;
+					const roots = compared?.roots ?? [realpathSync(profile.dir) + sep];
+					for (const root of roots) this.manifests.invalidate(join(root, "package.json"));
+					this.evict(this.profileModules(roots).filter((url) => {
+						const job = this.esmJob(url);
+						return job !== void 0 && namespaceOf(job) === void 0;
+					}));
+				}, void 0);
+				const result = await recomposeProfile(this.ownerContext.root, patches, "dsh", {
+					requiredIds,
+					running
+				});
+				const restartReason = compared === void 0 || unavailable ? "module-comparison" : result.restartReason;
+				return {
+					warnings: result.warnings,
+					pending,
+					...restartReason === void 0 ? {} : { restartReason }
+				};
+			} finally {
+				const recorded = comparison;
+				await this.contained("evicting dropped packages", () => {
+					const kept = mappedDirectories(this.ownerContext.get("pluginPackages")?.resolution);
+					return this.evictDropped([...mapped].filter((dir) => !kept.has(dir)), kept);
+				}, void 0);
+				await this.contained("recording loaded module files", () => {
+					if (recorded === void 0) return;
+					const urls = this.profileModules(recorded.roots);
+					this.files.observe(urls, {
+						seen: recorded.seen,
+						retained: new Set(pending.map(({ url }) => url)),
+						at: comparedAt
+					});
+				}, void 0);
+			}
+		}
 		static {
 			__runInitializers(_classThis, _classExtraInitializers);
 		}
 	};
 	return _classThis;
 })();
+/** Node's `kErrored` module status, the same in every supported Node version. */
+const MODULE_ERRORED = 5;
+/** The namespace of a cached module job, or `undefined` when it has none or its evaluation threw. */
+function namespaceOf(job) {
+	if (job?.module === void 0) return void 0;
+	if (Reflect.apply(Reflect.get(job.module, "getStatus"), job.module, []) === MODULE_ERRORED) return void 0;
+	try {
+		return job.module.getNamespace();
+	} catch (_error) {
+		return;
+	}
+	/* v8 ignore stop */
+}
+/**
+* The jobs a module job links to. Node 24+ may expose them as an array; Node 22 keeps the job of a failed import
+* whose links reject, and such a job contributes no links.
+*/
+async function linkedJobs(job) {
+	/* v8 ignore next -- CI coverage runs Node 24+, which drops failed jobs from the cache */
+	const linked = await Promise.resolve(job.linked).catch((_error) => []);
+	return Array.from(linked);
+}
+/** The Node-compatible CommonJS cache; the packed worker implements require without exposing this cache. */
+function commonJsCache() {
+	return Reflect.get(createRequire(import.meta.url), "cache") ?? {};
+}
+/** Every module job in the loader cache; Node's `LoadCache` maps each URL to per-type jobs. */
+function* moduleJobs(internal) {
+	for (const value of Map.prototype.values.call(internal.loadCache)) yield* Object.values(value).filter((job) => job !== void 0);
+}
+/**
+* The directories of a runtime resolution's profile mappings and linked roots, in every real spelling of those that
+* exist, each with a trailing separator.
+* @param resolution The published resolution, if any.
+* @returns The directories; none without a resolution.
+*/
+function mappedDirectories(resolution) {
+	const directories = /* @__PURE__ */ new Set();
+	if (resolution === void 0) return directories;
+	const dirs = [...resolution.entries.filter((entry) => entry.scope === "profile").map((entry) => entry.packageDir), ...resolution.linkedRoots.map((root) => root.realPath)];
+	for (const dir of dirs) for (const spelling of existsSync(dir) ? realSpellings(dir) : [dir]) directories.add(spelling + sep);
+	return directories;
+}
+/**
+* The JavaScript and native real paths of an existing path. A packed worker's file system has no native realpath.
+* @param path Existing path.
+* @returns The distinct spellings.
+*/
+function realSpellings(path) {
+	const native = Reflect.get(realpathSync, "native");
+	return [realpathSync(path), ...typeof native === "function" ? [String(Reflect.apply(native, realpathSync, [path]))] : []];
+}
+/**
+* Real directories, with a trailing separator, of the profile and of the targets its linked packages point to. Each
+* appears in both real-path spellings: Node's module caches use the JavaScript one, the runtime resolution the native
+* one, and on Windows they differ for 8.3 short names.
+*/
+function profileRoots(dir) {
+	const modules = join(realpathSync(dir), "node_modules");
+	const linked = (existsSync(modules) ? readdirSync(modules) : []).flatMap((name) => name.startsWith("@") ? readdirSync(join(modules, name)).map((child) => join(modules, name, child)) : [join(modules, name)]).filter((path) => lstatSync(path).isSymbolicLink() && existsSync(path));
+	return [...new Set([dir, ...linked].flatMap((path) => realSpellings(path)).map((root) => root + sep))];
+}
+/** Every `package.json` from a module file's directory up to the profile root or linked package target containing it. */
+function packageManifests(url, roots) {
+	const manifests = [];
+	const contains = (directory) => roots.some((root) => (directory + sep).startsWith(root));
+	for (let directory = dirname(fileURLToPath(url)); contains(directory); directory = dirname(directory)) {
+		const candidate = join(directory, "package.json");
+		if (existsSync(candidate)) manifests.push(candidate);
+	}
+	return manifests;
+}
 //#endregion
 export { Hmr as default };

package/lib/types/index.d.ts

@@ -91,6 +91,9 @@ declare class Hmr extends Service {
     private closing;
     private readonly configPaths;
     private readonly manifests;
+    private readonly files;
+    /** Every module statically reachable from the process entry point, including those under node_modules; collected on first use. */
+    private hostModules;
     /** Serialize a caller-owned mutation with all automatic reload paths.
      * @param operation Work that must not overlap module or configuration replacement.
      * @returns The operation result after its asynchronous work completes.
@@ -104,6 +107,21 @@ declare class Hmr extends Service {
      */
     watchConfig(filename: string, refresh: () => Promise<void>): Promise<() => Promise<void>>;
     constructor(ctx: Context, config: HmrConfig);
+    /**
+     * The cached ES module job for a URL. The packed worker loader exposes no Node module cache; native Node
+     * retains this cache even when asynchronous module hooks run in a separate thread.
+     */
+    private esmJob;
+    /** Whether this thread keeps a Node ES module cache; the packed worker loader keeps none. */
+    private hasEsmCache;
+    /** Whether the ES module cache holds a job for a URL; `false` when this thread keeps no ES module cache. */
+    private esmHas;
+    /** ES module cache keys, empty when this thread keeps no ES module cache. */
+    private esmUrls;
+    /** ES module cache keys and CommonJS cache filenames as URLs. */
+    private loadedUrls;
+    /** The module job of the process entry point, when the loader cached it under the entry's real path. */
+    private mainJob;
     [Service.init](): AsyncGenerator<() => Promise<void>, void, unknown>;
     /** Omit internal HMR frames from module import diagnostics.
      * @returns The preserved outer stack frames.
@@ -123,6 +141,87 @@ declare class Hmr extends Service {
      */
     private analyzeChanges;
     private partialReload;
+    /**
+     * Remove modules from the ES module and CommonJS caches so the next import evaluates their files again.
+     *
+     * CommonJS modules loaded through `import()` appear in both caches. Node's `LoadCache` maps each URL to per-type
+     * jobs, and its own `delete()` only clears one type slot, so whole entries are removed through `Map.prototype`.
+     * @returns Restores the removed cache entries.
+     */
+    private evict;
+    /** Loaded `file:` modules below the given profile roots. */
+    private profileModules;
+    /** Static import edges between loaded modules, across ES module links and CommonJS `require` children. */
+    private moduleGraph;
+    /**
+     * Plan the replacement of changed modules without changing anything. A changed module whose importers reach the
+     * process entry point's static graph, or a plugin that no affected Loader entry starts, stays loaded with its
+     * importers and is pending. The other changed modules and every module importing them are evicted by
+     * {@link stopPlanned}, which also expires the manifests from each changed file up to its root and stops the Loader
+     * entries running affected plugins.
+     * @param stale Changed module URLs.
+     * @param roots Directories, with a trailing separator, that bound the expired manifests.
+     * @returns The pending modules and the replacement of the others.
+     */
+    private planReplacement;
+    /**
+     * The plugins a loaded module exports, read from the ES module namespace and the CommonJS exports Node cached for it
+     * without evaluating anything.
+     * @param url Loaded module URL.
+     * @returns The exported plugins.
+     */
+    private pluginsOf;
+    /**
+     * Carry out a planned replacement: expire its manifests, evict its modules without a backup, and stop its Loader
+     * entries, so applying the generation imports the current files when it starts them.
+     * @param plan The planned replacement.
+     */
+    private stopPlanned;
+    /**
+     * Evict the loaded modules below the directories of mappings a recomposition dropped and expire their package
+     * configuration, so a disabled or removed package that is installed or enabled again is imported afresh. Modules of
+     * DSH's own static graph, and those below a directory that is still mapped, stay loaded.
+     * @param dropped Real directories, with a trailing separator, of the dropped mappings.
+     * @param kept Real directories, with a trailing separator, of the mappings that stay.
+     */
+    private evictDropped;
+    /** Report a failed replacement step and retain the caller’s fallback outcome. */
+    private contained;
+    /**
+     * Recompose the profile from its manifest and patch files, replacing running plugins whose loaded files below the
+     * profile directory or its linked package targets changed on disk, and publishing its runtime resolution. Changed
+     * modules are evicted and the Loader entries running them stop; app-boot's {@link recomposeProfile} then publishes the
+     * resolution, applies the generation, starts the stopped entries with the current files and configuration,
+     * imports entries whose import failed again, and judges activation. Afterwards the modules below the mappings the
+     * recomposition dropped are evicted, so a removed or deselected package is imported afresh when it returns. Callers run
+     * inside {@link runExclusive}.
+     * @param requiredIds Entry ids whose inactive state is reported as a failure even when it predates this call.
+     * @returns Inactive-entry diagnostics, the changed modules that load after a restart, and a profile-wide restart reason.
+     * @throws The patch read, publication, preparation, apply, or activation failure of the recomposition, including a
+     * replacement plugin that fails to load or start, whose previous code no longer runs.
+     */
+    reconcileProfile(requiredIds?: readonly string[]): Promise<ProfileReconciliation>;
+}
+/** Outcome of {@link Hmr.reconcileProfile}. */
+export interface ProfileReconciliation {
+    /** Diagnostics for Loader entries left inactive. */
+    warnings: string[];
+    /** Loaded modules whose files changed on disk and whose previous code keeps running until a restart. */
+    pending: PendingModule[];
+    /**
+     * Why every change waits for a restart: `module-comparison` when module caches cannot be inspected or their files
+     * compared, even when no URLs are known; `package-moved` when the runtime resolution cannot publish a moved package.
+     */
+    restartReason?: 'module-comparison' | 'package-moved';
+}
+/** A changed module that loads only after a restart. */
+export interface PendingModule {
+    url: string;
+    /**
+     * `host-module`: the process entry point's static graph imports it. `unmanaged-plugin`: it is imported by a plugin
+     * that runs outside a traversable Loader entry. `module-comparison`: loaded modules could not be compared with disk.
+     */
+    reason: 'host-module' | 'unmanaged-plugin' | 'module-comparison';
 }
 declare namespace Hmr {
     /** Cordis-compatible configuration type. */

package/lib/types/module-files.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Records the inode, size and modification time of loaded `file:` modules. A module is stale when its file
+ * disappeared or its identity differs from the recorded one. Change time is not recorded: creating a hard link to a
+ * file, as pnpm does when it imports from its store, changes it without changing content. A module first loaded after
+ * the last observation has no record; it is stale when its file was modified at or after that observation, less the
+ * timestamp resolution, so a reinstall between loading and the next comparison is detected at the cost of reloading a
+ * module that was first loaded after such a write.
+ */
+export declare class ModuleFiles {
+    /** Identity per recorded module; `undefined` marks a stale module, such as a pending one first loaded after the last observation. */
+    private records;
+    private observedAt;
+    /**
+     * The current time of the clock the operating system stamps local file writes with, read from a new marker file that is
+     * removed again. The system clock and file timestamps can differ by a clock tick in either direction, so module files
+     * are compared with this time; when no marker can be created, the system clock is used.
+     * @returns Epoch milliseconds.
+     */
+    now(): number;
+    /**
+     * Compare loaded file modules with disk.
+     * @param urls `file:` URLs of the loaded modules to compare.
+     * @returns URLs of stale modules, and the identity read for each compared URL (`undefined` for a missing file).
+     */
+    compare(urls: Iterable<string>): {
+        stale: Set<string>;
+        seen: Map<string, string | undefined>;
+    };
+    /**
+     * Replace every record with the identities of the given loaded modules.
+     * @param urls `file:` URLs of the loaded modules to record.
+     * @param options `seen` supplies identities read earlier for modules whose cache entry has not changed since, so a
+     * later write stays detectable; other modules are read now, and stay stale when their file was modified after `at`.
+     * `retained` modules keep their record, or are marked stale when they have none. `at` is the observation time from
+     * {@link now} used for unrecorded modules.
+     */
+    observe(urls: Iterable<string>, options?: {
+        seen?: ReadonlyMap<string, string | undefined>;
+        retained?: ReadonlySet<string>;
+        at?: number;
+    }): void;
+    /**
+     * Record the current identity of modules just evaluated again, leaving every other record unchanged.
+     * @param urls `file:` URLs of the re-evaluated modules.
+     */
+    refresh(urls: Iterable<string>): void;
+}
+//# sourceMappingURL=module-files.d.ts.map

package/lib/types/watch-config.d.ts

@@ -1,7 +1,8 @@
 import { type ChokidarOptions } from 'chokidar';
 import type { Context } from '@deepseek-ai/cordis';
 /**
- * Watch one patch path, including missing parents, and serialize refresh callbacks.
+ * Watch one patch path and its parent chain without subscribing to sibling files or directories.
+ * Missing parents are observed as they appear; refresh callbacks run serially.
  * @param ctx Context that owns watcher disposal and receives refresh failures.
  * @param filename Absolute patch-file path.
  * @param options Deployment watcher options; configuration watches enable write stabilization by default.

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "hmr"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "插件热重载",
+    "description": "在应用运行期间重新加载插件代码和配置。"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-hmr",
   "description": "Coordinated module and profile configuration hot reload",
-  "version": "0.2.1-alpha.2",
+  "version": "0.2.1-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -19,39 +19,41 @@
       "default": "./lib/index.js"
     },
     "./src/*": "./src/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
   },
   "files": [
+    "locale/*.json",
     "lib/index.js",
     "lib/types/**/*.d.ts"
   ],
   "author": "Shigma <shigma10826@gmail.com>",
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.1",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.1",
-    "@deepseek-ai/cordis-plugin-include": "~1.0.10-alpha.1",
-    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-cmdline": "0.2.1-alpha.2"
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.2",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.10-alpha.2",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-cmdline": "0.2.1-alpha.4"
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "chokidar": "^4.0.3",
+    "chokidar": "5.0.0",
     "node-addon-require-builtin": "^0.1.9",
     "picomatch": "^4.0.7",
-    "@deepseek-ai/schemastery": "~3.18.5-alpha.1"
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.2"
   },
   "devDependencies": {
     "@types/babel__code-frame": "^7.27.0",
     "@types/picomatch": "^4.0.3",
     "esbuild": "^0.28.2",
-    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.1",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.1",
-    "@deepseek-ai/cordis-plugin-include": "~1.0.10-alpha.1",
-    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-cmdline": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.2"
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.2",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.10-alpha.2",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-cmdline": "0.2.1-alpha.4",
+    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.4"
   }
 }