DSH plugin hot reload: cordis.yml, HMR, PENDING diagnosis

A DSH plugin's hot reload mechanism is "unload first, then load": cordis.yml selects the plugin tree to apply, and @deepseek-ai/dsh-hmr watches files and, on save, replaces running plugins by unloading (releasing effects) plus dependency-driven loading. To hot-swap precisely, give each entry an id; when a plugin never loads and reports nothing, it is usually because a service in inject has no provider and the fiber is stuck in PENDING.

How a DSH plugin composes the plugin tree with cordis.yml: id, disabled, and groups

cordis.yml is what decides which plugins are applied—every capability is a plugin, and this file selects the plugin tree (source). Besides name and config, an entry accepts other metadata:

- id: greeter          # stable identity for this entry
  name: './greeter.ts'
- id: consumer
  name: './consumer.ts'
  disabled: true       # keep the entry, skip mounting it

1. id provides a stable identity — it lets the loader tell "modify an existing entry" from "remove then add." Expect: only the affected part is remounted when you change the config.
2. disabled: true unloads without deleting — the entry is kept and mounting is skipped. Expect: setting it back restores the plugin, and plugins left PENDING because they depend on its service reload too.
3. A group can nest a sub-list — load and unload a set of entries as one unit. Expect: the whole group goes up and down together.
4. isolate provides an independent service instance — isolate a service instance for a group. Expect: two groups each see a provider of the same name with different config, without affecting each other.

Key cause and effect: an entry without an id gets a freshly generated id on every read, so any edit to the config file—even if the entry's own text is unchanged—is treated as remove-then-add and remounted.

How a DSH plugin hot reloads: dsh-hmr unload and reload

HMR works because unloading releases effects and loading follows dependencies, so "unload first, then load" can replace a running plugin (source). Configure and verify in four steps:

- id: logger
  name: '@deepseek-ai/cordis-plugin-logger-console'
- id: timer
  name: '@deepseek-ai/cordis-plugin-timer'
- id: hmr
  name: '@deepseek-ai/dsh-hmr'
  config:
    root: ['.']
- id: hello
  name: './hello.ts'

1. Mount @deepseek-ai/dsh-hmr in cordis.yml and set config.root to the directory to watch (e.g. ['.']). Expect: on save the old instance unloads first, then new code loads.
2. Also mount @deepseek-ai/cordis-plugin-logger-console so HMR records logs through the Cordis logger service. Expect: you see unload / reload messages; without a console exporter you see no output at all.
3. Also mount @deepseek-ai/cordis-plugin-timer, the timer service HMR injects for debouncing. Expect: the plugin does not stay in PENDING; without timer it stays PENDING forever and emits no hint.
4. Run it under tsx and save a plugin file as needed, for example node --import tsx ../../vendor/cordis/bin.js. Expect: every effect of the old instance is rolled back, new code loads and apply runs again; editing cordis.yml itself also updates only what changed by id.

To understand effects and unload rollback first, revisit DSH plugin events.

Diagnosing a DSH plugin stuck in PENDING: inject with no provider

If a plugin's inject names a service nobody provides, it waits forever and outputs nothing—this is not an error, because PENDING is a legal state and a provider may mount later (source). Locate it in four steps:

import { FiberState, type Context } from '@deepseek-ai/cordis'

export const name = 'diagnose'

export function apply(ctx: Context) {
  setTimeout(() => {
    for (const runtime of ctx.registry.values()) {
      for (const fiber of runtime.fibers) {
        if (fiber.state === FiberState.PENDING) {
          console.log(`${fiber.name} is PENDING — a required service is missing`)
        }
      }
    }
  }, 500)
}

1. Confirm the symptom is "neither acts nor reports" to rule out a thrown error. Expect: no error stack in the terminal and the process still running.
2. Enumerate the registry from any context: walk ctx.registry.values() and each runtime.fibers inside it. Expect: you get every plugin fiber and its state.
3. Filter for fibers where fiber.state === FiberState.PENDING. Expect: the stuck plugin's name prints, showing that a required service in its inject is missing.
4. Add a provider for that service, or drop the inject. Expect: the fiber moves from PENDING to ACTIVE and starts running.

Iterating without the PENDING filter also shows the loader's own plugins (Loader, Include) as ACTIVE, because the config file itself is mounted through a plugin.

Three self-checks after writing (good for any DeepSeek Harness plugin): does every commonly used plugin have an id; are HMR's logger and timer dependencies in place; when something "has no effect", did you look at the fiber state first. To apply this diagnosis to a real service, see the Cordis primer; to find ready-made logging or timer plugins, search the DSH Plugin Hub.