amicus 4.8.1 → 4.9.0

package/src/utils/alias-shadow-writer.js

@@ -0,0 +1,220 @@
+/**
+ * @module utils/alias-shadow-writer
+ * The alias-shadow notice's WRITE half: say it without ever sinking the run.
+ *
+ * EXTRACTED from src/utils/alias-shadow.js (PR #207 round 4). That file already
+ * separated the CHECK (read two alias tables, compare canonical forms) from the
+ * WRITE (get one advisory line onto a stream that may be a closed pipe), and
+ * rounds 2 and 3 put two independent hardenings on the write half alone —
+ * `safeWrite`'s synchronous guard and `armStream`'s asynchronous one. Round 4's
+ * B1 landed a third. The seam was already there; the file was at 286/300, and
+ * shaving the measurement prose that makes these guards auditable would have
+ * been the wrong economy, so the write half moved out whole.
+ *
+ * Nothing here was ever part of `alias-shadow.js`'s `module.exports` — these are
+ * internal helpers, not a public API — so there is no re-export shim and no
+ * import path anywhere in the tree that changes.
+ *
+ * Named mutants live with their red sets in tests/alias-shadow.test.js:
+ * "WRITERFATAL" (drop `safeWrite`'s try/catch), "STREAMFATAL" (drop
+ * `armStream`'s attach-once 'error' handler) and "STREAMDEAF" (round 5 — put
+ * the PURE no-op handler back, so the arming goes deaf to every class again
+ * instead of only the benign one).
+ */
+
+'use strict';
+
+/**
+ * Write a notice without ever letting the writer sink the run (round 2, B1).
+ *
+ * The 'never throws' contract used to cover only the CHECK: the guard wrapped
+ * `findAliasShadows`, so a writer that threw — a caller-supplied collector that
+ * rejects, a stream whose write throws — escaped and killed the launch this
+ * diagnosis exists to protect. Worse, on the failure branch it escaped a second
+ * time, because that branch announced itself through the SAME broken writer. A
+ * notice must never be fatal to what it is describing, so the write is swallowed
+ * here and nowhere else.
+ *
+ * ⚠️ This covers the SYNCHRONOUS half only. A piped stderr fails on a later turn
+ * and never throws from `write()` at all — see `armStream` below, which is the
+ * other half of the same contract.
+ * @param {(line: string) => void} out
+ * @param {string} line
+ */
+function safeWrite(out, line) {
+  try { out(line); } catch { /* a diagnosis must never sink the run it diagnoses */ }
+}
+
+/**
+ * The armed marker, keyed ON THE STREAM (PR #207 round 4, B1).
+ *
+ * It used to be a module-scoped `WeakSet`, which made "attach once" true only
+ * once per MODULE INSTANCE. `jest.resetModules()` builds a fresh registry, the
+ * fresh copy of this module starts with an empty set, and the SAME
+ * `process.stderr` collects a second listener — measured at SEVEN across
+ * tests/alias-shadow.test.js alone, against Node's 10-listener
+ * MaxListenersExceededWarning. That warning is emitted ASYNCHRONOUSLY onto
+ * `process.stderr.write`, which is the method several of this feature's absence
+ * controls replace and exact-match on, so the accumulation was a
+ * nondeterministic flake waiting for two more fixtures. A marker that lives on
+ * the stream is immune: it is the same object either way.
+ *
+ * `Symbol.for`, not `Symbol()`: the well-known-symbol registry is per REALM, so
+ * every instance of this module — reset registry, second resolved path, npx
+ * copy loaded beside a global one — computes the SAME key and therefore agrees
+ * about what is already armed. A module-local `Symbol()` would be a fresh key
+ * per instance and would re-arm exactly like the WeakSet did.
+ *
+ * It also retains nothing: a swapped-out stream (tests do this) is dropped with
+ * its own marker attached, where the WeakSet had to be weak on purpose.
+ */
+const ARMED = Symbol.for('amicus.alias-shadow.armed');
+
+/**
+ * The self-report marker (PR #207 round 5, A3+B2+D1+C2). Same `Symbol.for`
+ * registry discipline, and the same reason, as `ARMED` above: one report per
+ * STREAM, agreed on by every instance of this module.
+ */
+const REPORTED = Symbol.for('amicus.alias-shadow.reported');
+
+/**
+ * Stream failures that mean "the reader went away", and nothing more.
+ *
+ * This is the class the arming exists for: `amicus … | head`, a closed MCP
+ * client, a terminal that went away mid-write. There is nobody left to tell, so
+ * telling is pointless — these are swallowed in silence. Everything else is a
+ * real fault and gets said out loud (see `armStream`).
+ *
+ * `EOF` is here beside `EPIPE` because that is what a severed pipe reports on
+ * Windows, where this is developed; `ERR_STREAM_DESTROYED` and
+ * `ERR_STREAM_WRITE_AFTER_END` are Node's own spellings of the same "the sink is
+ * gone" fact for a destroyed/ended stream.
+ */
+const BENIGN_STREAM_ERRORS = new Set([
+  'EPIPE', 'EOF', 'ERR_STREAM_DESTROYED', 'ERR_STREAM_WRITE_AFTER_END',
+]);
+
+/**
+ * Is this the reader-went-away class? A code-less error is NOT assumed benign —
+ * nothing says it is, and the honest default for an unrecognised fault is to
+ * report it.
+ * @param {*} err
+ */
+function isBenignStreamError(err) {
+  return !!err && BENIGN_STREAM_ERRORS.has(err.code);
+}
+
+/**
+ * Make a stream's write failures non-fatal, once — WITHOUT going deaf (round 3
+ * A1; round 5 A3+B2+D1, and the contested C2, same mechanism).
+ *
+ * MEASURED, node v24.18.0 on Windows, against a REAL closed pipe (parent spawns
+ * a child with `stdio: ['ignore','ignore','pipe']` and destroys the read end;
+ * the child then writes to `process.stderr`):
+ *
+ *   · `write(line)` returns FALSE and throws NOTHING. `safeWrite`'s try/catch
+ *     sees nothing at all. The EPIPE arrives on a LATER turn, as an 'error'
+ *     event; with no listener, EventEmitter throws it, and that throw is an
+ *     uncaughtException that ends the process (measured: exit code 7).
+ *   · Passing a write CALLBACK does NOT fix it. The callback received the EPIPE
+ *     AND the 'error' event still fired unhandled — same exit 7. This is why
+ *     there is no callback here: it would observe the failure without disarming
+ *     it, and read like a guard while being none.
+ *   · Attaching for the duration of the write and detaching after is not merely
+ *     racy, it is always WRONG: delivery is always on a later turn, so the
+ *     detach always wins (measured: exit 7 again, with the handler's own log
+ *     line showing it was removed before the error landed).
+ *   · A persistent listener absorbs it, and a SECOND write raises a SECOND
+ *     'error' — so this must be `on`, never `once`.
+ *
+ * Hence: attach once, per stream object, and leave it.
+ *
+ * ⚠️ THE SCOPE IS THE WHOLE PROCESS, PERMANENTLY, and the round-3 text undersold
+ * it. From the first notice onward this handler receives EVERY 'error' raised on
+ * `process.stderr` by ANY producer in the process — not only the EPIPE from this
+ * feature's own write, and not only for the duration of the notice. It is
+ * sharpest in the MCP server, which imports this in-tree and then outlives every
+ * individual run. A pure no-op there would silently discard unrelated stderr
+ * faults for the life of the server, which is precisely the correct-but-SILENT
+ * degrade the product principle forbids. So the handler DISCRIMINATES: the
+ * benign reader-went-away class above is swallowed, and anything else is
+ * reported through the house logger.
+ *
+ * ⚠️ WHY THE REPORT IS BOUNDED TO ONE. MEASURED: `utils/logger.js` writes with
+ * `console.error`, i.e. onto `process.stderr` — the same stream that just
+ * failed (its own header: "Outputs JSON-formatted logs to stderr"). An unbounded
+ * report could therefore provoke the next 'error', handle it, report again, and
+ * spin the event loop forever — round 3's B1 defect ("the announcement becomes
+ * the next escape") in its asynchronous form. One report per stream, wrapped in
+ * its own try/catch, is what makes speaking up safe. The report is best-effort
+ * BY CONSTRUCTION and is documented as such rather than promised.
+ *
+ * Checked rather than assumed: nothing in src/, bin/ or scripts/ attaches to or
+ * depends on `process.stderr`'s 'error' event (the `.on('error')` hits in the
+ * tree are all on CHILD process streams), and adding a listener removes nobody
+ * else's — any handler another module attaches still runs alongside this one.
+ * `electron/main.js` installs a listener on the same stream for the same
+ * round-3 reason, but its handler is silent for EVERY code; this one
+ * deliberately departs from that precedent for the non-benign class, which is
+ * exactly why the bound above had to exist first.
+ *
+ * ⚠️ Scoped to the module's OWN default writer. An INJECTED writer (every test
+ * collector, and the MCP notices array) never reaches here, so nothing is armed
+ * on its behalf.
+ * @param {NodeJS.WritableStream} stream
+ * @param {(msg: string, ctx: object) => void} [log] the diagnostic seam —
+ *   injected by tests; defaults to the house logger's `error`.
+ */
+function armStream(stream, log) {
+  if (!stream || typeof stream.on !== 'function' || stream[ARMED]) { return; }
+  try {
+    // `configurable` so a test that borrows a real stream can still take it
+    // back; symbol-keyed, so it is invisible to `Object.keys`, `JSON.stringify`
+    // and anything else that walks the stream object we are borrowing.
+    Object.defineProperty(stream, ARMED, { value: true, configurable: true });
+  } catch {
+    // A stream nobody can MARK cannot be armed exactly once, and arming it
+    // without a mark would trade round 3's unhandled-'error' hazard for an
+    // unbounded-listener one on that same stream. Node never freezes
+    // `process.stderr`, so this is a guard, not a path.
+    return;
+  }
+  stream.on('error', (err) => {
+    // The reader went away. Nobody to tell; a diagnosis must never sink the run
+    // it diagnoses, and here it must not natter at a dead pipe either.
+    if (isBenignStreamError(err)) { return; }
+    if (stream[REPORTED]) { return; }
+    try {
+      Object.defineProperty(stream, REPORTED, { value: true, configurable: true });
+    } catch {
+      // Unreachable in practice: `ARMED` was defined on this same object moments
+      // ago, so the object takes symbol properties. Bounded-over-loud if it ever
+      // is reached — an unbounded report is the one failure mode worse than a
+      // missed one.
+      return;
+    }
+    try {
+      const report = log || require('./logger').logger.error;
+      // The message rides in the CONTEXT, not the format string: the logger
+      // JSON.stringifies the entry, and JSON.stringify escapes every C0 byte
+      // (MEASURED: ESC serializes as the six characters \u001b), so its text
+      // cannot repaint a terminal from here the way `formatAliasShadow`'s
+      // config fragments could.
+      report('alias-shadow notice: unexpected error on the notice stream', {
+        code: (err && err.code) || null,
+        error: err && err.message ? String(err.message) : String(err),
+      });
+    } catch { /* a diagnosis must never sink the run it diagnoses */ }
+  });
+}
+
+/** The default writer: stderr, armed against its own asynchronous failure. */
+function writeNoticeToStderr(line) {
+  const stream = process.stderr;
+  armStream(stream);
+  stream.write(line);
+}
+
+// `ARMED` is deliberately NOT exported: it is this module's private marker, and
+// a second holder of the key is a second thing that could clear it.
+module.exports = { safeWrite, armStream, writeNoticeToStderr };

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,10 +113,11 @@ 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 this table is the FLOOR a runner falls back to when no

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

@@ -34,11 +34,8 @@
 
 const HINTS = require('./remediation-hints');
 
-// Mirrors cli-handlers-doctor.js's own MAX_CATALOG_AGE_MS (which itself
-// mirrors model-catalog.js's DEFAULT_MAX_AGE_MS) -- duplicated rather than
-// imported to avoid a require cycle (cli-handlers-doctor.js requires this
-// module at load time, before its own module.exports exists).
-const MAX_CATALOG_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+// 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