@yemi33/minions 0.1.2445 → 0.1.2447

package/bin/install-internal-minions.js

@@ -227,8 +227,42 @@ function buildNpmInstallTarballArgs(tarballPath) {
   return ['install', '-g', tarballPath];
 }
 
-function buildNpmUninstallArgs(packageName) {
-  return ['uninstall', '-g', packageName];
+function buildNpmUninstallArgs(packageName, { userconfig = null } = {}) {
+  const args = ['uninstall', '-g', packageName];
+  if (userconfig) args.push('--userconfig', userconfig);
+  return args;
+}
+
+/**
+ * Reinstall a package from whatever registry the caller's own npm config points
+ * at. This is the rollback path: it deliberately carries no `--registry`,
+ * because the package being restored is the one that was already there and the
+ * internal feed is exactly what may have just failed.
+ */
+function buildNpmRestoreArgs(packageName, { userconfig = null } = {}) {
+  const args = ['install', '-g', packageName];
+  if (userconfig) args.push('--userconfig', userconfig);
+  return args;
+}
+
+const NPM_GLOBAL_PATH_KINDS = new Set(['root', 'prefix']);
+
+/**
+ * `npm root -g` / `npm prefix -g` under an explicit config file.
+ *
+ * Both answers are prefix-sensitive, and a custom prefix (the reported customer
+ * install uses `C:\.tools\.npm-global`) usually comes from an npmrc rather than
+ * from a flag. Resolving them under the SAME `--userconfig` the install uses is
+ * what stops the probe and the install from disagreeing about which prefix owns
+ * the `minions` shim we are about to inspect, clear, and recreate.
+ */
+function buildNpmGlobalPathArgs(kind, { userconfig = null } = {}) {
+  if (!NPM_GLOBAL_PATH_KINDS.has(kind)) {
+    throw new Error(`npm global path kind must be "root" or "prefix", got: ${kind}`);
+  }
+  const args = [kind, '-g'];
+  if (userconfig) args.push('--userconfig', userconfig);
+  return args;
 }
 
 /** Resolve the on-disk root of a globally installed package from `npm root -g`. */
@@ -292,6 +326,24 @@ function resolveBinShimPaths(npmPrefixG, platform = process.platform) {
   return [path.join(prefix, 'bin', 'minions')];
 }
 
+/**
+ * Does a `minions` shim occupy this path? Deliberately `lstat`, never
+ * `existsSync`: `existsSync` stats THROUGH a symlink and answers `false` for a
+ * dangling one — which is precisely the orphan we are hunting, npm's
+ * `<prefix>/bin/minions` link outliving the package directory it pointed into.
+ * That link still makes `npm install -g` abort with EEXIST, so "the target is
+ * gone" must never read as "the path is free".
+ */
+function shimPathPresent(shimPath, deps = {}) {
+  const lstat = deps.lstatSync || (p => fs.lstatSync(p));
+  try {
+    lstat(shimPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 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`.
@@ -325,9 +377,13 @@ function verifyBinShims({ npmPrefixG, packageName, platform = process.platform,
   const candidates = resolveBinShimPaths(npmPrefixG, platform);
   const shims = [];
   for (const shimPath of candidates) {
-    if (!exists(shimPath)) continue;
+    if (!shimPathPresent(shimPath, deps)) continue;
     shims.push({
       path: shimPath,
+      // `exists` follows the link on purpose here: the question is whether the
+      // command a user types can actually run, so a shim whose target is gone
+      // is broken no matter which package its link names.
+      broken: !exists(shimPath),
       matches: shimTargetsPackage({ shimPath, packageName, deps }),
       matchesPublic: packageName === PUBLIC_PACKAGE
         ? false
@@ -337,6 +393,14 @@ function verifyBinShims({ npmPrefixG, packageName, platform = process.platform,
   if (!shims.length) {
     return { ok: false, shims, reason: `no \`minions\` shim was found under ${String(npmPrefixG).trim()}` };
   }
+  const broken = shims.find(shim => shim.broken);
+  if (broken) {
+    return {
+      ok: false,
+      shims,
+      reason: `the \`minions\` shim at ${broken.path} is a broken link — its target no longer exists`,
+    };
+  }
   const mismatched = shims.filter(shim => !shim.matches);
   if (mismatched.length) {
     const stale = mismatched.find(shim => shim.matchesPublic);
@@ -351,7 +415,167 @@ function verifyBinShims({ npmPrefixG, packageName, platform = process.platform,
   return { ok: true, shims, reason: `\`minions\` resolves to ${packageName} (${shims.map(s => path.basename(s.path)).join(', ')})` };
 }
 
-// ─── Portable spawning ──────────────────────────────────────────────────────
+// ─── Orphaned `minions` shim repair ─────────────────────────────────────────
+//
+// npm refuses to overwrite a bin shim it does not currently own and aborts the
+// whole global install with EEXIST. A prior `npm uninstall -g` that was
+// interrupted — or any half-finished public→internal migration — can remove
+// `<npm root -g>/<package>` while leaving the `minions` trio under
+// `npm prefix -g`. `readGlobalPackageVersion` then reports nothing installed,
+// the run looks like a fresh install, and `npm install -g` dies on the leftover.
+//
+// The repair is ownership-safe by construction: a shim is only ever removed
+// when its body (or symlink target) names a package this installer owns AND
+// that package is no longer usable on disk. Anything else — a colleague's
+// script, a wrapper, an unreadable file — blocks the run with the exact path to
+// resolve rather than being deleted.
+
+/** Package names whose generated `minions` shim this installer may remove. */
+const SHIM_OWNER_PACKAGES = [INTERNAL_PACKAGE, PUBLIC_PACKAGE];
+
+/**
+ * Is a globally installed package still usable — package.json present AND every
+ * executable it declares in `bin` still on disk?
+ *
+ * "Present" is not enough. An interrupted uninstall can leave the package
+ * directory behind with its `bin/` already reaped, and a shim dispatching into
+ * that is exactly as broken as one pointing at nothing.
+ */
+function isGlobalPackageUsable(npmRootG, packageName, deps = {}) {
+  const exists = deps.existsSync || (p => fs.existsSync(p));
+  const readFile = deps.readFileSync || (p => fs.readFileSync(p, 'utf8'));
+  if (!String(npmRootG == null ? '' : npmRootG).trim()) return false;
+  let root;
+  try { root = resolveGlobalPackageRoot(npmRootG, packageName); } catch { return false; }
+  let manifest;
+  try { manifest = JSON.parse(readFile(path.join(root, 'package.json'))); } catch { return false; }
+  const bin = manifest && manifest.bin;
+  const targets = typeof bin === 'string'
+    ? [bin]
+    : (bin && typeof bin === 'object' ? Object.values(bin).filter(v => typeof v === 'string') : []);
+  if (!targets.length) return exists(root);
+  return targets.every(rel => exists(path.join(root, ...String(rel).split('/'))));
+}
+
+/**
+ * Inspect every platform-specific `minions` shim under the exact prefix the
+ * install will use and decide what — if anything — has to be cleared first.
+ *
+ * Returns `{ needsRepair, blocked, remove, shims, reason }`:
+ *   - `blocked`   an existing `minions` file could not be attributed to a
+ *                 package we own. Nothing is scheduled for deletion and the
+ *                 caller must refuse; `reason` names the exact path.
+ *   - `needsRepair` at least one shim is orphaned or stale. `remove` is the
+ *                 COMPLETE npm-generated set that exists (the Windows
+ *                 `.cmd`/`.ps1`/sh trio is written and rewritten as a unit, so
+ *                 leaving a sibling behind just moves the EEXIST).
+ *
+ * An unresolvable prefix or root is a skip, never a refusal and never a
+ * deletion: without both we cannot tell a shim from an unrelated file.
+ */
+function assessOrphanShims({
+  npmPrefixG,
+  npmRootG,
+  packageNames = SHIM_OWNER_PACKAGES,
+  platform = process.platform,
+  deps = {},
+} = {}) {
+  const prefix = String(npmPrefixG == null ? '' : npmPrefixG).trim();
+  const root = String(npmRootG == null ? '' : npmRootG).trim();
+  const owners = (packageNames && packageNames.length ? packageNames : SHIM_OWNER_PACKAGES);
+  const skip = reason => ({ needsRepair: false, blocked: false, remove: [], shims: [], reason });
+
+  if (!prefix || !root) {
+    return skip('npm did not report both a global prefix and a global root; shim repair skipped');
+  }
+  let candidates;
+  try { candidates = resolveBinShimPaths(prefix, platform); } catch { return skip('the global npm prefix could not be resolved; shim repair skipped'); }
+
+  const shims = [];
+  for (const shimPath of candidates) {
+    if (!shimPathPresent(shimPath, deps)) continue;
+    const owner = owners.find(name => shimTargetsPackage({ shimPath, packageName: name, deps })) || null;
+    shims.push({ path: shimPath, owner, usable: owner ? isGlobalPackageUsable(root, owner, deps) : false });
+  }
+  if (!shims.length) {
+    return { needsRepair: false, blocked: false, remove: [], shims, reason: `no \`minions\` shim exists under ${prefix}` };
+  }
+
+  // Ownership first, and wholesale: a prefix holding one unattributable
+  // `minions` file is not a prefix we are willing to partially clear.
+  const unprovable = shims.filter(shim => !shim.owner);
+  if (unprovable.length) {
+    return {
+      needsRepair: false,
+      blocked: true,
+      remove: [],
+      shims,
+      reason: `${unprovable.map(s => s.path).join(', ')} is named \`minions\` but was not generated by npm for `
+        + `${owners.join(' or ')}; refusing to delete a file this installer does not own. `
+        + 'Move or rename it (or remove it yourself if it is a leftover) and re-run.',
+    };
+  }
+
+  const orphans = shims.filter(shim => !shim.usable);
+  if (!orphans.length) {
+    return {
+      needsRepair: false,
+      blocked: false,
+      remove: [],
+      shims,
+      reason: `every \`minions\` shim under ${prefix} is backed by an installed package`,
+    };
+  }
+  const staleOwners = [...new Set(orphans.map(shim => shim.owner))];
+  return {
+    needsRepair: true,
+    blocked: false,
+    remove: shims.map(shim => shim.path),
+    shims,
+    reason: `${orphans.length} \`minions\` shim(s) under ${prefix} still dispatch into ${staleOwners.join(', ')}, `
+      + 'which is no longer installed; clearing the npm-generated set so `npm install -g` can recreate it',
+  };
+}
+
+/**
+ * Delete the shims `assessOrphanShims` scheduled. Idempotent — a path that is
+ * already gone is not a failure, so re-running a partially completed repair
+ * converges instead of erroring.
+ *
+ * `unlink` first, not `rm`: `fs.rmSync(p, { force: true })` decides "already
+ * absent" with a symlink-following existence check, so it returns success
+ * WITHOUT clearing a dangling link — the one case this repair exists for.
+ * `rm` stays as the fallback for whatever unlink refuses. Every removal is then
+ * re-probed, because a delete that silently no-ops must be reported as a
+ * failure the caller can act on rather than as a cleared path npm will still
+ * abort on.
+ */
+function removeOrphanShims(paths, deps = {}) {
+  const unlink = deps.unlinkSync || (p => fs.unlinkSync(p));
+  const remove = deps.rmSync || ((p, options) => fs.rmSync(p, options));
+  const removed = [];
+  const failed = [];
+  for (const target of paths || []) {
+    if (!shimPathPresent(target, deps)) continue;
+    try {
+      try {
+        unlink(target);
+      } catch (e) {
+        if (e && e.code === 'ENOENT') continue;
+        remove(target, { force: true });
+      }
+      if (shimPathPresent(target, deps)) {
+        throw new Error('the delete reported success but the path still exists');
+      }
+      removed.push(target);
+    } catch (e) {
+      failed.push({ path: target, error: e && e.message ? e.message : String(e) });
+    }
+  }
+  return { removed, failed };
+}
+
+
 //
 // 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
@@ -507,6 +731,96 @@ function diffPreservedPaths(before, after) {
   return before.filter(rel => !afterSet.has(rel));
 }
 
+/**
+ * Runtime paths that the PACKAGE ships and `minions init --force` therefore
+ * rewrites with package defaults (`bin/minions.js#copyDir` force-overwrites
+ * every shipped file except `config.json`), yet whose installed contents are
+ * operator- or agent-authored:
+ *
+ *   - `routing.md`          the operator's work-type → agent routing table
+ *   - `knowledge/agents/`   per-agent memory written by engine/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
+ * required files and run schema migrations while existing content survives.
+ */
+const INIT_RESEEDABLE_PATHS = ['routing.md', 'knowledge/agents'];
+
+/**
+ * Read the current bytes of every reseedable file under a runtime root.
+ * Returns `[{ rel, contents }]` — a list, not a tree, so restoring is a plain
+ * write per entry with no directory reconciliation.
+ */
+function snapshotReseedableFiles(runtimeRoot, deps = {}) {
+  const exists = deps.existsSync || (p => fs.existsSync(p));
+  const stat = deps.statSync || (p => fs.statSync(p));
+  const readdir = deps.readdirSync || (p => fs.readdirSync(p));
+  const readFile = deps.readFileSync || (p => fs.readFileSync(p));
+  const snapshot = [];
+  const visit = (rel) => {
+    const full = path.join(runtimeRoot, ...rel.split('/'));
+    if (!exists(full)) return;
+    let info;
+    try { info = stat(full); } catch { return; }
+    if (info.isDirectory()) {
+      let entries;
+      try { entries = readdir(full); } catch { return; }
+      for (const entry of entries) visit(`${rel}/${String(entry && entry.name !== undefined ? entry.name : entry)}`);
+      return;
+    }
+    try { snapshot.push({ rel, contents: readFile(full) }); } catch { /* unreadable — nothing to restore */ }
+  };
+  for (const rel of INIT_RESEEDABLE_PATHS) visit(rel);
+  return snapshot;
+}
+
+/**
+ * Put back every snapshotted file whose bytes the sync replaced or removed.
+ * Returns the relative paths actually restored, so the operator sees exactly
+ * what the package tried to reseed.
+ */
+function restoreReseededFiles(runtimeRoot, snapshot, deps = {}) {
+  const readFile = deps.readFileSync || (p => fs.readFileSync(p));
+  const writeFile = deps.writeFileSync || ((p, data) => fs.writeFileSync(p, data));
+  const mkdir = deps.mkdirSync || ((p, options) => fs.mkdirSync(p, options));
+  const restored = [];
+  for (const entry of snapshot || []) {
+    const full = path.join(runtimeRoot, ...entry.rel.split('/'));
+    let current = null;
+    try { current = readFile(full); } catch { current = null; }
+    if (current && Buffer.isBuffer(current) && Buffer.from(entry.contents).equals(current)) continue;
+    try {
+      mkdir(path.dirname(full), { recursive: true });
+      writeFile(full, entry.contents);
+      restored.push(entry.rel);
+    } catch { /* best-effort; the pre-migration backup is still the fallback */ }
+  }
+  return restored;
+}
+
+/**
+ * Decide whether a failed cutover must put the previously installed package
+ * back so the machine is not left with no `minions` command at all.
+ *
+ * Deliberately PACKAGE-scoped. User state is never rolled backward: the
+ * pre-migration backup exists for a human to reach for, and state created
+ * before or during the cutover (work items, dispatches, PR records) must
+ * survive a failed package swap untouched.
+ */
+function assessRollback({ publicUninstalled = false, internalUsable = false } = {}) {
+  if (!publicUninstalled) {
+    return { needed: false, reason: 'no previously installed package was removed' };
+  }
+  if (internalUsable) {
+    return { needed: false, reason: `${INTERNAL_PACKAGE} is installed and owns the \`minions\` command` };
+  }
+  return {
+    needed: true,
+    packageName: PUBLIC_PACKAGE,
+    reason: `${PUBLIC_PACKAGE} was removed and the cutover did not leave a usable \`minions\` command`,
+  };
+}
+
 /**
  * Count live agent processes by walking the dispatch PID files the engine
  * writes under `<runtime root>/engine/tmp/` — both the per-dispatch directory
@@ -579,6 +893,7 @@ const STEP_ORDER = [
   'download-artifact',
   'backup-state',
   'uninstall-public',
+  'repair-shims',
   'install-internal',
   'verify-install',
   'verify-shim',
@@ -601,6 +916,11 @@ const STEP_ORDER = [
  *     restore point.
  *   - `uninstall-public` precedes `install-internal` so the two packages never
  *     race for the same `minions` bin shim.
+ *   - `repair-shims` sits between them: npm removes the shims it still owns
+ *     during `uninstall-public`, so whatever survives to this point is an
+ *     orphan, and clearing it is what keeps `install-internal` from aborting
+ *     with EEXIST. It runs after `backup-state`, so nothing is ever deleted
+ *     before a restore point exists.
  *   - `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`.
@@ -634,6 +954,9 @@ function planSteps(state) {
   if (alreadyAtTarget) {
     skip.add('install-internal');
     skip.add('download-artifact');
+    // No install means no shim for the install to recreate, so there is nothing
+    // to make room for — and nothing this run is entitled to delete.
+    skip.add('repair-shims');
   }
   if (!restart) skip.add('restart');
 
@@ -729,6 +1052,17 @@ function readGlobalPackageVersion(npmRootG, packageName) {
   } catch { return null; }
 }
 
+/**
+ * Ask npm for its global root or prefix under an explicit config. Returns null
+ * rather than throwing: a prefix npm cannot report downgrades the shim work to
+ * a skipped, non-destructive warning instead of failing the migration.
+ */
+function resolveNpmGlobalPath(run, kind, config) {
+  try {
+    return run('npm', buildNpmGlobalPathArgs(kind, config), { timeout: NPM_VIEW_TIMEOUT_MS, capture: true }).stdout.trim() || null;
+  } catch { return null; }
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 function main(argv) {
@@ -749,7 +1083,13 @@ function main(argv) {
   const log = (...args) => console.log(...args);
   const run = makeRunner(secrets, { log });
   const scope = packageScope(opts.packageName);
+  // The runtime root is resolved ONCE, before any package is touched, and is
+  // 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();
+  const runtimeEnv = { ...process.env, MINIONS_HOME: runtimeRoot };
   const hasExistingRuntime = fs.existsSync(path.join(runtimeRoot, 'engine.js'));
 
   log(`\n  Internal Minions install`);
@@ -757,25 +1097,16 @@ function main(argv) {
   log(`    registry:     ${opts.registry}`);
   log(`    runtime root: ${runtimeRoot}${hasExistingRuntime ? '' : '  (fresh install)'}`);
 
+  // npm-usability probe only. The authoritative global root and prefix are
+  // re-resolved below under the same `--userconfig` the install uses, because a
+  // custom prefix (e.g. `C:\.tools\.npm-global`) normally comes from an npmrc.
   let npmRootG = null;
   try {
-    npmRootG = run('npm', ['root', '-g'], { timeout: NPM_VIEW_TIMEOUT_MS, capture: true }).stdout.trim();
+    npmRootG = run('npm', buildNpmGlobalPathArgs('root'), { 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({
@@ -828,6 +1159,20 @@ function main(argv) {
     tempDir = temp.dir;
     log(`  npm auth staged in a temporary config (removed when this run ends).`);
 
+    // From here on every prefix-sensitive npm command — root, prefix, uninstall,
+    // install, and the shim cleanup that reads the prefix — resolves through the
+    // SAME config file. A custom global prefix (the reported install uses
+    // `C:\.tools\.npm-global`) normally comes from an npmrc, so without this the
+    // probe could read one config while the install honored another, and the
+    // shim we inspected would not be the shim npm collides with.
+    const npmConfig = { userconfig: temp.file };
+    const resolvedRoot = resolveNpmGlobalPath(run, 'root', npmConfig);
+    if (resolvedRoot) npmRootG = resolvedRoot;
+    const npmPrefixG = resolveNpmGlobalPath(run, 'prefix', npmConfig);
+
+    const installedInternalVersion = readGlobalPackageVersion(npmRootG, opts.packageName);
+    const installedPublic = !!readGlobalPackageVersion(npmRootG, PUBLIC_PACKAGE);
+
     // 2. validate-feed ─────────────────────────────────────────────────────
     const viewArgs = buildNpmViewArgs({
       packageName: opts.packageName,
@@ -882,6 +1227,22 @@ function main(argv) {
       shimOwned,
     });
     log(`\n  Plan: ${steps.join(' → ')}`);
+
+    // Orphaned-shim gate. Evaluated BEFORE anything is downloaded, backed up, or
+    // uninstalled so an unattributable `minions` file refuses the run up front
+    // instead of surfacing halfway through a cutover — and so the reported
+    // EEXIST is caught here rather than by npm.
+    let orphanShims = { needsRepair: false, blocked: false, remove: [], reason: 'shim repair is not part of this plan' };
+    if (steps.includes('repair-shims')) {
+      orphanShims = assessOrphanShims({ npmPrefixG, npmRootG, packageNames: SHIM_OWNER_PACKAGES });
+      if (orphanShims.blocked) {
+        console.error(`\n  REFUSED: ${orphanShims.reason}`);
+        console.error('  Nothing was downloaded, uninstalled, or modified.\n');
+        return EXIT.REFUSED;
+      }
+      if (orphanShims.needsRepair) log(`  Orphaned shims detected: ${orphanShims.remove.join(', ')}`);
+    }
+
     if (installedInternalVersion === targetVersion && !steps.includes('install-internal')) {
       log(`  ${opts.packageName}@${targetVersion} is already installed — install step skipped (idempotent).`);
     } else if (installedInternalVersion === targetVersion && !shimOwned) {
@@ -894,7 +1255,12 @@ function main(argv) {
         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('uninstall-public')) log(`    npm ${buildNpmUninstallArgs(PUBLIC_PACKAGE, npmConfig).join(' ')}`);
+      if (steps.includes('repair-shims')) {
+        log(orphanShims.needsRepair
+          ? `    (repair) remove orphaned shims: ${orphanShims.remove.join(', ')}`
+          : `    (repair) no orphaned \`minions\` shim to clear`);
+      }
       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(' ')}`);
@@ -970,7 +1336,7 @@ function main(argv) {
         run(command, args, {
           timeout: CLI_INIT_TIMEOUT_MS,
           capture: true,
-          env: { ...process.env, MINIONS_HOME: runtimeRoot },
+          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}).`);
@@ -1009,6 +1375,32 @@ function main(argv) {
     }
 
     // 5. uninstall-public ──────────────────────────────────────────────────
+    let publicUninstalled = false;
+
+    /**
+     * 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.
+     */
+    const rollbackPackageIfNeeded = () => {
+      const decision = assessRollback({
+        publicUninstalled,
+        internalUsable: isGlobalPackageUsable(npmRootG, opts.packageName)
+          && (!npmPrefixG || verifyBinShims({ npmPrefixG, packageName: opts.packageName }).ok),
+      });
+      if (!decision.needed) return;
+      console.error(`\n  Rolling back the package cutover: ${decision.reason}.`);
+      console.error(`  Restoring ${decision.packageName} so \`minions\` works again. Your runtime state is untouched.`);
+      try {
+        run('npm', buildNpmRestoreArgs(decision.packageName, npmConfig), { timeout: NPM_INSTALL_TIMEOUT_MS });
+        console.error(`  Restored ${decision.packageName}.`);
+      } catch (e) {
+        console.error(`  Could not restore ${decision.packageName} automatically (${e.message}).`);
+        console.error(`  Run this yourself: npm ${buildNpmRestoreArgs(decision.packageName).join(' ')}`);
+      }
+    };
+
     if (steps.includes('uninstall-public')) {
       const readiness = assessCutoverReadiness({
         artifactReady: !!artifactPath,
@@ -1022,10 +1414,43 @@ function main(argv) {
         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 });
+      run('npm', buildNpmUninstallArgs(PUBLIC_PACKAGE, npmConfig), { timeout: NPM_INSTALL_TIMEOUT_MS, allowFailure: true });
+      publicUninstalled = true;
     }
 
-    // 6. install-internal ──────────────────────────────────────────────────
+    // 6. 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
+    // EEXIST. Re-assessed here (not reused from the gate above) because the
+    // uninstall that just ran is exactly what changes the answer.
+    if (steps.includes('repair-shims')) {
+      const repair = assessOrphanShims({ npmPrefixG, npmRootG, packageNames: SHIM_OWNER_PACKAGES });
+      if (repair.blocked) {
+        console.error(`\n  REFUSED: ${repair.reason}`);
+        if (backupDir) console.error(`  Your state backup is intact at ${backupDir}.`);
+        rollbackPackageIfNeeded();
+        console.error('');
+        return EXIT.REFUSED;
+      }
+      if (repair.needsRepair) {
+        log(`\n  Clearing orphaned \`minions\` shims — ${repair.reason}.`);
+        const removal = removeOrphanShims(repair.remove);
+        for (const cleared of removal.removed) log(`    removed ${cleared}`);
+        if (removal.failed.length) {
+          console.error(`\n  ERROR: could not remove ${removal.failed.map(f => `${f.path} (${f.error})`).join('; ')}.`);
+          console.error('  `npm install -g` would abort with EEXIST on it. Remove the file(s) manually and re-run.');
+          if (backupDir) console.error(`  Your state backup is intact at ${backupDir}.`);
+          rollbackPackageIfNeeded();
+          console.error('');
+          return EXIT.FAILED;
+        }
+      } else {
+        log(`\n  Shim check: ${repair.reason}.`);
+      }
+    }
+
+    // 7. install-internal ──────────────────────────────────────────────────
     if (steps.includes('install-internal')) {
       log(`\n  Installing ${opts.packageName}@${targetVersion} ...`);
       let installed = false;
@@ -1061,25 +1486,24 @@ function main(argv) {
           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}`);
-        }
+        rollbackPackageIfNeeded();
         console.error('');
         return EXIT.FAILED;
       }
     }
 
-    // 7. verify-install ────────────────────────────────────────────────────
+    // 8. 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');
+      console.error('  npm may have resolved a stale metadata cache. Try `npm cache clean --force` and re-run.');
+      rollbackPackageIfNeeded();
+      console.error('');
       return EXIT.FAILED;
     }
     log(`  Verified ${opts.packageName}@${installedNow} on disk.`);
 
-    // 8. verify-shim ───────────────────────────────────────────────────────
+    // 9. 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.
@@ -1090,9 +1514,10 @@ function main(argv) {
         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}`);
+        console.error(`    npm ${buildNpmUninstallArgs(PUBLIC_PACKAGE).join(' ')}`);
         if (artifactPath) console.error(`    npm ${buildNpmInstallTarballArgs(artifactPath).join(' ')}`);
         if (backupDir) console.error(`  Your state backup is intact at ${backupDir}.`);
+        rollbackPackageIfNeeded();
         console.error('');
         return EXIT.FAILED;
       }
@@ -1103,18 +1528,32 @@ function main(argv) {
 
     const installedCliPath = path.join(resolveGlobalPackageRoot(npmRootG, opts.packageName), 'bin', 'minions.js');
 
-    // 9. sync-init ─────────────────────────────────────────────────────────
+    // 10. 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);
     log('\n  Synchronizing the runtime root (minions init --force)...');
     try {
-      run(process.execPath, [installedCliPath, 'init', '--force', '--skip-start'], { timeout: CLI_INIT_TIMEOUT_MS });
+      run(process.execPath, [installedCliPath, 'init', '--force', '--skip-start'], {
+        timeout: CLI_INIT_TIMEOUT_MS,
+        env: runtimeEnv,
+      });
     } 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`);
+      console.error(`    minions restart`);
+      rollbackPackageIfNeeded();
+      console.error('');
       return EXIT.FAILED;
     }
 
+    const reseeded = restoreReseededFiles(runtimeRoot, reseedable);
+    if (reseeded.length) log(`  Restored operator-authored files the sync reseeded: ${reseeded.join(', ')}`);
+
     const preservedAfter = snapshotPreservedPaths(runtimeRoot);
     const lost = diffPreservedPaths(preservedBefore, preservedAfter);
     if (lost.length) {
@@ -1124,11 +1563,11 @@ function main(argv) {
     }
     if (preservedBefore.length) log(`  Preserved: ${preservedBefore.join(', ')}`);
 
-    // 10. restart ──────────────────────────────────────────────────────────
+    // 11. restart ──────────────────────────────────────────────────────────
     if (steps.includes('restart')) {
       log('\n  Restarting engine and dashboard (health-verified)...');
       try {
-        run(process.execPath, [installedCliPath, 'restart'], { timeout: CLI_RESTART_TIMEOUT_MS });
+        run(process.execPath, [installedCliPath, 'restart'], { timeout: CLI_RESTART_TIMEOUT_MS, env: runtimeEnv });
       } 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');
@@ -1146,7 +1585,7 @@ function main(argv) {
     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
+    // 12. 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.
@@ -1169,6 +1608,8 @@ module.exports = {
   PUBLIC_PACKAGE,
   EXIT,
   PRESERVED_PATHS,
+  INIT_RESEEDABLE_PATHS,
+  SHIM_OWNER_PACKAGES,
   STEP_ORDER,
   parseArgs,
   normalizeRegistry,
@@ -1181,11 +1622,17 @@ module.exports = {
   buildNpmPackArgs,
   buildNpmInstallTarballArgs,
   buildNpmUninstallArgs,
+  buildNpmRestoreArgs,
+  buildNpmGlobalPathArgs,
   resolveGlobalPackageRoot,
   resolvePackedTarball,
   resolveBinShimPaths,
+  shimPathPresent,
   shimTargetsPackage,
   verifyBinShims,
+  isGlobalPackageUsable,
+  assessOrphanShims,
+  removeOrphanShims,
   quoteWindowsArg,
   resolveSpawnTarget,
   redact,
@@ -1195,6 +1642,9 @@ module.exports = {
   resolveBackupStrategy,
   snapshotPreservedPaths,
   diffPreservedPaths,
+  snapshotReseedableFiles,
+  restoreReseededFiles,
+  assessRollback,
   countActiveAgents,
   assessAgentActivity,
   assessCutoverReadiness,

package/dashboard.js

@@ -101,6 +101,7 @@ const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, getKnowledgeBaseEntriesSnapshot, getProjectGitStatus, timeSince,
   MINIONS_DIR, AGENTS_DIR, ENGINE_DIR, INBOX_DIR, PRD_DIR } = queries;
 const apiContracts = require('./engine/api-contracts');
+const listPaging = require('./engine/api-contracts/paging');
 
 // Dev vs binary differentiation. When two dashboards run side-by-side (npm
 // install on 7331, local checkout on 7332), the favicon and title need to
@@ -3384,7 +3385,11 @@ async function _maxInputMtimeMs(inputs) {
 // cross-scope display order is post-enrichment (central + every project by
 // rowid), which per-scope SQL LIMIT/OFFSET cannot compose, and (c) slicing the
 // deterministic cached array is O(page) to serialize — the real transfer win.
-const _LIST_PAGE_MAX = 1000;
+// The bounds come from engine/api-contracts/paging.js — the SAME constants the
+// route catalog publishes on GET /api/routes, so the clamp and the advertised
+// contract can never drift (review of PR #1062).
+const _LIST_PAGE_MAX = listPaging.LIST_PAGE_MAX_LIMIT;
+const _LIST_PAGE_DEFAULT_LIMIT = listPaging.LIST_PAGE_DEFAULT_LIMIT;
 function _parsePageParams(req) {
   const params = new URL((req && req.url) || '/', 'http://localhost').searchParams;
   const hasLimit = params.has('limit');
@@ -3394,7 +3399,7 @@ function _parsePageParams(req) {
   const rawOffset = Number(params.get('offset'));
   const limit = hasLimit && Number.isFinite(rawLimit)
     ? Math.max(1, Math.min(_LIST_PAGE_MAX, Math.floor(rawLimit)))
-    : 50;
+    : _LIST_PAGE_DEFAULT_LIMIT;
   const offset = hasOffset && Number.isFinite(rawOffset) ? Math.max(0, Math.floor(rawOffset)) : 0;
   return { limit, offset };
 }
@@ -9164,14 +9169,23 @@ const server = http.createServer(async (req, res) => {
   }
 
   async function handlePlansList(req, res) {
+    let page;
     try {
-      planPrdValidation.validateNoQuery(req);
+      // Only the optional limit/offset paging params are accepted; every other
+      // query param is still rejected with the canonical 400, and the error
+      // blames the REJECTED param rather than the accepted paging one
+      // (W-ms3ovk83000rb60f). _parsePageParams returns null on the legacy
+      // no-param path so the response stays byte-identical to legacy then.
+      planPrdValidation.validateNoQuery(req, { allow: listPaging.LIST_PAGING_PARAMS });
+      page = _parsePageParams(req);
     } catch (e) {
       return apiErrorReply(res, e, req);
     }
     const now = Date.now();
     if (_plansCache && (now - _plansCacheTs) < PLANS_CACHE_TTL_MS) {
-      return jsonReply(res, 200, _plansCache);
+      // Keep caching the full array and slice per-request AFTER the cache read
+      // so paging never corrupts the cache and `total` reflects the full set.
+      return jsonReply(res, 200, page ? _paginateList(_plansCache, page) : _plansCache);
     }
     const fsp = fs.promises;
     // W-mrffmjaf002f08f0 — PRD JSON is SQL-authoritative (engine/prd-store.js);
@@ -9325,7 +9339,7 @@ const server = http.createServer(async (req, res) => {
     plans.sort((a, b) => (b.generatedAt || '').localeCompare(a.generatedAt || ''));
     _plansCache = plans;
     _plansCacheTs = Date.now();
-    return jsonReply(res, 200, plans);
+    return jsonReply(res, 200, page ? _paginateList(plans, page) : plans);
   }
 
   async function handlePlansArchiveRead(req, res, match) {
@@ -12551,7 +12565,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   // ── Watches API Handlers ─────────────────────────────────────────────────
 
   async function handleWatchesList(req, res) {
-    return jsonReply(res, 200, { watches: watchesMod.getWatches() });
+    const all = watchesMod.getWatches();
+    // Optional progressive-load paging (W-ms3ovk83000rb60f). With no paging
+    // params the response is byte-identical to the legacy `{ watches: [...] }`
+    // shape; when a param is present we slice the SAME array and keep the
+    // `watches` key (mapped from _paginateList's `items`) so existing consumers
+    // keep working, adding total/hasMore/offset/limit alongside it.
+    const page = _parsePageParams(req);
+    if (!page) return jsonReply(res, 200, { watches: all });
+    const { items, total, offset, limit, hasMore } = _paginateList(all, page);
+    return jsonReply(res, 200, { watches: items, total, hasMore, offset, limit });
   }
 
   async function handleWatchesTargetTypes(req, res) {
@@ -14829,10 +14852,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         },
       });
     }},
-    { method: 'GET', path: '/api/schedules', desc: 'Schedule definitions merged with SQL schedule-run state (_lastRun/_lastResult/_lastCompletedAt)', handler: (req, res) => {
+    { method: 'GET', path: '/api/schedules', desc: 'Schedule definitions merged with SQL schedule-run state (_lastRun/_lastResult/_lastCompletedAt). Optional ?limit=&offset= returns a { items, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the full array is byte-identical to legacy.', handler: (req, res) => {
+      const page = _parsePageParams(req);
       return serveFreshJson(req, res, {
         tag: 'schedules',
         inputs: [CONFIG_PATH],
+        variant: page ? ('p' + page.offset + '.' + page.limit) : '',
+        transform: page ? (list) => _paginateList(list, page) : null,
         builder: () => {
           // Read config.json directly via queries.getConfig() rather than
           // calling reloadConfig() — the latter cascades into
@@ -14857,12 +14883,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         },
       });
     }},
-    { method: 'GET', path: '/api/pipelines', desc: 'Pipeline definitions merged with last-5 SQL-backed runs', handler: (req, res) => {
+    { method: 'GET', path: '/api/pipelines', desc: 'Pipeline definitions merged with last-5 SQL-backed runs. Optional ?limit=&offset= returns a { items, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the full array is byte-identical to legacy.', handler: (req, res) => {
+      const page = _parsePageParams(req);
       return serveFreshJson(req, res, {
         tag: 'pipelines',
         inputs: [
           path.join(MINIONS_DIR, 'pipelines'),
         ],
+        variant: page ? ('p' + page.offset + '.' + page.limit) : '',
+        transform: page ? (list) => _paginateList(list, page) : null,
         builder: () => {
           try {
             const pl = require('./engine/pipeline');
@@ -15100,7 +15129,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Plans
     { method: 'POST', path: '/api/plan', desc: 'Create a plan work item that chains to PRD on completion', params: `title, description?, ${WORK_ITEM_PRIORITY_PARAM_HINT}, project? (string OR array for cross-repo plans), agent?, branch_strategy? or branchStrategy?`, handler: handlePlanCreate },
-    { method: 'GET', path: '/api/plans', desc: 'List plan files (.md drafts + .json PRDs)', handler: handlePlansList },
+    { method: 'GET', path: '/api/plans', desc: 'List plan files (.md drafts + .json PRDs). Optional ?limit=&offset= returns a { items, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the full array is byte-identical to legacy.', handler: handlePlansList },
     { method: 'POST', path: '/api/plans/trigger-verify', desc: 'Manually trigger verification for a completed plan', params: 'file', handler: handlePlansTriggerVerify },
     { method: 'POST', path: '/api/plans/approve', desc: 'Approve a plan for execution', params: 'file, approvedBy?, forceRegen?, skipRegen?', handler: handlePlansApprove },
     { method: 'POST', path: '/api/plans/pause', desc: 'Pause a plan (stops materialization + resets active items)', params: 'file', handler: handlePlansPause },
@@ -15996,7 +16025,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/schedules/run-now', desc: 'Manually enqueue the work item for a schedule', params: 'id', handler: handleSchedulesRunNow },
 
     // Watches
-    { method: 'GET', path: '/api/watches', desc: 'List all watches', handler: handleWatchesList },
+    { method: 'GET', path: '/api/watches', desc: 'List all watches. Optional ?limit=&offset= returns a wrapped { watches, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the response is byte-identical to legacy { watches: [...] }.', handler: handleWatchesList },
     { method: 'GET', path: '/api/watches/target-types', desc: 'List registered watch target types and their valid conditions', handler: handleWatchesTargetTypes },
     { method: 'GET', path: '/api/watches/action-types', desc: 'List registered follow-up action types (notify, dispatch-work-item, webhook, ...)', handler: handleWatchesActionTypes },
     { method: 'GET', path: /^\/api\/watches\/([\w-]+)\/history$/, template: '/api/watches/:id/history', desc: 'Read the persisted evaluation history (last 25 checks) for a watch', handler: handleWatchHistory },

package/docs/internal-install.md

@@ -97,7 +97,25 @@ by `test/unit/install-internal-minions.test.js`.
    (or already installed at the target version) *and* a state backup exists
    whenever there was a runtime to back up. Skipped with `--keep-public`, or when
    no public install is present.
-6. **`install-internal`** — `npm install -g <package>@<resolved-version>` against the
+6. **`repair-shims`** — clears **orphaned** `minions` shims under `npm prefix -g`.
+   `npm uninstall -g` has just removed the shims it still owned, so anything left
+   under the prefix that dispatches into `@yemi33/minions` or
+   `@opg-microsoft/minions` with no usable package behind it is a leftover from a
+   prior uninstall or an interrupted migration. npm refuses to overwrite a shim it
+   does not own and aborts the whole global install with `EEXIST`, so the complete
+   npm-generated set is cleared here and `install-internal` recreates it. Ownership
+   must be *proven* — a shim is removed only when its body or symlink target names
+   one of those packages **and** that package's declared `bin` is no longer on
+   disk. An unrelated file named `minions` refuses the run (exit `3`) with its
+   exact path instead of being deleted, and an npm that reports no prefix or root
+   skips the repair entirely rather than guessing. `npm --force` is never used.
+   Shims are detected with `lstat`, not an existence check: on Linux and macOS
+   the orphan is usually a **dangling** `<prefix>/bin/minions` symlink whose
+   target went with the package, and a symlink-following check reports that
+   directory entry as absent while npm still aborts on it. Each deletion is
+   re-probed afterwards, so a delete that quietly no-ops is reported as a
+   failure with its path rather than as a cleared shim.
+7. **`install-internal`** — `npm install -g <package>@<resolved-version>` against the
    feed. **If that fails, the script installs the already-downloaded tarball**
    (`npm install -g <backup-dir>/<package>.tgz` — no registry, no token, so it
    still works when the feed is exactly what failed) rather than leaving the
@@ -107,29 +125,65 @@ by `test/unit/install-internal-minions.test.js`.
    `uninstall-public` is planned. `npm uninstall -g` takes the shim with the
    package that owns it, so skipping the install alongside an uninstall would
    remove the command with nothing to restore it.
-7. **`verify-install`** — re-reads the installed `package.json` from disk and fails
+8. **`verify-install`** — re-reads the installed `package.json` from disk and fails
    loudly if npm did not actually land the resolved version.
-8. **`verify-shim`** — resolves the global npm prefix and proves the `minions`
+9. **`verify-shim`** — resolves the global npm prefix and proves the `minions`
    command itself dispatches into the internal package (`minions.cmd` /
    `minions.ps1` / the sh shim on Windows, the `<prefix>/bin/minions` symlink
    elsewhere). Owning the package directory is not the same as owning the
    command: a half-finished cutover can leave `@opg-microsoft/minions` installed
    while `minions` still runs the public build. A shim still pointing at
-   `@yemi33/minions` is a hard failure with the repair commands printed.
-9. **`sync-init`** — `minions init --force --skip-start`, the supported runtime
-   synchronization. It overwrites `.js`/`.html` runtime files and preserves
-   user-modified `.md` files.
-10. **`restart`** — `minions restart`, which is health-verified
+   `@yemi33/minions` is a hard failure with the repair commands printed, and so
+   is a shim whose link target no longer exists — naming the right package is
+   not the same as being able to run it.
+10. **`sync-init`** — `minions init --force --skip-start`, the supported runtime
+    synchronization. It overwrites `.js`/`.html` runtime files and adds files the
+    new version requires. `--force` would otherwise also rewrite the shipped
+    `routing.md` and `knowledge/agents/*.md` with package defaults, so the
+    installer snapshots those before the sync and puts them back after it.
+11. **`restart`** — `minions restart`, which is health-verified
     (`engine/restart-health.js`: PID + HTTP probe). Skipped with `--no-restart`.
-11. **`cleanup`** — always runs, on success and on every failure path. The
+12. **`cleanup`** — always runs, on success and on every failure path. The
     temporary npm config always goes; the downloaded artifact is retained (and its
     path printed) when the run ended with the machine still needing it.
 
+Every prefix-sensitive npm command — `root -g`, `prefix -g`, `uninstall -g`,
+`install -g`, and the shim inspection between them — runs against the **same**
+`--userconfig`, so a custom global prefix (for example
+`C:\.tools\.npm-global`, which usually comes from an `.npmrc` rather than a flag)
+cannot be honoured by the install and ignored by the probe.
+
 After `sync-init` the script re-checks every runtime path that existed
 beforehand (`config.json`, `engine/state.db`, `notes/`, `notes.md`, `plans/`,
 `knowledge/`, `projects/`, `pinned.md`). A path that existed before and is
 missing after is a hard failure pointing at the backup, not a silent data loss.
 
+## What this is not
+
+This is a **package-channel cutover**: it swaps the globally installed npm
+package and leaves your runtime where it is. It is **not** a reset, not a
+reinitialization, not an import/export migration, and it does not create a fresh
+Minions home.
+
+The runtime root is resolved **once**, before any package is touched
+(`MINIONS_HOME`, otherwise `~/.minions`), and that exact path is pinned onto the
+backup, the `init --force` sync, the verification, the restart, and any rollback.
+Every one of the following survives a successful run, a failed run, a rollback,
+and a re-run:
+
+| State | Preserved how |
+|---|---|
+| `engine/state.db` — work items, dispatches, PR records, schedules, pipelines, watches, meetings, PRDs, QA state, small state | Never replaced. Checkpointed to the backup directory (`PRAGMA wal_checkpoint(TRUNCATE)` + `VACUUM INTO`) before the package changes; the **live** database stays in place and the new version runs its own idempotent startup migrations against it. |
+| `config.json` | `minions init` never overwrites it (`neverOverwrite` in `bin/minions.js`), and it is copied into the backup directory as well. |
+| `routing.md`, `knowledge/agents/*.md` | Shipped by the package, so `init --force` *would* rewrite them. Snapshotted before `sync-init` and restored byte-for-byte after it. |
+| `notes.md`, `notes/`, `pinned.md`, `plans/`, `prd/`, `projects/`, `agents/` | Not shipped by the package, so the sync never touches them. Existence is re-verified after the sync. |
+
+The backup exists for **recovery only**. A failed install, verification, sync, or
+shim check restores the *previous package* so `minions` keeps working — it never
+restores state, never rolls your state backward, and never deletes state written
+before or during the cutover.
+
+
 ## Token handling
 
 - The ADO token is acquired **per run** and is short-lived.
@@ -169,6 +223,11 @@ the temporary npm config is removed either way.
 Re-running is also the **repair** path: if a previous run left the internal
 package on disk while `minions` still resolved elsewhere (or nowhere), the plan
 reinstates `download-artifact` + `install-internal` so the shim is re-linked.
+And if a previous run was interrupted between `npm uninstall -g` and
+`npm install -g` — leaving `minions` / `minions.cmd` / `minions.ps1` behind with
+no package to back them — `repair-shims` clears the orphans so the next run
+converges instead of dying on `EEXIST`. See
+[Orphaned `minions` shims](#orphaned-minions-shims-eexist).
 
 ## Relationship to `minions update`
 
@@ -203,7 +262,46 @@ the internal package on a machine that has no Minions at all.
 | `refusing to uninstall @yemi33/minions — …` | The artifact or the backup is missing | Nothing was removed. Re-run; the message names which precondition failed. |
 | `no way to back up the existing runtime state was found` | The runtime root has neither `engine/state-operations.js` nor a resolvable CLI | Nothing was uninstalled. The error lists every path that was probed; run `minions init --force` against the existing install to restore its engine files, then re-run. |
 | `the minions shim … still points at @yemi33/minions` | A previous half-finished cutover left the public shim in place | `npm uninstall -g @yemi33/minions`, then re-run. The install commands are printed with the error. |
-| Feed install failed after the public package was removed | Feed/network failure mid-install | Handled automatically — the script reinstalls from the tarball it downloaded before the uninstall. If that also fails, the retained artifact path and the offline `npm install -g <tarball>` command are printed. |
+| `npm ERR! EEXIST … <prefix>\minions` on `npm install -g` | **Orphaned shim** — a prior uninstall or interrupted migration removed the package directory but left the `minions` command behind, so nothing reported the old package as installed and npm refused to overwrite the leftover. | Handled automatically by `repair-shims`: just re-run the installer. Details below. |
+| `REFUSED: … is named minions but was not generated by npm for …` | A file called `minions` under `npm prefix -g` could not be attributed to `@yemi33/minions` or `@opg-microsoft/minions` | The installer never deletes a file it cannot prove it owns. Inspect the named path, move or rename it (or remove it yourself if it is a leftover), then re-run. Nothing was modified. |
+| Feed install failed after the public package was removed | Feed/network failure mid-install | Handled automatically — the script reinstalls from the tarball it downloaded before the uninstall. If that also fails, the retained artifact path and the offline `npm install -g <tarball>` command are printed, and the previous package is restored so `minions` keeps working. Your state is untouched. |
+
+### Orphaned `minions` shims (`EEXIST`)
+
+The reported failure, from a Windows install whose npm global prefix is
+`C:\.tools\.npm-global`:
+
+```
+npm error code EEXIST
+npm error path C:\.tools\.npm-global\minions
+npm error EEXIST: file already exists
+```
+
+`<npm root -g>\@yemi33\minions` had already been removed, but the shim trio
+`minions`, `minions.cmd`, and `minions.ps1` was still sitting under
+`npm prefix -g`. With no package metadata left to read, the installer saw nothing
+installed, planned no `uninstall-public`, and npm collided with the leftover.
+
+Inspect the state yourself with:
+
+```powershell
+npm prefix -g
+Get-ChildItem (npm prefix -g) -Filter 'minions*'
+Get-ChildItem (Join-Path (npm root -g) '@yemi33'), (Join-Path (npm root -g) '@opg-microsoft') -ErrorAction SilentlyContinue
+```
+
+```bash
+ls -l "$(npm prefix -g)/bin/minions"
+ls -d "$(npm root -g)"/@yemi33/minions "$(npm root -g)"/@opg-microsoft/minions 2>/dev/null
+```
+
+Re-running the installer is the fix — `repair-shims` clears the complete
+npm-generated set so the install can recreate it. Nothing else about your install
+is touched: the repair runs **after** the state backup, removes only files it has
+proven npm generated for a Minions package that is no longer usable, and refuses
+the run (exit `3`, nothing modified) rather than deleting an unrelated `minions`
+executable. Your runtime state is never involved — see
+[What this is not](#what-this-is-not).
 
 ## See also
 

package/engine/api-contracts/orchestration.js

@@ -4,6 +4,23 @@ const keepProcesses = require('../keep-process-sweep');
 const managedSpawn = require('../managed-spawn');
 const managedSpecNameMax = managedSpawn.validateManagedSpecName('x').maxLength;
 const agentApiValidation = require('../agent-api-validation');
+const paging = require('./paging');
+
+// The optional progressive-load paging window is the ONLY caller-supplied input
+// these list endpoints read; unknown params are ignored (not rejected) because
+// they never reach a validator.
+function pagedListContract() {
+  return {
+    audit: 'audited',
+    query: paging.listPagingQuery(
+      'Optional progressive-load paging window; any other query parameter is ignored, not rejected.',
+    ),
+    constraints: [
+      ...paging.listPagingClampConstraints(),
+      { kind: 'ignores-unknown-query-params', location: 'query' },
+    ],
+  };
+}
 
 function absentOrEmptyOperatorBody() {
   return {
@@ -74,9 +91,12 @@ module.exports = {
   ],
   overrides: {
     'GET /api/keep-processes': { noInput: true },
-    'GET /api/schedules': { noInput: true },
-    'GET /api/pipelines': { noInput: true },
-    'GET /api/watches': { noInput: true },
+    // These three consume the optional ?limit=&offset= paging window
+    // (W-ms3ovk83000rb60f) — they are NOT input-less, so the catalog must publish
+    // the real parameters instead of certifying them noInput.
+    'GET /api/schedules': pagedListContract(),
+    'GET /api/pipelines': pagedListContract(),
+    'GET /api/watches': pagedListContract(),
     'GET /api/watches/target-types': { noInput: true },
     'GET /api/watches/action-types': { noInput: true },
     'GET /api/watches/<id>/history': {

package/engine/api-contracts/paging.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// Single source of truth for the OPTIONAL progressive-load paging query surface
+// (`?limit=&offset=`) shared by the large list endpoints.
+//
+// dashboard.js's `_parsePageParams` clamps incoming values with these bounds and
+// the api-contract owner modules publish the same bounds on `GET /api/routes`,
+// so the runtime behavior and the advertised contract cannot drift. Adding
+// paging to another list endpoint means declaring `listPagingQuery()` on its
+// contract — otherwise the route keeps certifying itself input-less while
+// silently consuming caller input (review of PR #1062).
+
+const LIST_PAGE_MAX_LIMIT = 1000;
+const LIST_PAGE_DEFAULT_LIMIT = 50;
+const LIST_PAGING_PARAMS = Object.freeze(['limit', 'offset']);
+
+function listPagingQueryFields() {
+  return [
+    {
+      name: 'limit',
+      type: 'integer',
+      required: false,
+      min: 1,
+      max: LIST_PAGE_MAX_LIMIT,
+      default: LIST_PAGE_DEFAULT_LIMIT,
+    },
+    {
+      name: 'offset',
+      type: 'integer',
+      required: false,
+      min: 0,
+      default: 0,
+    },
+  ];
+}
+
+// `rationale` documents the per-route behavior for the params this contract does
+// NOT list (rejected on /api/plans, ignored on the serveFreshJson endpoints).
+function listPagingQuery(rationale) {
+  const query = { policy: 'optional', fields: listPagingQueryFields() };
+  if (rationale) query.rationale = String(rationale);
+  return query;
+}
+
+// Out-of-range/non-numeric paging values are clamped to the published bounds
+// rather than rejected, so the clamp is part of the contract, not a 400 path.
+function listPagingClampConstraints() {
+  return [
+    {
+      kind: 'clamped-limit',
+      field: 'limit',
+      location: 'query',
+      min: 1,
+      max: LIST_PAGE_MAX_LIMIT,
+      default: LIST_PAGE_DEFAULT_LIMIT,
+    },
+    {
+      kind: 'clamped-offset',
+      field: 'offset',
+      location: 'query',
+      min: 0,
+      default: 0,
+    },
+  ];
+}
+
+module.exports = {
+  LIST_PAGE_MAX_LIMIT,
+  LIST_PAGE_DEFAULT_LIMIT,
+  LIST_PAGING_PARAMS,
+  listPagingQueryFields,
+  listPagingQuery,
+  listPagingClampConstraints,
+};

package/engine/api-contracts/pull-requests.js

@@ -3,6 +3,7 @@
 const { PR_ACTIONS } = require('../pr-action');
 const { EXECUTION_TARGET_IDS } = require('../pr-fix-target');
 const { PR_FIX_CAUSE } = require('../shared');
+const paging = require('./paging');
 
 const PR_REFERENCE_FORMATS = Object.freeze([
   'GitHub PR URL',
@@ -52,6 +53,15 @@ module.exports = {
   overrides: {
     'GET /api/pull-requests': {
       audit: 'audited',
+      // Consumes the optional ?limit=&offset= paging window (W-ms3bbzry000i6612),
+      // clamped rather than rejected — declared so the catalog publishes it.
+      query: paging.listPagingQuery(
+        'Optional progressive-load paging window; any other query parameter is ignored, not rejected.',
+      ),
+      constraints: [
+        ...paging.listPagingClampConstraints(),
+        { kind: 'ignores-unknown-query-params', location: 'query' },
+      ],
     },
     'GET /api/prs/<id>': {
       audit: 'audited',

package/engine/api-contracts/work-plan-prd.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const paging = require('./paging');
+
 const AUDITED_NEGATIVE_TESTS = Object.freeze([{
   strategy: 'isolated-http-invalid-input-state-snapshot',
   expectedStatus: '400-or-409',
@@ -57,7 +59,24 @@ module.exports = {
       query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
     },
     'GET /api/plans': {
-      query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
+      audit: 'audited',
+      // Accepts the optional ?limit=&offset= paging window (W-ms3ovk83000rb60f);
+      // every OTHER query parameter is still rejected with the canonical 400 via
+      // planPrdValidation.validateNoQuery(req, { allow: LIST_PAGING_PARAMS }).
+      query: paging.listPagingQuery(
+        'Optional progressive-load paging window; any other query parameter is rejected (planPrdValidation.validateNoQuery).',
+      ),
+      constraints: [
+        ...paging.listPagingClampConstraints(),
+        {
+          kind: 'reject-unknown-query-params',
+          location: 'query',
+          allowed: [...paging.LIST_PAGING_PARAMS],
+        },
+      ],
+      negativeTests: [
+        { strategy: 'reject-unknown-query-param-blaming-the-rejected-name', expectedStatus: 400 },
+      ],
     },
     'POST /api/work-items': {
       audit: 'audited',
@@ -248,10 +267,18 @@ module.exports = {
       },
     },
     'GET /api/work-items': {
-      // Polled list endpoint: reads no query/body — returns the full slimmed
-      // work-item collection. Affirmed input-less so it is audited rather than
-      // defaulting to pending-audit by omission (review PR #966).
-      noInput: true,
+      // Polled list endpoint. Reads no body/headers; the only caller-supplied
+      // input is the optional ?limit=&offset= paging window (W-ms3bbzry000i6612),
+      // which is clamped rather than rejected. Declared explicitly so the catalog
+      // publishes the real parameters instead of certifying the route input-less.
+      audit: 'audited',
+      query: paging.listPagingQuery(
+        'Optional progressive-load paging window; any other query parameter is ignored, not rejected.',
+      ),
+      constraints: [
+        ...paging.listPagingClampConstraints(),
+        { kind: 'ignores-unknown-query-params', location: 'query' },
+      ],
     },
     'GET /api/work-items/archive': {
       // Archived-item listing: reads no query/body. Affirmed input-less.

package/engine/plan-prd-validation.js

@@ -65,11 +65,20 @@ function validateBody(body) {
   });
 }
 
-function validateNoQuery(req) {
+// Reject caller-supplied query params. `options.allow` lists the params the
+// endpoint genuinely accepts (e.g. the optional `limit`/`offset` paging window);
+// those are filtered out BEFORE the offending name is chosen, so the message and
+// the machine-readable `field`/`path` always blame a rejected param rather than
+// an accepted one (review of PR #1062).
+function validateNoQuery(req, options = {}) {
+  const allowed = new Set(Array.isArray(options.allow) ? options.allow : []);
   const parsed = new URL(req?.url || '/', 'http://localhost');
-  const names = [...new Set(parsed.searchParams.keys())];
+  const names = [...new Set(parsed.searchParams.keys())].filter(name => !allowed.has(name));
   if (names.length > 0) {
-    inputError(`This endpoint does not accept query parameters: ${names.join(', ')}`, {
+    const message = allowed.size > 0
+      ? `This endpoint only accepts the query parameters ${[...allowed].join(', ')}: ${names.join(', ')}`
+      : `This endpoint does not accept query parameters: ${names.join(', ')}`;
+    inputError(message, {
       code: 'unexpected-query',
       field: names[0],
       path: `query.${names[0]}`,

package/package.json

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