dsh-hot-reload

English | 中文

Live-reload upgraded DeepSeek Harness (dsh) plugins without restarting dsh.

dsh's built-in hot-reload (cordis-plugin-hmr) deliberately ignores
node_modules, so upgrading an installed plugin (dsh plugin add pkg@x)
normally requires a full dsh restart to take effect. This plugin closes that
gap: it watches your profile's pnpm-lock.yaml, and when an already-loaded
plugin package's version changes, it swaps the running plugin in place.

Behavior

On a plugin package upgrade, for each affected plugin:

• Reload it live — invalidate the module caches, re-import the new code, and
  re-instantiate the plugin fiber in place. dsh, your sessions, and every other
  plugin keep running.

• If the reload fails — you're left with the working old version, never a
  dead plugin, plus a logged note that a manual dsh restart is needed to
  pick up the new code. Two cases, both handled:

  • a failure while loading the new code (bad import, syntax error) is caught
    before the running plugin is touched — the old plugin is never disturbed;
  • 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 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.

Upgrading dsh-hot-reload itself

dsh-hot-reload can hot-reload itself too. When its own package is
upgraded, the running instance imports the new module, commits its own version
and persists it, closes its watcher, and then swaps its own fiber in place. The
new instance re-reads the state file and opens its own watcher — the old watcher
is closed before the new one opens, so there is never more than one live watcher.

To make that handoff — and a plain restart — safe, the plugin keeps its tracked
state in a file: profileDir/.dsh-hot-reload-state.json. It holds the committed
versions, the never-retried failedVersions, and the once-announced
noticedVersions. The file is written atomically — a .tmp file is written
and then renamed over the target, so a crash mid-write never leaves a truncated
file — and read back at startup, so a fresh instance inherits what the previous
one committed instead of treating already-loaded plugins as new and re-reloading
them.

This state file is required. If it cannot be written at startup, the plugin
refuses to start (it throws) rather than running with in-memory-only state that
a later self-reload or restart would lose.

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 every outcome. You get this in
every profile:

dsh-hot-reload: hot-reloaded [email protected] (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 covers every reload outcome — reloaded, failed, and
stale (not attempted — the old code is still running). To see everything else this plugin writes to the log (its warnings and
diagnostics), add dsh's console logger to your profile. It is a separate
package:

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:

- 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

dsh plugin --profile web add dsh-hot-reload

Then restart dsh once (bundle patch layers load at boot). After that, upgrades
apply live:

dsh plugin --profile web add some-plugin@newer   # reloaded automatically

Works in any profile — swap web for whichever profile you use; it watches
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 — 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)
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

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

A plugin that knows it isn't safe to hot-reload can force the restart-needed
path (no reload attempt) by declaring, in its own package.json:

{ "dsh": { "hotReload": false } }

Configuration

Set on the hot-reload row in your profile's cordis.patch.yml:

Key	Default	Meaning
debounce	300	ms to wait after a lockfile change before acting
profileDir	auto	absolute path to the profile dir to watch (auto-detected from the loader base URL if omitted)

Limitations — read this

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,
  a child_process — without a ctx.effect disposer can reload without
  throwing yet leave that resource dangling (a stray timer, a duplicate
  listener, an orphaned watcher). These accumulate across upgrades and are
  cleared only by an eventual restart.

• Cordis auto-unwinds everything a plugin registers through ctx
  (ctx.effect, ctx.on, ctx.provide, tool schemas, adapters), so
  well-behaved plugins reload cleanly. The risk is limited to plugins that
  bypass ctx. If in doubt, have such a plugin set dsh.hotReload: false.

• 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 the cordis/loader internals listed under
  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.

• A plugin that loads after dsh-hot-reload in the bundle order is reloaded
  once — to its current version — on the first lockfile write after boot, even
  when that write was for an unrelated package. Until this plugin has tracked the
  package across one cycle, it cannot tell whether the running code is the old or
  the current version, so it reloads rather than adopting a version that may
  never have run. For an HMR-safe plugin this is a harmless single redundant
  reload.

• The state file is required. The plugin writes its tracked state to
  profileDir/.dsh-hot-reload-state.json. If that file cannot be written — for
  example because the profile directory is read-only — the plugin refuses to
  start (it throws) rather than running with in-memory-only state.

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,
which dsh already hot-applies).

License

MIT © Stuart Hu