@yemi33/minions 0.1.2423 → 0.1.2425

package/bin/install-internal-minions.js

@@ -0,0 +1,1209 @@
+#!/usr/bin/env node
+'use strict';
+
+// One-command bootstrap for the internal (ISS ProjectFeed-ISS) Minions channel.
+//
+// Installs or upgrades `@opg-microsoft/minions` from the Azure Artifacts npm
+// registry using the caller's existing `az` login, then synchronizes the
+// existing runtime root with `minions init --force` and a health-verified
+// `minions restart` — preserving config, SQLite state, notes, plans, knowledge,
+// and project links.
+//
+// Deliberately standalone: it must run on a machine that has no Minions
+// installed yet, so it requires nothing from `engine/` and uses Node built-ins
+// 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`).
+//
+// 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
+// on success and on failure. The token never reaches argv, the process
+// environment, stdout, or any file under the runtime root.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// ─── Channel constants ──────────────────────────────────────────────────────
+
+/** 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. */
+const DEFAULT_REGISTRY = 'https://pkgs.dev.azure.com/office/ISS/_packaging/ProjectFeed-ISS/npm/registry/';
+
+const INTERNAL_PACKAGE = '@opg-microsoft/minions';
+const PUBLIC_PACKAGE = '@yemi33/minions';
+
+/** Safe default: the feed's own `latest` dist-tag, resolved to a concrete version before install. */
+const DEFAULT_VERSION_SPEC = 'latest';
+
+const EXIT = { OK: 0, FAILED: 1, USAGE: 2, REFUSED: 3 };
+
+const NPM_VIEW_TIMEOUT_MS = 60000;
+const NPM_PACK_TIMEOUT_MS = 300000;
+const NPM_INSTALL_TIMEOUT_MS = 300000;
+const CLI_INIT_TIMEOUT_MS = 300000;
+const CLI_RESTART_TIMEOUT_MS = 300000;
+const AZ_TOKEN_TIMEOUT_MS = 60000;
+
+// ─── Argument parsing ───────────────────────────────────────────────────────
+
+const USAGE = `
+  Install or upgrade the internal Minions package from the ISS Azure Artifacts feed.
+
+  Usage:
+    node bin/install-internal-minions.js [options]
+    scripts/install-internal-minions.ps1 [options]      (Windows)
+    scripts/install-internal-minions.sh  [options]      (Linux / macOS)
+
+  Options:
+    --version <spec>     Version or dist-tag to install (default: ${DEFAULT_VERSION_SPEC})
+    --registry <url>     Azure Artifacts npm registry (default: the ISS ProjectFeed-ISS feed)
+    --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>)
+    --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)
+    --dry-run            Print the plan and the exact commands, change nothing
+    --help               Show this help
+
+  Prerequisites: Azure CLI (\`az login\`), Node >= 22.5 with npm, and read access to
+  the ProjectFeed-ISS feed. No manually created PAT is required or accepted.
+`;
+
+const BOOLEAN_FLAGS = new Map([
+  ['--keep-public', 'keepPublic'],
+  ['--no-restart', 'restart'],
+  ['--force', 'force'],
+  ['--dry-run', 'dryRun'],
+  ['--help', 'help'],
+  ['-h', 'help'],
+]);
+
+const VALUE_FLAGS = new Map([
+  ['--version', 'versionSpec'],
+  ['--registry', 'registry'],
+  ['--package', 'packageName'],
+  ['--backup-dir', 'backupDir'],
+]);
+
+/**
+ * Parse CLI arguments into an options object. Pure — throws on malformed input
+ * so both the CLI and the tests observe identical validation.
+ */
+function parseArgs(argv) {
+  const opts = {
+    versionSpec: DEFAULT_VERSION_SPEC,
+    registry: DEFAULT_REGISTRY,
+    packageName: INTERNAL_PACKAGE,
+    backupDir: null,
+    keepPublic: false,
+    restart: true,
+    force: false,
+    dryRun: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (BOOLEAN_FLAGS.has(arg)) {
+      const key = BOOLEAN_FLAGS.get(arg);
+      opts[key] = arg === '--no-restart' ? false : true;
+      continue;
+    }
+    if (VALUE_FLAGS.has(arg)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      opts[VALUE_FLAGS.get(arg)] = value;
+      i++;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!opts.versionSpec) throw new Error('--version requires a value');
+  if (!opts.packageName.startsWith('@') || !opts.packageName.includes('/')) {
+    throw new Error(`--package must be a scoped package name, got: ${opts.packageName}`);
+  }
+  opts.registry = normalizeRegistry(opts.registry);
+  return opts;
+}
+
+/** Normalize a registry URL: https only, exactly one trailing slash. */
+function normalizeRegistry(url) {
+  if (!url) throw new Error('registry URL is required');
+  let parsed;
+  try { parsed = new URL(url); } catch { throw new Error(`invalid registry URL: ${url}`); }
+  if (parsed.protocol !== 'https:') throw new Error(`registry URL must use https, got: ${url}`);
+  return `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}/`;
+}
+
+/** The npm auth-config key prefix for a registry (`//host/path/`). */
+function registryAuthKey(registry) {
+  const parsed = new URL(normalizeRegistry(registry));
+  return `//${parsed.host}${parsed.pathname}`;
+}
+
+/** The npm scope key for a scoped package name (`@opg-microsoft`). */
+function packageScope(packageName) {
+  const scope = String(packageName).split('/')[0];
+  if (!scope.startsWith('@')) throw new Error(`not a scoped package name: ${packageName}`);
+  return scope;
+}
+
+// ─── Command construction (pure) ────────────────────────────────────────────
+
+/**
+ * `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.
+ */
+function buildTokenArgs() {
+  return ['account', 'get-access-token', '--resource', ADO_TOKEN_RESOURCE, '--query', 'accessToken', '-o', 'tsv'];
+}
+
+/**
+ * Temporary npm userconfig contents. The token is injected here and nowhere
+ * else. Both the bearer (`_authToken`) and the legacy base64 (`_password`) forms
+ * are emitted because Azure Artifacts accepts either and older npm/registry
+ * combinations only honor the latter.
+ *
+ * `baseConfig` is the caller's existing user npmrc, carried through verbatim so
+ * `prefix`, proxy, and other global-install settings keep applying — replacing
+ * the userconfig wholesale would silently relocate a `-g` install.
+ */
+function buildNpmrc({ registry, scope, token, baseConfig = '' }) {
+  const authKey = registryAuthKey(registry);
+  const lines = [];
+  const base = String(baseConfig || '').trim();
+  if (base) {
+    lines.push('; ── inherited from the caller\'s user npmrc ──', base, '');
+  }
+  lines.push(
+    '; ── added by install-internal-minions (temporary, deleted after the run) ──',
+    `${scope}:registry=${registry}`,
+    `${authKey}:_authToken=${token}`,
+    `${authKey}:username=minions`,
+    `${authKey}:_password=${Buffer.from(String(token), 'utf8').toString('base64')}`,
+    `${authKey}:email=minions@internal.invalid`,
+    '',
+  );
+  return lines.join('\n');
+}
+
+function buildNpmViewArgs({ packageName, versionSpec, registry, userconfig }) {
+  return ['view', `${packageName}@${versionSpec}`, 'version', '--registry', registry, '--userconfig', userconfig, '--json'];
+}
+
+function buildNpmInstallArgs({ packageName, version, registry, userconfig }) {
+  return ['install', '-g', `${packageName}@${version}`, '--registry', registry, '--userconfig', userconfig];
+}
+
+/**
+ * Download the resolved version from the feed as a tarball, without installing
+ * it. This is what makes the cutover safe: the artifact is on local disk before
+ * the public package is removed, so a feed/network/auth failure during the
+ * global install is recoverable offline instead of leaving the machine with no
+ * `minions` at all.
+ */
+function buildNpmPackArgs({ packageName, version, registry, userconfig, destination }) {
+  return [
+    'pack', `${packageName}@${version}`,
+    '--registry', registry,
+    '--userconfig', userconfig,
+    '--pack-destination', destination,
+    '--json',
+  ];
+}
+
+/**
+ * Install from the already-downloaded tarball. Deliberately carries no
+ * `--registry` and no `--userconfig`: the recovery path must not depend on the
+ * feed that just failed.
+ */
+function buildNpmInstallTarballArgs(tarballPath) {
+  return ['install', '-g', tarballPath];
+}
+
+function buildNpmUninstallArgs(packageName) {
+  return ['uninstall', '-g', packageName];
+}
+
+/** Resolve the on-disk root of a globally installed package from `npm root -g`. */
+function resolveGlobalPackageRoot(npmRootG, packageName) {
+  if (!npmRootG) throw new Error('could not resolve the global npm root');
+  return path.join(String(npmRootG).trim(), ...packageName.split('/'));
+}
+
+/**
+ * Locate the tarball `npm pack` just wrote. npm 9+ prints a JSON array with a
+ * `filename`; older npm printed the bare filename. Both are treated as hints and
+ * confirmed against the destination we control — and if neither parses, the
+ * destination directory is scanned, because the artifact's existence is what the
+ * cutover gate depends on, not npm's output format.
+ */
+function resolvePackedTarball(destination, stdout, deps = {}) {
+  const readdir = deps.readdirSync || (p => fs.readdirSync(p));
+  const exists = deps.existsSync || (p => fs.existsSync(p));
+  const hints = [];
+  const text = String(stdout == null ? '' : stdout).trim();
+  if (text) {
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { parsed = null; }
+    if (parsed) {
+      for (const entry of (Array.isArray(parsed) ? parsed : [parsed])) {
+        if (entry && entry.filename) hints.push(String(entry.filename));
+      }
+    } else {
+      for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.endsWith('.tgz')) hints.push(trimmed);
+      }
+    }
+  }
+  for (const hint of hints) {
+    const full = path.join(destination, path.basename(hint));
+    if (exists(full)) return full;
+  }
+  let entries;
+  try { entries = readdir(destination); } catch { return null; }
+  for (const entry of entries) {
+    const name = String(entry && entry.name !== undefined ? entry.name : entry);
+    if (name.endsWith('.tgz')) return path.join(destination, name);
+  }
+  return null;
+}
+
+// ─── `minions` bin shim verification ────────────────────────────────────────
+
+/**
+ * Candidate `minions` shim paths on the global npm prefix. npm writes a
+ * `.cmd`/`.ps1`/sh trio directly under the prefix on Windows and a single
+ * symlink under `<prefix>/bin` everywhere else.
+ */
+function resolveBinShimPaths(npmPrefixG, platform = process.platform) {
+  const prefix = String(npmPrefixG || '').trim();
+  if (!prefix) throw new Error('could not resolve the global npm prefix');
+  if (platform === 'win32') {
+    return [path.join(prefix, 'minions.cmd'), path.join(prefix, 'minions.ps1'), path.join(prefix, 'minions')];
+  }
+  return [path.join(prefix, 'bin', 'minions')];
+}
+
+/**
+ * Does this shim dispatch into `packageName`? The scoped name is discriminating,
+ * so a shim left behind by `@yemi33/minions` cannot pass as `@opg-microsoft/minions`.
+ * A symlink is read through `readlink`; a generated `.cmd`/`.ps1`/sh script is
+ * matched on its body.
+ */
+function shimTargetsPackage({ shimPath, packageName, deps = {} }) {
+  const readlink = deps.readlinkSync || (p => fs.readlinkSync(p));
+  const readFile = deps.readFileSync || (p => fs.readFileSync(p, 'utf8'));
+  const parts = String(packageName).split('/');
+  const fragments = [parts.join('/'), parts.join('\\')];
+  const matches = text => fragments.some(fragment => String(text).includes(fragment));
+  try {
+    if (matches(readlink(shimPath))) return true;
+  } catch { /* not a symlink — fall through to the script body */ }
+  try {
+    return matches(readFile(shimPath));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Prove that the `minions` command a user types now resolves to the internal
+ * package. Installing the package is not the same as owning the shim: an
+ * interrupted or partially rolled-back cutover can leave a working
+ * `@opg-microsoft/minions` on disk while `minions` still runs the public build.
+ */
+function verifyBinShims({ npmPrefixG, packageName, platform = process.platform, deps = {} }) {
+  const exists = deps.existsSync || (p => fs.existsSync(p));
+  const candidates = resolveBinShimPaths(npmPrefixG, platform);
+  const shims = [];
+  for (const shimPath of candidates) {
+    if (!exists(shimPath)) continue;
+    shims.push({
+      path: shimPath,
+      matches: shimTargetsPackage({ shimPath, packageName, deps }),
+      matchesPublic: packageName === PUBLIC_PACKAGE
+        ? false
+        : shimTargetsPackage({ shimPath, packageName: PUBLIC_PACKAGE, deps }),
+    });
+  }
+  if (!shims.length) {
+    return { ok: false, shims, reason: `no \`minions\` shim was found under ${String(npmPrefixG).trim()}` };
+  }
+  const mismatched = shims.filter(shim => !shim.matches);
+  if (mismatched.length) {
+    const stale = mismatched.find(shim => shim.matchesPublic);
+    return {
+      ok: false,
+      shims,
+      reason: stale
+        ? `the \`minions\` shim at ${stale.path} still points at ${PUBLIC_PACKAGE}`
+        : `the \`minions\` shim at ${mismatched[0].path} does not point at ${packageName}`,
+    };
+  }
+  return { ok: true, shims, reason: `\`minions\` resolves to ${packageName} (${shims.map(s => path.basename(s.path)).join(', ')})` };
+}
+
+// ─── Portable spawning ──────────────────────────────────────────────────────
+//
+// On Windows both `npm` and `az` are `.cmd` shims. Node >= 18.20 refuses to
+// spawn `.cmd`/`.bat` without a shell (CVE-2024-27980), and `shell: true` does
+// NOT quote individual arguments — it concatenates them into one command
+// string. So on Windows we quote every argument ourselves before handing the
+// line to cmd.exe. Absolute executables (`process.execPath`) skip the shell
+// entirely on every platform.
+
+/** cmd.exe-safe quoting for a single argument. */
+function quoteWindowsArg(arg) {
+  const value = String(arg);
+  if (value.length && /^[A-Za-z0-9_@:.,=+\-\\/]+$/.test(value)) return value;
+  // Double any backslashes that precede a quote or terminate the string, then
+  // escape embedded quotes — the standard CommandLineToArgvW round-trip.
+  const escaped = value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1');
+  return `"${escaped}"`;
+}
+
+/**
+ * Decide how to invoke a command on the current platform.
+ * Returns `{ command, args, shell }` ready for spawnSync.
+ */
+function resolveSpawnTarget(command, args, platform = process.platform) {
+  if (platform !== 'win32' || path.isAbsolute(command)) {
+    return { command, args, shell: false };
+  }
+  return {
+    command: `${command} ${args.map(quoteWindowsArg).join(' ')}`.trim(),
+    args: [],
+    shell: true,
+  };
+}
+
+// ─── Secret redaction ───────────────────────────────────────────────────────
+
+/**
+ * Strip every known secret from text before it reaches stdout/stderr. Applied to
+ * all child-process output and to error messages, so a failing npm command can
+ * never echo the token back through this script.
+ */
+function redact(text, secrets) {
+  let out = String(text == null ? '' : text);
+  for (const secret of secrets || []) {
+    if (!secret || String(secret).length < 8) continue;
+    const raw = String(secret);
+    out = out.split(raw).join('***REDACTED***');
+    const b64 = Buffer.from(raw, 'utf8').toString('base64');
+    out = out.split(b64).join('***REDACTED***');
+  }
+  return out;
+}
+
+// ─── Runtime-root inspection ────────────────────────────────────────────────
+
+function resolveRuntimeRoot(env = process.env) {
+  return env.MINIONS_HOME ? path.resolve(env.MINIONS_HOME) : path.join(os.homedir(), '.minions');
+}
+
+/**
+ * Resolve the CLI that can run `minions state backup` for the existing runtime.
+ *
+ * `minions init` deliberately excludes `bin` from the runtime-root copy (see the
+ * `excludeTop` set in bin/minions.js), so an installed runtime root has
+ * `engine.js` but NO `bin/minions.js` — the CLI lives in the globally installed
+ * package instead. `<runtimeRoot>/minions.js` IS copied but is the project
+ * launcher and has no `state` command, so it is never a candidate.
+ *
+ * Candidates, first existing one wins:
+ *   1. the internal package, when it is already installed (re-run / upgrade)
+ *   2. the public package, when it is still installed (the normal cutover)
+ *   3. the runtime root itself, so source-checkout runtime roots (which do carry
+ *      bin/) still work
+ *
+ * Pure apart from the injected `exists` probe, so the contract is asserted
+ * directly rather than inferred from a live migration.
+ */
+function resolveBackupCliCandidates({
+  npmRootG = null,
+  runtimeRoot = null,
+  packageName = null,
+  installedInternalVersion = null,
+  installedPublic = false,
+} = {}) {
+  const candidates = [];
+  const pushPackageRoot = (name) => {
+    if (!name) return;
+    try { candidates.push(path.join(resolveGlobalPackageRoot(npmRootG, name), 'bin', 'minions.js')); } catch { /* npm root unresolved */ }
+  };
+  if (installedInternalVersion) pushPackageRoot(packageName);
+  if (installedPublic) pushPackageRoot(PUBLIC_PACKAGE);
+  if (runtimeRoot) candidates.push(path.join(runtimeRoot, 'bin', 'minions.js'));
+  return [...new Set(candidates)];
+}
+
+function resolveBackupCli(state, exists = p => fs.existsSync(p)) {
+  const candidates = resolveBackupCliCandidates(state);
+  return { path: candidates.find(exists) || null, candidates };
+}
+
+/**
+ * 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
+ *      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
+ *      existing global CLI can be present and still have no way to take a backup.
+ *   2. an installed CLI's `minions state backup`, for runtime roots that predate
+ *      the SQL store layout and therefore carry no state-operations module.
+ */
+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 cli = resolveBackupCli(state, exists);
+  const candidates = [modulePath, ...cli.candidates].filter(Boolean);
+  if (modulePath && exists(modulePath)) return { kind: 'runtime-module', modulePath, candidates };
+  if (cli.path) return { kind: 'cli', cliPath: cli.path, candidates };
+  return { kind: 'none', candidates };
+}
+
+/** 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. */
+const PRESERVED_PATHS = [
+  'config.json',
+  'engine/state.db',
+  'notes',
+  'notes.md',
+  'plans',
+  'knowledge',
+  'projects',
+  'pinned.md',
+];
+
+/**
+ * Snapshot which preserved paths exist. Compared before and after migration so
+ * a path that existed beforehand and vanished is a hard failure rather than a
+ * silent data loss.
+ */
+function snapshotPreservedPaths(runtimeRoot, exists = p => fs.existsSync(p)) {
+  const present = [];
+  for (const rel of PRESERVED_PATHS) {
+    if (exists(path.join(runtimeRoot, ...rel.split('/')))) present.push(rel);
+  }
+  return present;
+}
+
+function diffPreservedPaths(before, after) {
+  const afterSet = new Set(after);
+  return before.filter(rel => !afterSet.has(rel));
+}
+
+/**
+ * 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).
+ * Filesystem-based on purpose: it works with the dashboard down, which is
+ * exactly when a migration is most likely to be attempted.
+ */
+function countActiveAgents(runtimeRoot, deps = {}) {
+  const readdir = deps.readdirSync || (p => fs.readdirSync(p, { withFileTypes: true }));
+  const readFile = deps.readFileSync || (p => fs.readFileSync(p, 'utf8'));
+  const isAlive = deps.isAlive || defaultIsAlive;
+  const tmpRoot = path.join(runtimeRoot, 'engine', 'tmp');
+  const pidFiles = [];
+  let entries;
+  try { entries = readdir(tmpRoot); } catch { return 0; }
+  for (const entry of entries) {
+    const full = path.join(tmpRoot, entry.name);
+    if (entry.isDirectory && entry.isDirectory()) {
+      let inner;
+      try { inner = readdir(full); } catch { continue; }
+      for (const child of inner) {
+        const name = child.name !== undefined ? child.name : child;
+        if (String(name).startsWith('pid-') && String(name).endsWith('.pid')) pidFiles.push(path.join(full, name));
+      }
+    } else if (String(entry.name).startsWith('pid-') && String(entry.name).endsWith('.pid')) {
+      pidFiles.push(full);
+    }
+  }
+  let alive = 0;
+  for (const file of pidFiles) {
+    let pid;
+    try { pid = Number(String(readFile(file)).trim()); } catch { continue; }
+    if (Number.isInteger(pid) && pid > 0 && isAlive(pid)) alive++;
+  }
+  return alive;
+}
+
+function defaultIsAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === 'EPERM'; }
+}
+
+/**
+ * Decide whether the disruptive phase (package replacement + `init --force` +
+ * restart) may run. The engine's restart/reattachment contract covers an engine
+ * restart, but it does NOT cover rewriting the runtime `.js` files an active
+ * agent's engine is executing — so active agents block by default.
+ */
+function assessAgentActivity({ activeAgents, force }) {
+  if (activeAgents <= 0) return { allowed: true, activeAgents, reason: 'no active agents' };
+  if (force) {
+    return {
+      allowed: true,
+      activeAgents,
+      reason: `${activeAgents} active agent(s) overridden by --force`,
+      warning: true,
+    };
+  }
+  return {
+    allowed: false,
+    activeAgents,
+    reason: `${activeAgents} agent process(es) are still running; migration deferred`,
+  };
+}
+
+// ─── Migration plan (pure) ──────────────────────────────────────────────────
+
+const STEP_ORDER = [
+  'acquire-token',
+  'validate-feed',
+  'download-artifact',
+  'backup-state',
+  'uninstall-public',
+  'install-internal',
+  'verify-install',
+  'verify-shim',
+  'sync-init',
+  'restart',
+  'cleanup',
+];
+
+/**
+ * Build the ordered migration plan for the detected state.
+ *
+ * The ordering is the safety contract, not a formality:
+ *   - `validate-feed` precedes `backup-state` and `uninstall-public`, so an
+ *     unreachable feed or missing version can never remove a working install.
+ *   - `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.
+ *   - `backup-state` precedes every mutation of the runtime root, and also
+ *     precedes `uninstall-public`, so the cutover never starts without a
+ *     restore point.
+ *   - `uninstall-public` precedes `install-internal` so the two packages never
+ *     race for the same `minions` bin shim.
+ *   - `verify-shim` precedes `sync-init`, so the runtime is only synchronized
+ *     once `minions` actually resolves to the internal package.
+ *   - `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
+ * shim, so the idempotent skip is conditioned on the shim, not on the version
+ * alone. Skipping it while `uninstall-public` is planned would let npm take the
+ * command away with the package it owns and leave nothing to put it back — and
+ * because the next run observes the same version match, the plan would omit the
+ * install again and the machine could never repair itself.
+ */
+function planSteps(state) {
+  const {
+    hasExistingRuntime = false,
+    installedPublic = false,
+    installedInternalVersion = null,
+    targetVersion,
+    keepPublic = false,
+    restart = true,
+    shimOwned = true,
+  } = state || {};
+
+  const willUninstallPublic = !!installedPublic && !keepPublic;
+  const alreadyAtTarget = !!targetVersion
+    && installedInternalVersion === targetVersion
+    && !willUninstallPublic
+    && shimOwned;
+  const skip = new Set();
+  if (!hasExistingRuntime) skip.add('backup-state');
+  if (!willUninstallPublic) skip.add('uninstall-public');
+  if (alreadyAtTarget) {
+    skip.add('install-internal');
+    skip.add('download-artifact');
+  }
+  if (!restart) skip.add('restart');
+
+  return STEP_ORDER.filter(step => !skip.has(step));
+}
+
+/**
+ * Gate the destructive half of the cutover. Removing the global public package
+ * is the only irreversible-feeling step for a user, so it is allowed only when a
+ * usable CLI is guaranteed to be recoverable afterwards:
+ *   - the internal artifact is already downloaded (or the internal package is
+ *     already installed at the target version), and
+ *   - a state backup exists whenever there was a runtime to back up.
+ * Pure, so the contract is asserted directly rather than inferred from logs.
+ */
+function assessCutoverReadiness({
+  artifactReady = false,
+  internalAlreadyInstalled = false,
+  backupRequired = false,
+  backupReady = false,
+} = {}) {
+  if (!artifactReady && !internalAlreadyInstalled) {
+    return { allowed: false, reason: 'the internal package artifact has not been downloaded yet' };
+  }
+  if (backupRequired && !backupReady) {
+    return { allowed: false, reason: 'no state backup exists yet' };
+  }
+  // The reason is echoed verbatim into the operator-facing log, so it reports
+  // what actually happened rather than the most common path.
+  const recoverable = artifactReady
+    ? 'artifact downloaded'
+    : 'the internal package is already installed at the target version';
+  const backup = backupRequired ? 'state backed up' : 'no runtime state to back up';
+  return { allowed: true, reason: `${recoverable}, ${backup}` };
+}
+
+// ─── Process helpers ────────────────────────────────────────────────────────
+
+function makeRunner(secrets, { log = console.log, error = console.error } = {}) {
+  return function run(command, args, { timeout, cwd, capture = false, allowFailure = false, env } = {}) {
+    const target = resolveSpawnTarget(command, args);
+    const result = spawnSync(target.command, target.args, {
+      cwd: cwd || process.cwd(),
+      env: env || process.env,
+      encoding: 'utf8',
+      timeout,
+      windowsHide: true,
+      shell: target.shell,
+      stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'inherit', 'pipe'],
+    });
+    const stderr = redact(result.stderr || '', secrets);
+    const stdout = redact(result.stdout || '', secrets);
+    const ok = !result.error && result.status === 0;
+    if (!ok && !allowFailure) {
+      if (!capture && stderr.trim()) error(stderr.trimEnd());
+      const detail = result.error
+        ? redact(result.error.message, secrets)
+        : `exit code ${result.status}`;
+      const err = new Error(`${command} ${redact(args.join(' '), secrets)} failed (${detail})`);
+      err.stdout = stdout;
+      err.stderr = stderr;
+      throw err;
+    }
+    if (capture && !ok && stderr.trim()) log(stderr.trimEnd());
+    return { ok, stdout, stderr, status: result.status };
+  };
+}
+
+/** Create the 0600 temporary npm userconfig. Returns `{ dir, file }`. */
+function writeTempNpmrc({ registry, scope, token, baseConfig }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'minions-internal-npm-'));
+  const file = path.join(dir, '.npmrc');
+  fs.writeFileSync(file, buildNpmrc({ registry, scope, token, baseConfig }), { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* best-effort on filesystems without POSIX modes */ }
+  return { dir, file };
+}
+
+/** Remove the temporary npm config. Best-effort and idempotent. */
+function cleanupTempNpmrc(dir) {
+  if (!dir) return false;
+  try { fs.rmSync(dir, { recursive: true, force: true }); return true; } catch { return false; }
+}
+
+function readUserNpmrc(env = process.env) {
+  const candidate = env.NPM_CONFIG_USERCONFIG || path.join(os.homedir(), '.npmrc');
+  try { return fs.readFileSync(candidate, 'utf8'); } catch { return ''; }
+}
+
+function readGlobalPackageVersion(npmRootG, packageName) {
+  try {
+    const pkgPath = path.join(resolveGlobalPackageRoot(npmRootG, packageName), 'package.json');
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version || null;
+  } catch { return null; }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    console.error(`\n  ${e.message}`);
+    console.error(USAGE);
+    return EXIT.USAGE;
+  }
+  if (opts.help) {
+    console.log(USAGE);
+    return EXIT.OK;
+  }
+
+  const secrets = [];
+  const log = (...args) => console.log(...args);
+  const run = makeRunner(secrets, { log });
+  const scope = packageScope(opts.packageName);
+  const runtimeRoot = resolveRuntimeRoot();
+  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)'}`);
+
+  let npmRootG = null;
+  try {
+    npmRootG = run('npm', ['root', '-g'], { timeout: NPM_VIEW_TIMEOUT_MS, capture: true }).stdout.trim();
+  } catch (e) {
+    console.error(`\n  ERROR: npm is required but not usable: ${e.message}\n`);
+    return EXIT.FAILED;
+  }
+  const installedInternalVersion = readGlobalPackageVersion(npmRootG, opts.packageName);
+  const installedPublic = !!readGlobalPackageVersion(npmRootG, PUBLIC_PACKAGE);
+
+  // The global bin prefix is where the `minions` shim lives. Resolved up front so
+  // a prefix npm itself cannot report is a warning, not a late failure after the
+  // package is already installed.
+  let npmPrefixG = null;
+  try {
+    npmPrefixG = run('npm', ['prefix', '-g'], { timeout: NPM_VIEW_TIMEOUT_MS, capture: true }).stdout.trim() || null;
+  } catch {
+    npmPrefixG = null;
+  }
+
+  // Agent-activity gate — evaluated before anything is acquired or mutated.
+  const activity = assessAgentActivity({
+    activeAgents: countActiveAgents(runtimeRoot),
+    force: opts.force,
+  });
+  if (!activity.allowed) {
+    console.error(`\n  REFUSED: ${activity.reason}.`);
+    console.error('  Replacing the runtime package rewrites the engine code those agents are executing,');
+    console.error('  which the restart/reattachment contract does not cover.');
+    console.error('  Wait for them to finish (`minions status`), or re-run with --force to override.\n');
+    return EXIT.REFUSED;
+  }
+  if (activity.warning) console.log(`\n  WARNING: ${activity.reason}.`);
+
+  let tempDir = null;
+  let artifactDir = null;
+  let retainArtifact = false;
+  let backupArtifactParked = false;
+  try {
+    // 1. acquire-token ─────────────────────────────────────────────────────
+    let token = '';
+    if (opts.dryRun) {
+      log(`\n  [dry-run] az ${buildTokenArgs().join(' ')}`);
+      token = 'DRY-RUN-PLACEHOLDER-TOKEN';
+    } else {
+      log('\n  Acquiring a short-lived Azure DevOps token via the Azure CLI...');
+      let tokenResult;
+      try {
+        tokenResult = run('az', buildTokenArgs(), { timeout: AZ_TOKEN_TIMEOUT_MS, capture: true });
+      } catch (e) {
+        console.error(`\n  ERROR: could not acquire an Azure DevOps token (${e.message}).`);
+        console.error('  Run `az login` (and `az account set --subscription <id>` if needed) and retry.\n');
+        return EXIT.FAILED;
+      }
+      token = tokenResult.stdout.trim();
+      if (!token) {
+        console.error('\n  ERROR: the Azure CLI returned an empty access token. Run `az login` and retry.\n');
+        return EXIT.FAILED;
+      }
+      secrets.push(token);
+    }
+
+    const temp = writeTempNpmrc({
+      registry: opts.registry,
+      scope,
+      token,
+      baseConfig: readUserNpmrc(),
+    });
+    tempDir = temp.dir;
+    log(`  npm auth staged in a temporary config (removed when this run ends).`);
+
+    // 2. validate-feed ─────────────────────────────────────────────────────
+    const viewArgs = buildNpmViewArgs({
+      packageName: opts.packageName,
+      versionSpec: opts.versionSpec,
+      registry: opts.registry,
+      userconfig: temp.file,
+    });
+    let targetVersion = null;
+    if (opts.dryRun) {
+      log(`  [dry-run] npm ${redact(viewArgs.join(' '), secrets)}`);
+      targetVersion = opts.versionSpec === DEFAULT_VERSION_SPEC ? '<resolved-latest>' : opts.versionSpec;
+    } else {
+      log(`  Validating feed access and resolving ${opts.packageName}@${opts.versionSpec}...`);
+      let viewResult;
+      try {
+        viewResult = run('npm', viewArgs, { timeout: NPM_VIEW_TIMEOUT_MS, capture: true });
+      } catch (e) {
+        console.error(`\n  ERROR: could not read ${opts.packageName}@${opts.versionSpec} from the feed.`);
+        console.error(`  ${e.message}`);
+        console.error('  Confirm you have read access to the feed and that the version exists.');
+        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, '');
+      }
+      if (!targetVersion) {
+        console.error('\n  ERROR: the feed returned no version for that spec. Nothing was modified.\n');
+        return EXIT.FAILED;
+      }
+      log(`  Feed access confirmed; target version ${targetVersion}.`);
+    }
+
+    // Owning the package directory is not the same as owning the `minions`
+    // command. Feeding real shim ownership into the plan is what makes a
+    // half-finished cutover repairable by simply re-running: without it, the
+    // version match alone would skip the one step that re-links the shim.
+    const shimOwned = (npmPrefixG && installedInternalVersion)
+      ? verifyBinShims({ npmPrefixG, packageName: opts.packageName }).ok
+      : true;
+
+    const steps = planSteps({
+      hasExistingRuntime,
+      installedPublic,
+      installedInternalVersion,
+      targetVersion,
+      keepPublic: opts.keepPublic,
+      restart: opts.restart,
+      shimOwned,
+    });
+    log(`\n  Plan: ${steps.join(' → ')}`);
+    if (installedInternalVersion === targetVersion && !steps.includes('install-internal')) {
+      log(`  ${opts.packageName}@${targetVersion} is already installed — install step skipped (idempotent).`);
+    } else if (installedInternalVersion === targetVersion && !shimOwned) {
+      log(`  ${opts.packageName}@${targetVersion} is installed but \`minions\` does not resolve to it — reinstalling to repair the shim.`);
+    }
+
+    if (opts.dryRun) {
+      log('\n  [dry-run] Commands that would run:');
+      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('uninstall-public')) log(`    npm ${buildNpmUninstallArgs(PUBLIC_PACKAGE).join(' ')}`);
+      if (steps.includes('install-internal')) {
+        log(`    npm ${redact(buildNpmInstallArgs({ packageName: opts.packageName, version: targetVersion, registry: opts.registry, userconfig: temp.file }).join(' '), secrets)}`);
+        log(`    (on failure) npm ${buildNpmInstallTarballArgs('<backup-dir>/<package>.tgz').join(' ')}`);
+      }
+      log(`    minions init --force --skip-start`);
+      if (steps.includes('restart')) log(`    minions restart`);
+      log('\n  [dry-run] No changes made.\n');
+      return EXIT.OK;
+    }
+
+    const preservedBefore = snapshotPreservedPaths(runtimeRoot);
+
+    // 3. download-artifact ─────────────────────────────────────────────────
+    // The cutover contract: the tarball is on local disk BEFORE the public
+    // package is removed, so a feed, network, or auth failure during the global
+    // install can be recovered from without the feed.
+    let artifactPath = null;
+    if (steps.includes('download-artifact')) {
+      log(`\n  Downloading ${opts.packageName}@${targetVersion} from the feed...`);
+      artifactDir = fs.mkdtempSync(path.join(os.tmpdir(), 'minions-internal-pkg-'));
+      let packResult;
+      try {
+        packResult = run('npm', buildNpmPackArgs({
+          packageName: opts.packageName,
+          version: targetVersion,
+          registry: opts.registry,
+          userconfig: temp.file,
+          destination: artifactDir,
+        }), { timeout: NPM_PACK_TIMEOUT_MS, capture: true });
+      } catch (e) {
+        console.error(`\n  ERROR: could not download ${opts.packageName}@${targetVersion} from the feed.`);
+        console.error(`  ${e.message}`);
+        console.error('  Nothing was uninstalled or modified.\n');
+        return EXIT.FAILED;
+      }
+      artifactPath = resolvePackedTarball(artifactDir, packResult.stdout);
+      if (!artifactPath) {
+        console.error(`\n  ERROR: npm reported success but no tarball landed in ${artifactDir}.`);
+        console.error('  Refusing to start the cutover without a downloaded artifact. Nothing was modified.\n');
+        return EXIT.FAILED;
+      }
+      log(`    Artifact downloaded: ${path.basename(artifactPath)}`);
+    }
+
+    // 4. backup-state ──────────────────────────────────────────────────────
+    let backupDir = null;
+    let backupStatePath = null;
+    if (steps.includes('backup-state')) {
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+      backupDir = opts.backupDir
+        ? path.resolve(opts.backupDir)
+        : path.join(runtimeRoot, 'backups', `internal-install-${stamp}`);
+      fs.mkdirSync(backupDir, { recursive: true });
+      const backup = resolveBackupStrategy({
+        npmRootG,
+        runtimeRoot,
+        packageName: opts.packageName,
+        installedInternalVersion,
+        installedPublic,
+      });
+      log(`\n  Backing up runtime state to ${backupDir} ...`);
+      if (backup.kind === 'none') {
+        console.error('\n  ERROR: no way to back up the existing runtime state was found.');
+        console.error(`  Looked for: ${backup.candidates.join(', ')}`);
+        console.error('  Refusing to migrate without a consistent backup. Nothing was uninstalled.\n');
+        return EXIT.FAILED;
+      }
+      try {
+        backupStatePath = path.join(backupDir, 'state.db');
+        const [command, args] = backup.kind === 'runtime-module'
+          ? [process.execPath, ['-e', BACKUP_MODULE_SCRIPT, backup.modulePath, backupStatePath]]
+          : [process.execPath, [backup.cliPath, 'state', 'backup', backupStatePath]];
+        run(command, args, {
+          timeout: CLI_INIT_TIMEOUT_MS,
+          capture: true,
+          env: { ...process.env, MINIONS_HOME: runtimeRoot },
+        });
+        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}).`);
+      } 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']) {
+        const src = path.join(runtimeRoot, rel);
+        try { if (fs.existsSync(src)) fs.copyFileSync(src, path.join(backupDir, rel)); } catch { /* best-effort */ }
+      }
+      // Park the artifact beside the backup so the recovery source outlives the
+      // temp directory and stays discoverable after the process exits.
+      if (artifactPath) {
+        try {
+          const parked = path.join(backupDir, path.basename(artifactPath));
+          fs.copyFileSync(artifactPath, parked);
+          artifactPath = parked;
+          backupArtifactParked = true;
+        } catch { /* best-effort — the temp copy is still usable this run */ }
+      }
+      fs.writeFileSync(path.join(backupDir, 'manifest.json'), `${JSON.stringify({
+        createdAt: new Date().toISOString(),
+        runtimeRoot,
+        fromPackage: installedPublic ? PUBLIC_PACKAGE : (installedInternalVersion ? opts.packageName : null),
+        fromVersion: installedInternalVersion,
+        toPackage: opts.packageName,
+        toVersion: targetVersion,
+        artifact: artifactPath ? path.basename(artifactPath) : null,
+        preservedPaths: preservedBefore,
+      }, null, 2)}\n`);
+      log(`    config/routing/pinned copied; manifest written.`);
+      if (artifactPath && backupArtifactParked) log(`    Recovery artifact parked at ${artifactPath}`);
+    }
+
+    // 5. uninstall-public ──────────────────────────────────────────────────
+    if (steps.includes('uninstall-public')) {
+      const readiness = assessCutoverReadiness({
+        artifactReady: !!artifactPath,
+        internalAlreadyInstalled: installedInternalVersion === targetVersion,
+        backupRequired: hasExistingRuntime,
+        backupReady: !!backupStatePath && fs.existsSync(backupStatePath),
+      });
+      if (!readiness.allowed) {
+        console.error(`\n  ERROR: refusing to uninstall ${PUBLIC_PACKAGE} — ${readiness.reason}.`);
+        console.error('  The public package is only removed once a usable CLI is guaranteed to be recoverable.\n');
+        return EXIT.FAILED;
+      }
+      log(`\n  Removing the public ${PUBLIC_PACKAGE} global install (${readiness.reason})...`);
+      run('npm', buildNpmUninstallArgs(PUBLIC_PACKAGE), { timeout: NPM_INSTALL_TIMEOUT_MS, allowFailure: true });
+    }
+
+    // 6. install-internal ──────────────────────────────────────────────────
+    if (steps.includes('install-internal')) {
+      log(`\n  Installing ${opts.packageName}@${targetVersion} ...`);
+      let installed = false;
+      try {
+        run('npm', buildNpmInstallArgs({
+          packageName: opts.packageName,
+          version: targetVersion,
+          registry: opts.registry,
+          userconfig: temp.file,
+        }), { timeout: NPM_INSTALL_TIMEOUT_MS });
+        installed = true;
+      } catch (e) {
+        console.error(`\n  WARNING: the feed install failed (${e.message}).`);
+        // Recovery, not a hint: install the artifact already on disk. It is the
+        // same bytes the feed resolved, and the local install needs neither the
+        // registry nor the token — which is exactly what just failed.
+        if (artifactPath && fs.existsSync(artifactPath)) {
+          log(`  Recovering from the downloaded artifact (${path.basename(artifactPath)})...`);
+          try {
+            run('npm', buildNpmInstallTarballArgs(artifactPath), { timeout: NPM_INSTALL_TIMEOUT_MS });
+            installed = true;
+            log('  Recovered: the CLI was restored from the downloaded artifact.');
+          } catch (recoveryError) {
+            console.error(`  Recovery from the artifact also failed (${recoveryError.message}).`);
+          }
+        }
+      }
+      if (!installed) {
+        retainArtifact = true;
+        console.error(`\n  ERROR: could not install ${opts.packageName}@${targetVersion}.`);
+        if (backupDir) console.error(`  Your state backup is intact at ${backupDir}.`);
+        if (artifactPath) {
+          console.error(`  Retry the offline install yourself with:`);
+          console.error(`    npm ${buildNpmInstallTarballArgs(artifactPath).join(' ')}`);
+        }
+        if (steps.includes('uninstall-public')) {
+          console.error(`  Or fall back to the public package with:`);
+          console.error(`    npm install -g ${PUBLIC_PACKAGE}`);
+        }
+        console.error('');
+        return EXIT.FAILED;
+      }
+    }
+
+    // 7. verify-install ────────────────────────────────────────────────────
+    const installedNow = readGlobalPackageVersion(npmRootG, opts.packageName);
+    if (installedNow !== targetVersion) {
+      console.error(`\n  ERROR: expected ${opts.packageName}@${targetVersion} on disk, found ${installedNow || 'nothing'}.`);
+      console.error('  npm may have resolved a stale metadata cache. Try `npm cache clean --force` and re-run.\n');
+      return EXIT.FAILED;
+    }
+    log(`  Verified ${opts.packageName}@${installedNow} on disk.`);
+
+    // 8. 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.
+    if (npmPrefixG) {
+      const shimCheck = verifyBinShims({ npmPrefixG, packageName: opts.packageName });
+      if (!shimCheck.ok) {
+        retainArtifact = true;
+        console.error(`\n  ERROR: ${shimCheck.reason}.`);
+        console.error(`  ${opts.packageName}@${installedNow} is installed, but \`minions\` does not run it.`);
+        console.error(`  Repair the shim with:`);
+        console.error(`    npm uninstall -g ${PUBLIC_PACKAGE}`);
+        if (artifactPath) console.error(`    npm ${buildNpmInstallTarballArgs(artifactPath).join(' ')}`);
+        if (backupDir) console.error(`  Your state backup is intact at ${backupDir}.`);
+        console.error('');
+        return EXIT.FAILED;
+      }
+      log(`  Verified ${shimCheck.reason}.`);
+    } else {
+      log('  WARNING: npm did not report a global prefix; the `minions` shim could not be verified.');
+    }
+
+    const installedCliPath = path.join(resolveGlobalPackageRoot(npmRootG, opts.packageName), 'bin', 'minions.js');
+
+    // 9. sync-init ─────────────────────────────────────────────────────────
+    log('\n  Synchronizing the runtime root (minions init --force)...');
+    try {
+      run(process.execPath, [installedCliPath, 'init', '--force', '--skip-start'], { timeout: CLI_INIT_TIMEOUT_MS });
+    } catch (e) {
+      console.error(`\n  ERROR: runtime synchronization failed (${e.message}).`);
+      console.error(`  The package is installed. Finish manually with:`);
+      console.error(`    minions init --force`);
+      console.error(`    minions restart\n`);
+      return EXIT.FAILED;
+    }
+
+    const preservedAfter = snapshotPreservedPaths(runtimeRoot);
+    const lost = diffPreservedPaths(preservedBefore, preservedAfter);
+    if (lost.length) {
+      console.error(`\n  ERROR: these runtime paths existed before migration and are now missing: ${lost.join(', ')}`);
+      if (backupDir) console.error(`  Restore from ${backupDir} before continuing.\n`);
+      return EXIT.FAILED;
+    }
+    if (preservedBefore.length) log(`  Preserved: ${preservedBefore.join(', ')}`);
+
+    // 10. restart ──────────────────────────────────────────────────────────
+    if (steps.includes('restart')) {
+      log('\n  Restarting engine and dashboard (health-verified)...');
+      try {
+        run(process.execPath, [installedCliPath, 'restart'], { timeout: CLI_RESTART_TIMEOUT_MS });
+      } catch (e) {
+        console.error(`\n  ERROR: restart failed (${e.message}).`);
+        console.error('  The package and runtime files are up to date; run `minions restart` to finish.\n');
+        return EXIT.FAILED;
+      }
+    } else {
+      log('\n  Restart skipped (--no-restart). Run `minions restart` when ready.');
+    }
+
+    log(`\n  Done. ${opts.packageName}@${installedNow} is installed at ${runtimeRoot}.`);
+    if (backupDir) log(`  Pre-migration backup: ${backupDir}`);
+    log('');
+    return EXIT.OK;
+  } catch (e) {
+    console.error(`\n  ERROR: ${redact(e && e.message ? e.message : String(e), secrets)}\n`);
+    return EXIT.FAILED;
+  } finally {
+    // 11. 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.
+    cleanupTempNpmrc(tempDir);
+    // The artifact is kept only when the run left the machine needing it and the
+    // backup directory did not already receive a copy.
+    if (retainArtifact && artifactDir && !backupArtifactParked) {
+      console.error(`  Recovery artifact retained at ${artifactDir}\n`);
+    } else {
+      cleanupTempNpmrc(artifactDir);
+    }
+  }
+}
+
+module.exports = {
+  ADO_TOKEN_RESOURCE,
+  DEFAULT_REGISTRY,
+  DEFAULT_VERSION_SPEC,
+  INTERNAL_PACKAGE,
+  PUBLIC_PACKAGE,
+  EXIT,
+  PRESERVED_PATHS,
+  STEP_ORDER,
+  parseArgs,
+  normalizeRegistry,
+  registryAuthKey,
+  packageScope,
+  buildTokenArgs,
+  buildNpmrc,
+  buildNpmViewArgs,
+  buildNpmInstallArgs,
+  buildNpmPackArgs,
+  buildNpmInstallTarballArgs,
+  buildNpmUninstallArgs,
+  resolveGlobalPackageRoot,
+  resolvePackedTarball,
+  resolveBinShimPaths,
+  shimTargetsPackage,
+  verifyBinShims,
+  quoteWindowsArg,
+  resolveSpawnTarget,
+  redact,
+  resolveRuntimeRoot,
+  resolveBackupCliCandidates,
+  resolveBackupCli,
+  resolveBackupStrategy,
+  snapshotPreservedPaths,
+  diffPreservedPaths,
+  countActiveAgents,
+  assessAgentActivity,
+  assessCutoverReadiness,
+  planSteps,
+  writeTempNpmrc,
+  cleanupTempNpmrc,
+  main,
+};
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}