amicus 4.7.1 → 4.8.0

package/src/utils/config.js

@@ -60,7 +60,16 @@ function saveConfig(configData) {
   if (configData && configData.aliases) {
     const cleaned = {};
     for (const [key, value] of Object.entries(configData.aliases)) {
-      if (key === 'null' || !value || typeof value !== 'string' || value === 'null') {
+      // `key === '__proto__'` — v4.8 SI-22.4 fix round 3 (council G-5). Without
+      // it the write below (`cleaned[key] = value`) hit Object.prototype's
+      // INHERITED `__proto__` setter, which ignores a string, so the alias
+      // vanished with NO "Removing invalid alias" notice — the only silent
+      // removal in this loop. Rejecting it explicitly puts it on the same
+      // footing as the `'null'` key beside it: same branch, same message.
+      // (No pollution was possible either way — only strings reach this line,
+      // and the setter ignores them — so this is an announcement fix, not a
+      // security one. Stated that way on purpose.)
+      if (key === 'null' || key === '__proto__' || !value || typeof value !== 'string' || value === 'null') {
         process.stderr.write(
           `Notice: Removing invalid alias '${key}' (value: ${JSON.stringify(value)}) from config.\n`
         );
@@ -78,7 +87,14 @@ function saveConfig(configData) {
 
 /** @returns {object} Copy of the default alias map */
 function getDefaultAliases() {
-  return { ...DEFAULT_ALIASES };
+  // ⚠️ `__proto__: null` must be RESTATED here, not inherited. A spread into a
+  // bare `{}` literal produces a plain object again, so fixing the builders in
+  // curated-models.js does NOT reach this copy — measured, not assumed. Its
+  // consumers index it: `sidecar/setup.js:479` (`getDefaultAliases()[alias]`)
+  // and `electron/setup-ui-aliases.js :: buildAliasEditorHTML`
+  // (`aliases[key] !== undefined`).
+  // Named mutant "BUILDERPROTO" covers this line too.
+  return { __proto__: null, ...DEFAULT_ALIASES };
 }
 
 /**
@@ -216,7 +232,44 @@ function checkConfigChanged(currentHash) {
 function getEffectiveAliases() {
   const config = loadConfig();
   const userAliases = (config && config.aliases) || {};
-  return { ...DEFAULT_ALIASES, ...userAliases };
+  // `__proto__: null` — v4.8 SI-22.4 fix round 2 (council B1). This table is
+  // read with BARE INDEXING by five gates, so on a normal object a member
+  // literally named 'toString' / 'constructor' / 'valueOf' / 'hasOwnProperty'
+  // resolved off Object.prototype to a truthy Function and was treated as a
+  // KNOWN ALIAS. Measured, not argued:
+  //   resolveModel('toString')                    -> the Function itself,
+  //       typeof 'function', where every caller expects a model-id STRING
+  //       (`:111` and `:142` gate on `!== undefined`, which a Function passes)
+  //   classifyCouncilMembers(['toString '], [])   -> ACCEPTED, i.e. runnable
+  // The SAME defect class this release already closed at other lookup tables —
+  // `tally.js :: VERDICTS`, `report.js :: SYMBOL`, `debate.js :: PAST_TENSE`
+  // (all `__proto__: null`), plus `street-cred.js :: perJudgeRank` and
+  // `report.js :: ROLE_SUFFIX` (both `Object.create(null)`, the same guarantee
+  // in the other spelling). The ALIAS table was not among them.
+  // ⚠️ SI-22.4 WIDENED it and that is why it is fixed here: at BASE the padded
+  // spelling ('toString ') missed the prototype and was correctly dropped;
+  // trimming before the lookup landed it on the inherited property. The
+  // unpadded spelling was already accepted, so restoring only the padded case
+  // would take more code AND deliberately preserve a known hole.
+  // ⚠️ Fixed HERE, not at the call sites — one line closes all five, each
+  // MEASURED at its own gate expression with `'toString'` (not inferred from
+  // this one): `resolveModel` `:111`/`:142` (`!== undefined` true→false) ·
+  // `classifyCouncilMembers` (accepted→dropped, end to end) ·
+  // `council/presets-cli.js:41` (`amicus council save`: unresolved false→true) ·
+  // `pack/pack-validate.js:71` (`seatOk` true→false) ·
+  // `utils/route-launch.js:205` (`isAlias` true→false).
+  // No consumer breaks: every reference either indexes (`aliases[key]`) or
+  // iterates own-enumerable keys (`Object.entries`/`Object.keys` —
+  // `buildProviderModels`, `formatAliasNames`, `mcp-tools.js :: getGuideText`,
+  // `sidecar/models.js :: aliasMarks`), and both behave identically on a
+  // null-prototype object. NOTHING calls a method ON the object — swept
+  // uncapped over `src/` and `electron/` for `aliases.<x>`, `in aliases`,
+  // `Object.values`, `JSON.stringify`, spread and `for…in`.
+  // A `__proto__` key inside the user's own config.json is copied as an ORDINARY
+  // own property by spread (never the setter), so the prototype stays null —
+  // measured on both a literal and a `JSON.parse`d source.
+  // Named mutant "PROTOALIASES": drop `__proto__: null` from the literal below.
+  return { __proto__: null, ...DEFAULT_ALIASES, ...userAliases };
 }
 
 /**
@@ -414,11 +467,42 @@ function getCouncilWithSource(name, catalog = []) {
  * at the last refresh; the leg itself fails pre-flight with the actionable
  * local_endpoint_unreachable error if it is truly down). Only a NON-EMPTY
  * catalog that omits the resolved id is a definitive drop.
- * @param {string[]} members raw council members (aliases or provider/model ids)
+ *
+ * WHITESPACE (v4.8 SI-22.4). Each member is TRIMMED before it is classified,
+ * closing a divergence: `--models` already trimmed
+ * (`sidecar/fanout-validate.js :: parseModelsList`, and `cli-council-run-bench.js
+ * :: parseList` on the council surface) while `--council` did not, so the same
+ * stray space was benign on one flag and, here, converted a typo into a dropped
+ * member and a degraded (2) exit. ⚠️ The dominant effect is RESURRECTION, not
+ * de-duplication: a padded member that is dropped today starts RUNNING, which
+ * is a new paid leg. Where the trim makes two members collide, the bench
+ * becomes a real twin and `seats.js :: buildSeats` mints `alias#N` for both.
+ * An all-whitespace member trims to `''`, which no alias table names, so gate 1
+ * below drops it — the `.filter(Boolean)` half of `parseModelsList`'s shape,
+ * reached without a third `reason` string (see the tripwire note below).
+ * @param {string[]} members council members as configured — aliases or
+ *   provider/model ids, trimmed per member here. ⚠️ This is the only place the
+ *   preset READ path trims — NOT the only place the preset path trims at all,
+ *   and NOT the only trim a member meets. The WRITE side already trimmed:
+ *   `council/presets-cli.js:34` (`amicus council save`) stores
+ *   `.split(',').map(m => m.trim()).filter(Boolean)`, and the only other writer
+ *   of `cfg.councils` in `src/` (`sidecar/setup.js:593`, the seeded `free`
+ *   council) composes its members from generated/existing alias KEYS, which
+ *   cannot carry user padding. So a padded member in `cfg.councils` comes from
+ *   a hand-edited `config.json`, and that is the case this trim serves.
+ *   Downstream, both council
+ *   surfaces re-join the expanded bench and re-parse it downstream —
+ *   `cli-handlers-fanout.js:91` → `:119` → `sidecar/fanout.js ::
+ *   validateFanoutModels` → `parseModelsList`, and `mcp-council-run.js:177` →
+ *   the spawned child's `cli-council-run-bench.js :: parseList` — so a member
+ *   that somehow kept padding past this point would still be trimmed there
  * @param {Array<{id:string}>} [catalog]
  * @returns {{models:string[], dropped:string[], droppedMembers:Array<{member:string, reason:string}>}}
  *   `dropped` is the flat member-ref list (unchanged shape, pre-v4.5-Wave-2
  *   callers keep working); `droppedMembers` additively pairs each with WHY.
+ *   ⚠️ Both report the member RAW — untrimmed, byte-for-byte as configured
+ *   (v4.8 SI-22.4, R22.4-2) — so a user can find the offending string in their
+ *   own config. Only `models` carries the trimmed value.
  *
  *   Standing note (D18, v4.7 PR5): each `droppedMembers` entry is `{member, reason}`
  *   (that is the real key — BACKLOG.md's description of this shape had drifted to
@@ -442,18 +526,29 @@ function classifyCouncilMembers(members, catalog = []) {
   const models = [];
   const dropped = [];
   const droppedMembers = [];
-  for (const member of members) {
+  for (const raw of members) {
+    // v4.8 SI-22.4. Trim BEFORE gate 1 below, never after: a padded ALIAS
+    // ('gpt ') must reach the alias table as written in the table, and a padded
+    // full id ('openai/gpt-5 ') must reach the catalog lookup clean. Trimming
+    // downstream of either gate would leave both misses in place. Non-strings
+    // pass through untouched so their `.includes` still throws exactly as it
+    // did before this line existed. Named mutant "NOTRIM": drop the `.trim()`.
+    const member = typeof raw === 'string' ? raw.trim() : raw;
     const id = member.includes('/') ? member : aliases[member];
+    // R22.4-2: `models` gets the TRIMMED value, `dropped`/`droppedMembers` get
+    // `raw` — a member still dropped after trimming is reported as the user
+    // wrote it, or they cannot grep their own config for it. Named mutant
+    // "TRIMDROPPED": report `member` instead of `raw` in the two drop branches.
     if (!id) { // alias no longer resolves
-      dropped.push(member);
-      droppedMembers.push({ member, reason: 'alias no longer resolves to a known model' });
+      dropped.push(raw);
+      droppedMembers.push({ member: raw, reason: 'alias no longer resolves to a known model' });
       continue;
     }
     const vendor = typeof id === 'string' ? id.split('/')[0] : '';
     if (isLocalProvider(vendor)) { models.push(member); continue; }
     if (known.size > 0 && !known.has(id)) { // delisted model
-      dropped.push(member);
-      droppedMembers.push({ member, reason: 'resolved id is not present in the cached model catalog' });
+      dropped.push(raw);
+      droppedMembers.push({ member: raw, reason: 'resolved id is not present in the cached model catalog' });
       continue;
     }
     models.push(member);
@@ -465,8 +560,11 @@ function classifyCouncilMembers(members, catalog = []) {
  * Expand a saved council into a runnable members list, degrading gracefully.
  * Unresolvable aliases and delisted ids are dropped with a warning rather than
  * fail-fast-aborting the whole wave (classification: classifyCouncilMembers
- * above). Returns members RAW (alias or id) — leg-time validation resolves
- * them again.
+ * above). Returns members UNRESOLVED (the alias or id as configured, never the
+ * id an alias maps to) — leg-time validation resolves them again. ⚠️ Not
+ * byte-identical to the configured string since v4.8 SI-22.4: classification
+ * trims each member, so `models[i]` is the configured member minus any
+ * surrounding whitespace. `dropped`/`droppedMembers` still carry it raw.
  *
  * Resolution order: user config (`config.councils`) is checked first; when
  * `name` is absent there, the built-in benches (`free`/`budget`/`frontier`)

package/src/utils/curated-models.js

@@ -111,6 +111,13 @@ const CARDLESS = [
   { alias: 'grok', routes: { openrouter: 'openrouter/x-ai/grok-4.3' } },
   { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.6' } },
   { alias: 'seed', routes: { openrouter: 'openrouter/bytedance-seed/seed-2.0-lite' } },
+  // inkling added 2026-08-14: the council-review workflow's default bench
+  // names it, and a workflow can only use aliases this table ships — a CI
+  // runner has no user config, so a locally-defined alias resolves to
+  // nothing there. Pinned to the full model, not `inkling-small`: the bench
+  // seat wants the flagship's judgment. `:batch` is deliberately not pinned
+  // (deferred completion is wrong for an interactive council leg).
+  { alias: 'inkling', routes: { openrouter: 'openrouter/thinkingmachines/inkling' } },
 ];
 
 /**
@@ -242,7 +249,14 @@ function directFormProvenance() {
  * without corrupting divergent-vendor ids (e.g. Anthropic's dash format).
  */
 function toGatewayRoutes() {
-  const out = {};
+  // `__proto__: null` — v4.8 SI-22.4 round 3 (G-1). Read by BARE INDEXING
+  // downstream, so a plain `{}` let an alias named 'toString'/'constructor'/
+  // 'valueOf'/'hasOwnProperty' resolve off Object.prototype to a truthy
+  // Function — including on the auto-repair path (`alias-resolver.js ::
+  // autoRepairAlias`), which `getEffectiveAliases`'s own fix could never reach.
+  // Full measurement + why THREE seeds were needed:
+  // tests/council/preset-trim-mutants.js :: BUILDERPROTO (the named mutant).
+  const out = { __proto__: null };
   for (const f of FAMILIES) { out[f.alias] = gatewayRoutesFor(f.vendorPath, f.fallback); }
   for (const e of CARDLESS) { out[e.alias] = gatewayRoutesFor(vendorOf(e.routes.openrouter), e.routes); }
   return out;
@@ -262,7 +276,8 @@ function toGatewayRoutes() {
  * shipped defaults.
  */
 function toDefaultAliases() {
-  const out = {};
+  // `__proto__: null` — see toGatewayRoutes above. Becomes DEFAULT_ALIASES.
+  const out = { __proto__: null };
   for (const [alias, routes] of Object.entries(toGatewayRoutes())) {
     out[alias] = routes.direct || routes.openrouter;
   }

package/src/utils/degrade.js

@@ -17,6 +17,11 @@ const DEGRADE_CHANNELS = Object.freeze(new Set([
   'dropped-members', 'chair-skipped-cost-ceiling', 'chair-failed',
   'thin-cross-review', 'debate-degraded', 'inexact-under-ceiling',
   'stage1-retry',
+  // v4.8: the seat<->leg join failed. THREE shapes, one channel: a launched seat whose wave
+  // returned legs but none its own; a returned leg matching no roster slot; and (T5.5, `-rv` only)
+  // a leg that DID match a slot but whose join key names no judge the wave launched.
+  // Never a guess — silent mis-attribution is the failure seat identity exists to kill (§4.4).
+  'seat-unbound',
   'internal',
   // doctor channels
   'doctor-check-failed', 'doctor-fix',

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

@@ -130,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