amicus 4.6.3 → 4.7.1

package/src/utils/cli-preflight.js

@@ -40,4 +40,30 @@ function requireValidTaskId(args, useJson, commandLabel, usage) {
   return taskId;
 }
 
-module.exports = { requireNoUiForJson, requireValidTaskId };
+/**
+ * `pack save --version <semver>` can never work, and used to fail SILENTLY:
+ * `version` is a global BOOLEAN_FLAG (src/cli.js), so parseArgs sets
+ * `args.version = true` and drops the semver into positionals, then
+ * bin/amicus.js prints the version banner BEFORE command dispatch — so
+ * `handlePack` never runs and no pack is written, at exit 0. `--version=2.0.0`
+ * fails identically (the inline value is discarded at the isBooleanFlag branch,
+ * ahead of the --key=value branch). The pack's own version is `--pack-version`.
+ *
+ * Returns the failure rather than exiting, so bin/amicus.js keeps one exit site
+ * and this stays unit-testable (bin/amicus.js is a script, not a module).
+ *
+ * @param {object} args - parsed CLI args
+ * @returns {{code: string, message: string, hint: string}|null} null when there is no conflict
+ */
+function packSaveVersionConflict(args) {
+  if (!args || !args.version) { return null; }
+  const argv = Array.isArray(args._) ? args._ : [];
+  if (argv[0] !== 'pack' || argv[1] !== 'save') { return null; }
+  return {
+    code: ERROR_CODES.BAD_ARGS,
+    message: "Error: --version is amicus's own global flag, not the saved pack's version",
+    hint: 'Use --pack-version <semver> to set the version of the pack being saved.',
+  };
+}
+
+module.exports = { requireNoUiForJson, requireValidTaskId, packSaveVersionConflict };

package/src/utils/config.js

@@ -419,6 +419,21 @@ function getCouncilWithSource(name, 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.
+ *
+ *   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
+ *   `{ref, reason}`). The two `reason` literals are produced below, in the
+ *   alias-miss and catalog-miss branches of `classifyCouncilMembers`; they are
+ *   free text, not a coded enum, and today NO consumer branches on the string. They
+ *   are not display-only: `council/presets-cli.js` (`amicus council show`,
+ *   `:149-150`) renders `${member} (${reason})`, `council/run.js` (`:80-87`) carries
+ *   it verbatim into a degrade-note payload, and `reason` is also persisted into
+ *   `run.json` (`run-state.js`, `mcp-council-run.js`) — not merely shown to a human.
+ *   `cli-council-run-bench.js` (`:74`) only type-checks that `reason` is a string
+ *   when round-tripping `--dropped-members` across the MCP→CLI spawn boundary. The
+ *   tripwire: if a THIRD reason string is ever added here, stop and re-decide
+ *   whether `reason` should become a coded enum instead of free text — this note
+ *   marks that decision point, it does not make it.
  */
 function classifyCouncilMembers(members, catalog = []) {
   const aliases = getEffectiveAliases();

package/src/utils/doctor-engine-check.js

@@ -48,6 +48,38 @@ function evaluateEngineInstalls(d) {
 
   const broken = npxCopies.filter((i) => !i.engineOk);
   if (broken.length === 0) {
+    // Version skew (#133): a PRESENT engine can still be the wrong one. The
+    // npx copies and the global install resolve independently and at different
+    // times, and two versions writing one shared opencode.db is what produced
+    // #133's SQLiteError. Compare npx against global ONLY — a genuine source
+    // checkout's engine legitimately differs, so including it would fire red
+    // on every developer machine and in CI (E-1c). Unresolved versions never
+    // signal skew; absence of evidence is not evidence.
+    // WARN, never ERROR: doctor --fix has no skew branch, so an error would be
+    // unfixable, and this file already downgrades to warn at the ambiguous-npx
+    // branch below whenever the copy npx will select is ambiguous.
+    //
+    // Review round 2, finding 1: `kind === 'global'` alone is NOT the whole
+    // baseline. On the documented end-user invocation — `amicus doctor` run
+    // from the globally-installed copy — the running process IS the global
+    // install, so engine-install-scan.js's own dedup drops the separate
+    // `global` record and only `kind:'running'` survives, carrying
+    // `isGlobal: true` instead (see scanEngineInstalls). Without the
+    // `|| i.isGlobal` clause, the skew check was structurally unable to fire
+    // for exactly the users who filed #133. A TRUE source checkout (running,
+    // no isGlobal) is still excluded, as intended.
+    const globalV = (installs.find((i) => i.kind === 'global' || i.isGlobal) || {}).engineVersion;
+    const skewed = globalV
+      ? npxCopies.filter((i) => i.engineVersion && i.engineVersion !== globalV)
+      : [];
+    if (skewed.length > 0) {
+      const detail = skewed.map((i) => `${i.pkgDir} has ${i.engineVersion}`).join('; ');
+      return {
+        id, name, status: 'warn',
+        message: `engine version skew — global install has ${globalV}; ${detail}`,
+        hint: HINTS.engineVersionSkew,
+      };
+    }
     return {
       id, name, status: 'ok',
       message: `engine present in ${npxCopies.length} npx-cache ${plural(npxCopies.length, 'copy', 'copies')}`,

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/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

package/src/utils/result-schema-rebuild.js

@@ -91,6 +91,7 @@ function buildWaveResultFromSession(project, waveId) {
     legs,
     promptMeta: meta.promptMeta || null,
     ...(meta.pack ? { pack: meta.pack } : {}), // v4.5 Task 13: absent-not-null, mirrors promptMeta's sourcing above.
+    ...(meta.tag ? { tag: meta.tag } : {}), // v4.7 F8 (D13): absent-not-null, same idiom as pack above.
     createdAt: meta.createdAt || null,
     completedAt: meta.completedAt || null,
   });

package/src/utils/result-schema.js

@@ -47,6 +47,7 @@ function durationBetween(createdAt, completedAt) {
  * @returns {object} run document; `pack` (v4.5 Task 13) is additive — present only when
  *   metadata.pack was recorded (solo session launched via --pack), sourced straight off
  *   `metadata` like `usage`/`opencodeSessionId` already are (no new function parameter needed).
+ *   `tag` (v4.7 F8/D13) is additive the same way — present only when metadata.tag was recorded.
  */
 function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null, usage = null }) {
   const status = result ? statusFromResult(result) : (metadata.status || 'unknown');
@@ -71,6 +72,7 @@ function buildRunResult({ taskId, metadata = {}, result = null, summary = null,
     opencodeSessionId: metadata.opencodeSessionId || null,
     usage: usage !== null ? usage : (metadata.usage || null),
     ...(metadata.pack ? { pack: metadata.pack } : {}),
+    ...(metadata.tag ? { tag: metadata.tag } : {}),
   };
 }
 
@@ -127,9 +129,11 @@ function waveExitCode(waveStatus) {
  * @param {string[]} [opts.notices] - Advisory per-leg migration notices (#61 FIX 2); never affects status/exitCode.
  * @param {{name: string, version: string, hash: string, source: string}|null} [opts.pack] - v4.5 Task 13:
  *   additive — present only when the wave was launched via --pack (absent, never null, otherwise).
+ * @param {string|null} [opts.tag] - v4.7 F8 (D13): additive — present only when the wave was
+ *   launched via --tag (absent, never null, otherwise).
  * @returns {object} wave document
  */
-function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [], pack = null }) {
+function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [], pack = null, tag = null }) {
   const { sumWaveUsage } = require('./pricing');
   // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
   // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
@@ -157,6 +161,7 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
     usage: sumWaveUsage(legs),
     notices: Array.isArray(notices) ? notices.filter(Boolean) : [],
     ...(pack ? { pack } : {}),
+    ...(tag ? { tag } : {}),
   };
 }
 

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

@@ -33,9 +33,21 @@ function listSessionIndexTmpFiles() {
   return entries
     .filter((name) => name.startsWith(prefix) && name.endsWith('.tmp'))
     .map((name) => {
-      let mtimeMs = null;
-      try { mtimeMs = fs.statSync(path.join(dir, name)).mtimeMs; } catch { /* raced away — skip below */ }
-      return { name, mtimeMs };
+      let st = null;
+      // statSync (not lstatSync) is a DECIDED policy, not an oversight (owner
+      // ruling, v4.7 PR7 — see BACKLOG.md "session-index-tmp-sweep.js follows
+      // symlinks... where its sibling deliberately does not"). This sweep's
+      // targets are index tmp files directly in the flat config dir, never
+      // traversed through a directory an attacker could redirect — unlike
+      // session-metadata-tmp-sweep.js's walk through per-session directories
+      // (see that file's "Symlink safety" paragraph for why THAT sweep must
+      // never follow). Following here means a symlink named like an orphaned
+      // tmp file is still swept (unlink removes only the link); the one real
+      // consequence is AGE_THRESHOLD_MS reading the TARGET's mtime, so a fresh
+      // link to an old file is swept with no grace window. Filed, not fixed —
+      // see the BACKLOG entry above for the full inclusion/unfiled-delta split.
+      try { st = fs.statSync(path.join(dir, name)); } catch { /* raced away */ }
+      return { name, mtimeMs: st && st.isFile() ? st.mtimeMs : null };
     })
     .filter((f) => f.mtimeMs !== null);
 }
@@ -52,6 +64,9 @@ function unlinkSessionIndexTmp(name) {
  * this in guard() the same way it wires the mcp-legacy check's inspect/migrate.
  * @param {{listSessionIndexTmpFiles: () => Array<{name:string, mtimeMs:number}>,
  *   fix?: boolean, now: () => number, unlinkSessionIndexTmp: (name: string) => void}} d
+ * Its four `message` strings are byte-identical to
+ * session-metadata-tmp-sweep.js's evaluateSessionMetadataTmpSweep by design
+ * (only `id`/`name`/`fixDetail` differ) — reword both or neither.
  */
 function evaluateSessionIndexTmpSweep(d) {
   const id = 'sessions-index-tmp'; const name = 'Session index tmp files';

package/src/utils/session-index.js

@@ -94,4 +94,5 @@ module.exports = {
   INDEX_FILENAME,
   recordSession,
   lookupSessionProject,
+  readIndex,
 };

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

@@ -29,6 +29,14 @@
  * symlinked taskId or subagents directory could otherwise be traversed and
  * have files unlinked through the link, effectively outside the sessions
  * root; lstat closes that off at zero cost.
+ *
+ * Consequence of the SR-3 isFile() gate (listTmpIn, below): a SYMLINK whose
+ * basename matches the tmp pattern is now excluded from the list entirely —
+ * neither swept nor reported. Before SR-3 it was swept (unlink removes the
+ * link, never the target — a safe success). Deliberate: this module's
+ * never-follow policy applies to the entries it unlinks too. Note the sibling
+ * session-index-tmp-sweep.js diverges here — it uses statSync, so a
+ * symlink-to-a-file with the matching name IS still swept there.
  */
 
 const fs = require('fs');
@@ -38,7 +46,14 @@ const HINTS = require('./remediation-hints');
 /** Files older than this survive to the next --fix, never a live writer's ms-lived tmp. */
 const AGE_THRESHOLD_MS = 60 * 1000;
 
-/** The cwd-scoped sessions root: <cwd>/.claude/amicus_sessions. */
+/**
+ * The cwd-scoped sessions root: <cwd>/.claude/amicus_sessions.
+ * Reads process.cwd() directly, NOT doctor's injected getCwd
+ * (cli-handlers-doctor.js's realDeps().getCwd) — the
+ * listSessionMetadataTmpFiles/unlinkSessionMetadataTmp deps are wired
+ * argument-free in that same realDeps(), so that seam does not reach here.
+ * Thread cwd through those deps if a `doctor --cwd <dir>` mode ever lands.
+ */
 function sessionsRoot() {
   const { SESSIONS_DIR } = require('../session-manager');
   return path.join(process.cwd(), '.claude', SESSIONS_DIR);
@@ -56,9 +71,9 @@ function listTmpIn(dir, root) {
   return entries
     .filter(isMetadataTmp)
     .map((basename) => {
-      let mtimeMs = null;
-      try { mtimeMs = fs.lstatSync(path.join(dir, basename)).mtimeMs; } catch { /* raced away — skip below */ }
-      return { name: path.relative(root, path.join(dir, basename)), mtimeMs };
+      let st = null;
+      try { st = fs.lstatSync(path.join(dir, basename)); } catch { /* raced away */ }
+      return { name: path.relative(root, path.join(dir, basename)), mtimeMs: st && st.isFile() ? st.mtimeMs : null };
     })
     .filter((f) => f.mtimeMs !== null);
 }
@@ -107,6 +122,11 @@ function unlinkSessionMetadataTmp(name) {
  * wraps this in guard() the same way it wires the sibling sessions-index-tmp check.
  * @param {{listSessionMetadataTmpFiles: () => Array<{name:string, mtimeMs:number}>,
  *   fix?: boolean, now: () => number, unlinkSessionMetadataTmp: (name: string) => void}} d
+ * The four `message` strings below are byte-identical to the index sibling's
+ * (session-index-tmp-sweep.js's evaluateSessionIndexTmpSweep, same four
+ * ok/warn returns) on purpose — `id`/`name` and the `fixDetail` wording are
+ * the only disambiguators between the two rows. Reword one side and the
+ * pairing silently breaks: reword both, or neither.
  */
 function evaluateSessionMetadataTmpSweep(d) {
   const id = 'session-metadata-tmp'; const name = 'Session metadata tmp files';

package/src/utils/spend-ledger.js

@@ -55,13 +55,17 @@ const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
  * @param {string} [opts.councilName] council name (additive attribution)
  * @param {string} [opts.project] project directory (additive attribution)
  * @param {string} [opts.gateway] resolved gateway ('direct'|'openrouter'|'local', additive attribution)
+ * @param {string} [opts.tag] user-chosen tag (v4.7 F8 D16, additive attribution) —
+ *   nullable dim, same null-not-absent convention as councilRunId/project below;
+ *   deliberately the OPPOSITE convention from createSessionMetadata's tag (D13,
+ *   absent-not-null) — see the dim-list comment below.
  * @param {number} [opts.attempt] fallback attempt count (omitted if absent)
  * @param {string} [opts.substitutedFor] substituted model (omitted if absent)
  * @param {string} [opts.retryOfWaveId] wave id being retried (omitted if absent)
  * @param {{dir?:string}} [ctx] test seam — dir overrides getConfigDir()
  */
 function appendSpend({ taskId, waveId, model, mode, usage,
-  op, status, councilRunId, councilName, project, gateway,
+  op, status, councilRunId, councilName, project, gateway, tag,
   attempt, substitutedFor, retryOfWaveId }, ctx = {}) {
   if (!usage) { return; }
   try {
@@ -76,15 +80,18 @@ function appendSpend({ taskId, waveId, model, mode, usage,
       mode: mode || null,
       tokens: usage.tokens || null,
       cost: usage.cost || null,
-      // v4.3 additive attribution (spec 7.1). Nullable dimensions default to
-      // null (so a row is always groupable); linkage fields are OMITTED unless
-      // present (they only exist on fallback/retry rows).
+      // v4.3 additive attribution (spec 7.1), extended v4.7 F8 D16 with `tag`.
+      // Nullable dimensions (op/status/councilRunId/councilName/project/
+      // gateway/tag) default to null (so a row is always groupable); linkage
+      // fields are OMITTED unless present (they only exist on fallback/retry
+      // rows).
       op: op || null,
       status: status || null,
       councilRunId: councilRunId || null,
       councilName: councilName || null,
       project: project || null,
       gateway: gateway || null,
+      tag: tag || null,
     };
     if (attempt !== undefined) { row.attempt = attempt; }
     if (substitutedFor !== undefined) { row.substitutedFor = substitutedFor; }

package/src/utils/validators.js

@@ -24,6 +24,20 @@ const { PROVIDER_KEY_MAP } = require('./provider-registry');
 /** Task ID format: alphanumeric, hyphens, underscores, 1-64 chars */
 const TASK_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
 
+const TAG_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+ * v4.7 F8 (D13): tag validation REJECTS (unlike sanitizeCouncilName, which
+ * cleans) — a stored tag is a user-chosen search key, so silent truncation
+ * or charset-stripping would make `--search`/`--group-by tag` miss it.
+ * Non-string guards the valueless `--tag` parse (cli.js turns it into true).
+ */
+function validateTag(value) {
+  if (typeof value !== 'string' || !TAG_PATTERN.test(value)) {
+    return { ok: false, error: 'Invalid --tag: 1-64 chars, letters/digits/_/- only' };
+  }
+  return { ok: true, tag: value };
+}
+
 /**
  * Validate a task ID format (safe for use in file paths)
  * @param {string} taskId
@@ -249,6 +263,8 @@ module.exports = {
   MODEL_THINKING_SUPPORT,
   TASK_ID_PATTERN,
   validateTaskId,
+  TAG_PATTERN,
+  validateTag,
   safeSessionDir,
   validatePromptContent,
   validateCwdPath,