amicus 4.8.1 → 4.9.1

package/src/sidecar/models.js

@@ -21,25 +21,11 @@ const { getFamilies } = require('../utils/curated-models');
 const { pickCurrent } = require('../utils/quick-picks');
 const { probeStoredAliases, selectStoredAliases } = require('./models-probe');
 const { DEFAULT_MAX_LEGS } = require('./fanout-validate');
+const { fmtRow, fmtGatewayFinding, fmtProbeLine, fmtProviderFailure } = require('./models-render');
 
 const CHECK_EXIT_CAP = 100;
 
-/** '0.000003' per token → '3.00' per Mtok; '—' when unknown or variable (-1) */
-function perMtok(perToken) {
-  if (perToken === null || perToken === undefined) { return '—'; }
-  const n = Number(perToken);
-  if (Number.isNaN(n) || n < 0) { return '—'; }
-  return (n * 1e6).toFixed(2);
-}
 
-function fmtRow(m, aliasesById) {
-  const alias = aliasesById.get(m.id);
-  const aliasCol = alias ? `[${alias}] ` : '';
-  const ctx = m.contextLength ?? '—';
-  const pIn = perMtok(m.pricing && m.pricing.prompt);
-  const pOut = perMtok(m.pricing && m.pricing.completion);
-  return `${aliasCol}${m.id}\n    ${m.name}  ctx ${ctx}  $/Mtok in ${pIn} out ${pOut}`;
-}
 
 /** alias marks: id → comma-joined alias names (effective user aliases) */
 function aliasMarks() {
@@ -130,47 +116,31 @@ async function runRefresh(args) {
   return 0;
 }
 
-/** One readable line per gateway-route finding (Task 6, #gwid). @param {object} f @returns {string} */
-function fmtGatewayFinding(f) {
-  if (f.kind === 'stale') {
-    return `  GATEWAY STALE (${f.gateway}): ${f.alias} -> ${f.model}`;
-  }
-  if (f.kind === 'divergent-missing') {
-    return `  GATEWAY DIVERGENT: ${f.alias} has no direct form; catalog confirms ${f.model}`;
-  }
-  return `  GATEWAY DIVERGENT: ${f.alias} direct form ${f.model} no longer matches catalog (now ${f.expected})`;
-}
 
-const PROBE_LABELS = { served: 'SERVED', 'accepted-but-silent': 'SILENT', error: 'ERROR' };
 
-/** '$0.0004' | '$1.23' | '—' (unknown). Deliberately NOT formatCost (pricing.js):
- * a probe result's `cost` is a bare number (models-probe.js doesn't carry the
- * reported/estimated source tag), so this never claims a precision it can't back. */
-function fmtProbeCost(cost) {
-  if (cost === null || cost === undefined || Number.isNaN(cost)) { return '—'; }
-  return cost < 1 ? `$${cost.toFixed(4)}` : `$${cost.toFixed(2)}`;
-}
 
-/** One readable line per probed alias (`--check --live`, v4.6.2 PR3): uppercase
- * class prefix padded to a fixed column, two-space indent — mirrors the STALE/
- * DRIFTED/GATEWAY line style above. @param {object} r probeStoredAliases() row */
-function fmtProbeLine(r) {
-  const head = `  ${(PROBE_LABELS[r.outcome] + ':').padEnd(8)}${r.alias} -> ${r.target}`;
-  if (r.outcome === 'served') { return `${head} (${fmtProbeCost(r.cost)})`; }
-  if (r.outcome === 'accepted-but-silent') { return `${head} — ${r.detail} (accepted but not serving)`; }
-  return `${head} — ${r.detail}`;
-}
 
 async function runCheck(args) {
+  // v4.9 W13 Task B (BACKLOG C5). FIRST — ahead of the catalog-unavailable return
+  // below, exactly when an offline user most needs to know what their aliases bind
+  // to. No name list, so the subject is curated ∩ configured — NOT "the whole
+  // configured set", the overstatement round 3's B2 struck from findAliasShadows'
+  // docstring and whose twin here outlived it (round 5, D2). stderr only, so
+  // `--json` stays byte-clean; `audit…` opens a fresh scope (PR #203 A5).
+  require('../utils/alias-shadow').auditAliasShadows();
   const catalogInfo = await getCatalogInfo();
   const catalog = catalogInfo.models;
+  const providerFailures = Array.isArray(catalogInfo.providerFailures) ? catalogInfo.providerFailures : [];
   if (!catalog || catalog.length === 0) {
     const probeSkipped = args.live ? 'catalog-unavailable' : null;
     if (args.json) {
       process.stdout.write(JSON.stringify(buildAuditDoc({
-        stale: [], catalogAvailable: false, probeSkipped
+        stale: [], catalogAvailable: false, probeSkipped, providerFailures
       }), null, 2) + '\n');
     } else {
+      // Council C2 (PR 215): "catalog unavailable" is precisely when the user
+      // needs to know WHICH provider refused them.
+      for (const f of providerFailures) { process.stdout.write(fmtProviderFailure(f) + '\n'); }
       process.stdout.write('Catalog unavailable (offline or no providers reachable); cannot check.\n');
       if (probeSkipped) { process.stdout.write(fmtLiveSkipped(probeSkipped) + '\n'); }
     }
@@ -179,7 +149,7 @@ async function runCheck(args) {
   const sources = collectAliasSources();
   const stale = findStaleAliases(sources, catalog)
     .map(s => ({ ...s, suggestions: suggestReplacements(s.model, catalog) }));
-  const drifted = findDriftedStoredAliases(sources, catalog);
+  const drifted = findDriftedStoredAliases(sources, catalogInfo);
   // Task 6 (#gwid): per-gateway-form audit of the curated DEFAULTS
   // (toGatewayRoutes()) — additive to the flat audit above. Informational by
   // default; --strict promotes it to a build-breaking exit code (CI gate).
@@ -214,10 +184,14 @@ async function runCheck(args) {
 
   if (args.json) {
     process.stdout.write(JSON.stringify(buildAuditDoc({
-      stale, catalogAvailable: true, gatewayFindings, drifted, probe: probeResults
+      stale, catalogAvailable: true, gatewayFindings, drifted, probe: probeResults, providerFailures
     }), null, 2) + '\n');
     return exitCode;
   }
+  // issue 209: report REJECTED provider fetches before the alias findings -- an
+  // empty namespace explains stale/absent aliases downstream, and staying
+  // silent about it is the original defect.
+  for (const f of providerFailures) { process.stdout.write(fmtProviderFailure(f) + '\n'); }
   const driftLines = buildFallbackDriftReport(catalog);
   if (stale.length === 0 && drifted.length === 0) {
     process.stdout.write(`All aliases resolve to catalog models (${sources.length} checked).\n`);

package/src/sidecar/read.js

@@ -15,6 +15,10 @@ const { fenceSidecarOutput } = require('../utils/untrusted-fence');
 // this module's own searchSessions re-export below.
 const { searchSessions } = require('./list-search');
 const { normalizeLimit, truncationNotice } = require('./list-limit');
+// v4.9 W12: council runs are first-class rows on this surface too — the merge
+// amicus_list has done since v4.0 §8, split out for the same line-budget reason
+// as the two modules above. Owns the MODEL cell's rendering and width.
+const { padModel, modelCell, mergeCouncilRows, councilScopeNotice } = require('./list-council');
 
 /**
  * Format a timestamp as relative age
@@ -134,16 +138,28 @@ function enumerateAllProjects(opts = {}) {
  */
 async function listSidecars(options) {
   const { status, all, json, search, limit, project = process.cwd() } = options;
-  // Mirrors models.js:279-281's valueless-flag shape.
+  // Mirrors the valueless-flag shape of `sidecar/models.js :: handleModels`'s
+  // first guard (was `:279-281`; re-anchored by symbol in v4.9 W13).
   if (search === true) { throw new Error('--search requires a value'); }
   const cap = normalizeLimit(limit); // throws on valueless/non-integer/negative
 
   let sessions = all
     ? enumerateAllProjects({ status, project })
     : enumerateSessions(project, { status });
+  // Round 3 (B1): the merge's catch degrades to the session rows and used to do
+  // it in SILENCE. It now hands the failure out through this sink and the human
+  // branch says it — seam rationale at list-council.js :: mergeCouncilRows.
+  let unavailable = null;
+  sessions = mergeCouncilRows(sessions, project,
+    { status, all, onUnavailable: (note) => { unavailable = note; } });
   if (search) { sessions = searchSessions(sessions, search, { project }); }
   if (sessions.length === 0) {
     console.log('No amicus sessions found.');
+    // A1's disclosure as under the table below — an empty `--all` is where the
+    // omission is loudest — and B1's note on the same gate for the same reason:
+    // this early return is the one line both modes share, and --json cannot move.
+    if (!json && unavailable) { console.log(unavailable); }
+    if (all && !json) { console.log(councilScopeNotice()); }
     return;
   }
 
@@ -157,9 +173,11 @@ async function listSidecars(options) {
 
   if (json) {
     console.log(JSON.stringify(sessions, null, 2));
+    // No silent caps — but on stderr, so stdout stays one parseable document.
+    if (truncated) { console.error(truncationNotice(cap, total)); }
   } else {
     console.log(
-      'ID'.padEnd(10) + 'MODEL'.padEnd(23) + 'STATUS'.padEnd(11) +
+      'ID'.padEnd(10) + padModel('MODEL') + 'STATUS'.padEnd(11) +
       'TAG'.padEnd(12) + 'AGE'.padEnd(12) + 'BRIEFING' +
       (all ? '  PROJECT' : '')
     );
@@ -170,7 +188,7 @@ async function listSidecars(options) {
         ((s.briefing?.length > 30) ? '...' : '');
       console.log(
         `${(s.id || '').padEnd(10)}` +
-        `${(s.type === 'wave' ? `wave(${s.legCount ?? 0} legs)` : (s.model || '')).padEnd(23)}` +
+        `${padModel(modelCell(s))}` +
         `${(s.status || 'unknown').padEnd(11)}` +
         `${(s.tag || '').padEnd(12)}` +
         `${age.padEnd(12)}` +
@@ -178,13 +196,19 @@ async function listSidecars(options) {
         (all ? `  ${s.project || ''}` : '')
       );
     });
-  }
-
-  // No silent caps: say what was elided, and how to see it all. In --json mode
-  // this goes to stderr so stdout stays a single parseable document.
-  if (truncated) {
-    const notice = truncationNotice(cap, total);
-    if (json) { console.error(notice); } else { console.log(notice); }
+    // THE TRAILING ORDER IS LOAD-BEARING (round 3, B4): docs/usage.md says every
+    // human `--all` listing ENDS with the scope note, and truncation used to
+    // print after the fork — after it — so `--all --limit N` made that false.
+    // Narrowest qualifier first; the standing limit closes.
+    if (truncated) { console.log(truncationNotice(cap, total)); }
+    if (unavailable) { console.log(unavailable); }
+    // Round 2 (A1): under `--all` the session rows span every indexed project
+    // and the council rows only ever span this one — say so. THIS is the seam:
+    // `all`, the `mergeCouncilRows` call above and the human table are all
+    // visible from here, and the merge itself cannot print. Inside the human
+    // branch on purpose — `--json` is a shape contract, and unlike the
+    // truncation notice there is no cap here for a script to raise.
+    if (all) { console.log(councilScopeNotice()); }
   }
 }
 

package/src/sidecar/reopen-spend.js

@@ -20,7 +20,8 @@ function finalizeSpendForReopen({ taskId, model, mode, op, result, status, proje
     metadata.usage = usage; // buildRunResult surfaces metadata.usage into the --json doc for free
     try {
       const { appendSpend } = require('../utils/spend-ledger');
-      const gateway = metadata.gateway || (String(model).startsWith('openrouter/') ? 'openrouter' : 'direct');
+      const { gatewayOf } = require('../utils/gateway-router');
+      const gateway = metadata.gateway || gatewayOf(model);
       // v4.7.1 Task 7 D16: null-not-absent, the OPPOSITE convention from
       // metadata.tag's absent-not-null (D13) — same `|| null` idiom as start.js:237.
       appendSpend({ taskId, model, mode, usage, op, status, project, gateway, tag: metadata.tag || null }, ctx);

package/src/sidecar/setup.js

@@ -475,9 +475,17 @@ async function runReadlineSetup() {
       await warnOnLowOpenRouterCredit();
     }
 
-    const { getCatalog } = require('../utils/model-catalog');
+    const { getCatalogInfo } = require('../utils/model-catalog');
     let catalog = [];
-    try { catalog = await getCatalog(); } catch (_err) { /* offline: pinned */ }
+    // #208: carry the per-provider fetch outcomes alongside the rows, so the
+    // vendor shortlist below cannot synthesise a bare direct id for a
+    // namespace whose fetch was rejected rather than never attempted.
+    let providerFailures = [];
+    try {
+      const info = await getCatalogInfo();
+      catalog = info.models;
+      providerFailures = info.providerFailures || [];
+    } catch (_err) { /* offline: pinned */ }
 
     // Task 7 (cost-aware defaults P2): per-provider picker, once per keyed
     // provider, BEFORE the mode prompt -- orthogonal to standard-vs-free-council.
@@ -537,7 +545,7 @@ async function runReadlineSetup() {
     }
 
     // Read-modify-write — never rebuild the alias table (no-clobber rule).
-    const cfg = loadConfig() || { aliases: toLiveSeedAliases(catalog) };
+    const cfg = loadConfig() || { aliases: toLiveSeedAliases({ models: catalog, providerFailures }) };
     if (!cfg.aliases) { cfg.aliases = {}; }
     if (chosen.alias) {
       cfg.default = chosen.alias;
@@ -548,7 +556,7 @@ async function runReadlineSetup() {
       // choice), but the alias's VALUE must stay the vendor phase's tier choice --
       // skip the curated-flagship upgrade so it isn't discarded.
       if (pick && !chosen.noUpgrade && !vendorAliasesWritten.has(chosen.alias)) {
-        cfg.aliases[chosen.alias] = toStorableRoute(pick);
+        cfg.aliases[chosen.alias] = toStorableRoute(pick, { models: catalog, providerFailures });
       } else if (cfg.aliases[chosen.alias] === undefined) {
         const fallback = getDefaultAliases()[chosen.alias];
         if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }
@@ -599,6 +607,7 @@ async function runReadlineSetup() {
           const { buildModelShortlist } = require('../utils/model-shortlist');
           const shortlist = buildModelShortlist(pick.vendorPath, {
             catalog,
+            providerFailures,
             recommendedId: cfg.aliases[chosen.alias],
           });
           const specific = await promptForVendorModel(

package/src/sidecar/start.js

@@ -219,6 +219,7 @@ async function startSidecar(options) {
     try {
       const { appendSpend } = require('../utils/spend-ledger');
       const { statusFromResult } = require('../utils/result-schema');
+      const { gatewayOf } = require('../utils/gateway-router');
       appendSpend({
         taskId, model, mode: effectiveHeadless ? 'headless' : 'interactive', usage: runUsage,
         op: 'start', status: statusFromResult(result), project: effectiveProject,
@@ -227,7 +228,7 @@ async function startSidecar(options) {
         // inside createSessionMetadata. Reading `metadata.gateway` throws a ReferenceError the
         // best-effort catch swallows → EVERY start-mode spend row silently dropped + start-json.test.js
         // goes red. Use an in-scope value (spec-complete for direct/openrouter):
-        gateway: String(model).startsWith('openrouter/') ? 'openrouter' : 'direct',
+        gateway: gatewayOf(model),
         // (To also attribute v4.2 'local': thread the resolved route gateway — dropped today at
         // cli-handlers-run.js:47 — into createSessionMetadata and read `meta.gateway`, as continue.js:111 does.)
         // v4.7 F8 D16: same in-scope-value rule as gateway above — `m` is the

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

@@ -172,13 +172,20 @@ function suggestReplacements(staleModel, catalog, n = 3) {
  * @param {Array<{id:string}>} catalog
  * @returns {Array<{alias:string,stored:string,current:string}>}
  */
-function findDriftedStoredAliases(sources, catalog) {
-  if (!catalog || catalog.length === 0) { return []; }
+function findDriftedStoredAliases(sources, catalogOrInfo) {
+  // Council #216 A1/B2/C1: accepts catalogInfo (or a bare array, for existing
+  // callers). Passing models WITHOUT providerFailures made this compute the bare
+  // direct form for a REJECTED namespace while sidecar/setup.js persists the
+  // gateway form -- reporting drift that does not exist, and suggesting a repair
+  // that writes back the unservable direct id issue 208 removed.
+  const info = Array.isArray(catalogOrInfo) ? { models: catalogOrInfo } : (catalogOrInfo || { models: [] });
+  const catalog = info.models || [];
+  if (catalog.length === 0) { return []; }
   const { resolveQuickPicks, toStorableRoute } = require('./quick-picks');
   const current = new Map();
   for (const r of resolveQuickPicks(catalog)) {
     if (r.source !== 'live') { continue; }
-    const stored = toStorableRoute(r);
+    const stored = toStorableRoute(r, info);
     if (stored) { current.set(r.alias, { display: stored, routeValues: new Set(Object.values(r.routes)) }); }
   }
   const byProvider = idsByProvider(catalog);

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