amicus 4.8.0 → 4.9.0

package/src/sidecar/setup.js

@@ -353,6 +353,73 @@ async function printDoctorFinale(deps = {}) {
   }
 }
 
+/**
+ * #138 second level: after a family pick, let the user name a SPECIFIC model
+ * from that vendor. Returns the chosen catalog id, or null to keep the
+ * family default (bare Enter, an empty shortlist, or two invalid entries).
+ *
+ * The prompt deliberately avoids the substring "Pick a number":
+ * tests/sidecar/setup.test.js:392,475 branch on that literal and would
+ * answer '' here, leaving new coverage green but vacuous.
+ * @param {(q: string) => Promise<string>} ask
+ * @param {(line: string) => void} print
+ * @param {{suggested: Array<object>, rest: Array<object>, total: number}} shortlist
+ * @param {string} vendorPath
+ * @returns {Promise<string|null>}
+ */
+async function promptForVendorModel(ask, print, shortlist, vendorPath) {
+  if (!shortlist || shortlist.total === 0) { return null; }
+
+  let visible = shortlist.suggested;
+  const fmt = (r, i) => {
+    const price = r.pricePerMInput === null ? 'n/a' : `$${r.pricePerMInput.toFixed(2)}/M in`;
+    const ctx = r.contextLength === null || r.contextLength === undefined ? '' : ` · ctx ${r.contextLength}`;
+    return `  ${i + 1}) ${r.id}${ctx} · ${price}${r.isRecommended ? '  (recommended)' : ''}`;
+  };
+
+  const render = () => {
+    print('');
+    print(`Which ${vendorPath} model?`);
+    visible.forEach((r, i) => print(fmt(r, i)));
+    if (visible.length < shortlist.total) {
+      print(`  … ${shortlist.total - visible.length} more`);
+    }
+    print('');
+  };
+  render();
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const hint = visible.length < shortlist.total ? ", 'a' for all" : '';
+    const answer = (await ask(
+      `Choose 1-${visible.length}${hint}, a full model id, or Enter to keep the default: `
+    ) || '').trim();
+
+    if (answer === '') { return null; }
+    if (answer.toLowerCase() === 'a' && visible.length < shortlist.total) {
+      visible = shortlist.suggested.concat(shortlist.rest);
+      render();
+      attempt--; // expanding the list is not a failed attempt
+      continue;
+    }
+    if (/^\d+$/.test(answer)) {
+      const n = Number.parseInt(answer, 10);
+      if (n >= 1 && n <= visible.length) { return visible[n - 1].id; }
+    }
+    if (answer.includes('/')) { return answer; }
+    // F1 (council review, PR 196): the final attempt used to fall through
+    // silently -- the loop just exited and the caller kept the family
+    // default with no feedback at all, so the user's last keystroke
+    // visibly did nothing. Both attempts now print, but the last one also
+    // states the consequence instead of implying a further retry.
+    if (attempt === 0) {
+      print(`Invalid choice: "${answer}".`);
+    } else {
+      print(`Invalid choice: "${answer}". Keeping the family default.`);
+    }
+  }
+  return null;
+}
+
 /**
  * Run the readline-based setup wizard (headless fallback)
  *
@@ -486,6 +553,62 @@ async function runReadlineSetup() {
         const fallback = getDefaultAliases()[chosen.alias];
         if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }
       }
+
+      // #138: offer the family -> model second level. `pick.vendorPath` is
+      // the vendor whose catalog rows we drill into; a chosen id REPLACES
+      // the flagship route for this alias only. Guarded — a picker failure
+      // must never abort a setup run that has already collected keys.
+      //
+      // R4a (fix round 2, supersedes R4's noUpgrade disjunct; wording
+      // corrected in the F7 fix wave -- the previous wording claimed the
+      // governing rule was "never ask about the same vendor twice in one
+      // run", which this guard cannot implement and does not):
+      //
+      // `vendorAliasesWritten` holds PROVIDER names (runProviderDefaultPickers
+      // adds each entry of `foundKeys`, e.g. 'google'/'openai'/'anthropic'/
+      // 'deepseek'), while `chosen.alias` is a FAMILY ALIAS name ('gemini',
+      // 'gemini-pro', 'gpt', 'opus', 'deepseek'). The two prompts write
+      // DIFFERENT config keys -- the per-provider picker writes
+      // `config.aliases[provider]` (e.g. `aliases.google`), this drill-down
+      // writes `config.aliases[chosen.alias]` (e.g. `aliases.gemini`) -- so
+      // `!vendorAliasesWritten.has(chosen.alias)` only skips the drill-down
+      // when the alias STRING happens to collide with an already-written
+      // provider name. Today that's 'deepseek' alone (alias 'deepseek' ===
+      // provider 'deepseek'); every other family alias never collides, so
+      // this drill-down still fires for those even after the per-provider
+      // phase ran for that family's vendor -- correctly: the two prompts
+      // bind different keys, they are not "the same vendor twice".
+      //
+      // TRAP: re-keying this guard to `pick.vendorPath` (so it tests the
+      // actual vendor instead of the alias-name coincidence) looks like the
+      // obvious fix for the mismatch above and is NOT one -- it was
+      // measured to delete issue 138's feature entirely for every user
+      // holding a direct key, by skipping the drill-down for every family
+      // whose per-provider picker already ran this session. Leave this
+      // guard exactly as it is.
+      //
+      // `chosen.noUpgrade` does NOT imply no question was asked for this
+      // vendor: a user can type a known alias name (noUpgrade=true) for a
+      // vendor the per-provider phase already walked through this run, and
+      // that must still be skipped. Whenever noUpgrade is true AND the
+      // alias is genuinely unasked-about, `!vendorAliasesWritten.has(...)`
+      // is already true on its own, so dropping the noUpgrade disjunct
+      // loses no legitimate firing case -- only the double-ask.
+      if (pick && !vendorAliasesWritten.has(chosen.alias)) {
+        try {
+          const { buildModelShortlist } = require('../utils/model-shortlist');
+          const shortlist = buildModelShortlist(pick.vendorPath, {
+            catalog,
+            recommendedId: cfg.aliases[chosen.alias],
+          });
+          const specific = await promptForVendorModel(
+            askQuestion.bind(null, rl), console.log, shortlist, pick.vendorPath
+          );
+          if (specific) { cfg.aliases[chosen.alias] = specific; }
+        } catch (err) {
+          console.log(`Note: couldn't list ${pick.vendorPath} models (${err.message}).`);
+        }
+      }
     } else {
       cfg.default = chosen.modelId;
     }
@@ -613,6 +736,7 @@ module.exports = {
   createDefaultConfig,
   deriveFreeAlias,
   detectApiKeys,
+  promptForVendorModel,
   runFreeCouncilBranch,
   runInteractiveSetup,
   runReadlineSetup,

package/src/template/render.js

@@ -14,12 +14,25 @@
  */
 
 const VAR_RE = /\{\{\s*([A-Za-z_][\w.]*)\s*\}\}/g;
+// Single source: validation and rendering both derive from this set — adding an
+// entry here is sufficient for both. A simple variable {{foo_bar}} reads
+// data.fooBar (snake_case slot, camelCase data key).
 const KNOWN_VARIABLES = ['prompt', 'artifact', 'artifact_path', 'date', 'project', 'var.<key>'];
 
 function knownList() {
   return KNOWN_VARIABLES.map((v) => `{{${v}}}`).join(', ');
 }
 
+function isSimpleVariable(name) {
+  // Reads KNOWN_VARIABLES live, not a load-time copy, so extending the
+  // exported set is sufficient (VAR_RE can never match the 'var.<key>' entry).
+  return name !== 'var.<key>' && KNOWN_VARIABLES.includes(name);
+}
+
+function dataKeyFor(name) {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
 /**
  * Render a template with strict typo-safety rules:
  * unknown variable -> error; slot present without its data -> error; data
@@ -46,7 +59,7 @@ function renderTemplate(text, data) {
       }
       continue;
     }
-    if (!['prompt', 'artifact', 'artifact_path', 'date', 'project'].includes(name)) {
+    if (!isSimpleVariable(name)) {
       return { error: `Error: Unknown template variable {{${name}}}. Known: ${knownList()}` };
     }
   }
@@ -76,12 +89,8 @@ function renderTemplate(text, data) {
   }
 
   const rendered = String(text).replace(VAR_RE, (_, name) => {
-    if (name === 'prompt') { return data.prompt; }
-    if (name === 'artifact') { return data.artifact; }
-    if (name === 'artifact_path') { return data.artifactPath; }
-    if (name === 'date') { return data.date; }
-    if (name === 'project') { return data.project; }
-    return vars[name.slice(4)];
+    if (name.startsWith('var.')) { return vars[name.slice(4)]; }
+    return data[dataKeyFor(name)];
   });
 
   return { text: rendered, notices };

package/src/utils/alias-audit.js

@@ -1,10 +1,21 @@
 /**
- * Alias Audit (F5) — report + suggest, never auto-repair.
+ * Alias Audit (F5) — report + suggest for most classes; doctor --fix auto-repairs one narrow, mechanically-unambiguous class (B3).
  *
  * Finds aliases/routes pointing at models absent from the catalog and
  * suggests current same-vendor replacements. Pure functions over inputs;
  * collectAliasSources() does the gathering. Consumed by `amicus models
  * --check` and the npm wrapper scripts.
+ *
+ * `findFabricatedAliasRepairs()` (B3, council review of PR 198) is the one
+ * exception to "never auto-repair": it detects the single class `doctor
+ * --fix` can safely rewrite unattended -- a bare id `classifyModel` proves
+ * `invalid` on the `direct` gateway AND for which the catalog holds an
+ * unambiguous OpenRouter twin (`pairAcrossGateways`, never string
+ * concatenation) -- still pure detection here; the actual write lives in
+ * `doctor-alias-check.js`'s `repairAlias()`. Every OTHER class this module
+ * finds (typo, retired model, ambiguous twin, drifted-but-live) stays
+ * report-and-suggest only, same as before -- this module does not become a
+ * general auto-repair tool.
  */
 
 'use strict';
@@ -132,7 +143,10 @@ function suggestReplacements(staleModel, catalog, n = 3) {
  * fresh `amicus setup` would seed today — the v4.6.1 release-gate class
  * (stored `gemini` -> 3.1-flash-lite-preview: still catalog-listed so
  * findStaleAliases passes it, no longer what the family resolves to).
- * Report + suggest, never auto-repair (this module's charter).
+ * Report + suggest only -- unlike `findFabricatedAliasRepairs` below (B3's
+ * narrow, mechanically-unambiguous exception), THIS function never
+ * auto-repairs: a drifted-but-live target has no single unambiguous
+ * "correct" answer to converge on the way a fabricated id does.
  *
  * Only user-config rows are checked (defaults/curated follow the catalog by
  * construction), only for aliases that are quick-pick families (a custom
@@ -178,4 +192,68 @@ function findDriftedStoredAliases(sources, catalog) {
     .map(({ alias, model }) => ({ alias, stored: model, current: current.get(alias).display }));
 }
 
-module.exports = { collectAliasSources, findStaleAliases, findDriftedStoredAliases, suggestReplacements };
+/**
+ * B3 (council review of PR 198, issue 195): the narrow, mechanically-
+ * unambiguous class of stored alias `doctor --fix` may repair -- a bare
+ * `<vendor>/<model>` id in a 'user-config' row (what's actually persisted to
+ * `config.aliases`, the only source a repair can rewrite) that
+ * `classifyModel` proves `invalid` on the `direct` gateway AND for which the
+ * catalog contains an unambiguous OpenRouter twin (`pairAcrossGateways` --
+ * never string-concatenation). This is exactly the class the pre-fix
+ * v4.8.0 `chooseRowId`/`applyProviderDefault` could persist (an unconditional
+ * `openrouter/` strip with no catalog evidence); PR 198's
+ * `directFormIfProven` (model-canonicalization.js) now refuses to write it
+ * going forward, so this function finds the ones already ON DISK and
+ * converges them onto the same OpenRouter-prefixed answer the picker would
+ * offer today, rather than inventing a third one.
+ *
+ * Deliberately narrower than findStaleAliases: a typo'd, retired, or
+ * user-invented id also classifies `invalid`, but `pairAcrossGateways` can
+ * only find a twin when the extracted vendor + version token names a REAL
+ * model that still exists, under that exact normalized name, in the
+ * catalog's OpenRouter namespace -- a typo or a genuinely dead model can
+ * never satisfy that. Ambiguous (>1 match) or absent twins are left
+ * untouched -- still reported as stale by findStaleAliases, never repaired.
+ *
+ * DIVERGENT_VENDORS (e.g. anthropic) are excluded on purpose:
+ * model-canonicalization.js gates that set FIRST and unconditionally, so its
+ * predicates never strip a divergent vendor's prefix in the first place --
+ * a bare divergent-vendor alias could not have been produced by the bug
+ * this repairs, so treating one as fabricated here would be inventing a new
+ * class, not converging on the picker's own answer.
+ *
+ * Empty/absent catalog -> [] : classifyModel can only return 'unknown' with
+ * no catalog rows, and 'unknown' never authorises a repair -- no positive
+ * evidence, no write.
+ * @param {Array<{alias:string,model:string,source:string}>} sources
+ * @param {Array<{id:string}>} catalog
+ * @returns {Array<{alias:string,oldId:string,newId:string}>}
+ */
+function findFabricatedAliasRepairs(sources, catalog) {
+  if (!catalog || catalog.length === 0) { return []; }
+  const { classifyModel } = require('./model-classification');
+  const { pairAcrossGateways } = require('./gateway-route-catalog');
+  const { DIVERGENT_VENDORS } = require('./curated-models');
+  const catalogInfo = { models: catalog };
+
+  const out = [];
+  for (const { alias, model, source } of sources) {
+    if (source !== 'user-config') { continue; }
+    if (typeof model !== 'string' || model.startsWith('openrouter/')) { continue; } // not bare
+    const parts = model.split('/');
+    if (parts.length < 2) { continue; } // not a <vendor>/<model> shape
+    const vendor = parts[0];
+    if (DIVERGENT_VENDORS.has(vendor)) { continue; }
+    const versionToken = parts.slice(1).join('/');
+    if (classifyModel(model, 'direct', catalogInfo) !== 'invalid') { continue; }
+    const paired = pairAcrossGateways(vendor, versionToken, catalogInfo);
+    if (!paired.openrouter) { continue; } // ambiguous or absent twin -- leave as a warning
+    out.push({ alias, oldId: model, newId: paired.openrouter });
+  }
+  return out;
+}
+
+module.exports = {
+  collectAliasSources, findStaleAliases, findDriftedStoredAliases, suggestReplacements,
+  findFabricatedAliasRepairs,
+};

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 };