dsh-hot-reload 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -3,6 +3,121 @@
 All notable changes to `dsh-hot-reload` are documented here. This project
 follows [semantic versioning](https://semver.org/).
 
+## 0.1.4
+
+Two rounds of code-review fixes (engine + CI). No config or API changes.
+
+**Correct detection**
+
+- **One consistent view per cycle**: each cycle now enumerates loader entries
+  once and reads each `package.json` once (the sole exception being a deliberate
+  re-read at import time, which is what makes the committed version truthful),
+  and every decision uses that view. A
+  transient loader failure mid-cycle could previously make a detected upgrade
+  look like "not a loaded plugin", committing it as loaded while the old code
+  kept running — silently, forever.
+- **De-duplicate reloads by runtime, not specifier string** — aliased specifiers
+  (`pkg` vs `pkg/index.js`) resolving to one runtime no longer double-apply, and
+  one specifier mounted under two loader trees (two runtimes) now reloads both.
+- **Commit the version actually imported** — captured at import time inside the
+  reload, never re-read afterwards. A version that lands while a slow `apply()`
+  is still activating is therefore *not* recorded as loaded; it stays visible as
+  a change and is picked up on the next cycle, so the running code converges on
+  the newest version instead of silently stalling on an older one.
+- **Track by loader membership, not filesystem probes**: a package is dropped
+  when no loader entry is backed by it, not when a directory check fails. A
+  dangling pnpm symlink mid-swap can no longer evict a live plugin, and a
+  removed plugin row no longer stays tracked forever. A momentarily unreadable
+  `package.json` leaves the package tracked at its old version.
+- **Newly loaded rows are adopted, not reloaded** — dsh already loaded them.
+  A package whose `package.json` was unreadable at boot is tracked as
+  version-unknown rather than untracked, so its first readable version is
+  loaded instead of being mistaken for a fresh row and adopted silently.
+- **Disabled plugin rows are ignored**, using cordis's inherited `entry.disabled`
+  getter (an ancestor entry can disable a row, and the raw option may be a
+  `!!js` expression). Upgrading a disabled plugin no longer produces a spurious
+  "restart dsh" warning for something that isn't running. Group rows are skipped
+  too — they are containers, not plugin packages.
+- Degraded snapshots (`loader.entries()` throwing) leave state untouched; the
+  next event retries. If the loader is degraded at boot, the first successful
+  snapshot is simply adopted as the tracked state.
+
+**Honest reporting**
+
+- **A failed reload is never retried automatically.** Each attempt tears down
+  the working rolled-back plugin, and unrelated lockfile writes used to
+  re-trigger it indefinitely. One clear message says what to do (install a
+  different version, or restart dsh); later cycles stay quiet.
+- **No more false successes**: a changed package with no live fiber to reload
+  now warns and is *not* committed, instead of logging "hot-reloaded (0
+  module(s))". A package with a mix of live and fiberless entries reloads the
+  live ones and reports how many were skipped. An enabled row that simply has
+  no fiber *yet* (still importing) stays retryable — only a reload that was
+  attempted and failed is terminal.
+- **Explicit `profileDir` config always wins** — it is no longer silently
+  overridden by the auto-detected dir when its lockfile is missing.
+
+**Shutdown**
+
+- The disposer **never waits** on an in-flight reload, so dsh's shutdown can't
+  hang on an arbitrary plugin's `apply()`. A reload caught mid-activation by
+  teardown skips its rollback rather than re-registering fibers into a context
+  that is already tearing down — and if that activation *succeeds* after
+  teardown, the new plugin is dropped rather than left running (with its timers
+  and sockets live) past shutdown.
+- Lockfile churn during a long reload queues at most **one** follow-up cycle
+  instead of one per debounce window.
+
+**Docs**
+
+- `cordis.patch.yml` no longer advertises a **`reloadable` config key that was
+  never implemented** — a leftover from an abandoned opt-in design. The only
+  config keys are `debounce` and `profileDir`.
+- Corrected the "safe plugins are reloaded, unsafe ones are flagged" framing in
+  the package description and bundle patch: nothing judges a plugin's safety.
+  Every upgrade is attempted optimistically, a throw rolls back, and
+  `dsh.hotReload: false` is the only opt-out.
+- Both READMEs now document the disabled-row and not-yet-attached cases, and
+  list **every** cordis/loader internal the reload path depends on (previously
+  only three of six), which is what the Compatibility section is for.
+
+**CI**
+
+- Releases are now cut **only by pushing a `v*` tag**; pushes to `main` no
+  longer publish. One tag = one run = one version, which removes the E403 race
+  between the push- and tag-triggered runs of the same version.
+- The run **fails loudly** if the tag disagrees with `package.json`'s version,
+  if the version is a **prerelease** (this project publishes stable versions
+  only — an unflagged prerelease would land on the `latest` dist-tag), or if
+  `npm view` fails for a non-404 reason (previously a green run that silently
+  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.
+
+## 0.1.3
+
+Code-review fixes (engine + CI):
+
+- Reload each changed package **once per module**, not once per plugin row —
+  rows sharing a specifier share a runtime, so per-row reloading double-applied
+  and leaked a module instance.
+- **Serialize reload cycles** so a change arriving mid-reload can't run a second
+  cycle concurrently against the registry.
+- Commit the tracked version **only after a successful reload/skip**, so a failed
+  reload can be retried by re-installing the same version.
+- **Validate the profile dir** (warn if no `pnpm-lock.yaml`), and prefer a
+  candidate dir that actually contains the lockfile.
+- Disposer now awaits `watcher.close()` and guards against in-flight reloads via
+  a `disposed` flag.
+- CI: add a `concurrency` group so a commit+tag push can't race to publish
+  (E403); publish only on a confirmed `E404` (not on transient `npm view`
+  failures).
+
 ## 0.1.2
 
 - Docs: add a **Compatibility** section (built/tested against dsh `0.1.0-rc.6`;

package/README.md

@@ -25,6 +25,20 @@ On a plugin package upgrade, for each affected plugin:
   - a failure while *initializing* it (the new `apply` throws, sync **or** async)
     is rolled back — the old version is re-instantiated in place.
 
+  A version that failed is **not retried automatically** — retrying would tear
+  down the working plugin again on every later lockfile write. Install a
+  different version, or restart dsh, to pick the new code up.
+
+Two cases produce no reload, by design:
+
+- **Disabled plugin rows are skipped silently.** A disabled plugin isn't
+  running, so there is nothing to swap — and re-enabling it makes dsh load the
+  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.
+
 It **never restarts dsh for you** — restarting is left to you (and your
 supervisor, if any).
 
@@ -47,11 +61,20 @@ the profile it's loaded into.
 ## Compatibility
 
 Built and tested against **dsh `0.1.0-rc.6`** (Node 22 / 24). It reaches into
-cordis/loader internals shared with `cordis-plugin-hmr`
-(`loader.internal.loadCache`, `registry.plugin`/`delete`, `fiber.entry`), so a
-future dsh that changes those may require an update. It fails safe: if the
-internals it needs are missing, it degrades to reporting "restart needed" rather
-than breaking dsh.
+cordis/loader internals — mostly the same ones `cordis-plugin-hmr` uses — so a
+future dsh that changes any of them may require an update:
+
+| Internal | Used for |
+|---|---|
+| `loader.internal.loadCache` | invalidating the ESM module cache |
+| `loader.internal.resolve` / `resolveSync` | resolving a specifier to a URL (dispatched on `internal.version`) |
+| `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.
 
 ## Opting out
 
@@ -73,9 +96,9 @@ Set on the `hot-reload` row in your profile's `cordis.patch.yml`:
 
 ## Limitations — read this
 
-This plugin is **optimistic**, not verified. It attempts the reload and only
-falls back to "restart needed" on a **thrown** error. It does **not** detect
-*silent* leaks:
+This plugin is **optimistic**, not verified. It attempts the reload and falls
+back to "restart needed" only when something **throws** (or when there is no
+live fiber to swap). It does **not** detect *silent* leaks:
 
 - A plugin that acquires a **raw resource outside cordis** — a bare
   `setInterval`, a `net`/`http` server, a `WebSocketServer`, an `fs.watch`,
@@ -90,9 +113,8 @@ falls back to "restart needed" on a **thrown** error. It does **not** detect
 - Reloading a plugin that holds **live connections** (e.g. a WebSocket bridge)
   drops and re-establishes them; clients must reconnect. That's expected, not an
   error.
-- The reload path relies on cordis/loader internals
-  (`loader.internal.loadCache`, `registry.plugin`/`delete`, `fiber.entry`) — the
-  same ones `cordis-plugin-hmr` uses. If those internals are unavailable (no
+- The reload path relies on the cordis/loader internals listed under
+  [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.
 

package/README.zh.md

@@ -22,6 +22,17 @@ dsh 自带的热重载（`cordis-plugin-hmr`）刻意忽略 `node_modules`，所
   - 新代码在**初始化**阶段失败（新的 `apply` 抛错，**同步或异步**）会被回滚——
     旧版本就地重新实例化。
 
+  失败的版本**不会自动重试**——重试会在此后每次 lockfile 写入时再次拆除正在
+  正常工作的插件。请安装另一个版本，或重启 dsh，以加载新代码。
+
+有两种情况按设计不做重载：
+
+- **已禁用（disabled）的插件行会被静默跳过。** 已禁用的插件本就没在运行，没有
+  可替换的对象；重新启用时 dsh 自然会加载新代码。
+- **尚未挂上 fiber 的插件**（仍在导入中，或此前加载失败）会被报告为
+  `no live fiber to reload right now` 并原样保留。由于什么都没有被拆除，这种
+  情况**会**在下次 lockfile 变化时重新检查；若反复出现，请重启 dsh。
+
 它**绝不会替你重启 dsh**——重启交给你（以及你的守护进程，如果有的话）。
 
 ## 安装
@@ -41,11 +52,20 @@ dsh plugin --profile web add some-plugin@newer   # 自动热重载
 
 ## 兼容性
 
-基于并测试于 **dsh `0.1.0-rc.6`**（Node 22 / 24）。它会用到与 `cordis-plugin-hmr`
-共享的 cordis/loader 内部（`loader.internal.loadCache`、`registry.plugin`/
-`delete`、`fiber.entry`），因此未来若某个 dsh 版本改动了这些内部，可能需要更新
-本插件。它是失败安全的：一旦所需内部不可用，会退化为报告“需要重启”，而不会
-弄坏 dsh。
+基于并测试于 **dsh `0.1.0-rc.6`**（Node 22 / 24）。它会用到 cordis/loader 的内部
+接口——大多与 `cordis-plugin-hmr` 相同——因此未来若某个 dsh 版本改动了其中任何
+一项，可能需要更新本插件：
+
+| 内部接口 | 用途 |
+|---|---|
+| `loader.internal.loadCache` | 使 ESM 模块缓存失效 |
+| `loader.internal.resolve` / `resolveSync` | 把 specifier 解析为 URL（按 `internal.version` 分派） |
+| `registry.plugin` / `registry.delete` | 替换插件实例 |
+| `fiber.entry`、`fiber.runtime` | 把新插件重新挂到运行中的行上 |
+| `entry.disabled` | 跳过已禁用的行（继承式 getter） |
+| `entry.options.group` | 跳过 group 容器行 |
+
+它是失败安全的：一旦所需内部不可用，会退化为报告“需要重启”，而不会弄坏 dsh。
 
 ## 退出热重载（opt-out）
 
@@ -67,8 +87,8 @@ dsh plugin --profile web add some-plugin@newer   # 自动热重载
 
 ## 局限——务必阅读
 
-本插件是**乐观式**的，并非验证式。它尝试重载，且只在**抛出**错误时回退到
-“需要重启”。它**无法**检测*静默*泄漏：
+本插件是**乐观式**的，并非验证式。它尝试重载，且仅在**抛出**错误时（或没有可
+替换的活动 fiber 时）回退到“需要重启”。它**无法**检测*静默*泄漏：
 
 - 一个在 cordis 之外获取**裸资源**的插件——裸 `setInterval`、`net`/`http`
   服务器、`WebSocketServer`、`fs.watch`、`child_process`——**且没有用
@@ -79,11 +99,9 @@ dsh plugin --profile web add some-plugin@newer   # 自动热重载
   仅限于绕过 `ctx` 的插件。拿不准时，让这类插件设 `dsh.hotReload: false`。
 - 重载一个持有**活动连接**的插件（例如 WebSocket 桥接）会断开并重建这些连接；
   客户端需要重连。这是预期行为，不是错误。
-- 重载路径依赖 cordis/loader 内部（`loader.internal.loadCache`、
-  `registry.plugin`/`delete`、`fiber.entry`）——与 `cordis-plugin-hmr` 用的是同
-  一套。若这些内部不可用（既无 `--expose-internals`，也无
-  `node-addon-require-builtin` 原生插件），本插件会退化为对每次变化只报告
-  “需要重启”，而不做重载。
+- 重载路径依赖[兼容性](#兼容性)一节列出的 cordis/loader 内部接口。若这些内部
+  不可用（既无 `--expose-internals`，也无 `node-addon-require-builtin` 原生
+  插件），本插件会退化为对每次变化只报告“需要重启”，而不做重载。
 
 范围说明：本插件处理的是**已加载插件的升级**。安装一个**全新**插件是另一回事
 （把它的行加入 `cordis.patch.yml`，这个 dsh 本身已经会热应用）。

package/cordis.patch.yml

@@ -1,16 +1,15 @@
 # dsh-hot-reload bundle patch — mounts the watcher plugin that live-reloads
 # upgraded plugin packages without restarting dsh.
 #
-# Behavior: on a plugin package change it either hot-reloads the plugin in
-# place (if judged safe) or logs that a manual `dsh` restart is needed (if not).
-# It never restarts dsh itself. See README.md for the full safety model.
+# Behavior: on a plugin package upgrade it attempts a live reload, and on any
+# thrown error rolls back to the working old version and logs that a manual
+# `dsh` restart is needed. A plugin can opt out with `dsh.hotReload: false` in
+# its own package.json. It never restarts dsh itself. See README.md for the
+# limitations (silent leaks it cannot detect).
 - insert:
     - id: hot-reload
       name: 'dsh-hot-reload'
       # config:
-      #   # Extra package names you personally vouch are safe to hot-reload,
-      #   # even if they don't declare `dsh.hotReload: true` themselves.
-      #   reloadable: []
       #   # Debounce (ms) after a lockfile change before acting.
       #   debounce: 300
       #   # Absolute path to the profile dir to watch; auto-detected if omitted.

package/lib/index.js

@@ -13,6 +13,8 @@
 // ctx.effect disposer can reload without error yet leave that resource dangling.
 // A plugin can opt out of reload entirely with `dsh.hotReload: false` in its
 // package.json, which forces the restart-needed path without a reload attempt.
+// 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.
 //
 // NOTE: the reload path uses cordis/loader internals (loader.internal.loadCache,
 // registry.plugin/delete, fiber.entry) — the same ones HMR uses. If a future
@@ -20,16 +22,19 @@
 // crash dsh.
 
 import { watch } from "chokidar";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 
 export const name = "dsh-hot-reload";
 
 const getOuterStack = () => [];
 const cjsRequire = createRequire(import.meta.url);
 
+/** handlePackage outcome: a reload was attempted and failed — never retry it. */
+const TERMINAL = Symbol("dsh-hot-reload:terminal");
+
 export function apply(ctx, config = {}) {
   const log = ctx.logger ?? console;
   const loader = ctx.loader;
@@ -55,6 +60,14 @@ export function apply(ctx, config = {}) {
   }
   const lockfile = join(profileDir, "pnpm-lock.yaml");
   const nodeModules = join(profileDir, "node_modules");
+  // Validate the auto-detected dir loudly: watching a wrong/nonexistent lockfile
+  // would silently track 0 packages and never fire.
+  if (!existsSync(lockfile)) {
+    log.warn?.(
+      `dsh-hot-reload: no pnpm-lock.yaml at ${lockfile} — is this the profile dir? ` +
+        "set config.profileDir to fix; the plugin will watch but detect nothing until it appears."
+    );
+  }
 
   // ---- package <-> loader-entry helpers ----
 
@@ -70,6 +83,12 @@ export function apply(ctx, config = {}) {
     return specifier.split("/")[0];
   }
 
+  // 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.
   function readPkgJson(pkg) {
     try {
       return JSON.parse(readFileSync(join(nodeModules, pkg, "package.json"), "utf8"));
@@ -82,31 +101,71 @@ export function apply(ctx, config = {}) {
     return readPkgJson(pkg)?.version ?? null;
   }
 
-  function optedOut(pkg) {
-    return readPkgJson(pkg)?.dsh?.hotReload === false;
-  }
-
   function entries() {
     try {
       return [...loader.entries()];
     } catch {
-      return [];
+      return null; // degraded — callers must not confuse this with "no plugins loaded"
     }
   }
 
-  function entriesForPkg(pkg) {
-    return entries().filter((e) => pkgOf(e?.options?.name) === pkg);
+  /** One consistent per-cycle view: pkg -> { json, version, live, fiberless }
+   *  for every package backing a loader entry, built from a SINGLE loader
+   *  enumeration and a SINGLE package.json read per package (the whole cycle
+   *  consumes this, so a loader/fs hiccup after the diff can't be misread as
+   *  "not a loaded plugin"; `reloadEntry` deliberately re-reads the version at
+   *  import time, and nothing else does).
+   *
+   *  Every question about what a row IS gets answered here, once:
+   *   - group rows are containers, not plugin packages — excluded entirely;
+   *   - disabled rows aren't running, so there is nothing to reload and nothing
+   *     to report. `disabled` is an inherited getter (an ancestor entry can
+   *     disable a row, and the raw option may be a !!js expression node), so
+   *     never read options.disabled — excluded entirely;
+   *   - `live` holds one entry per RUNTIME: reloadEntry swaps all of a runtime's
+   *     fibers at once, so aliased specifiers ("pkg" vs "pkg/index.js") sharing
+   *     a runtime must reload once, while one specifier under two loader trees
+   *     is two runtimes and must reload twice;
+   *   - `fiberless` counts enabled rows with nothing attached (mid-import, or
+   *     failed to load) — reportable, but not reloadable.
+   *
+   *  Returns null when the loader can't enumerate right now — treating that as
+   *  "everything uninstalled" would wipe the tracked versions and spuriously
+   *  reload everything next cycle. A package whose package.json is momentarily
+   *  unreadable (mid pnpm swap) still appears, with version null. */
+  function snapshot() {
+    const list = entries();
+    if (!list) return null;
+    const pkgs = Object.create(null);
+    const seenRuntimes = new Map();
+    for (const e of list) {
+      if (e?.options?.group || e?.disabled) continue;
+      const pkg = pkgOf(e?.options?.name);
+      if (!pkg) continue;
+      let rec = pkgs[pkg];
+      if (!rec) {
+        const json = readPkgJson(pkg);
+        rec = pkgs[pkg] = { json, version: json?.version ?? null, live: [], fiberless: 0 };
+        seenRuntimes.set(pkg, new Set());
+      }
+      const runtime = e?.fiber?.runtime;
+      if (!runtime) {
+        rec.fiberless += 1;
+      } else if (!seenRuntimes.get(pkg).has(runtime)) {
+        seenRuntimes.get(pkg).add(runtime);
+        rec.live.push(e);
+      }
+    }
+    return pkgs;
   }
 
-  /** pkg -> installed version, across every package that backs a loaded entry. */
-  function snapshotVersions() {
+  /** Baseline map for a snapshot. A package whose version couldn't be read is
+   *  tracked with a null version rather than omitted: omitting it would make its
+   *  first readable version look like a brand-new row and get adopted without a
+   *  reload, silently leaving the old code running. */
+  function currentVersions(snap) {
     const map = Object.create(null);
-    for (const e of entries()) {
-      const pkg = pkgOf(e?.options?.name);
-      if (!pkg || pkg in map) continue;
-      const v = versionOf(pkg);
-      if (v) map[pkg] = v;
-    }
+    for (const pkg in snap) map[pkg] = snap[pkg].version;
     return map;
   }
 
@@ -142,8 +201,14 @@ export function apply(ctx, config = {}) {
     } catch {}
   }
 
-  /** Reload one loaded entry's module in place. Throws (after rollback) on failure. */
-  async function reloadEntry(entry) {
+  /** 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
+   *  still registered). Returns the package version read at IMPORT time — a
+   *  version read afterwards could record one that was never imported (a bump
+   *  landing during a slow apply()), which would make the next cycle see no
+   *  change and skip that upgrade forever. */
+  async function reloadEntry(entry, pkg) {
     const specifier = entry?.options?.name;
     const parentURL = entry?.parent?.tree?.ctx?.baseUrl ?? ctx.baseUrl;
     const oldFiber = entry.fiber;
@@ -156,9 +221,16 @@ export function apply(ctx, config = {}) {
 
     invalidate(url); // matters for in-place edits; harmless no-op for a version bump (new realpath)
 
+    // 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.
+    const importedVersion = versionOf(pkg);
     const newPlugin = loader.unwrapExports(await loader.import(url, getOuterStack));
     if (!newPlugin) throw new Error(`fresh import produced no plugin for ${specifier}`);
 
+    // Re-check after the (slow) import: never start the destructive swap into a
+    // context that began tearing down while we were awaiting.
+    if (disposed) throw new Error("dsh-hot-reload disposed mid-reload");
+
     // Snapshot fibers before disposal, then swap: dispose old (runs ctx disposers),
     // re-instantiate the new plugin against each old fiber's entry + config.
     const fibers = [...runtime.fibers];
@@ -169,11 +241,18 @@ export function apply(ctx, config = {}) {
       // how an async apply() throw is surfaced into this try/catch (a plain
       // reattach would let it escape asynchronously and leave the plugin dead).
       await Promise.all(fresh.map((f) => f?.await?.()));
+      // Activation can SUCCEED after teardown began — and the disposer no longer
+      // waits for us, so nothing else would ever dispose these fibers. Throwing
+      // here routes into the same drop-and-bail path the failure case uses.
+      if (disposed) throw new Error("dsh-hot-reload disposed mid-reload");
     } catch (err) {
-      // Rollback to the old plugin so a failed reload never leaves it dead.
       try {
-        ctx.registry.delete(newPlugin);
+        ctx.registry.delete(newPlugin); // every path out of here drops the new plugin
       } catch {}
+      // Teardown began while activation was awaiting: do NOT reattach into the
+      // dying context — its own teardown disposes whatever is still registered.
+      if (disposed) throw err;
+      // Otherwise roll back, so a failed reload never leaves the plugin dead.
       const restored = [];
       for (const of of fibers) {
         try {
@@ -185,6 +264,7 @@ export function apply(ctx, config = {}) {
       } catch {}
       throw err;
     }
+    return importedVersion;
   }
 
   function reattach(plugin, oldFiber) {
@@ -196,44 +276,149 @@ export function apply(ctx, config = {}) {
 
   // ---- change handling ----
 
-  async function handlePackage(pkg) {
-    const affected = entriesForPkg(pkg);
-    if (!affected.length) return; // not a loaded plugin (e.g. a fresh install) — out of scope
-    const version = versionOf(pkg) ?? "?";
+  /** Reload the live modules of a changed package, as already classified by the
+   *  cycle's snapshot record. Returns the version string to commit, `false` to
+   *  leave it uncommitted but RETRYABLE, or TERMINAL when a reload was attempted
+   *  and failed — that version is never retried (each attempt tears down the
+   *  working rolled-back plugin; recovery is a different version or a dsh
+   *  restart). */
+  async function handlePackage(pkg, rec) {
+    const { version, live, fiberless } = rec;
 
-    if (optedOut(pkg)) {
+    if (rec.json?.dsh?.hotReload === false) {
       log.info?.(`dsh-hot-reload: ${pkg}@${version} sets dsh.hotReload:false — restart dsh to load the new version`);
-      return;
+      return version;
     }
     if (!internal) {
       log.info?.(`dsh-hot-reload: ${pkg}@${version} changed — restart dsh to load the new version`);
-      return;
+      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,
+      // 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`
+      );
+      return false;
+    }
+    if (fiberless) {
+      log.warn?.(`dsh-hot-reload: ${pkg}@${version}: skipping ${fiberless} entry(ies) with no live fiber`);
     }
 
     try {
-      for (const entry of affected) await reloadEntry(entry);
-      log.info?.(`dsh-hot-reload: hot-reloaded ${pkg}@${version} (${affected.length} plugin row(s))`);
+      // Only ever commit a version some module actually imported. If a bump
+      // lands mid-cycle the modules can disagree about what they loaded; rather
+      // than pick one, leave the package uncommitted (retryable) so the next
+      // cycle re-snapshots and converges. Costs one redundant reload in a rare
+      // case; the alternative risks recording a version that never loaded.
+      let committed = null;
+      for (const entry of live) {
+        if (disposed) return false; // shutting down — don't touch the registry, don't commit
+        const imported = await reloadEntry(entry, pkg);
+        if (committed && imported !== committed) {
+          log.info?.(`dsh-hot-reload: ${pkg} changed again mid-reload — re-checking on the next change`);
+          return false;
+        }
+        committed ??= imported;
+      }
+      committed ??= version;
+      log.info?.(`dsh-hot-reload: hot-reloaded ${pkg}@${committed} (${live.length} module(s))`);
+      return committed;
     } catch (err) {
-      log.warn?.(`dsh-hot-reload: could not hot-reload ${pkg}@${version} — restart dsh to load the new version`);
+      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`
+      );
       log.warn?.(err);
+      return TERMINAL; // attempted and failed: never retried for this version
     }
   }
 
   // ---- watcher ----
 
-  let versions = snapshotVersions();
+  const boot = snapshot();
+  // null when the loader couldn't enumerate at boot. By design there is no
+  // retry and no warning: the first successful snapshot simply becomes the
+  // tracked state. Accepted tradeoff — if the loader is degraded at boot AND
+  // the very first lockfile event is a real upgrade, that upgrade is adopted
+  // 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)
   let timer = null;
+  let pending = false; // at most ONE cycle queued behind the running one; bursts coalesce into it
+  let disposed = false;
+  let running = Promise.resolve(); // serializes reload cycles across debounce batches
+
+  async function runCycle() {
+    if (disposed) return;
+    // ONE loader enumeration + ONE package.json read per package for the whole
+    // cycle: the diff below and the reloads it drives act on the same facts, so
+    // a transient loader/fs failure can never make a detected upgrade look like
+    // "not a loaded plugin" and get silently committed. (The single exception is
+    // the at-import version re-read in reloadEntry, which must not be cached.)
+    const snap = snapshot();
+    if (!snap) return; // degraded — keep current state, the next event retries
+    if (!versions) {
+      versions = currentVersions(snap); // adopt whatever is in the system (see `boot` above)
+      return;
+    }
+    for (const pkg in snap) {
+      if (disposed) return;
+      const version = snap[pkg].version;
+      if (!version) {
+        // package.json unreadable right now (mid pnpm swap). Track it with a
+        // null version if we've never had one, so the first readable version
+        // reads as a change and reloads, instead of being adopted as a fresh row.
+        if (!(pkg in versions)) versions[pkg] = null;
+        continue;
+      }
+      if (!(pkg in versions)) {
+        versions[pkg] = version; // newly loaded row: dsh just loaded it fresh, nothing to reload
+        continue;
+      }
+      if (versions[pkg] === version) continue;
+      // A version whose reload failed is never re-attempted: each attempt tears
+      // down the working rolled-back plugin again. Recovery is a different
+      // version or a dsh restart — the failure log said so once, stay quiet now.
+      if (failedVersions[pkg] === version) continue;
+      const commit = await handlePackage(pkg, snap[pkg]);
+      if (commit === TERMINAL) {
+        failedVersions[pkg] = version; // attempted, failed: don't try this version again
+      } else if (commit) {
+        versions[pkg] = commit; // the version actually imported, not the cycle-start one
+        delete failedVersions[pkg];
+      }
+      // commit === false: not attempted (teardown, or nothing attached yet) —
+      // leave it uncommitted and retryable on a later event.
+    }
+    // Drop a package when the LOADER no longer has an entry backed by it — not
+    // when its directory is missing. A point-in-time fs probe is wrong twice
+    // over: a dangling pnpm symlink mid-swap would evict a live plugin, and a
+    // removed plugin row whose package stays installed would be tracked forever.
+    for (const pkg of Object.keys(versions)) {
+      if (!(pkg in snap)) {
+        delete versions[pkg];
+        delete failedVersions[pkg];
+      }
+    }
+  }
+
   const trigger = () => {
+    if (disposed) return;
     if (timer) clearTimeout(timer);
-    timer = setTimeout(async () => {
+    timer = setTimeout(() => {
       timer = null;
-      const next = snapshotVersions();
-      const changed = [];
-      for (const pkg in next) {
-        if (versions[pkg] !== next[pkg]) changed.push(pkg);
-      }
-      versions = next;
-      for (const pkg of changed) await handlePackage(pkg);
+      if (pending) return; // a queued cycle will snapshot fresh state and see this change too
+      pending = true;
+      running = running
+        .then(() => {
+          pending = false;
+          return runCycle();
+        })
+        .catch((e) => log.warn?.("dsh-hot-reload: reload cycle error", e));
     }, debounceMs);
   };
 
@@ -242,24 +427,34 @@ export function apply(ctx, config = {}) {
   watcher.on("add", trigger);
   watcher.on("error", (e) => log.warn?.("dsh-hot-reload: watcher error", e));
 
-  ctx.effect(() => () => {
+  ctx.effect(() => async () => {
+    // Never wait on an in-flight reload: dsh's shutdown must not hang on an
+    // arbitrary plugin's apply()/fiber.await(). Setting `disposed` first makes
+    // any straggling cycle harmless — it stops between modules, and a reload
+    // caught mid-activation skips the rollback rather than reattaching fibers
+    // into a context that is already tearing down.
+    disposed = true;
     if (timer) clearTimeout(timer);
-    watcher.close();
+    running.catch(() => {}); // keep an in-flight rejection from going unhandled
+    try {
+      await watcher.close();
+    } catch {}
   });
 
   log.info?.(
-    `dsh-hot-reload: watching ${lockfile} (${Object.keys(versions).length} plugin package(s) tracked)`
+    `dsh-hot-reload: watching ${lockfile} (${Object.keys(versions ?? {}).length} plugin package(s) tracked)`
   );
 }
 
-/** Best-effort profile-dir resolution: explicit config, then the loader base URL. */
+/** Profile-dir resolution: an explicit config.profileDir ALWAYS wins — it must
+ *  never be silently overridden by auto-detection (a fresh profile without a
+ *  lockfile yet would otherwise get the baseUrl dir, watching and hot-swapping
+ *  the wrong profile; apply() warns loudly when the lockfile is missing).
+ *  Auto-detection from the loader base URL applies only when config is absent. */
 function resolveProfileDir(ctx, config) {
   if (config.profileDir) return config.profileDir;
   try {
-    if (ctx.baseUrl) {
-      const p = fileURLToPath(new URL(".", ctx.baseUrl));
-      return p.replace(/\/$/, "");
-    }
+    if (ctx.baseUrl) return fileURLToPath(new URL(".", ctx.baseUrl)).replace(/\/$/, "");
   } catch {}
   return null;
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-hot-reload",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
-  "description": "Live-reload upgraded DeepSeek Harness (dsh) plugins without restarting dsh — safe plugins are hot-reloaded in place; unsafe ones are flagged for a manual restart.",
+  "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": [
     "dsh",
     "dsh-plugin",