dsh-hot-reload 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -3,6 +3,96 @@
 All notable changes to `dsh-hot-reload` are documented here. This project
 follows [semantic versioning](https://semver.org/).
 
+## 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:
+`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 +183,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

@@ -36,12 +36,81 @@ 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).
 
+## 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 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.
+
+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 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
+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
@@ -68,13 +137,32 @@ 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) |
 | `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 +205,21 @@ 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
+  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

@@ -30,11 +30,72 @@ 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**——重启交给你（以及你的守护进程，如果有的话）。
 
+## 你如何知道发生了什么
+
+插件会把每个结果写进 dsh 的日志。但 dsh 不会把日志打印到你的终端，所以这些内容
+很容易被忽略。另有两个地方会告诉你发生了什么。
+
+**1. 每次重载成功，在你的终端里输出一行。** 任意 profile 都有：
+
+```
+dsh-hot-reload: hot-reloaded some-plugin@1.2.0 (1 module(s))
+```
+
+**2. dsh web 应用里的一条短提示。** 重载成功时会出现一条。凡是新代码*没有*加载、
+旧代码仍在运行的情况，也都会出现一条：
+
+- 重载失败，已换回旧版本
+- 该插件没有正在运行的副本可供替换
+- 该插件用 `dsh.hotReload: false` 关闭了热重载
+- dsh 没有提供重载所需的内部接口
+
+其中第二种情况是**每个版本只提示一次**，而不是每次检查都提示。这种情况在此后
+每次 lockfile 写入时都会重试——包括为别的包发生的写入——所以若不加这个限制，
+同一条提示会反复出现，而且没有办法关掉它。另外三种情况每次发生都会提示。
+
+提示会滑入，停留数秒，然后淡出。如果一次升级重载了多个插件，提示会排队逐条显示。
+
+web 那一部分只在运行 web 服务器的 profile 中加载，并通过
+`GET /dsh-hot-reload/events` 发送提示。没有 web 服务器的 profile（例如 `tui`）
+仍然有终端那一行和日志。
+
+提示不会被保存。如果重载发生时没有打开任何浏览器标签页，那条提示就没有了。
+日志里仍有记录。
+
+如果你在标签页开着的时候重启 dsh，标签页会自己重新建立通道，提示继续可用。
+它大约会尝试三分钟。若仍然连不上，就在浏览器控制台写一行提示并停止重试；
+刷新页面即可重新开始。
+
+### 如果你想在终端里看到全部内容
+
+上面那一行只覆盖成功的重载。若想看到本插件写进日志的全部内容（包括失败），请把
+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
@@ -60,12 +121,29 @@ 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） |
 | `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 +180,17 @@ dsh plugin --profile web add some-plugin@newer   # 自动热重载
 - 重载路径依赖[兼容性](#兼容性)一节列出的 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`，请把它
+  算作局域网里任何人都能打开的又一个地址。
 
 范围说明：本插件处理的是**已加载插件的升级**。安装一个**全新**插件是另一回事
 （把它的行加入 `cordis.patch.yml`，这个 dsh 本身已经会热应用）。

package/lib/client.js

@@ -0,0 +1,213 @@
+// 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";
+
+    /** 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. */
+    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;
+        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];
+      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,57 @@ 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
+    }
+  }
+
   // ---- package <-> loader-entry helpers ----
 
   /** Package name backing a loader entry's module specifier, or null for local/builtin. */
@@ -84,11 +146,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"));
@@ -286,22 +357,33 @@ 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;
     }
 
     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.
-      log.warn?.(
-        `dsh-hot-reload: ${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) {
@@ -325,12 +407,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
@@ -347,6 +430,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;
@@ -390,6 +474,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.
@@ -402,6 +487,7 @@ export function apply(ctx, config = {}) {
       if (!(pkg in snap)) {
         delete versions[pkg];
         delete failedVersions[pkg];
+        delete noticedVersions[pkg];
       }
     }
   }
@@ -441,6 +527,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.1.4",
+  "version": "0.2.1",
   "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": {