Hot re-apply of an in-place updated plugin package fails with tool "X" already registered; module cache serves stale code

[xuhurdern-beep]

Issue draft — upstream deepseek-harness

Prepared from a real reproduction via the dsh-live-reload plugin (third-party,
https://github.com/xuhurdern-beep/dsh-live-reload). Filed for upstream discussion.

---

Title

Hot re-apply of an in-place updated plugin package fails with tool "X" is already registered; the loader's module cache also serves the pre-update code

Summary

When a plugin package that is already mounted in the running tree is updated in place on
disk (the plugin market reinstalls/updates it: files under node_modules/<pkg> are rewritten),
re-applying the composition through the root Include fails:

failed to apply loader entry include (cordis:include): failed to apply loader entry
import-claude (dsh-chat-import): tool "import_claude" is already registered
(for a per-agent variant, register through that agent's `agent.ctx` instead)

A fresh boot with the same composition works fine (the row is the first registrant). The failure
only happens when the row is re-applied while its previous fiber is still live.

Environment

• deepseek-harness 0.1.0-rc.5
• Node v24.13.0, Windows
• Profile: web (bundle list includes dsh-base, dsh-web-app, a tool-registering plugin)

Reproduction

1. Boot a profile whose bundles include a plugin that registers a tool (e.g. any ctx.tools.register plugin).
2. While the instance is running, reinstall/update that same plugin (market action rewrites
   node_modules/<pkg>; the profile manifest / bundle layer is touched).
3. Hot-apply the composition (built-in user-patch HMR on cordis.patch.yml, or the
   dsh-live-reload refresh which calls the same include.update).
4. Observe: the row is re-applied; apply() re-runs ctx.tools.register({ name: '...' });
   the name is still owned by the previous fiber → already registered → the whole include
   update rolls back (transactional) → the refresh reports failure.

Even when the row's options are otherwise identical (so no collision), the loader's ESM module
cache serves the old code for the same package URL — the updated package's new code never
loads without a process restart.

Root-cause analysis

• Module cache: the loader imports every row through Node's internal ESM ModuleLoader
  (cordis-plugin-loader src/internal.ts: ctx.loader.internal.loadCache, keyed by file URL).
  An in-place package update keeps the same URLs, so loadCache returns the pre-update
  ModuleJob. Module-level HMR is intentionally off on the web surface, but there is no
  documented/supported API to evict a package's cached jobs, so third-party hot-reload tooling
  must either restart the process or reach into loader.internal.loadCache (Node internals).
• Duplicate registration on re-apply: the entry replace path (src/config/entry.ts) is
  import(candidate.name) → dispose(previous) → start(plugin). If the import hits the stale
  cache, the "new" apply runs the OLD code while the old fiber may still hold its registrations —
  the observed already registered error. (The harness's own HMR handles withdrawal for
  tool-fs's read_image; the re-apply ordering above is the fragile spot for out-of-tree
  plugins.)

Expected behavior

1. A documented, supported way to evict/reload the cached module jobs of one package
   (e.g. a loader.evictPackage(pkgDir) or a cache-busting import path), so in-place package
   updates can be hot-applied without a restart; and
2. the re-apply path must withdraw the previous fiber's tool registrations before the new
   apply() runs, so a re-applied row can never collide with its own previous generation; or,
   failing that, produce an actionable error ("package X was updated on disk; a restart is
   required to load the new code") instead of the cryptic tool-name collision.

Workaround demonstrated today

dsh-live-reload (v0.2.0) detects on-disk package changes (a per-bundle file
fingerprint seeded at boot) and re-points the changed package's loader rows at
a cache-busted entry URL (<entry file URL>?dshr=<rev>), which creates a
fresh module-cache key per on-disk revision and forces the loader's replace
path (re-import → dispose the old fiber — withdrawing its tool registrations →
start). Verified in its scripted e2e: after an in-place rewrite of a mounted
bundle, a refresh re-imports and runs the new code (marker file v1→v2) with
the same tool name, no collision, no restart. It relies on Node's URL-keyed ESM
cache semantics; a first-class loader API (documented eviction or reload of one
package) would make it robust and remove the need for the query-string trick.

[argszero]

Verified the replace path against master (vendor/loader/src/config/entry.ts:217-233) — your ordering claim is exact: import(candidate.name) (line 217) → _dispose(previous) (226) → _start(plugin) (233). One nuance worth separating, because I think the report conflates two independent mechanisms with different fixes:

The collision requires the registration to survive _dispose — that's a lifecycle gap, not just an ordering symptom

The error is thrown by the tools registry's NamedEntries when the same scope already owns the name (packages/core/tools/src/index.ts:715-728, scope-keyed; the "per-agent variant" branch is the undefined-scope/global case). If _dispose(previous) fully withdraws the old fiber's registrations, then a same-name collision on the next _start is impossible even with the stale-cache old code (import doesn't execute the plugin; only _start does, and it runs after dispose). So the observed already registered implies the previous registration outlived the fiber — i.e. the plugin's ctx.tools.register(...) did not hook into the fiber's disposal. The repo convention is explicit: "Registrations are effects — every contribution goes through ctx.effect() / ctx.on(); a registry's register() returns the disposer." An out-of-repo plugin that ignores the returned disposer (or registers into a shared/root ctx rather than its own fiber ctx) survives re-apply by construction.

That changes the fix priority:

• Your mechanism A (stale module cache → wrong code runs) — real, and your ?dshr=rev cache-busted-entry workaround is the correct shape. The durable API would be a loader-level evictPackage(dir) that invalidates the package's loadCache jobs and re-imports; Node's cache is keyed by resolved URL, so a revision-suffixed specifier is exactly a manual eviction. This needs a loader API.
• Your mechanism B (re-apply collides with own previous generation) — the durable fix is not "dispose before import" (import-before-dispose is deliberate: the replacement must be loadable before teardown, so a dispose failure can roll back to a working plugin — see the rollback path at :235-245). The durable fix is making registrations fiber-owned effects so dispose reliably withdraws them. For the harness: that's already the stated contract; the missing piece is a load-time guard that flags a plugin whose registration ignores the disposer (cheap: compare the registered entry's ownership to the fiber ctx). For plugin authors: honor the returned disposer / register on the injected fiber ctx.

Cross-thread link

This is the same loader-entry lifecycle blind spot as the reconcile family (#1377/#1404 — blind state reconciliation can silently disable an unresolved bundle; here, hot re-apply can either run stale code or collide with a live fiber). Both are "the loader's replace path assumes the old fiber is fully and correctly torn down" failures. A shared hardening direction: make entry replacement verify withdrawal (registrations gone, effects disposed) before _start, and report an actionable error naming the surviving owner when it can't — which is your expected-behavior #2, but reached via lifecycle verification instead of reordering.