c8ctl-plugin-nano 1.64.0 → 1.65.0

package/c8ctl-plugin.js

@@ -159,6 +159,19 @@ const STOP_GRACE_MS = 8_000;
 // `nano work` child to quiesce it — stop leasing new jobs, finish in-flight work,
 // then exit. SIGTERM/SIGINT remain the FORCE abort (kill harness, yield jobs).
 const SUPERVISOR_DRAIN_SIGNAL = 'SIGUSR2';
+// Hot-reload readiness gate: after a rolling `supervisor reload` respawns a
+// worker, the daemon waits (bounded) for the replacement to STAMP `readyAt` on
+// its activity marker — i.e. its activation loop is up and leasing jobs — before
+// draining the NEXT worker, so at most one worker is ever unavailable at a time.
+// A bare spawn/PID is not readiness: the child still has to import the plugin,
+// build its SDK client and start its activation loop. The wait is bounded so a
+// slow/never-ready replacement (e.g. a wedged engine) can't stall the roll — on
+// timeout the daemon advances anyway (degrading to the old spawn-and-advance).
+const SUPERVISOR_RELOAD_READY_POLL_MS = 100;
+const SUPERVISOR_RELOAD_READY_TIMEOUT_MS = Math.max(
+  0,
+  Number.parseInt(process.env.NANO_SUPERVISOR_RELOAD_READY_TIMEOUT_MS ?? '', 10) || 30_000,
+);
 // Upper bound on one `--auto` engine-read reconcile (enumerate deployed
 // definitions + fetch each BPMN). A read that stalls past this is treated as a
 // transient failure so the running poller set is KEPT and, crucially, shutdown
@@ -325,6 +338,19 @@ function readWorkerActivity(id) {
   }
 }
 
+/**
+ * Whether an activity marker proves a specific child (`pid`) is up and leasing.
+ * Both conditions are required (#253): a finite `readyAt` (the runtime's
+ * first-activation handshake fired) AND `act.pid === pid` (the marker belongs to
+ * THIS child, not a stale one a failed best-effort delete left behind from a
+ * previous incarnation — which would otherwise let the rolling reload advance
+ * before the fresh replacement has actually reported ready). Pure so it can be
+ * unit-tested directly.
+ */
+function activityMarkerReadyFor(act, pid) {
+  return !!(act && act.pid === pid && Number.isFinite(act.readyAt));
+}
+
 /**
  * Deterministic control-socket path shared by the daemon and every client.
  * Derived from a hash of the (possibly overridden) state home so distinct
@@ -3589,6 +3615,11 @@ async function createSupervisorDeps(opts = {}) {
     config,
     fetchImpl,
     env = process.env,
+    // A plain JS thunk (Effect-free, monolith-supplied) fired ONCE when the
+    // activation loop begins leasing — lifted below into the runtime's
+    // `onFirstActivation` Effect. Used as the rolling-reload readiness handshake
+    // (#253): stamping readiness only when the runtime is actually serving.
+    onFirstActivation,
   } = opts;
   if (!runner || typeof runner.run !== 'function') {
     throw new TypeError('createSupervisorDeps: `runner` must be a raw job runner `{ run(job): Promise<void> }`');
@@ -3597,7 +3628,6 @@ async function createSupervisorDeps(opts = {}) {
   const rt = await loadSupervisorRuntime();
   const { demand } = await import('./agentic.mjs');
   const { createRawEngineClient } = await import('./supervisor-engine.mjs');
-
   // Base/auth: the single canonical worker-engine chain (explicit restConfig →
   // profile restAddress → localhost), ALWAYS run through the token same-origin
   // gate — even when a caller pins the base via `restConfig` — so token
@@ -3661,6 +3691,11 @@ async function createSupervisorDeps(opts = {}) {
     agenticEndpoint,
     agenticConfig,
     config: scope ? { ...config, scope } : config,
+    // Lift the plain readiness thunk into an Effect the runtime runs on its own
+    // fiber the instant it starts leasing (#253). Effect-free JS in, Effect out —
+    // the same "monolith supplies plain JS, TS lifts it" seam as the other ports.
+    onFirstActivation:
+      typeof onFirstActivation === 'function' ? rt.Effect.sync(onFirstActivation) : undefined,
   });
 
   // The `settle` seam (issue #156, escalation answer (a)): the runner settles a
@@ -8386,7 +8421,7 @@ function agenticStateForTarget(target, safeUrl = (u) => u) {
  * list; `busy` is derived so callers can't desync it from `jobs`.
  * @param {{ pid:number, updatedAt:number, jobs:Array<{key:string,type:string,since:number}>, engine:(string|null), agentic:object }} fields
  */
-function buildActivityPayload({ pid, updatedAt, jobs, engine, agentic }) {
+function buildActivityPayload({ pid, updatedAt, jobs, engine, agentic, readyAt }) {
   const jobList = Array.isArray(jobs) ? jobs : [];
   return {
     pid,
@@ -8395,6 +8430,10 @@ function buildActivityPayload({ pid, updatedAt, jobs, engine, agentic }) {
     jobs: jobList,
     engine: engine ?? null,
     agentic,
+    // When the worker's activation loop has started (it has imported, built its
+    // SDK client and begun leasing), the producer stamps this; null until then.
+    // The supervisor's rolling reload gates on it (a spawn/PID is not readiness).
+    readyAt: readyAt ?? null,
   };
 }
 
@@ -9124,10 +9163,15 @@ async function workAgent(req, flags, ctx) {
   // is updated once the channel target is resolved and again on each
   // connect/disconnect below.
   let agenticState = { status: 'starting' };
+  // Readiness handshake (Copilot review on #253): null until this worker's
+  // activation loop is actually up and leasing; the supervisor's rolling reload
+  // waits for this stamp before draining the next worker so a bare spawn/PID is
+  // never mistaken for a serving replacement.
+  let readyAt = null;
   const writeActivity = () => {
     if (!activityFile) return;
     const jobs = [...activeJobs.entries()].map(([key, v]) => ({ key, type: v.type, since: v.since }));
-    const payload = buildActivityPayload({ pid: process.pid, updatedAt: Date.now(), jobs, engine: workerEngine, agentic: agenticState });
+    const payload = buildActivityPayload({ pid: process.pid, updatedAt: Date.now(), jobs, engine: workerEngine, agentic: agenticState, readyAt });
     const tmp = `${activityFile}.${process.pid}.tmp`;
     try {
       mkdirSync(dirname(activityFile), { recursive: true });
@@ -10198,6 +10242,16 @@ async function workAgent(req, flags, ctx) {
     // agentic target didn't resolve to a connect — the runtime then runs with no
     // agentic scope and presence/steer degrade to no-ops.
     agenticEndpoint: agenticEndpoint || undefined,
+    // Readiness handshake (#253): the runtime fires this the instant its activation
+    // loop begins leasing (on its OWN fiber, after reconcile/presence are forked;
+    // under agentic the connect cycle is a concurrent child, so the connection may
+    // still be connecting — readiness is LEASING-gated, not connection-gated). Stamp
+    // `readyAt` on the
+    // activity marker here so the supervisor's rolling `reload` waits for THIS
+    // replacement to be genuinely serving before draining the next worker. A bare
+    // `runFork` return (which only schedules the fiber) is NOT readiness.
+    // Best-effort — a marker write never fails the worker.
+    onFirstActivation: () => { readyAt = Date.now(); writeActivity(); },
     config: {
       activation: { requestTimeoutMs: pollTimeoutMs },
       dispatch: { recoveryWindowMs, extendIntervalMs: lockExtendIntervalMs },
@@ -10225,6 +10279,12 @@ async function workAgent(req, flags, ctx) {
   const supervisor = await SupervisorEffect.runPromise(makeSupervisorRuntime(supervisorDeps));
   const supervisorFiber = SupervisorEffect.runFork(supervisor.run);
 
+  // Readiness is stamped by the runtime's `onFirstActivation` handshake (wired
+  // into `createSupervisorDeps` above), NOT here: `runFork` only *schedules* the
+  // fiber and can return before it has executed at all, so stamping `readyAt`
+  // in this continuation could report the worker ready before its activation loop
+  // is leasing — defeating the rolling reload's one-at-a-time guarantee (#253).
+
   // Seed this worker's presence into the runtime's ownership registry (issue
   // #173) and late-bind the per-job relay seam to the running supervisor. The
   // presence-projection fiber announces (register) then heartbeats this instance
@@ -11118,6 +11178,19 @@ function formatSupervisorStatus(status) {
   lines.push('Supervisor:');
   lines.push(`  daemon pid: ${d.pid ?? '-'} ${alive ? '(alive)' : '(dead — stale state)'}`);
   if (d.version) lines.push(`  version:    ${d.version}`);
+  // Flag a code update the running daemon hasn't adopted yet: the plugin on disk
+  // has advanced past the daemon's version (e.g. after `nano update`). A rolling
+  // `supervisor reload` adopts the new WORKER code with zero downtime; a daemon
+  // restart is needed for new SUPERVISOR code. `status.pluginVersion` is only
+  // present on a live socket `status` frame; the socket-unreachable fallback
+  // (`statusFromState()`) has no such field, so read the on-disk package version
+  // locally as a fallback — otherwise the warning silently disappears exactly
+  // when the daemon is alive but its control socket is briefly unreachable.
+  const onDiskVersion = status.pluginVersion
+    ?? (() => { try { return pluginPackage().version; } catch { return null; } })();
+  if (onDiskVersion && d.version && onDiskVersion !== d.version) {
+    lines.push(`  on disk:    ${onDiskVersion} (update available — run \`c8ctl nano supervisor reload\` to adopt new worker code; restart the daemon for new supervisor code)`);
+  }
   if (d.startedAt) lines.push(`  started:    ${d.startedAt}`);
   if (d.socket) lines.push(`  control:    ${d.socket}`);
   const workers = Array.isArray(status.workers) ? status.workers : [];
@@ -11288,7 +11361,19 @@ function waitForChildExit(child, timeoutMs) {
     // #202: a null/undefined timeout means WAIT INDEFINITELY (graceful drain) —
     // no timer is armed, so we only resolve when the child actually exits.
     const t = timeoutMs == null ? null : setTimeout(() => finish(), timeoutMs);
-    function finish() { if (done) return; done = true; if (t) clearTimeout(t); resolve(); }
+    // `finish` ALWAYS removes the `exit` listener, including the timeout path:
+    // `child.once` only self-removes when the event fires, so a timed-out wait
+    // would otherwise leave its listener attached. The readiness poll calls this
+    // ~every 100ms for up to 30s, so a leaked listener per poll accumulates
+    // hundreds on a long-lived child — a `MaxListenersExceededWarning` plus
+    // retained closures (#253 review).
+    function finish() {
+      if (done) return;
+      done = true;
+      if (t) clearTimeout(t);
+      child.removeListener('exit', finish);
+      resolve();
+    }
     child.once('exit', finish);
   });
 }
@@ -11386,6 +11471,11 @@ async function runSupervisorDaemon() {
   // restart-on-exit path and let a second `stop --force` escalate a live drain.
   let draining = false;
   let forcing = false;
+  // Hot code reload (rolling drain+respawn). A `reload` op adopts new on-disk
+  // plugin code into the worker children by gracefully draining and respawning
+  // them one at a time (so the fleet keeps serving). This flag rejects a second
+  // concurrent reload — a single rolling pass owns the fleet until it finishes.
+  let reloading = false;
   // Live-view monitor: tracks the last-broadcast fleet signature so we push a
   // refreshed status to attached consoles only on real change (see below).
   let monitorTimer = null;
@@ -11638,6 +11728,216 @@ async function runSupervisorDaemon() {
     return true;
   };
 
+  // Hot code reload of a single worker: GRACEFULLY drain it (SIGUSR2 — finish
+  // in-flight jobs, then exit) and respawn it, so the new child re-reads the
+  // updated plugin from disk. Unlike `restartWorker` (a force SIGTERM/SIGKILL
+  // swap), this waits INDEFINITELY for the drain so no in-flight job is lost —
+  // adopting new code is never worth killing running work.
+  //
+  // CAPACITY CAVEAT: this drains the worker BEFORE spawning its replacement, so
+  // for the drain+boot window that worker serves no jobs. The fleet's "zero
+  // downtime" guarantee is therefore a FLEET-level one — with >1 worker the rest
+  // keep serving while one drains. A single-worker fleet (or a job type served by
+  // only this one worker) does lose that type's serving capacity until the drain
+  // finishes, `startWorker` runs, AND the replacement reports ready. Preserving an
+  // overlapping serving replacement would need a two-child handoff; that is
+  // intentionally out of scope here (documented in README/AGENTS).
+  //
+  // ONE-AT-A-TIME: after respawning, this waits (bounded) for the replacement to
+  // stamp `readyAt` on its activity marker — it is up and leasing — before it
+  // returns, so `runReload` never drains the NEXT worker while this one is still
+  // booting. A bare spawn/PID is not readiness (Copilot review on #253).
+  //
+  // The drain runs OUTSIDE the op lock (it can be arbitrarily long) so a
+  // `stop --force` or a `remove`/`restart` for this same worker isn't blocked
+  // and can escalate/interrupt it. Because of that, the respawn is guarded by
+  // the child-identity check (`w.child === child`): if a concurrent
+  // force-stop/restart/remove already swapped or deleted this worker while we
+  // drained, we must NOT respawn (that would leak a duplicate child or revive a
+  // removed worker). We also skip the respawn when the daemon is shutting down.
+  // Poll a freshly (re)spawned worker's activity marker until it stamps `readyAt`
+  // (its activation loop is up and leasing), the child is swapped/exits, the
+  // daemon starts shutting down, or the bounded deadline passes. Returns whether
+  // it became ready; the caller advances regardless — readiness is a best-effort
+  // gate, never a hard block. Used by the rolling reload so it does not drain the
+  // next worker while this replacement is still booting (Copilot review on #253).
+  const waitForWorkerReady = async (w, child, timeoutMs) => {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+      // Stop waiting if a concurrent restart/force-stop swapped this child, or it
+      // already exited — it is no longer a booting replacement to gate on.
+      if (w.child !== child) return false;
+      if (child.exitCode !== null || child.signalCode !== null) return false;
+      // Abort at once on a spawn failure (ENOENT/EMFILE/…): it emits only 'error'
+      // with NO 'exit', so `exitCode`/`signalCode` stay null and the two checks
+      // above never fire — without this the loop would poll the full ready-timeout
+      // (~30s) before the final live-PID gate rejects a worker that never started
+      // (#253 review). `handleDeath` nulls `w.pid` on that 'error' (and a failed
+      // spawn has no `child.pid` to begin with), so a null `w.pid` for THIS still
+      // -current child means the replacement is dead — stop waiting immediately.
+      if (w.pid == null) return false;
+      const act = readWorkerActivity(w.id);
+      // Require the marker to be from THIS replacement child (`act.pid === child.pid`)
+      // AND carry a finite `readyAt` (#253): a stale marker left by a previous
+      // incarnation must not pass this gate before the freshly spawned child has
+      // reported ready — see activityMarkerReadyFor.
+      if (activityMarkerReadyFor(act, child.pid)) return true;
+      if (shuttingDown || Date.now() >= deadline) {
+        dlog(`worker '${w.id}' not ready within ${timeoutMs}ms after reload — advancing anyway`);
+        return false;
+      }
+      // waitForChildExit doubles as a poll sleep: it resolves early if the child
+      // exits (the loop-top guard then returns) so we never busy-spin on a dead child.
+      await waitForChildExit(child, SUPERVISOR_RELOAD_READY_POLL_MS);
+    }
+  };
+
+  const reloadWorker = async (id) => {
+    const w = workers.get(id);
+    if (!w) return false;
+    const child = w.child;
+    w.stopping = true;
+    if (w.restartTimer) { clearTimeout(w.restartTimer); w.restartTimer = null; }
+    const pid = w.pid;
+    if (child && pid) {
+      try { process.kill(pid, SUPERVISOR_DRAIN_SIGNAL); } catch { /* already gone */ }
+      await waitForChildExit(child, null);
+    }
+    // Only respawn if nobody else acted on this worker while we drained: it must
+    // still exist, we must not be shutting down, and its child handle must still
+    // be the one we drained (a concurrent restart/force-stop would have swapped
+    // it). The startWorker+guard runs under the op lock so it can't interleave
+    // with add/remove.
+    const started = await serializeOp(async () => {
+      const cur = workers.get(id);
+      if (!cur || cur !== w || shuttingDown || w.child !== child) return null;
+      w.stopping = false;
+      w.restarts = 0;
+      startWorker(w);
+      dlog(`worker '${id}' respawned (awaiting readiness before adopting new code)`);
+      return w.child;
+    });
+    if (!started) return false;
+    // `startWorker` returns the instant the child is forked — but the replacement
+    // still has to import the plugin, build its SDK client, and start its
+    // activation loop before it serves jobs. Signalling "reloaded" here lets
+    // `runReload` advance to drain the NEXT worker, so returning on the bare spawn
+    // could leave the just-respawned worker AND the next (draining) worker down at
+    // once, breaking the one-at-a-time guarantee (Copilot review on #253). Gate on
+    // the replacement stamping `readyAt` on its activity marker (it is up and
+    // leasing) before we return. Bounded so a slow/never-ready replacement can't
+    // wedge the roll — on timeout we advance anyway (degrading to spawn-and-advance).
+    await waitForWorkerReady(w, started, SUPERVISOR_RELOAD_READY_TIMEOUT_MS);
+    // Report reloaded only when the child we spawned is STILL this worker's live
+    // current child. `waitForWorkerReady` returns even when the replacement exited
+    // (crash/spawn-fail) or was swapped by a concurrent restart/remove — in those
+    // cases no replacement is actually running, so counting it as reloaded would
+    // let the terminal frame claim success and let the roll drain the next worker
+    // with this one down (#253 review). A readiness *timeout* on a still-live
+    // current child still counts as success — readiness is best-effort.
+    //
+    // Gate on the LIVE PID, not just object identity + null exit/signal: a spawn
+    // failure (ENOENT/EMFILE/…) emits only 'error' with NO 'exit', so
+    // `exitCode`/`signalCode` stay null and `w.child` keeps pointing at the failed
+    // ChildProcess until its backoff retry — the identity+exit check alone would
+    // count that as reloaded (#253 review). `handleDeath` nulls `w.pid` on every
+    // death (error OR exit), and a failed spawn has no `child.pid`, so requiring
+    // `w.pid` to be non-null AND still equal to this child's pid rejects both a
+    // failed spawn and a dead/retrying child while accepting a live replacement
+    // (readiness timeout included).
+    //
+    // Also reject `w.stopping`: a concurrent `remove`/`restart`/`stop` sets that
+    // flag (and clears the restart timer) BEFORE its kill signal lands, so for a
+    // brief window `w.child`/`w.pid` still point at the live replacement we just
+    // spawned. Counting that as reloaded would let the roll drain the NEXT worker
+    // while this one is being torn down — a partial-fleet outage. A worker being
+    // stopped has no confirmed serving replacement, so treat it as a failed
+    // reload (the `runReload` else-branch then aborts the roll, #253 review).
+    //
+    // Also reject `shuttingDown`: a `stop` can begin DURING this replacement's
+    // readiness wait, after which `waitForWorkerReady` still returns and (for a
+    // last target) `w.stopping` may not be latched yet — so without this the gate
+    // would report a clean reload while shutdown is already tearing the fleet
+    // down. A daemon that is shutting down has no serving future for this worker,
+    // so treat a shutdown observed before the gate as a failed/interrupted reload
+    // (the `runReload` else-branch aborts the roll, #253 review).
+    return w.child === started && !w.stopping && !shuttingDown && w.pid != null && w.pid === started.pid
+      && started.exitCode === null && started.signalCode === null;
+  };
+
+  // Rolling hot reload across a set of worker ids: drain+respawn each in turn
+  // (one at a time, so the rest of the fleet keeps serving). Streams progress to
+  // `sock` (registered as an attach consumer for the interleaved worker events)
+  // and ends with a terminal `reloaded` frame. Aborts early if the daemon starts
+  // shutting down. Never clears `supervisor.json` — a reload is not a stop.
+  const runReload = async (ids, sock) => {
+    reloading = true;
+    const reloaded = [];
+    const skipped = [];
+    let interrupted = false;
+    try {
+      for (let i = 0; i < ids.length; i++) {
+        const id = ids[i];
+        // If the daemon starts shutting down mid-roll, the remaining workers
+        // never adopt the new code — record them as skipped (and flag the roll
+        // interrupted) so the terminal frame can't report a clean success for a
+        // pass that stopped early.
+        if (shuttingDown) {
+          interrupted = true;
+          for (let j = i; j < ids.length; j++) skipped.push(ids[j]);
+          break;
+        }
+        // A target that has vanished mid-roll (only `remove`/drain-remove deletes
+        // the entry — `restart` keeps it) has NO confirmed serving replacement,
+        // exactly like the reload-failure branch below. Continuing to drain the
+        // NEXT worker on top of that gap is the same partial-fleet risk the canary
+        // exists to prevent, so treat a removed-mid-roll target uniformly: mark it
+        // and every remaining id skipped and abort the roll (#253 review).
+        if (!workers.has(id)) {
+          interrupted = true;
+          for (let j = i; j < ids.length; j++) skipped.push(ids[j]);
+          break;
+        }
+        const ok = await reloadWorker(id);
+        if (ok) {
+          reloaded.push(id);
+          // Emit the per-worker "reloaded" progress signal ONLY after the final
+          // success gate above confirmed a live, still-current replacement — not
+          // at spawn time. A crash/spawn-fail makes `reloadWorker` return false
+          // and the worker is skipped, so broadcasting at spawn time would let the
+          // streaming client print `reloaded "…" (adopted new code)` for a reload
+          // that actually failed (#253 review).
+          broadcast({ type: 'event', event: 'worker-reload', id });
+        }
+        else {
+          // A reload FAILURE (not a mere readiness timeout — that returns true on
+          // a still-live child) means this worker has NO confirmed serving
+          // replacement: it crashed, failed to spawn, or was concurrently swapped.
+          // Draining the NEXT worker on top of that gap breaks the one-at-a-time
+          // guarantee AND could roll a broken replacement across the whole fleet.
+          // Stop the roll here (a canary), marking this + every remaining id
+          // skipped so the terminal frame reports a partial failure (#253 review).
+          interrupted = true;
+          for (let j = i; j < ids.length; j++) skipped.push(ids[j]);
+          break;
+        }
+        try { sock.write(encodeFrame(statusFrame(false))); } catch { /* client gone */ }
+      }
+    } catch (err) {
+      interrupted = true;
+      dlog(`reload error: ${err?.message || err}`);
+    } finally {
+      reloading = false;
+      // Terminal success requires BOTH a clean pass (not interrupted) AND nothing
+      // skipped: a skipped worker (failed reload, or removed/absent mid-roll) is a
+      // partial reload, so `ok: true` would let the streaming client exit zero and
+      // hide it from automation (#253 review). Propagate the partial failure.
+      const ok = !interrupted && skipped.length === 0;
+      try { sock.write(encodeFrame({ ok, type: 'reloaded', reloaded, skipped, interrupted, final: true })); } catch { /* client gone */ }
+    }
+  };
+
+
   // Resolve a target token to worker ids: exact id, else all with that profile.
   const resolveTargets = (target) => {
     const t = String(target || '').trim();
@@ -11655,6 +11955,11 @@ async function runSupervisorDaemon() {
     ok: true,
     type: 'status',
     daemon: supervisorDaemonDescriptor({ pid: process.pid, startedAt, version: daemonVersion, socket: socketPath, logFile: daemonLogFile }),
+    // The plugin version currently ON DISK (re-read each call), so `status` can
+    // flag when a `nano update` has advanced the code past the running daemon —
+    // i.e. a `supervisor reload` would adopt new worker code (and a daemon
+    // restart new supervisor code). Best-effort; falls back to the daemon's own.
+    pluginVersion: (() => { try { return pluginPackage().version; } catch { return daemonVersion; } })(),
     workers: pub || [...workers.values()].map(workerPublic),
     ...(final ? { final: true } : {}),
   });
@@ -11758,6 +12063,50 @@ async function runSupervisorDaemon() {
           sock.write(encodeFrame({ ok: true, type: 'restarted', restarted, final: true }));
           break;
         }
+        case 'reload': {
+          // Hot code adoption: rolling graceful drain+respawn so worker children
+          // re-read the updated plugin from disk with zero fleet downtime.
+          // Accepts a single `target` token (id|profile|all) or a `targets`
+          // array (workforce passes its exact owned id list). Streams progress
+          // and ends with a terminal `reloaded` frame — draining can take a long
+          // time, so this MUST be a streaming op, not a one-shot request.
+          if (shuttingDown) { sock.write(encodeFrame({ ok: false, error: 'supervisor is shutting down', final: true })); break; }
+          if (reloading) { sock.write(encodeFrame({ ok: false, error: 'a reload is already in progress', final: true })); break; }
+          // Reject reload explicitly on Windows BEFORE draining anything. The
+          // rolling reload's graceful drain relies on SIGUSR2 (SUPERVISOR_DRAIN_SIGNAL)
+          // to quiesce each worker child; Windows cannot deliver SIGUSR2 (Node maps
+          // a non-zero signal there to a forceful, SIGKILL-like termination, and the
+          // child's `process.once('SIGUSR2')` drain handler never fires), so a
+          // "graceful" drain either hard-kills in-flight work or leaves `reloadWorker`
+          // waiting forever for a child that was never asked to exit. Fail fast with
+          // an actionable message instead of hanging the roll on the first worker
+          // (#253 review). `restart`/`stop`+`start` remain the Windows path to adopt
+          // new code.
+          if (osPlatform() === 'win32') {
+            sock.write(encodeFrame({ ok: false, error: 'hot reload is not supported on Windows (its graceful drain relies on SIGUSR2, which Windows cannot deliver) — use `supervisor restart <target>`, or `supervisor stop` + `start`, to adopt new code', final: true }));
+            break;
+          }
+          const raw = Array.isArray(req.targets)
+            ? req.targets.flatMap((t) => resolveTargets(t))
+            : resolveTargets(req.target);
+          const ids = [...new Set(raw)];
+          if (ids.length === 0) { sock.write(encodeFrame({ ok: true, type: 'reloaded', reloaded: [], skipped: [], final: true })); break; }
+          // Register as an attach consumer so the client also sees the
+          // interleaved worker-reload/start events, then send an opening frame
+          // and kick the rolling reload asynchronously (don't block the control
+          // loop — a `stop`/`status` must still be serviceable meanwhile). Latch
+          // `reloading` HERE, before scheduling: `runReload` only sets it once it
+          // actually runs on a later tick, so a second `reload` socket arriving
+          // in that window would otherwise still see `false` and start a duplicate
+          // rolling pass over the same workers. The flag is reset in runReload's
+          // `finally`.
+          reloading = true;
+          attachClients.add(sock);
+          sock.write(encodeFrame({ ok: true, type: 'reloading', targets: ids }));
+          sock.write(encodeFrame(statusFrame(false)));
+          setTimeout(() => { runReload(ids, sock); }, 0);
+          break;
+        }
         case 'attach':
           attachClients.add(sock);
           sock.write(encodeFrame(statusFrame(false)));
@@ -11879,11 +12228,19 @@ async function runSupervisorDaemon() {
     return Number.isFinite(n) && n >= 0 ? Math.floor(n) : SUPERVISOR_MONITOR_INTERVAL_MS;
   })();
   if (monitorMs > 0) {
-    lastMonitorSig = supervisorStatusSignature([...workers.values()].map(workerPublic));
+    // Fold the on-disk plugin version into the monitor signature so a `nano update`
+    // that changes ONLY the on-disk package (no worker transition) still repaints
+    // attached consoles with the new version + `supervisor reload` hint (#253
+    // review). The worker-field signature alone never changes on a version-only
+    // bump, so an idle fleet would otherwise hide an available reload until an
+    // unrelated worker transition or a manual `status`.
+    const monitorSignature = (pub) =>
+      `${supervisorStatusSignature(pub)}\u0000${(() => { try { return pluginPackage().version; } catch { return daemonVersion; } })()}`;
+    lastMonitorSig = monitorSignature([...workers.values()].map(workerPublic));
     monitorTimer = setInterval(() => {
       if (shuttingDown) return;
       const pub = [...workers.values()].map(workerPublic);
-      const sig = supervisorStatusSignature(pub);
+      const sig = monitorSignature(pub);
       const changed = sig !== lastMonitorSig;
       lastMonitorSig = sig;
       if (changed && attachClients.size > 0) broadcast(statusFrame(false, pub));
@@ -12075,7 +12432,7 @@ async function supervisorStartCmd(req, flags, ctx) {
   await supervisorStatusCmd();
   logger.info('');
   logger.info('Attach an interactive console with: c8ctl nano supervisor');
-  logger.info('Manage without it:                  c8ctl nano supervisor add|remove|restart|status|stop');
+  logger.info('Manage without it:                  c8ctl nano supervisor add|remove|restart|reload|status|stop');
 }
 
 async function supervisorStatusCmd() {
@@ -12168,6 +12525,97 @@ async function supervisorRestartCmd(req) {
   else { logger.error(res.error); process.exit(1); }
 }
 
+/**
+ * Stream a rolling hot reload of the fleet and log its progress. Shared by
+ * `supervisor reload` and `workforce reload`. Sends `req` (a `reload` op with a
+ * `target` token or a `targets` array) and resolves with the outcome that ended
+ * the stream ('reloaded' | 'detached' | 'closed' | 'unreachable'). Ctrl-C
+ * DETACHES the client — the daemon keeps reloading in the background.
+ */
+async function streamSupervisorReload(socketPath, req, logger, { label = 'fleet' } = {}) {
+  return await new Promise((resolve) => {
+    let sock = null;
+    let buf = '';
+    let done = false;
+    let onSigint = null;
+    const cleanup = () => {
+      if (onSigint) { try { process.removeListener('SIGINT', onSigint); } catch { /* ignore */ } }
+      try { if (sock) sock.end(); } catch { /* ignore */ }
+    };
+    const finish = (result) => { if (done) return; done = true; cleanup(); resolve(result); };
+
+    supervisorConnect(socketPath).then((s) => {
+      sock = s;
+      sock.setEncoding('utf8');
+      onSigint = () => {
+        logger.info('Detached — supervisor keeps reloading in the background. Rerun `nano supervisor status` to check progress.');
+        finish('detached');
+      };
+      process.on('SIGINT', onSigint);
+
+      sock.on('data', (chunk) => {
+        buf += chunk;
+        const { frames, rest } = decodeFrames(buf);
+        buf = rest;
+        for (const frame of frames) {
+          if (!frame) continue;
+          // Handle the terminal `reloaded` frame BEFORE the generic `ok:false`
+          // request-error guard: `runReload` emits a partial failure as a
+          // terminal `{ type:'reloaded', final:true, ok:false, reloaded, skipped }`
+          // frame, so the bare `ok === false` guard would swallow it as a generic
+          // "reload failed" and hide which workers reloaded/skipped (#253 review).
+          // We still exit non-zero for `ok:false` so automation sees the partial.
+          // Match ONLY `type:'reloaded'`, never a bare `frame.final`: generic
+          // terminal error frames (e.g. `{ok:false, error:'a reload is already in
+          // progress', final:true}`) are also `final` but carry no reloaded/skipped
+          // lists, so this branch would print "No workers were reloaded" and hide
+          // `frame.error` — they must fall through to the `ok === false` guard below.
+          if (frame.type === 'reloaded') {
+            const reloaded = Array.isArray(frame.reloaded) ? frame.reloaded : [];
+            const skipped = Array.isArray(frame.skipped) ? frame.skipped : [];
+            if (reloaded.length > 0) logger.info(`Reloaded ${reloaded.length} worker(s): ${reloaded.join(', ')}.`);
+            else logger.warn('No workers were reloaded.');
+            if (skipped.length > 0) logger.warn(`Skipped (gone/changed, or roll aborted after a failed reload): ${skipped.join(', ')}.`);
+            finish(frame.ok === false ? 'error' : 'reloaded');
+            return;
+          }
+          if (frame.ok === false) { logger.error(frame.error || 'reload failed'); finish('error'); return; }
+          if (frame.type === 'reloading') {
+            const n = Array.isArray(frame.targets) ? frame.targets.length : 0;
+            logger.info(`Reloading ${n} worker(s) in ${label} one at a time (draining in-flight jobs first). Press Ctrl-C to detach.`);
+          } else if (frame.event === 'worker-reload' && frame.id) {
+            logger.info(`  reloaded "${frame.id}" (adopted new code).`);
+          }
+        }
+      });
+      sock.on('error', () => finish('closed'));
+      sock.on('close', () => finish('closed'));
+      sock.write(encodeFrame(req));
+    }).catch(() => finish('unreachable'));
+  });
+}
+
+/**
+ * Hot-adopt new plugin code into the running fleet with zero downtime: roll
+ * through the target workers, gracefully draining (finish in-flight jobs) and
+ * respawning each so the new child re-reads the updated `c8ctl-plugin.js` from
+ * disk. Defaults to the whole fleet. Note this adopts new WORKER code only; the
+ * supervisor daemon itself keeps running its startup code until a full restart
+ * (`supervisor stop && supervisor start`).
+ */
+async function supervisorReloadCmd(req) {
+  const logger = getLogger();
+  // Default to the whole fleet: "adopt new code" naturally means every worker.
+  const target = req.positional[1] || 'all';
+  const running = await liveSupervisor();
+  if (!running) { logger.error('Supervisor is not running.'); process.exit(1); }
+  const socketPath = running.socket || getSupervisorSocketPath();
+  const outcome = await streamSupervisorReload(socketPath, { op: 'reload', target }, logger, { label: 'the fleet' });
+  if (outcome === 'unreachable') { logger.error('Could not reach the supervisor control socket to reload it.'); process.exit(1); }
+  if (outcome === 'closed') { logger.error('The supervisor closed the connection before the reload finished (daemon crash or concurrent stop?) — the roll may be incomplete. Rerun `nano supervisor status` to check the fleet.'); process.exit(1); }
+  if (outcome === 'error') process.exit(1);
+}
+
 /**
  * Count the in-flight jobs across a fleet snapshot (array of
  * `summarizeSupervisorWorker` results) — the number an operator is waiting on
@@ -12967,6 +13415,9 @@ async function supervisorCommand(req, flags, ctx) {
     case 'restart':
       await supervisorRestartCmd(req);
       return;
+    case 'reload':
+      await supervisorReloadCmd(req);
+      return;
     case 'stop':
       await supervisorStopCmd(coerceBool(flags?.force, false));
       return;
@@ -12975,7 +13426,7 @@ async function supervisorCommand(req, flags, ctx) {
       supervisorLogsCmd(req);
       return;
     default:
-      getLogger().error(`Unknown supervisor action "${action}". Use: start|install|uninstall|status|add|remove|restart|stop|logs|attach`);
+      getLogger().error(`Unknown supervisor action "${action}". Use: start|install|uninstall|status|add|remove|restart|reload|stop|logs|attach`);
       process.exit(1);
   }
 }
@@ -13924,6 +14375,41 @@ async function workforceStopCmd(req, flags, manifestName) {
   if (hadError) process.exit(1);
 }
 
+/**
+ * Hot-adopt new plugin code into a workforce's running workers with zero
+ * downtime: roll through the manifest-owned workers, gracefully draining and
+ * respawning each so the new child re-reads the updated plugin from disk.
+ * Mirrors `workforce stop`'s ownership resolution (longest-prefix match + a
+ * live-profile collision guard) so it only ever reloads workers this manifest
+ * owns.
+ */
+async function workforceReloadCmd(req, flags, manifestName) {
+  const logger = getLogger();
+  const running = await liveSupervisor();
+  if (!running) { logger.error('Supervisor is not running.'); process.exit(1); }
+  const manifestNames = listWorkforceManifestNames();
+  const { running: stillRunning, reachable, workers: live } = await fetchSupervisorWorkers();
+  if (!stillRunning) { logger.warn('Supervisor is not running — nothing to reload.'); return; }
+  if (!reachable) {
+    logger.error('Supervisor is running but its status socket is unreachable — cannot enumerate workers.');
+    process.exit(1);
+  }
+  const owned = live
+    .filter((w) => w && typeof w.id === 'string' && isWorkforceOwnedWorker(w.id, manifestName, manifestNames))
+    .filter((w) => {
+      const embedded = workforceProfileFromWorkerName(manifestName, w.id);
+      if (embedded != null && w.profile != null && w.profile !== embedded) return false;
+      return true;
+    })
+    .map((w) => w.id);
+  if (owned.length === 0) { logger.info(`No workers from workforce "${manifestName}" are running.`); return; }
+  const socketPath = running.socket || getSupervisorSocketPath();
+  const outcome = await streamSupervisorReload(socketPath, { op: 'reload', targets: owned }, logger, { label: `workforce "${manifestName}"` });
+  if (outcome === 'unreachable') { logger.error('Could not reach the supervisor control socket to reload it.'); process.exit(1); }
+  if (outcome === 'closed') { logger.error('The supervisor closed the connection before the reload finished (daemon crash or concurrent stop?) — the roll may be incomplete. Rerun `nano supervisor status` to check the fleet.'); process.exit(1); }
+  if (outcome === 'error') process.exit(1);
+}
+
 async function workforceCommand(req, flags) {
   const logger = getLogger();
   const action = (req.positional[0] || '').toLowerCase();
@@ -13961,8 +14447,11 @@ async function workforceCommand(req, flags) {
     case 'down':
       await workforceStopCmd(req, flags, manifestName);
       return;
+    case 'reload':
+      await workforceReloadCmd(req, flags, manifestName);
+      return;
     default:
-      logger.error(`Unknown workforce action "${action}". Use: add|remove|list|start|status|stop`);
+      logger.error(`Unknown workforce action "${action}". Use: add|remove|list|start|status|stop|reload`);
       process.exit(1);
   }
 }
@@ -15808,6 +16297,8 @@ export {
   agenticStateForTarget,
   normalizeAgenticMessage,
   buildActivityPayload,
+  activityMarkerReadyFor,
+  waitForChildExit,
   supervisorWorkerActivityFile,
   WORK_FORWARD_FLAGS,
   installParentDeathWatchdog,
@@ -15816,6 +16307,8 @@ export {
   supervisorRequest,
   supervisorStartCmd,
   supervisorAddCmd,
+  supervisorReloadCmd,
+  workforceReloadCmd,
   runningSupervisor,
   readSupervisorState,
   clearSupervisorState,
@@ -15922,6 +16415,7 @@ export const metadata = {
         { command: 'c8ctl nano supervisor add decider', description: 'Add a supervised worker (forwarding work flags) to the running supervisor' },
         { command: 'c8ctl nano supervisor add reviewer --instances 3', description: 'Add 3 distinct auto-named instances of a profile in one call' },
         { command: 'c8ctl nano supervisor restart reviewer', description: 'Restart a supervised worker by id or profile' },
+        { command: 'c8ctl nano supervisor reload', description: 'Adopt updated harness code with zero downtime: after `nano update`, roll through the fleet draining in-flight jobs and respawning each worker so it re-reads the new plugin (workers only; restart the daemon for new supervisor code)' },
         { command: 'c8ctl nano supervisor stop', description: 'Stop the supervisor daemon and all its workers' },
         { command: 'c8ctl nano workforce add copilot --instances 5 --auto', description: 'Compose a reusable fleet: 5 copilot workers serving every deployed agent job type (--auto)' },
         { command: 'c8ctl nano workforce add qwen --instances 2 --roles pr-review,feature', description: "Add an entry mapped to explicit job types (<rank>:pr-review, <rank>:feature, where <rank> is the qwen hire's rank at start) — does not mutate the hired profile" },
@@ -15930,6 +16424,7 @@ export const metadata = {
         { command: 'c8ctl nano workforce status --json', description: 'Manifest entries joined against live supervisor status (desired vs actual), machine-readable for the install script / CI' },
         { command: 'c8ctl nano workforce list', description: 'Print the default manifest and list the manifests that exist on this machine' },
         { command: 'c8ctl nano workforce stop', description: "Remove this manifest's workers; stop the daemon too if no supervised workers remain" },
+        { command: 'c8ctl nano workforce reload', description: "Hot-adopt updated code into this manifest's workers (rolling graceful drain+respawn, zero downtime)" },
       ],
     },
     processos: {
@@ -16161,8 +16656,8 @@ function printUsage() {
   console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--terminal pty|pipe] [--protocol pipe|acp] [--permission yolo|escalate|filter] [--env NAME=VALUE ...] [--list]');
   console.log('  c8ctl nano assign <profileName> <cap[,cap...]> [--name <n>] [--capabilities <a,b>]');
   console.log('  c8ctl nano work <profileName> [--auto [--auto-scope <p>]] [--arg <switch> ...] [--recovery-window <ms>] [--idle-timeout <ms>] [--job-timeout <ms>] [--poll-timeout <ms>] [--job-type <token> ...] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
-  console.log('  c8ctl nano supervisor [start|install|uninstall|status|add|remove|restart|stop|logs|attach] ... (manage many workers from one terminal)');
-  console.log('  c8ctl nano workforce [add|remove|list|start|status|stop] ... [--manifest <manifest>] (declarative, reusable fleet manifests)');
+  console.log('  c8ctl nano supervisor [start|install|uninstall|status|add|remove|restart|reload|stop|logs|attach] ... (manage many workers from one terminal)');
+  console.log('  c8ctl nano workforce [add|remove|list|start|status|stop|reload] ... [--manifest <manifest>] (declarative, reusable fleet manifests)');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -16181,7 +16676,7 @@ function printUsage() {
   console.log('  assign   Grant new capabilities (roles) to an existing hire (additive; comma-separated; workers hot-reload)');
   console.log('  work     Run a hired profile as Nano job workers, polling for work until Ctrl-C');
   console.log('  supervisor  Run/manage a fleet of workers from one terminal (detachable console + non-interactive control)');
-  console.log('  workforce   Compose a reusable, declarative fleet manifest and reconcile it up/down (add|remove|list|start|status|stop)');
+  console.log('  workforce   Compose a reusable, declarative fleet manifest and reconcile it up/down (add|remove|list|start|status|stop|reload)');
   console.log('');
   console.log('Options:');
   console.log('  <nodes>              Number of nodes to start (default 1)');