amicus 4.8.0 → 4.9.0

package/src/utils/alias-shadow.js

@@ -0,0 +1,294 @@
+/**
+ * Alias-shadow self-diagnosis — name a local alias that repoints a curated one.
+ *
+ * (v4.9 W13 Task B — BACKLOG C5, #129's own side observation.)
+ *
+ * A user-config alias may repoint a CURATED alias at a different model. When it
+ * does, everything keyed on the alias NAME — per-model operating notes, the
+ * bench a workflow spells, a council preset — quietly describes a model the
+ * alias no longer resolves to. Nothing downstream can recover the fact:
+ * `config.js :: getEffectiveAliases` returns `{...DEFAULT_ALIASES,
+ * ...userAliases}`, so by the time `resolveModel` or
+ * `route-launch.js :: resolveRouteForLaunch` sees an id, the two sources have
+ * already collapsed into one string. That is why the comparison lives here and
+ * reads the two sides SEPARATELY (`loadConfig().aliases` vs `toDefaultAliases()`)
+ * rather than being a line inside the merge.
+ *
+ * ⚠️ DIAGNOSIS ONLY. This module resolves nothing, changes no id, no exit code
+ * and no artifact — a local override winning over the curated pin is the
+ * DOCUMENTED contract (`getEffectiveAliases`: "user wins"). All this does is say
+ * so out loud, once, on stderr.
+ *
+ * Wired at three sites, all measured (see tests/alias-shadow.test.js's header
+ * for the measurement):
+ *   1. `cli-council-run-bench.js :: resolveBench` — the one bench-resolution
+ *      helper BOTH council transports EXECUTE, because `mcp-council-run.js`
+ *      always spawns the CLI child with an expanded `--models` list. The bench,
+ *      the chair (explicit or default) and the critic are all inspected there:
+ *      they resolve through this same table, so a shadow on any of them is
+ *      equally invisible (PR #203 round 1, A6).
+ *   2. `mcp-council-bench.js :: auditBenchAliases`, called by
+ *      `mcp-council-run.js :: handleCouncilRunTool` — the MCP SURFACE (PR #207
+ *      round 2, A1). Site 1 executes on the MCP path but surfaces nothing there
+ *      (see below); this one writes into the tool result's notice array, so the
+ *      client actually sees it. Same three seats, same entry point.
+ *   3. `sidecar/models.js :: runCheck` — `amicus models --check`, the one site
+ *      that passes no name list, so the subject is every CURATED alias the user
+ *      has also configured (PR #207 round 3, B2 — the earlier wording here said
+ *      "the whole configured alias set", which overstates it by the same margin
+ *      the `findAliasShadows` docstring did).
+ *
+ * ⚠️ SURFACE vs EXECUTION, measured (PR #203 round 1 A4; resolved PR #207 round
+ * 2 A1). Site 1 EXECUTES on both transports but SURFACES on only one: the
+ * council child's stderr is not a pipe the MCP server reads. `mcp-server.js ::
+ * spawnSidecarProcess` spawns it with `stdio: ['ignore', 'ignore', <fd>]`, the
+ * fd being an open handle on `<runDir>/debug.log` (or `'ignore'` when that dir
+ * cannot be created), then `unref`s it. So on the CLI the notice lands on the
+ * user's terminal; from site 1 alone an MCP caller would have to open
+ * `<runDir>/debug.log` to find it. Site 2 exists to close exactly that gap, and
+ * it is a different SURFACE rather than a second copy of the same one — the
+ * child still writes its line to `debug.log`, the parent writes its own to the
+ * tool result, and no single surface ever shows it twice. The same limitation
+ * still applies to every OTHER stderr notice the council child writes.
+ *
+ * ⚠️ THE WRITE HALF LIVES NEXT DOOR, in `alias-shadow-writer.js` (round 4). This
+ * file is the CHECK and the RENDERING; that one is `safeWrite`, `armStream` and
+ * the default stderr writer, with the measured Node pipe behaviour they defend
+ * against. Neither was ever exported from here, so the split changed no import
+ * path in the tree.
+ *
+ * Named mutants, all with their red sets recorded in tests/alias-shadow.test.js:
+ * "SHADOWSILENT" (make `noteAliasShadows` a no-op), "GATEWAYFORM" (compare raw
+ * strings instead of canonical forms below), "SCOPESTUCK" (give
+ * `auditAliasShadows` a shared module-global Set instead of a fresh one),
+ * "WRITERFATAL" (drop `safeWrite`'s try/catch — now in alias-shadow-writer.js),
+ * "MCPMUTE" (make `auditBenchAliases` a no-op), "STREAMFATAL" (drop
+ * `armStream`'s attach-once 'error' handler — round 3, A1, also next door),
+ * "MESSAGERAW" (interpolate `err.message` straight into the failure line again —
+ * round 3, B1), "NOTICERAW" (interpolate the config-sourced fragments into
+ * `formatAliasShadow`'s template unsanitized — round 4, A1), "THROWNRAW" (drop
+ * `describeThrown`'s sanitizing pass, leaving the FAILURE line raw and unbounded
+ * — round 5, C1) and "STREAMDEAF" (put `armStream`'s pure no-op handler back, so
+ * the arming goes deaf to every error class again — round 5, A3/B2/D1/C2, in
+ * alias-shadow-writer.js).
+ */
+
+'use strict';
+
+// The WRITE half, extracted in round 4 — `safeWrite` is the synchronous guard,
+// `writeNoticeToStderr` the armed default writer. See that module for the
+// measured Node behaviour both of them exist for.
+const { safeWrite, writeNoticeToStderr } = require('./alias-shadow-writer');
+// The house sanitizer for third-party text — see `formatAliasShadow` for which
+// fragments are third-party and why the pass is per-fragment.
+const { collapseExcerpt } = require('./text-sanitize');
+
+/**
+ * Aliases whose LOCAL (user-config) value differs from the id amicus ships.
+ *
+ * @param {string[]} [names] alias names to inspect — a council bench, typically.
+ *   Members carrying a `/` are full model ids, not aliases, and are skipped;
+ *   members are trimmed and de-duplicated. Omit the argument to inspect every
+ *   CURATED alias, reporting the ones the user has also configured (the
+ *   `models --check` surface).
+ *
+ *   ⚠️ That is narrower than "every alias the user has configured", which is
+ *   what this used to claim (PR #207 round 3, B2), and the narrower scope is the
+ *   CORRECT one: a shadow is by definition a local value standing in front of a
+ *   curated twin, so an alias the curated table never ships has nothing to
+ *   shadow and can never appear here. The same holds for an explicit `names`
+ *   list — a purely local member is silently skipped, not reported.
+ * @returns {Array<{alias: string, local: string, curated: string}>} one row per
+ *   shadowed alias, in the order the names were given.
+ */
+function findAliasShadows(names) {
+  const { loadConfig } = require('./config');
+  const { toDefaultAliases, toCanonicalDefault } = require('./curated-models');
+  const cfg = loadConfig();
+  const userAliases = (cfg && cfg.aliases && typeof cfg.aliases === 'object') ? cfg.aliases : {};
+  // Own keys only: a user config.json can carry a literal `__proto__`/`toString`
+  // key, and bare indexing on a plain object would read Object.prototype — the
+  // same defect class `getEffectiveAliases`'s `__proto__: null` closed.
+  const configured = new Set(Object.keys(userAliases));
+  const curated = toDefaultAliases(); // already null-prototype; safe to index
+  const wanted = Array.isArray(names) ? names : Object.keys(curated);
+  const seen = new Set();
+  const out = [];
+  for (const raw of wanted) {
+    const alias = typeof raw === 'string' ? raw.trim() : '';
+    if (!alias || alias.includes('/') || seen.has(alias)) { continue; }
+    seen.add(alias);
+    if (!configured.has(alias)) { continue; }        // no local override -> silent
+    const local = userAliases[alias];
+    const shipped = curated[alias];
+    if (typeof local !== 'string' || typeof shipped !== 'string') { continue; } // not a curated alias -> silent
+    // Compare CANONICAL forms, not raw strings. A direct-capable vendor's
+    // curated pin is the bare policy-routed id (`openai/gpt-5.6-terra`), so a
+    // config pinning the explicit OpenRouter form of the SAME MODEL differs as a
+    // string and not as a model — the same false positive
+    // `alias-drift.js`/`findDriftedStoredAliases` already guards against, and it
+    // would fire on gpt AND deepseek in this repo's own CI alias map. Gateway
+    // ROUTING has its own audit (`models --check`'s per-gateway section); this
+    // notice speaks only when the alias names a different MODEL. The rows still
+    // report both sides RAW, so the user can grep their own config.
+    if (toCanonicalDefault(local) === toCanonicalDefault(shipped)) { continue; }
+    out.push({ alias, local, curated: shipped });
+  }
+  return out;
+}
+
+/**
+ * How much of one quoted config fragment ever reaches the line. MEASURED: the
+ * longest id the curated table ships is 39 characters
+ * (`openrouter/mistralai/mistral-medium-3-5`) and the longest alias name is 10;
+ * past 64 this is not a model id, it is a payload.
+ */
+const MAX_FRAGMENT_CHARS = 64;
+
+/** One quoted config fragment, safe to paste into the line below. */
+const safeFragment = (value) => collapseExcerpt(value, MAX_FRAGMENT_CHARS);
+
+/**
+ * The notice, with everything it QUOTES neutralized (PR #207 round 4, A1).
+ *
+ * This line quotes the user's `config.json` onto a terminal and into the MCP
+ * tool result, so each quoted value is third-party text and rides the house
+ * sanitizer — `utils/text-sanitize.js :: collapseExcerpt`, the same one
+ * `engine-skew.js :: safeVersion` uses at its own cap, for the same reason. ANSI
+ * and bidi controls are dropped, remaining control bytes collapse to spaces, and
+ * the result is one bounded line: a config value can no longer repaint the
+ * terminal, forge a SECOND `Notice:` line after the newline it smuggled in, or
+ * reverse the sentence it is quoted into.
+ *
+ * ⚠️ THE FRAGMENTS, NOT THE COMPOSED LINE. `collapseExcerpt` trims and caps
+ * whatever it is given, so passing the finished string would eat the trailing
+ * newline both writers depend on and could clip `(curated ships …)` off the end.
+ * The quotes, the parens and that newline are OURS; only the values are theirs.
+ *
+ * ⚠️ MEASURED, which fragment is actually hostile-capable: `local` is a raw
+ * config VALUE and is the hole. `alias` is user-supplied too, but a row exists
+ * only when the name is byte-identical to a key of the null-prototype curated
+ * table, and all 21 shipped names measure `/^[a-z0-9.-]+$/` — an escape-carrying
+ * name never becomes a row at all (pinned as an absence control). `curated` is
+ * house data. All three go through anyway: "this notice is one line, and its
+ * structure is ours" should not depend on that chain of reasoning surviving the
+ * next change to the curated table.
+ *
+ * ⚠️ The ROWS `findAliasShadows` returns stay RAW on purpose (see its docstring)
+ * — this is a RENDERING pass, and a caller diffing a row against the config file
+ * still sees the bytes that are actually in it.
+ * @param {{alias: string, local: string, curated: string}} s
+ * @returns {string}
+ */
+function formatAliasShadow(s) {
+  return `Notice: alias '${safeFragment(s.alias)}' resolves to ${safeFragment(s.local)} `
+    + `(curated ships ${safeFragment(s.curated)})\n`;
+}
+
+/**
+ * Describe a caught throw without becoming the next one (PR #207 round 3, B1).
+ *
+ * The failure branch below used to interpolate `err.message` directly, so the
+ * template was evaluated BEFORE `safeWrite` ever ran: a thrown `null` or
+ * `undefined` raised a fresh TypeError inside the catch and escaped
+ * `noteAliasShadows` entirely — the exact failure the catch exists to prevent,
+ * re-entering through the catch's own announcement. A thrown bare string was the
+ * quieter half: strings carry no `.message`, so a real reason printed as
+ * `(undefined)`.
+ *
+ * ⚠️ `String(x)` is not total either — MEASURED: `String(Object.create(null))`
+ * throws `TypeError: Cannot convert object to primitive value` — so the
+ * conversion carries its own guard. Nothing in a catch block may throw,
+ * including the code that describes what was caught.
+ *
+ * ⚠️ AND IT IS THIRD-PARTY TEXT (PR #207 round 5, C1). Round 3 made this total;
+ * round 4 sanitized the SHADOW notice's fragments and left this one's result
+ * raw, so the FAILURE line still pasted an arbitrary thrown message —
+ * unsanitized and unbounded — onto a terminal and into an MCP tool result. A
+ * thrown value is not house data: it carries provider text, a filesystem path,
+ * or the user's own config file (the case that motivated round 4). Same
+ * `collapseExcerpt` pass, same reasons, one function later.
+ *
+ * ⚠️ THE CAP IS THE HOUSE DEFAULT (200), NOT `MAX_FRAGMENT_CHARS` (64). Both are
+ * the same discipline — a caller sizing the cap to what its field legitimately
+ * holds, as `engine-skew.js :: safeVersion` does at 32 — and the two fields are
+ * not the same kind of text. A fragment is a MODEL ID (measured longest: 39), so
+ * 64 bounds it with room to spare. A thrown message is a SENTENCE: `EACCES:
+ * permission denied, open 'C:\\Users\\…\\config.json'` already exceeds 64, and
+ * clipping there would bound the payload by destroying the diagnosis. 200 is
+ * what `text-sanitize.js` documents as "long enough for a real engine error",
+ * and it leaves this composed line the same order of magnitude as the shadow
+ * line's three 64-char fragments.
+ *
+ * The pass runs INSIDE the try, so a value whose `String()` throws still lands
+ * in the catch rather than escaping through the sanitizer's argument.
+ * @param {*} err whatever was thrown — an Error, a string, null, anything.
+ * @returns {string} one bounded line, safe to paste into the notice.
+ */
+function describeThrown(err) {
+  try { return collapseExcerpt(String((err && err.message) || err)); }
+  catch { return 'unprintable error'; }
+}
+
+/**
+ * Say it once per SCOPE. Never throws — not the check, not the write, and (round
+ * 3, A1) not the write's own delayed failure either.
+ *
+ * It never degrades SILENTLY either: a failed check announces its own failure.
+ * That is not defensive decoration. During this task's own development the
+ * guard swallowed a real `TypeError: loadConfig is not a function` (a leaked
+ * module mock in tests/sidecar/models-command.test.js) and the feature simply
+ * went quiet, which is precisely the correct-but-silent degrade the product
+ * principle forbids.
+ *
+ * ⚠️ The dedup scope is the caller's, passed in (PR #207 council round 2, B3).
+ * It used to be a module-global `spoken` Set that `auditAliasShadows` cleared
+ * wholesale — so one caller's dedup state was reachable, and erasable, by every
+ * other caller in the process. There is no module-global state here now: two
+ * scope-less calls are two independent scopes.
+ * @param {string[]} [names] see findAliasShadows
+ * @param {(line: string) => void} [write] injected for tests; defaults to stderr
+ *   so a `--json` document on stdout stays byte-clean.
+ * @param {Set<string>} [scope] alias names already spoken. Omit for a fresh
+ *   one-shot scope; pass a shared Set to collapse several calls into one run.
+ */
+function noteAliasShadows(names, write, scope) {
+  const out = write || writeNoticeToStderr;
+  const spoken = scope instanceof Set ? scope : new Set();
+  try {
+    for (const s of findAliasShadows(names)) {
+      if (spoken.has(s.alias)) { continue; }
+      spoken.add(s.alias);
+      safeWrite(out, formatAliasShadow(s));
+    }
+  } catch (err) {
+    // `describeThrown` FIRST, and outside the template, so the announcement
+    // cannot become the second escape (round 3, B1).
+    const why = describeThrown(err);
+    safeWrite(out, `Notice: could not check whether local aliases shadow the curated table (${why})\n`);
+  }
+}
+
+/**
+ * THE WIRING ENTRY POINT: open a fresh notice scope, then speak.
+ *
+ * Every wired site calls this and nothing else, in ONE statement, so the scope
+ * can never be opened by one caller and forgotten by the next — a two-step
+ * "reset, then note" would have made the A5 defect re-introducible by omission,
+ * which for a self-diagnosis feature means going quiet with a green suite.
+ *
+ * PR #203 A5 asked for a re-openable scope; round 2 (B3) supplied the shape
+ * that makes it structural rather than disciplined: the fresh `Set` IS the
+ * scope, so there is no shared latch to get stuck and none to clear.
+ * `noteAliasShadows` stays exported as the scope-respecting primitive (two
+ * calls sharing one scope still produce one line per alias).
+ * @param {string[]} [names] see findAliasShadows
+ * @param {(line: string) => void} [write] see noteAliasShadows
+ */
+function auditAliasShadows(names, write) {
+  noteAliasShadows(names, write, new Set());
+}
+
+module.exports = {
+  findAliasShadows, formatAliasShadow, noteAliasShadows, auditAliasShadows,
+};

package/src/utils/config.js

@@ -244,7 +244,7 @@ function getEffectiveAliases() {
   // 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
+  // `report-cost.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;

package/src/utils/curated-models.js

@@ -98,7 +98,14 @@ const CARDLESS = [
   // (live smoke wave 47278069) — the entry was OpenRouter-only at authoring.
   { alias: 'fable', routes: { openrouter: 'openrouter/anthropic/claude-fable-5',
                               anthropic: 'anthropic/claude-fable-5' } },
-  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.7-max' } },
+  // qwen/kimi refreshed 2026-08-26 (v4.9 W13): both were a model generation
+  // behind. These are the FALLBACK FLOOR — a caller or fork with no CI alias map
+  // resolves its whole bench through this table (see `inkling` below), while the
+  // owner's machine and .github/amicus-ci-aliases.json already ran the newer ids.
+  // Cardless entries have no `idPattern`, so `models --check` can only ask
+  // whether the OLD id still EXISTS — which is how a pin sits a generation back
+  // with every gate green (scripts/check-ci-alias-pins.js asks the other one).
+  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.8-max' } },
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
   { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
   { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-medium-3-5' } },
@@ -106,17 +113,18 @@ const CARDLESS = [
   // whole devstral family and the alias had no other route. No retarget — no
   // served model is a devstral successor ("no pinned guess is better than a
   // wrong one"); `mistral` remains the vendor's alias.
-  { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5.1' } },
+  { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5.3' } },
   { alias: 'minimax', routes: { openrouter: 'openrouter/minimax/minimax-m2.7' } },
   { alias: 'grok', routes: { openrouter: 'openrouter/x-ai/grok-4.3' } },
-  { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.6' } },
+  // kimi: see the qwen refresh note above (both moved 2026-08-26, v4.9 W13).
+  { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k3' } },
   { 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).
+  // names it, and this table is the FLOOR a runner falls back to when no
+  // alias map is provisioned (workflow_call callers, forks) — there, a
+  // locally defined alias still resolves to nothing. Pinned to the full
+  // model, not `inkling-small`: the bench seat wants the flagship's
+  // judgment. `:batch` is not pinned (wrong for an interactive council leg).
   { alias: 'inkling', routes: { openrouter: 'openrouter/thinkingmachines/inkling' } },
 ];
 

package/src/utils/degrade.js

@@ -2,8 +2,8 @@
 
 /**
  * @module utils/degrade
- * The degrade/heal record: one shape, one vocabulary, shared by the council
- * runtime and `doctor`. Pure — no I/O, no council knowledge.
+ * The degrade/heal/info record: one shape, one vocabulary, shared by the
+ * council runtime and `doctor`. Pure — no I/O, no council knowledge.
  *
  * WHY validation lives here and THROWS: it is what makes the announcement
  * contract real. A degrade that does not say what was lost, why, and what it
@@ -17,6 +17,8 @@ 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.9 task mode: a task run writes no reliability-ledger rows — announced as kind:'info'.
+  'ledger-skipped',
   // 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.
@@ -27,13 +29,16 @@ const DEGRADE_CHANNELS = Object.freeze(new Set([
   'doctor-check-failed', 'doctor-fix',
 ]));
 
-const KINDS = Object.freeze(new Set(['degrade', 'heal']));
+// 'info' (v4.9): an announcement that is neither a loss nor a recovery — the
+// sink records and prints it but never flips `degraded` (run-degrade.js gates
+// the flip on kind === 'degrade').
+const KINDS = Object.freeze(new Set(['degrade', 'heal', 'info']));
 const REQUIRED = ['what', 'why', 'effect'];
 
 function makeDegrade(input = {}) {
   const kind = input.kind === undefined ? 'degrade' : input.kind;
   if (!KINDS.has(kind)) {
-    throw new Error(`degrade: unknown kind '${kind}' (expected 'degrade' or 'heal')`);
+    throw new Error(`degrade: unknown kind '${kind}' (expected 'degrade', 'heal', or 'info')`);
   }
   if (!DEGRADE_CHANNELS.has(input.channel)) {
     throw new Error(`degrade: unknown channel '${input.channel}'`);
@@ -66,7 +71,9 @@ function makeDegrade(input = {}) {
  * @returns {string} one line, newline-terminated
  */
 function formatDegrade(record) {
-  const lead = record.kind === 'heal' ? 'Recovered' : 'Notice';
+  // Lead map: degrade → Notice, heal → Recovered, info → Note. Anything else
+  // (a legacy JSON-parsed record with no kind) keeps the pre-info default, Notice.
+  const lead = record.kind === 'heal' ? 'Recovered' : record.kind === 'info' ? 'Note' : 'Notice';
   const remedy = record.remedy ? ` Try: ${record.remedy}.` : '';
   return `${lead}: ${record.what} — ${record.why}. ${record.effect}.${remedy}\n`;
 }

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

@@ -0,0 +1,149 @@
+// src/utils/doctor-alias-check.js
+'use strict';
+
+/**
+ * @module utils/doctor-alias-check
+ * The `aliases` doctor check ("Model aliases"), split out of
+ * src/cli-handlers-doctor.js to keep that file under the 300-line gate
+ * (mirrors doctor-engine-check.js / doctor-electron-mcp-check.js /
+ * doctor-base-url-check.js / doctor-local-providers-check.js -- same reason,
+ * a different check).
+ *
+ * B3 (council review of PR 198, issue 195): `doctor --fix` repairs exactly
+ * one narrow class of stored alias -- see alias-audit.js's
+ * `findFabricatedAliasRepairs` for the detection rule (classifies `invalid`
+ * on the `direct` gateway AND has an unambiguous OpenRouter twin) and why it
+ * cannot false-positive a typo, a retired model, or a user-invented id.
+ * Repair = rewrite `config.aliases[alias]` to that catalog-confirmed
+ * OpenRouter id -- read-modify-write, no-clobber (mirrors
+ * `applyProviderDefault`, provider-default-picker.js). Every OTHER
+ * stale/drifted alias is left untouched and stays a warning, hinting at
+ * `amicus models --check` same as before this PR.
+ *
+ * A3 (council review of PR 198): the repair ACTION additionally requires the
+ * cached catalog to be FRESH (same `MAX_CATALOG_AGE_MS` window as doctor's
+ * own `catalog` check, cli-handlers-doctor.js). `readCache()` here reads the
+ * exact same cache doctor's `catalog` check may independently report as
+ * `stale (Nh old)` -- without this gate, `--fix` would rewrite a user's
+ * config from data the SAME run just called untrustworthy. A stale catalog
+ * can be missing rows that would make a "fabricated" id look repairable when
+ * it is merely unfetched, so a stale catalog declines the repair (explaining
+ * why via `repairFabricatedAliasStaleCatalog`) rather than writing on
+ * unverified evidence; detection/reporting is unaffected either way.
+ */
+
+const HINTS = require('./remediation-hints');
+
+// Single source: model-catalog.js's DEFAULT_MAX_AGE_MS -- the same 24h window as doctor's own `catalog` check.
+const MAX_CATALOG_AGE_MS = require('./model-catalog').DEFAULT_MAX_AGE_MS;
+
+/**
+ * @param {{fetchedAt?: number}|null} cache
+ * @returns {boolean} true when `cache` exists, has a numeric `fetchedAt`, and
+ *   is no older than `MAX_CATALOG_AGE_MS` -- the same test doctor's `catalog`
+ *   check applies to decide `ok` vs `stale (Nh old)`.
+ */
+function isCatalogFresh(cache) {
+  if (!cache || typeof cache.fetchedAt !== 'number') { return false; }
+  return (Date.now() - cache.fetchedAt) <= MAX_CATALOG_AGE_MS;
+}
+
+/**
+ * Rewrite one alias's stored value in place. Read-modify-write / no-clobber
+ * -- preserves `config.default` and every other alias/key (same contract as
+ * `applyProviderDefault`, provider-default-picker.js).
+ * @param {string} alias
+ * @param {string} newId verbatim catalog id (an OpenRouter-namespace id from
+ *   `pairAcrossGateways` -- never hand-derived by string concatenation)
+ */
+function repairAlias(alias, newId) {
+  const { loadConfig, saveConfig } = require('./config');
+  const config = loadConfig() || {};
+  if (!config.aliases || typeof config.aliases !== 'object') { config.aliases = {}; }
+  config.aliases[alias] = newId;
+  saveConfig(config);
+}
+
+/** One pass: sources + both existing audits + the repairable set, over the same catalog. */
+function computeState(d, catalog) {
+  const sources = d.collectAliasSources();
+  return {
+    sources,
+    stale: d.findStaleAliases(sources, catalog),
+    drifted: d.findDriftedStoredAliases(sources, catalog),
+    repairable: d.findFabricatedAliasRepairs(sources, catalog),
+  };
+}
+
+/**
+ * @param {{readCache: () => ({models?: Array}|null), collectAliasSources: () => Array,
+ *   findStaleAliases: (s:Array, c:Array) => Array, findDriftedStoredAliases: (s:Array, c:Array) => Array,
+ *   findFabricatedAliasRepairs: (s:Array, c:Array) => Array<{alias:string,oldId:string,newId:string}>,
+ *   fix?: boolean, repairAlias?: (alias:string, newId:string) => void}} d
+ * @returns {{id,name,status,message,hint,fixed?,fixDetail?}}
+ */
+function evaluateAliasesCheck(d) {
+  const id = 'aliases';
+  const name = 'Model aliases';
+  const cache = d.readCache();
+  const catalog = (cache && cache.models) || [];
+  const catalogFresh = isCatalogFresh(cache);
+
+  let state = computeState(d, catalog);
+  let fixFields = {};
+
+  // Only under --fix, only when there is something in the narrow,
+  // mechanically-unambiguous class to repair (rule 1), and only on a FRESH
+  // catalog (A3) -- a failed individual rewrite is best-effort -- it simply
+  // stays a warning, same as one findStaleAliases could never resolve.
+  if (d.fix && state.repairable.length > 0 && catalogFresh) {
+    const repaired = [];
+    for (const r of state.repairable) {
+      try { d.repairAlias(r.alias, r.newId); repaired.push(r); }
+      catch { /* best-effort -- an unrepaired alias just stays a warning below */ }
+    }
+    if (repaired.length > 0) {
+      // Rule 6: announce every repair, naming the alias and both ids -- this
+      // fixDetail flows into the 'heal' degrade's `why` field (doctor-degrade.js).
+      const detail = repaired.map((r) => `'${r.alias}' (${r.oldId} -> ${r.newId})`).join('; ');
+      fixFields = {
+        fixed: true,
+        fixDetail: `rewrote ${repaired.length} fabricated alias(es) to its catalog-confirmed OpenRouter id: ${detail}`,
+      };
+      // Rule 5 (idempotency): recompute from a fresh config read so both this
+      // run's message and a second --fix run see the post-repair reality, not
+      // the pre-repair snapshot -- a repaired alias must not still count as
+      // stale/repairable below.
+      state = computeState(d, catalog);
+    }
+  }
+
+  const { stale, drifted, repairable } = state;
+  if (stale.length === 0 && drifted.length === 0) {
+    return {
+      id, name, status: 'ok',
+      message: catalog.length ? 'all resolve' : 'catalog empty — not checked', hint: null,
+      ...fixFields,
+    };
+  }
+  const parts = [];
+  if (stale.length) { parts.push(`${stale.length} stale: ${stale.map((s) => s.alias).join(', ')}`); }
+  if (drifted.length) { parts.push(`${drifted.length} drifted: ${drifted.map((s) => s.alias).join(', ')}`); }
+  // Rule 1: without --fix, report the repairable count and the hint, change
+  // nothing. A3: when the catalog is stale, say so explicitly rather than
+  // offering a fix that will silently decline to write.
+  if (repairable.length) {
+    parts.push(catalogFresh
+      ? `${repairable.length} fixable via doctor --fix`
+      : `${repairable.length} fixable via doctor --fix once the catalog is refreshed (catalog is stale)`);
+  }
+  return {
+    id, name, status: 'warn', message: parts.join('; '),
+    hint: repairable.length === 0
+      ? 'amicus models --check'
+      : (catalogFresh ? HINTS.repairFabricatedAlias : HINTS.repairFabricatedAliasStaleCatalog),
+    ...fixFields,
+  };
+}
+
+module.exports = { evaluateAliasesCheck, repairAlias };