amicus 4.6.2 → 4.7.0

package/src/utils/model-fetcher.js

@@ -8,17 +8,19 @@
 const https = require('https');
 
 /**
- * Hardcoded Anthropic models (no public listing endpoint). This is the
- * DIRECT-API floor only — Fable is OpenRouter-only (see curated-models.js
- * DIVERGENT_VENDORS / CARDLESS 'fable' entry, which has no `anthropic` route)
- * and must never appear here: classifyModel() returns 'valid' on a floor HIT
- * before it ever checks `authoritative`, so listing an OR-only model here
- * would mislabel a direct-API request for it as valid.
+ * Hardcoded Anthropic floor: the anthropic/ rows a KEYLESS user (or a
+ * failed live fetch) gets. Every id here must be one the direct API
+ * GENUINELY serves — classifyModel() returns 'valid' on a floor HIT before
+ * it ever checks `authoritative`, so a speculative row would mislabel a
+ * dead direct-API request as valid. (fable joined 2026-08-05 after live
+ * verification — /v1/models lists claude-fable-5 and a direct smoke leg
+ * served; v4.6.3 spec §3.)
  */
 const ANTHROPIC_MODELS = [
   { id: 'anthropic/claude-opus-5', name: 'Claude Opus 5', contextLength: null, pricing: null },
   { id: 'anthropic/claude-opus-4-8', name: 'Claude Opus 4.8', contextLength: null, pricing: null },
   { id: 'anthropic/claude-sonnet-5', name: 'Claude Sonnet 5', contextLength: null, pricing: null },
+  { id: 'anthropic/claude-fable-5', name: 'Claude Fable 5', contextLength: null, pricing: null },
   { id: 'anthropic/claude-haiku-4-5', name: 'Claude Haiku 4.5', contextLength: null, pricing: null },
   // Dated snapshot: the id Anthropic's /v1/models actually lists, and the
   // `haiku` direct route curated-models.js authors. Without it the floor

package/src/utils/remediation-hints.js

@@ -87,6 +87,20 @@ const REMEDIATION_HINTS = Object.freeze({
    */
   sweepSessionIndexTmp:
     'amicus doctor --fix  (sweeps orphaned .sessions-index.json.*.tmp files left by an interrupted write)',
+
+  /**
+   * Orphaned per-session metadata.json.*.tmp files (v4.6.3 PR3 Task 3 / D8):
+   * same producer shape as sweepSessionIndexTmp above, one level down — a
+   * kill between an atomic write's tmp-write and rename leaves a stray temp
+   * file in a session directory forever. `doctor --fix` sweeps files older
+   * than 60s (never a live writer's ms-lived tmp).
+   *
+   * Voice ruling (Christian, 2026-08-03, sweepSessionIndexTmp above): applies
+   * verbatim here — the cause is definitional, not a guess, so this hint also
+   * keeps its confident voice rather than the unverified-cause voice.
+   */
+  sweepSessionMetadataTmp:
+    'amicus doctor --fix  (sweeps orphaned .metadata.json.*.tmp files left by an interrupted write)',
 });
 
 module.exports = REMEDIATION_HINTS;

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

@@ -0,0 +1,156 @@
+// src/utils/session-metadata-tmp-sweep.js
+'use strict';
+
+/**
+ * v4.6.3 PR3 Task 3 (D8): orphaned per-session metadata.json.*.tmp sweep for
+ * `amicus doctor --fix`.
+ *
+ * A kill between writeFileAtomic's tmp-write and rename (any of the ~30
+ * metadata.json write sites — session-manager.js, sidecar/session-finalize.js,
+ * etc.) leaves a stray `.metadata.json.<pid>.<hex>.tmp` file in a session
+ * directory forever (the B09 orphan class). This module lists and removes
+ * them; src/cli-handlers-doctor.js composes the result into a check line.
+ * 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
+ * `<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
+ * point at OTHER projects (issue #40's cross-project fallback exists exactly
+ * because the index can be stale). Trusting it here to decide which
+ * directories a --fix sweep may unlink from risks touching an unrelated
+ * project on stale data — the wrong failure direction for a destructive
+ * operation. Walking the cwd-scoped tree directly can only ever find/remove
+ * files under the project doctor is already running against.
+ *
+ * Symlink safety (Task 3 review carry, v4.6.3 PR3): every stat in this walk
+ * is lstatSync, never statSync — this module never follows symlinks. A
+ * 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');
+const path = require('path');
+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.
+ * 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);
+}
+
+/** True when `basename` is an orphaned metadata tmp file (not e.g. progress.json.*.tmp). */
+function isMetadataTmp(basename) {
+  return basename.startsWith('.metadata.json.') && basename.endsWith('.tmp');
+}
+
+/** List metadata tmp files directly inside `dir`, named relative to `root`. */
+function listTmpIn(dir, root) {
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return []; }
+  return entries
+    .filter(isMetadataTmp)
+    .map((basename) => {
+      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);
+}
+
+/**
+ * List orphaned per-session metadata.json.*.tmp files under the cwd-scoped
+ * sessions root, covering both `<taskId>/` and `<taskId>/subagents/<id>/`.
+ * @returns {Array<{name: string, mtimeMs: number}>}
+ */
+function listSessionMetadataTmpFiles() {
+  const { SUBAGENTS_DIR } = require('../session-manager');
+  const root = sessionsRoot();
+  let taskIds;
+  try { taskIds = fs.readdirSync(root); } catch { return []; }
+  const found = [];
+  for (const taskId of taskIds) {
+    const taskDir = path.join(root, taskId);
+    let stat;
+    try { stat = fs.lstatSync(taskDir); } catch { continue; }
+    if (!stat.isDirectory()) { continue; }
+    found.push(...listTmpIn(taskDir, root));
+
+    const subagentsDir = path.join(taskDir, SUBAGENTS_DIR);
+    let subIds;
+    try { subIds = fs.readdirSync(subagentsDir); } catch { continue; }
+    for (const subId of subIds) {
+      const subDir = path.join(subagentsDir, subId);
+      let subStat;
+      try { subStat = fs.lstatSync(subDir); } catch { continue; }
+      if (!subStat.isDirectory()) { continue; }
+      found.push(...listTmpIn(subDir, root));
+    }
+  }
+  return found;
+}
+
+/** Delete one orphaned tmp file by name (relative to the sessions root; never an absolute/caller path). */
+function unlinkSessionMetadataTmp(name) {
+  const root = sessionsRoot();
+  fs.unlinkSync(path.join(root, name));
+}
+
+/**
+ * Compose the doctor check line for the metadata tmp-orphan sweep. Pure
+ * decision logic (list/sweep side effects come in via `d`); src/cli-handlers-doctor.js
+ * 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';
+  const files = d.listSessionMetadataTmpFiles() || [];
+  if (files.length === 0) {
+    return { id, name, status: 'ok', message: '0 orphaned tmp files', hint: null };
+  }
+  if (!d.fix) {
+    return { id, name, status: 'warn', message: `${files.length} orphaned tmp file(s) — run with --fix`, hint: HINTS.sweepSessionMetadataTmp };
+  }
+  const nowMs = d.now();
+  const sweepable = files.filter((f) => (nowMs - f.mtimeMs) > AGE_THRESHOLD_MS);
+  let swept = 0;
+  for (const f of sweepable) {
+    try { d.unlinkSessionMetadataTmp(f.name); swept += 1; } catch { /* best-effort — report what we got */ }
+  }
+  const remaining = files.length - swept;
+  if (remaining === 0) {
+    const fixFields = swept > 0 ? { fixed: true, fixDetail: `swept ${swept} orphaned session-metadata tmp file(s)` } : {};
+    return { id, name, status: 'ok', message: `swept ${swept} orphaned tmp file(s)`, hint: null, ...fixFields };
+  }
+  return { id, name, status: 'warn', message: `swept ${swept}, ${remaining} remaining (too fresh or unremovable)`, hint: HINTS.sweepSessionMetadataTmp };
+}
+
+module.exports = {
+  AGE_THRESHOLD_MS, listSessionMetadataTmpFiles, unlinkSessionMetadataTmp, evaluateSessionMetadataTmpSweep,
+};

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,