@deepseek-ai/dsh-hmr 0.1.6-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Shigma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

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

package/README.md

@@ -0,0 +1,95 @@
+---
+description: "Reload plugin code and profile configuration through one coordinated queue."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-hmr
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Reload plugin source and configuration while an application is running. Module replacements, Include refreshes and profile configuration changes share one queue. Package installation runs outside that queue. Existing Cordis HMR configuration and events remain available under `ctx.hmr`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The base bundle enables HMR with `root: []` when the launcher supplies `profileContext`; hosts without that profile context leave this entry disabled. Headless, SDK and ACP bundles disable that entry in YAML; a later profile patch can enable it. Disabling or omitting HMR applies changes on restart. To enable source-module watching, configure the `hmr` entry supplied by the base bundle in the profile patch before launching:
+
+```yaml
+- id: hmr
+  disabled: false
+  config:
+    root: ["."]
+```
+
+Existing configurations replace the module name `@deepseek-ai/cordis-plugin-hmr` with `@deepseek-ai/dsh-hmr`. The `hmr` service key, `baseDir`, `config`, `getLinked()`, `getOuterStack()`, `hmr/change` and `hmr/reload` remain available. The vendored package remains available; DSH profiles use this package.
+
+### Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `base` | Context base URL | Base directory for module watching. |
+| `root` | `["."]` | Module watch roots; `[]` retains only explicit configuration watches. |
+| `ignored` | `["**/node_modules", "**/.*", "cache", "data"]` | Excluded module paths. |
+| `debounce` | `100` | Milliseconds for combining module changes. |
+
+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.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<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.
+
+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. HMR also owns module-cache replacement and reload scheduling. Configuration watchers start outside the active transaction context so later notifications can enter the queue. No invariant companion is published because the queue and watcher registrations have no independent persisted projection.
+
+Watched module paths use Node ESM resolution's `realpathSync()` spelling, including Windows short directory names, so file events match the module cache.
+
+The module replacement implementation derives from `@cordisjs/plugin-hmr` 1.0.15, with Harness Node-loader and lazy-config changes. Its [MIT license](LICENSE) is retained.
+
+</details>
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Reloaded plugins
+
+#### What the model sees
+
+`ctx.hmr` adds no model-facing tools or messages. Loaded plugins determine subsequent tool and prompt contributions.
+
+#### Token effect
+
+No direct token contribution.
+
+#### KV Cache effect
+
+Reloading a contributing plugin can change later request prefixes; HMR does not rewrite conversation history.
+
+## Known Limitations and Deferred Work
+
+<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. The browser Client module graph retains its separate browser-side loading mechanism.
+
+### Dev Note
+
+<a id="dev-note"></a>
+
+None.

package/README.zh.md

@@ -0,0 +1,95 @@
+---
+description: "通过统一协调队列热重载插件代码和 profile 配置。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-hmr
+
+[English](README.md) | 中文
+
+## 概述
+
+在应用运行期间重载插件源码和配置。模块替换、Include 刷新与 profile 配置变更共用一个队列。包安装在该队列之外执行。`ctx.hmr` 保留现有 Cordis HMR 的配置和事件。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+启动器提供 `profileContext` 时，base 组合包以 `root: []` 启用 HMR；没有该 profile 上下文的宿主保留此条目为禁用状态。Headless、SDK 和 ACP 组合包在 YAML 中禁用此条目，后续 profile patch 可以重新启用。禁用或省略 HMR 时，更改在重启后生效。如需监听源码模块，在启动前通过 profile patch 配置 base 组合包提供的 `hmr` 条目：
+
+```yaml
+- id: hmr
+  disabled: false
+  config:
+    root: ["."]
+```
+
+已有配置将模块名 `@deepseek-ai/cordis-plugin-hmr` 替换为 `@deepseek-ai/dsh-hmr`。继续提供 `hmr` 服务键、`baseDir`、`config`、`getLinked()`、`getOuterStack()`、`hmr/change` 和 `hmr/reload`。工作区保留 vendored 包；DSH profile 使用本包。
+
+### 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `base` | Context 的 base URL | 模块监听的基准目录。 |
+| `root` | `["."]` | 模块监听目录；`[]` 仅保留显式注册的配置监听。 |
+| `ignored` | `["**/node_modules", "**/.*", "cache", "data"]` | 排除的模块路径。 |
+| `debounce` | `100` | 合并模块变化的毫秒数。 |
+
+Chokidar 选项（包括轮询）保持原有含义。精确配置监听同时观察新增、删除及初始不存在的父目录。它们默认使用 `awaitWriteFinish: true`：编辑后等待 Chokidar 的 2 秒写入稳定窗口，避免其变化事件节流丢失通知。可通过 `awaitWriteFinish` 调整窗口；禁用它可能漏掉快速连续编辑。直接通过 Plugin Manager 发起的操作无需等待文件事件即可应用。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+`watchConfig()` 注册会被等待的配置处理器。`runExclusive()` 将配置变更、Loader 更新与自动重载串行化，并拒绝嵌套事务。包安装和删除在该队列之外执行。HMR 不获取包操作写锁；manifest 通知仅在有序的 `dsh.profile.bundles` 列表变化时触发重载。profile 与 home patch 变化也会触发重新组合。配置事务期间收到的文件事件在事务结束后处理。
+
+App-boot 负责 profile 解析和 patch 优先级规则。HMR 读取启动器提供的纯数据 `profileContext`，在初始化时注册 profile manifest 和两份用户 patch 的监听，并等待应用就绪后处理更改。销毁 HMR 时会关闭监听器并取消等待启动的重载。HMR 也负责模块缓存替换和重载调度。配置监听器在当前事务上下文之外启动，使后续通知可以进入队列。不发布 invariant 伴生入口，因为队列和监听注册没有独立的持久投影。
+
+被监听模块的路径沿用 Node ESM 解析所用的 `realpathSync()` 表示，包括 Windows 短目录名，使文件事件与模块缓存匹配。
+
+模块替换实现源自 `@cordisjs/plugin-hmr` 1.0.15，包含 Harness 的 Node loader 和惰性配置修改。保留其 [MIT 许可证](LICENSE)。
+
+</details>
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 被重载的插件
+
+#### 模型看到什么
+
+`ctx.hmr` 不添加模型工具或消息。加载后的插件决定后续工具和提示词贡献。
+
+#### Token 影响
+
+没有直接的 token 贡献。
+
+#### KV Cache 影响
+
+重载提供上下文的插件可能改变后续请求前缀；HMR 不改写对话历史。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 模块替换需要 Node loader 内部接口。框架依赖变化调用宿主提供的 `loader.exit()` 钩子；HMR 本身不重启进程。
+- 通过插件管理器替换已安装包版本仍需要重启。浏览器 Client 模块图保留独立的浏览器侧加载机制。
+
+### 开发备注
+
+<a id="dev-note"></a>
+
+无。

package/lib/index.js

@@ -0,0 +1,672 @@
+import { createRequire } from "node:module";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { basename, dirname, join, relative, resolve } from "node:path";
+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 { codeFrameColumns } from "@babel/code-frame";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import picomatch from "picomatch";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/watch-config.js
+/** Exact-path watching for live profile patch files outside Cordis module roots. */
+const registrations = /* @__PURE__ */ new WeakMap();
+async function findWatchRoot(filename) {
+	let root = dirname(filename);
+	let depth = 0;
+	while (true) try {
+		if (!(await stat(root)).isDirectory()) throw new Error(`config watch parent is not a directory: ${root}`);
+		const canonicalRoot = await realpath(root);
+		return {
+			filename: resolve(canonicalRoot, relative(root, filename)),
+			root: canonicalRoot,
+			depth
+		};
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = dirname(root);
+		if (parent === root) throw error;
+		root = parent;
+		depth += 1;
+	}
+}
+/**
+* Watch one patch path, including missing parents, and serialize refresh callbacks.
+* @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.
+* @param refresh Callback for additions, changes, and removals.
+* @param inTransaction Whether disposal is running inside the refresh being removed.
+* @returns A disposer that closes the watcher and drains its current refresh.
+* @throws When path resolution, watcher startup, or effect registration fails.
+*/
+async function watchConfig(ctx, filename, options, refresh, inTransaction = () => false) {
+	const target = await findWatchRoot(filename);
+	const paths = registrations.get(ctx) ?? /* @__PURE__ */ new Set();
+	registrations.set(ctx, paths);
+	if (paths.has(target.filename)) throw new Error(`config path already registered: ${filename}`);
+	const { cwd: _cwd, ignored: _ignored, ...watchOptions } = options;
+	const watcher = watch(target.root, {
+		awaitWriteFinish: true,
+		...watchOptions,
+		depth: target.depth,
+		ignoreInitial: false
+	});
+	paths.add(target.filename);
+	const state = { dirty: false };
+	let running;
+	const onChange = (path) => {
+		const observed = resolve(path);
+		if (observed !== filename && observed !== target.filename) return;
+		state.dirty = true;
+		if (running) return;
+		running = (async () => {
+			while (state.dirty) {
+				state.dirty = false;
+				try {
+					await refresh();
+				} catch (reason) {
+					const error = reason instanceof Error ? reason : new Error(String(reason), { cause: reason });
+					ctx.logger.warn("config reload at %C failed", filename);
+					ctx.logger.warn(error);
+				}
+			}
+		})().finally(() => {
+			running = void 0;
+		});
+	};
+	watcher.on("add", onChange);
+	watcher.on("change", onChange);
+	watcher.on("unlink", onChange);
+	const ready = Promise.withResolvers();
+	let pending = true;
+	watcher.once("ready", () => {
+		pending = false;
+		ready.resolve();
+	});
+	watcher.on("error", (error) => {
+		if (pending) {
+			pending = false;
+			ready.reject(error);
+		} else ctx.logger.warn(error);
+	});
+	const dispose = async () => {
+		await watcher.close();
+		paths.delete(target.filename);
+		if (!inTransaction()) await running;
+	};
+	try {
+		await ready.promise;
+		return ctx.effect(() => dispose, "hmr.watchConfig()");
+	} catch (error) {
+		await dispose();
+		throw error;
+	}
+}
+//#endregion
+//#region lib/types/error.js
+function isBuildFailure(e) {
+	return e !== null && typeof e === "object" && "errors" in e && Array.isArray(e.errors) && e.errors.every((error) => error !== null && typeof error === "object" && "text" in error && typeof error.text === "string");
+}
+/** Log HMR build failures with code frames when source locations are available.
+* @param ctx Context owning reload diagnostics.
+* @param e Failure from the module loader or compiler.
+*/
+function handleError(ctx, e) {
+	if (!isBuildFailure(e)) {
+		ctx.logger.warn(e);
+		return;
+	}
+	for (const error of e.errors) {
+		if (!error.location) {
+			ctx.logger.warn(error.text);
+			continue;
+		}
+		try {
+			const { file, line, column } = error.location;
+			const formatted = codeFrameColumns(readFileSync(file, "utf8"), { start: {
+				line,
+				column
+			} }, {
+				highlightCode: true,
+				message: error.text
+			});
+			ctx.logger.warn(`File: ${file}:${line}:${column}\n` + formatted);
+		} catch (e) {
+			ctx.logger.warn(e);
+		}
+	}
+}
+//#endregion
+//#region lib/types/index.js
+/** Serialized module and profile-configuration reloads. */
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+function canonicalPath(filename) {
+	try {
+		return realpathSync(filename);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = dirname(filename);
+		if (parent === filename) throw error;
+		return resolve(canonicalPath(parent), basename(filename));
+	}
+}
+/**
+* Recursively collect all module dependencies from a ModuleJob.
+* Skips node: builtins and node_modules to focus on user code.
+*/
+async function loadDependencies(job, ignored = /* @__PURE__ */ new Set()) {
+	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;
+		dependencies.add(job.url);
+		const children = await job.linked;
+		await Promise.all(Array.prototype.map.call(children, traverse));
+	}
+	await traverse(job);
+	return dependencies;
+}
+/** Hot reload service with Cordis-compatible module configuration and events. */
+let Hmr = (() => {
+	let _classDecorators = [Inject("loader"), Inject("timer")];
+	let _classDescriptor;
+	let _classExtraInitializers = [];
+	let _classThis;
+	let _classSuper = Service;
+	var Hmr = class extends _classSuper {
+		static {
+			_classThis = this;
+		}
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			__esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, {
+				kind: "class",
+				name: _classThis.name,
+				metadata: _metadata
+			}, null, _classExtraInitializers);
+			Hmr = _classThis = _classDescriptor.value;
+			if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		config;
+		/** Cordis-compatible watcher defaults. */
+		static Config = z.object({
+			base: z.string(),
+			root: z.array(String).role("table").default(["."]),
+			ignored: z.array(String).role("table").default([
+				"**/node_modules",
+				"**/.*",
+				"cache",
+				"data"
+			]),
+			debounce: z.natural().role("ms").default(100)
+		});
+		/** Absolute base directory used to resolve module watch roots. */
+		baseDir;
+		ownerContext;
+		internal;
+		watcher;
+		/**
+		* Changes from externals will always trigger a full reload.
+		* Externals are the dependency tree of the CLI worker entry point.
+		*/
+		externals;
+		/**
+		* Files that should be reloaded (accepted changes).
+		* Includes all stashed files and their dependents.
+		*/
+		accepted;
+		/**
+		* Files that should NOT be reloaded.
+		* Includes externals and files whose dependents are all declined.
+		*/
+		declined;
+		/** Stashed file changes waiting to be processed */
+		stashed = /* @__PURE__ */ new Set();
+		operations = Promise.resolve();
+		executing = new AsyncLocalStorage();
+		applicationReady = Promise.resolve(true);
+		closing = false;
+		configPaths = /* @__PURE__ */ new Set();
+		/** 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.
+		*/
+		runExclusive(operation) {
+			if (this.executing.getStore()) return Promise.reject(/* @__PURE__ */ new Error("HMR transactions cannot be nested"));
+			const task = this.operations.then(async () => {
+				if (this.closing) throw new Error("HMR is disposed");
+				return this.executing.run(true, operation);
+			});
+			this.operations = task.catch(() => {});
+			return task;
+		}
+		runReload(operation) {
+			return this.runExclusive(async () => {
+				if (await this.applicationReady) await operation();
+			});
+		}
+		/** Watch a configuration path through the same queue as module replacement.
+		* @param filename Absolute path, which may not exist yet.
+		* @param refresh Rebuilds configuration from its current files and awaits Loader completion.
+		* @returns Disposer closing this registration and waiting for its pending refresh.
+		*/
+		async watchConfig(filename, refresh) {
+			const paths = [resolve(filename), canonicalPath(filename)];
+			if (paths.some((path) => this.configPaths.has(path))) throw new Error(`config path already registered: ${filename}`);
+			for (const path of paths) this.configPaths.add(path);
+			try {
+				const dispose = await this.executing.exit(() => watchConfig(this.ownerContext, filename, this.config, () => this.runReload(refresh), () => this.executing.getStore() === true));
+				return async () => {
+					await dispose();
+					for (const path of paths) this.configPaths.delete(path);
+				};
+			} catch (error) {
+				for (const path of paths) this.configPaths.delete(path);
+				throw error;
+			}
+		}
+		constructor(ctx, config) {
+			super(ctx, "hmr");
+			this.config = config;
+			this.ownerContext = ctx;
+			if (!this.ctx.loader.internal) throw new Error("--expose-internals is required for HMR service");
+			this.internal = this.ctx.loader.internal;
+			this.baseDir = fileURLToPath(new URL(config.base || ".", ctx.baseUrl));
+		}
+		/**
+		* Resolve a module specifier to a URL, compatible with Node 22-24.
+		*/
+		async _resolve(specifier, parentURL, attrs) {
+			switch (this.internal.version) {
+				case "v1": return await this.internal.resolve(specifier, parentURL, attrs);
+				case "v2": return this.internal.resolveSync(parentURL, {
+					specifier,
+					attributes: attrs
+				});
+			}
+		}
+		async *[Service.init]() {
+			yield async () => {
+				this.closing = true;
+				await this.watcher?.close();
+				if (!this.executing.getStore()) await this.operations;
+			};
+			const profile = this.ownerContext.get("profileContext");
+			if (profile !== void 0) {
+				const ready = this.ownerContext.get("appReady");
+				if (ready === void 0) throw new Error("Profile HMR requires application readiness");
+				const started = Promise.withResolvers();
+				this.applicationReady = started.promise;
+				const unsubscribe = ready.onReady(() => {
+					started.resolve(true);
+				});
+				yield () => {
+					unsubscribe();
+					started.resolve(false);
+					return Promise.resolve();
+				};
+				const manifestPath = join(profile.dir, "package.json");
+				const patchFiles = [profile.patchPath, join(profile.home, PROFILE_PATCH_FILENAME)];
+				let lastInputs;
+				let lastBundles = JSON.stringify(profile.startedBundles);
+				const refresh = async (manifestOnly) => {
+					const bundles = JSON.stringify(readProfileManifest("dsh", profile.dir).dsh?.profile?.bundles ?? []);
+					if (manifestOnly && bundles === lastBundles) return;
+					const inputs = JSON.stringify([bundles, ...patchFiles.map((filename) => {
+						try {
+							return readFileSync(filename, "utf8");
+						} catch (error) {
+							if (error.code === "ENOENT") return null;
+							throw error;
+						}
+					})]);
+					if (inputs === lastInputs) return;
+					const patches = readProfilePatches("dsh", profile);
+					const warnings = await reconcileProfilePatches(this.ownerContext.root, patches, "dsh");
+					lastInputs = inputs;
+					lastBundles = bundles;
+					for (const diagnostic of warnings) this.ctx.logger.warn(diagnostic);
+				};
+				for (const filename of patchFiles) await this.watchConfig(filename, () => refresh(false));
+				await this.watchConfig(manifestPath, () => refresh(true));
+			}
+			const { loader } = this.ctx;
+			const { root, ignored } = this.config;
+			if (!this.config.base) this.ctx.logger.info("watching %o", root);
+			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, {
+				...this.config,
+				cwd: watchBaseDir,
+				ignored: (path) => match(relative(watchBaseDir, path)),
+				ignoreInitial: true
+			});
+			const changed = /* @__PURE__ */ new Set();
+			const dispatch = this.ctx.debounce(() => {
+				this.runExclusive(async () => {
+					if (!await this.applicationReady) return;
+					const batch = [...changed];
+					changed.clear();
+					const includes = /* @__PURE__ */ new Set();
+					let fullReload = false;
+					for (const path of batch) {
+						const filename = canonicalPath(resolve(watchBaseDir, path));
+						const configuredFilename = resolve(this.baseDir, path);
+						if (this.configPaths.has(filename) || this.configPaths.has(configuredFilename)) continue;
+						const url = pathToFileURL(filename).href;
+						if (this.externals.has(url)) {
+							fullReload = true;
+							continue;
+						}
+						if (this.internal.loadCache.has(url)) {
+							this.stashed.add(url);
+							continue;
+						}
+						const include = [...loader.entries()].map((entry) => entry.subtree).find((tree) => tree?.filename === filename || tree?.filename === configuredFilename);
+						if (include !== void 0) includes.add(include);
+						else this.ctx.emit("hmr/change", url);
+					}
+					if (!fullReload && includes.size === 0 && this.stashed.size === 0) return;
+					if (fullReload) {
+						loader.exit();
+						return;
+					}
+					for (const include of includes) await include.refresh();
+					if (this.stashed.size > 0) try {
+						await this.partialReload();
+					} finally {
+						this.stashed.clear();
+					}
+					await loader.await();
+				}).catch((error) => {
+					this.ctx.logger.warn(error);
+				});
+			}, this.config.debounce);
+			this.watcher.on("change", (path) => {
+				changed.add(path);
+				dispatch();
+			});
+			const ready = Promise.withResolvers();
+			let readyState = root.length === 0 ? "resolved" : "pending";
+			if (root.length === 0) ready.resolve();
+			else this.watcher.once("ready", () => {
+				readyState = "resolved";
+				ready.resolve();
+			});
+			this.watcher.on("error", (error) => {
+				if (readyState === "pending") {
+					readyState = "rejected";
+					ready.reject(error);
+				} else this.ctx.logger.warn(error);
+			});
+			await ready.promise;
+		}
+		/** Omit internal HMR frames from module import diagnostics.
+		* @returns The preserved outer stack frames.
+		*/
+		getOuterStack = () => [];
+		/** Read direct module dependency URLs from the active Node loader.
+		* @param url Module URL.
+		* @returns Linked module URLs, or an empty list for an uncached module.
+		*/
+		async getLinked(url) {
+			const job = this.internal.loadCache.get(url);
+			if (!job) return [];
+			const linked = await job.linked;
+			return Array.prototype.map.call(linked, (job) => job.url);
+		}
+		/**
+		* Classify changed files into accepted (should reload) and declined (should not).
+		*
+		* A file is accepted if it's directly changed (stashed) or if any of its
+		* dependents are accepted. A file is declined if all its dependents are
+		* declined or if it's an external.
+		*/
+		async analyzeChanges() {
+			const pending = [];
+			this.accepted = new Set(this.stashed);
+			this.declined = new Set(this.externals);
+			const isExcluded = (url) => url.startsWith("node:") || url.includes("/node_modules/");
+			await Promise.all([...this.stashed].map(async (url) => {
+				const children = await this.getLinked(url);
+				for (const child of children) {
+					if (this.accepted.has(child) || this.declined.has(child) || isExcluded(child)) continue;
+					pending.push(child);
+				}
+			}));
+			while (pending.length) {
+				let index = 0, hasUpdate = false;
+				while (index < pending.length) {
+					const url = pending[index];
+					const children = await this.getLinked(url);
+					let isDeclined = true, isAccepted = false;
+					for (const child of children) {
+						if (this.declined.has(child) || isExcluded(child)) continue;
+						if (this.accepted.has(child)) {
+							isAccepted = true;
+							break;
+						} else {
+							isDeclined = false;
+							if (!pending.includes(child)) {
+								hasUpdate = true;
+								pending.push(child);
+							}
+						}
+					}
+					if (isAccepted || isDeclined) {
+						hasUpdate = true;
+						pending.splice(index, 1);
+						if (isAccepted) this.accepted.add(url);
+						else this.declined.add(url);
+					} else index++;
+				}
+				if (!hasUpdate) break;
+			}
+			for (const url of pending) this.declined.add(url);
+		}
+		async partialReload() {
+			await this.analyzeChanges();
+			const pending = /* @__PURE__ */ new Map();
+			const reloads = /* @__PURE__ */ new Map();
+			const nameMap = /* @__PURE__ */ new Map();
+			for (const entry of this.ctx.loader.entries()) {
+				const baseUrl = entry.parent.tree.ctx.baseUrl;
+				if (baseUrl === void 0) throw new Error("HMR entry tree has no base URL");
+				const names = nameMap.get(baseUrl) ?? /* @__PURE__ */ new Set();
+				names.add(entry.options.name);
+				nameMap.set(baseUrl, names);
+			}
+			for (const [baseUrl, names] of nameMap) for (const name of names) try {
+				const { url } = await this._resolve(name, baseUrl, {});
+				if (this.declined.has(url)) continue;
+				const job = this.internal.loadCache.get(url);
+				const plugin = this.ctx.loader.unwrapExports(job?.module?.getNamespace());
+				if (!job || !plugin) continue;
+				pending.set(job, plugin);
+				this.declined.add(url);
+			} catch (err) {
+				this.ctx.logger.warn(err);
+			}
+			for (const [job, plugin] of pending) {
+				this.declined.delete(job.url);
+				const dependencies = [...await loadDependencies(job, this.declined)];
+				this.declined.add(job.url);
+				if (!dependencies.some((dep) => this.accepted.has(dep))) continue;
+				dependencies.forEach((dep) => this.accepted.add(dep));
+				reloads.set(plugin, {
+					filename: job.url,
+					runtime: this.ctx.registry.get(plugin)
+				});
+			}
+			/**
+			* 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 generations = [...reloads].map(([previous, info]) => ({
+				...info,
+				previous,
+				fibers: [...info.runtime?.fibers ?? []].map((fiber) => {
+					const entry = fiber.entry?.fiber?.uid === fiber.uid ? fiber.entry : void 0;
+					return {
+						fiber,
+						entry,
+						config: entry === void 0 ? fiber._config : entry.options.config
+					};
+				})
+			}));
+			const attempts = [];
+			try {
+				for (const generation of generations) {
+					const replacement = this.ctx.loader.unwrapExports(await this.ctx.loader.import(generation.filename, this.getOuterStack));
+					attempts.push({
+						...generation,
+						replacement
+					});
+				}
+			} catch (e) {
+				handleError(this.ctx, e);
+				rollback();
+				throw e;
+			}
+			const reload = async (plugin, fibers) => {
+				const activated = [];
+				for (const previousFiber of fibers) {
+					if (previousFiber.fiber.parent.fiber.uid === null) continue;
+					const fiber = previousFiber.fiber.parent.registry.plugin(plugin, previousFiber.config, this.getOuterStack).ctx.fiber;
+					if (previousFiber.entry !== void 0) {
+						fiber.entry = previousFiber.entry;
+						previousFiber.entry.fiber = fiber;
+					}
+					activated.push(fiber);
+				}
+				await Promise.all(activated.map((fiber) => fiber.await()));
+			};
+			const removed = /* @__PURE__ */ new Set();
+			try {
+				for (const { previous: plugin, replacement, filename, runtime, fibers } of attempts) {
+					if (!runtime) continue;
+					const path = relative(this.baseDir, fileURLToPath(filename));
+					removed.add(plugin);
+					try {
+						this.ctx.registry.delete(plugin);
+						await Promise.all(fibers.map(({ fiber }) => fiber.await()));
+					} catch (err) {
+						this.ctx.logger.warn("failed to dispose plugin at %C", path);
+						this.ctx.logger.warn(err);
+					}
+					try {
+						await reload(replacement, fibers);
+						this.ctx.logger.info("reload plugin at %C", path);
+					} catch (err) {
+						this.ctx.logger.warn("failed to reload plugin at %C", path);
+						this.ctx.logger.warn(err);
+						throw err;
+					}
+				}
+			} catch (error) {
+				rollback();
+				for (const { previous: plugin, replacement, fibers } of attempts) {
+					if (!removed.has(plugin)) continue;
+					try {
+						const replacementFibers = [...this.ctx.registry.get(replacement)?.fibers ?? []];
+						this.ctx.registry.delete(replacement);
+						await Promise.allSettled(replacementFibers.map((fiber) => fiber.await()));
+						await reload(plugin, fibers);
+					} catch (err) {
+						this.ctx.logger.warn(err);
+					}
+				}
+				throw error;
+			}
+			await this.ctx.loader.await();
+			this.ctx.emit("hmr/reload", reloads);
+			this.stashed = /* @__PURE__ */ new Set();
+		}
+		static {
+			__runInitializers(_classThis, _classExtraInitializers);
+		}
+	};
+	return _classThis;
+})();
+//#endregion
+export { Hmr as default };

package/lib/types/error.d.ts

@@ -0,0 +1,7 @@
+import { Context } from '@deepseek-ai/cordis';
+/** Log HMR build failures with code frames when source locations are available.
+ * @param ctx Context owning reload diagnostics.
+ * @param e Failure from the module loader or compiler.
+ */
+export declare function handleError(ctx: Context, e: unknown): void;
+//# sourceMappingURL=error.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,112 @@
+import { Context, Service, type Plugin } from '@deepseek-ai/cordis';
+import { type ChokidarOptions } from 'chokidar';
+import z from '@deepseek-ai/schemastery';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Serialized plugin-code and configuration reloads. */
+        hmr: Hmr;
+    }
+    interface Events {
+        /** A watched file has no module or configuration handler.
+         * @mode emit
+         * @param url Canonical file URL.
+         */
+        'hmr/change'(url: string): void;
+        /** Module replacements have finished loading.
+         * @mode emit
+         * @param reloads Replaced plugins and their module locations.
+         */
+        'hmr/reload'(reloads: Map<Plugin, Reload>): void;
+    }
+}
+/** Module roots and watcher timing, with Chokidar deployment options. */
+export interface HmrConfig extends ChokidarOptions {
+    /** Directory resolved against the owning context's base URL. */
+    base?: string;
+    /** Module watch roots; an empty list leaves only explicit configuration watches. */
+    root: string[];
+    /** Milliseconds for combining module changes. */
+    debounce: number;
+    /** Glob patterns excluded from module watching. */
+    ignored: string[];
+}
+/** Module location and runtime retained during a replacement. */
+export interface Reload {
+    filename: string;
+    runtime?: Plugin.Runtime | undefined;
+}
+/** Hot reload service with Cordis-compatible module configuration and events. */
+declare class Hmr extends Service {
+    config: HmrConfig;
+    /** Cordis-compatible watcher defaults. */
+    static Config: z<HmrConfig>;
+    /** Absolute base directory used to resolve module watch roots. */
+    baseDir: string;
+    private readonly ownerContext;
+    private internal;
+    private watcher;
+    /**
+     * Changes from externals will always trigger a full reload.
+     * Externals are the dependency tree of the CLI worker entry point.
+     */
+    private externals;
+    /**
+     * Files that should be reloaded (accepted changes).
+     * Includes all stashed files and their dependents.
+     */
+    private accepted;
+    /**
+     * Files that should NOT be reloaded.
+     * Includes externals and files whose dependents are all declined.
+     */
+    private declined;
+    /** Stashed file changes waiting to be processed */
+    private stashed;
+    private operations;
+    private readonly executing;
+    private applicationReady;
+    private closing;
+    private readonly configPaths;
+    /** 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.
+     */
+    runExclusive<T>(operation: () => Promise<T>): Promise<T>;
+    private runReload;
+    /** Watch a configuration path through the same queue as module replacement.
+     * @param filename Absolute path, which may not exist yet.
+     * @param refresh Rebuilds configuration from its current files and awaits Loader completion.
+     * @returns Disposer closing this registration and waiting for its pending refresh.
+     */
+    watchConfig(filename: string, refresh: () => Promise<void>): Promise<() => Promise<void>>;
+    constructor(ctx: Context, config: HmrConfig);
+    /**
+     * Resolve a module specifier to a URL, compatible with Node 22-24.
+     */
+    private _resolve;
+    [Service.init](): AsyncGenerator<() => Promise<void>, void, unknown>;
+    /** Omit internal HMR frames from module import diagnostics.
+     * @returns The preserved outer stack frames.
+     */
+    getOuterStack: () => string[];
+    /** Read direct module dependency URLs from the active Node loader.
+     * @param url Module URL.
+     * @returns Linked module URLs, or an empty list for an uncached module.
+     */
+    getLinked(url: string): Promise<string[]>;
+    /**
+     * Classify changed files into accepted (should reload) and declined (should not).
+     *
+     * A file is accepted if it's directly changed (stashed) or if any of its
+     * dependents are accepted. A file is declined if all its dependents are
+     * declined or if it's an external.
+     */
+    private analyzeChanges;
+    private partialReload;
+}
+declare namespace Hmr {
+    /** Cordis-compatible configuration type. */
+    type Config = HmrConfig;
+}
+export default Hmr;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,14 @@
+import { type ChokidarOptions } from 'chokidar';
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Watch one patch path, including missing parents, and serialize refresh callbacks.
+ * @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.
+ * @param refresh Callback for additions, changes, and removals.
+ * @param inTransaction Whether disposal is running inside the refresh being removed.
+ * @returns A disposer that closes the watcher and drains its current refresh.
+ * @throws When path resolution, watcher startup, or effect registration fails.
+ */
+export declare function watchConfig(ctx: Context, filename: string, options: ChokidarOptions, refresh: () => Promise<void> | void, inTransaction?: () => boolean): Promise<() => Promise<void>>;
+//# sourceMappingURL=watch-config.d.ts.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@deepseek-ai/dsh-hmr",
+  "description": "Coordinated module and profile configuration hot reload",
+  "version": "0.1.6-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/boot/hmr"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "author": "Shigma <shigma10826@gmail.com>",
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/dsh-app-boot": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis-plugin-timer": "^1.1.4",
+    "@deepseek-ai/dsh-cmdline": "^0.1.6-alpha.2"
+  },
+  "dependencies": {
+    "@babel/code-frame": "^7.29.0",
+    "chokidar": "^4.0.3",
+    "picomatch": "^4.0.3",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@types/babel__code-frame": "^7.27.0",
+    "@types/picomatch": "^3.0.2",
+    "esbuild": "^0.28.1",
+    "@deepseek-ai/cordis-plugin-timer": "^1.1.4",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/dsh-app-boot": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-cmdline": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-atomic-write": "^0.1.6-alpha.2"
+  }
+}