c8ctl-plugin-nano 1.19.0 → 1.21.0

package/c8ctl-plugin.js

@@ -35,6 +35,7 @@ import {
   openSync,
   readFileSync,
   writeFileSync,
+  appendFileSync,
   rmSync,
   readdirSync,
   chmodSync,
@@ -43,13 +44,18 @@ import {
   statfsSync,
   lstatSync,
   mkdtempSync,
+  closeSync,
+  watchFile,
+  unwatchFile,
 } from 'node:fs';
-import { randomUUID } from 'node:crypto';
-import { homedir, platform as osPlatform, devNull } from 'node:os';
+import { createConnection, createServer } from 'node:net';
+import { randomUUID, createHash } from 'node:crypto';
+import { homedir, platform as osPlatform, devNull, tmpdir } from 'node:os';
 import { join, isAbsolute, resolve as resolvePath, dirname, basename, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
+import { createInterface as createReadline } from 'node:readline';
 import { platformForHost } from './platforms.mjs';
 
 const requireFromHere = createRequire(import.meta.url);
@@ -117,6 +123,7 @@ const READINESS_POLL_MS = 500;
 const HEALTH_TIMEOUT_MS = 1_500;
 const STOP_GRACE_MS = 8_000;
 const PROCESSOS_STATE_FILE = 'processos.json';
+const SUPERVISOR_STATE_FILE = 'supervisor.json';
 const PROCESSOS_DEFAULT_PORT = 8090;
 const DEFAULT_NANO_URL = 'http://localhost:8080';
 
@@ -191,6 +198,34 @@ function getLogDir() {
   return join(getStateHome(), 'logs');
 }
 
+// ---------------------------------------------------------------------------
+// Worker supervisor paths (see the `supervisor` command). The supervisor is a
+// detached daemon that manages a fleet of `nano work` child processes; it keeps
+// its own state file, a control socket, and per-worker + daemon log files.
+// ---------------------------------------------------------------------------
+
+function getSupervisorStateFile() {
+  return join(getStateHome(), SUPERVISOR_STATE_FILE);
+}
+
+function getSupervisorLogDir() {
+  return join(getLogDir(), 'supervisor');
+}
+
+/**
+ * Deterministic control-socket path shared by the daemon and every client.
+ * Derived from a hash of the (possibly overridden) state home so distinct
+ * C8CTL_NANO_HOME instances get distinct sockets, and kept SHORT to stay under
+ * the ~104-byte AF_UNIX `sun_path` limit on macOS regardless of username. On
+ * Windows a named pipe is used instead. The chosen path is also recorded in the
+ * state file so clients can prefer the daemon's own reported path.
+ */
+function getSupervisorSocketPath() {
+  const hash = createHash('sha1').update(getStateHome()).digest('hex').slice(0, 8);
+  if (osPlatform() === 'win32') return `\\\\.\\pipe\\c8ctl-nano-sup-${hash}`;
+  return join(tmpdir(), `c8ctl-nano-sup-${hash}.sock`);
+}
+
 // ---------------------------------------------------------------------------
 // Persistent plugin config (config.json) — user settings that survive across
 // clusters: the binary path and the workspace (models/workers) location.
@@ -200,20 +235,39 @@ function getConfigFile() {
   return join(getStateHome(), CONFIG_FILE);
 }
 
-function readConfig() {
+function readConfigStrict() {
   const file = getConfigFile();
   if (!existsSync(file)) return {};
+  const cfg = JSON.parse(readFileSync(file, 'utf-8'));
+  return cfg && typeof cfg === 'object' ? cfg : {};
+}
+
+function readConfig() {
   try {
-    const cfg = JSON.parse(readFileSync(file, 'utf-8'));
-    return cfg && typeof cfg === 'object' ? cfg : {};
+    return readConfigStrict();
   } catch {
+    // A malformed/torn config.json is swallowed here so ordinary callers get an
+    // empty map; callers that must tell "absent" from "unreadable" apart use
+    // readConfigStrict() directly and handle the throw.
     return {};
   }
 }
 
 function writeConfig(cfg) {
   mkdirSync(getStateHome(), { recursive: true });
-  writeFileSync(getConfigFile(), JSON.stringify(cfg, null, 2));
+  // Atomic write: serialize to a temp file in the same dir, then rename over the
+  // target. A rename is atomic on a POSIX filesystem, so a concurrent reader
+  // (e.g. `work`'s profile watcher, or another `assign`) never observes a
+  // half-written config.json and JSON.parse never sees a torn file.
+  const target = getConfigFile();
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+  try {
+    renameSync(tmp, target);
+  } catch (err) {
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    throw err;
+  }
 }
 
 /**
@@ -368,7 +422,7 @@ function launcherEnvMarkers(resolved) {
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'assign', 'work'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'assign', 'work', 'supervisor'];
 
 /**
  * Parse positional args + flags into a normalized request.
@@ -1565,6 +1619,21 @@ function jobTypeMatrix(rank, capabilities) {
   return [...new Set(tokens)];
 }
 
+/**
+ * Diff a running set of job-type pollers against a desired set. Pure so the
+ * profile-watch reconcile in `work` (which starts pollers for `added` types and
+ * gracefully drains pollers for `removed` types) is unit-testable. Order in the
+ * returned arrays is stable (desired order for `added`, current order for
+ * `removed`) for deterministic logging.
+ */
+function diffJobTypes(current, desired) {
+  const cur = new Set(current);
+  const want = new Set(desired);
+  const added = [...want].filter((t) => !cur.has(t));
+  const removed = [...cur].filter((t) => !want.has(t));
+  return { added, removed };
+}
+
 /** All persisted hire profiles, keyed by name. */
 function readHires() {
   const cfg = readConfig();
@@ -1573,6 +1642,16 @@ function readHires() {
   return cfg.hires && typeof cfg.hires === 'object' && !Array.isArray(cfg.hires) ? cfg.hires : {};
 }
 
+/**
+ * Like readHires(), but propagates a malformed-config parse error instead of
+ * swallowing it. Lets a caller distinguish "profile genuinely removed" from
+ * "config temporarily unreadable/torn" so it can report an accurate reason.
+ */
+function readHiresStrict() {
+  const cfg = readConfigStrict();
+  return cfg.hires && typeof cfg.hires === 'object' && !Array.isArray(cfg.hires) ? cfg.hires : {};
+}
+
 /** Persist a single hire profile into config.json under `hires`. */
 function writeHire(profile) {
   const cfg = readConfig();
@@ -2975,7 +3054,10 @@ async function workAgent(req, flags) {
   logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobKillMs}ms; activation lock: ${jobLockMs}ms; poll timeout: ${pollTimeoutMs}ms`);
   logger.info('Polling for work — press Ctrl-C to stop.');
 
-  const workers = jobTypes.map((jobType) =>
+  // A per-job-type worker factory. Captures all the CLI-local + profile context
+  // in closure scope so the profile watcher below can (re)spawn a poller for any
+  // job type on demand without re-reading the flags.
+  const makeWorker = (jobType) =>
     camunda.createJobWorker({
       jobType,
       workerName: `${name}:${jobType}`,
@@ -3156,35 +3238,172 @@ async function workAgent(req, flags) {
           variables: { [AGENT_RESULT_KEY]: resultEnvelope },
         });
       },
-    }),
-  );
+    });
+
+  // Live worker registry keyed by job type, so the profile watcher can add or
+  // drain individual pollers without disturbing the others. `draining` is the
+  // shutdown latch (shared with the watcher so a reconcile can't race a stop).
+  const workers = new Map();
+  let draining = false;
+
+  const drainWorker = async (w) => {
+    try {
+      if (typeof w.stopGracefully === 'function') {
+        await w.stopGracefully({ waitUpToMs: STOP_GRACE_MS });
+      } else if (typeof w.stop === 'function') {
+        await w.stop();
+      }
+      return true;
+    } catch {
+      return false; // best-effort: never let one worker's stop failure hang us
+    }
+  };
+
+  const spawnJobType = (jobType) => {
+    if (workers.has(jobType)) return false;
+    workers.set(jobType, makeWorker(jobType));
+    return true;
+  };
+
+  for (const jobType of jobTypes) spawnJobType(jobType);
+
+  // ---- Live profile watch: reconcile the poller set when the watched profile's
+  // job types change (e.g. `c8ctl nano assign <name> …`) — start pollers for
+  // added types, gracefully drain pollers for removed types — without a restart
+  // and without disturbing unchanged types' in-flight work. ----
+  const configFile = getConfigFile();
+  const WATCH_INTERVAL_MS = 1500;
+  let reconciling = false;
+  // Set when a profile change arrives while a reconcile is already in flight, so
+  // we run one more pass after the current drain completes instead of dropping
+  // the update until the next change fires.
+  let reconcileRequested = false;
+  // Handle to the in-flight reconcile so shutdown can wait for it to finish
+  // before snapshotting `workers` (avoids double-stops / missed drains).
+  let inFlightReconcile = null;
+
+  // Desired job types from the CURRENT on-disk profile (matrix ∪ --job-type
+  // extras). Returns { skip } for a transient/torn read, a vanished profile, or
+  // an invalid edit — callers must then KEEP the running set, never tear down.
+  const desiredJobTypes = () => {
+    let stored;
+    try {
+      stored = readHiresStrict()[name];
+    } catch {
+      // config.json exists but doesn't parse (e.g. a torn write): the profile is
+      // NOT necessarily gone, so don't claim it was deleted — skip this pass.
+      return { skip: 'config unreadable' };
+    }
+    if (!stored) return { skip: 'deleted' };
+    const norm = normalizeStoredProfile(name, stored);
+    if (norm.error) return { skip: norm.error };
+    const m = jobTypeMatrix(norm.profile.rank, norm.profile.capabilities);
+    return { jobTypes: [...new Set([...m, ...extraJobTypes])] };
+  };
+
+  const reconcile = () => {
+    if (draining) return inFlightReconcile || Promise.resolve();
+    if (reconciling) {
+      // A change landed mid-reconcile — remember it so the current pass loops
+      // once more rather than leaving the worker set stale until the next edit.
+      // Return the ACTUAL in-flight promise (not a fresh short-lived one) so a
+      // caller — including shutdown — waits for the real reconcile to finish.
+      reconcileRequested = true;
+      return inFlightReconcile || Promise.resolve();
+    }
+    reconciling = true;
+    reconcileRequested = false;
+    inFlightReconcile = (async () => {
+      try {
+        do {
+          reconcileRequested = false;
+          await runReconcilePass();
+        } while (reconcileRequested && !draining);
+      } finally {
+        reconciling = false;
+        inFlightReconcile = null;
+      }
+    })();
+    return inFlightReconcile;
+  };
+
+  const runReconcilePass = async () => {
+      const desired = desiredJobTypes();
+      if (desired.skip) {
+        if (desired.skip === 'deleted') {
+          logger.warn(`Profile "${name}" is gone from config — keeping the current ${workers.size} worker(s) running.`);
+        } else {
+          logger.warn(`Profile "${name}" reload skipped — ${desired.skip}; keeping current workers.`);
+        }
+        return;
+      }
+      const { added, removed } = diffJobTypes([...workers.keys()], desired.jobTypes);
+      if (added.length === 0 && removed.length === 0) return;
+      logger.info(`Profile "${name}" changed — reconciling job types (+${added.length} / -${removed.length}).`);
+      for (const jt of added) {
+        spawnJobType(jt);
+        logger.info(`  + now listening on ${jt}`);
+      }
+      await Promise.all(
+        removed.map(async (jt) => {
+          const w = workers.get(jt);
+          logger.info(`  - draining ${jt} …`);
+          const ok = await drainWorker(w);
+          if (ok) {
+            // Only drop it from the registry once it has actually stopped, so a
+            // failed drain stays tracked and gets retried on the next reconcile
+            // pass (or on shutdown) instead of leaking an untracked poller.
+            workers.delete(jt);
+            logger.info(`  - stopped ${jt}`);
+          } else {
+            logger.warn(`  - ${jt} did not stop cleanly; keeping it tracked so it is retried on the next reconcile or shutdown.`);
+          }
+        }),
+      );
+      logger.info(`  now listening on ${workers.size} job type(s): ${[...workers.keys()].join('  ')}`);
+  };
+
+  // `watchFile` (polling stat) is deliberate over `fs.watch`: it survives the
+  // atomic temp+rename that `writeConfig` does (fs.watch would rebind to the old
+  // inode and go silent), and it's uniform across platforms. Profile edits are
+  // rare + manual, so a ~1.5s poll latency is fine.
+  watchFile(configFile, { interval: WATCH_INTERVAL_MS }, (curr, prev) => {
+    // Fires each interval; act only on real changes. Compare mtime, ctime and
+    // size, not mtime alone: on filesystems with coarse mtime resolution (or two
+    // edits within one mtime tick) mtimeMs can be unchanged while size/ctimeMs
+    // differ, and an mtime-only guard would skip a genuine profile update.
+    if (
+      curr.mtimeMs === prev.mtimeMs &&
+      curr.ctimeMs === prev.ctimeMs &&
+      curr.size === prev.size
+    ) return;
+    // `reconcile()` owns the `inFlightReconcile` handle: a change arriving while
+    // a reconcile is already running coalesces into the current pass and returns
+    // that same in-flight promise, so shutdown always waits for the real one.
+    reconcile().catch((err) => logger.warn(`profile reload failed: ${err?.message || err}`));
+  });
 
   // Keep the process alive until a stop signal, then drain gracefully.
   await new Promise((resolve) => {
-    let stopping = false;
     const stop = async (signal) => {
-      if (stopping) return;
-      stopping = true;
-      logger.info(`Received ${signal} — stopping ${workers.length} worker(s)...`);
+      if (draining) return;
+      draining = true;
+      // Stop watching first so no new reconcile can be triggered, then wait for
+      // any in-flight reconcile to finish before snapshotting `workers` — this
+      // prevents double-stops, missed drains, or a wrong worker count on exit.
+      unwatchFile(configFile);
+      if (inFlightReconcile) {
+        logger.info('Waiting for in-flight profile reconcile to finish before shutdown…');
+        await inFlightReconcile;
+      }
+      const list = [...workers.values()];
+      logger.info(`Received ${signal} — stopping ${list.length} worker(s)...`);
       if (reaperTimer) clearInterval(reaperTimer);
       if (runDirTimer) clearInterval(runDirTimer);
-      let stopFailures = 0;
-      await Promise.all(
-        workers.map(async (w) => {
-          try {
-            if (typeof w.stopGracefully === 'function') {
-              await w.stopGracefully({ waitUpToMs: STOP_GRACE_MS });
-            } else if (typeof w.stop === 'function') {
-              await w.stop();
-            }
-          } catch {
-            // best-effort: never let one worker's stop failure hang shutdown
-            stopFailures += 1;
-          }
-        }),
-      );
+      const results = await Promise.all(list.map(drainWorker));
+      const stopFailures = results.filter((ok) => !ok).length;
       if (stopFailures > 0) {
-        logger.warn(`${stopFailures} of ${workers.length} worker(s) did not stop cleanly; some connections may still be open.`);
+        logger.warn(`${stopFailures} of ${list.length} worker(s) did not stop cleanly; some connections may still be open.`);
       } else {
         logger.info('All workers stopped.');
       }
@@ -3195,6 +3414,1051 @@ async function workAgent(req, flags) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// supervisor — run & manage a fleet of `nano work` children from one terminal.
+//
+// `nano work` needs the c8ctl host runtime (createClient), so worker loops
+// cannot run inside a bare detached process. The supervisor is therefore a
+// process *manager*: a detached daemon spawns one `c8ctl nano work <profile>`
+// child per worker, restarts crashed children with capped backoff, and serves a
+// control socket (newline-delimited JSON) used by both the management
+// subcommands (status/add/remove/restart/stop/logs — no interactive surface
+// needed) and the interactive `attach` console, which can be detached from
+// (leaving the daemon running) or used to `stop` the whole fleet.
+// ---------------------------------------------------------------------------
+
+const SUPERVISOR_BACKOFF_BASE_MS = 1_000;
+const SUPERVISOR_BACKOFF_MAX_MS = 30_000;
+// A child that stayed up at least this long before exiting is not crash-looping,
+// so its restart backoff is reset to zero.
+const SUPERVISOR_HEALTHY_UPTIME_MS = 60_000;
+const SUPERVISOR_CONNECT_TIMEOUT_MS = 6_000;
+// End-to-end deadline for a single request: once connected, a wedged/incompatible
+// daemon that accepts but never sends a `final` frame must not hang the client.
+const SUPERVISOR_RESPONSE_TIMEOUT_MS = 15_000;
+// Tighter end-to-end deadline for quick liveness probes (status checks used by
+// liveSupervisor/ensureSupervisor). Without this, a daemon that accepts the
+// connection but never returns a `final` frame would still block the "fast"
+// probe for the full SUPERVISOR_RESPONSE_TIMEOUT_MS, hanging stop/remove/restart.
+const SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS = 2_000;
+// Hard cap on a single connection's inbound buffer, so a misbehaving client
+// can't grow the daemon's memory without bound with a newline-free frame.
+const SUPERVISOR_MAX_FRAME_BYTES = 1 << 20; // 1 MiB
+
+// The `nano work` flags forwarded verbatim to each spawned child.
+// kind: 'value' → `--flag v`; 'boolean' → `--flag`; 'list' → repeated `--flag v`.
+const WORK_FORWARD_FLAGS = {
+  'max-parallel': 'value',
+  'job-timeout': 'value',
+  'lock-grace': 'value',
+  'poll-timeout': 'value',
+  sandbox: 'value',
+  image: 'value',
+  'secret-resolver': 'value',
+  'reap-age': 'value',
+  'reap-interval': 'value',
+  'min-free-mb': 'value',
+  'clone-timeout': 'value',
+  'keep-runs': 'boolean',
+  stream: 'boolean',
+  arg: 'list',
+  env: 'list',
+  'job-type': 'list',
+};
+
+/**
+ * Reconstruct the `work` argv tail from a parsed flags object, so `supervisor
+ * add <profile> [work flags]` forwards those flags to the spawned child. Pure.
+ */
+function reconstructWorkArgs(flags) {
+  const out = [];
+  if (!flags || typeof flags !== 'object') return out;
+  for (const [name, kind] of Object.entries(WORK_FORWARD_FLAGS)) {
+    const v = flags[name];
+    if (v === undefined || v === null) continue;
+    if (kind === 'boolean') {
+      if (v === true || v === 'true') out.push(`--${name}`);
+    } else if (kind === 'list') {
+      const items = Array.isArray(v) ? v : [v];
+      for (const item of items) {
+        if (item === undefined || item === null) continue;
+        out.push(`--${name}`, String(item));
+      }
+    } else if (v !== '') {
+      out.push(`--${name}`, String(v));
+    }
+  }
+  return out;
+}
+
+/** Assign a unique, stable worker id from a profile name (pure). */
+function supervisorWorkerId(profile, taken) {
+  const base = String(profile || '').trim() || 'worker';
+  const set = taken instanceof Set ? taken : new Set(taken || []);
+  if (!set.has(base)) return base;
+  for (let i = 2; ; i++) {
+    const candidate = `${base}#${i}`;
+    if (!set.has(candidate)) return candidate;
+  }
+}
+
+/**
+ * Redact sensitive values from a reconstructed `work` argv before logging, so
+ * supervisor logs never capture secrets. Both `--env NAME=VALUE` and the
+ * inline `--env=NAME=VALUE` form become `NAME=***` (the value passed to
+ * `nano work` is untouched). Pure.
+ */
+function redactWorkArgs(args) {
+  const out = [];
+  const list = Array.isArray(args) ? args : [];
+  const redactPair = (pair) => {
+    const eq = pair.indexOf('=');
+    return eq === -1 ? '***' : `${pair.slice(0, eq)}=***`;
+  };
+  for (let i = 0; i < list.length; i++) {
+    const tok = String(list[i]);
+    if (tok === '--env' && i + 1 < list.length) {
+      out.push(tok, redactPair(String(list[i + 1])));
+      i++;
+    } else if (tok.startsWith('--env=')) {
+      out.push(`--env=${redactPair(tok.slice('--env='.length))}`);
+    } else {
+      out.push(tok);
+    }
+  }
+  return out;
+}
+
+/** Capped exponential restart backoff for a crash-looping child (pure). */
+function supervisorBackoffMs(restarts, base = SUPERVISOR_BACKOFF_BASE_MS, max = SUPERVISOR_BACKOFF_MAX_MS) {
+  const n = Math.max(0, Number(restarts) || 0);
+  return Math.min(max, base * 2 ** Math.min(n, 20));
+}
+
+/** Newline-delimited JSON framing for the control socket (pure). */
+function encodeFrame(obj) {
+  return JSON.stringify(obj) + '\n';
+}
+
+/** Split a buffered string into complete JSON frames + a remainder (pure). */
+function decodeFrames(buffer) {
+  const frames = [];
+  let rest = String(buffer ?? '');
+  let idx;
+  while ((idx = rest.indexOf('\n')) >= 0) {
+    const line = rest.slice(0, idx).trim();
+    rest = rest.slice(idx + 1);
+    if (!line) continue;
+    try { frames.push(JSON.parse(line)); } catch { /* skip malformed frame */ }
+  }
+  return { frames, rest };
+}
+
+/** Humanise a millisecond duration compactly (pure). */
+function formatDuration(ms) {
+  const s = Math.floor((Number(ms) || 0) / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d${h % 24}h`;
+}
+
+/** Project a live/stored worker record to a status row (pure w.r.t. `now`). */
+function summarizeSupervisorWorker(w, now = Date.now()) {
+  const alive = isPidAlive(w.pid);
+  const uptimeMs = alive && w.startedAt ? Math.max(0, now - new Date(w.startedAt).getTime()) : 0;
+  return {
+    id: w.id,
+    profile: w.profile,
+    pid: alive ? w.pid : null,
+    state: w.stopping ? 'stopping' : alive ? 'running' : 'down',
+    restarts: Number(w.restarts) || 0,
+    uptimeMs,
+    lastExit: w.lastExit ?? null,
+    args: Array.isArray(w.args) ? w.args : [],
+  };
+}
+
+/** Render a supervisor status object as an aligned text table. */
+function formatSupervisorStatus(status) {
+  const lines = [];
+  const d = status.daemon || {};
+  const alive = d.pid ? isPidAlive(d.pid) : false;
+  lines.push('Supervisor:');
+  lines.push(`  daemon pid: ${d.pid ?? '-'} ${alive ? '(alive)' : '(dead — stale state)'}`);
+  if (d.startedAt) lines.push(`  started:    ${d.startedAt}`);
+  if (d.socket) lines.push(`  control:    ${d.socket}`);
+  const workers = Array.isArray(status.workers) ? status.workers : [];
+  lines.push('');
+  if (workers.length === 0) {
+    lines.push('  No workers. Add one with: c8ctl nano supervisor add <profile>');
+    return lines.join('\n');
+  }
+  const rows = workers.map((w) => ({
+    id: String(w.id),
+    profile: String(w.profile),
+    state: String(w.state),
+    pid: w.pid ? String(w.pid) : '-',
+    restarts: String(w.restarts),
+    uptime: w.state === 'running' ? formatDuration(w.uptimeMs) : '-',
+    last: w.lastExit ? String(w.lastExit) : '-',
+  }));
+  const head = { id: 'ID', profile: 'PROFILE', state: 'STATE', pid: 'PID', restarts: 'RESTARTS', uptime: 'UPTIME', last: 'LAST EXIT' };
+  const cols = ['id', 'profile', 'state', 'pid', 'restarts', 'uptime', 'last'];
+  const width = {};
+  for (const c of cols) width[c] = Math.max(head[c].length, ...rows.map((r) => r[c].length));
+  const fmt = (r) => '  ' + cols.map((c) => r[c].padEnd(width[c])).join('  ');
+  lines.push(fmt(head));
+  for (const r of rows) lines.push(fmt(r));
+  return lines.join('\n');
+}
+
+function readSupervisorState() {
+  const file = getSupervisorStateFile();
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSupervisorState(state) {
+  mkdirSync(getStateHome(), { recursive: true });
+  // Atomic + owner-only: write to a same-dir temp file (mode 0600) then rename
+  // over the target, so a concurrent reader never sees a torn file and the
+  // state (which records worker argv) isn't world-readable.
+  const target = getSupervisorStateFile();
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  try { renameSync(tmp, target); }
+  catch (err) { try { rmSync(tmp, { force: true }); } catch { /* best effort */ } throw err; }
+}
+
+function clearSupervisorState() {
+  const file = getSupervisorStateFile();
+  try { if (existsSync(file)) rmSync(file); } catch { /* best effort */ }
+}
+
+/** Running daemon state (pid alive) or null. */
+function runningSupervisor() {
+  const state = readSupervisorState();
+  return state && isPidAlive(state.pid) ? state : null;
+}
+
+/** Synthesize a state-file-shaped object from a live `status` response. */
+function stateFromStatus(res, socketPath) {
+  return {
+    pid: res.daemon?.pid,
+    startedAt: res.daemon?.startedAt,
+    socket: res.daemon?.socket || socketPath,
+    logFile: res.daemon?.logFile,
+    workers: res.workers || [],
+  };
+}
+
+/**
+ * Resolve a live supervisor, healing a missing/stale state file. Returns the
+ * running state (pid alive) if present; otherwise probes the deterministic
+ * control socket and, if a daemon answers, re-persists and returns its state so
+ * management commands still work when supervisor.json was deleted/cleaned.
+ * Returns null when nothing is listening.
+ */
+async function liveSupervisor() {
+  const running = runningSupervisor();
+  if (running) return running;
+  try {
+    const socketPath = getSupervisorSocketPath();
+    const res = await supervisorRequest({ op: 'status' }, { socketPath, timeoutMs: 500, responseTimeoutMs: SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS });
+    if (res && res.ok) {
+      const state = stateFromStatus(res, socketPath);
+      try { writeSupervisorState(state); } catch { /* best effort */ }
+      return state;
+    }
+  } catch { /* no live daemon on the socket */ }
+  return null;
+}
+
+/** How to re-invoke the c8ctl CLI to spawn the daemon + `work` children. */
+function c8ctlInvocation() {
+  const entry = process.env.C8CTL_NANO_ENTRY || process.argv[1];
+  return { exec: process.execPath, entry };
+}
+
+function supervisorDaemonLogFile() {
+  return join(getSupervisorLogDir(), 'daemon.log');
+}
+
+function supervisorWorkerLogFile(id) {
+  return join(getSupervisorLogDir(), `worker-${String(id).replace(/[^\w.#-]/g, '_')}.log`);
+}
+
+function waitForChildExit(child, timeoutMs) {
+  return new Promise((resolve) => {
+    if (!child || child.exitCode !== null || child.signalCode !== null) return resolve();
+    let done = false;
+    const finish = () => { if (done) return; done = true; clearTimeout(t); resolve(); };
+    const t = setTimeout(finish, timeoutMs);
+    child.once('exit', finish);
+  });
+}
+
+// --- Daemon ----------------------------------------------------------------
+
+/**
+ * The supervisor daemon body. Runs under `c8ctl nano supervisor __daemon`,
+ * spawned detached by `startSupervisorDaemon`. Never returns — it runs until a
+ * stop request or SIGTERM, then drains children and exits.
+ */
+async function runSupervisorDaemon() {
+  const startedAt = new Date().toISOString();
+  const { exec, entry } = c8ctlInvocation();
+  const socketPath = getSupervisorSocketPath();
+  const daemonLogFile = supervisorDaemonLogFile();
+  mkdirSync(getSupervisorLogDir(), { recursive: true });
+
+  const workers = new Map();
+  const attachClients = new Set();
+  let shuttingDown = false;
+
+  // Daemon-wide mutation serialization: `add`/`remove`/`restart` must not
+  // interleave, or two clients racing the same worker could each spawn an
+  // untracked child. Every mutation runs to completion before the next starts.
+  let opQueue = Promise.resolve();
+  const serializeOp = (fn) => {
+    const run = opQueue.then(fn, fn);
+    opQueue = run.then(() => {}, () => {});
+    return run;
+  };
+
+  const dlog = (msg) => {
+    try { appendFileSync(daemonLogFile, `[${new Date().toISOString()}] ${msg}\n`); } catch { /* best effort */ }
+  };
+
+  const workerPublic = (w) => summarizeSupervisorWorker(w);
+
+  const persist = () => {
+    try {
+      writeSupervisorState({
+        pid: process.pid,
+        startedAt,
+        socket: socketPath,
+        logFile: daemonLogFile,
+        workers: [...workers.values()].map((w) => ({
+          id: w.id, profile: w.profile, args: w.args, pid: isPidAlive(w.pid) ? w.pid : null,
+          startedAt: w.startedAt || null, restarts: w.restarts, lastExit: w.lastExit ?? null,
+          stopping: !!w.stopping, logFile: w.logFile,
+        })),
+      });
+    } catch { /* best effort */ }
+  };
+
+  const broadcast = (frame) => {
+    const data = encodeFrame(frame);
+    for (const sock of attachClients) {
+      try { sock.write(data); } catch { /* client gone */ }
+    }
+  };
+
+  const startWorker = (w) => {
+    let fd;
+    try { fd = openSync(w.logFile, 'a'); } catch { fd = 'ignore'; }
+    const child = spawn(exec, [entry, 'nano', 'work', w.profile, ...w.args], {
+      env: process.env,
+      stdio: ['ignore', fd, fd],
+    });
+    if (typeof fd === 'number') { try { closeSync(fd); } catch { /* dup'd into child */ } }
+    w.child = child;
+    w.pid = child.pid || null;
+    w.startedAt = new Date().toISOString();
+    w.spawnedAt = Date.now();
+    dlog(`worker '${w.id}' (profile ${w.profile}) started pid ${w.pid}: work ${[w.profile, ...redactWorkArgs(w.args)].join(' ')}`);
+    broadcast({ type: 'event', event: 'worker-start', worker: workerPublic(w) });
+
+    // A spawn failure (ENOENT/EMFILE/…) emits only 'error' with no 'exit', so
+    // both paths funnel through one death handler that schedules a restart.
+    // `settled` guards the error+exit double-fire; the `w.child !== child` check
+    // ignores a stale child's late exit after `restart` swapped in a new one
+    // (which would otherwise clobber the live pid and leak a duplicate worker).
+    let settled = false;
+    const handleDeath = (reason) => {
+      if (w.child !== child || settled) return;
+      settled = true;
+      w.pid = null;
+      w.lastExit = reason;
+      const ranMs = Date.now() - (w.spawnedAt || Date.now());
+      if (ranMs >= SUPERVISOR_HEALTHY_UPTIME_MS) w.restarts = 0;
+      if (w.stopping || shuttingDown || !workers.has(w.id)) { persist(); return; }
+      const delay = supervisorBackoffMs(w.restarts);
+      w.restarts += 1;
+      dlog(`worker '${w.id}' down (${reason}); restarting in ${delay}ms (restart #${w.restarts})`);
+      broadcast({ type: 'event', event: 'worker-exit', worker: workerPublic(w), restartInMs: delay });
+      w.restartTimer = setTimeout(() => {
+        w.restartTimer = null;
+        if (!w.stopping && !shuttingDown && workers.has(w.id)) startWorker(w);
+      }, delay);
+      if (typeof w.restartTimer.unref === 'function') w.restartTimer.unref();
+      persist();
+    };
+    child.on('error', (err) => handleDeath(`spawn error: ${err.message}`));
+    child.on('exit', (code, signal) => handleDeath(signal ? `signal ${signal}` : `code ${code}`));
+    persist();
+  };
+
+  const addWorker = (profile, args) => {
+    const id = supervisorWorkerId(profile, new Set(workers.keys()));
+    const w = {
+      id, profile: String(profile), args: Array.isArray(args) ? args.map(String) : [],
+      restarts: 0, stopping: false, lastExit: null, logFile: supervisorWorkerLogFile(id),
+    };
+    workers.set(id, w);
+    startWorker(w);
+    return w;
+  };
+
+  const stopWorker = async (id) => {
+    const w = workers.get(id);
+    if (!w) return false;
+    w.stopping = true;
+    if (w.restartTimer) { clearTimeout(w.restartTimer); w.restartTimer = null; }
+    const pid = w.pid;
+    if (w.child && pid) {
+      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+      await waitForChildExit(w.child, STOP_GRACE_MS);
+      if (isPidAlive(pid)) { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
+    }
+    return true;
+  };
+
+  const removeWorker = async (id) => {
+    if (!workers.has(id)) return false;
+    await stopWorker(id);
+    workers.delete(id);
+    dlog(`worker '${id}' removed`);
+    broadcast({ type: 'event', event: 'worker-remove', id });
+    persist();
+    return true;
+  };
+
+  const restartWorker = async (id) => {
+    const w = workers.get(id);
+    if (!w) return false;
+    await stopWorker(id);
+    w.stopping = false;
+    w.restarts = 0;
+    startWorker(w);
+    dlog(`worker '${id}' restarted`);
+    return true;
+  };
+
+  // Resolve a target token to worker ids: exact id, else all with that profile.
+  const resolveTargets = (target) => {
+    const t = String(target || '').trim();
+    if (!t) return [];
+    if (t === 'all' || t === '*') return [...workers.keys()];
+    if (workers.has(t)) return [t];
+    return [...workers.values()].filter((w) => w.profile === t).map((w) => w.id);
+  };
+
+  const statusFrame = (final) => ({
+    ok: true,
+    type: 'status',
+    daemon: { pid: process.pid, startedAt, socket: socketPath, logFile: daemonLogFile },
+    workers: [...workers.values()].map(workerPublic),
+    ...(final ? { final: true } : {}),
+  });
+
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    // Let any in-flight mutation finish before we snapshot the worker set, so
+    // an add/restart racing the shutdown can't leave an orphaned child behind.
+    try { await opQueue; } catch { /* mutation already logged */ }
+    dlog(`received ${signal || 'stop'} — stopping ${workers.size} worker(s)`);
+    await Promise.all([...workers.keys()].map((id) => stopWorker(id)));
+    broadcast({ type: 'event', event: 'daemon-stop' });
+    try { server.close(); } catch { /* ignore */ }
+    if (osPlatform() !== 'win32') { try { rmSync(socketPath, { force: true }); } catch { /* ignore */ } }
+    clearSupervisorState();
+    process.exit(0);
+  };
+
+  const handleRequest = async (req, sock) => {
+    const op = req && req.op;
+    try {
+      switch (op) {
+        case 'status':
+          sock.write(encodeFrame(statusFrame(true)));
+          break;
+        case 'add': {
+          if (shuttingDown) { sock.write(encodeFrame({ ok: false, error: 'supervisor is shutting down', final: true })); break; }
+          if (!req.profile) { sock.write(encodeFrame({ ok: false, error: 'add requires a profile', final: true })); break; }
+          // `--name` selects a DIFFERENT hire inside `nano work`, so a worker
+          // added as profile X but carrying `--name Y` would run Y while status
+          // and logs report X. Reject it — the supervisor id derives from the
+          // positional profile and that must be what actually runs.
+          // `req.args` comes from untrusted JSON and may be non-array (e.g. a
+          // string or object). Coerce to an array of string tokens before
+          // scanning/forwarding so a malformed payload yields a clean rejection
+          // instead of throwing a generic request error.
+          const args = Array.isArray(req.args) ? req.args.filter((a) => typeof a === 'string') : [];
+          const badName = args.find((a) => a === '--name' || a === '-n' || /^--name=/.test(a) || /^-n=/.test(a));
+          if (badName) { sock.write(encodeFrame({ ok: false, error: `--name is not allowed for a supervised worker (it would run a different hire than the reported profile "${req.profile}")`, final: true })); break; }
+          const stored = readHires()[String(req.profile)];
+          if (!stored) { sock.write(encodeFrame({ ok: false, error: `no hire named "${req.profile}"`, final: true })); break; }
+          const w = await serializeOp(() => addWorker(req.profile, args));
+          sock.write(encodeFrame({ ok: true, type: 'added', worker: workerPublic(w), final: true }));
+          break;
+        }
+        case 'remove': {
+          if (shuttingDown) { sock.write(encodeFrame({ ok: false, error: 'supervisor is shutting down', final: true })); break; }
+          const removed = await serializeOp(async () => {
+            const ids = resolveTargets(req.target);
+            for (const id of ids) await removeWorker(id);
+            return ids;
+          });
+          sock.write(encodeFrame({ ok: true, type: 'removed', removed, final: true }));
+          break;
+        }
+        case 'restart': {
+          if (shuttingDown) { sock.write(encodeFrame({ ok: false, error: 'supervisor is shutting down', final: true })); break; }
+          const restarted = await serializeOp(async () => {
+            const ids = resolveTargets(req.target);
+            for (const id of ids) await restartWorker(id);
+            return ids;
+          });
+          sock.write(encodeFrame({ ok: true, type: 'restarted', restarted, final: true }));
+          break;
+        }
+        case 'attach':
+          attachClients.add(sock);
+          sock.write(encodeFrame(statusFrame(false)));
+          break;
+        case 'stop':
+          sock.write(encodeFrame({ ok: true, type: 'stopping', final: true }));
+          setTimeout(() => shutdown('stop'), 50);
+          break;
+        default:
+          sock.write(encodeFrame({ ok: false, error: `unknown op "${op}"`, final: true }));
+      }
+    } catch (err) {
+      try { sock.write(encodeFrame({ ok: false, error: String(err && err.message || err), final: true })); } catch { /* ignore */ }
+    }
+  };
+
+  // Bind the control socket. A stale unix socket file from a crashed daemon
+  // would make listen() fail with EADDRINUSE even though nobody is listening;
+  // remove it first (we already know no live daemon owns our state).
+  if (osPlatform() !== 'win32') { try { rmSync(socketPath, { force: true }); } catch { /* ignore */ } }
+
+  const server = createServer((sock) => {
+    sock.setEncoding('utf8');
+    let buf = '';
+    // Serialize requests per connection: handleRequest is async and mutates the
+    // shared workers map, so a second 'data' event arriving mid-await must not
+    // interleave add/remove/restart. Chain each frame onto a per-socket queue.
+    let queue = Promise.resolve();
+    sock.on('data', (chunk) => {
+      buf += chunk;
+      // Cap by UTF-8 byte length, not string length: buf is a decoded string
+      // whose .length counts UTF-16 code units, so multibyte input could hold
+      // far more than SUPERVISOR_MAX_FRAME_BYTES in memory before being dropped.
+      if (Buffer.byteLength(buf, 'utf8') > SUPERVISOR_MAX_FRAME_BYTES) {
+        dlog(`control connection exceeded ${SUPERVISOR_MAX_FRAME_BYTES} bytes without a complete frame — dropping`);
+        try { sock.destroy(); } catch { /* ignore */ }
+        buf = '';
+        return;
+      }
+      const { frames, rest } = decodeFrames(buf);
+      buf = rest;
+      for (const req of frames) {
+        queue = queue.then(() => handleRequest(req, sock)).catch((err) => dlog(`request error: ${err?.message || err}`));
+      }
+    });
+    sock.on('close', () => attachClients.delete(sock));
+    sock.on('error', () => attachClients.delete(sock));
+  });
+
+  // Create the control socket owner-only from the start. The socket file lives
+  // in shared tmpdir(); libuv binds it synchronously inside listen(), so a
+  // restrictive umask around that call closes the TOCTOU window where another
+  // local user could connect before the chmod below lands. Restore the previous
+  // umask immediately after — the listen() bind is synchronous, so no unrelated
+  // file creation can interleave. Unix only; on Windows umask/mode are no-ops.
+  const isWin = osPlatform() === 'win32';
+  const prevUmask = isWin ? null : process.umask(0o177);
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(socketPath, resolve);
+    });
+  } catch (err) {
+    dlog(`failed to bind control socket ${socketPath}: ${err.message}`);
+    process.exit(1);
+  } finally {
+    if (!isWin) { try { process.umask(prevUmask); } catch { /* ignore */ } }
+  }
+
+  // Lock the control socket to the owner so another local user can't drive the
+  // supervisor (stop/add/remove). Unix only — Windows named pipes are secured
+  // by their own ACLs, not filesystem mode bits. This chmod is now a backstop
+  // for the owner-only umask applied around listen() above.
+  if (!isWin) {
+    try { chmodSync(socketPath, 0o600); } catch (err) { dlog(`could not chmod control socket: ${err.message}`); }
+  }
+
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  dlog(`supervisor daemon up (pid ${process.pid}) — control ${socketPath}`);
+  persist();
+
+  // Keep the event loop alive indefinitely; the server holds it, but add an
+  // explicit never-resolving guard so a transient server close can't exit us.
+  await new Promise(() => {});
+}
+
+// --- Client (management subcommands + attach) ------------------------------
+
+/** Connect to the control socket, resolving with the socket once connected. */
+function supervisorConnect(socketPath, { timeoutMs = SUPERVISOR_CONNECT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    const sock = createConnection(socketPath);
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      sock.destroy();
+      reject(new Error(`timed out connecting to supervisor at ${socketPath}`));
+    }, timeoutMs);
+    sock.once('connect', () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.setEncoding('utf8');
+      resolve(sock);
+    });
+    sock.once('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+/** Send one request and collect frames until a `final:true` frame arrives. */
+function supervisorRequest(req, { socketPath, timeoutMs, responseTimeoutMs = SUPERVISOR_RESPONSE_TIMEOUT_MS } = {}) {
+  const path = socketPath || (readSupervisorState()?.socket) || getSupervisorSocketPath();
+  return new Promise((resolve, reject) => {
+    supervisorConnect(path, { timeoutMs }).then((sock) => {
+      let buf = '';
+      let settled = false;
+      const finish = (fn, arg) => { if (settled) return; settled = true; clearTimeout(timer); try { sock.end(); } catch { /* ignore */ } fn(arg); };
+      const done = (result) => finish(resolve, result);
+      const fail = (err) => finish(reject, err);
+      // End-to-end response deadline: a daemon that accepts the connection but
+      // never sends a `final` frame must not hang the caller forever.
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        try { sock.destroy(); } catch { /* ignore */ }
+        reject(new Error(`timed out waiting for supervisor response from ${path}`));
+      }, responseTimeoutMs);
+      sock.on('data', (chunk) => {
+        buf += chunk;
+        const { frames, rest } = decodeFrames(buf);
+        buf = rest;
+        for (const frame of frames) {
+          if (frame.final) return done(frame);
+        }
+      });
+      sock.on('error', fail);
+      sock.on('close', () => done({ ok: false, error: 'connection closed before response' }));
+      sock.write(encodeFrame(req));
+    }).catch(reject);
+  });
+}
+
+/**
+ * Ensure a daemon is running, spawning it detached if not, and return its
+ * running state. Polls the control socket until it answers a status request.
+ */
+async function startSupervisorDaemon() {
+  const existing = runningSupervisor();
+  if (existing) return existing;
+
+  const socketPath = getSupervisorSocketPath();
+  // The state file may be missing (deleted, cleaned up, or not yet written)
+  // while a daemon is still listening on the deterministic socket. Adopt that
+  // live daemon instead of spawning a second one that would orphan the
+  // original and its workers.
+  try {
+    const res = await supervisorRequest({ op: 'status' }, { socketPath, timeoutMs: 500, responseTimeoutMs: SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS });
+    if (res && res.ok) {
+      // Re-persist the adopted daemon's state so subsequent pid-based checks
+      // (runningSupervisor()) work immediately, instead of staying broken until
+      // some later command happens to heal supervisor.json.
+      const adopted = runningSupervisor() || stateFromStatus(res, socketPath);
+      try { writeSupervisorState(adopted); } catch { /* best effort */ }
+      return adopted;
+    }
+  } catch { /* no live daemon on the socket — safe to (re)spawn */ }
+
+  clearSupervisorState(); // clear any stale marker from a dead daemon
+
+  const { exec, entry } = c8ctlInvocation();
+  mkdirSync(getSupervisorLogDir(), { recursive: true });
+  const logFile = supervisorDaemonLogFile();
+  let fd;
+  try { fd = openSync(logFile, 'a'); } catch { fd = 'ignore'; }
+  const child = spawn(exec, [entry, 'nano', 'supervisor', '__daemon'], {
+    env: process.env,
+    detached: true,
+    stdio: ['ignore', fd, fd],
+  });
+  child.unref();
+  if (typeof fd === 'number') { try { closeSync(fd); } catch { /* ignore */ } }
+  if (typeof child.pid !== 'number') throw new Error('failed to spawn supervisor daemon');
+
+
+  const deadline = Date.now() + SUPERVISOR_CONNECT_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const res = await supervisorRequest({ op: 'status' }, { socketPath, timeoutMs: 750, responseTimeoutMs: SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS });
+      if (res && res.ok) {
+        // The daemon can answer `status` on the socket a beat before it has
+        // written supervisor.json. Fall back to the live status response so
+        // callers always get a state object with a usable pid.
+        return runningSupervisor() || readSupervisorState() || stateFromStatus(res, socketPath);
+      }
+    } catch { /* not up yet */ }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error(`supervisor daemon did not become ready (see ${logFile})`);
+}
+
+async function supervisorStartCmd(req, flags) {
+  const logger = getLogger();
+  const state = await startSupervisorDaemon();
+  logger.info(`Supervisor daemon running (pid ${state.pid}).`);
+
+  const specs = normalizeArgList(flags?.worker);
+  const workArgs = reconstructWorkArgs(flags);
+  for (const profile of specs) {
+    const res = await supervisorRequest({ op: 'add', profile, args: workArgs });
+    if (res.ok) logger.info(`  + worker "${res.worker.id}" (profile ${profile})`);
+    else logger.error(`  ! could not add "${profile}": ${res.error}`);
+  }
+
+  if (coerceBool(flags?.attach, false)) {
+    await attachSupervisorConsole(runningSupervisor() || state);
+    return;
+  }
+  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');
+}
+
+async function supervisorStatusCmd() {
+  const logger = getLogger();
+  const running = runningSupervisor();
+  if (!running) {
+    // The state file may be missing (deleted/cleaned) while a daemon is still
+    // listening on the deterministic socket — same case startSupervisorDaemon
+    // adopts. Probe it before declaring the supervisor down, and re-persist so
+    // the state file is healed for later pid-based checks.
+    try {
+      const res = await supervisorRequest({ op: 'status' }, { socketPath: getSupervisorSocketPath(), timeoutMs: 500, responseTimeoutMs: SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS });
+      if (res && res.ok) {
+        try { writeSupervisorState(stateFromStatus(res, getSupervisorSocketPath())); } catch { /* best effort */ }
+        logger.info(formatSupervisorStatus(res));
+        return;
+      }
+    } catch { /* no live daemon on the socket — genuinely down */ }
+    const stale = readSupervisorState();
+    if (stale) {
+      logger.info('Supervisor: not running (stale state — daemon pid is dead).');
+      logger.info('  Start it with: c8ctl nano supervisor start');
+    } else {
+      logger.info('Supervisor: not running.');
+      logger.info('  Start it with: c8ctl nano supervisor start   (or attach: c8ctl nano supervisor)');
+    }
+    return;
+  }
+  try {
+    const res = await supervisorRequest({ op: 'status' });
+    if (res.ok) { logger.info(formatSupervisorStatus(res)); return; }
+  } catch { /* fall back to state file below */ }
+  // Socket unreachable but pid alive — render from the last persisted state.
+  logger.info(formatSupervisorStatus({
+    daemon: { pid: running.pid, startedAt: running.startedAt, socket: running.socket },
+    workers: (running.workers || []).map((w) => summarizeSupervisorWorker(w)),
+  }));
+}
+
+async function supervisorAddCmd(req, flags) {
+  const logger = getLogger();
+  // Use only the positional profile. `--name` is a documented hire/work/assign
+  // flag, so honouring it here would make `supervisor add reviewer --name foo`
+  // surprisingly add `foo` instead of `reviewer`.
+  const profile = req.positional[1];
+  if (!profile) { logger.error('Usage: c8ctl nano supervisor add <profile> [work flags]'); process.exit(1); }
+  await startSupervisorDaemon();
+  const res = await supervisorRequest({ op: 'add', profile, args: reconstructWorkArgs(flags) });
+  if (res.ok) logger.info(`Added worker "${res.worker.id}" (profile ${profile}); pid ${res.worker.pid ?? 'starting'}.`);
+  else { logger.error(`Could not add "${profile}": ${res.error}`); process.exit(1); }
+}
+
+async function supervisorRemoveCmd(req) {
+  const logger = getLogger();
+  const target = req.positional[1];
+  if (!target) { logger.error('Usage: c8ctl nano supervisor remove <id|profile|all>'); process.exit(1); }
+  if (!await liveSupervisor()) { logger.error('Supervisor is not running.'); process.exit(1); }
+  const res = await supervisorRequest({ op: 'remove', target });
+  if (res.ok && res.removed.length > 0) logger.info(`Removed worker(s): ${res.removed.join(', ')}.`);
+  else if (res.ok) { logger.warn(`No worker matched "${target}".`); }
+  else { logger.error(res.error); process.exit(1); }
+}
+
+async function supervisorRestartCmd(req) {
+  const logger = getLogger();
+  const target = req.positional[1];
+  if (!target) { logger.error('Usage: c8ctl nano supervisor restart <id|profile|all>'); process.exit(1); }
+  if (!await liveSupervisor()) { logger.error('Supervisor is not running.'); process.exit(1); }
+  const res = await supervisorRequest({ op: 'restart', target });
+  if (res.ok && res.restarted.length > 0) logger.info(`Restarted worker(s): ${res.restarted.join(', ')}.`);
+  else if (res.ok) { logger.warn(`No worker matched "${target}".`); }
+  else { logger.error(res.error); process.exit(1); }
+}
+
+async function supervisorStopCmd() {
+  const logger = getLogger();
+  const running = await liveSupervisor();
+  if (!running) {
+    if (readSupervisorState()) { clearSupervisorState(); logger.info('Cleared stale supervisor state.'); }
+    else logger.warn('Supervisor is not running — nothing to stop.');
+    return;
+  }
+  try {
+    await supervisorRequest({ op: 'stop' });
+  } catch {
+    // Socket unreachable — fall back to signalling the daemon pid directly.
+    try { process.kill(running.pid, 'SIGTERM'); } catch { /* already gone */ }
+  }
+  // Gate the wait loop and the SIGKILL fallback on the daemon pid we captured,
+  // not on runningSupervisor()/the state file: the daemon clears its state file
+  // as part of shutting down (and liveSupervisor()/external cleanup can remove
+  // it too), so a state-file check can report "gone" while the process is still
+  // alive — which would break the loop early and skip the SIGKILL fallback,
+  // leaving a wedged daemon and its worker process group running.
+  const deadline = Date.now() + STOP_GRACE_MS + 2_000;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(running.pid)) break;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  if (isPidAlive(running.pid)) {
+    logger.warn(`Supervisor (pid ${running.pid}) did not stop gracefully — sending SIGKILL.`);
+    // The daemon is spawned detached (a process-group leader) and its workers
+    // are children in that group, so SIGKILL the whole group to avoid orphaning
+    // `nano work` processes. Fall back to the bare pid (e.g. on Windows, or if
+    // the daemon isn't a group leader).
+    let killedGroup = false;
+    if (osPlatform() !== 'win32') {
+      try { process.kill(-running.pid, 'SIGKILL'); killedGroup = true; } catch { /* fall back below */ }
+    }
+    if (!killedGroup) { try { process.kill(running.pid, 'SIGKILL'); } catch { /* ignore */ } }
+    clearSupervisorState();
+  }
+  logger.info('Supervisor stopped.');
+}
+
+function supervisorLogsCmd(req) {
+  const logger = getLogger();
+  const id = req.positional[1];
+  const file = id ? supervisorWorkerLogFile(id) : supervisorDaemonLogFile();
+  if (!existsSync(file)) {
+    logger.error(`No log file at ${file}.${id ? ` (unknown worker "${id}"?)` : ''}`);
+    process.exit(1);
+  }
+  const follow = Boolean(req.follow);
+  const tailArgs = follow ? ['-n', '200', '-F', file] : ['-n', '200', file];
+  const proc = spawn('tail', tailArgs, { stdio: ['ignore', 'inherit', 'inherit'] });
+  proc.on('error', () => {
+    // tail unavailable (e.g. Windows): print the tail ourselves, no follow.
+    if (follow) logger.warn('`--follow` is not supported without `tail` on this platform; printing the current tail only.');
+    try {
+      const lines = readFileSync(file, 'utf-8').split('\n');
+      logger.info(lines.slice(-200).join('\n'));
+    } catch (err) { logger.error(`Could not read ${file}: ${err.message}`); }
+  });
+}
+
+/**
+ * Interactive attach console. Streams live events from the daemon and accepts
+ * line commands. `detach` (or Ctrl-D) disconnects but leaves the daemon
+ * running; `stop` tears the fleet down.
+ */
+async function attachSupervisorConsole(state) {
+  const logger = getLogger();
+  const socketPath = state?.socket || getSupervisorSocketPath();
+  let sock;
+  try {
+    sock = await supervisorConnect(socketPath);
+  } catch (err) {
+    logger.error(`Could not attach to supervisor: ${err.message}`);
+    process.exit(1);
+  }
+
+  const out = (s) => process.stdout.write(s + '\n');
+  out('Attached to nano worker supervisor. Type "help" for commands.');
+  out('Detach (leave it running) with "detach" or Ctrl-D; tear it down with "stop".');
+  sock.write(encodeFrame({ op: 'attach' }));
+
+  let buf = '';
+  sock.on('data', (chunk) => {
+    buf += chunk;
+    const { frames, rest } = decodeFrames(buf);
+    buf = rest;
+    for (const frame of frames) {
+      if (frame.type === 'status') {
+        out('');
+        out(formatSupervisorStatus(frame));
+      } else if (frame.type === 'event') {
+        const w = frame.worker;
+        if (frame.event === 'worker-start') out(`• worker ${w.id} started (pid ${w.pid}).`);
+        else if (frame.event === 'worker-exit') out(`• worker ${w.id} exited (${w.lastExit}); restarting in ${formatDuration(frame.restartInMs)}.`);
+        else if (frame.event === 'worker-remove') out(`• worker ${frame.id} removed.`);
+        else if (frame.event === 'daemon-stop') out('• supervisor stopping.');
+      } else if (frame.type === 'added') {
+        out(`• added worker ${frame.worker.id}.`);
+      } else if (frame.type === 'removed') {
+        out(`• removed: ${frame.removed.join(', ') || '(none matched)'}.`);
+      } else if (frame.type === 'restarted') {
+        out(`• restarted: ${frame.restarted.join(', ') || '(none matched)'}.`);
+      } else if (frame.ok === false) {
+        out(`! ${frame.error}`);
+      }
+    }
+  });
+
+  const rl = createReadline({ input: process.stdin, output: process.stdout, prompt: 'supervisor> ' });
+  rl.prompt();
+
+  await new Promise((resolve) => {
+    let stopping = false;
+    const finish = () => { try { rl.close(); } catch { /* ignore */ } try { sock.end(); } catch { /* ignore */ } resolve(); };
+
+    sock.on('close', () => { if (!stopping) out('\nSupervisor connection closed.'); finish(); });
+
+    rl.on('line', (line) => {
+      const parts = String(line).trim().split(/\s+/).filter(Boolean);
+      const cmd = (parts.shift() || '').toLowerCase();
+      switch (cmd) {
+        case '': break;
+        case 'help':
+          out('Commands: status | add <profile> [work flags] | remove <id|profile|all> |');
+          out('          restart <id|profile|all> | logs [id] | detach | stop | help');
+          break;
+        case 'status': sock.write(encodeFrame({ op: 'status' })); break;
+        case 'add': {
+          const profile = parts.shift();
+          if (!profile) { out('usage: add <profile> [work flags]'); break; }
+          sock.write(encodeFrame({ op: 'add', profile, args: parts }));
+          break;
+        }
+        case 'remove': case 'rm': {
+          const target = parts.shift();
+          if (!target) { out('usage: remove <id|profile|all>'); break; }
+          sock.write(encodeFrame({ op: 'remove', target }));
+          break;
+        }
+        case 'restart': {
+          const target = parts.shift();
+          if (!target) { out('usage: restart <id|profile|all>'); break; }
+          sock.write(encodeFrame({ op: 'restart', target }));
+          break;
+        }
+        case 'logs': case 'log': {
+          const file = parts[0] ? supervisorWorkerLogFile(parts[0]) : supervisorDaemonLogFile();
+          try {
+            const lines = readFileSync(file, 'utf-8').split('\n');
+            out(lines.slice(-30).join('\n'));
+          } catch { out(`no log at ${file}`); }
+          break;
+        }
+        case 'detach': case 'quit': case 'exit':
+          out('Detaching — supervisor keeps running. Reattach with: c8ctl nano supervisor');
+          finish();
+          return;
+        case 'stop':
+          stopping = true;
+          out('Stopping supervisor…');
+          sock.write(encodeFrame({ op: 'stop' }));
+          setTimeout(finish, 500);
+          return;
+        default:
+          out(`unknown command "${cmd}" — type "help"`);
+      }
+      rl.prompt();
+    });
+
+    // Ctrl-D (EOF) detaches, leaving the daemon running.
+    rl.on('close', () => {
+      if (stopping) return;
+      out('\nDetaching — supervisor keeps running. Reattach with: c8ctl nano supervisor');
+      finish();
+    });
+  });
+}
+
+/** Dispatch the `supervisor` subcommand's action. */
+async function supervisorCommand(req, flags) {
+  const action = (req.positional[0] || '').toLowerCase();
+  switch (action) {
+    case '__daemon':
+      await runSupervisorDaemon();
+      return;
+    case '':
+    case 'attach': {
+      const state = await startSupervisorDaemon();
+      await attachSupervisorConsole(runningSupervisor() || state);
+      return;
+    }
+    case 'start':
+      await supervisorStartCmd(req, flags);
+      return;
+    case 'status':
+    case 'list':
+    case 'ls':
+      await supervisorStatusCmd();
+      return;
+    case 'add':
+      await supervisorAddCmd(req, flags);
+      return;
+    case 'remove':
+    case 'rm':
+      await supervisorRemoveCmd(req);
+      return;
+    case 'restart':
+      await supervisorRestartCmd(req);
+      return;
+    case 'stop':
+      await supervisorStopCmd();
+      return;
+    case 'logs':
+    case 'log':
+      supervisorLogsCmd(req);
+      return;
+    default:
+      getLogger().error(`Unknown supervisor action "${action}". Use: start|status|add|remove|restart|stop|logs|attach`);
+      process.exit(1);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // update — pull a new nanobpmn release onto a machine with an existing install.
 // The plugin (and the bundled server binary, shipped via the matching platform
@@ -4547,6 +5811,7 @@ export {
   applyAssign,
   resolveAssignInputs,
   jobTypeMatrix,
+  diffJobTypes,
   parseJobTypeFlags,
   deriveJobLockMs,
   derivePollTimeoutMs,
@@ -4556,6 +5821,26 @@ export {
   RESERVED_RESULT_KEYS,
   SANDBOXES,
 };
+export {
+  reconstructWorkArgs,
+  supervisorWorkerId,
+  redactWorkArgs,
+  supervisorBackoffMs,
+  encodeFrame,
+  decodeFrames,
+  formatDuration,
+  summarizeSupervisorWorker,
+  formatSupervisorStatus,
+  WORK_FORWARD_FLAGS,
+  runSupervisorDaemon,
+  startSupervisorDaemon,
+  supervisorRequest,
+  runningSupervisor,
+  readSupervisorState,
+  clearSupervisorState,
+  getSupervisorSocketPath,
+  getSupervisorStateFile,
+};
 
 export const metadata = {
   name: 'c8ctl-plugin-nano',
@@ -4595,6 +5880,12 @@ export const metadata = {
         { command: 'c8ctl nano hire --name coder --rank senior --command "agent-harness" --sandbox docker --image ghcr.io/acme/agent:1', description: 'Create a profile that runs each job in a throwaway Docker container' },
         { command: 'c8ctl nano work reviewer', description: 'Spawn Nano job workers for the "reviewer" profile and poll for work' },
         { command: 'c8ctl nano work coder --sandbox docker --image ghcr.io/acme/agent:1', description: 'Run jobs in isolated containers with disk-hygiene reaping' },
+        { command: 'c8ctl nano supervisor start --worker reviewer --worker coder', description: 'Start a detached supervisor managing several workers from one terminal' },
+        { command: 'c8ctl nano supervisor', description: 'Attach an interactive console to the supervisor (detach with Ctrl-D, leaving it running)' },
+        { command: 'c8ctl nano supervisor status', description: 'List supervised workers (pid, state, restarts, uptime) without the console' },
+        { command: 'c8ctl nano supervisor add decider --max-parallel 2', description: 'Add a supervised worker (forwarding work flags) to the running supervisor' },
+        { command: 'c8ctl nano supervisor restart reviewer', description: 'Restart a supervised worker by id or profile' },
+        { command: 'c8ctl nano supervisor stop', description: 'Stop the supervisor daemon and all its workers' },
       ],
     },
     processos: {
@@ -4657,6 +5948,8 @@ export const commands = {
       'lock-grace': { type: 'string', description: 'work: extra ms added to --job-timeout to derive the broker activation lock, so the worker reports before the lock lapses (default 120000)' },
       'poll-timeout': { type: 'string', description: 'work: broker long-poll window in ms each activateJobs request is held open (fewer reconnects → fewer transient connect errors); default 30000, 0 = broker default, negative = return immediately' },
       'job-type': { type: 'string', multiple: true, description: 'work: extra job type to service alongside the rank×capability matrix (repeatable)' },
+      worker: { type: 'string', multiple: true, description: 'supervisor start: profile to launch as a supervised worker (repeatable)' },
+      attach: { type: 'boolean', description: 'supervisor start: attach the interactive console after starting the daemon' },
     },
     handler: async (args, flags) => {
       const logger = getLogger();
@@ -4714,6 +6007,9 @@ export const commands = {
           case 'work':
             await workAgent(req, flags);
             break;
+          case 'supervisor':
+            await supervisorCommand(req, flags);
+            break;
         }
       } catch (error) {
         logger.error(`nano ${req.subcommand} failed: ${error instanceof Error ? error.message : error}`);
@@ -4805,6 +6101,7 @@ 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>] [--env NAME=VALUE ...] [--list]');
   console.log('  c8ctl nano assign <profileName> [<capability> ...] [--name <n>] [--capabilities <a,b>]');
   console.log('  c8ctl nano work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--job-timeout <ms>] [--lock-grace <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|status|add|remove|restart|stop|logs|attach] ... (manage many workers from one terminal)');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -4821,6 +6118,7 @@ function printUsage() {
   console.log('  hire     Create a CLI agent worker profile (rank + capabilities → job-type matrix)');
   console.log('  assign   Grant new capabilities (roles) to an existing hire (additive)');
   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('');
   console.log('Options:');
   console.log('  <nodes>              Number of nodes to start (default 1)');