DeepSeek Harness plugin HMR reload: cache, timers, effects

The trap plugin authors fall into most is not writing bad code but "assuming hot reload took effect": apply() does rerun and the log shows a new activation record, yet the module is still old, the timer still carries last round's transaction marker, or the host crashes outright. These four failures each have their own signals; triage with the table first, then fix them one by one (#10774, #11121).

DeepSeek Harness: Triage table: symptoms and signals for four failures

In one sentence: no reaction to code changes is a watch-scope problem; a reaction with wrong behavior is a cache problem; nested-transaction errors are a marker problem; a host exit is an inactive-context problem.

DSH plugin: Type 1: config hot reload is not module hot reload

hmr.config.root defaults to an empty array and only watches config files; a file:// plugin on another drive is not in the watched scope at all.

1. Confirm the symptom: every touch of cordis.patch.yml adds another apply() record, which means the plugin was rebuilt.
2. But the imported module is not re-evaluated — Node's ESM cache is keyed by resolved URL, and an unchanged URL keeps the old module.
3. Check the watch scope: the base bundle sets hmr.config.root to [], so source watching is off; profile recomposition only covers the profile directory and linked package targets.
4. Fix it by configuring both base and root in the hmr entry:

- id: hmr
  disabled: false
  config:
    base: 'file:///F:/path/to/your/repo/'
    root: ['plugin/dsh-live-workbench', 'server']

5. base only anchors relative paths; root decides what is actually watched, so changing only base is the same as not enabling watching.
6. Make the plugin entry a static import of its handler so HMR has a dependency path to replace; a dynamic import(...?v=timestamp) only refreshes the entry.

The community ran a two-stage check on the packaged desktop app: with root: ['.'], both entry changes and static dependency changes reloaded; narrowed to two directories, both still reloaded. The ?v= route has a ceiling — it re-evaluates only the entry, and sibling modules statically imported by the entry stay old.

DeepSeek Harness: Type 2: timers permanently carry the transaction marker

apply() executes inside an HMR transaction, and timers registered there capture the marker; the transaction ends milliseconds later, but the timer keeps it.

1. Reproduce: the plugin uses ctx.interval() in apply() for a 15-second heartbeat whose callback does a config write such as saveSelection().
2. Cold start is fine and hmr.executing.getStore() is undefined.
3. After hot reload, getStore() is true inside every callback.
4. So runExclusive() rejects right at the entry: HMR transactions cannot be nested.
5. The symptom is that every capability requiring a config write silently stops working, printing one error per cycle, until restart.
6. The community's minimal reproduction (plain Node + AsyncLocalStorage) had 0 failures on cold start and 3/3 failures after hot reload.

The fix is not "clear the marker before entering the transaction". The community measured that this lets genuine nested calls through too: an inner task queues behind an outer one that is waiting on it, neither Promise can settle, and every later runExclusive on that instance never returns. The workable version gives each transaction an independent state object, sets active to false when it ends, and updates the other three read sites in the same file to getStore()?.active.

DSH Plugin: Type 3: the host dies with INACTIVE_EFFECT

The plugin's apply is async and never rechecks whether the fiber is still alive after the first await; when hot reload destroys the context before the second child plugin mounts, it crashes.

1. Read the crash log: CordisError: cannot create effect on inactive context, with code: 'INACTIVE_EFFECT'.
2. Read the stack: Fiber._reload → plugin() → assertActive.
3. Read the code shape: apply does await ctx.plugin(workspaceDependencies, ...), then synchronous path work, then a second await ctx.plugin(officeSkills, ...).
4. Trigger: hot reload destroys or replaces that fiber while the first await is suspended, so the context is already inactive at the second mount.
5. Fix one: if the two child plugins do not depend on each other, mount both in one synchronous turn.
6. Fix two: recheck whether the fiber is still active after every await, and return early when it is not.

This error is not a Cordis defect; assertActive behaves correctly. The caller crossed the invalidation point.

DeepSeek Harness: Type 4: the official manager refuses overwrite installs

In HMR mode, as soon as the profile dependency already contains a package with that name, the official manager refuses outright — pnpm never even runs.

1. Read the error: official plugin manager update failed: refused to execute (already-installed).
2. Match the version: rc.1 and rc.2 support overwrite updates; rc.3, rc.4, and rc.5 do not, as the community measured version by version.
3. Recovery path: uninstall the plugin → official restart → reinstall.
4. That is currently the only stable path, and the upgrade guide already documents removeBundle followed by installBundle.
5. To bypass it you can use DSH's bundled pnpm with add <package>@<version> --save-exact, but that is manual intervention, not a UI capability.
6. The root fix is an atomic updateBundle: install into a temp directory and swap, leaving the profile untouched on failure.

DSH plugin: Cautions

Prove a reload with behavior, not with log lines.

1. Do not use "an activation log appeared" as proof hot reload worked. It proves only that apply() reran.
2. Do not configure only base. With an empty root, source watching is still off.
3. Do not register timers that write config inside apply(). They always break after hot reload unless core fixes it.
4. Do not use ctx directly after an await. Recheck liveness after every asynchronous step.
5. Cold-start once after changing a plugin. Defects in the hot-reload path easily mask real logic problems.

If none of the four match, first confirm whether your plugin is registered through a profile patch as a file:// path — that is the most common starting point.See DeepSeek Harness plugin load: already registered, pending for the related case.