dsh-hot-reload 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 All notable changes to `dsh-hot-reload` are documented here. This project
 follows [semantic versioning](https://semver.org/).
 
+## 0.2.0
+
+You can now see reload results without reading the logs. Config did not change:
+`debounce` and `profileDir` are still the only keys. Detection and reloading did
+not change either.
+
+**New messages**
+
+- **One terminal line for each reload that worked.** dsh never prints its log to
+  the terminal, so until now nothing this plugin wrote showed up there. A
+  successful reload now also writes one line. This works in every profile.
+- **A short pop-up message in the dsh web app.** You get one when a reload works,
+  and one in every case that leaves the old code running: a reload that failed
+  and was rolled back, a plugin with no running copy, `dsh.hotReload: false`, and
+  missing loader internals. If one upgrade reloads several plugins, the messages
+  show one after another.
+- The web part ships as `lib/client.js` (`exports["./client"]`, plus `dsh.client`
+  with `platform: "web"`) and attaches to the `shell.overlay` slot. It is written
+  by hand in the format the browser loader expects, so this package still has
+  **no build step** and **no new dependencies**. `react` and
+  `@deepseek-ai/dsh-client-ui-primitives` come from the web app's own modules.
+- Messages travel over a `GET /dsh-hot-reload/events` route added to
+  `ctx.webServer`. Nothing is saved: if no browser is connected, the message is
+  gone. The log is still the lasting record.
+- One `report()` call now writes the log line, the terminal line, and the browser
+  message from a single message string, so those surfaces cannot disagree.
+
+**When parts are missing**
+
+- The route is added through `ctx.inject(["webServer"], …)`. A top-level `inject`
+  would have made the whole plugin wait forever in a profile with no web server,
+  because cordis treats every injected name as required — `tui` would have
+  stopped reloading anything. A single `ctx.get` call would have been unreliable:
+  it only returns a service once that service is fully started, and the web
+  server starts later, after it opens its socket. It would also never recover if
+  the web server were replaced. `ctx.inject` only makes a small child part wait,
+  and it registers the route again each time the web server is replaced.
+- A missing web server, a repeated route, a renamed slot, a browser module that
+  no longer loads, or a dsh build without `Toast` each cost you the pop-up only.
+  Reloading still works and the web app still starts.
+- If the message channel cannot be reached at all, the browser half says so once
+  in the console instead of staying quiet. Otherwise a dead channel looks exactly
+  like "no reloads have happened yet".
+
 ## 0.1.4
 
 Two rounds of code-review fixes (engine + CI). No config or API changes.
@@ -93,11 +137,11 @@ Two rounds of code-review fixes (engine + CI). No config or API changes.
   skipped the release). E404 is detected structurally via `--json` rather than
   by grepping npm's error prose.
 - Concurrency is keyed per tag, so distinct releases never share a queue slot
-  (a shared group could silently cancel a pending release's run). Because that
-  allows two releases to publish concurrently, a post-publish step re-points
-  `latest` at the highest published version — `npm publish` sets `latest`
-  unconditionally, so otherwise the run finishing last would win regardless of
-  version order.
+  (a shared group could silently cancel a pending release's run). Two releases
+  cut within a couple of minutes can therefore publish concurrently, leaving
+  the `latest` dist-tag on whichever finished last; releases are cut one at a
+  time and the repair is a single `npm dist-tag add`, so this is accepted
+  rather than automated.
 
 ## 0.1.3
 

package/README.md

@@ -42,6 +42,63 @@ Two cases produce no reload, by design:
 It **never restarts dsh for you** — restarting is left to you (and your
 supervisor, if any).
 
+## How you see what happened
+
+The plugin writes every result to dsh's log. But dsh does not print its log to
+your terminal, so those lines are easy to miss. Two extra places show you what
+happened.
+
+**1. One line in your terminal, for each reload that worked.** You get this in
+every profile:
+
+```
+dsh-hot-reload: hot-reloaded some-plugin@1.2.0 (1 module(s))
+```
+
+**2. A short pop-up message in the dsh web app.** You get one when a reload
+works. You also get one in every case where the new code did *not* load, so the
+old code is still running:
+
+- the reload failed, and the old version was put back
+- the plugin has no running copy to swap out
+- the plugin turned off hot reload with `dsh.hotReload: false`
+- dsh did not provide the internal parts the reload needs
+
+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.
+
+The web part only loads in a profile that runs a web server. It sends the
+messages over `GET /dsh-hot-reload/events`. A profile with no web server, such
+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 want every line in your terminal
+
+The terminal line above only covers reloads that worked. To see everything this
+plugin writes to the log, including failures, add dsh's console logger to your
+profile. It is a separate package:
+
+```sh
+dsh plugin --profile web add @deepseek-ai/cordis-plugin-logger-console
+```
+
+Then add a row for it in that profile's `cordis.patch.yml` and restart dsh:
+
+```yaml
+- insert:
+    - id: logger-console
+      name: '@deepseek-ai/cordis-plugin-logger-console'
+```
+
+This prints all dsh log lines, not only this plugin's.
+
+> **Note for full-screen profiles.** The terminal line is written straight to the
+> screen. In a profile that draws a full-screen interface, such as `tui`, the
+> line can land in the middle of the drawing and make the screen look wrong. It
+> looks wrong only until the screen is drawn again.
+
 ## Install
 
 ```sh
@@ -73,8 +130,26 @@ future dsh that changes any of them may require an update:
 | `entry.disabled` | skipping disabled rows (inherited getter) |
 | `entry.options.group` | skipping group container rows |
 
-It fails safe: if the internals it needs are missing, it degrades to reporting
-"restart needed" rather than breaking dsh.
+The pop-up message in the web app (and only that part) also uses:
+
+| dsh part | Used for |
+|---|---|
+| `ctx.webServer.register` | serving the message channel |
+| `window.__ModuleLoader__` | loading the browser half |
+| the `shell.overlay` slot | placing the message over the app |
+| `Toast` from `@deepseek-ai/dsh-client-ui-primitives` | drawing it |
+
+The plugin fails safe. If a part it needs is missing, it reports "restart needed"
+instead of breaking dsh. The pop-up behaves the same way. A missing web server,
+a browser module it cannot load, an unknown slot, a repeated registration, or a
+dsh build with no `Toast` each cost you the pop-up only. Reloading still works,
+and the web app still starts.
+
+One exception: the browser half asks dsh for a service named `slots`. dsh's web
+app refuses to start if any plugin never becomes ready. So if some future dsh
+build had no `slots` service at all, this part would wait forever and show up in
+dsh's start-up error list. Every other failure listed above is caught and simply
+does nothing.
 
 ## Opting out
 
@@ -117,6 +192,11 @@ 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 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
+  secret. But if you bind dsh to `0.0.0.0`, count it as one more address that
+  anyone on your network can open.
 
 Scope note: this handles **upgrades of already-loaded plugins**. Installing a
 *brand-new* plugin is a separate concern (adding its row to `cordis.patch.yml`,

package/README.zh.md

@@ -35,6 +35,57 @@ dsh 自带的热重载（`cordis-plugin-hmr`）刻意忽略 `node_modules`，所
 
 它**绝不会替你重启 dsh**——重启交给你（以及你的守护进程，如果有的话）。
 
+## 你如何知道发生了什么
+
+插件会把每个结果写进 dsh 的日志。但 dsh 不会把日志打印到你的终端，所以这些内容
+很容易被忽略。另有两个地方会告诉你发生了什么。
+
+**1. 每次重载成功，在你的终端里输出一行。** 任意 profile 都有：
+
+```
+dsh-hot-reload: hot-reloaded some-plugin@1.2.0 (1 module(s))
+```
+
+**2. dsh web 应用里的一条短提示。** 重载成功时会出现一条。凡是新代码*没有*加载、
+旧代码仍在运行的情况，也都会出现一条：
+
+- 重载失败，已换回旧版本
+- 该插件没有正在运行的副本可供替换
+- 该插件用 `dsh.hotReload: false` 关闭了热重载
+- dsh 没有提供重载所需的内部接口
+
+提示会滑入，停留数秒，然后淡出。如果一次升级重载了多个插件，提示会排队逐条显示。
+
+web 那一部分只在运行 web 服务器的 profile 中加载，并通过
+`GET /dsh-hot-reload/events` 发送提示。没有 web 服务器的 profile（例如 `tui`）
+仍然有终端那一行和日志。
+
+提示不会被保存。如果重载发生时没有打开任何浏览器标签页，那条提示就没有了。
+日志里仍有记录。
+
+### 如果你想在终端里看到全部内容
+
+上面那一行只覆盖成功的重载。若想看到本插件写进日志的全部内容（包括失败），请把
+dsh 的控制台日志插件加进你的 profile。它是一个独立的包：
+
+```sh
+dsh plugin --profile web add @deepseek-ai/cordis-plugin-logger-console
+```
+
+然后在该 profile 的 `cordis.patch.yml` 中加入一行，并重启 dsh：
+
+```yaml
+- insert:
+    - id: logger-console
+      name: '@deepseek-ai/cordis-plugin-logger-console'
+```
+
+这会打印 dsh 的所有日志，而不只是本插件的。
+
+> **全屏界面 profile 的注意事项。** 终端那一行是直接写到屏幕上的。在绘制全屏
+> 界面的 profile（例如 `tui`）中，这一行可能落在画面中间，让屏幕看起来乱掉。
+> 这只会持续到屏幕下一次重绘为止。
+
 ## 安装
 
 ```sh
@@ -65,7 +116,23 @@ dsh plugin --profile web add some-plugin@newer   # 自动热重载
 | `entry.disabled` | 跳过已禁用的行（继承式 getter） |
 | `entry.options.group` | 跳过 group 容器行 |
 
-它是失败安全的：一旦所需内部不可用，会退化为报告“需要重启”，而不会弄坏 dsh。
+web 应用里的提示（且仅这一部分）还用到：
+
+| dsh 的部件 | 用途 |
+|---|---|
+| `ctx.webServer.register` | 提供提示通道 |
+| `window.__ModuleLoader__` | 加载浏览器侧那一半 |
+| `shell.overlay` 插槽 | 把提示放到应用之上 |
+| `@deepseek-ai/dsh-client-ui-primitives` 的 `Toast` | 绘制提示 |
+
+本插件是失败安全的。若所需部件缺失，它会报告“需要重启”，而不会弄坏 dsh。提示
+也一样：缺少 web 服务器、浏览器模块加载不了、插槽名未知、重复注册、或 dsh 构建
+中没有 `Toast`，代价都只是没有提示。重载照常工作，web 应用也照常启动。
+
+有一个例外：浏览器侧那一半会向 dsh 索取名为 `slots` 的服务。只要有任何插件始终
+没有就绪，dsh 的 web 应用就会拒绝启动。所以，假如将来某个 dsh 构建完全没有
+`slots` 服务，这一部分就会一直等待，并出现在 dsh 的启动错误列表里。上面列出的
+其他失败都会被捕获，只是什么都不做。
 
 ## 退出热重载（opt-out）
 
@@ -102,6 +169,10 @@ dsh plugin --profile web add some-plugin@newer   # 自动热重载
 - 重载路径依赖[兼容性](#兼容性)一节列出的 cordis/loader 内部接口。若这些内部
   不可用（既无 `--expose-internals`，也无 `node-addon-require-builtin` 原生
   插件），本插件会退化为对每次变化只报告“需要重启”，而不做重载。
+- 提示通道（`GET /dsh-hot-reload/events`）**不做任何密码校验**，与 dsh 自带的
+  `/plugins/events` 相同。它发送的是插件名和版本号。dsh 的插件列表本来就会显示
+  这些内容，所以并没有多暴露什么秘密。但如果你把 dsh 绑定到 `0.0.0.0`，请把它
+  算作局域网里任何人都能打开的又一个地址。
 
 范围说明：本插件处理的是**已加载插件的升级**。安装一个**全新**插件是另一回事
 （把它的行加入 `cordis.patch.yml`，这个 dsh 本身已经会热应用）。

package/lib/client.js

@@ -0,0 +1,167 @@
+// dsh-hot-reload — web half: raise a transient banner when the host half
+// reloads (or fails to reload) a plugin package.
+//
+// This file is hand-written in the shape a built client bundle takes, because
+// the package deliberately has no build step: a classic script that REGISTERS a
+// factory with the browser module loader, whose body runs at materialization
+// rather than at script execution. Consequences for editing it:
+//
+//   - no JSX (React.createElement instead) and no import/export syntax — the
+//     factory takes a synchronous `require` and RETURNS its exports;
+//   - only the platform seed modules may be required, under their exact keys:
+//     react, react/jsx-runtime, react-dom, react-dom/client,
+//     @deepseek-ai/cordis, and the @deepseek-ai/dsh-client-{ui-slots,
+//     web-react, ui-primitives, ui-attachment, schema-form} set. They come from
+//     the web shell's own build, so this half needs no other plugin bundle;
+//   - `id` must be the package name: the loader resolves "<id>/client" and the
+//     bare id to these same exports.
+//
+// The host half only serves this to browsers (package.json's dsh.client pins
+// platform "web"), and nothing here is required for reloading to work. Every
+// failure path below degrades to "no banner" — but note the shell fails its
+// boot if a plugin entry never activates, so a throw at factory scope would
+// cost the page: that is why the requires are guarded rather than bare.
+
+window.__ModuleLoader__.load({
+  id: "dsh-hot-reload",
+  factory: (require) => {
+    // Guarded because a throw here escapes the factory, leaves this entry
+    // without a fiber, and the web shell's boot-time sweep turns any entry that
+    // did not reach ACTIVE into a thrown boot failure — i.e. an unguarded
+    // require miss costs the whole page, not just the banner. Degrade to a
+    // no-op plugin instead, so the entry still activates.
+    let React = null;
+    let primitives = null;
+    let seedError = null;
+    try {
+      React = require("react");
+      primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+    } catch (error) {
+      seedError = error;
+    }
+
+    /** Must match EVENTS_ENDPOINT in lib/index.js. The two halves ship as
+     *  separate bundles with no module in common, so this constant is duplicated
+     *  rather than shared — change one, change the other. */
+    const EVENTS_ENDPOINT = "/dsh-hot-reload/events";
+
+    /** Root-scoped list slot that the shell frame renders over the whole app,
+     *  and dsh's documented home for a plugin's own floating surface. Root scope
+     *  matters here: reloads are triggered from a terminal, so a notice must be
+     *  able to appear with no conversation open. (The `root` slot itself is
+     *  single-occupancy — registering there would shadow the entire app frame.) */
+    const SLOT = "shell.overlay";
+
+    /** Cordis plugin name. */
+    const name = "dsh-hot-reload";
+    /** Required services: the slot registry this half contributes its banner to. */
+    const inject = ["slots"];
+
+    /** Leading glyphs, built once: `primitives` is fixed for the life of the
+     *  factory, so rebuilding these per render would only churn element identity
+     *  and force the icon span to reconcile. Undefined when this dsh build no
+     *  longer ships the icon — the banner reads fine without one. */
+    const icon = (Icon) => (typeof Icon === "function" ? React.createElement(Icon) : undefined);
+    const ICONS = seedError !== null ? {} : {
+      reloaded: icon(primitives.IconRefreshOutline16),
+      other: icon(primitives.IconWarningOutline16),
+    };
+
+    /**
+     * The shell.overlay entry: subscribes to the host's notice channel and shows
+     * one banner at a time, oldest first.
+     *
+     * Notices queue rather than replace: one lockfile write can reload several
+     * packages, and showing only the newest would silently drop the rest.
+     *
+     * @param props.warn - reports a dead channel; supplied by apply() through the
+     * wrapper it registers, so nothing about this component is factory-global and
+     * a second plugin row cannot repoint the first row's logger.
+     */
+    function ReloadNotices({ warn }) {
+      const [queue, setQueue] = React.useState([]);
+      // Stable identity is load-bearing: Toast restarts its hold-and-fade timer
+      // whenever `onDone` changes, so a fresh arrow per render would let a burst
+      // of arrivals keep resetting the banner already on screen instead of
+      // letting it finish and hand over to the next one.
+      const shift = React.useCallback(() => setQueue((q) => q.slice(1)), []);
+
+      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();
+      }, []);
+
+      const head = queue[0];
+      if (head === undefined) return null;
+      // Keyed by arrival sequence so two identical texts in a row remount and
+      // replay the slide/hold/fade, instead of reusing an already-faded banner.
+      return React.createElement(primitives.Toast, {
+        key: head.seq,
+        text: `dsh-hot-reload: ${head.text}`,
+        icon: head.kind === "reloaded" ? ICONS.reloaded : ICONS.other,
+        onDone: shift,
+      });
+    }
+
+    /**
+     * Client plugin body: mount the banner into the shell overlay.
+     * @param ctx - client root context.
+     */
+    function apply(ctx) {
+      if (seedError !== null) {
+        ctx.logger?.warn?.("dsh-hot-reload: a platform module is unavailable — reload notices disabled");
+        ctx.logger?.warn?.(seedError);
+        return;
+      }
+      if (typeof primitives.Toast !== "function") {
+        ctx.logger?.warn?.("dsh-hot-reload: this dsh build ships no Toast primitive — reload notices disabled");
+        return;
+      }
+      const warn = (message) => ctx.logger?.warn?.(message);
+      // slots.inject waits for the slot to be declared and disposes with this
+      // fiber, so an unknown slot name parks quietly instead of throwing.
+      ctx.slots.inject(SLOT, () => {
+        try {
+          return ctx.slots.register({ name: SLOT, id: "dsh-hot-reload.notices", order: 100 }, () =>
+            React.createElement(ReloadNotices, { warn })
+          );
+        } catch (error) {
+          // A changed registration contract, or a duplicate id from a second
+          // dsh-hot-reload row: lose the notices, never the page.
+          ctx.logger?.warn?.("dsh-hot-reload: could not mount reload notices");
+          ctx.logger?.warn?.(error);
+          return () => {};
+        }
+      });
+    }
+
+    // The loader takes the factory's return value AS the module exports, so the
+    // CJS `module.exports` preamble a built bundle carries is not needed here.
+    return { apply, inject, name };
+  },
+});

package/lib/index.js

@@ -16,6 +16,11 @@
 // Disabled rows are skipped silently (nothing is running to swap); an enabled
 // row with no fiber attached yet is reported and left for a later change.
 //
+// Outcomes are announced on two surfaces besides ctx.logger — one stderr line
+// per successful reload, and an SSE channel the browser half (lib/client.js)
+// turns into a transient toast. Both are additive and best-effort; see the
+// "notification surfaces" section in apply().
+//
 // NOTE: the reload path uses cordis/loader internals (loader.internal.loadCache,
 // registry.plugin/delete, fiber.entry) — the same ones HMR uses. If a future
 // cordis changes them, reloads will fail closed to "restart needed", never
@@ -32,6 +37,12 @@ export const name = "dsh-hot-reload";
 const getOuterStack = () => [];
 const cjsRequire = createRequire(import.meta.url);
 
+/** SSE channel the web half subscribes to for reload notices. Duplicated
+ *  verbatim in lib/client.js: the two halves are separate bundles (Node ESM
+ *  here, a browser classic script there) with no module in common, and this
+ *  package has no build step to generate a shared one from. */
+const EVENTS_ENDPOINT = "/dsh-hot-reload/events";
+
 /** handlePackage outcome: a reload was attempted and failed — never retry it. */
 const TERMINAL = Symbol("dsh-hot-reload:terminal");
 
@@ -69,6 +80,116 @@ export function apply(ctx, config = {}) {
     );
   }
 
+  // ---- notification surfaces ----
+  //
+  // Both are strictly ADDITIVE to ctx.logger, which stays the record of truth,
+  // and neither may throw into a reload cycle: a broken notification must never
+  // turn a working reload into a failed one.
+  //
+  //  - stderr, successful reloads only. cordis's logger fans messages out to
+  //    registered exporters, and the dsh host process registers none (only the
+  //    browser shell does), so nothing this plugin logs reaches the terminal dsh
+  //    runs in. One line per reload is the profile-independent baseline.
+  //  - an SSE channel the web half subscribes to (lib/client.js) and renders as
+  //    a transient toast. Registered only when a webServer service exists, so a
+  //    profile without one — tui — behaves exactly as it does today.
+  //
+  // Fire and forget: nothing is buffered and no delivery is confirmed. A notice
+  // raised while no browser is connected is simply lost. That is deliberate —
+  // the logger already holds the durable record, and replaying on connect would
+  // need a per-tab cursor to avoid re-announcing old reloads on every reload of
+  // the page itself.
+  const connections = new Set();
+
+  /** Announce one cycle outcome on every surface, from ONE message.
+   *
+   *  Call this for outcomes; call `log.*` directly for diagnostics. Writing the
+   *  message once is the point: an earlier version had each site author a log
+   *  string and a near-identical notice string, which is the one code path whose
+   *  whole job is telling the truth about what happened — the two can drift and
+   *  nothing catches it. Here the terminal and the banner cannot disagree.
+   *
+   *  `kind` is "reloaded" (it worked), "failed" (attempted and rolled back), or
+   *  "stale" (not attempted; the old code is still running). It selects the log
+   *  level and the browser's icon, and only "reloaded" reaches stderr. Callers
+   *  pass the bare message — every surface adds its own prefix. */
+  function report(kind, message) {
+    if (kind === "reloaded") {
+      log.info?.(`dsh-hot-reload: ${message}`);
+      try {
+        process.stderr.write(`dsh-hot-reload: ${message}\n`);
+      } catch {}
+    } else {
+      log.warn?.(`dsh-hot-reload: ${message}`);
+    }
+    if (!connections.size) return;
+    const line = `data: ${JSON.stringify({ type: "notice", kind, text: message })}\n\n`;
+    for (const res of connections) {
+      try {
+        res.write(line);
+      } catch {} // a half-dead socket is the browser's problem, not the reloader's
+    }
+  }
+
+  // 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. */
@@ -286,11 +407,11 @@ export function apply(ctx, config = {}) {
     const { version, live, fiberless } = rec;
 
     if (rec.json?.dsh?.hotReload === false) {
-      log.info?.(`dsh-hot-reload: ${pkg}@${version} sets dsh.hotReload:false — restart dsh to load the new version`);
+      report("stale", `${pkg}@${version} sets dsh.hotReload:false — restart dsh to load the new version`);
       return version;
     }
     if (!internal) {
-      log.info?.(`dsh-hot-reload: ${pkg}@${version} changed — restart dsh to load the new version`);
+      report("stale", `${pkg}@${version} changed — restart dsh to load the new version`);
       return version;
     }
 
@@ -299,8 +420,9 @@ export function apply(ctx, config = {}) {
       // Enabled but nothing attached: mid-import or a load failure. Say so once,
       // 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.
-      log.warn?.(
-        `dsh-hot-reload: ${pkg}@${version} has no live fiber to reload right now — restart dsh if it stays on the old version`
+      report(
+        "stale",
+        `${pkg}@${version} has no live fiber to reload right now — restart dsh if it stays on the old version`
       );
       return false;
     }
@@ -325,12 +447,13 @@ export function apply(ctx, config = {}) {
         committed ??= imported;
       }
       committed ??= version;
-      log.info?.(`dsh-hot-reload: hot-reloaded ${pkg}@${committed} (${live.length} module(s))`);
+      report("reloaded", `hot-reloaded ${pkg}@${committed} (${live.length} module(s))`);
       return committed;
     } catch (err) {
       if (disposed) return false; // aborted by teardown, not a real failure — stay quiet
-      log.warn?.(
-        `dsh-hot-reload: could not hot-reload ${pkg}@${version} — not retrying; restart dsh (or install a different version) to load it`
+      report(
+        "failed",
+        `could not hot-reload ${pkg}@${version} — not retrying; restart dsh (or install a different version) to load it`
       );
       log.warn?.(err);
       return TERMINAL; // attempted and failed: never retried for this version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hot-reload",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "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": [
@@ -29,6 +29,7 @@
   "main": "lib/index.js",
   "exports": {
     ".": "./lib/index.js",
+    "./client": "./lib/client.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -42,6 +43,9 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
     }
   },
   "dependencies": {