@yemi33/minions 0.1.2092 → 0.1.2094

package/bin/minions.js

@@ -246,6 +246,69 @@ function spawnDashboard() {
   return proc;
 }
 
+/** Spawn the external supervisor (engine/supervisor.js). The supervisor
+ *  watches BOTH the engine and the dashboard and respawns whichever dies,
+ *  unless `engine/stop-intent.json` is present (set by `minions stop`).
+ *  Single-instance guard inside supervisor.js means double-spawn during
+ *  rapid restart is harmless — the second invocation exits cleanly when it
+ *  sees a live PID in supervisor.pid. */
+function spawnSupervisor() {
+  const out = _openStdioLog('supervisor-stdio.log');
+  const err = _openStdioLog('supervisor-stdio.log');
+  const proc = spawn(process.execPath, [path.join(MINIONS_HOME, 'engine', 'supervisor.js')], {
+    cwd: MINIONS_HOME, stdio: ['ignore', out, err], detached: true, windowsHide: true,
+  });
+  proc.unref();
+  return proc;
+}
+
+// Path getter — evaluated lazily inside the helper so MINIONS_HOME, which
+// is initialized later in module load, is bound at call time rather than
+// at function-definition time.
+const _supervisorPidPath = () => path.join(MINIONS_HOME, 'engine', 'supervisor.pid');
+
+/** Clear the stop-intent flag so the supervisor resumes guarding the engine
+ *  and dashboard. Called at the top of every start/restart path.
+ *  Delegates to engine/shared.js when available so engine.js, dashboard.js,
+ *  and the CLI all share one source of truth. Falls back to a direct unlink
+ *  during early init when shared.js may not have loaded yet. */
+function clearStopIntent() {
+  try { shared.clearStopIntent(); }
+  catch {
+    try { fs.unlinkSync(path.join(MINIONS_HOME, 'engine', 'stop-intent.json')); } catch {}
+  }
+}
+
+/** Write the stop-intent flag so the supervisor stands down instead of
+ *  respawning the engine/dashboard we're about to kill. Called at the top of
+ *  every stop/uninstall path. */
+function writeStopIntent(source) {
+  try { shared.writeStopIntent(source || 'minions cli'); }
+  catch {
+    try {
+      fs.writeFileSync(path.join(MINIONS_HOME, 'engine', 'stop-intent.json'), JSON.stringify({
+        stoppedAt: new Date().toISOString(),
+        source: source || 'minions cli',
+      }, null, 2));
+    } catch { /* best effort */ }
+  }
+}
+
+/** Kill the supervisor process if its PID file points at a live process.
+ *  Used by `minions stop` and `minions restart` after writing stop-intent. */
+function killSupervisor() {
+  try {
+    const pid = Number(fs.readFileSync(_supervisorPidPath(), 'utf8').trim());
+    if (!pid || pid === process.pid) return;
+    if (process.platform === 'win32') {
+      try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', timeout: 5000, windowsHide: true }); } catch {}
+    } else {
+      try { process.kill(pid, 'SIGTERM'); } catch {}
+    }
+    try { fs.unlinkSync(_supervisorPidPath()); } catch {}
+  } catch { /* no PID file — supervisor not running */ }
+}
+
 const LEGACY_DEFAULT_SQUAD_HOME = path.join(os.homedir(), '.squad');
 const LEGACY_ROOT_POINTER_PATH = path.join(os.homedir(), '.squad-root');
 
@@ -504,6 +567,10 @@ function init() {
   const dashWasUp = isPortListening(DASH_PORT);
   const restartStartMs = Date.now();
   if (isUpgrade) {
+    // Pre-write stop-intent so the supervisor doesn't race-respawn the
+    // engine/dashboard we're about to kill for upgrade.
+    writeStopIntent('minions upgrade');
+    killSupervisor();
     try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME, timeout: 10000, windowsHide: true }); } catch {}
     // Free the dashboard port too — without this the new dashboard EADDRINUSE-dies
     // silently and the user keeps running stale code from the old dashboard process.
@@ -511,6 +578,9 @@ function init() {
     // Clear AFTER kill so the old dashboard can't repopulate during shutdown.
     _clearDashboardBrowserState(MINIONS_HOME);
   }
+  // Clear stop-intent so the supervisor we're about to spawn (and any
+  // already-running one whose PID file survived) resumes guarding.
+  clearStopIntent();
   console.log(isUpgrade
     ? `\n  Upgrade complete (${pkgVersion}). Restarting engine and dashboard...\n`
     : '\n  Starting engine and dashboard...\n');
@@ -524,6 +594,9 @@ function init() {
   console.log(`  Dashboard started (PID: ${dashProc.pid})`);
   console.log(`  Dashboard: http://localhost:${DASH_PORT}`);
 
+  const supProc = spawnSupervisor();
+  console.log(`  Supervisor started (PID: ${supProc.pid})`);
+
   void (async () => {
     const shouldOpen = forceOpen || !dashWasUp ||
       !(await _waitForBrowserReconnect(MINIONS_HOME, { afterMs: restartStartMs, timeoutMs: 5000 }));
@@ -822,6 +895,11 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   ensureInstalled();
   const dashWasUp = isPortListening(DASH_PORT);
   const restartStartMs = Date.now();
+  // Pre-write stop-intent so the supervisor doesn't race-respawn the
+  // engine/dashboard we're about to kill. Killed before the engine/dashboard
+  // so its 30s tick doesn't fire mid-restart against a half-dead engine.
+  writeStopIntent('minions restart');
+  killSupervisor();
   // Layered kill — each step is best-effort, so the next still runs if one
   // fails. Goal: the old engine is gone before we spawn a new one, even if
   // PowerShell is unavailable, the engine is hung, or its cmdline doesn't match.
@@ -831,7 +909,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   // survive so the new engine can re-attach them via PID files).
   killPidOnly(oldEnginePid);
   killByPort(DASH_PORT);
-  killMinionsProcesses(['engine.js', 'dashboard.js']);
+  killMinionsProcesses(['engine.js', 'dashboard.js', 'supervisor.js']);
   // Confirm the OS finished the asynchronous termination before we spawn new
   // processes. Without this, `taskkill /F` returns immediately while the
   // kernel is still releasing the dashboard's port; the new dashboard spawned
@@ -857,6 +935,8 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   // Clear stale beacons AFTER the kill so the old dashboard's last writes
   // can't repopulate the file in the gap between clear and shutdown.
   _clearDashboardBrowserState(MINIONS_HOME);
+  // Clear stop-intent so the freshly-spawned supervisor resumes guarding.
+  clearStopIntent();
   const engineOut = _openStdioLog('engine-stdio.log');
   const engineErr = _openStdioLog('engine-stdio.log');
   const engineProc = spawn(process.execPath, [path.join(MINIONS_HOME, 'engine.js'), 'start', ...rest], {
@@ -867,6 +947,8 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   const dashProc = spawnDashboard();
   console.log(`  Dashboard started (PID: ${dashProc.pid})`);
   console.log(`  Dashboard: http://localhost:${DASH_PORT}`);
+  const supProc = spawnSupervisor();
+  console.log(`  Supervisor started (PID: ${supProc.pid})`);
   console.log('  Verifying restart health...');
   void (async () => {
     const result = await waitForRestartHealth({
@@ -1007,9 +1089,14 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   console.log('\n  Uninstalling Minions...\n');
 
   // 1. Kill all processes
+  // Stop-intent FIRST so the supervisor stands down before we kill it. Without
+  // this the supervisor could race-respawn the engine/dashboard between our
+  // engine-stop and the supervisor kill.
+  writeStopIntent('minions uninstall');
+  killSupervisor();
   try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME, timeout: 10000 }); } catch {}
   killByPort(DASH_PORT);
-  killMinionsProcesses(['engine.js', 'dashboard.js', 'spawn-agent.js']);
+  killMinionsProcesses(['engine.js', 'dashboard.js', 'spawn-agent.js', 'supervisor.js']);
   console.log('  Killed all processes');
 
   // 2. Remove minions-authored skills from ~/.claude/skills/

package/dashboard.js

@@ -5,6 +5,11 @@
  * Opens: http://localhost:7331
  */
 
+// Install ISO timestamp prefixes on console.{log,info,warn,error} so the
+// post-mortem in engine/dashboard-stdio.log is diagnosable to the second.
+// Must run BEFORE any other require that might log during module init.
+require('./engine/stdio-timestamps').installIfNotInstalled();
+
 const http = require('http');
 const zlib = require('zlib');
 const fs = require('fs');

package/engine/cli.js

@@ -462,6 +462,12 @@ const commands = {
       try { fs.writeFileSync(path.join(shared.MINIONS_DIR, '.minions-version'), codeVersion); } catch {}
     }
     e.log('info', 'Engine started');
+    // F1: clear stop-intent on every successful engine boot. Covers `node
+    // engine.js start` (direct CLI), `minions start` (delegates to engine.js
+    // start via engineCmds), and the dashboard's restartEngine path — all of
+    // which would otherwise leave a prior `minions stop`'s stop-intent on
+    // disk and silently stand down the external supervisor.
+    try { shared.clearStopIntent(); } catch { /* best effort */ }
     console.log(`Engine started (PID: ${process.pid})`);
 
     const config = getConfig();
@@ -1100,6 +1106,14 @@ const commands = {
       console.log('  On next start, they\'ll get a 20-min grace period before being marked as orphans.');
       console.log('  To kill them now, run: node engine.js kill\n');
     }
+    // Write stop-intent BEFORE killing so the external supervisor (engine/
+    // supervisor.js) sees the flag on its next tick and stands down instead
+    // of respawning. Cleared by `minions start`/`restart` AND by every
+    // successful engine boot (engine/cli.js#start) — so a direct
+    // `node engine.js start` after this stop still clears the flag.
+    if (!shared.writeStopIntent('engine.js stop')) {
+      e.log('warn', 'Failed to write stop-intent');
+    }
     const control = getControl();
     if (control.pid && control.pid !== process.pid) {
       try { process.kill(control.pid); } catch { /* process may be dead */ }

package/engine/shared.js

@@ -935,6 +935,44 @@ function deleteDispatchPromptSidecar(item) {
  * The thrown error points at the bloated file so operators can act instead
  * of chasing V8 heap traces.
  */
+// ── Stop-intent flag (engine/stop-intent.json) ──────────────────────────────
+//
+// File-presence signal used by the external supervisor (engine/supervisor.js)
+// to know when a user explicitly asked Minions to be down (`minions stop`,
+// `minions uninstall`, `engine.js stop`, mid-`minions restart`). Centralized
+// here so dashboard.js, bin/minions.js, engine/cli.js, and supervisor.js all
+// honor the same contract:
+//
+//   - Set by every stop/kill code path BEFORE killing.
+//   - Cleared by every start/respawn code path AFTER the new processes are up.
+//   - File presence (even empty / corrupt) means "user wanted stop" — read
+//     fail-closed so a half-written JSON during a kill window can't be
+//     interpreted as "no intent" and trigger a respawn-against-user-wishes.
+//
+// Body schema: `{ stoppedAt: ISO, source: string }`. Source is informational
+// only; presence is the load-bearing signal.
+
+const STOP_INTENT_PATH = path.join(ENGINE_DIR, 'stop-intent.json');
+
+function writeStopIntent(source) {
+  try {
+    fs.writeFileSync(STOP_INTENT_PATH, JSON.stringify({
+      stoppedAt: new Date().toISOString(),
+      source: source || 'unspecified',
+    }, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+function clearStopIntent() {
+  try { fs.unlinkSync(STOP_INTENT_PATH); return true; }
+  catch { return false; }
+}
+
+function isStopIntentSet() {
+  return fs.existsSync(STOP_INTENT_PATH);
+}
+
 function assertStateFileSize(filePath, maxBytes) {
   const limit = Number(maxBytes) > 0 ? Number(maxBytes) : ENGINE_DEFAULTS.maxStateFileBytes;
   try {
@@ -5430,6 +5468,10 @@ module.exports = {
   resolveEngineCacheDir,
   openUrlInBrowser,
   CONTROL_PATH,
+  STOP_INTENT_PATH,
+  writeStopIntent,
+  clearStopIntent,
+  isStopIntentSet,
   COOLDOWNS_PATH,
   ENGINE_STATE_PATH, // W-mp60tw0u000j3931
   PR_LINKS_PATH,

package/engine/stdio-timestamps.js

@@ -0,0 +1,37 @@
+/**
+ * engine/stdio-timestamps.js — Prefix every console.log/warn/error/info line
+ * with an ISO-8601 timestamp so dashboard-stdio.log and engine-stdio.log
+ * become diagnosable to the second.
+ *
+ * Required at the very top of dashboard.js and engine.js (and supervisor.js).
+ * Without this, "what was the dashboard doing at 01:01:56?" requires fishing
+ * through log.json's adjacent engine entries and hoping timing lines up.
+ *
+ * The wrap is a no-op when MINIONS_NO_STDIO_TIMESTAMPS is truthy (used by
+ * tests that compare console output verbatim).
+ */
+
+const _STAMP = Symbol.for('minions.stdioTimestampsInstalled');
+
+function _ts() { return new Date().toISOString(); }
+
+function _wrap(method) {
+  const original = console[method].bind(console);
+  return (...args) => {
+    try { original(`[${_ts()}]`, ...args); }
+    catch { original(...args); }
+  };
+}
+
+function installIfNotInstalled() {
+  if (globalThis[_STAMP]) return false;
+  if (process.env.MINIONS_NO_STDIO_TIMESTAMPS) return false;
+  console.log = _wrap('log');
+  console.info = _wrap('info');
+  console.warn = _wrap('warn');
+  console.error = _wrap('error');
+  globalThis[_STAMP] = true;
+  return true;
+}
+
+module.exports = { installIfNotInstalled };

package/engine/supervisor.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * engine/supervisor.js — External watchdog for engine + dashboard.
+ *
+ * Spawned `detached: true` by `minions start`/`restart` after the engine and
+ * dashboard are up. Polls every SUPERVISOR_INTERVAL_MS:
+ *   - engine PID from `engine/control.json`
+ *   - dashboard PID via port-listener probe (port 7331 by default)
+ *
+ * When either is dead AND the stop-intent flag is NOT set, respawns the dead
+ * one in the same way the CLI does (detached, stdio routed to the engine-
+ * authored log files). When the stop-intent flag IS set, the supervisor
+ * stands down — the user explicitly asked Minions to be down.
+ *
+ * Background: see conversation 2026-06-01. The dashboard runs an in-process
+ * watchdog that respawns the engine, but nothing watched the dashboard. When
+ * both processes died together (terminal close, logoff, OOM), neither could
+ * recover. This external supervisor closes that gap.
+ *
+ * The supervisor itself is intentionally unmonitored. If you need stronger
+ * guarantees (machine reboot, OS-level user logoff), register Minions as a
+ * Windows Service via nssm — see docs/supervisor.md.
+ */
+
+require('./stdio-timestamps').installIfNotInstalled();
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, execSync } = require('child_process');
+
+// Lazy path getters route through engine/shared.js when available so the
+// supervisor's notion of "the engine dir" honors MINIONS_TEST_DIR (used by
+// the unit tests). Fall back to __dirname-based resolution when shared.js
+// isn't loadable (e.g. early load / bad upgrade) so the supervisor still
+// boots in production.
+const MINIONS_DIR = path.resolve(__dirname, '..');
+function _sharedOrNull() {
+  try { return require('./shared'); } catch { return null; }
+}
+function _engineDir() { return _sharedOrNull()?.ENGINE_DIR || __dirname; }
+const STATIC_ENGINE_DIR = __dirname; // for require-time paths that can't be lazy
+function CONTROL_PATH_FN() { return path.join(_engineDir(), 'control.json'); }
+function STOP_INTENT_PATH_FN() { return _sharedOrNull()?.STOP_INTENT_PATH || path.join(_engineDir(), 'stop-intent.json'); }
+function SUPERVISOR_PID_PATH_FN() { return path.join(_engineDir(), 'supervisor.pid'); }
+
+// Eager bindings preserved for backwards-compatible exports — read-only
+// snapshots of the path at module-load time. Internal callers should use
+// the _FN getters above so MINIONS_TEST_DIR overrides take effect.
+const CONTROL_PATH = path.join(STATIC_ENGINE_DIR, 'control.json');
+const STOP_INTENT_PATH = path.join(STATIC_ENGINE_DIR, 'stop-intent.json');
+const SUPERVISOR_PID_PATH = path.join(STATIC_ENGINE_DIR, 'supervisor.pid');
+
+const SUPERVISOR_INTERVAL_MS = Number(process.env.MINIONS_SUPERVISOR_INTERVAL_MS) || 30000;
+const DASH_PORT = Number(process.env.MINIONS_DASHBOARD_PORT) || 7331;
+// Grace window after we (re)spawn a process — gives it time to bind its port
+// or write its PID before we re-probe. Without this we'd race the freshly
+// spawned process and double-spawn.
+const POST_SPAWN_GRACE_MS = Number(process.env.MINIONS_SUPERVISOR_GRACE_MS) || 15000;
+const isWin = process.platform === 'win32';
+
+function safeReadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+// Single source of truth lives in engine/shared.js (writeStopIntent /
+// clearStopIntent / isStopIntentSet). The supervisor used to re-implement
+// this locally; centralizing it ensures dashboard.js, bin/minions.js,
+// engine/cli.js, and the supervisor all read/write through one contract.
+// Fall back to a local file-presence check if shared.js fails to load (e.g.
+// during a bad upgrade) — we'd rather fail-closed than crash the supervisor.
+function isStopIntentSet() {
+  try {
+    const shared = require('./shared');
+    if (shared && typeof shared.isStopIntentSet === 'function') {
+      return shared.isStopIntentSet();
+    }
+  } catch { /* shared unavailable — fall through to local probe */ }
+  return fs.existsSync(STOP_INTENT_PATH_FN());
+}
+
+function isPidAlive(pid) {
+  if (!pid) return false;
+  try {
+    if (isWin) {
+      const out = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+        encoding: 'utf8', timeout: 3000, windowsHide: true,
+      });
+      return out.includes(String(pid));
+    }
+    process.kill(pid, 0);
+    return true;
+  } catch { return false; }
+}
+
+function listeningPidsForPort(port) {
+  try {
+    if (isWin) {
+      const out = execSync(`netstat -ano | findstr ":${port} " | findstr LISTENING`, {
+        encoding: 'utf8', timeout: 5000, windowsHide: true,
+      });
+      const pids = new Set();
+      for (const line of out.split('\n')) {
+        const pid = line.trim().split(/\s+/).pop();
+        if (pid && /^\d+$/.test(pid) && pid !== '0') pids.add(Number(pid));
+      }
+      return [...pids];
+    }
+    const out = execSync(`lsof -ti:${port}`, { encoding: 'utf8', timeout: 5000 });
+    return out.split('\n').map(s => s.trim()).filter(Boolean).map(Number);
+  } catch { return []; }
+}
+
+function openAppendFd(name) {
+  // Try to use the same append-fd helper the rest of the codebase uses, fall
+  // back to a plain fs.openSync(..., 'a') when it isn't available. We re-route
+  // child stdio to engine/<name> so a respawned process produces a postmortem
+  // in the same place a CLI-spawned one would.
+  //
+  // Uses _engineDir() (lazy getter) — not the removed top-level ENGINE_DIR.
+  // The fixup commit renamed top-level ENGINE_DIR to STATIC_ENGINE_DIR and
+  // _engineDir(), and a stale ENGINE_DIR reference here silently returned
+  // 'ignore' for both stdout AND stderr, causing every supervisor-spawned
+  // dashboard and engine to lose its stdio trail entirely (the dashboard
+  // still serves HTTP 200, but you can't see anything it logs).
+  const dir = _engineDir();
+  try {
+    const shared = require('./shared');
+    if (shared && typeof shared.openAppendLogFd === 'function') {
+      return shared.openAppendLogFd(name, dir, { fallback: 'ignore' }).fd;
+    }
+  } catch { /* shared unavailable — fall through */ }
+  try { return fs.openSync(path.join(dir, name), 'a'); } catch { return 'ignore'; }
+}
+
+function spawnEngine() {
+  const out = openAppendFd('engine-stdio.log');
+  const err = openAppendFd('engine-stdio.log');
+  const proc = spawn(process.execPath, [path.join(MINIONS_DIR, 'engine.js'), 'start'], {
+    cwd: MINIONS_DIR,
+    stdio: ['ignore', out, err],
+    detached: true,
+    windowsHide: true,
+  });
+  proc.unref();
+  return proc.pid;
+}
+
+function spawnDashboard() {
+  const out = openAppendFd('dashboard-stdio.log');
+  const err = openAppendFd('dashboard-stdio.log');
+  const env = { ...process.env, MINIONS_NO_AUTO_OPEN: '1' };
+  const proc = spawn(process.execPath, [path.join(MINIONS_DIR, 'dashboard.js')], {
+    cwd: MINIONS_DIR,
+    stdio: ['ignore', out, err],
+    detached: true,
+    windowsHide: true,
+    env,
+  });
+  proc.unref();
+  return proc.pid;
+}
+
+// Initialized to Date.now() in main() so the supervisor's first tick (fires
+// at +2s after spawn) is INSIDE the POST_SPAWN_GRACE_MS window. Without this
+// the first tick can race the freshly-spawned engine from `minions restart`
+// before that engine has written its PID to control.json, double-spawning
+// the engine.
+let _lastEngineRespawnAt = 0;
+let _lastDashboardRespawnAt = 0;
+
+// Window during which a `null` pid + recent `restarted_at` is interpreted as
+// "another watchdog is currently respawning the engine — don't double-spawn."
+// The dashboard's in-process engine watchdog (dashboard.js:11873-11901) calls
+// `mutateControl({pid:null, restarted_at})` BEFORE spawning, opening a gap
+// where supervisor would otherwise see `state==='running' && !control.pid`
+// and racefully spawn a second engine. 60s gives the new engine ample time
+// to enter cli.js:443 and write its own PID on cold Windows boots.
+const RESPAWN_IN_PROGRESS_WINDOW_MS = Number(process.env.MINIONS_SUPERVISOR_RESPAWN_WINDOW_MS) || 60000;
+
+function checkEngine(now) {
+  if (now - _lastEngineRespawnAt < POST_SPAWN_GRACE_MS) return;
+  const control = safeReadJson(CONTROL_PATH_FN());
+  // Only respawn when control.json says "running" — paused/stopped/stopping
+  // are legitimate states the supervisor must not override.
+  if (!control || control.state !== 'running') return;
+  if (control.pid && isPidAlive(control.pid)) return;
+
+  // Cross-watchdog race guard: dashboard.js's in-process engine watchdog
+  // writes `{pid: null, restarted_at}` BEFORE spawning a new engine. During
+  // that window supervisor's `control.pid && isPidAlive` check falls through
+  // (pid is null/falsy) and we would double-spawn. If `restarted_at` was
+  // updated in the last RESPAWN_IN_PROGRESS_WINDOW_MS, assume someone else
+  // owns the respawn and skip this tick.
+  if (control.pid == null && control.restarted_at) {
+    const restartedAtMs = Date.parse(control.restarted_at);
+    if (Number.isFinite(restartedAtMs) && (now - restartedAtMs) < RESPAWN_IN_PROGRESS_WINDOW_MS) {
+      return;
+    }
+  }
+
+  console.log(`[supervisor] Engine PID ${control.pid || '(none)'} is dead — respawning...`);
+  const newPid = spawnEngine();
+  _lastEngineRespawnAt = now;
+  console.log(`[supervisor] Engine respawned (new PID: ${newPid})`);
+}
+
+function checkDashboard(now) {
+  if (now - _lastDashboardRespawnAt < POST_SPAWN_GRACE_MS) return;
+  const pids = listeningPidsForPort(DASH_PORT);
+  if (pids.length > 0) return;
+
+  console.log(`[supervisor] Dashboard not listening on port ${DASH_PORT} — respawning...`);
+  const newPid = spawnDashboard();
+  _lastDashboardRespawnAt = now;
+  console.log(`[supervisor] Dashboard respawned (new PID: ${newPid})`);
+}
+
+function tick() {
+  try {
+    if (isStopIntentSet()) return;
+    const now = Date.now();
+    checkEngine(now);
+    checkDashboard(now);
+  } catch (e) {
+    console.error(`[supervisor] tick error: ${e && e.message}`);
+  }
+}
+
+function writePidFile() {
+  try { fs.writeFileSync(SUPERVISOR_PID_PATH_FN(), String(process.pid)); } catch { /* best effort */ }
+}
+
+function clearPidFileIfMine() {
+  try {
+    const existing = fs.readFileSync(SUPERVISOR_PID_PATH_FN(), 'utf8').trim();
+    if (existing === String(process.pid)) fs.unlinkSync(SUPERVISOR_PID_PATH_FN());
+  } catch { /* file already gone or read failed — fine */ }
+}
+
+function main() {
+  // Single-instance guard: if another supervisor is already alive (PID file
+  // points to a live process), exit cleanly. Avoids supervisor-spawning-
+  // supervisor loops during rapid `minions restart`.
+  const existing = (() => {
+    try { return Number(fs.readFileSync(SUPERVISOR_PID_PATH_FN(), 'utf8').trim()); } catch { return null; }
+  })();
+  if (existing && existing !== process.pid && isPidAlive(existing)) {
+    console.log(`[supervisor] Another supervisor already running (PID ${existing}); exiting.`);
+    process.exit(0);
+  }
+
+  writePidFile();
+  // Seed both respawn timestamps so the first tick is inside the post-spawn
+  // grace window — supervisor was spawned moments after engine + dashboard
+  // and we don't want to race them. Without this seed, _lastEngineRespawnAt
+  // = 0 and the +2s warm-up tick can fire before the fresh engine writes
+  // its PID to control.json on cold Windows boots.
+  _lastEngineRespawnAt = Date.now();
+  _lastDashboardRespawnAt = Date.now();
+  console.log(`[supervisor] Started (PID ${process.pid}); interval=${SUPERVISOR_INTERVAL_MS}ms, dashboardPort=${DASH_PORT}`);
+
+  const interval = setInterval(tick, SUPERVISOR_INTERVAL_MS);
+  // Run one tick immediately so a freshly-restarted Minions covers any early
+  // crash in the first SUPERVISOR_INTERVAL_MS window.
+  setTimeout(tick, 2000);
+
+  function shutdown(reason) {
+    console.log(`[supervisor] Shutting down (${reason}).`);
+    clearInterval(interval);
+    clearPidFileIfMine();
+    // Don't process.exit — let the runtime drain remaining log writes.
+  }
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('beforeExit', () => clearPidFileIfMine());
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  // Exposed for unit tests — engine code shouldn't reach into these.
+  _internals: {
+    isStopIntentSet,
+    isPidAlive,
+    listeningPidsForPort,
+    openAppendFd,
+    checkEngine,
+    checkDashboard,
+    tick,
+    // Path getters honor MINIONS_TEST_DIR via shared.ENGINE_DIR, so test
+    // isolation correctly redirects writes/reads under createTestMinionsDir.
+    get paths() {
+      return {
+        CONTROL_PATH: CONTROL_PATH_FN(),
+        STOP_INTENT_PATH: STOP_INTENT_PATH_FN(),
+        SUPERVISOR_PID_PATH: SUPERVISOR_PID_PATH_FN(),
+      };
+    },
+  },
+};

package/engine.js

@@ -21,6 +21,11 @@
  *   node .minions/engine.js discover     Dry-run work discovery
  */
 
+// Install ISO timestamp prefixes on console.{log,info,warn,error} so
+// engine-stdio.log is diagnosable to the second. Must run BEFORE any other
+// require that might log during module init.
+require('./engine/stdio-timestamps').installIfNotInstalled();
+
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2092",
+  "version": "0.1.2094",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"