@yemi33/minions 0.1.2447 → 0.1.2449

package/bin/minions.js

@@ -9,12 +9,15 @@
  *   minions remove <project-dir>     Unlink a project
  *   minions list                     List linked projects
  *   minions update [--no-wait]       Update to latest version (--no-wait backgrounds the post-update restart)
+ *                                    Channel-gated: refuses a public install over an internal runtime.
+ *                                    --allow-downgrade overrides the semver downgrade guard.
  *   minions version                  Show installed and package versions
  *   minions doctor [--harness]       Check prerequisites and runtime health (--harness: print runtime harness inventory)
  *   minions state <subcmd>            Check, backup, or export SQLite state
  *   minions restart [--open]         Stop + start engine + dashboard (--open forces a new browser tab)
  *   minions start [--open]           Start engine + dashboard if not already running (no-op when up)
- *   minions stop                     Stop the engine
+ *   minions stop                     Request engine shutdown and return (engine only)
+ *   minions stop --all [--wait]      Stop the whole stack (supervisor + dashboard + engine)
  *   minions status                   Show engine status
  *   minions pause / resume           Pause/resume dispatching
  *   minions queue                    Show dispatch queue
@@ -62,9 +65,28 @@ const net = require('net');
 const { spawn, spawnSync, execSync } = require('child_process');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
-const shared = require(path.join(PKG_ROOT, 'engine', 'shared'));
+const shared = require(path.join(PKG_ROOT, 'engine', 'core', 'shared'));
 const { openUrlInBrowser } = shared;
-const { waitForRestartHealth, formatRestartHealthError } = require(path.join(PKG_ROOT, 'engine', 'restart-health'));
+const {
+  confirmRestartHealthBeforeCleanup,
+  waitForRestartHealth,
+  formatRestartHealthError,
+} = require(path.join(PKG_ROOT, 'engine', 'recovery', 'restart-health'));
+const { removeSupersededModuleFiles } = require('./install-layout');
+const {
+  terminateProcess,
+  listNodePidsMatchingScripts,
+} = require(path.join(PKG_ROOT, 'engine', 'processes', 'process-utils'));
+// P-b28e4f60 — the ordered whole-stack teardown lives in exactly one place.
+// Every CLI path that stops the runtime (stop --all, restart, nuke, uninstall,
+// the init upgrade) calls stopWholeRuntimeStack() below, which wraps this.
+const {
+  stopRuntimeStack,
+  stopStackExitCode,
+  holderIsLiveDaemon,
+  STOP_STACK_EXIT,
+  DEFAULT_STOP_TIMEOUT_MS: STOP_STACK_DEFAULT_TIMEOUT_MS,
+} = require(path.join(PKG_ROOT, 'engine', 'recovery', 'stop-stack'));
 // Dev-mode dashboard port. `--dev` mode (see argv parser below) retargets
 // MINIONS_HOME at PKG_ROOT and routes the dashboard onto this port so a dev
 // checkout coexists with a global npm install on the normal port (7331).
@@ -126,16 +148,6 @@ function getListeningPids(port) {
   } catch { return []; }
 }
 
-/** Kill process(es) listening on a given port. Works cross-platform. */
-function killByPort(port) {
-  const pids = getListeningPids(port);
-  if (process.platform === 'win32') {
-    for (const pid of pids) try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', timeout: 5000, windowsHide: true }); } catch {}
-  } else {
-    for (const pid of pids) try { process.kill(Number(pid), 'SIGKILL'); } catch {}
-  }
-}
-
 const isPortListening = (port) => getListeningPids(port).length > 0;
 
 /** Authoritative "is something accepting TCP connections on this port?" probe.
@@ -157,15 +169,13 @@ function tcpPortAccepts(port, timeoutMs = 1500) {
 }
 
 /**
- * Wait until no process is listening on `port`, retrying a kill on each tick
- * for any stragglers that re-appeared (e.g. orphan child the original kill
- * missed, or a process that respawned itself). Returns true when the port is
- * free, false on timeout.
+ * Wait until no process is listening on `port`. Daemons are terminated only
+ * after exact runtime-root ownership checks before this helper is entered.
  *
  * Rationale: `taskkill /F` and `SIGKILL` return immediately while the OS does
  * the actual termination asynchronously, and the port doesn't transition to
  * available until the kernel finalises the socket close. Without this wait,
- * the new dashboard race-spawned just after `killByPort` can hit EADDRINUSE
+ * the new dashboard race-spawned just after termination can hit EADDRINUSE
  * and exit silently — the bug pattern that surfaced as "Dashboard failed
  * health check, port=7331 listening=no" while the OLD dashboard PID was
  * still bound to the port.
@@ -175,9 +185,6 @@ function waitForPortRelease(port, timeoutMs = 10000, pollMs = 200) {
   while (Date.now() - start < timeoutMs) {
     const pids = getListeningPids(port);
     if (pids.length === 0) return { ok: true, waitedMs: Date.now() - start };
-    // Retry the kill — covers the case where the original killByPort missed a
-    // sibling listener or a new orphan appeared mid-wait.
-    killByPort(port);
     const sleepUntil = Date.now() + pollMs;
     while (Date.now() < sleepUntil) { /* spin */ }
   }
@@ -264,42 +271,50 @@ function readEnginePid(minionsHome) {
  * they can be re-attached on next start (CLAUDE.md timeouts/liveness section).
  * Tree-kill (`taskkill /T`, `pgrep -P` walk) would orphan in-flight work.
  */
-function killPidOnly(pid) {
-  if (!pid || pid === process.pid) return;
-  try {
-    if (process.platform === 'win32') {
-      execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', timeout: 5000, windowsHide: true });
-    } else {
-      try { process.kill(pid, 'SIGKILL'); } catch {}
+function killPidOnly(pid, scriptPaths = daemonScriptPaths()) {
+  if (!pid || pid === process.pid) return false;
+  return terminateProcess('bin.daemon-stop-process', { pid }, { scriptPaths });
+}
+
+function daemonScriptPaths({ includeAgents = false } = {}) {
+  const scripts = [
+    path.join(MINIONS_HOME, 'engine.js'),
+    path.join(MINIONS_HOME, 'dashboard.js'),
+    path.join(MINIONS_HOME, 'engine', 'recovery', 'supervisor.js'),
+  ];
+  if (includeAgents) scripts.push(path.join(MINIONS_HOME, 'engine', 'agents', 'spawn-agent.js'));
+  return scripts;
+}
+
+/** Kill only exact daemon scripts owned by this runtime root. */
+function killMinionsProcesses(scriptPaths, { includeDescendants = false } = {}) {
+  const pids = listNodePidsMatchingScripts(scriptPaths);
+  for (const pid of pids) {
+    if (pid === process.pid) continue;
+    if (includeDescendants) {
+      shared.terminateProcess('bin.daemon-stop-tree', { pid }, { scriptPaths });
     }
-  } catch {}
+    else killPidOnly(pid, scriptPaths);
+  }
+  return pids.filter(pid => pid !== process.pid);
 }
 
-/** Kill minions processes by command-line pattern matching (wmic on Windows, pkill on Unix). */
-function killMinionsProcesses(patterns) {
-  try {
-    if (process.platform === 'win32') {
-      // Use PowerShell Get-CimInstance (works on Win11 where wmic is removed)
-      let out;
-      try {
-        out = execSync('powershell -NoProfile -Command "Get-CimInstance Win32_Process -Filter \\"name=\'node.exe\'\\" | Select-Object ProcessId,CommandLine | ConvertTo-Csv -NoTypeInformation"', { encoding: 'utf8', timeout: 10000, windowsHide: true });
-      } catch {
-        // Fallback to wmic for older Windows
-        try { out = execSync('wmic process where "name=\'node.exe\'" get processid,commandline /format:csv', { encoding: 'utf8', timeout: 10000, windowsHide: true }); } catch { return; }
-      }
-      for (const line of out.split('\n')) {
-        if (patterns.some(p => line.includes(p))) {
-          const pidMatch = line.match(/(\d{2,})/);
-          const pid = pidMatch ? pidMatch[1] : null;
-          if (pid && pid !== String(process.pid)) killPidOnly(pid);
-        }
-      }
-    } else {
-      for (const p of patterns) {
-        try { execSync(`pkill -f "${p}" 2>/dev/null`, { timeout: 5000 }); } catch {}
-      }
+function retryKillVerifiedPids(pids, scriptPaths, { attempts = 3, pollMs = 200 } = {}) {
+  const remaining = new Set(
+    (pids || []).map(Number).filter(pid => Number.isInteger(pid) && pid > 0 && pid !== process.pid),
+  );
+  const killed = [];
+  for (let attempt = 0; attempt < attempts && remaining.size > 0; attempt++) {
+    for (const pid of [...remaining]) {
+      if (!killPidOnly(pid, scriptPaths)) continue;
+      remaining.delete(pid);
+      killed.push(pid);
     }
-  } catch {}
+    if (remaining.size > 0 && attempt + 1 < attempts) {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, pollMs);
+    }
+  }
+  return killed;
 }
 
 /** Open append-mode FDs under engine/ for detached-process stdio. If the file
@@ -363,7 +378,7 @@ function spawnDashboard(requestedPort) {
   return proc;
 }
 
-/** Spawn the external supervisor (engine/supervisor.js). The supervisor
+/** Spawn the external supervisor (engine/recovery/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
@@ -372,18 +387,13 @@ function spawnDashboard(requestedPort) {
 function spawnSupervisor() {
   const out = _openStdioLog('supervisor-stdio.log');
   const err = _openStdioLog('supervisor-stdio.log');
-  const proc = spawn(process.execPath, [..._sqliteSpawnFlags(), path.join(MINIONS_HOME, 'engine', 'supervisor.js')], {
+  const proc = spawn(process.execPath, [..._sqliteSpawnFlags(), path.join(MINIONS_HOME, 'engine', 'recovery', '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');
-
 /**
  * Resolve the cold-start restart-health budget (ms) from config, falling back
  * to ENGINE_DEFAULTS.restartHealthTimeoutMs. Mirrors the Settings clamp range
@@ -449,7 +459,7 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
   void (async () => {
     const healthTimeoutMs = _resolveRestartHealthTimeoutMs();
     const verificationStartedAt = Date.now();
-    const startupResult = await waitForRestartHealth({
+    let startupResult = await waitForRestartHealth({
       minionsHome: MINIONS_HOME,
       expectedEnginePid: engineProc.pid,
       dashboardPid: dashProc.pid,
@@ -460,13 +470,14 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
     });
     if (!startupResult.ok) {
       console.error(formatRestartHealthError(startupResult));
-      _cleanupFailedStackSpawn({
+      const cleanup = await _cleanupFailedStackSpawn({
         enginePid: engineProc.pid,
         dashboardPid: dashProc.pid,
         supervisorPid: null,
         dashboardPort: requested.port,
       });
-      process.exit(1);
+      if (!cleanup.skipped) process.exit(1);
+      startupResult = cleanup.health;
     }
 
     // The CLI owns startup recovery until the exact dashboard PID has bound the
@@ -476,10 +487,10 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
     const supProc = spawnSupervisor();
     console.log(`  Supervisor started (PID: ${supProc.pid})`);
     console.log('  Verifying restart health...');
-    const supervisorInternals = require(path.join(PKG_ROOT, 'engine', 'supervisor'))._internals;
+    const supervisorInternals = require(path.join(PKG_ROOT, 'engine', 'recovery', 'supervisor'))._internals;
     const startupElapsedMs = Date.now() - verificationStartedAt;
     const topologyTimeoutMs = Math.max(MIN_TOPOLOGY_VERIFY_TIMEOUT_MS, healthTimeoutMs - startupElapsedMs);
-    const result = await waitForRestartHealth({
+    let result = await waitForRestartHealth({
       minionsHome: MINIONS_HOME,
       expectedEnginePid: engineProc.pid,
       dashboardPid: dashProc.pid,
@@ -495,18 +506,19 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
       topologyScripts: {
         engine: path.join(MINIONS_HOME, 'engine.js'),
         dashboard: path.join(MINIONS_HOME, 'dashboard.js'),
-        supervisor: path.join(MINIONS_HOME, 'engine', 'supervisor.js'),
+        supervisor: path.join(MINIONS_HOME, 'engine', 'recovery', 'supervisor.js'),
       },
     });
     if (!result.ok) {
       console.error(formatRestartHealthError(result));
-      _cleanupFailedStackSpawn({
+      const cleanup = await _cleanupFailedStackSpawn({
         enginePid: engineProc.pid,
         dashboardPid: dashProc.pid,
         supervisorPid: supProc.pid,
         dashboardPort: requested.port,
       });
-      process.exit(1);
+      if (!cleanup.skipped) process.exit(1);
+      result = cleanup.health;
     }
     console.log(`  Restart verified: engine PID ${result.engine.pid}; dashboard healthy.`);
 
@@ -528,15 +540,39 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
   });
 }
 
-function _cleanupFailedStackSpawn({ enginePid, dashboardPid, supervisorPid, dashboardPort }) {
-  writeStopIntent('restart verification failed');
-  for (const pid of [supervisorPid, dashboardPid, enginePid]) killPidOnly(pid);
-  for (const pid of [supervisorPid, dashboardPid, enginePid]) waitForPidDeath(pid, 5000);
-  if (dashboardPort) {
-    killByPort(dashboardPort);
-    waitForPortRelease(dashboardPort, 5000);
+async function _cleanupFailedStackSpawn({ enginePid, dashboardPid, supervisorPid, dashboardPort }) {
+  const finalHealth = await confirmRestartHealthBeforeCleanup({
+    minionsHome: MINIONS_HOME,
+    expectedEnginePid: enginePid,
+    dashboardPid,
+    dashboardPort,
+    supervisorPid,
+    requireBeaconOwner: true,
+  });
+  if (finalHealth.ok) {
+    console.error(
+      '  Cleanup skipped: the expected engine, dashboard, and supervisor are currently healthy and owned.'
+    );
+    return { skipped: true, health: finalHealth };
   }
-  shared.clearDashboardPortFile(MINIONS_HOME);
+
+  const cleanupSource = `restart verification failed (${process.pid})`;
+  writeStopIntent(cleanupSource);
+  try {
+    for (const [pid, scriptPath] of [
+      [supervisorPid, path.join(MINIONS_HOME, 'engine', 'recovery', 'supervisor.js')],
+      [dashboardPid, path.join(MINIONS_HOME, 'dashboard.js')],
+      [enginePid, path.join(MINIONS_HOME, 'engine.js')],
+    ]) {
+      killPidOnly(pid, [scriptPath]);
+    }
+    for (const pid of [supervisorPid, dashboardPid, enginePid]) waitForPidDeath(pid, 5000);
+    if (dashboardPort) waitForPortRelease(dashboardPort, 5000);
+    shared.clearDashboardPortFile(MINIONS_HOME);
+  } finally {
+    _clearStopIntentIfSource(cleanupSource);
+  }
+  return { skipped: false, health: finalHealth };
 }
 
 /** Poll engine/dashboard-port.json until it appears (dashboard wrote it on
@@ -578,7 +614,7 @@ async function _waitForDashboardPortFile(home, timeoutMs = 12000, pollMs = 150,
 
 /** 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,
+ *  Delegates to engine/core/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() {
@@ -603,19 +639,62 @@ function writeStopIntent(source) {
   }
 }
 
-/** 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() {
+function _clearStopIntentIfSource(source) {
   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 intent = JSON.parse(fs.readFileSync(shared.STOP_INTENT_PATH, 'utf8'));
+    if (intent && intent.source === source) shared.clearStopIntent();
+  } catch { /* missing, replaced, or unreadable intent is preserved */ }
+}
+
+/**
+ * The CLI's ONE whole-stack teardown call site (P-b28e4f60).
+ *
+ * The ordered sequence — stop-intent → supervisor → dashboard → engine drain →
+ * verified reap → WAL-index check → late-respawn sweep → verification — is
+ * owned by engine/recovery/stop-stack.js. `minions stop --all`, `restart`,
+ * `nuke`, `uninstall` and the init upgrade path all route through here, so
+ * exactly one implementation of that sequence exists in the tree.
+ *
+ * `waitForRelease` is opt-in and defaults OFF: only a caller that must PROVE
+ * the database handles are gone (the pre-migration gate behind
+ * `minions stop --all --wait`) blocks on `engine/state.db-shm`. Callers that
+ * immediately replace the stack, or delete the runtime root outright, run the
+ * identical teardown and get the same evidence reported without the wait.
+ *
+ * Never throws for an expected outcome — the caller decides what a refusal or
+ * an expired budget means for ITS command.
+ */
+function stopWholeRuntimeStack({ source, timeoutMs, waitForRelease = false }) {
+  const verdict = stopRuntimeStack({
+    minionsHome: MINIONS_HOME,
+    source,
+    timeoutMs,
+    waitForRelease,
+  });
+  for (const svc of verdict.stopped) {
+    console.log(`  Stopped ${svc.name} (PID ${svc.pid}, ${svc.via})`);
+  }
+  for (const holder of verdict.holders) {
+    console.error(`  Still running: ${holder.name} (PID ${holder.pid}) — ${holder.reason}`);
+  }
+  console.log(`  ${verdict.reason} (${verdict.waitedMs}ms)`);
+  return verdict;
+}
+
+/** `--timeout <ms>` / `--timeout=<ms>` for `minions stop --all`. Defaults to
+ *  the shared module's budget, which matches the internal installer's
+ *  quiescence window so a stop can never be shorter than the wait after it. */
+function _resolveStopAllTimeoutMs(argv) {
+  const flagIdx = argv.indexOf('--timeout');
+  const inline = argv.find(a => typeof a === 'string' && a.startsWith('--timeout='));
+  if (flagIdx < 0 && !inline) return STOP_STACK_DEFAULT_TIMEOUT_MS;
+  const raw = flagIdx >= 0 ? argv[flagIdx + 1] : inline.slice('--timeout='.length);
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    console.error(`\n  --timeout requires a positive integer in milliseconds, got: ${raw || '(missing)'}\n`);
+    process.exit(2);
+  }
+  return n;
 }
 
 const LEGACY_DEFAULT_SQUAD_HOME = path.join(os.homedir(), '.squad');
@@ -823,14 +902,19 @@ if (devMode) process.env.MINIONS_DASHBOARD_PORT = String(devPort);
 // dynamic chain re-introduces the 7331 bug W-mq5nwl9l was opened to fix.
 const DASHBOARD_PORT = resolveDashboardPort(rest).port;
 // Propagate the port to every child (engine, dashboard, delegated subcommands).
-// engine/cli.js status reads MINIONS_PORT; dashboard.js reads PORT. We export
+// engine/operations/cli.js status reads MINIONS_PORT; dashboard.js reads PORT. We export
 // MINIONS_PORT as the *requested* port for legacy consumers, but loopback callers
-// (watch-actions / pipeline / managed-spawn) must read the *actual* bound port
+// (watch action handlers / pipeline / managed-spawn) must read the *actual* bound port
 // from the dashboard-port.json beacon via shared.readDashboardPortFile() — the
 // dashboard may bind to a fallback port (7332+) on EADDRINUSE, and MINIONS_PORT
 // stays frozen at the originally-requested value in that case.
 process.env.MINIONS_PORT = String(DASHBOARD_PORT);
 const POST_UPDATE_INIT_TIMEOUT_MS = 120000;
+// Teardown budget for the paths that immediately REPLACE the stack (upgrade)
+// or DELETE the runtime root (nuke, uninstall). Mirrors the 10s timeout the
+// inline `engine.js stop` call used to carry, so a hung engine cannot stall
+// them — whatever survives the budget is force-reaped or deleted next.
+const FORCED_STOP_BUDGET_MS = 10000;
 // W-mqpx0tpi — the post-update `minions restart` runs as a child of `minions
 // update` under this wall-clock cap. It must outlive the restart-health budget
 // (now up to ~60s for a cold post-`npm install` dashboard boot) plus spawn +
@@ -859,7 +943,7 @@ function getPkgVersionFresh() {
 
 // Which npm distribution is this CLI? Derived from the installed package
 // manifest (public `@yemi33/minions` vs an internal rename produced by
-// tools/prepare-package.js) so `minions version` compares against the right
+// scripts/prepare-package.js) so `minions version` compares against the right
 // registry channel and `minions update` reinstalls ITSELF instead of pulling
 // in a second package that fights over the shared `minions` bin (npm EEXIST).
 function getPkgName() {
@@ -875,6 +959,18 @@ function getInstalledVersion() {
 
 function saveInstalledVersion(version) {
   fs.writeFileSync(path.join(MINIONS_HOME, '.minions-version'), version);
+  // Record WHICH npm distribution produced this runtime root (W-ms6b7prf006tef7f-b).
+  // `.minions-version` alone cannot tell an internal `@opg-microsoft/minions`
+  // root apart from a public `@yemi33/minions` one, so a channel gate has
+  // nothing to compare against. Read back via shared.readRuntimeChannel();
+  // best-effort, because failing to stamp the channel must never fail an init.
+  try {
+    fs.writeFileSync(path.join(MINIONS_HOME, shared.RUNTIME_CHANNEL_MARKER), `${JSON.stringify({
+      name: getPkgName(),
+      version,
+      installedAt: new Date().toISOString(),
+    }, null, 2)}\n`);
+  } catch {}
   // Persist source commit so dashboard can detect repo-based installs
   try {
     const commit = execSync('git rev-parse --short HEAD', { cwd: PKG_ROOT, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
@@ -942,6 +1038,9 @@ function init() {
 
   // Copy with smart merge logic
   copyDir(PKG_ROOT, MINIONS_HOME, excludeTop, alwaysUpdate, neverOverwrite, isUpgrade, actions);
+  for (const removed of removeSupersededModuleFiles(MINIONS_HOME)) {
+    actions.updated.push(`removed ${removed}`);
+  }
   shared.syncBundledPersonalSkills(path.join(MINIONS_HOME, 'skills'), { homeDir: os.homedir() });
 
   // Create config from template if it doesn't exist
@@ -989,7 +1088,7 @@ function init() {
   // current config only references one. Missing optional runtimes surface as
   // warns, not failures.
   try {
-    const { runPreflight, printPreflight } = require(path.join(MINIONS_HOME, 'engine', 'preflight'));
+    const { runPreflight, printPreflight } = require(path.join(MINIONS_HOME, 'engine', 'agents', 'preflight'));
     let preflightConfig = null;
     try { preflightConfig = JSON.parse(fs.readFileSync(path.join(MINIONS_HOME, 'config.json'), 'utf8')); }
     catch { /* config may not exist on first init — fine, preflight handles null */ }
@@ -997,22 +1096,43 @@ function init() {
     printPreflight(results, { label: 'Preflight checks' });
   } catch {}
 
-  // Update flow passes --skip-start so it can perform a single visible restart afterwards.
-  if (isUpgrade && skipStart) return;
+  // Constellation companion report (P-e93c85a1). Purely informational and
+  // strictly non-fatal: init/update must succeed identically whether or not a
+  // Constellation companion exists. The SYNC probe is used deliberately —
+  // init() is synchronous, and the marker-only path is bounded by a single file
+  // read, so a hung or absent companion can never stall an install or upgrade.
+  // Minions never downloads, executes, or installs Constellation; when the
+  // companion is missing or incompatible this only PRINTS the documented
+  // install command for the operator to run. The whole block is wrapped so a
+  // probe defect can never break `minions init` / `minions update`.
+  try {
+    const companion = require(path.join(MINIONS_HOME, 'engine', 'api', 'companion'));
+    const companionLines = companion.formatCompanionLines(
+      companion.probeCompanionSync({ config: _readConfigJsonSafe() })
+    );
+    if (companionLines.length > 0) {
+      console.log('');
+      for (const line of companionLines) console.log(`  ${line}`);
+      console.log('');
+    }
+  } catch { /* companion reporting is optional — never block init/update */ }
+
+  // The caller owns process lifecycle whenever it requests copy/sync-only mode.
+  // This must also hold for a fresh runtime root; otherwise isolated installs
+  // unexpectedly launch a second engine/dashboard/supervisor stack.
+  if (skipStart) return;
 
   // Auto-start on fresh install; direct force-upgrade restarts automatically.
   const upgradeRequested = resolveDashboardPort([]);
   const dashWasUp = isPortListening(upgradeRequested.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.
-    killByPort(upgradeRequested.port);
+    // Ordered teardown (stop-intent → supervisor → dashboard → engine drain →
+    // verified reap → late-respawn sweep) is owned by
+    // engine/recovery/stop-stack.js. Best-effort: an upgrade must not be
+    // blocked by a refusal, and the spawn below replaces whatever survives.
+    // Budget mirrors the 10s the inline `engine.js stop` call used to get.
+    stopWholeRuntimeStack({ source: 'minions upgrade', timeoutMs: FORCED_STOP_BUDGET_MS });
     // Wipe the runtime port file so the new dashboard's freshly-written
     // beacon is the source of truth (avoids polling-back a stale entry).
     shared.clearDashboardPortFile(MINIONS_HOME);
@@ -1278,10 +1398,17 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   Setup:
     minions init                     Bootstrap ~/.minions/ (first time)
     minions update [--no-wait]       Update to latest version (--no-wait backgrounds the restart)
+                                       Refuses a public install over an internal runtime.
+                                       An internal install updates from its own feed (Azure CLI auth).
+                                       --allow-downgrade  Permit a target version older than the installed one
+                                       --registry <url>   Override the internal feed (internal channel only)
     minions version                  Show installed vs package version
     minions doctor [--harness]       Check prerequisites and runtime health (--harness: print runtime harness inventory)
     minions state check              Run SQLite integrity and invariant checks
     minions state backup <file>      Checkpoint and create a consistent SQLite backup
+    minions state summary [--json]   Row-count census + fingerprint of the SQL state
+    minions state verify-backup <file>
+                                      Verify a backup file's integrity and contents
     minions state export <file>      Write a human-readable diagnostic JSON export
     minions state import-legacy-json <dir> --confirm
                                       Offline recovery import from a legacy home
@@ -1295,7 +1422,13 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   Engine:
     minions restart [--open]         Stop + start engine + dashboard (--open forces a new browser tab)
     minions start [--open]           Start engine + dashboard if not already running (idempotent; --open forces a new tab)
-    minions stop                     Stop the engine
+    minions stop                     Stop the engine (requests shutdown and returns immediately)
+    minions stop --all [--wait]      Stop the WHOLE stack: supervisor + dashboard + engine
+                                       --wait          Block until the engine/state.db handles are
+                                                       released (quiescence gate before a migration)
+                                       --timeout <ms>  Budget for the teardown (default 60000)
+                                       Exit codes: 0 stopped · 3 not quiesced within the budget
+                                                   · 4 refused (a live PID could not be verified)
     minions status                   Show agents, projects, queue
     minions pause / resume           Pause/resume dispatching
     minions dispatch                 Force a dispatch cycle
@@ -1351,6 +1484,13 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   init();
 } else if (cmd === 'update') {
   const noWait = rest.includes('--no-wait') || rest.includes('--detach');
+  const allowDowngrade = rest.includes('--allow-downgrade');
+  const registryIdx = rest.indexOf('--registry');
+  const registryOverride = registryIdx !== -1 ? rest[registryIdx + 1] : null;
+  if (registryIdx !== -1 && (!registryOverride || registryOverride.startsWith('--'))) {
+    console.error('\n  ERROR: --registry requires a feed URL.\n');
+    process.exit(1);
+  }
   console.log('\n  Updating Minions...\n');
   // Dev/symlink installs: PKG_ROOT === MINIONS_HOME — npm update is a no-op (symlink already
   // points to the repo), and `minions init --force` would fail (cwd/.minions is inside PKG_ROOT).
@@ -1361,6 +1501,26 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
     console.log(`  Version synced to ${getPkgVersion()} (dev/symlink install — pull from git to update code)`);
   } else {
     const preVersion = getPkgVersionFresh();
+    // CHANNEL GATE (W-ms6b7prf006tef7f-d). The runtime root — not PKG_ROOT — is
+    // the channel authority. PKG_ROOT only says which package an install WOULD
+    // pull; it resolves PUBLIC both from an opg repo checkout (whose own
+    // package.json is named `@yemi33/minions`) and from a stale public global
+    // shim standing in front of an internal runtime. Gating on the runtime's
+    // `.minions-package` marker is what stops a stale public build from landing
+    // on top of a newer internal one. Runs BEFORE any npm call so a refusal
+    // never touches the registry or the install.
+    const channel = shared.resolveUpdateChannel({ pkgRoot: PKG_ROOT, runtimeRoot: MINIONS_HOME });
+    if (!channel.allowed) {
+      console.error(`\n  REFUSED: this would install the public package over an internal runtime.`);
+      console.error(`  Runtime channel:    ${channel.runtimeName}${channel.runtimeVersion ? `@${channel.runtimeVersion}` : ''} (${MINIONS_HOME})`);
+      console.error(`  Would install:      ${channel.pkgName} (resolved from ${PKG_ROOT})`);
+      console.error(`  A public install is never a valid upgrade for an internal runtime.`);
+      console.error(`\n  Use the internal installer instead:`);
+      for (const line of channel.remediation) console.error(`    ${line}`);
+      console.error('');
+      process.exit(1);
+    }
+    if (channel.warning) console.log(`  ${channel.warning}`);
     // Resolve the ACTIVE distribution first: an internal build must update
     // itself, not the public package. Installing `@yemi33/minions` on top of an
     // `@opg-microsoft/minions` install adds a second package claiming the same
@@ -1368,6 +1528,52 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
     // Reinstalling the same package name is an in-place upgrade, so no bin
     // collision is possible.
     const pkgName = getPkgName();
+
+    // INTERNAL FEED ROUTING (W-ms9bhf9k001j29cb). `npm view` / `npm install -g`
+    // with no registry of their own resolve a SCOPED package through whatever
+    // `@scope:registry` the caller's npm config carries — which routed an
+    // `@opg-microsoft/minions` update to a public proxy and answered E404 for a
+    // package that exists in the ISS ProjectFeed-ISS feed. A package served by a
+    // private feed is therefore updated through that feed, using the SAME
+    // auth/config seams as the bootstrap installer (short-lived `az` token →
+    // 0600 temporary userconfig → npm, with the scoped registry pinned on the
+    // command line so ambient config cannot redirect it). Anything not on a
+    // private channel — the public package above all — keeps the plain npm path
+    // below unchanged.
+    const internalInstaller = require('./install-internal-minions');
+    let feed = null;
+    try {
+      feed = internalInstaller.resolveInternalFeed(pkgName, { registry: registryOverride || undefined });
+    } catch (e) {
+      console.error(`\n  ERROR: invalid --registry value: ${e.message}\n`);
+      process.exit(1);
+    }
+    if (registryOverride && !feed) {
+      console.error(`\n  ERROR: --registry applies only to an internal channel install; ${pkgName} is served by your own npm registry.\n`);
+      process.exit(1);
+    }
+
+    let feedSession = null;
+    // Every failure below exits the process, and process.exit() skips `finally`,
+    // so the staged credential is removed explicitly here. The session also
+    // registers its own process-exit hook as a backstop.
+    const exitUpdate = (code) => {
+      if (feedSession) { feedSession.close(); feedSession = null; }
+      process.exit(code);
+    };
+    // Feed failures arrive pre-formatted as operator-actionable lines (which
+    // feed, which auth flow, what a 404 there actually means); anything else is
+    // a plain npm/exec failure.
+    const reportUpdateFailure = (e, fallback) => {
+      if (e && Array.isArray(e.lines)) {
+        console.error('');
+        for (const line of e.lines) console.error(`  ${line}`);
+        console.error('');
+      } else {
+        console.error(fallback, e && e.message ? e.message : e);
+      }
+    };
+
     // Resolve the target version explicitly BEFORE installing, and pin the
     // install to that exact version instead of a floating `@latest` tag. This
     // avoids a race where `npm view` (used here and by `minions version`) and
@@ -1379,21 +1585,51 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
     // though `npm view pkg version` reports a newer one (W-mr9k4a5x00090184).
     let targetVersion;
     try {
-      targetVersion = execSync(shared.buildNpmViewVersionCommand(pkgName), { encoding: 'utf8', timeout: 15000, windowsHide: true }).trim();
+      if (feed) {
+        console.log(`  Internal channel — resolving ${pkgName} from ${feed.registry}`);
+        feedSession = internalInstaller.openInternalFeedSession(feed);
+        targetVersion = feedSession.resolveVersion();
+      } else {
+        targetVersion = execSync(shared.buildNpmViewVersionCommand(pkgName), { encoding: 'utf8', timeout: 15000, windowsHide: true }).trim();
+      }
     } catch (e) {
-      console.error(`  Failed to resolve the latest version of ${pkgName} from the npm registry:`, e.message);
-      process.exit(1);
+      reportUpdateFailure(e, `  Failed to resolve the latest version of ${pkgName} from the npm registry:`);
+      exitUpdate(1);
     }
     if (!targetVersion) {
-      console.error(`  Failed to resolve the latest version of ${pkgName} from the npm registry (empty response).`);
-      process.exit(1);
+      console.error(`  Failed to resolve the latest version of ${pkgName} from the ${feed ? 'internal feed' : 'npm registry'} (empty response).`);
+      exitUpdate(1);
+    }
+    // The public path validates the version inside its install-command builder;
+    // a feed-resolved version reaches npm as an argument the same way, so gate
+    // it identically rather than trusting registry output.
+    if (feed && !shared.isValidNpmVersion(targetVersion)) {
+      console.error(`  Refusing to install an invalid version resolved from the internal feed: ${JSON.stringify(targetVersion)}`);
+      exitUpdate(1);
     }
 
+    // DOWNGRADE GUARD (W-ms6b7prf006tef7f-d). The same stale-packument failure
+    // described above can also resolve BACKWARDS, in which case the install
+    // succeeds and the post-install check below passes (on-disk == target) while
+    // the runtime silently moves to an older build. Compare numerically against
+    // what is on disk and refuse by default.
+    const downgrade = shared.evaluateUpdateDowngrade({ installedVersion: preVersion, targetVersion, allowDowngrade });
+    if (!downgrade.allowed) {
+      console.error(`\n  REFUSED: ${pkgName}@${targetVersion} would downgrade the installed ${pkgName}@${preVersion}.`);
+      for (const line of downgrade.message.split('\n')) console.error(`  ${line}`);
+      console.error('');
+      exitUpdate(1);
+    }
+    if (downgrade.message) console.log(`  ${downgrade.message}`);
+
     try {
-      execSync(shared.buildNpmGlobalInstallCommand(pkgName, targetVersion), { stdio: 'inherit', timeout: 120000 });
+      if (feedSession) feedSession.install(targetVersion);
+      else execSync(shared.buildNpmGlobalInstallCommand(pkgName, targetVersion), { stdio: 'inherit', timeout: 120000 });
     } catch (e) {
-      console.error('  npm update failed:', e.message);
-      process.exit(1);
+      reportUpdateFailure(e, '  npm update failed:');
+      exitUpdate(1);
+    } finally {
+      if (feedSession) { feedSession.close(); feedSession = null; }
     }
     // Equivalent to `minions init --force --skip-start`, but avoids recursing through
     // the global shim while npm is still settling the updated install.
@@ -1470,6 +1706,36 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   }
   console.log('\n  Starting Minions (engine + dashboard + supervisor)...');
   spawnFullStackAndVerify({ rest, forceOpen, dashWasUp: false, restartStartMs: Date.now() });
+} else if (cmd === 'stop' && rest.includes('--all')) {
+  // Opt-in WHOLE-STACK stop. Bare `minions stop` deliberately keeps its
+  // engine-only, non-blocking delegation (engineCmds → `engine.js stop`, which
+  // requests shutdown and returns) because recovery paths, operator scripts
+  // and the engine's own callers depend on that semantic. This branch is the
+  // additive contract on top of it.
+  //
+  //   minions stop --all           full ordered teardown; does not block on
+  //                                the engine/state.db handle release
+  //   minions stop --all --wait    additionally waits for the WAL index to be
+  //                                released, i.e. proves quiescence
+  //
+  // The exit code is the machine-readable result (STOP_STACK_EXIT): 0 stopped,
+  // 3 not quiesced within the budget, 4 refused on an unverified holder. No
+  // caller should ever have to scrape this output.
+  ensureInstalled();
+  const stopAllWait = rest.includes('--wait');
+  const stopAllVerdict = stopWholeRuntimeStack({
+    source: stopAllWait ? 'minions stop --all --wait' : 'minions stop --all',
+    timeoutMs: _resolveStopAllTimeoutMs(rest),
+    waitForRelease: stopAllWait,
+  });
+  process.exit(stopStackExitCode(stopAllVerdict));
+} else if (cmd === 'stop' && rest.includes('--wait')) {
+  // `--wait` alone would silently wait for nothing: the engine-only delegation
+  // returns as soon as shutdown is REQUESTED. Fail loudly instead.
+  console.error('\n  ERROR: `--wait` only applies to the whole-stack stop.');
+  console.error('  Run `minions stop --all --wait` to wait for the runtime handles to be released,');
+  console.error('  or `minions stop` to request engine shutdown and return immediately.\n');
+  process.exit(1);
 } else if (cmd === 'restart') {
   // `--cli` / `--model` flags forward to `engine.js start` so the runtime
   // fleet flips before the daemon spawns (P-6b3f9c2e AC: works on restart).
@@ -1480,16 +1746,6 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   const restartResolved = resolveDashboardPort(rest);
   const dashWasUp = isPortListening(restartResolved.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.
-  const oldEnginePid = readEnginePid(MINIONS_HOME);
-  try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME, timeout: 10000, windowsHide: true }); } catch {}
   // Give the engine's graceful handler time to drain non-reattachable pooled
   // leases. Detached cold agents are not part of that drain and remain alive
   // for normal PID-file reattachment by the replacement engine.
@@ -1499,34 +1755,40 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
       return Number(cfg?.engine?.shutdownTimeout) || shared.ENGINE_DEFAULTS.shutdownTimeout;
     } catch { return shared.ENGINE_DEFAULTS.shutdownTimeout; }
   })();
-  const gracefulEngineStop = waitForPidDeath(oldEnginePid, shutdownTimeout + 5000);
-  if (!gracefulEngineStop.ok) {
-    // Fallback for a hung engine. Kill only the engine PID, never its detached
-    // cold-agent children; pooled leases have already exceeded their drain budget.
-    killPidOnly(oldEnginePid);
+  // Ordered teardown — stop-intent first so the supervisor stands down and
+  // cannot race-respawn what we are about to stop, then supervisor, dashboard,
+  // graceful engine drain, verified reap, and the late-respawn sweep that
+  // closes the watchdog race window. All of it lives in
+  // engine/recovery/stop-stack.js; restart owns only what follows.
+  // The WAL-index release is deliberately NOT awaited: restart replaces the
+  // stack, and the port gate below is its real readiness condition.
+  const teardown = stopWholeRuntimeStack({
+    source: 'minions restart',
+    timeoutMs: shutdownTimeout + 5000,
+    waitForRelease: false,
+  });
+  // A holder that is provably NOT one of our daemons (a stale PID file, a
+  // recycled PID) must not wedge the command restart exists to heal — the port
+  // gate below still refuses to spawn over a live dashboard. Anything else
+  // means a daemon survived, and spawning a second stack over it is exactly
+  // the multi-engine state we must never create.
+  const blockingHolders = teardown.holders.filter(h => holderIsLiveDaemon(h) || h.name === 'engine');
+  if (blockingHolders.length > 0) {
+    console.error(`\n  ERROR: Refusing restart — ${teardown.reason}`);
+    console.error('  The new stack cannot safely take over control.json while those processes are alive.');
+    process.exit(1);
   }
-  killByPort(restartResolved.port);
-  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
-  // ~10ms later hits EADDRINUSE and exits, producing the "Restart verification
-  // failed, port=7331 listening=no" symptom against an orphan PID that's
-  // STILL bound to the port a heartbeat later.
-  if (oldEnginePid) {
-    const engineDead = waitForPidDeath(oldEnginePid, 5000);
-    if (!engineDead.ok) {
-      console.error(`\n  ERROR: Old engine (PID ${oldEnginePid}) did not exit within 5s after kill.`);
-      console.error(`  The new engine cannot safely take over control.json. Aborting restart.`);
-      process.exit(1);
+  let portFree = waitForPortRelease(restartResolved.port, 10000);
+  if (!portFree.ok) {
+    const retriedPids = retryKillVerifiedPids(portFree.stillBound, daemonScriptPaths());
+    if (retriedPids.length > 0) {
+      portFree = waitForPortRelease(restartResolved.port, 5000);
     }
   }
-  const portFree = waitForPortRelease(restartResolved.port, 10000);
   if (!portFree.ok) {
-    console.error(`\n  ERROR: Port ${restartResolved.port} still in use after 10s — killing failed.`);
+    console.error(`\n  ERROR: Port ${restartResolved.port} still in use after verified stop retries.`);
     console.error(`  Bound by PID(s): ${portFree.stillBound.join(', ')}`);
-    console.error(`  Manually free the port: taskkill /F /PID ${portFree.stillBound.join(' /PID ')}`);
-    console.error(`  Then retry: minions restart`);
+    console.error('  Refusing to terminate an unverified port owner. Stop that application explicitly, then retry.');
     process.exit(1);
   }
   // Wipe the runtime port file so a stale entry from the old dashboard
@@ -1539,11 +1801,17 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   // fresh engine/dashboard during the kill→spawn window — those become ORPHANS
   // the new stack never reaps, and orphan engines keep dispatching agents +
   // spawning copilot (the root of the recurring multi-engine / MCP-auth storms).
-  // stop-intent is STILL set here, so any respawn has already stood down or is
-  // about to; reap once more so the stack we spawn below is the ONLY one. Scoped
-  // by command-line to engine/dashboard/supervisor — never touches agent/copilot
-  // children, preserving the re-attach invariant.
-  killMinionsProcesses(['engine.js', 'dashboard.js', 'supervisor.js']);
+  // The sweep itself is step 8 of the shared teardown above (it runs with
+  // stop-intent still set, so any respawn has already stood down, and a
+  // survivor comes back as a holder and aborts this command). What remains
+  // restart-specific is proving the port was not reclaimed in the window
+  // between that sweep and the spawn below.
+  const finalPortFree = waitForPortRelease(restartResolved.port, 5000);
+  if (!finalPortFree.ok) {
+    console.error(`\n  ERROR: Port ${restartResolved.port} was reclaimed during the restart race window.`);
+    console.error(`  Bound by PID(s): ${finalPortFree.stillBound.join(', ')}`);
+    process.exit(1);
+  }
   // Clear stop-intent so the freshly-spawned supervisor resumes guarding.
   clearStopIntent();
   spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs });
@@ -1576,9 +1844,16 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   console.log('\n  Minions Factory Reset\n');
 
   // 1. Kill all processes
-  try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME }); } catch {}
-  killByPort(resolveDashboardPort([]).port);
-  killMinionsProcesses(['engine.js', 'dashboard.js', 'spawn-agent.js']);
+  // The ordered teardown (stop-intent → supervisor → dashboard → engine drain
+  // → verified reap) stands the supervisor down FIRST, so it cannot
+  // race-respawn the engine while we delete the state database underneath it.
+  stopWholeRuntimeStack({ source: 'minions nuke', timeoutMs: FORCED_STOP_BUDGET_MS });
+  // Agents are deliberately spared by the shared teardown so restarts can
+  // reattach them; a factory reset deletes their state, so they go too.
+  killMinionsProcesses(daemonScriptPaths({ includeAgents: true }), { includeDescendants: true });
+  // The nested `init` below re-spawns the stack, so this root must not be left
+  // carrying a stop-intent that would stand the new supervisor down.
+  clearStopIntent();
   shared.clearDashboardPortFile(MINIONS_HOME);
   console.log('  Killed all processes');
 
@@ -1664,12 +1939,12 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   // 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(resolveDashboardPort([]).port);
-  killMinionsProcesses(['engine.js', 'dashboard.js', 'spawn-agent.js', 'supervisor.js']);
+  // engine-stop and the supervisor kill. That ordering — and the graceful
+  // engine drain that follows it — is owned by engine/recovery/stop-stack.js.
+  stopWholeRuntimeStack({ source: 'minions uninstall', timeoutMs: FORCED_STOP_BUDGET_MS });
+  // Agents are deliberately spared by the shared teardown so restarts can
+  // reattach them; an uninstall deletes the runtime root, so they go too.
+  killMinionsProcesses(daemonScriptPaths({ includeAgents: true }), { includeDescendants: true });
   console.log('  Killed all processes');
 
   // 2. Remove minions-authored skills from ~/.claude/skills/
@@ -1680,7 +1955,7 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
         const skillFile = path.join(claudeSkills, dir, 'SKILL.md');
         try {
           const content = fs.readFileSync(skillFile, 'utf8');
-          if (content.includes('Auto-extracted skill') || content.includes('author:')) {
+          if (/<!-- Auto-extracted by [^>]+ on \d{4}-\d{2}-\d{2} -->/.test(content)) {
             fs.rmSync(path.join(claudeSkills, dir), { recursive: true, force: true });
           }
         } catch {}
@@ -1704,13 +1979,27 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   console.log(`    npm install -g ${uninstallPkgName} && minions init\n`);
 } else if (cmd === 'state') {
   ensureInstalled();
-  const operations = require(path.join(MINIONS_HOME, 'engine', 'state-operations'));
+  const operations = require(path.join(MINIONS_HOME, 'engine', 'persistence', 'state-operations'));
   const sub = rest[0];
   try {
     let result;
     if (sub === 'check') result = operations.checkState();
     else if (sub === 'backup') result = operations.backupState(rest[1]);
     else if (sub === 'export') result = operations.exportState(rest[1]);
+    else if (sub === 'summary') {
+      result = operations.summarizeState();
+      if (!rest.includes('--json')) {
+        console.log(`\n  Schema version: ${result.schemaVersion}`);
+        console.log(`  Fingerprint:    ${result.fingerprint}`);
+        console.log('  Row counts:');
+        for (const [table, count] of Object.entries(result.tables)) {
+          console.log(`    ${String(table).padEnd(30)} ${count === null ? 'n/a' : count}`);
+        }
+        console.log('');
+        process.exit(0);
+      }
+    }
+    else if (sub === 'verify-backup') result = operations.verifyBackup(rest[1]);
     else if (sub === 'import-legacy-json') {
       if (!rest.includes('--confirm')) throw new Error('legacy import requires --confirm');
       const enginePid = readEnginePid(MINIONS_HOME);
@@ -1725,7 +2014,7 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
       result = operations.importLegacyJson(rest[1]);
     }
     else {
-      console.error('\n  Usage: minions state (check|backup <file>|export <file>|import-legacy-json <dir> --confirm)\n');
+      console.error('\n  Usage: minions state (check|backup <file>|summary [--json]|verify-backup <file>|export <file>|import-legacy-json <dir> --confirm)\n');
       process.exit(2);
     }
     console.log(JSON.stringify(result, null, 2));
@@ -1765,7 +2054,7 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
     }
   }
   try {
-    const { backfillReviewLearnings } = require(path.join(MINIONS_HOME, 'engine', 'review-learning-backfill'));
+    const { backfillReviewLearnings } = require(path.join(MINIONS_HOME, 'engine', 'memory', 'review-learning-backfill'));
     const result = backfillReviewLearnings({ dryRun, limit, project });
     console.log(JSON.stringify(result, null, 2));
     process.exit(0);
@@ -1775,7 +2064,7 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   }
 } else if (cmd === 'doctor') {
   ensureInstalled();
-  const { doctor, runHarnessDoctor } = require(path.join(MINIONS_HOME, 'engine', 'preflight'));
+  const { doctor, runHarnessDoctor } = require(path.join(MINIONS_HOME, 'engine', 'agents', 'preflight'));
   if (rest.includes('--harness')) {
     // Print the read-only runtime harness inventory and exit. The
     // legacy `minions doctor` still runs the full preflight + runtime fleet
@@ -1791,11 +2080,15 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   // the in-process supervisor can't (Windows job-object teardown when the
   // parent terminal closes, Linux OOM-killer, cgroup limits, pkill, reboot).
   ensureInstalled();
-  const watchdog = require(path.join(MINIONS_HOME, 'engine', 'watchdog'));
+  const watchdog = require(path.join(MINIONS_HOME, 'engine', 'recovery', 'watchdog'));
   const sub = rest[0];
-  const minionsBin = __filename;
+  // Source checkouts should recover with the same code they run, not an older
+  // globally installed package. npm-state installs have no local bin and keep
+  // using this executable as the fallback.
+  const localMinionsBin = path.join(MINIONS_HOME, 'bin', 'minions.js');
+  const minionsBin = fs.existsSync(localMinionsBin) ? localMinionsBin : __filename;
   if (sub === 'tick') {
-    const shared = require(path.join(MINIONS_HOME, 'engine', 'shared'));
+    const shared = require(path.join(MINIONS_HOME, 'engine', 'core', 'shared'));
     // Resolve the live dashboard port via the in-file resolver, which honors
     // the runtime beacon (written by dashboard.js after bind), env, and
     // config — so the watchdog probes whatever port the dashboard actually