dsh-hot-reload 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -3,6 +3,71 @@
 All notable changes to `dsh-hot-reload` are documented here. This project
 follows [semantic versioning](https://semver.org/).
 
+## 0.2.2
+
+Reloads now re-import a plugin's whole package, not just its entry module.
+Config and API unchanged.
+
+**Fixes**
+
+- **Multi-file plugins reload as one unit.** The reload used to invalidate only
+  the entry URL and re-import it. Under a hoisted linker (`nodeLinker: hoisted`)
+  a version bump rewrites the package's files in place, so the entry's relative
+  imports (`./routes.js` and friends) resolved to the same URLs and hit the
+  stale cache — the running plugin mixed new entry code with old dependency code,
+  which for a plugin like `dshmarket` surfaced as a crash looking for a file the
+  new version had deleted. The reload now invalidates every cached module under
+  the package's own directory (in both the ESM `loadCache` and the CJS
+  `require.cache`) before re-importing, so the entry and its in-package imports
+  come back together. Shared dependencies live outside that directory and are
+  left alone.
+
+## 0.2.1
+
+Code-review fixes to the 0.2.0 notification surfaces. No config or API changes,
+and detection and reloading are untouched.
+
+**Fixes**
+
+- **The pop-ups come back on their own after dsh restarts.** A browser tab whose
+  message channel closed for good used to stay silent until you reloaded the
+  page. This was easy to hit: the web server opens its socket before this plugin
+  adds its route, so a tab retrying in that gap got the web app's HTML instead of
+  a message channel, which the browser treats as a permanent failure. The tab now
+  opens a new channel after 1s, 2s, 4s, 8s, 16s, then every 30s, up to ten tries
+  (about three minutes). If all ten fail it says so in the console and stops, so
+  a profile that simply has no host half does not knock at the door forever. Each
+  successful connect gives the next outage a fresh set of tries.
+- **A broken `ctx.inject` can no longer stop dsh from starting.** Setting up the
+  message channel now runs last and inside a `try`. Before, it ran before the
+  file watcher and was the one unguarded call on that path: if a future cordis
+  changed `ctx.inject`, `apply()` would throw, dsh's start-up check would refuse
+  to boot, and the watcher would never have been created — losing reloading over
+  a feature that only reports on it.
+- **A `HEAD` request no longer hangs.** `HEAD` was answered with a never-ending
+  message stream, but Node throws away a `HEAD` body, so the caller waited until
+  its own timeout while its connection sat in the plugin's list of subscribers
+  collecting writes nobody would read. Health checks and link pre-fetchers do
+  send `HEAD`. It now gets the headers and a clean close.
+- **"No running copy to swap out" is announced once per version, not forever.**
+  That case is deliberately left uncommitted so a plugin that was merely still
+  starting gets picked up later — which meant every later lockfile write, even
+  for a completely unrelated package, showed the same pop-up again with no way to
+  dismiss it. The retry is unchanged; only the repeat announcing is dropped.
+
+**Docs**
+
+- The README told you to watch for the "no running copy" message *repeating* as
+  your sign to restart dsh. It no longer repeats, so that advice was pointing at
+  a signal that never comes. Both READMEs now say what to watch instead.
+- **New limitation written down: the lockfile is only a trigger.** Version
+  numbers come from each package's installed `package.json`. On pnpm 11 the
+  files on disk are written before the lockfile, so what this plugin reads has
+  settled — but nothing checks that. A future pnpm that wrote the lockfile first
+  could make an upgrade be missed silently. This was a known gap; it was only
+  ever recorded in the repo's internal notes, and one of those notes had the
+  write order backwards.
+
 ## 0.2.0
 
 You can now see reload results without reading the logs. Config did not change:

package/{README.zh.md → README-zh.md}

@@ -30,8 +30,10 @@ dsh 自带的热重载（`cordis-plugin-hmr`）刻意忽略 `node_modules`，所
 - **已禁用（disabled）的插件行会被静默跳过。** 已禁用的插件本就没在运行，没有
   可替换的对象；重新启用时 dsh 自然会加载新代码。
 - **尚未挂上 fiber 的插件**（仍在导入中，或此前加载失败）会被报告为
-  `no live fiber to reload right now` 并原样保留。由于什么都没有被拆除，这种
-  情况**会**在下次 lockfile 变化时重新检查；若反复出现，请重启 dsh。
+  `no live fiber to reload right now` 并原样保留。由于什么都没有被拆除，之后
+  每次 lockfile 变化都**会**重新检查它；一旦出现正在运行的副本，它会自己完成
+  重载。提示是**每个版本只给一次**，不是每次检查都给——所以，如果该插件已有
+  足够时间启动，你却仍看到同一个版本被报告，请重启 dsh。
 
 它**绝不会替你重启 dsh**——重启交给你（以及你的守护进程，如果有的话）。
 
@@ -54,6 +56,10 @@ dsh-hot-reload: hot-reloaded some-plugin@1.2.0 (1 module(s))
 - 该插件用 `dsh.hotReload: false` 关闭了热重载
 - dsh 没有提供重载所需的内部接口
 
+其中第二种情况是**每个版本只提示一次**，而不是每次检查都提示。这种情况在此后
+每次 lockfile 写入时都会重试——包括为别的包发生的写入——所以若不加这个限制，
+同一条提示会反复出现，而且没有办法关掉它。另外三种情况每次发生都会提示。
+
 提示会滑入，停留数秒，然后淡出。如果一次升级重载了多个插件，提示会排队逐条显示。
 
 web 那一部分只在运行 web 服务器的 profile 中加载，并通过
@@ -63,6 +69,10 @@ web 那一部分只在运行 web 服务器的 profile 中加载，并通过
 提示不会被保存。如果重载发生时没有打开任何浏览器标签页，那条提示就没有了。
 日志里仍有记录。
 
+如果你在标签页开着的时候重启 dsh，标签页会自己重新建立通道，提示继续可用。
+它大约会尝试三分钟。若仍然连不上，就在浏览器控制台写一行提示并停止重试；
+刷新页面即可重新开始。
+
 ### 如果你想在终端里看到全部内容
 
 上面那一行只覆盖成功的重载。若想看到本插件写进日志的全部内容（包括失败），请把
@@ -111,6 +121,7 @@ dsh plugin --profile web add some-plugin@newer   # 自动热重载
 |---|---|
 | `loader.internal.loadCache` | 使 ESM 模块缓存失效 |
 | `loader.internal.resolve` / `resolveSync` | 把 specifier 解析为 URL（按 `internal.version` 分派） |
+| `loader.import` / `loader.unwrapExports` | 重新导入新模块，并取出其中的插件导出 |
 | `registry.plugin` / `registry.delete` | 替换插件实例 |
 | `fiber.entry`、`fiber.runtime` | 把新插件重新挂到运行中的行上 |
 | `entry.disabled` | 跳过已禁用的行（继承式 getter） |
@@ -169,6 +180,13 @@ web 应用里的提示（且仅这一部分）还用到：
 - 重载路径依赖[兼容性](#兼容性)一节列出的 cordis/loader 内部接口。若这些内部
   不可用（既无 `--expose-internals`，也无 `node-addon-require-builtin` 原生
   插件），本插件会退化为对每次变化只报告“需要重启”，而不做重载。
+- lockfile 只是**触发器**。版本号是从每个包已安装的 `package.json` 读取的，因为
+  只有这个文件才说明一次 import 实际会拿到什么。在 pnpm 11 上（实测 11.21.0），
+  磁盘上的文件**先**写、lockfile **最后**写，所以本插件动作时读到的版本已经稳定。
+  但插件并不会去*核实*这一点。如果将来某个 pnpm 版本改成先写 lockfile，一次检查
+  就可能读到旧版本、跳过它，而且不再回头看——被监听的只有 lockfile，那次升级就会
+  被**静默**漏掉，不给任何提示，直到你安装另一个版本或重启 dsh。`debounce` 帮不上
+  忙：实测这个间隔有 2.5–4 秒，远超任何合理的 debounce 取值。
 - 提示通道（`GET /dsh-hot-reload/events`）**不做任何密码校验**，与 dsh 自带的
   `/plugins/events` 相同。它发送的是插件名和版本号。dsh 的插件列表本来就会显示
   这些内容，所以并没有多暴露什么秘密。但如果你把 dsh 绑定到 `0.0.0.0`，请把它

package/README.md

@@ -1,6 +1,6 @@
 # dsh-hot-reload
 
-English | [中文](README.zh.md)
+English | [中文](README-zh.md)
 
 Live-reload upgraded [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugins **without restarting dsh**.
 
@@ -36,8 +36,10 @@ Two cases produce no reload, by design:
   new code anyway.
 - **A plugin that has no live fiber *yet*** (still importing, or it failed to
   load earlier) is reported as `no live fiber to reload right now` and left
-  alone. Nothing was torn down, so this one *is* re-examined on the next
-  lockfile change — if it keeps repeating, restart dsh.
+  alone. Nothing was torn down, so this one *is* re-examined on every later
+  lockfile change, and it reloads by itself as soon as a running copy appears.
+  You are told **once per version**, not once per check — so if you still see
+  the same version reported after the plugin has had time to start, restart dsh.
 
 It **never restarts dsh for you** — restarting is left to you (and your
 supervisor, if any).
@@ -64,6 +66,11 @@ old code is still running:
 - the plugin turned off hot reload with `dsh.hotReload: false`
 - dsh did not provide the internal parts the reload needs
 
+The second case is announced **once per version**, not once per check. That case
+is retried on every later lockfile write — including writes for other packages —
+so without this limit you would get the same pop-up over and over, with no way
+to dismiss it. The other three are announced each time they happen.
+
 The message slides in, stays a few seconds, then fades out. If one upgrade
 reloads several plugins, the messages line up and show one after another.
 
@@ -74,6 +81,11 @@ as `tui`, still gets the terminal line and the log.
 Messages are not saved. If no browser tab is open when a reload happens, that
 message is gone. The log still has the record.
 
+If you restart dsh with a tab open, the tab opens a new channel by itself and
+pop-ups keep working. It tries for about three minutes. If it still cannot
+connect after that, it writes one line to the browser console and stops trying;
+reload the page to start again.
+
 ### If you want every line in your terminal
 
 The terminal line above only covers reloads that worked. To see everything this
@@ -125,6 +137,7 @@ future dsh that changes any of them may require an update:
 |---|---|
 | `loader.internal.loadCache` | invalidating the ESM module cache |
 | `loader.internal.resolve` / `resolveSync` | resolving a specifier to a URL (dispatched on `internal.version`) |
+| `loader.import` / `loader.unwrapExports` | re-importing the fresh module and unwrapping its plugin export |
 | `registry.plugin` / `registry.delete` | swapping the plugin instance |
 | `fiber.entry`, `fiber.runtime` | re-attaching the new plugin to the running rows |
 | `entry.disabled` | skipping disabled rows (inherited getter) |
@@ -192,6 +205,16 @@ live fiber to swap). It does **not** detect *silent* leaks:
   [Compatibility](#compatibility). If they are unavailable (no
   `--expose-internals` and no `node-addon-require-builtin` addon), the plugin
   degrades to reporting "restart needed" for every change instead of reloading.
+- The lockfile is only the **trigger**. Version numbers are read from each
+  package's installed `package.json`, because that is the only file that says
+  what an import would really get. On pnpm 11 (measured on 11.21.0) the files on
+  disk are written **first** and the lockfile **last**, so by the time this
+  plugin acts, the versions it reads have settled. But nothing here *checks*
+  that. If some future pnpm wrote the lockfile first, a check could read the old
+  version, skip it, and never look again — the lockfile is the only thing
+  watched, so that upgrade would be missed **silently**, with no message, until
+  you install another version or restart dsh. The `debounce` setting does not
+  help: the gap measured 2.5–4 seconds, far longer than any sane debounce.
 - The message channel (`GET /dsh-hot-reload/events`) has **no password check**,
   the same as dsh's own `/plugins/events`. It sends plugin names and version
   numbers. dsh already shows those through its plugin list, so this adds no new

package/lib/client.js

@@ -52,6 +52,14 @@ window.__ModuleLoader__.load({
      *  single-occupancy — registering there would shadow the entire app frame.) */
     const SLOT = "shell.overlay";
 
+    /** Waits before each attempt to re-open a channel that closed for good, in
+     *  ms. The list is the whole retry policy: its values are the schedule and
+     *  its LENGTH is the budget — run off the end and the tab gives up, so a
+     *  host half that is simply not there costs ten requests, not a request
+     *  every few seconds forever. 16s of fast retries covers a dsh restart;
+     *  the 30s tail covers a slow one. */
+    const RETRY_DELAYS_MS = [1000, 2000, 4000, 8000, 16000, 30000, 30000, 30000, 30000, 30000];
+
     /** Cordis plugin name. */
     const name = "dsh-hot-reload";
     /** Required services: the slot registry this half contributes its banner to. */
@@ -88,32 +96,70 @@ window.__ModuleLoader__.load({
 
       React.useEffect(() => {
         let seq = 0;
-        const source = new EventSource(EVENTS_ENDPOINT);
-        source.addEventListener("message", (event) => {
-          let frame;
-          try {
-            frame = JSON.parse(event.data);
-          } catch {
-            return;
-          }
-          if (frame === null || typeof frame !== "object") return;
-          if (frame.type !== "notice" || typeof frame.text !== "string") return;
-          seq += 1;
-          setQueue((q) => q.concat({ seq, kind: frame.kind, text: frame.text }));
-        });
-        // A dead channel is otherwise invisible: with no route registered, the
-        // request falls through to the SPA fallback and answers 200 text/html,
-        // which EventSource rejects as a permanent failure rather than retrying.
-        // Say so once, so "the feature is off" is distinguishable from "broken".
-        let reported = false;
-        source.addEventListener("error", () => {
-          if (reported || source.readyState !== 2 /* CLOSED */) return;
-          reported = true;
-          warn(`dsh-hot-reload: notice channel ${EVENTS_ENDPOINT} is unavailable — no reload banners`);
-        });
-        // Otherwise EventSource reconnects on its own; the host holds no per-tab
-        // state, so a reconnect costs nothing and misses only what it was down for.
-        return () => source.close();
+        let source = null;
+        let timer = null;
+        let retries = 0;
+        let stopped = false;
+
+        const connect = () => {
+          const es = new EventSource(EVENTS_ENDPOINT);
+          source = es;
+          // A successful connect gives the next outage a full retry budget
+          // again, so the bound below is per outage rather than per tab. It
+          // still bounds a host half that is simply absent: with nothing ever
+          // answering there is no open event, so the budget never refills.
+          es.addEventListener("open", () => {
+            retries = 0;
+          });
+          es.addEventListener("message", (event) => {
+            let frame;
+            try {
+              frame = JSON.parse(event.data);
+            } catch {
+              return;
+            }
+            if (frame === null || typeof frame !== "object") return;
+            if (frame.type !== "notice" || typeof frame.text !== "string") return;
+            seq += 1;
+            setQueue((q) => q.concat({ seq, kind: frame.kind, text: frame.text }));
+          });
+          es.addEventListener("error", () => {
+            // A transient drop leaves readyState CONNECTING and EventSource
+            // retries it on its own — nothing to do. CLOSED is the fatal case
+            // and the one that needs us: with no route registered the request
+            // falls through to the SPA fallback and answers 200 text/html,
+            // which EventSource treats as a permanent failure. That happens on
+            // every dsh restart, because the web server binds its socket before
+            // this plugin's route is registered — so without re-arming here, one
+            // ill-timed retry would cost the banner for the life of the tab.
+            if (stopped || es.readyState !== 2 /* CLOSED */) return;
+            es.close();
+            const delay = RETRY_DELAYS_MS[retries];
+            if (delay === undefined) {
+              warn(
+                `dsh-hot-reload: notice channel ${EVENTS_ENDPOINT} still unavailable after ` +
+                  `${RETRY_DELAYS_MS.length} retries — no reload banners until this page is reloaded`
+              );
+              return;
+            }
+            // Say it once per outage, so "the feature is off" stays
+            // distinguishable from "broken", without a warning per retry.
+            if (retries === 0) {
+              warn(`dsh-hot-reload: notice channel ${EVENTS_ENDPOINT} is unavailable — retrying`);
+            }
+            retries += 1;
+            timer = setTimeout(connect, delay);
+          });
+        };
+
+        connect();
+        // The host holds no per-tab state, so a reconnect costs nothing and
+        // misses only the notices raised while it was down.
+        return () => {
+          stopped = true;
+          if (timer !== null) clearTimeout(timer);
+          if (source !== null) source.close();
+        };
       }, []);
 
       const head = queue[0];

package/lib/index.js

@@ -1,8 +1,9 @@
 // dsh-hot-reload — live-reload upgraded dsh plugins without restarting dsh.
 //
 // It watches the profile's pnpm-lock.yaml; when an already-loaded plugin
-// package's version changes, it invalidates that module's caches, re-imports
-// the new code, and swaps the running plugin fiber in place — the same
+// package's version changes, it invalidates that package's cached modules
+// (entry plus in-package imports), re-imports the new code, and swaps the
+// running plugin fiber in place — the same
 // technique cordis-plugin-hmr uses, but reaching into node_modules (which HMR
 // deliberately ignores).
 //
@@ -29,8 +30,8 @@
 import { watch } from "chokidar";
 import { readFileSync, existsSync } from "node:fs";
 import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
 
 export const name = "dsh-hot-reload";
 
@@ -131,65 +132,6 @@ export function apply(ctx, config = {}) {
     }
   }
 
-  // ctx.inject, NOT a module-level `export const inject`, and NOT a one-shot
-  // ctx.get. The distinction matters three ways:
-  //
-  //  - a module-level inject is REQUIRED (Inject.resolve maps every declared
-  //    name to a wait), so it would park the whole plugin forever in a profile
-  //    that has no web server — tui would stop reloading anything at all;
-  //  - ctx.inject parks only this CHILD fiber, leaving the reloader running;
-  //  - ctx.get would be both racy and one-shot. It resolves strictly, returning
-  //    undefined unless the providing fiber is already ACTIVE, and WebServer
-  //    only becomes active after its async listen() binds — while loader entries
-  //    start concurrently, so whether we win that race is chance. Being a single
-  //    read, it also never recovers: a web server that reloads (port change, a
-  //    dsh HMR cycle) comes back with an empty route table and nothing would
-  //    re-register. ctx.inject re-runs this body on exactly that event.
-  ctx.inject(["webServer"], (webCtx) => {
-    // Acquire and release in one effect, as dsh's own client-hmr channel does:
-    // the disposer drops the route and every open stream when this child fiber
-    // unloads — on shutdown, and before the body re-runs for a replaced server.
-    webCtx.effect(() => {
-      let disposeRoute;
-      try {
-        disposeRoute = webCtx.webServer.register({
-          kind: "exact",
-          path: EVENTS_ENDPOINT,
-          handler: (req, res) => {
-            if (req.method !== "GET" && req.method !== "HEAD") {
-              res.writeHead(405);
-              res.end();
-              return;
-            }
-            res.writeHead(200, {
-              "content-type": "text/event-stream",
-              "cache-control": "no-cache",
-              connection: "keep-alive",
-            });
-            res.write(": connected\n\n");
-            connections.add(res);
-            res.on("close", () => connections.delete(res));
-          },
-        });
-      } catch (err) {
-        // Duplicate path (a second dsh-hot-reload row) or a webserver API change.
-        // The notices are optional; the reloader is not — degrade, never throw.
-        log.warn?.("dsh-hot-reload: could not register the notice channel; web notices are disabled");
-        log.warn?.(err);
-        return () => {};
-      }
-      return () => {
-        disposeRoute();
-        for (const res of connections) {
-          try {
-            res.destroy();
-          } catch {}
-        }
-        connections.clear();
-      };
-    }, "dsh-hot-reload: notice channel");
-  });
-
   // ---- package <-> loader-entry helpers ----
 
   /** Package name backing a loader entry's module specifier, or null for local/builtin. */
@@ -205,11 +147,20 @@ export function apply(ctx, config = {}) {
   }
 
   // Versions come from node_modules/<pkg>/package.json, never from the lockfile
-  // we watch: pnpm writes the lockfile BEFORE materializing node_modules, so a
-  // cycle triggered by that write can see the new version there while the old
-  // code is still on disk — re-importing would load the OLD module while
-  // committing the NEW version as loaded. The lockfile is the trigger; the
-  // installed package.json is the truth about what an import would actually get.
+  // we watch. The lockfile records what pnpm RESOLVED; only the installed
+  // package.json describes what an import would actually get, and nothing ties
+  // the write we observe to the state of the tree on disk.
+  //
+  // Measured on pnpm 11.21.0 (`add`, `update` and `install`, four runs): the
+  // tree is materialized FIRST and the lockfile written LAST, 20-40ms after the
+  // final package lands — so a cycle triggered by that write reads settled
+  // versions. The design does not DEPEND on that order, but it is exposed to
+  // it: a pnpm that wrote the lockfile first would have a cycle read stale
+  // versions, `continue` past them, and never re-arm, because nothing but the
+  // lockfile is watched — the upgrade would be lost silently and permanently.
+  // The debounce is no defense; the materialization window measured 2.5-4s.
+  // A settle/confirm pass would close it. Not implemented; see README
+  // "Limitations", which states the exposure plainly.
   function readPkgJson(pkg) {
     try {
       return JSON.parse(readFileSync(join(nodeModules, pkg, "package.json"), "utf8"));
@@ -322,6 +273,49 @@ export function apply(ctx, config = {}) {
     } catch {}
   }
 
+  /** Directory, as a trailing-slash file:// URL, of the nearest ancestor that
+   *  has a package.json — the package this module belongs to. A version bump
+   *  rewrites every file inside it in place under a hoisted linker, so a reload
+   *  must drop the whole directory, not just the entry. Returns null when no
+   *  package.json is found (defensive; a node_modules package always has one). */
+  function packageRootUrlOf(url) {
+    let dir = dirname(fileURLToPath(url));
+    for (;;) {
+      if (existsSync(join(dir, "package.json"))) {
+        const href = pathToFileURL(dir).href;
+        return href.endsWith("/") ? href : `${href}/`;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  }
+
+  /** Invalidate every cached module under one package directory — the entry and
+   *  its transitive in-package imports. Re-importing only the entry would leave
+   *  `./routes.js` and friends on their stale cache entries (the URLs are
+   *  unchanged under a hoisted linker), so the running plugin would mix old and
+   *  new code. Shared dependencies live OUTSIDE this directory and are left
+   *  alone: re-importing them would be wasteful and would fork shared classes. */
+  function invalidateTree(rootUrl) {
+    if (!rootUrl) return;
+    // ESM loadCache.
+    try {
+      for (const u of Map.prototype.keys.call(internal.loadCache)) {
+        if (typeof u === "string" && u.startsWith(rootUrl)) {
+          Map.prototype.delete.call(internal.loadCache, u);
+        }
+      }
+    } catch {}
+    // CJS: modules imported via import() also land in the require cache on Node 24.
+    try {
+      const rootPath = fileURLToPath(rootUrl);
+      for (const fp of Object.keys(cjsRequire.cache)) {
+        if (fp.startsWith(rootPath)) delete cjsRequire.cache[fp];
+      }
+    } catch {}
+  }
+
   /** Reload one loaded entry's module in place. Throws on failure, after rolling
    *  the old plugin back — except when teardown began mid-reload, where it drops
    *  the new plugin and does NOT roll back (the dying context disposes what is
@@ -340,7 +334,14 @@ export function apply(ctx, config = {}) {
     const url = await resolveUrl(specifier, parentURL);
     if (!url) throw new Error(`could not resolve ${specifier}`);
 
-    invalidate(url); // matters for in-place edits; harmless no-op for a version bump (new realpath)
+    // Drop the whole package directory, not just the entry: under a hoisted
+    // linker a version bump rewrites files in place (same URLs), so the entry's
+    // relative imports would otherwise re-hit the stale cache and mix old and
+    // new code. Falls back to the single-URL invalidation only when no
+    // package.json is found.
+    const rootUrl = packageRootUrlOf(url);
+    if (rootUrl) invalidateTree(rootUrl);
+    else invalidate(url);
 
     // Read the version as close to the import as possible: this is what the
     // fresh module actually is, and the only value safe to commit.
@@ -417,13 +418,23 @@ export function apply(ctx, config = {}) {
 
     if (!live.length) {
       if (!fiberless) return version; // only disabled rows — nothing to do, nothing to say
-      // Enabled but nothing attached: mid-import or a load failure. Say so once,
+      // Enabled but nothing attached: mid-import or a load failure. Say so,
       // don't commit, and stay retryable — no reload was attempted, so a plugin
       // that was merely still activating picks this up on a later event.
-      report(
-        "stale",
-        `${pkg}@${version} has no live fiber to reload right now — restart dsh if it stays on the old version`
-      );
+      //
+      // Announce it at most once per version, though. Staying retryable means
+      // the version is deliberately NOT committed, so every later lockfile
+      // write — including ones for entirely unrelated packages — re-detects the
+      // same change and would re-announce it. Tolerable as a log line; as an
+      // undismissable banner it would follow the user through routine `pnpm
+      // add` work forever. Only the announcing is suppressed; the retry is not.
+      if (noticedVersions[pkg] !== version) {
+        noticedVersions[pkg] = version;
+        report(
+          "stale",
+          `${pkg}@${version} has no live fiber to reload right now — restart dsh if it stays on the old version`
+        );
+      }
       return false;
     }
     if (fiberless) {
@@ -470,6 +481,7 @@ export function apply(ctx, config = {}) {
   // silently (old code keeps running, no notice). Deliberate, not an oversight.
   let versions = boot ? currentVersions(boot) : null;
   const failedVersions = Object.create(null); // pkg -> version whose reload failed (never retried)
+  const noticedVersions = Object.create(null); // pkg -> version already announced on a retryable path
   let timer = null;
   let pending = false; // at most ONE cycle queued behind the running one; bursts coalesce into it
   let disposed = false;
@@ -513,6 +525,7 @@ export function apply(ctx, config = {}) {
       } else if (commit) {
         versions[pkg] = commit; // the version actually imported, not the cycle-start one
         delete failedVersions[pkg];
+        delete noticedVersions[pkg];
       }
       // commit === false: not attempted (teardown, or nothing attached yet) —
       // leave it uncommitted and retryable on a later event.
@@ -525,6 +538,7 @@ export function apply(ctx, config = {}) {
       if (!(pkg in snap)) {
         delete versions[pkg];
         delete failedVersions[pkg];
+        delete noticedVersions[pkg];
       }
     }
   }
@@ -564,6 +578,89 @@ export function apply(ctx, config = {}) {
     } catch {}
   });
 
+  // ---- notice channel ----
+  //
+  // LAST on purpose, and wrapped. Everything above is the reloader; everything
+  // here is an optional extra surface for talking about it. Registered earlier,
+  // any throw from this block would abort apply() before the watcher exists —
+  // so a change in a cordis API this plugin only uses for NOTICES would cost the
+  // reloading too, and dsh's boot sweep turns a FAILED entry into a refusal to
+  // start at all. Ordered and guarded, the worst case is "no banners".
+  //
+  // ctx.inject, NOT a module-level `export const inject`, and NOT a one-shot
+  // ctx.get. The distinction matters three ways:
+  //
+  //  - a module-level inject is REQUIRED (Inject.resolve maps every declared
+  //    name to a wait), so it would park the whole plugin forever in a profile
+  //    that has no web server — tui would stop reloading anything at all;
+  //  - ctx.inject parks only this CHILD fiber, leaving the reloader running;
+  //  - ctx.get would be both racy and one-shot. It resolves strictly, returning
+  //    undefined unless the providing fiber is already ACTIVE, and WebServer
+  //    only becomes active after its async listen() binds — while loader entries
+  //    start concurrently, so whether we win that race is chance. Being a single
+  //    read, it also never recovers: a web server that reloads (port change, a
+  //    dsh HMR cycle) comes back with an empty route table and nothing would
+  //    re-register. ctx.inject re-runs this body on exactly that event.
+  try {
+    ctx.inject(["webServer"], (webCtx) => {
+      // Acquire and release in one effect, as dsh's own client-hmr channel does:
+      // the disposer drops the route and every open stream when this child fiber
+      // unloads — on shutdown, and before the body re-runs for a replaced server.
+      webCtx.effect(() => {
+        let disposeRoute;
+        try {
+          disposeRoute = webCtx.webServer.register({
+            kind: "exact",
+            path: EVENTS_ENDPOINT,
+            handler: (req, res) => {
+              if (req.method === "HEAD") {
+                // Node discards a HEAD response body, so the usual stream would
+                // never reach the caller: it would block until its own timeout
+                // while its socket sat in `connections` collecting writes nobody
+                // reads. Health checks and link prefetchers do send HEAD.
+                // Answer what the headers would be, then close.
+                res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+                res.end();
+                return;
+              }
+              if (req.method !== "GET") {
+                res.writeHead(405);
+                res.end();
+                return;
+              }
+              res.writeHead(200, {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+              });
+              res.write(": connected\n\n");
+              connections.add(res);
+              res.on("close", () => connections.delete(res));
+            },
+          });
+        } catch (err) {
+          // Duplicate path (a second dsh-hot-reload row) or a webserver API change.
+          // The notices are optional; the reloader is not — degrade, never throw.
+          log.warn?.("dsh-hot-reload: could not register the notice channel; web notices are disabled");
+          log.warn?.(err);
+          return () => {};
+        }
+        return () => {
+          disposeRoute();
+          for (const res of connections) {
+            try {
+              res.destroy();
+            } catch {}
+          }
+          connections.clear();
+        };
+      }, "dsh-hot-reload: notice channel");
+    });
+  } catch (err) {
+    log.warn?.("dsh-hot-reload: could not set up the notice channel; web notices are disabled");
+    log.warn?.(err);
+  }
+
   log.info?.(
     `dsh-hot-reload: watching ${lockfile} (${Object.keys(versions ?? {}).length} plugin package(s) tracked)`
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hot-reload",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Live-reload upgraded DeepSeek Harness (dsh) plugins without restarting dsh \u2014 the running plugin is swapped in place, and a reload that fails rolls back to the working old version and asks for a manual restart.",
   "keywords": [
@@ -36,7 +36,7 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "README.zh.md",
+    "README-zh.md",
     "CHANGELOG.md",
     "LICENSE"
   ],