@yemi33/minions 0.1.2448 → 0.1.2449

package/bin/install-internal-minions.js

@@ -14,8 +14,9 @@
 // only. State work is delegated to the *installed* CLI (`minions state backup`,
 // `minions init --force`, `minions restart`) rather than reimplemented here —
 // those are the supported entry points and already own the consistency
-// contracts (`engine/state-operations.js#backupState` does
-// `PRAGMA wal_checkpoint(TRUNCATE)` + `VACUUM INTO`).
+// contracts (`engine/persistence/state-operations.js#backupState` does a
+// best-effort `PRAGMA wal_checkpoint(PASSIVE)` + an authoritative
+// `VACUUM INTO`, which is consistent even when the WAL cannot be quiesced).
 //
 // Token handling: the ADO access token is acquired per-run, written only into a
 // 0600 temporary npm userconfig inside the OS temp dir, and that file is removed
@@ -29,7 +30,7 @@ const { spawnSync } = require('child_process');
 
 // ─── Channel constants ──────────────────────────────────────────────────────
 
-/** Azure DevOps resource id used for `az account get-access-token` (mirrors engine/ado-token.js). */
+/** Azure DevOps resource id used for `az account get-access-token` (mirrors engine/ado/token.js). */
 const ADO_TOKEN_RESOURCE = '499b84ac-1321-427f-aa17-267ca6975798';
 
 /** Documented default feed: the ISS ProjectFeed-ISS Azure Artifacts npm registry. */
@@ -66,6 +67,9 @@ const USAGE = `
     --package <name>     Package to install (default: ${INTERNAL_PACKAGE})
     --backup-dir <dir>   Where to write the pre-migration state backup
                          (default: <runtime root>/backups/internal-install-<timestamp>)
+    --runtime-root <dir> Pin the runtime root (MINIONS_HOME) this run reads, backs up,
+                         synchronizes, and restarts. Required to disambiguate when more
+                         than one candidate root carries runtime state.
     --keep-public        Do not uninstall an existing ${PUBLIC_PACKAGE} global install
     --no-restart         Sync runtime files but skip the health-verified restart
     --force              Proceed even while agents are active (see docs/internal-install.md)
@@ -90,6 +94,7 @@ const VALUE_FLAGS = new Map([
   ['--registry', 'registry'],
   ['--package', 'packageName'],
   ['--backup-dir', 'backupDir'],
+  ['--runtime-root', 'runtimeRoot'],
 ]);
 
 /**
@@ -102,6 +107,7 @@ function parseArgs(argv) {
     registry: DEFAULT_REGISTRY,
     packageName: INTERNAL_PACKAGE,
     backupDir: null,
+    runtimeRoot: null,
     keepPublic: false,
     restart: true,
     force: false,
@@ -128,7 +134,17 @@ function parseArgs(argv) {
   if (!opts.packageName.startsWith('@') || !opts.packageName.includes('/')) {
     throw new Error(`--package must be a scoped package name, got: ${opts.packageName}`);
   }
+  // The generic VALUE_FLAGS parse accepts an empty/whitespace string, which
+  // path.resolve() would turn into the cwd — silently installing into a
+  // different root than the caller named.
+  if (opts.runtimeRoot !== null && !String(opts.runtimeRoot).trim()) {
+    throw new Error('--runtime-root requires a value');
+  }
   opts.registry = normalizeRegistry(opts.registry);
+  // An explicitly pinned root is resolved here so every downstream comparison —
+  // candidate dedupe, the MINIONS_HOME handed to children, the printed plan —
+  // sees the same absolute path.
+  if (opts.runtimeRoot) opts.runtimeRoot = path.resolve(opts.runtimeRoot);
   return opts;
 }
 
@@ -154,8 +170,54 @@ function packageScope(packageName) {
   return scope;
 }
 
+// ─── Private-feed channels (W-ms9bhf9k001j29cb) ─────────────────────────────
+//
+// Which npm distributions are served by a private feed instead of the caller's
+// ordinary registry. This is the table `minions update` consults to decide
+// whether an update needs feed auth at all: a package that is not listed keeps
+// the plain `npm view` / `npm install -g` behavior with no token, no temporary
+// config, and no registry override.
+const INTERNAL_FEED_CHANNELS = Object.freeze([
+  Object.freeze({ packageName: INTERNAL_PACKAGE, registry: DEFAULT_REGISTRY }),
+]);
+
+/**
+ * Resolve the private feed that owns `packageName`, or null when the package is
+ * served by whatever registry the caller's npm config already points at.
+ *
+ * Pure: no filesystem, no network, no environment. `registry` overrides the
+ * channel default (the `--registry` flag on both entry points) and is validated
+ * the same way, so an override can never silently downgrade to http.
+ */
+function resolveInternalFeed(packageName, { registry } = {}) {
+  const channel = INTERNAL_FEED_CHANNELS.find(c => c.packageName === packageName);
+  if (!channel) return null;
+  return {
+    packageName,
+    registry: normalizeRegistry(registry || channel.registry),
+    scope: packageScope(packageName),
+  };
+}
+
 // ─── Command construction (pure) ────────────────────────────────────────────
 
+/**
+ * Pin a scoped package's registry at the ONE npm precedence layer ambient
+ * configuration cannot override.
+ *
+ * npm resolves a SCOPED package through `@scope:registry`, and `--registry`
+ * only sets the *default* registry — so a `@opg-microsoft:registry=<public
+ * proxy>` line in the caller's config wins over `--registry` and routes the
+ * request to the wrong feed (observed as a misleading E404 for a package that
+ * exists). npm's precedence is `cli > env > ./.npmrc > --userconfig > global`,
+ * which also means a project `.npmrc` in the caller's cwd beats the temporary
+ * userconfig this script stages. The command line is the only authoritative
+ * layer, and the registry URL is not a secret, so pinning it there is safe.
+ */
+function buildScopeRegistryArg({ packageName, registry }) {
+  return `--${packageScope(packageName)}:registry=${normalizeRegistry(registry)}`;
+}
+
 /**
  * `az` arguments for a short-lived ADO access token. `-o tsv` keeps the raw
  * token off the JSON path so it is never pretty-printed by az itself.
@@ -194,11 +256,13 @@ function buildNpmrc({ registry, scope, token, baseConfig = '' }) {
 }
 
 function buildNpmViewArgs({ packageName, versionSpec, registry, userconfig }) {
-  return ['view', `${packageName}@${versionSpec}`, 'version', '--registry', registry, '--userconfig', userconfig, '--json'];
+  return ['view', `${packageName}@${versionSpec}`, 'version', '--registry', registry, '--userconfig', userconfig,
+    buildScopeRegistryArg({ packageName, registry }), '--json'];
 }
 
 function buildNpmInstallArgs({ packageName, version, registry, userconfig }) {
-  return ['install', '-g', `${packageName}@${version}`, '--registry', registry, '--userconfig', userconfig];
+  return ['install', '-g', `${packageName}@${version}`, '--registry', registry, '--userconfig', userconfig,
+    buildScopeRegistryArg({ packageName, registry })];
 }
 
 /**
@@ -213,6 +277,7 @@ function buildNpmPackArgs({ packageName, version, registry, userconfig, destinat
     'pack', `${packageName}@${version}`,
     '--registry', registry,
     '--userconfig', userconfig,
+    buildScopeRegistryArg({ packageName, registry }),
     '--pack-destination', destination,
     '--json',
   ];
@@ -630,8 +695,161 @@ function redact(text, secrets) {
 
 // ─── Runtime-root inspection ────────────────────────────────────────────────
 
-function resolveRuntimeRoot(env = process.env) {
-  return env.MINIONS_HOME ? path.resolve(env.MINIONS_HOME) : path.join(os.homedir(), '.minions');
+/**
+ * The engine's root-pointer file (`engine/core/shared.js` ROOT_POINTER_PATH, written
+ * by `minions init`). Duplicated rather than imported: this installer must run
+ * on a machine with no Minions installed, so it stays Node-built-ins-only.
+ */
+function runtimeRootPointerPath(homedir = os.homedir()) {
+  return path.join(homedir, '.minions-root');
+}
+
+function readRuntimeRootPointer(homedir = os.homedir()) {
+  try {
+    const pointed = fs.readFileSync(runtimeRootPointerPath(homedir), 'utf8').trim();
+    return pointed ? path.resolve(pointed) : null;
+  } catch { return null; }
+}
+
+/**
+ * Nearest ancestor of `cwd` (inclusive) that looks like a Minions source
+ * checkout — mirrors the `preferSourceCheckout` branch of the engine's
+ * `resolveMinionsHome()`, which returns a package root that contains `.git`.
+ * That branch is precisely why a repo checkout can become the engine's runtime
+ * root, so the installer has to see the same candidate the engine would.
+ *
+ * `engine.js` is required alongside `.git`: `.git` alone is every repository on
+ * the machine, and a directory the engine could never boot from is not a
+ * runtime root — listing it would manufacture ambiguity instead of exposing it.
+ */
+function findCheckoutRoot(cwd, exists) {
+  let dir = cwd ? path.resolve(String(cwd)) : null;
+  for (let depth = 0; dir && depth < 64; depth++) {
+    if (exists(path.join(dir, '.git')) && exists(path.join(dir, 'engine.js'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function describeRuntimeRootSource(source, homedir = os.homedir()) {
+  switch (source) {
+    case 'flag': return '--runtime-root';
+    case 'env': return 'MINIONS_HOME';
+    case 'pointer': return `recorded in ${runtimeRootPointerPath(homedir)}`;
+    case 'default': return 'the default ~/.minions';
+    case 'checkout': return 'a source checkout at or above the current directory';
+    default: return String(source);
+  }
+}
+
+/**
+ * Decide, once and explicitly, which runtime root this run owns.
+ *
+ * The old resolution was `MINIONS_HOME || ~/.minions`: cwd-blind, and blind to
+ * the root-pointer file the ENGINE consults. The engine additionally prefers a
+ * package root containing `.git`. That divergence is how a repo checkout
+ * silently becomes the runtime root — the installer backs up and synchronizes
+ * one root while the engine boots out of another.
+ *
+ * Every candidate the engine could pick is enumerated here, deduplicated by
+ * resolved path (highest-priority source wins), and scored by whether it carries
+ * a NON-EMPTY `engine/state.db` — a zero-byte database is an aborted init, not a
+ * runtime worth protecting.
+ *
+ * Ranking:
+ *   1. `--runtime-root`             explicit operator pin, always wins
+ *   2. two or more stateful roots   REFUSE (`ambiguous`) — never guess
+ *   3. `MINIONS_HOME`               explicit environment pin
+ *   4. the single stateful root     the only way a checkout can be selected, and
+ *                                   only when nothing else carries state
+ *   5. the root-pointer file        what `minions init` last recorded
+ *   6. `~/.minions`                 the default (fresh install)
+ *
+ * Because a stateful candidate outranks every stateless one and two stateful
+ * candidates are a refusal, a repo checkout can never win over a root that
+ * already carries state.
+ *
+ * Pure apart from the injected `exists` / `size` / `readPointer` probes, so the
+ * contract is asserted directly rather than inferred from a live migration.
+ */
+function resolveAuthoritativeRuntimeRoot(options = {}) {
+  const {
+    flag = null,
+    env = process.env,
+    cwd = process.cwd(),
+    homedir = os.homedir(),
+    exists = p => fs.existsSync(p),
+    size = (p) => { try { return fs.statSync(p).size; } catch { return 0; } },
+    readPointer = null,
+  } = options;
+
+  const pointer = readPointer ? readPointer() : readRuntimeRootPointer(homedir);
+  const defaultRoot = path.resolve(path.join(homedir, '.minions'));
+  const ordered = [
+    ['flag', flag],
+    ['env', env && env.MINIONS_HOME],
+    ['pointer', pointer],
+    ['default', defaultRoot],
+    ['checkout', findCheckoutRoot(cwd, exists)],
+  ];
+
+  const candidates = [];
+  const seen = new Set();
+  for (const [source, value] of ordered) {
+    if (!value) continue;
+    const root = path.resolve(String(value));
+    if (seen.has(root)) continue;
+    seen.add(root);
+    const statePath = path.join(root, 'engine', 'state.db');
+    candidates.push({ source, root, hasState: exists(statePath) && size(statePath) > 0 });
+  }
+
+  const bySource = source => candidates.find(c => c.source === source) || null;
+  const pick = (candidate, reason) => ({
+    root: candidate.root,
+    source: candidate.source,
+    candidates,
+    ambiguous: false,
+    reason,
+  });
+
+  const flagged = bySource('flag');
+  if (flagged) return pick(flagged, `pinned explicitly with --runtime-root ${flagged.root}`);
+
+  const stateful = candidates.filter(c => c.hasState);
+  if (stateful.length > 1) {
+    const describe = c => `      ${c.root}  (${describeRuntimeRootSource(c.source, homedir)})`
+      + `${c.hasState ? '  [carries state]' : ''}`;
+    return {
+      root: null,
+      source: null,
+      candidates,
+      ambiguous: true,
+      reason: `${stateful.length} candidate runtime roots carry a non-empty engine/state.db, `
+        + 'and no --runtime-root was given.\n'
+        + '    Candidates considered:\n'
+        + candidates.map(describe).join('\n')
+        + '\n    Refusing to guess which one is authoritative. Re-run pinned to the one you mean:\n'
+        + stateful.map(c => `      --runtime-root ${c.root}`).join('\n'),
+    };
+  }
+
+  const envRoot = bySource('env');
+  if (envRoot) return pick(envRoot, 'pinned by MINIONS_HOME');
+
+  if (stateful.length === 1) {
+    return pick(stateful[0], `the only candidate carrying runtime state (${describeRuntimeRootSource(stateful[0].source, homedir)})`);
+  }
+
+  const pointerRoot = bySource('pointer');
+  if (pointerRoot && exists(pointerRoot.root)) {
+    return pick(pointerRoot, `recorded in ${runtimeRootPointerPath(homedir)}`);
+  }
+
+  const fallback = candidates.find(c => c.root === defaultRoot);
+  return pick(fallback, `the default runtime root${fallback.hasState ? '' : ' (fresh install)'}`);
 }
 
 /**
@@ -679,8 +897,8 @@ function resolveBackupCli(state, exists = p => fs.existsSync(p)) {
  * Decide how to back up the existing runtime's SQLite state, preferring the
  * option that cannot go stale:
  *
- *   1. the runtime's OWN `engine/state-operations.js`. `minions init` copies
- *      `engine/*.js` into the runtime root, so it is present for every installed
+ *   1. the runtime's OWN `engine/persistence/state-operations.js`. `minions init` copies
+ *      packaged engine JavaScript into the runtime root, so it is present for every installed
  *      runtime and is by construction version-matched to that runtime's
  *      `engine/state.db`. Resolving a CLI is not sufficient on its own — the
  *      published public package predates the `minions state` command, so an
@@ -690,10 +908,16 @@ function resolveBackupCli(state, exists = p => fs.existsSync(p)) {
  */
 function resolveBackupStrategy(state, exists = p => fs.existsSync(p)) {
   const runtimeRoot = (state && state.runtimeRoot) || null;
-  const modulePath = runtimeRoot ? path.join(runtimeRoot, 'engine', 'state-operations.js') : null;
+  const modulePaths = runtimeRoot
+    ? [
+      path.join(runtimeRoot, 'engine', 'persistence', 'state-operations.js'),
+      path.join(runtimeRoot, 'engine', 'state-operations.js'),
+    ]
+    : [];
+  const modulePath = modulePaths.find(exists) || null;
   const cli = resolveBackupCli(state, exists);
-  const candidates = [modulePath, ...cli.candidates].filter(Boolean);
-  if (modulePath && exists(modulePath)) return { kind: 'runtime-module', modulePath, candidates };
+  const candidates = [...modulePaths, ...cli.candidates].filter(Boolean);
+  if (modulePath) return { kind: 'runtime-module', modulePath, candidates };
   if (cli.path) return { kind: 'cli', cliPath: cli.path, candidates };
   return { kind: 'none', candidates };
 }
@@ -701,7 +925,16 @@ function resolveBackupStrategy(state, exists = p => fs.existsSync(p)) {
 /** Run the runtime's own backupState() out-of-process against its own MINIONS_HOME. */
 const BACKUP_MODULE_SCRIPT = 'require(process.argv[1]).backupState(process.argv[2]);';
 
-/** Runtime paths that MUST survive the migration. */
+/**
+ * Runtime paths that MUST survive the migration.
+ *
+ * Presence-only by construction — an emptied `engine/state.db` still passes
+ * this list, which is why the `verify-continuity` step exists and compares a
+ * row-level `summarizeState()` census instead. Schedules, pipeline RUNS,
+ * watches, meetings, and QA sessions live in SQL and are covered by that
+ * census; `pipelines/` (definitions), `prompts/`, `playbooks/`, and `agents/`
+ * are on disk and are covered here.
+ */
 const PRESERVED_PATHS = [
   'config.json',
   'engine/state.db',
@@ -711,6 +944,10 @@ const PRESERVED_PATHS = [
   'knowledge',
   'projects',
   'pinned.md',
+  'pipelines',
+  'prompts',
+  'playbooks',
+  'agents',
 ];
 
 /**
@@ -738,7 +975,7 @@ function diffPreservedPaths(before, after) {
  * operator- or agent-authored:
  *
  *   - `routing.md`          the operator's work-type → agent routing table
- *   - `knowledge/agents/`   per-agent memory written by engine/consolidation.js
+ *   - `knowledge/agents/`   per-agent memory written by engine/memory/consolidation.js
  *
  * A package-channel cutover must not reseed either. Their bytes are captured
  * before `sync-init` and put back after it, so the sync can still add newly
@@ -824,7 +1061,7 @@ function assessRollback({ publicUninstalled = false, internalUsable = false } =
 /**
  * Count live agent processes by walking the dispatch PID files the engine
  * writes under `<runtime root>/engine/tmp/` — both the per-dispatch directory
- * layout and the legacy flat layout (see engine/shared.js#forEachPidFile).
+ * layout and the legacy flat layout (see engine/core/shared.js#forEachPidFile).
  * Filesystem-based on purpose: it works with the dashboard down, which is
  * exactly when a migration is most likely to be attempted.
  */
@@ -885,12 +1122,645 @@ function assessAgentActivity({ activeAgents, force }) {
   };
 }
 
+// ─── Service quiescence ─────────────────────────────────────────────────────
+
+/**
+ * The three files the SQLite state actually consists of. `state.db` is the
+ * database; `-wal` is the write-ahead log holding committed-but-uncheckpointed
+ * transactions; `-shm` is the WAL shared-memory index.
+ *
+ * `-shm` is the liveness signal that matters here: SQLite creates it when the
+ * FIRST connection opens the database in WAL mode and removes it when the LAST
+ * one closes cleanly. A present, non-empty `-shm` therefore means a process
+ * still holds the database open even when every PID we know about is gone.
+ */
+const STATE_DB_FILES = ['engine/state.db', 'engine/state.db-wal', 'engine/state.db-shm'];
+const STATE_SHM_REL = 'engine/state.db-shm';
+
+/** Files copied verbatim beside the backup, and put back by a state rollback. */
+const BACKUP_COPIED_FILES = ['config.json', 'routing.md', 'pinned.md'];
+
+/** Subdirectory of the backup holding the ORIGINAL, byte-for-byte state files. */
+const RETAINED_ORIGINAL_DIR = 'original';
+
+const QUIESCE_TIMEOUT_MS = 60000;
+const QUIESCE_POLL_MS = 500;
+const CLI_STOP_TIMEOUT_MS = 120000;
+/** Budget for the read-only capability probe: `minions help` prints and exits. */
+const CLI_HELP_TIMEOUT_MS = 20000;
+
+/**
+ * The stop contract to prefer, as the EXACT argv it issues.
+ *
+ * A bare `minions stop` is delegated to `engine.js stop`, which writes stop
+ * intent and RETURNS — it asks only the engine to stand down and never touches
+ * the dashboard or the supervisor. Those hold `engine/state.db` independently,
+ * so the `-shm` gate below could never go green after a "successful" stop. The
+ * whole-stack verb tears the supervisor, dashboard, and engine down in order and
+ * `--wait` blocks until the handles are actually released.
+ */
+const WHOLE_STACK_STOP_ARGS = ['stop', '--all', '--wait'];
+
+/**
+ * The fallback for a CLI that predates the whole-stack verb. Mid-cutover the
+ * resolved CLI is frequently the OLDER PUBLIC package (see `resolveBackupCli`),
+ * which would reject or ignore `--all`, so it gets the verb it does know plus
+ * the wait loop that has always backed it.
+ */
+const LEGACY_STOP_ARGS = ['stop'];
+
+/**
+ * The verb the capability probe runs.
+ *
+ * `help` is the FIRST branch of the CLI's command dispatch, prints usage, and
+ * exits — no runtime root, no daemon, no state. `minions stop --help` would be
+ * catastrophic here: `stop` is in the CLI's `engineCmds` delegation set, so an
+ * older CLI would forward it to `engine.js stop` and actually stop the engine
+ * as a side effect of asking whether it can.
+ */
+const CLI_CAPABILITY_PROBE_ARGS = ['help'];
+
+/** Operator-facing names for the three ways this gate can try to stop a runtime. */
+const STOP_PATH_LABELS = {
+  'whole-stack': 'whole-stack (`minions stop --all --wait`)',
+  legacy: 'legacy fallback (`minions stop` + wait loop)',
+  none: 'no stop issued (wait loop only)',
+};
+
+/**
+ * Read a CLI's OWN help text and report which stop flags it advertises.
+ *
+ * Deliberately behavioral: the installed CLI is asked what it can do, and the
+ * answer comes from the binary that will actually run. Comparing version strings
+ * would be a guess across two independently-versioned publish channels — the
+ * internal feed and the public registry share no ordering — and the failure mode
+ * of a wrong guess is an unknown flag passed to a live teardown command.
+ *
+ * `--wait` is required as well as `--all` because both are in the argv we issue.
+ * Matching is per line for `--all` so an unrelated mention elsewhere in the help
+ * cannot vouch for the stop verb; `--no-wait` (from `minions update`) cannot
+ * match `--wait`, which needs two consecutive dashes.
+ */
+function detectStopCapabilities(helpText) {
+  const text = String(helpText || '');
+  const wholeStack = text.split(/\r?\n/).some(line => /\bstop\b/.test(line) && /--all\b/.test(line));
+  const wait = /--wait\b/.test(text);
+  return { wholeStack, wait, supported: wholeStack && wait };
+}
+
+/**
+ * Ask the resolved CLI what it supports. FAILS CLOSED to the legacy verb: an
+ * unreadable, empty, or unrecognized answer means we send the command every
+ * published CLI has always understood, never one it might not.
+ */
+function probeStopCapability({ cliPath, run, env, timeoutMs = CLI_HELP_TIMEOUT_MS } = {}) {
+  if (!cliPath) {
+    return { supported: false, probed: false, reason: 'no installed CLI to probe' };
+  }
+  let result;
+  try {
+    result = run(process.execPath, [cliPath, ...CLI_CAPABILITY_PROBE_ARGS], {
+      timeout: timeoutMs,
+      capture: true,
+      allowFailure: true,
+      env,
+    });
+  } catch (e) {
+    return {
+      supported: false,
+      probed: false,
+      reason: `the capability probe could not run (${e && e.message ? e.message : e})`,
+    };
+  }
+  const help = `${(result && result.stdout) || ''}\n${(result && result.stderr) || ''}`;
+  const capabilities = detectStopCapabilities(help);
+  return {
+    supported: capabilities.supported,
+    probed: true,
+    capabilities,
+    reason: capabilities.supported
+      ? 'the installed CLI advertises `minions stop --all [--wait]`'
+      : 'the installed CLI does not advertise `minions stop --all [--wait]`',
+  };
+}
+
+/**
+ * The detail lines every quiescence refusal prints, in ONE place so the cutover
+ * gate and the state-restoring rollback cannot drift.
+ *
+ * Reports which stop contract ran and the exact argv it issued — without that,
+ * "the runtime did not release the database" is indistinguishable between a
+ * whole-stack teardown that genuinely could not finish and a legacy fallback
+ * that only ever asked the engine to stand down.
+ */
+function formatQuiescenceRefusal(quiescence = {}) {
+  const stopPath = quiescence.stopPath || 'none';
+  const issued = Array.isArray(quiescence.stopArgs) && quiescence.stopArgs.length
+    ? `; issued: ${quiescence.stopArgs.join(' ')}`
+    : '';
+  const exit = Number.isInteger(quiescence.stopExitCode) && quiescence.stopExitCode !== 0
+    ? ` (exit code ${quiescence.stopExitCode})`
+    : '';
+  const lines = [`  Stop path: ${STOP_PATH_LABELS[stopPath] || STOP_PATH_LABELS.none}${issued}${exit}`];
+  const holders = Array.isArray(quiescence.holders) ? quiescence.holders : [];
+  if (holders.length) {
+    lines.push('  Still holding the database:');
+    for (const holder of holders) lines.push(`      ${holder.name}  PID ${holder.pid}`);
+  } else {
+    lines.push(`  No recorded service PID is alive, but ${STATE_SHM_REL} is still non-empty —`);
+    lines.push('  an unrecorded process (or a re-parented one) still has the database open.');
+  }
+  return lines;
+}
+
+/**
+ * The PIDs the runtime itself records for its long-lived services, read from
+ * the files the running daemons write — so this works with the dashboard down,
+ * which is exactly when a migration is most likely to be attempted:
+ *
+ *   - `engine/control.json`        `pid`  the engine daemon
+ *   - `engine/dashboard-port.json` `pid`  the dashboard
+ *   - `engine/supervisor.pid`             the supervisor
+ *
+ * Agent processes are deliberately NOT included: they are covered by the
+ * separate active-agent gate, and any database handle they hold is still
+ * caught by the `-shm` evidence below.
+ */
+function readServicePids(runtimeRoot, deps = {}) {
+  const readFile = deps.readFileSync || (p => fs.readFileSync(p, 'utf8'));
+  const sources = [
+    ['engine', ['engine', 'control.json'], 'json'],
+    ['dashboard', ['engine', 'dashboard-port.json'], 'json'],
+    ['supervisor', ['engine', 'supervisor.pid'], 'text'],
+  ];
+  const found = [];
+  for (const [name, segments, shape] of sources) {
+    const file = path.join(runtimeRoot, ...segments);
+    let raw;
+    try { raw = String(readFile(file)); } catch { continue; }
+    let pid = null;
+    if (shape === 'json') {
+      try { pid = Number(JSON.parse(raw).pid); } catch { pid = null; }
+    } else {
+      pid = Number(raw.trim());
+    }
+    if (Number.isInteger(pid) && pid > 0) found.push({ name, pid, file });
+  }
+  return found;
+}
+
+/** Recorded service PIDs that are still running. */
+function detectRunningServices(runtimeRoot, deps = {}) {
+  const isAlive = deps.isAlive || defaultIsAlive;
+  return readServicePids(runtimeRoot, deps)
+    .filter(entry => entry.pid !== process.pid && isAlive(entry.pid));
+}
+
+/** `-shm` evidence for the pinned root: `{ present, bytes }`. */
+function readStateShm(runtimeRoot, deps = {}) {
+  const stat = deps.statSync || (p => fs.statSync(p));
+  try {
+    const info = stat(path.join(runtimeRoot, ...STATE_SHM_REL.split('/')));
+    return { present: true, bytes: Number(info && info.size) || 0 };
+  } catch { return { present: false, bytes: 0 }; }
+}
+
+/**
+ * Pure verdict on whether the state database is free of live handles.
+ *
+ * BOTH conditions must hold: every recorded service PID is dead AND the WAL
+ * shared-memory index is gone or zero-length. Either alone is a false green — a
+ * PID file can be stale while a re-parented process still holds the database,
+ * and `-shm` can lag a PID that has only just been signalled.
+ */
+function assessDatabaseQuiescence({ running = [], shm = { present: false, bytes: 0 } } = {}) {
+  const holders = running.map(entry => ({ name: entry.name, pid: entry.pid }));
+  const shmHeld = !!shm.present && Number(shm.bytes) > 0;
+  if (holders.length) {
+    return {
+      quiesced: false,
+      holders,
+      shmHeld,
+      reason: `still running: ${holders.map(h => `${h.name} (PID ${h.pid})`).join(', ')}`,
+    };
+  }
+  if (shmHeld) {
+    return {
+      quiesced: false,
+      holders,
+      shmHeld,
+      reason: `${STATE_SHM_REL} is still present and non-empty (${shm.bytes} bytes), `
+        + 'so a process still holds the database open',
+    };
+  }
+  return { quiesced: true, holders: [], shmHeld: false, reason: 'no service holds engine/state.db' };
+}
+
+/** Block the calling thread. The installer is deliberately spawnSync-only. */
+function sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Number(ms) || 0); }
+  catch { const until = Date.now() + (Number(ms) || 0); while (Date.now() < until) { /* spin */ } }
+}
+
+/**
+ * Stop the engine/dashboard running against the PINNED root and wait until the
+ * database handles are actually released.
+ *
+ * Ordered before `backup-state` — and therefore before every uninstall and
+ * package mutation — because a backup taken while the engine is writing is a
+ * backup of a moving target, and rewriting the runtime `.js` files underneath a
+ * live daemon is exactly the failure the restart contract does not cover.
+ *
+ * The stop verb is chosen by BEHAVIORAL probe of the resolved CLI, not by
+ * version: `stop --all --wait` when that CLI advertises it, otherwise the legacy
+ * `stop`. Both paths then run the same wait loop, because the CLI's own verdict
+ * is never trusted — the `-shm` evidence below is.
+ *
+ * FAILS CLOSED: when the handles are not released inside the timeout the caller
+ * gets `ok: false`, the path that was taken, and the exact PIDs still holding
+ * the database.
+ */
+function quiesceServices({
+  runtimeRoot,
+  cliPath = null,
+  run,
+  env,
+  log = console.log,
+  timeoutMs = QUIESCE_TIMEOUT_MS,
+  pollMs = QUIESCE_POLL_MS,
+  probeTimeoutMs = CLI_HELP_TIMEOUT_MS,
+  deps = {},
+  sleep = sleepSync,
+  now = () => Date.now(),
+} = {}) {
+  const probeState = () => assessDatabaseQuiescence({
+    running: detectRunningServices(runtimeRoot, deps),
+    shm: readStateShm(runtimeRoot, deps),
+  });
+  const startedAt = now();
+  const initial = probeState();
+  if (initial.quiesced) {
+    return {
+      ok: true,
+      stopped: false,
+      stopPath: 'none',
+      stopArgs: null,
+      stopExitCode: null,
+      capabilityProbe: null,
+      holders: [],
+      waitedMs: 0,
+      reason: initial.reason,
+    };
+  }
+  log(`    ${initial.reason}`);
+  let stopped = false;
+  let stopPath = 'none';
+  let stopArgs = null;
+  let stopExitCode = null;
+  let capabilityProbe = null;
+  if (cliPath) {
+    capabilityProbe = probeStopCapability({ cliPath, run, env, timeoutMs: probeTimeoutMs });
+    stopPath = capabilityProbe.supported ? 'whole-stack' : 'legacy';
+    stopArgs = [cliPath, ...(capabilityProbe.supported ? WHOLE_STACK_STOP_ARGS : LEGACY_STOP_ARGS)];
+    log(`    ${capabilityProbe.reason}.`);
+    log(`    Stopping the runtime — ${STOP_PATH_LABELS[stopPath]} ...`);
+    try {
+      const result = run(process.execPath, stopArgs, {
+        timeout: CLI_STOP_TIMEOUT_MS,
+        capture: true,
+        allowFailure: true,
+        env,
+      });
+      stopExitCode = result && Number.isInteger(result.status) ? result.status : null;
+      stopped = true;
+    } catch (e) {
+      log(`    WARNING: \`minions ${stopArgs.slice(1).join(' ')}\` failed (${e && e.message ? e.message : e}); waiting for the handles anyway.`);
+    }
+  } else {
+    log('    WARNING: no installed CLI was found to run `minions stop`; waiting for the handles to be released.');
+  }
+  const deadline = now() + timeoutMs;
+  let verdict = probeState();
+  while (!verdict.quiesced && now() < deadline) {
+    sleep(pollMs);
+    verdict = probeState();
+  }
+  return {
+    ok: verdict.quiesced,
+    stopped,
+    stopPath,
+    stopArgs,
+    stopExitCode,
+    capabilityProbe,
+    holders: verdict.holders,
+    waitedMs: now() - startedAt,
+    reason: verdict.reason,
+  };
+}
+
+// ─── Original-state retention ───────────────────────────────────────────────
+
+/**
+ * Copy the ORIGINAL `state.db`, `-wal`, and `-shm` byte-for-byte into
+ * `<backup>/original/`, beside the `VACUUM INTO` snapshot.
+ *
+ * The snapshot is the *consistent* artifact and is what a human should restore
+ * by hand; these are the *literal* pre-migration bytes, which is what an
+ * automatic state-restoring rollback needs in order to put the runtime back
+ * exactly as it was — WAL included. Neither is ever deleted by this run under
+ * any outcome: `cleanup` only removes the temporary npm config and the temp
+ * artifact directory.
+ */
+function retainOriginalStateFiles(runtimeRoot, backupDir, deps = {}) {
+  const exists = deps.existsSync || (p => fs.existsSync(p));
+  const mkdir = deps.mkdirSync || ((p, options) => fs.mkdirSync(p, options));
+  const copy = deps.copyFileSync || ((src, dest) => fs.copyFileSync(src, dest));
+  const dir = path.join(backupDir, RETAINED_ORIGINAL_DIR);
+  const retained = [];
+  const missing = [];
+  const failed = [];
+  for (const rel of STATE_DB_FILES) {
+    const src = path.join(runtimeRoot, ...rel.split('/'));
+    const base = path.basename(rel);
+    if (!exists(src)) { missing.push(rel); continue; }
+    try {
+      mkdir(dir, { recursive: true });
+      copy(src, path.join(dir, base));
+      retained.push(`${RETAINED_ORIGINAL_DIR}/${base}`);
+    } catch (e) {
+      failed.push({ rel, error: e && e.message ? e.message : String(e) });
+    }
+  }
+  return { dir, retained, missing, failed };
+}
+
+/**
+ * Put the retained original state files back. Idempotent: copying the same
+ * bytes twice is a no-op, and a sidecar the original run did NOT have is
+ * removed rather than left to pair a restored database with a foreign WAL.
+ *
+ * `engine/state.db` itself is never removed — only its sidecars — so a backup
+ * that somehow lacks the database can never delete the live one.
+ */
+function restoreOriginalStateFiles(runtimeRoot, backupDir, deps = {}) {
+  const exists = deps.existsSync || (p => fs.existsSync(p));
+  const mkdir = deps.mkdirSync || ((p, options) => fs.mkdirSync(p, options));
+  const copy = deps.copyFileSync || ((src, dest) => fs.copyFileSync(src, dest));
+  const remove = deps.rmSync || ((p, options) => fs.rmSync(p, options));
+  const dir = path.join(backupDir, RETAINED_ORIGINAL_DIR);
+  const restored = [];
+  const removed = [];
+  const failed = [];
+  for (const rel of STATE_DB_FILES) {
+    const src = path.join(dir, path.basename(rel));
+    const dest = path.join(runtimeRoot, ...rel.split('/'));
+    try {
+      if (exists(src)) {
+        mkdir(path.dirname(dest), { recursive: true });
+        copy(src, dest);
+        restored.push(rel);
+      } else if (rel !== 'engine/state.db' && exists(dest)) {
+        remove(dest, { force: true });
+        removed.push(rel);
+      }
+    } catch (e) {
+      failed.push({ rel, error: e && e.message ? e.message : String(e) });
+    }
+  }
+  return { dir, restored, removed, failed };
+}
+
+/** Put back the config/routing/pinned copies parked beside the backup. */
+function restoreBackupCopiedFiles(runtimeRoot, backupDir, deps = {}) {
+  const exists = deps.existsSync || (p => fs.existsSync(p));
+  const copy = deps.copyFileSync || ((src, dest) => fs.copyFileSync(src, dest));
+  const restored = [];
+  const failed = [];
+  for (const rel of BACKUP_COPIED_FILES) {
+    const src = path.join(backupDir, rel);
+    if (!exists(src)) continue;
+    try {
+      copy(src, path.join(runtimeRoot, rel));
+      restored.push(rel);
+    } catch (e) {
+      failed.push({ rel, error: e && e.message ? e.message : String(e) });
+    }
+  }
+  return { restored, failed };
+}
+
+// ─── State continuity (pre/post invariants) ─────────────────────────────────
+
+/**
+ * The continuity gate is an explicit ALLOWLIST of durable tables, not a denylist
+ * of volatile ones. A denylist fails open: every table nobody remembered to
+ * enumerate is silently gated, and most of the SQL state legitimately shrinks
+ * across a package cutover —
+ *
+ *   - `cc_sessions` / `doc_sessions` are DELETEd when a session is invalidated
+ *     (engine/persistence/small-state-store.js), and a changed
+ *     `prompts/cc-system.md` hash invalidates CC sessions — which `sync-init`
+ *     ships by definition,
+ *   - `pending_rebases` is deleted and rewritten wholesale every tick,
+ *   - `worktree_pool`, `managed_processes`, `schedule_runs`, `pipeline_runs`,
+ *     `metrics`, `cc_queued_messages`, `memory_retrieval_runs`, `steering_deliveries`
+ *     are all runtime bookkeeping that shrinks by design,
+ *   - `pr_mirror_hashes` is DROPPED outright by migration 018, which surfaces as
+ *     a `missingTables` entry, and
+ *   - `logs` / `events` / `memory_lifecycle_events` / `dispatches` / `cooldowns`
+ *     are capped, consumed, retention-pruned, or expire.
+ *
+ * So only the tables listed here are gated; everything else is passed to
+ * `compareStateSummaries` as `ignoreTables`. These hold irreplaceable
+ * operator- and agent-authored records that no install step may reduce.
+ *
+ * `repairedByMigration` names a shipped REPAIR migration that deletes rows from
+ * that table by design. The gate is lifted for that table only on a run that
+ * actually crosses that schema version — so a normal upgrade still fails on a
+ * PRD drop, while the one migration entitled to delete PRD rows is not reported
+ * as data loss.
+ */
+const CONTINUITY_DURABLE_TABLES = [
+  { table: 'work_items' },
+  { table: 'pull_requests' },
+  { table: 'plans' },
+  // Migration 024 deletes duplicate live PRD echoes of archived imports.
+  { table: 'prds', repairedByMigration: 24 },
+  { table: 'prd_items', repairedByMigration: 24 },
+  { table: 'prd_verify_prs', repairedByMigration: 24 },
+  { table: 'memory_records' },
+  { table: 'inbox_entries' },
+  { table: 'watches' },
+  { table: 'qa_runs' },
+  { table: 'qa_sessions' },
+];
+
+/**
+ * Turn the durable allowlist into the `ignoreTables` set `compareStateSummaries`
+ * expects: every table present on either side of the census that is NOT gated.
+ * Pure — the schema versions come from the two summaries themselves.
+ */
+function resolveContinuityIgnoreTables(before, after, durable = CONTINUITY_DURABLE_TABLES) {
+  const beforeVersion = Number(before && before.schemaVersion) || 0;
+  const afterVersion = Number(after && after.schemaVersion) || 0;
+  const gated = new Set();
+  for (const entry of durable) {
+    const { table, repairedByMigration = null } = typeof entry === 'string' ? { table: entry } : (entry || {});
+    if (!table) continue;
+    // A run that crosses the repair migration is entitled to the deletions it makes.
+    if (repairedByMigration && beforeVersion < repairedByMigration && afterVersion >= repairedByMigration) continue;
+    gated.add(table);
+  }
+  const seen = new Set([
+    ...Object.keys((before && before.tables) || {}),
+    ...Object.keys((after && after.tables) || {}),
+  ]);
+  return [...seen].filter(table => !gated.has(table)).sort();
+}
+
+/** Markers so a summary can be recovered from stdout that also carries warnings. */
+const SUMMARY_BEGIN = '<<MINIONS-STATE-SUMMARY>>';
+const SUMMARY_END = '<</MINIONS-STATE-SUMMARY>>';
+
+const EMIT = (expr) => `process.stdout.write(${JSON.stringify(SUMMARY_BEGIN)}+JSON.stringify(${expr})+${JSON.stringify(SUMMARY_END)});`;
+
+/** Census the LIVE state of a runtime root, through that runtime's own module. */
+const SUMMARIZE_STATE_SCRIPT = EMIT('require(process.argv[1]).summarizeState()');
+
+/** Census a backup file read-only, through the runtime's own `verifyBackup`. */
+const SUMMARIZE_BACKUP_SCRIPT = EMIT('require(process.argv[1]).verifyBackup(process.argv[2]).summary');
+
+/**
+ * Compare two summaries with the runtime's OWN `compareStateSummaries` rather
+ * than a second implementation here. The summaries travel through files because
+ * a full table census is far too large for argv on Windows.
+ */
+const COMPARE_SUMMARIES_SCRIPT = 'const f=require("fs");const m=require(process.argv[1]);'
+  + 'const r=(p)=>JSON.parse(f.readFileSync(p,"utf8"));'
+  + EMIT('m.compareStateSummaries(r(process.argv[2]),r(process.argv[3]),{ignoreTables:r(process.argv[4])})');
+
+/** Recover the emitted JSON payload from a child's stdout. Null when absent. */
+function extractEmittedJson(stdout) {
+  const text = String(stdout == null ? '' : stdout);
+  const start = text.indexOf(SUMMARY_BEGIN);
+  if (start < 0) return null;
+  const end = text.indexOf(SUMMARY_END, start + SUMMARY_BEGIN.length);
+  if (end < 0) return null;
+  try { return JSON.parse(text.slice(start + SUMMARY_BEGIN.length, end)); } catch { return null; }
+}
+
+/**
+ * Locate the state-operations module a runtime root carries. `minions init`
+ * copies packaged engine JavaScript into the runtime root, so it is present for
+ * every installed runtime and is by construction version-matched to that
+ * runtime's `engine/state.db`.
+ */
+function resolveStateOperationsModule(runtimeRoot, exists = p => fs.existsSync(p)) {
+  if (!runtimeRoot) return null;
+  return [
+    path.join(runtimeRoot, 'engine', 'persistence', 'state-operations.js'),
+    path.join(runtimeRoot, 'engine', 'state-operations.js'),
+  ].find(exists) || null;
+}
+
+/**
+ * Run a `summarizeState()` census out-of-process, against either a backup file
+ * (read-only, preferred for the pre-migration side) or the live pinned root.
+ * Never throws — an unavailable census is reported, not fatal, so the caller
+ * can degrade to the presence-only check instead of aborting a healthy install.
+ */
+function readStateSummary({ run, modulePath, backupPath = null, env, timeout = CLI_INIT_TIMEOUT_MS } = {}) {
+  if (!modulePath) {
+    return { ok: false, summary: null, error: 'no engine/persistence/state-operations.js was found under the runtime root' };
+  }
+  const args = backupPath
+    ? ['-e', SUMMARIZE_BACKUP_SCRIPT, modulePath, backupPath]
+    : ['-e', SUMMARIZE_STATE_SCRIPT, modulePath];
+  try {
+    const result = run(process.execPath, args, { timeout, capture: true, env });
+    const summary = extractEmittedJson(result.stdout);
+    if (!summary || !summary.tables) throw new Error('the census returned no table counts');
+    return { ok: true, summary, error: null };
+  } catch (e) {
+    return { ok: false, summary: null, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+/**
+ * Compare a pre- and post-migration census through the runtime's own
+ * `compareStateSummaries`. Returns `{ ok, comparison, error }`; an
+ * unavailable comparison is `ok: false` with `comparison: null`, which the
+ * caller must treat as "could not verify", not as "verified".
+ */
+function compareStateContinuity({
+  run, modulePath, before, after, env,
+  ignoreTables = null,
+  timeout = CLI_INIT_TIMEOUT_MS,
+  tmpDirFactory = () => fs.mkdtempSync(path.join(os.tmpdir(), 'minions-continuity-')),
+} = {}) {
+  if (!modulePath) return { ok: false, comparison: null, error: 'no state-operations module to compare with' };
+  if (!before || !after) return { ok: false, comparison: null, error: 'a state census is missing' };
+  const ignore = ignoreTables || resolveContinuityIgnoreTables(before, after);
+  let dir = null;
+  try {
+    dir = tmpDirFactory();
+    const beforePath = path.join(dir, 'before.json');
+    const afterPath = path.join(dir, 'after.json');
+    const ignorePath = path.join(dir, 'ignore.json');
+    fs.writeFileSync(beforePath, JSON.stringify(before));
+    fs.writeFileSync(afterPath, JSON.stringify(after));
+    fs.writeFileSync(ignorePath, JSON.stringify(ignore));
+    const result = run(process.execPath, ['-e', COMPARE_SUMMARIES_SCRIPT, modulePath, beforePath, afterPath, ignorePath], {
+      timeout, capture: true, env,
+    });
+    const comparison = extractEmittedJson(result.stdout);
+    if (!comparison || typeof comparison.ok !== 'boolean') throw new Error('the comparison returned no verdict');
+    return { ok: true, comparison, error: null };
+  } catch (e) {
+    return { ok: false, comparison: null, error: e && e.message ? e.message : String(e) };
+  } finally {
+    if (dir) { try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ } }
+  }
+}
+
+/** Render a failed comparison as the operator-facing explanation. */
+function describeContinuityFailure(comparison) {
+  const parts = [];
+  if (comparison.missingTables && comparison.missingTables.length) {
+    parts.push(`tables missing after migration: ${comparison.missingTables.join(', ')}`);
+  }
+  if (comparison.emptyAfterNonEmptyBefore && comparison.emptyAfterNonEmptyBefore.length) {
+    parts.push(`tables emptied: ${comparison.emptyAfterNonEmptyBefore.join(', ')}`);
+  }
+  if (comparison.regressions && comparison.regressions.length) {
+    parts.push(`row counts fell: ${comparison.regressions.map(r => `${r.table} ${r.before} → ${r.after}`).join(', ')}`);
+  }
+  return parts.length ? parts.join('; ') : 'the state census regressed';
+}
+
+/**
+ * Decide whether a state-restoring rollback may run. Package rollback is always
+ * available; STATE rollback additionally requires the retained original bytes,
+ * because restoring a `VACUUM INTO` snapshot over a live root would silently
+ * discard the WAL the original run left behind.
+ */
+function assessStateRollback({ backupDir = null, retainedOriginals = [] } = {}) {
+  if (!backupDir) {
+    return { allowed: false, reason: 'this run took no backup, so there is nothing to restore from' };
+  }
+  if (!retainedOriginals.includes('original/state.db')) {
+    return { allowed: false, reason: `the original engine/state.db was not retained under ${RETAINED_ORIGINAL_DIR}/` };
+  }
+  return { allowed: true, reason: `restoring the original state files retained in ${backupDir}` };
+}
+
 // ─── Migration plan (pure) ──────────────────────────────────────────────────
 
 const STEP_ORDER = [
   'acquire-token',
   'validate-feed',
   'download-artifact',
+  'quiesce-services',
   'backup-state',
   'uninstall-public',
   'repair-shims',
@@ -898,6 +1768,7 @@ const STEP_ORDER = [
   'verify-install',
   'verify-shim',
   'sync-init',
+  'verify-continuity',
   'restart',
   'cleanup',
 ];
@@ -911,6 +1782,11 @@ const STEP_ORDER = [
  *   - `download-artifact` precedes `uninstall-public`, so the public package is
  *     only removed once the internal one is resolved AND on local disk — a feed
  *     failure during the install is then recoverable offline.
+ *   - `quiesce-services` precedes `backup-state`, and therefore precedes every
+ *     uninstall and package mutation: a backup taken while the engine is
+ *     writing is a backup of a moving target, and rewriting the runtime `.js`
+ *     files underneath a live daemon is exactly what the restart contract does
+ *     not cover. It fails CLOSED when the handles are not released.
  *   - `backup-state` precedes every mutation of the runtime root, and also
  *     precedes `uninstall-public`, so the cutover never starts without a
  *     restore point.
@@ -923,6 +1799,24 @@ const STEP_ORDER = [
  *     before a restore point exists.
  *   - `verify-shim` precedes `sync-init`, so the runtime is only synchronized
  *     once `minions` actually resolves to the internal package.
+ *   - `verify-continuity` runs while the services are still quiesced, BEFORE
+ *     `restart`. Two reasons, and both are load-bearing:
+ *       1. A census taken against a live engine races it — rows move under the
+ *          count, so the verdict is not reproducible. Under quiescence the only
+ *          writer is the census itself, and `getDb()` applies pending migrations
+ *          on open (`engine/db/index.js`), so a pre-restart census still
+ *          exercises the migrations deterministically.
+ *       2. Its failure action, `rollbackStateAndPackage()`, overwrites
+ *          `engine/state.db{,-wal,-shm}` with the retained pre-migration bytes.
+ *          After a restart that would destroy every write the restarted engine
+ *          and dashboard had already made — including the migrations that had
+ *          just succeeded. Gating before the restart means the rollback can only
+ *          ever discard bytes that nothing has written to since the backup.
+ *     It stays the last gate before `cleanup`: the preserved-path check is
+ *     presence-only and an emptied `engine/state.db` passes it.
+ *   - `restart` is therefore the final action of a run that has already proven
+ *     its state survived, so the machine is only brought back up on state that
+ *     was verified.
  *   - `cleanup` is always last and always present — it runs in a `finally`.
  *
  * `install-internal` is also the only step that (re-)links the `minions` bin
@@ -949,7 +1843,13 @@ function planSteps(state) {
     && !willUninstallPublic
     && shimOwned;
   const skip = new Set();
-  if (!hasExistingRuntime) skip.add('backup-state');
+  if (!hasExistingRuntime) {
+    // Nothing is running against a root that has no runtime, nothing to back
+    // up, and no pre-migration census to compare a post-migration one against.
+    skip.add('quiesce-services');
+    skip.add('backup-state');
+    skip.add('verify-continuity');
+  }
   if (!willUninstallPublic) skip.add('uninstall-public');
   if (alreadyAtTarget) {
     skip.add('install-internal');
@@ -1020,7 +1920,10 @@ function makeRunner(secrets, { log = console.log, error = console.error } = {})
       err.stderr = stderr;
       throw err;
     }
-    if (capture && !ok && stderr.trim()) log(stderr.trimEnd());
+    // A tolerated failure is still a failure: its stderr is the only recorded
+    // cause for the fallback, so it belongs on the diagnostic stream with every
+    // other diagnostic — never interleaved into this script's stdout.
+    if (capture && !ok && stderr.trim()) error(stderr.trimEnd());
     return { ok, stdout, stderr, status: result.status };
   };
 }
@@ -1063,6 +1966,156 @@ function resolveNpmGlobalPath(run, kind, config) {
   } catch { return null; }
 }
 
+// ─── Authenticated feed session (W-ms9bhf9k001j29cb) ────────────────────────
+//
+// The seam `minions update` uses to update an internal install from its own
+// feed. It exists so the in-place updater reuses THIS file's auth/config
+// handling — short-lived `az` token, 0600 temporary userconfig, redacted
+// output, guaranteed cleanup — instead of growing a second, divergent copy of
+// security-sensitive logic in bin/minions.js.
+
+/** Read a version out of `npm view … version --json` (array, JSON string, or bare). */
+function parseViewedVersion(stdout) {
+  const raw = String(stdout == null ? '' : stdout).trim();
+  if (!raw) return '';
+  try {
+    const parsed = JSON.parse(raw);
+    const value = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
+    return value == null ? '' : String(value).trim();
+  } catch {
+    return raw.replace(/^"|"$/g, '');
+  }
+}
+
+/**
+ * Operator-facing explanation for a failed feed operation, as printable lines.
+ *
+ * The failure this replaces is the misleading one: with no registry of its own,
+ * an update of the internal package was routed by ambient npm config to a
+ * public proxy, which answered E404 — reading as "this package does not exist"
+ * for a package that does exist, in a feed that was never contacted. Every
+ * message below therefore names the feed that WAS queried and the two real
+ * causes (auth, or feed read permission / missing version).
+ */
+function describeInternalFeedFailure({ kind, error, feed, versionSpec = DEFAULT_VERSION_SPEC } = {}) {
+  const detail = error && error.message ? String(error.message) : '';
+  const pkg = feed ? feed.packageName : INTERNAL_PACKAGE;
+  const registry = feed ? feed.registry : DEFAULT_REGISTRY;
+  if (kind === 'auth') {
+    return [
+      `Could not acquire an Azure DevOps token for the internal feed (${registry}).`,
+      detail ? `  ${detail}` : '',
+      '  Sign in with the Azure CLI, then retry:',
+      '    az login',
+      '    az account set --subscription <id>   (only if you have more than one)',
+    ].filter(Boolean);
+  }
+  const action = kind === 'install' ? `install ${pkg}@${versionSpec} from` : `read ${pkg}@${versionSpec} from`;
+  return [
+    `Could not ${action} the internal feed.`,
+    `  Feed: ${registry}`,
+    detail ? `  ${detail}` : '',
+    '  This is the ISS ProjectFeed-ISS Azure Artifacts feed, not a public registry — a 404 here',
+    '  means the version is not published to the feed or your account has no Azure Artifacts read',
+    '  access to it, never that the package is unpublished.',
+    '  Check: `az login` succeeds, you have read permission on ProjectFeed-ISS, and the version exists.',
+  ].filter(Boolean);
+}
+
+function feedError({ kind, error, feed, versionSpec }) {
+  const lines = describeInternalFeedFailure({ kind, error, feed, versionSpec });
+  const err = new Error(lines.join('\n'));
+  err.feedFailure = kind;
+  err.lines = lines;
+  return err;
+}
+
+/**
+ * Open an authenticated npm session against a private feed.
+ *
+ * Acquires a short-lived ADO access token through the caller's existing Azure
+ * CLI login and stages it in a 0600 temporary userconfig — the token never
+ * reaches argv, the environment, stdout, or any persistent file. Every npm
+ * command issued through the session carries that userconfig plus the
+ * command-line scope pin, so neither the caller's npm config nor the ambient
+ * default registry can redirect it.
+ *
+ * `close()` removes the staged credential and is idempotent. It is also wired
+ * to a `process.on('exit')` hook, because the caller (`minions update`) exits
+ * non-zero on npm failures and `process.exit()` skips `finally` blocks.
+ */
+function openInternalFeedSession(feed, deps = {}) {
+  if (!feed || !feed.registry || !feed.packageName) throw new Error('an internal feed is required');
+  const log = deps.log || console.log;
+  const error = deps.error || console.error;
+  const secrets = [];
+  const run = deps.run || makeRunner(secrets, { log, error });
+
+  let token;
+  try {
+    const acquired = deps.acquireToken
+      ? deps.acquireToken()
+      : run('az', buildTokenArgs(), { timeout: AZ_TOKEN_TIMEOUT_MS, capture: true }).stdout;
+    token = String(acquired == null ? '' : acquired).trim();
+  } catch (e) {
+    throw feedError({ kind: 'auth', error: e, feed });
+  }
+  if (!token) throw feedError({ kind: 'auth', error: new Error('the Azure CLI returned an empty access token'), feed });
+  secrets.push(token);
+
+  const temp = (deps.writeTempNpmrc || writeTempNpmrc)({
+    registry: feed.registry,
+    scope: feed.scope,
+    token,
+    baseConfig: (deps.readUserNpmrc || readUserNpmrc)(),
+  });
+
+  let closed = false;
+  const cleanup = () => {
+    if (closed) return false;
+    closed = true;
+    return (deps.cleanupTempNpmrc || cleanupTempNpmrc)(temp.dir);
+  };
+  const onExit = () => { cleanup(); };
+  process.on('exit', onExit);
+
+  return {
+    userconfig: temp.file,
+    registry: feed.registry,
+    packageName: feed.packageName,
+    secrets,
+    /** Resolve a version spec (dist-tag or exact) to a concrete version from the feed. */
+    resolveVersion(versionSpec = DEFAULT_VERSION_SPEC) {
+      const args = buildNpmViewArgs({
+        packageName: feed.packageName, versionSpec, registry: feed.registry, userconfig: temp.file,
+      });
+      let result;
+      try {
+        result = run('npm', args, { timeout: NPM_VIEW_TIMEOUT_MS, capture: true });
+      } catch (e) {
+        throw feedError({ kind: 'view', error: e, feed, versionSpec });
+      }
+      return parseViewedVersion(result.stdout);
+    },
+    /** Install an exact version globally from the feed. */
+    install(version) {
+      const args = buildNpmInstallArgs({
+        packageName: feed.packageName, version, registry: feed.registry, userconfig: temp.file,
+      });
+      try {
+        return run('npm', args, { timeout: NPM_INSTALL_TIMEOUT_MS });
+      } catch (e) {
+        throw feedError({ kind: 'install', error: e, feed, versionSpec: version });
+      }
+    },
+    close() {
+      const removed = cleanup();
+      process.removeListener('exit', onExit);
+      return removed;
+    },
+  };
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 function main(argv) {
@@ -1078,7 +2131,6 @@ function main(argv) {
     console.log(USAGE);
     return EXIT.OK;
   }
-
   const secrets = [];
   const log = (...args) => console.log(...args);
   const run = makeRunner(secrets, { log });
@@ -1087,15 +2139,26 @@ function main(argv) {
   // pinned onto every child process below (backup, init, restart) rather than
   // left to whatever MINIONS_HOME each child happens to inherit. A cutover that
   // backed up one root and synchronized another would look successful and lose
-  // the operator's state.
-  const runtimeRoot = resolveRuntimeRoot();
+  // the operator's state — and a machine where more than one candidate carries
+  // runtime state is refused here rather than resolved by guessing.
+  const rootDecision = resolveAuthoritativeRuntimeRoot({ flag: opts.runtimeRoot });
+  if (rootDecision.ambiguous) {
+    console.error(`\n  REFUSED: ${rootDecision.reason}`);
+    console.error('\n  Nothing was downloaded, uninstalled, or modified.\n');
+    return EXIT.REFUSED;
+  }
+  const runtimeRoot = rootDecision.root;
   const runtimeEnv = { ...process.env, MINIONS_HOME: runtimeRoot };
+  // MINIONS_TEST_DIR outranks MINIONS_HOME in the engine's resolveMinionsHome(),
+  // so an inherited one would silently un-pin every child we just pinned.
+  delete runtimeEnv.MINIONS_TEST_DIR;
   const hasExistingRuntime = fs.existsSync(path.join(runtimeRoot, 'engine.js'));
 
   log(`\n  Internal Minions install`);
   log(`    package:      ${opts.packageName}@${opts.versionSpec}`);
   log(`    registry:     ${opts.registry}`);
   log(`    runtime root: ${runtimeRoot}${hasExistingRuntime ? '' : '  (fresh install)'}`);
+  log(`    pinned via:   ${rootDecision.source} — ${rootDecision.reason}`);
 
   // npm-usability probe only. The authoritative global root and prefix are
   // re-resolved below under the same `--userconfig` the install uses, because a
@@ -1196,12 +2259,7 @@ function main(argv) {
         console.error('  Nothing was uninstalled or modified.\n');
         return EXIT.FAILED;
       }
-      try {
-        const parsed = JSON.parse(viewResult.stdout.trim());
-        targetVersion = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
-      } catch {
-        targetVersion = viewResult.stdout.trim().replace(/^"|"$/g, '');
-      }
+      targetVersion = parseViewedVersion(viewResult.stdout);
       if (!targetVersion) {
         console.error('\n  ERROR: the feed returned no version for that spec. Nothing was modified.\n');
         return EXIT.FAILED;
@@ -1254,7 +2312,15 @@ function main(argv) {
       if (steps.includes('download-artifact')) {
         log(`    npm ${redact(buildNpmPackArgs({ packageName: opts.packageName, version: targetVersion, registry: opts.registry, userconfig: temp.file, destination: '<temp>' }).join(' '), secrets)}`);
       }
-      if (steps.includes('backup-state')) log(`    minions state backup <backup-dir>/state.db`);
+      if (steps.includes('quiesce-services')) {
+        log(`    minions ${CLI_CAPABILITY_PROBE_ARGS.join(' ')}   (capability probe: does this CLI know \`stop --all\`?)`);
+        log(`    minions ${WHOLE_STACK_STOP_ARGS.join(' ')}   (or \`minions ${LEGACY_STOP_ARGS.join(' ')}\` when the probe says it does not)`);
+        log(`    (then wait for engine/state.db-shm to be released)`);
+      }
+      if (steps.includes('backup-state')) {
+        log(`    minions state backup <backup-dir>/state.db`);
+        log(`    (retain) copy engine/state.db{,-wal,-shm} → <backup-dir>/${RETAINED_ORIGINAL_DIR}/`);
+      }
       if (steps.includes('uninstall-public')) log(`    npm ${buildNpmUninstallArgs(PUBLIC_PACKAGE, npmConfig).join(' ')}`);
       if (steps.includes('repair-shims')) {
         log(orphanShims.needsRepair
@@ -1266,7 +2332,9 @@ function main(argv) {
         log(`    (on failure) npm ${buildNpmInstallTarballArgs('<backup-dir>/<package>.tgz').join(' ')}`);
       }
       log(`    minions init --force --skip-start`);
+      if (steps.includes('verify-continuity')) log(`    (verify) summarizeState() before vs after — any regression rolls state back`);
       if (steps.includes('restart')) log(`    minions restart`);
+      log(`    MINIONS_HOME=${runtimeRoot}   (pinned onto every command above; source: ${rootDecision.source})`);
       log('\n  [dry-run] No changes made.\n');
       return EXIT.OK;
     }
@@ -1305,9 +2373,46 @@ function main(argv) {
       log(`    Artifact downloaded: ${path.basename(artifactPath)}`);
     }
 
-    // 4. backup-state ──────────────────────────────────────────────────────
+    // 4. quiesce-services ──────────────────────────────────────────────────
+    // Everything below this line mutates the runtime root or the installed
+    // package, so the engine and dashboard running against the PINNED root are
+    // stopped first and their database handles are proven released. Fails
+    // CLOSED: nothing is backed up, uninstalled, or installed otherwise.
+    const backupCli = resolveBackupCli({
+      npmRootG,
+      runtimeRoot,
+      packageName: opts.packageName,
+      installedInternalVersion,
+      installedPublic,
+    });
+    let servicesStopped = false;
+    if (steps.includes('quiesce-services')) {
+      log(`\n  Quiescing services running against ${runtimeRoot} ...`);
+      const quiescence = quiesceServices({
+        runtimeRoot,
+        cliPath: backupCli.path,
+        run,
+        env: runtimeEnv,
+        log,
+      });
+      if (!quiescence.ok) {
+        console.error(`\n  REFUSED: the runtime did not release engine/state.db — ${quiescence.reason}.`);
+        for (const line of formatQuiescenceRefusal(quiescence)) console.error(line);
+        console.error('  Backing up or replacing the package while the database is open would capture a moving');
+        console.error('  target and rewrite engine code a live daemon is executing.');
+        console.error('  Stop those process(es) (`minions stop --all --wait`, or end the PIDs above) and re-run.');
+        console.error('  Nothing was backed up, uninstalled, or modified.\n');
+        return EXIT.REFUSED;
+      }
+      servicesStopped = quiescence.stopped;
+      log(`    ${quiescence.stopped ? `Services stopped via the ${STOP_PATH_LABELS[quiescence.stopPath]}; ` : ''}${quiescence.reason}.`);
+    }
+
+    // 5. backup-state ──────────────────────────────────────────────────────
     let backupDir = null;
     let backupStatePath = null;
+    let retainedOriginals = { retained: [], missing: [], failed: [] };
+    let preMigrationSummary = null;
     if (steps.includes('backup-state')) {
       const stamp = new Date().toISOString().replace(/[:.]/g, '-');
       backupDir = opts.backupDir
@@ -1339,17 +2444,52 @@ function main(argv) {
           env: runtimeEnv,
         });
         if (!fs.existsSync(backupStatePath)) throw new Error('the backup command reported success but wrote no file');
-        log(`    SQLite state checkpointed and backed up (via ${backup.kind === 'runtime-module' ? 'the runtime\'s own engine/state-operations.js' : backup.cliPath}).`);
+        log(`    SQLite state backed up consistently (via ${backup.kind === 'runtime-module' ? 'the runtime\'s own engine/persistence/state-operations.js' : backup.cliPath}).`);
       } catch (e) {
         backupStatePath = null;
         console.error(`\n  ERROR: state backup failed (${e.message}).`);
         console.error('  Refusing to migrate without a consistent backup. Nothing was uninstalled.\n');
         return EXIT.FAILED;
       }
-      for (const rel of ['config.json', 'routing.md', 'pinned.md']) {
+      for (const rel of BACKUP_COPIED_FILES) {
         const src = path.join(runtimeRoot, rel);
         try { if (fs.existsSync(src)) fs.copyFileSync(src, path.join(backupDir, rel)); } catch { /* best-effort */ }
       }
+      // Retain the ORIGINAL bytes beside the VACUUM snapshot. The snapshot is
+      // the consistent artifact a human restores by hand; these are what an
+      // automatic state-restoring rollback needs to put the runtime back
+      // exactly as it was, WAL included. Neither is ever deleted by this run.
+      retainedOriginals = retainOriginalStateFiles(runtimeRoot, backupDir);
+      if (!retainedOriginals.retained.includes(`${RETAINED_ORIGINAL_DIR}/state.db`)) {
+        const why = retainedOriginals.failed.length
+          ? retainedOriginals.failed.map(f => `${f.rel} (${f.error})`).join('; ')
+          : `engine/state.db was not found under ${runtimeRoot}`;
+        console.error(`\n  ERROR: could not retain the original state files — ${why}.`);
+        console.error('  A state-restoring rollback would be impossible. Nothing was uninstalled.\n');
+        return EXIT.FAILED;
+      }
+      log(`    Original state retained byte-for-byte: ${retainedOriginals.retained.join(', ')}`);
+      // Pre-migration census, read from the BACKUP rather than the live root:
+      // `verifyBackup` opens it read-only, so measuring the baseline can never
+      // mutate, WAL, or lock the state it is vouching for.
+      const censusModule = backup.kind === 'runtime-module'
+        ? backup.modulePath
+        : resolveStateOperationsModule(runtimeRoot);
+      const census = readStateSummary({
+        run,
+        modulePath: censusModule,
+        backupPath: backupStatePath,
+        env: runtimeEnv,
+      });
+      if (census.ok) {
+        preMigrationSummary = census.summary;
+        const rows = Object.values(census.summary.tables).reduce((sum, n) => sum + (Number(n) || 0), 0);
+        log(`    Pre-migration census: schema v${census.summary.schemaVersion}, `
+          + `${Object.keys(census.summary.tables).length} tables, ${rows} rows.`);
+      } else {
+        log(`    WARNING: no pre-migration state census could be taken (${census.error}).`);
+        log('    Continuity verification will be skipped; the preserved-path check still applies.');
+      }
       // Park the artifact beside the backup so the recovery source outlives the
       // temp directory and stays discoverable after the process exits.
       if (artifactPath) {
@@ -1363,25 +2503,41 @@ function main(argv) {
       fs.writeFileSync(path.join(backupDir, 'manifest.json'), `${JSON.stringify({
         createdAt: new Date().toISOString(),
         runtimeRoot,
+        runtimeRootSource: rootDecision.source,
+        runtimeRootReason: rootDecision.reason,
         fromPackage: installedPublic ? PUBLIC_PACKAGE : (installedInternalVersion ? opts.packageName : null),
         fromVersion: installedInternalVersion,
         toPackage: opts.packageName,
         toVersion: targetVersion,
         artifact: artifactPath ? path.basename(artifactPath) : null,
         preservedPaths: preservedBefore,
+        // Everything below is retained, not transient: the artifacts listed here
+        // are never removed by this run under any outcome.
+        retainedArtifacts: [
+          'state.db',
+          ...BACKUP_COPIED_FILES.filter(rel => fs.existsSync(path.join(backupDir, rel))),
+          ...retainedOriginals.retained,
+        ],
+        servicesStopped,
+        preMigrationSummary,
       }, null, 2)}\n`);
       log(`    config/routing/pinned copied; manifest written.`);
       if (artifactPath && backupArtifactParked) log(`    Recovery artifact parked at ${artifactPath}`);
     }
 
-    // 5. uninstall-public ──────────────────────────────────────────────────
+    // 6. uninstall-public ──────────────────────────────────────────────────
     let publicUninstalled = false;
+    // Captured before `sync-init` and reused by the state rollback below, so
+    // the restore path uses the SAME copier as the normal reseed repair.
+    let reseedable = [];
 
     /**
      * Put the previous package back when a failed cutover would otherwise leave
-     * the machine with no `minions` command. Package-scoped ONLY: the state
-     * backup is never restored automatically, so state written before or during
-     * the cutover is neither rolled backward nor deleted.
+     * the machine with no `minions` command. Package-scoped ONLY: on this path
+     * the state backup is never restored, so state written before or during the
+     * cutover is neither rolled backward nor deleted. The state-restoring
+     * rollback below is a separate, narrower path used only when continuity
+     * verification proves state was actually lost.
      */
     const rollbackPackageIfNeeded = () => {
       const decision = assessRollback({
@@ -1418,7 +2574,7 @@ function main(argv) {
       publicUninstalled = true;
     }
 
-    // 6. repair-shims ──────────────────────────────────────────────────────
+    // 7. repair-shims ──────────────────────────────────────────────────────
     // npm has now removed whatever shims it still owned. Anything left under the
     // prefix that names a Minions package with no usable install behind it is an
     // ORPHAN — npm will not overwrite it and aborts the global install with
@@ -1450,7 +2606,7 @@ function main(argv) {
       }
     }
 
-    // 7. install-internal ──────────────────────────────────────────────────
+    // 8. install-internal ──────────────────────────────────────────────────
     if (steps.includes('install-internal')) {
       log(`\n  Installing ${opts.packageName}@${targetVersion} ...`);
       let installed = false;
@@ -1492,7 +2648,7 @@ function main(argv) {
       }
     }
 
-    // 8. verify-install ────────────────────────────────────────────────────
+    // 9. verify-install ────────────────────────────────────────────────────
     const installedNow = readGlobalPackageVersion(npmRootG, opts.packageName);
     if (installedNow !== targetVersion) {
       console.error(`\n  ERROR: expected ${opts.packageName}@${targetVersion} on disk, found ${installedNow || 'nothing'}.`);
@@ -1503,7 +2659,7 @@ function main(argv) {
     }
     log(`  Verified ${opts.packageName}@${installedNow} on disk.`);
 
-    // 9. verify-shim ───────────────────────────────────────────────────────
+    // 10. verify-shim ───────────────────────────────────────────────────────
     // Owning the package directory is not the same as owning the `minions`
     // command: a half-finished cutover can leave the shim wired to the public
     // package while the internal one sits installed and unused.
@@ -1528,13 +2684,13 @@ function main(argv) {
 
     const installedCliPath = path.join(resolveGlobalPackageRoot(npmRootG, opts.packageName), 'bin', 'minions.js');
 
-    // 10. sync-init ────────────────────────────────────────────────────────
+    // 11. sync-init ────────────────────────────────────────────────────────
     // `minions init --force` overwrites every file the package ships, which
     // includes `routing.md` and `knowledge/agents/*.md`. Those are operator- and
     // agent-authored, so their bytes are captured here and put back below: this
     // is a package-channel cutover, and the sync may only ADD newly required
     // files and run the runtime's own idempotent startup migrations.
-    const reseedable = snapshotReseedableFiles(runtimeRoot);
+    reseedable = snapshotReseedableFiles(runtimeRoot);
     log('\n  Synchronizing the runtime root (minions init --force)...');
     try {
       run(process.execPath, [installedCliPath, 'init', '--force', '--skip-start'], {
@@ -1563,7 +2719,148 @@ function main(argv) {
     }
     if (preservedBefore.length) log(`  Preserved: ${preservedBefore.join(', ')}`);
 
-    // 11. restart ──────────────────────────────────────────────────────────
+    // 12. verify-continuity ────────────────────────────────────────────────
+    // The preserved-path check above is presence-only: an emptied
+    // `engine/state.db` passes it. This step re-runs the runtime's OWN
+    // `summarizeState()` against the pinned root, out-of-process, and feeds
+    // both censuses to its `compareStateSummaries`. Any regression, missing
+    // table, or non-empty → empty transition is a hard failure that triggers a
+    // state-restoring rollback.
+
+    /**
+     * Restore the runtime to its pre-migration state and put the previous
+     * package back. Unlike `rollbackPackageIfNeeded`, this IS state-scoped —
+     * it is only reached when continuity verification proved state was lost, so
+     * the retained original bytes are strictly better than what is on disk.
+     *
+     * Idempotent: every step re-copies the same retained bytes, so a re-run
+     * converges on the same result rather than compounding.
+     */
+    const rollbackStateAndPackage = () => {
+      const report = { quiesced: null, state: null, copied: null, reseeded: [], reverified: null, restarted: false };
+      const gate = assessStateRollback({ backupDir, retainedOriginals: retainedOriginals.retained });
+      if (!gate.allowed) {
+        console.error(`  State rollback is not possible: ${gate.reason}.`);
+        rollbackPackageIfNeeded();
+        return report;
+      }
+      console.error(`  ${gate.reason}.`);
+
+      // Nothing may hold the database we are about to overwrite.
+      report.quiesced = quiesceServices({
+        runtimeRoot,
+        cliPath: resolveBackupCli({
+          npmRootG,
+          runtimeRoot,
+          packageName: opts.packageName,
+          installedInternalVersion: readGlobalPackageVersion(npmRootG, opts.packageName),
+          installedPublic: !!readGlobalPackageVersion(npmRootG, PUBLIC_PACKAGE),
+        }).path,
+        run,
+        env: runtimeEnv,
+        log: console.error,
+      });
+      if (!report.quiesced.ok) {
+        console.error(`  ABORTED: ${report.quiesced.reason}. Nothing was restored — your backup is intact at ${backupDir}.`);
+        for (const line of formatQuiescenceRefusal(report.quiesced)) console.error(line);
+        return report;
+      }
+
+      report.state = restoreOriginalStateFiles(runtimeRoot, backupDir);
+      for (const rel of report.state.restored) console.error(`    restored ${rel}`);
+      for (const rel of report.state.removed) console.error(`    removed ${rel} (the original run had none)`);
+      for (const failure of report.state.failed) console.error(`    FAILED ${failure.rel}: ${failure.error}`);
+
+      report.copied = restoreBackupCopiedFiles(runtimeRoot, backupDir);
+      for (const rel of report.copied.restored) console.error(`    restored ${rel}`);
+      for (const failure of report.copied.failed) console.error(`    FAILED ${failure.rel}: ${failure.error}`);
+
+      // Same copier as the normal reseed repair — one implementation, not two.
+      report.reseeded = restoreReseededFiles(runtimeRoot, reseedable);
+      for (const rel of report.reseeded) console.error(`    restored ${rel}`);
+
+      rollbackPackageIfNeeded();
+
+      const restartCli = resolveBackupCli({
+        npmRootG,
+        runtimeRoot,
+        packageName: opts.packageName,
+        installedInternalVersion: readGlobalPackageVersion(npmRootG, opts.packageName),
+        installedPublic: !!readGlobalPackageVersion(npmRootG, PUBLIC_PACKAGE),
+      }).path;
+      if (restartCli && opts.restart) {
+        try {
+          run(process.execPath, [restartCli, 'restart'], { timeout: CLI_RESTART_TIMEOUT_MS, env: runtimeEnv });
+          report.restarted = true;
+          console.error('    engine and dashboard restarted');
+        } catch (e) {
+          console.error(`    could not restart automatically (${e.message}); run \`minions restart\` yourself`);
+        }
+      }
+
+      // Re-verify: the restore is only credible if the census comes back.
+      const after = readStateSummary({
+        run,
+        modulePath: resolveStateOperationsModule(runtimeRoot),
+        env: runtimeEnv,
+      });
+      report.reverified = after.ok
+        ? compareStateContinuity({
+          run,
+          modulePath: resolveStateOperationsModule(runtimeRoot),
+          before: preMigrationSummary,
+          after: after.summary,
+          env: runtimeEnv,
+        })
+        : { ok: false, comparison: null, error: after.error };
+      if (report.reverified.ok && report.reverified.comparison.ok) {
+        console.error('  Rollback verified: the restored state matches the pre-migration census.');
+      } else {
+        console.error(`  Rollback could NOT be verified (${report.reverified.comparison
+          ? describeContinuityFailure(report.reverified.comparison)
+          : report.reverified.error}).`);
+        console.error(`  Restore by hand from ${backupDir}.`);
+      }
+      return report;
+    };
+
+    if (steps.includes('verify-continuity') && preMigrationSummary) {
+      log('\n  Verifying state continuity (row-level census, before vs after)...');
+      const postModule = resolveStateOperationsModule(runtimeRoot);
+      const after = readStateSummary({ run, modulePath: postModule, env: runtimeEnv });
+      const continuity = after.ok
+        ? compareStateContinuity({
+          run,
+          modulePath: postModule,
+          before: preMigrationSummary,
+          after: after.summary,
+          env: runtimeEnv,
+        })
+        : { ok: false, comparison: null, error: after.error };
+      if (!continuity.ok) {
+        // Could not verify is NOT verified — but it is also not proof of loss,
+        // so it warns loudly and leaves the retained originals in place rather
+        // than rolling a healthy runtime backward on missing evidence.
+        log(`  WARNING: state continuity could not be verified (${continuity.error}).`);
+        log(`  The pre-migration state is retained at ${path.join(backupDir, RETAINED_ORIGINAL_DIR)}.`);
+      } else if (!continuity.comparison.ok) {
+        console.error(`\n  ERROR: state was lost during the migration — ${describeContinuityFailure(continuity.comparison)}.`);
+        rollbackStateAndPackage();
+        console.error(`\n  Your pre-migration state remains at ${backupDir} (nothing there is ever deleted).\n`);
+        return EXIT.FAILED;
+      } else {
+        const rows = Object.values(after.summary.tables).reduce((sum, n) => sum + (Number(n) || 0), 0);
+        log(`  Continuity verified: schema v${after.summary.schemaVersion}, `
+          + `${Object.keys(after.summary.tables).length} tables, ${rows} rows; no table regressed.`);
+      }
+    } else if (steps.includes('verify-continuity')) {
+      log('\n  Continuity verification skipped: no pre-migration census was available.');
+    }
+
+    // 13. restart ──────────────────────────────────────────────────────────
+    // Last, and only on state that verify-continuity already proved survived:
+    // the machine is never brought back up on state this run cannot vouch for,
+    // and no post-restart write can be destroyed by a state-restoring rollback.
     if (steps.includes('restart')) {
       log('\n  Restarting engine and dashboard (health-verified)...');
       try {
@@ -1578,14 +2875,19 @@ function main(argv) {
     }
 
     log(`\n  Done. ${opts.packageName}@${installedNow} is installed at ${runtimeRoot}.`);
-    if (backupDir) log(`  Pre-migration backup: ${backupDir}`);
+    if (backupDir) {
+      log(`  Pre-migration backup: ${backupDir}`);
+      if (retainedOriginals.retained.length) {
+        log(`  Original state retained: ${retainedOriginals.retained.join(', ')} (never removed by this installer)`);
+      }
+    }
     log('');
     return EXIT.OK;
   } catch (e) {
     console.error(`\n  ERROR: ${redact(e && e.message ? e.message : String(e), secrets)}\n`);
     return EXIT.FAILED;
   } finally {
-    // 12. cleanup — runs on success and on every failure path, including the
+    // 14. cleanup — runs on success and on every failure path, including the
     // early `return`s above, so the token file never outlives the process. The
     // temp artifact copy goes too; when there was a runtime to back up, the
     // recovery tarball was already parked in the backup directory.
@@ -1609,12 +2911,20 @@ module.exports = {
   EXIT,
   PRESERVED_PATHS,
   INIT_RESEEDABLE_PATHS,
+  STATE_DB_FILES,
+  BACKUP_COPIED_FILES,
+  RETAINED_ORIGINAL_DIR,
+  CONTINUITY_DURABLE_TABLES,
+  resolveContinuityIgnoreTables,
   SHIM_OWNER_PACKAGES,
   STEP_ORDER,
   parseArgs,
   normalizeRegistry,
   registryAuthKey,
   packageScope,
+  INTERNAL_FEED_CHANNELS,
+  resolveInternalFeed,
+  buildScopeRegistryArg,
   buildTokenArgs,
   buildNpmrc,
   buildNpmViewArgs,
@@ -1636,7 +2946,9 @@ module.exports = {
   quoteWindowsArg,
   resolveSpawnTarget,
   redact,
-  resolveRuntimeRoot,
+  resolveAuthoritativeRuntimeRoot,
+  runtimeRootPointerPath,
+  findCheckoutRoot,
   resolveBackupCliCandidates,
   resolveBackupCli,
   resolveBackupStrategy,
@@ -1644,6 +2956,27 @@ module.exports = {
   diffPreservedPaths,
   snapshotReseedableFiles,
   restoreReseededFiles,
+  readServicePids,
+  detectRunningServices,
+  readStateShm,
+  assessDatabaseQuiescence,
+  WHOLE_STACK_STOP_ARGS,
+  LEGACY_STOP_ARGS,
+  CLI_CAPABILITY_PROBE_ARGS,
+  STOP_PATH_LABELS,
+  detectStopCapabilities,
+  probeStopCapability,
+  formatQuiescenceRefusal,
+  quiesceServices,
+  retainOriginalStateFiles,
+  restoreOriginalStateFiles,
+  restoreBackupCopiedFiles,
+  resolveStateOperationsModule,
+  extractEmittedJson,
+  readStateSummary,
+  compareStateContinuity,
+  describeContinuityFailure,
+  assessStateRollback,
   assessRollback,
   countActiveAgents,
   assessAgentActivity,
@@ -1651,6 +2984,11 @@ module.exports = {
   planSteps,
   writeTempNpmrc,
   cleanupTempNpmrc,
+  makeRunner,
+  readUserNpmrc,
+  parseViewedVersion,
+  describeInternalFeedFailure,
+  openInternalFeedSession,
   main,
 };