amicus 4.7.1 → 4.8.1

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

package/src/workspace/artifact-guard.js

@@ -14,20 +14,16 @@
 
 const fsReal = require('fs');
 const path = require('path');
-const { sanitizeName } = require('../council/run-launch');
 const { readPointer } = require('./run-scan');
 const { isRealpathContained } = require('../utils/path-fence');
+// v4.8 PR5a: name derivation moved to ./artifact-names (the 300-line gate). The two
+// constants and artifactAllowlist are re-exported below unchanged, so every existing
+// caller and test keeps importing them from here.
+// `isSeatTable` joins them (fix-wave, council A1/B1): run-detail.js has to answer "is
+// this run in seat space?" with THE predicate artifactAllowlist gates on, not a second
+// spelling of it, and this module is already its import surface.
+const { artifactAllowlist, isSeatTable, FIXED_ARTIFACTS, DEBATE_ARTIFACTS } = require('./artifact-names');
 
-const FIXED_ARTIFACTS = Object.freeze(['briefing-stage1.md', 'bundle-stage2.md', 'chair-packet.md', 'chair-output.md', 'tally-input.json']);
-// ⚠️ DE-ROT (F28): v4.1's debate stage writes five MORE run-dir artifact kinds the original
-// allowlist never named, so the Workspace hard-refused every `--debate` output with
-// `artifact not allowed: <name>`. Writers: tally-provisional.json = src/council/run.js:199;
-// revote-bundle.md = run-debate.js:119; debate.json = run-debate.js:261; the per-seat
-// rebuttal-/revote- pair = materializeDebate (run-launch.js:127-136).
-// ⚠️ FIVE KINDS, THREE ENTRIES — that is not a miscount (v4.4.1 DOC-7, re-verified). This const
-// holds only the three RUN-LEVEL names; the last two of the five, the rebuttal-/revote- pair, are
-// per BENCH MODEL and are appended inside artifactAllowlist below, next to review-/judge-.
-const DEBATE_ARTIFACTS = Object.freeze(['tally-provisional.json', 'revote-bundle.md', 'debate.json']);
 const MAX_ARTIFACT_BYTES = 200 * 1024;
 
 // isRealpathContained itself now lives in ../utils/path-fence.js (the shared "fence 2"
@@ -53,108 +49,6 @@ function truncateUtf8(buf, max) {
   return buf.subarray(0, end);
 }
 
-/**
- * @param {object} run parsed run.json (may be partial)
- * @returns {string[]} the allowlist. When two or more DISTINCT bench entries sanitize to the
- *   same artifact name, a non-enumerable-in-spirit (but plain, test-visible) `collisions`
- *   array is attached: `[{sanitized, models: [rawA, rawB, ...]}, ...]`. See the R4
- *   council-review note below for why this is surfaced rather than silently deduped.
- */
-function artifactAllowlist(run) {
-  const names = [...FIXED_ARTIFACTS];
-  const bench = run && Array.isArray(run.bench) ? run.bench : [];
-  // ⚠️ DE-ROT (F28): run.json carries a `debate` key ONLY on --debate runs, and it is seeded
-  // on the FIRST write (src/council/run.js:74-77), so this gate is safe and keeps the
-  // allowlist tight for the common case.
-  const debated = !!(run && run.debate);
-  if (debated) { names.push(...DEBATE_ARTIFACTS); }
-
-  // ⚠️ R4 COUNCIL REVIEW (fourth live paid council, major, unanimous): sanitizeName is NOT
-  // injective — it maps every character outside [a-zA-Z0-9._-] to '-', so two DISTINCT bench
-  // entries ('vendor/a', 'vendor?a') both produce 'vendor-a'. Both models would then request
-  // the SAME artifact file, and the renderer's `[data-artifact="..."]` lookup (drillIntoJudge)
-  // hands back whichever section matches first — prose silently misattributed to the wrong
-  // model. That is a run-integrity defect (this run directory genuinely cannot hold both
-  // models' review/judge files under distinct names), not a display quirk, so it must be
-  // DETECTED and surfaced, never smoothed away by deduping the resulting name list.
-  //
-  // A bench with genuinely REPEATED identical entries (['gemini', 'gemini']) is a different,
-  // harmless case that must keep collapsing to one set of rows (preserved intent) — collapse
-  // those via a Set over the RAW bench values FIRST, so identical entries never even reach
-  // the collision check below (only entries that are distinct as raw strings but coincide
-  // after sanitizeName count as a collision).
-  const uniqueModels = [...new Set(bench)];
-  const rawBySanitized = new Map(); // sanitized name -> first raw model seen for it
-  const collisionModels = new Map(); // sanitized name -> Set(raw models) once >1 raw maps to it
-  for (const m of uniqueModels) {
-    const s = sanitizeName(m);
-    if (rawBySanitized.has(s)) {
-      if (!collisionModels.has(s)) { collisionModels.set(s, new Set([rawBySanitized.get(s)])); }
-      collisionModels.get(s).add(m);
-    } else {
-      rawBySanitized.set(s, m);
-    }
-  }
-
-  // ⚠️ Task 18 (RN-1): the collision above is a real run-integrity defect — the run directory
-  // physically holds ONE file where two models' artifacts should be, and no renderer trick can
-  // recover both. What the renderer CAN stop doing is showing model A's prose under model B's
-  // name. Deterministic disambiguation: per colliding sanitized name, sort the RAW models
-  // (sorting, not insertion order, is what keeps this reproducible across processes/runs); the
-  // first (sorted) keeps the bare sanitized name, the rest get `~2`, `~3`, ... The suffixed
-  // names deliberately do not exist on disk — the presence manifest (run-detail.js, via
-  // fs.statSync over this same allowlist) marks them absent, so the renderer shows the honest
-  // "not written yet" empty state for every model but the first, instead of cross-matching.
-  const nameFor = new Map(); // raw model -> its (possibly suffixed) sanitized name
-  for (const m of uniqueModels) {
-    let s = sanitizeName(m);
-    const collision = collisionModels.get(s);
-    if (collision) {
-      const sortedRaw = [...collision].sort();
-      const index = sortedRaw.indexOf(m);
-      if (index > 0) { s = `${s}~${index + 1}`; }
-    }
-    nameFor.set(m, s);
-  }
-
-  for (const m of uniqueModels) {
-    const s = nameFor.get(m);
-    names.push(`review-${s}.md`);
-    names.push(`judge-${s}.md`);
-    // rebuttal-/revote- are keyed on the same BENCH ALIAS through the same (now possibly
-    // suffixed) name — materializeDebate is called with `d.raiser` / the revote leg's model
-    // (both aliases), so a colliding pair's debate artifacts are disambiguated the same way.
-    if (debated) {
-      names.push(`rebuttal-${s}.md`);
-      names.push(`revote-${s}.md`);
-    }
-  }
-  // `uniqueModels` already collapsed genuinely-repeated bench entries, so this final Set is
-  // now just a belt-and-suspenders no-op for names — it can no longer mask a real collision,
-  // since that path is detected above from the RAW (pre-sanitize) values instead.
-  const list = [...new Set(names)];
-  if (collisionModels.size) {
-    list.collisions = [...collisionModels.entries()].map(([sanitized, models]) => ({
-      sanitized, models: [...models],
-    }));
-  }
-  // Consumed by workspace-panels.js (wireLazyPanels' file lists + drillIntoJudge's artifact
-  // lookup), which prefers this map over re-deriving names via sanitizeName(model) directly —
-  // that re-derivation is exactly what would ignore the suffixing above and misattribute prose.
-  // ⚠️ Fix-wave (review finding 1) residual limit this map cannot close: the BARE (unsuffixed)
-  // name is still exactly ONE physical file on disk, and its actual bytes belong to whichever
-  // colliding model's writer ran LAST — no map can recover which one that was. The guarantee
-  // delivered here is narrower than "attribution is fully sound": at most the sorted-first
-  // model can still be misattributed under the bare name; artifactCollisions (the run-integrity
-  // banner rendered by workspace-app.js's renderBanners) is what covers that residual case.
-  list.artifactsByModel = Object.fromEntries(
-    [...nameFor].map(([m, s]) => [m, {
-      review: `review-${s}.md`, judge: `judge-${s}.md`,
-      rebuttal: `rebuttal-${s}.md`, revote: `revote-${s}.md`,
-    }]),
-  );
-  return list;
-}
 
 /**
  * @param {string} project
@@ -241,6 +135,6 @@ function readRunArtifact(project, runId, name, deps = {}) {
 }
 
 module.exports = {
-  artifactAllowlist, readRunArtifact, isRealpathContained,
+  artifactAllowlist, isSeatTable, readRunArtifact, isRealpathContained,
   FIXED_ARTIFACTS, DEBATE_ARTIFACTS, MAX_ARTIFACT_BYTES,
 };