amicus 4.7.0 → 4.8.0

package/src/utils/engine-install-scan.js

@@ -27,12 +27,21 @@ function defaultNpmCacheDir(platform) {
   return path.join(os.homedir(), '.npm');
 }
 
-/** Best-effort `npm root -g`. Never throws; returns null on any failure. */
-function defaultNpmRootG() {
+/**
+ * Best-effort `npm root -g`. Never throws; returns null on any failure.
+ * ⚠️ Windows needs shell:true — npm is a .cmd shim, and Node 24's
+ * CVE-2024-27980 hardening rejects .cmd via execFileSync without a shell
+ * (bare `npm` → ENOENT, `npm.cmd` → EINVAL). Without this the global install
+ * was invisible to the whole scan, which also blinded engine-repair's donor
+ * search: `doctor --fix` reported "no healthy sibling install" while one sat
+ * at %AppData%\npm\node_modules.
+ */
+function resolveNpmRootG({ execFileSync, platform } = {}) {
+  const win = (platform || process.platform) === 'win32';
   try {
-    const { execFileSync } = require('child_process');
-    const out = execFileSync('npm', ['root', '-g'], {
-      encoding: 'utf-8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'],
+    const exec = execFileSync || require('child_process').execFileSync;
+    const out = exec(win ? 'npm root -g' : 'npm', win ? [] : ['root', '-g'], {
+      encoding: 'utf-8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'], shell: win,
     });
     return String(out).trim() || null;
   } catch (_e) {
@@ -45,13 +54,41 @@ function safe(fn, fallback) {
   try { return fn(); } catch (_e) { return fallback; }
 }
 
+/**
+ * Resolve the engine version from the roots already on the record. Reads
+ * opencode-ai's own package.json, which is a faithful proxy for the executed
+ * binary because opencode-ai exact-pins all 12 platform sub-packages.
+ * ⚠️ Do NOT read next to the binary: hasOpencodeBinary probes
+ * opencode-windows-<arch>/bin/opencode.exe on win32 but .bin/opencode on
+ * POSIX, and .bin/ has no package.json — a binary-adjacent rule would work on
+ * Windows only and silently return nothing on the two POSIX CI legs.
+ * Uses the real `fs` module directly (not a seam) because this is the
+ * PRODUCTION default — tests always inject `readEngineVersion` instead (the
+ * suite's fakeFs implements no readFileSync).
+ * @returns {string|undefined} undefined (never null) so toEqual fixtures survive
+ */
+function defaultReadEngineVersion({ roots }) {
+  for (const root of roots || []) {
+    try {
+      const raw = require('fs').readFileSync(path.join(root, 'opencode-ai', 'package.json'), 'utf-8');
+      const v = JSON.parse(raw).version;
+      if (v) { return String(v); }
+    } catch (_e) { /* try the next root */ }
+  }
+  return undefined;
+}
+
+/** Resolve p's real path via fs.realpathSync, tolerating any throw. */
+function realNorm(p, fs) {
+  return path.normalize(safe(() => fs.realpathSync(p), p));
+}
+
 /** Drop installs whose pkgDir resolves to the same real path; keep the first. */
 function dedupByRealpath(installs, fs) {
   const seen = new Set();
   const out = [];
   for (const inst of installs) {
-    const real = safe(() => fs.realpathSync(inst.pkgDir), inst.pkgDir);
-    const key = path.normalize(real);
+    const key = realNorm(inst.pkgDir, fs);
     if (seen.has(key)) { continue; }
     seen.add(key);
     out.push(inst);
@@ -59,6 +96,21 @@ function dedupByRealpath(installs, fs) {
   return out;
 }
 
+/**
+ * True when pkgDir is the same real install as the npm-global amicus
+ * package (`<gRoot>/amicus`). Recovers "this record IS the global install"
+ * after dedupByRealpath has already dropped the separate `kind:'global'`
+ * record — see the docblock on scanEngineInstalls for why (#133 R-A finding
+ * 1: on the documented end-user invocation, `amicus doctor` run from the
+ * globally-installed copy, `runningPkgDir` IS `<npm root -g>/amicus`, and
+ * listAmicusInstalls pushes `running` first, so dedup keeps `running` and
+ * drops `global`).
+ */
+function isGlobalInstall({ pkgDir, fs, gRoot }) {
+  if (!gRoot) { return false; }
+  return realNorm(pkgDir, fs) === realNorm(path.join(gRoot, 'amicus'), fs);
+}
+
 /**
  * The amicus installs that could serve the MCP, highest-priority first
  * (running, global, then npx-cache copies). All I/O behind seams.
@@ -76,7 +128,7 @@ function listAmicusInstalls(deps = {}) {
   const platform = deps.platform || process.platform;
   const runningPkgDir = deps.runningPkgDir || path.join(__dirname, '..', '..');
   const npmCacheDir = deps.npmCacheDir || defaultNpmCacheDir(platform);
-  const npmRootG = deps.npmRootG || defaultNpmRootG;
+  const npmRootG = deps.npmRootG || (() => resolveNpmRootG({ platform }));
 
   const raw = [{ kind: 'running', pkgDir: runningPkgDir }];
 
@@ -121,22 +173,53 @@ function classifyLaunch(config) {
  * @param {object} [deps] - listAmicusInstalls seams, plus:
  * @param {(d:{pkgDir:string}) => boolean} [deps.hasOpencodeBinary]
  * @param {(d:{pkgDir:string}) => string[]} [deps.opencodeRoots]
+ * @param {(d:{pkgDir:string, roots:string[]}) => (string|undefined)} [deps.readEngineVersion]
  * @param {() => (object|null)} [deps.readAmicusMcpConfig]
- * @returns {{installs: Array<{kind,pkgDir,engineOk,roots}>, mcpLaunch: string}}
+ * @returns {{installs: Array<{kind,pkgDir,engineOk,roots,engineVersion,isGlobal?}>, mcpLaunch: string}}
  */
 function scanEngineInstalls(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const platform = deps.platform || process.platform;
   const hasOpencodeBinary = deps.hasOpencodeBinary || require('./path-setup').hasOpencodeBinary;
   const opencodeRoots = deps.opencodeRoots || require('./path-setup').opencodeRoots;
+  const readEngineVersion = deps.readEngineVersion || defaultReadEngineVersion;
   const readAmicusMcpConfig = deps.readAmicusMcpConfig
     || (() => require('./mcp-discovery').readAmicusMcpConfig());
 
-  const installs = listAmicusInstalls(deps).map((i) => ({
-    ...i,
-    engineOk: !!hasOpencodeBinary({ pkgDir: i.pkgDir }),
-    roots: opencodeRoots({ pkgDir: i.pkgDir }),
-  }));
+  // Resolve `npm root -g` once and feed that SAME resolver into
+  // listAmicusInstalls (below), so the isGlobal recovery here reuses its
+  // result instead of spawning a second `npm root -g` process.
+  let gRootCache;
+  let gRootResolved = false;
+  const npmRootGRaw = deps.npmRootG || (() => resolveNpmRootG({ platform }));
+  const npmRootGOnce = () => {
+    if (!gRootResolved) { gRootCache = safe(() => npmRootGRaw(), null); gRootResolved = true; }
+    return gRootCache;
+  };
+
+  const rawInstalls = listAmicusInstalls({ ...deps, platform, npmRootG: npmRootGOnce });
+  const gRoot = npmRootGOnce(); // already resolved by listAmicusInstalls above; this just reads the cache
+
+  const installs = rawInstalls.map((i) => {
+    const roots = opencodeRoots({ pkgDir: i.pkgDir });
+    // #133 R-A finding 1: recovers "this IS the global install" for a
+    // record whose `kind:'global'` twin was dropped by dedupByRealpath
+    // (see isGlobalInstall's docblock). Deliberately NOT stamped inside
+    // listAmicusInstalls — its output is pinned exact by toEqual in
+    // tests/utils/engine-install-scan.test.js:57 and :89.
+    const isGlobal = i.kind !== 'global' && isGlobalInstall({ pkgDir: i.pkgDir, fs, gRoot });
+    return {
+      ...i,
+      engineOk: !!hasOpencodeBinary({ pkgDir: i.pkgDir }),
+      roots,
+      engineVersion: safe(() => readEngineVersion({ pkgDir: i.pkgDir, roots }), undefined),
+      ...(isGlobal ? { isGlobal: true } : {}),
+    };
+  });
   const mcpLaunch = classifyLaunch(safe(() => readAmicusMcpConfig(), null));
   return { installs, mcpLaunch };
 }
 
-module.exports = { listAmicusInstalls, scanEngineInstalls, classifyLaunch };
+module.exports = {
+  listAmicusInstalls, scanEngineInstalls, classifyLaunch, resolveNpmRootG,
+};

package/src/utils/engine-repair.js

@@ -23,11 +23,105 @@ function runningPkgDir() {
   return path.join(__dirname, '..', '..');
 }
 
-/** First healthy install whose real path differs from the destination. */
+/**
+ * Parse a semver-shaped string into a [major, minor, patch] triple.
+ * Prerelease versions (`1.18.15-beta.1`) return null — treated the same as
+ * unparseable, so they sort LAST rather than tying with (and, via a stable
+ * sort, sometimes beating) the release they're a prerelease of. Only the
+ * exact-release leading triple is a valid donor signal; amicus pins exact
+ * release versions, never prereleases.
+ * @returns {[number,number,number]|null} null for undefined/non-string/non-semver/prerelease
+ */
+function parseVersionTriple(v) {
+  if (typeof v !== 'string') { return null; }
+  const trimmed = v.trim();
+  if (/^\d+\.\d+\.\d+-/.test(trimmed)) { return null; }
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(trimmed);
+  if (!m) { return null; }
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Descending version comparator: newest first, unparseable/absent sorts last
+ * (never throws). Two unparseable values compare equal (0).
+ */
+function compareVersionsDesc(a, b) {
+  const ta = parseVersionTriple(a);
+  const tb = parseVersionTriple(b);
+  if (!ta && !tb) { return 0; }
+  if (!ta) { return 1; }
+  if (!tb) { return -1; }
+  for (let i = 0; i < 3; i += 1) {
+    if (ta[i] !== tb[i]) { return tb[i] - ta[i]; }
+  }
+  return 0;
+}
+
+/**
+ * TWO TIERS, not one sort. An explicitly-global healthy donor — `kind:'global'`,
+ * or `isGlobal:true` when engine-install-scan.js's dedup collapsed the
+ * `global` record into `running` (#133 R-A finding 1) — wins OUTRIGHT,
+ * regardless of version. Only when no explicit-global donor exists does
+ * engineVersion rank the remaining candidates (newest first; ties/absent
+ * versions fall back to list order, running-first).
+ *
+ * Review round 2, finding 2: a single version-first sort (this function's
+ * first cut) inverted R-A's own goal three ways, each confirmed by a test in
+ * tests/utils/engine-repair.test.js:
+ *   1. running (dev tree) newer than global → donated the dev tree. R-A's
+ *      stated goal is "--fix stops donating the dev engine"; the dev tree
+ *      running ahead of the pin is the NORMAL direction mid-pin-bump, not a
+ *      reason to trust it over the global install.
+ *   2. running-that-is-global older than a healthy npx sibling → donated the
+ *      npx sibling — the exact outcome the ORIGINAL (pre-engineVersion)
+ *      findDonor test says must never happen, reintroduced via the source
+ *      class this file's own scanEngineInstalls docblock calls LEAST
+ *      trustworthy (npx-cache copies: optional-dependency skips, AV
+ *      quarantine on every re-resolve).
+ *   3. global's version unresolved, npx sibling versioned → donated the npx
+ *      copy despite a `global` record existing at all.
+ * All three share one cause: ranking by version BEFORE asking "is there an
+ * explicit global donor at all". Tiering fixes it without losing what the
+ * version ranking was FOR — Task 3's kind-only rule left a residual hole
+ * (dev checkout, no npm-global install, broken npx destination, healthy npx
+ * sibling — no record has kind:'global' at all) where the old code fell
+ * through to `healthy[0]`, the running dev tree, and could donate a
+ * version-skewed dev engine over a newer healthy sibling. That hole is
+ * exactly the case where tier 1 finds nothing and tier 2's version ranking
+ * takes over.
+ *
+ * A `kind !== 'running'` proxy for tier 1 is wrong: listAmicusInstalls pushes
+ * `running` first and `global` second, and dedupByRealpath keeps the FIRST of
+ * any two entries that resolve to the same real path. So on an ordinary
+ * end-user machine — where the running process IS the global install — the
+ * `global` record never survives dedup; that copy is labeled `kind:
+ * 'running'` (carrying `isGlobal:true` instead, once scanEngineInstalls has
+ * run). A `kind !== 'running'` filter would then skip the good global engine
+ * and donate some other (possibly stale) healthy copy, importing the exact
+ * version skew this self-heal exists to prevent.
+ *
+ * Tier 1 (`kind==='global' || isGlobal`) is correct on both topologies: on a
+ * dev machine the dev tree and the global install are distinct real paths, so
+ * the `global` record survives dedup and wins over the dev tree. On an
+ * end-user machine there is no separate `global` record — the running process
+ * already IS it, flagged `isGlobal:true` — so tier 1 still finds it. Tier 2
+ * (list-order fallback via a stable sort) only applies when tier 1 finds
+ * nothing at all — a pure dev checkout or npx-only machine.
+ */
 function findDonor({ installs, destPkgDir, fs }) {
   const norm = (p) => { try { return path.normalize(fs.realpathSync(p)); } catch { return path.normalize(p); } };
   const destReal = norm(destPkgDir);
-  return installs.find((i) => i.engineOk && norm(i.pkgDir) !== destReal) || null;
+  const healthy = installs.filter((i) => i.engineOk && norm(i.pkgDir) !== destReal);
+  if (healthy.length === 0) { return null; }
+
+  const explicitGlobal = healthy.find((i) => i.kind === 'global' || i.isGlobal);
+  if (explicitGlobal) { return explicitGlobal; }
+
+  // No explicit-global donor on this machine at all — rank the remaining
+  // healthy candidates by engineVersion (newest first; Array#sort is stable,
+  // so ties/absent versions preserve list order, i.e. running-first).
+  const sorted = [...healthy].sort((a, b) => compareVersionsDesc(a.engineVersion, b.engineVersion));
+  return sorted[0];
 }
 
 /** The donor root (nested or hoisted) that actually holds the engine binary. */

package/src/utils/no-output-backstop.js

@@ -20,7 +20,7 @@
 
 const { envNumber } = require('./env-num');
 
-const DEFAULT_NO_OUTPUT_BACKSTOP_MS = 120000;
+const DEFAULT_NO_OUTPUT_BACKSTOP_MS = 300000;
 
 /** @param {object} [env] test seam; defaults to process.env */
 function resolveNoOutputBackstopMs(env) {

package/src/utils/remediation-hints.js

@@ -88,6 +88,35 @@ const REMEDIATION_HINTS = Object.freeze({
   sweepSessionIndexTmp:
     'amicus doctor --fix  (sweeps orphaned .sessions-index.json.*.tmp files left by an interrupted write)',
 
+  /**
+   * Engine version skew (#133 R-A): a PRESENT engine can still be the WRONG
+   * one — the npx-cache copy `npx -y amicus@latest mcp` launches and the
+   * global install resolve independently and at different times, and two
+   * engine versions writing one shared opencode.db is what produced #133's
+   * SQLiteError. Unlike reinstallEngineAv (antivirus quarantine — a MISSING
+   * binary), this is a WRONG-VERSION binary, so the remedy has to touch both
+   * sides: reinstall the global copy (which re-resolves to the exact pinned
+   * opencode-ai/@opencode-ai/sdk version amicus pins as of 4.7.1), and clear
+   * the npx-cache tree so the npx copy re-resolves fresh next time it
+   * launches instead of replaying a stale cached one.
+   *
+   * Review round 2, finding 3: the first cut of this hint said
+   * `npm cache clean --force`, which does NOT touch the npx tree — verified
+   * against npm's own lib/commands/cache.js (npm 11.16.0): `cache clean`
+   * removes `flatOptions.cache` (the registry-metadata cache, `<cache
+   * dir>/_cacache`), while npx installs live at the SEPARATE
+   * `flatOptions.npxCache` (`<cache dir>/_npx`). That command would have left
+   * the skewed npx copy byte-for-byte in place. The correct command is npm's
+   * own npx-cache subcommand: `npm cache npx rm` with no keys and `--force`
+   * empties the whole npx cache (cache.js's `npxRm`: no keys + force →
+   * `fs.rm(npxCache, {recursive:true, force:true})`). Since `doctor --fix`
+   * has no dedicated skew branch (WARN only — see doctor-engine-check.js),
+   * this hint is the ONLY remedy the user gets — it must actually work.
+   */
+  engineVersionSkew:
+    'npm install -g amicus && npm cache npx rm --force  (reinstalls the global engine to the exact pinned opencode-ai version — amicus pins it exactly as of 4.7.1 — '
+    + 'and empties the npx cache, the SEPARATE directory `npm cache clean` does not touch, so the npx-cache copy `npx -y amicus@latest mcp` launches re-resolves fresh to that same pinned version instead of replaying a stale one)',
+
   /**
    * Orphaned per-session metadata.json.*.tmp files (v4.6.3 PR3 Task 3 / D8):
    * same producer shape as sweepSessionIndexTmp above, one level down — a
@@ -101,6 +130,19 @@ const REMEDIATION_HINTS = Object.freeze({
    */
   sweepSessionMetadataTmp:
     'amicus doctor --fix  (sweeps orphaned .metadata.json.*.tmp files left by an interrupted write)',
+
+  /**
+   * Stale sessions-index.json entries (R16): session-index.js :: recordSession
+   * never removes a row, so a project that is deleted, renamed or moved
+   * leaves its taskId -> path entries behind forever, and every
+   * recordSession call pays for rewriting the WHOLE index — the per-start
+   * cost grows with total sessions ever, not live ones. `doctor --fix`
+   * removes only entries whose project path no longer exists on disk
+   * (liveness, never age — R16-2): a five-year-old entry for a project that
+   * still exists is left alone.
+   */
+  pruneSessionIndex:
+    'amicus doctor --fix  (removes sessions-index.json entries whose project no longer exists on disk — liveness-based, never by age)',
 });
 
 module.exports = REMEDIATION_HINTS;

package/src/utils/session-index-prune.js

@@ -0,0 +1,297 @@
+// src/utils/session-index-prune.js
+'use strict';
+
+/**
+ * R16: sessions-index.json stale-entry prune for `amicus doctor --fix`.
+ *
+ * session-index.js :: recordSession appends taskId -> canonicalProjectPath on
+ * every session start and nothing ever removes one. A project that is
+ * deleted, renamed or moved leaves its rows behind forever, and every
+ * recordSession call pays for rewriting the WHOLE index (full read -> parse
+ * -> mutate -> stringify -> atomic write), so the per-start cost grows with
+ * total sessions ever, not live ones (docs/superpowers/plans/
+ * 2026-08-22-v48-wave25-r16-index-prune.md §0.1). This module lists and
+ * removes the dead rows; src/cli-handlers-doctor.js composes the result into
+ * a check line. Structurally mirrors utils/session-index-tmp-sweep.js (R16-1:
+ * reuse that whole warn/fix/hint shape rather than inventing a new one).
+ *
+ * R16-2 (liveness, NEVER age): an entry is stale IFF its project path no
+ * longer resolves to a directory on disk. No TTL, no mtime sort — a
+ * five-year-old entry for a project that still exists is still a valid
+ * lookup target; a one-day-old entry for a deleted project is not. Unlike its
+ * tmp-file sibling (which age-gates in `evaluate` so a live writer's ms-lived
+ * tmp is never swept), there is no such grace window here by design.
+ *
+ * R16-3 (probe distinct projects, not entries): the index is
+ * taskId -> project and many task ids share one project (measured: `amicus
+ * list --all`'s enumerateAllProjects walks every distinct project — 21,145
+ * rows in 8,275ms before a manual prune to 187 entries, 132 rows in 53ms
+ * after). Probing per-entry would repeat the same statSync for every task id
+ * that shares a project; `listStaleSessionIndexEntries` dedupes to the
+ * distinct project set FIRST, statSyncs each ONCE, then marks entries whose
+ * project is in the dead set. Both counts are reported.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const HINTS = require('./remediation-hints');
+
+// The zeroed shape for "checked, nothing stale". Also the base (via spread)
+// for the distinguishable failure shape listStaleSessionIndexEntries returns
+// on an internal error — see that function's catch, below.
+const EMPTY_RESULT = Object.freeze({
+  staleTaskIds: [], entryCount: 0, distinctProjectCount: 0, staleProjectCount: 0,
+});
+
+/**
+ * Whether `project` still resolves to a directory.
+ *
+ * statSync (not lstatSync) is deliberate: unlike session-index-tmp-sweep.js's
+ * DESTRUCTIVE unlink (see that file's symlink-safety comment) or
+ * session-metadata-tmp-sweep.js's never-follow walk, nothing here ever
+ * deletes anything AT `project` — only the taskId's row in a wholly separate
+ * JSON file. A project reached through a symlink is a live lookup target
+ * exactly like any other; a DANGLING symlink should read as gone the same way
+ * a deleted real directory does, which is what following (statSync), not
+ * lstatSync, gives us.
+ *
+ * Judgment call (R16, left open by the plan on purpose): only ENOENT/ENOTDIR
+ * is treated as "confirmed gone". Everything else — EACCES, EPERM, a
+ * transient EIO, an unmounted network share timing out — means "cannot
+ * confirm", not "confirmed gone", so it is treated as LIVE. This mirrors the
+ * ENOENT-only split workspace/artifact-guard.js :: readRunArtifact already
+ * uses for the identical ambiguity (its RN-10 fix). Treating "cannot read" as
+ * "does not exist" would prune a LIVE entry on a permissions blip — both a
+ * liveness-check correctness bug (R16-2) and a silent loss of user state
+ * (plan Global Constraint 5).
+ *
+ * @param {string} project
+ * @param {(p: string) => import('fs').Stats} statSync
+ * @returns {boolean}
+ */
+function projectExists(project, statSync) {
+  try {
+    return statSync(project).isDirectory();
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) { return false; }
+    return true;
+  }
+}
+
+/**
+ * List session-index entries whose project no longer exists.
+ *
+ * Never THROWS: the corrupt/missing-index case is handled exactly as
+ * session-index.js :: readIndex already handles it (corrupt/missing -> {}),
+ * so it never reaches the catch below. An unexpected internal failure still
+ * degrades rather than propagates into `doctor` — but (council R16 fix round
+ * A3) the degraded result now carries `error`, which an all-clear result
+ * never has, so "checked, 0 stale" and "could not check" can never collapse
+ * to the same value. See evaluateSessionIndexPrune for how that distinction
+ * is read.
+ *
+ * @param {{statSync?: (p: string) => import('fs').Stats,
+ *   readIndex?: () => Record<string,string>}} [deps] - injectable for tests
+ *   (e.g. to simulate EACCES without needing real OS permissions).
+ * @returns {{staleTaskIds: string[], entryCount: number,
+ *   distinctProjectCount: number, staleProjectCount: number, error?: string}}
+ */
+function listStaleSessionIndexEntries(deps = {}) {
+  try {
+    const statSync = deps.statSync || fs.statSync;
+    const readIndex = deps.readIndex || require('./session-index').readIndex;
+
+    const index = readIndex() || {};
+    const taskIds = Object.keys(index);
+
+    // R16-3: dedupe to the DISTINCT project set before ever touching the disk.
+    const projects = new Set();
+    for (const taskId of taskIds) {
+      const project = index[taskId];
+      if (typeof project === 'string' && project) { projects.add(project); }
+    }
+
+    const deadProjects = new Set();
+    for (const project of projects) {
+      if (!projectExists(project, statSync)) { deadProjects.add(project); }
+    }
+
+    const staleTaskIds = taskIds.filter((taskId) => {
+      const project = index[taskId];
+      // A non-string/empty project can never resolve to a lookup target
+      // either — dead weight from the same "nothing ever removes a row" gap,
+      // and this is the only place that can ever clean it up.
+      return !(typeof project === 'string' && project) || deadProjects.has(project);
+    });
+
+    return {
+      staleTaskIds,
+      entryCount: taskIds.length,
+      distinctProjectCount: projects.size,
+      staleProjectCount: deadProjects.size,
+    };
+  } catch (err) {
+    // Council R16 fix round (A3): landing here must not read the same as "0
+    // stale rows" — this project's stated north star is that a
+    // correct-but-SILENT degrade fails the bar as hard as a crash. The
+    // expected corrupt/missing-index case never reaches this catch (readIndex
+    // itself already guards to {}); what DOES land here is either a real bug
+    // or a throwing injected dep (deps.readIndex/deps.statSync are both real
+    // injection points). Tag the result so evaluateSessionIndexPrune can tell
+    // "checked, found nothing" apart from "could not check" — still never
+    // throws into doctor, just stops reporting a failure as an all-clear.
+    return { ...EMPTY_RESULT, error: (err && err.message) || String(err) };
+  }
+}
+
+/**
+ * Remove the given taskIds from the index, atomically, through the same
+ * writeFileAtomic path session-index.js :: recordSession uses. Re-reads the
+ * index fresh (never reuses a list-time snapshot), deletes ONLY the given
+ * ids — never any other key a concurrent writer may have added to the
+ * freshly-read index (verified: tests/doctor-index-prune.test.js's "removes
+ * only the given ids" and the B1 concurrent-add case below) — and writes
+ * only when at least one given id is still actually present.
+ *
+ * `deps.readIndex` plus the `|| {}` guard below mirror
+ * listStaleSessionIndexEntries (council R16 fix round A1/A4): that was the
+ * one asymmetry between the two siblings — `list` was stub-testable for a
+ * corrupt/absent readIndex, `prune` was not testable at all without a real
+ * config dir, and an injected readIndex() returning null/undefined would
+ * TypeError on `Object.prototype.hasOwnProperty.call(null, ...)`. The REAL
+ * readIndex can never return null (session-index.js :: readIndex always
+ * yields a validated object or `{}`), so this never fires in production —
+ * it closes a tested gap, not a live bug. Still does NOT guard its own
+ * THROWS, matching session-index-tmp-sweep.js :: unlinkSessionIndexTmp,
+ * which also lets fs errors propagate to its caller; evaluateSessionIndexPrune
+ * (below) is that catcher.
+ *
+ * B1/D1 (council R16 fix round 2 — raised again by two more models;
+ * adjudicated, real, pre-existing, still NOT fixed here): the race is
+ * TWO-SIDED. `target` is computed before the read so only the in-memory
+ * filter below runs between read and write — the narrowest this window gets
+ * without real synchronization — but session-index.js :: recordSession
+ * performs the IDENTICAL unlocked read-modify-write. Locking only THIS side
+ * would be theater: closing the race properly requires locking
+ * recordSession too, exactly the hot-start-path cost ruling R16-1 rejected
+ * when it chose this doctor-check design over "prune on write". Consequence,
+ * unchanged: a session recorded by another process between this read and
+ * this write is lost, degrading `amicus read <id>` from another project
+ * into a not-found. `src/utils/session-lock.js` already provides atomic
+ * PID/staleness lock-file primitives (used today per-session-dir, not for
+ * this file) — the natural home for that future lock/CAS, noted so it is
+ * not re-derived, but NOT wired in here: its own change, beyond R16.
+ *
+ * @param {string[]} staleTaskIds
+ * @param {{readIndex?: () => Record<string,string>}} [deps] - injectable for
+ *   tests (matches listStaleSessionIndexEntries's shape/rationale above).
+ * @returns {number} count actually removed (may be less than
+ *   staleTaskIds.length if an id was already gone by the time this ran).
+ */
+function pruneStaleSessionIndexEntries(staleTaskIds, deps = {}) {
+  // Array.isArray, not `|| []` (council R16 fix round 2, A2/d1): the old
+  // guard caught null/undefined but let any OTHER truthy value through — a
+  // string would iterate per character below, a plain object would throw.
+  const ids = Array.isArray(staleTaskIds) ? staleTaskIds : [];
+  if (ids.length === 0) { return 0; }
+
+  // Lazy requires here match session-index-tmp-sweep.js's established
+  // convention for these same deps (council R16 fix round 2, A4) — kept, not hoisted.
+  const { INDEX_FILENAME, readIndex: realReadIndex } = require('./session-index');
+  const readIndex = deps.readIndex || realReadIndex;
+  const { getConfigDir } = require('./config');
+  const { writeFileAtomic } = require('./atomic-write');
+  const target = path.join(getConfigDir(), INDEX_FILENAME);
+
+  const index = readIndex() || {};
+  let removed = 0;
+  for (const taskId of ids) {
+    if (Object.prototype.hasOwnProperty.call(index, taskId)) {
+      delete index[taskId];
+      removed += 1;
+    }
+  }
+  if (removed === 0) { return 0; }
+
+  writeFileAtomic(target, JSON.stringify(index, null, 2), { mode: 0o600 });
+  return removed;
+}
+
+/**
+ * Compose the doctor check line for the stale-entry prune. Pure decision
+ * logic (list/prune side effects come in via `d`); src/cli-handlers-doctor.js
+ * wraps this in guard() the same way it wires the tmp-sweep check beside it.
+ * @param {{listStaleSessionIndexEntries: () => {staleTaskIds:string[],
+ *   entryCount:number, distinctProjectCount:number, staleProjectCount:number,
+ *   error?:string},
+ *   fix?: boolean,
+ *   pruneStaleSessionIndexEntries: (ids: string[]) => number}} d
+ */
+function evaluateSessionIndexPrune(d) {
+  const id = 'sessions-index-prune'; const name = 'Session index stale entries';
+  const list = d.listStaleSessionIndexEntries();
+
+  // Council R16 fix round (A3): a listing failure gets its own status, never
+  // coalesced into the "0 stale" shape below. `status: 'error'` is the same
+  // vocabulary guard() uses for every other doctor check failure —
+  // doctor-degrade.js turns it into a 'doctor-check-failed' record; doctor
+  // still finishes and prints every other line (loud, not fatal).
+  if (!list || list.error) {
+    return {
+      id, name, status: 'error',
+      message: `could not determine stale session-index entries: ${(list && list.error) || 'unknown error'}`,
+      hint: null,
+    };
+  }
+  const { staleTaskIds, entryCount, distinctProjectCount, staleProjectCount } = list;
+  const staleCount = staleTaskIds.length;
+
+  if (staleCount === 0) {
+    return {
+      id, name, status: 'ok',
+      message: `0 stale rows (${entryCount} entries, ${distinctProjectCount} distinct project(s) checked)`,
+      hint: null,
+    };
+  }
+  if (!d.fix) {
+    return {
+      id, name, status: 'warn',
+      message: `${staleCount} stale row(s) of ${entryCount} — ${staleProjectCount} of ${distinctProjectCount} distinct project(s) gone — run with --fix`,
+      hint: HINTS.pruneSessionIndex,
+    };
+  }
+
+  // Council R16 fix round (A2): capture WHY a write underperformed instead of
+  // reporting every cause as the same generic guess — a thrown exception
+  // (disk full, EACCES, a bug) is a different fact from some ids having
+  // already been removed by a racing prune, and swallowing the exception's
+  // own message was hiding that difference. Status stays 'warn' either way
+  // (never crashes doctor — see the throwing-prune test) but the message no
+  // longer lies about which one happened.
+  let pruned = 0;
+  let writeError = null;
+  try { pruned = d.pruneStaleSessionIndexEntries(staleTaskIds) || 0; }
+  catch (e) { writeError = (e && e.message) || 'unknown error'; }
+
+  if (pruned === staleCount && !writeError) {
+    return {
+      id, name, status: 'ok', message: `pruned ${pruned} stale row(s)`, hint: null,
+      fixed: true,
+      fixDetail: `pruned ${pruned} stale session-index row(s) (${staleProjectCount} deleted project(s))`,
+    };
+  }
+  // Council R16 fix round 2 (A3): name the OBSERVATION (fewer removed than
+  // listed), not an inferred cause — the count can differ for reasons other
+  // than "the index changed" underneath us.
+  const remaining = staleCount - pruned;
+  const reason = writeError ? `write failed: ${writeError}` : 'fewer entries removed than expected';
+  return {
+    id, name, status: 'warn',
+    message: `pruned ${pruned}, ${remaining} remaining (${reason})`,
+    hint: HINTS.pruneSessionIndex,
+  };
+}
+
+module.exports = {
+  listStaleSessionIndexEntries, pruneStaleSessionIndexEntries, evaluateSessionIndexPrune,
+};

package/src/utils/session-metadata-tmp-sweep.js

@@ -13,7 +13,7 @@
  * Structurally mirrors utils/session-index-tmp-sweep.js (B15's sibling).
  *
  * Enumeration decision (cwd-scoped, index rejected — recorded at plan time,
- * docs/superpowers/plans/2026-08-05-v463-pr3-cli-doctor-odds.md): this walks
+ * v4.6.3 D8): this walks
  * `<process.cwd()>/.claude/amicus_sessions/` — each taskId dir plus its
  * `subagents/<id>/` children — rather than consulting sessions-index.json.
  * `amicus doctor` is a per-project surface; the index is best-effort and can