amicus 4.8.1 → 4.9.1

package/src/utils/engine-skew-records.js

@@ -0,0 +1,146 @@
+/**
+ * @module utils/engine-skew-records
+ * Server identity and the bounded store of standing engine-skew records.
+ *
+ * EXTRACTED from src/utils/engine-skew.js (v4.9 W10 round 2), which owns the
+ * comparison, the announcement and the remedy text and had reached the 300-line
+ * gate. Everything here answers one question instead — WHICH SERVER is this,
+ * and what was last observed about it — and that is where the round-2 findings
+ * on identity collapse (A3), the shared unknown bucket (B3) and unbounded growth
+ * (B7) all landed. `engine-skew.js` re-exports the public half, so callers and
+ * tests keep one import site.
+ *
+ * BEST-EFFORT, like its parent: an identity read on a diagnostic path must not
+ * be able to fail a session create, so nothing here throws.
+ */
+
+'use strict';
+
+/**
+ * The standing skew records: server identity -> `{server, installed}`, holding
+ * the LAST comparison observed for that server (see noteSessionVersion). Not a
+ * single process-wide slot (W10 round-1 review A3+B3): one slot stamped the
+ * first skew ever seen onto every later failure, including failures of an
+ * unrelated server and failures after the skew was fixed mid-run.
+ */
+const _skewByServer = new Map();
+
+/** The key used when the client cannot name its server. Distinct from every
+ *  real base URL, so an unidentified server borrows no one else's record. */
+const UNKNOWN_SERVER_KEY = '<unknown server>';
+
+/**
+ * How many servers the map remembers (round-2 review B7). This is
+ * process-lifetime state on a path that runs once per session create — every
+ * fanout leg, every council seat, for as long as an MCP server stays up — and
+ * its key is a server URL, which an operator controls. 32 is far past any real
+ * topology (production talks to ONE spawned server per process) while still
+ * being a bound rather than a hope.
+ */
+const MAX_SKEW_SERVERS = 32;
+
+/**
+ * The identity of the server this client talks to — its base URL, normalized to
+ * an origin AND path.
+ *
+ * MEASURED 2026-08-25 against this checkout's `@opencode-ai/sdk`, not read off
+ * the types: `createOpencodeClient({ baseUrl })` returns an object whose only
+ * non-namespace key is `_client`, and `client._client.getConfig()` answers
+ * `{bodySerializer, headers, parseAs, querySerializer, baseUrl, fetch}` — the
+ * `baseUrl` being exactly the string passed in, and `undefined` when none was.
+ * That is the SMALLEST honest key available at session-create time: no round
+ * trip, no new SDK call, and in production `startServer` always builds the
+ * client from one spawned server's own `sdkServer.url`, so distinct servers get
+ * distinct ports and distinct keys. It is an identity, not proof of identity —
+ * two amicus processes that spawn servers on the same port at different times
+ * would collide — which is why every record is also refreshed on each create.
+ *
+ * THE PATH IS PART OF THE KEY (round-2 review A3). `new URL(raw).origin` alone
+ * collapses two distinct servers onto one record whenever they share an origin
+ * — a reverse proxy at `…:8080/engine-a` and `…:8080/engine-b`, and MEASURED
+ * 2026-08-26, EVERY opaque-origin URL: `new URL('unix:///tmp/a.sock').origin`
+ * and its `b.sock` twin are both the literal string `"null"`. A shared record
+ * is precisely what per-server keying exists to prevent. Amicus's own topology
+ * cannot reach it today — `startServer` is the only production client builder
+ * and always passes one spawned server's `http://127.0.0.1:<port>` — but the
+ * external/shared-server case in engine-skew.js's SCOPE paragraph can, and
+ * keeping the path costs one expression.
+ *
+ * `_client` is the SDK's own internal handle and the ONLY route to that value
+ * (measured: the client's other keys are all resource namespaces). If a future
+ * SDK renames it, this returns UNKNOWN_SERVER_KEY and every server shares one
+ * bucket again. That bucket is genuinely degraded, not merely coarser: under it
+ * a record can be attributed to the wrong server AND cleared by the wrong one.
+ * `noteSessionVersion` clears from it anyway, on purpose — its docblock records
+ * the measurement behind that ruling.
+ *
+ * @param {object} [client] - the SDK client, or nothing
+ * @returns {string} origin + path, the raw value if it will not parse, else
+ *   UNKNOWN_SERVER_KEY. Never throws: an identity read on a diagnostic path
+ *   must not be able to fail a session create.
+ */
+function serverKeyForClient(client) {
+  let raw;
+  try {
+    raw = client && client._client && typeof client._client.getConfig === 'function'
+      ? client._client.getConfig().baseUrl
+      : undefined;
+  } catch (_e) {
+    return UNKNOWN_SERVER_KEY;
+  }
+  if (typeof raw !== 'string' || !raw.trim()) { return UNKNOWN_SERVER_KEY; }
+  try {
+    const url = new URL(raw);
+    return `${url.origin}${url.pathname}`.replace(/\/+$/, '') || url.origin;
+  } catch (_e) { return raw.trim(); }
+}
+
+/** The record standing against one KEY, or undefined. */
+function skewForKey(key) {
+  return _skewByServer.get(key);
+}
+
+/** Record a skew as the most RECENTLY seen, evicting the least recent past the
+ *  bound. Re-inserting on every observation is what makes "recent" mean last
+ *  observed rather than first seen. */
+function rememberSkew(key, skew) {
+  _skewByServer.delete(key);
+  _skewByServer.set(key, skew);
+  while (_skewByServer.size > MAX_SKEW_SERVERS) {
+    _skewByServer.delete(_skewByServer.keys().next().value);
+  }
+}
+
+/** Drop one server's record — a retraction, or "an older engine answers here
+ *  now". Safe on a key that was never recorded. */
+function forgetSkew(key) {
+  _skewByServer.delete(key);
+}
+
+/**
+ * The standing skew record for ONE server, or null.
+ *
+ * A caller with no client gets the UNKNOWN key's record — never another
+ * server's. Reading is defensive but cannot meaningfully throw.
+ * @param {object} [client] - the SDK client whose server is being asked about
+ * @returns {{server: string, installed: string}|null}
+ */
+function currentEngineSkew(client) {
+  try { return _skewByServer.get(serverKeyForClient(client)) || null; } catch (_e) { return null; }
+}
+
+/** Test-only: forget every standing record. */
+function _resetSkewRecords() {
+  _skewByServer.clear();
+}
+
+module.exports = {
+  serverKeyForClient,
+  currentEngineSkew,
+  skewForKey,
+  rememberSkew,
+  forgetSkew,
+  UNKNOWN_SERVER_KEY,
+  MAX_SKEW_SERVERS,
+  _resetSkewRecords,
+};

package/src/utils/engine-skew.js

@@ -0,0 +1,300 @@
+/**
+ * @module utils/engine-skew
+ * Runtime detection of an opencode ENGINE version skew: server vs installed.
+ *
+ * The version the server we are actually talking to reports, against the engine
+ * sitting in THIS install's node_modules.
+ *
+ * WHY (#133, piece 3). The outage was one engine version (npx cache, 1.17.3)
+ * serving every MCP session while another (global install, 1.18.15) served the
+ * CLI, both writing one shared SQLite file — so every MCP prompt died before a
+ * model was ever called. `amicus doctor` printed ZERO errors throughout: its
+ * skew check (`doctor-engine-check.js`) compares npx-cache copies against the
+ * GLOBAL install and says nothing about the copy the running process actually
+ * loaded. MEASURED here 2026-08-25: that baseline sees global 1.18.15 vs npx
+ * 1.18.15 and reports clean, while the running checkout loads engine **1.2.20**
+ * — a live instance of #133's own class, invisible to the check built for it.
+ * Hence a RUNTIME comparison with no global baseline.
+ *
+ * SCOPE, stated honestly (W10 review F2): this handshake fires when the server
+ * answering this process was started by a DIFFERENT install (shared or external
+ * server, PATH-hoisted binary). In #133's literal recorded topology the npx copy
+ * spawned its OWN engine — server and installed versions were EQUAL on that
+ * side, the skew being against a global install neither loads — so THIS check
+ * stays silent there; the engine-log excerpt (piece 2) names that case instead,
+ * by quoting the SQLiteError itself.
+ *
+ * MEASURED, not reasoned from types (2026-08-25, against a locally spawned
+ * engine): `client.session.create({})` returns `data = {directory,id,projectID,
+ * slug,time,title,version}` and `data.version` was `"1.2.20"` — byte-identical
+ * to this checkout's `node_modules/opencode-ai/package.json`. `Session.version`
+ * IS the engine's own version, so the two sides are directly comparable.
+ *
+ * SHAPE. `src/opencode-client.js :: createSession` pushes the observed version
+ * here together with its client (it discarded both before); this module owns
+ * the comparison, the announcement and the remedy text, while
+ * `./engine-skew-records.js` owns the server identity and the standing record —
+ * one per SERVER, refreshed on every create — that `src/headless.js` appends to
+ * a leg's death report. That keeps the client's return type a plain session-id
+ * string (measured: all three production callers — `headless.js`,
+ * `mcp-server.js`, `sidecar/interactive.js` — assign it straight to one).
+ *
+ * EVERYTHING HERE IS BEST-EFFORT: a diagnosis must never become the failure it
+ * reports on. Every path returns null/undefined rather than throwing.
+ */
+
+'use strict';
+
+const path = require('path');
+const {
+  serverKeyForClient, currentEngineSkew, skewForKey, rememberSkew, forgetSkew,
+  UNKNOWN_SERVER_KEY, MAX_SKEW_SERVERS, _resetSkewRecords,
+} = require('./engine-skew-records');
+// The SAME sanitizer the log excerpt uses (round-3 reviews B1+C2). A server's
+// reported version is third-party text on its way to a terminal and to MCP,
+// exactly like an engine log line; one implementation, one dialect.
+const { collapseExcerpt } = require('./text-sanitize');
+
+/** How much of a server-reported version is ever rendered. Real versions are
+ *  semver-shaped; past this it is not a version, it is a payload. */
+const MAX_VERSION_CHARS = 32;
+
+/** One version string, safe to paste into a one-line notice or an error message:
+ *  no ANSI, no control bytes, no bidi reordering, no newline that could forge a
+ *  second `[amicus] ` line, never longer than the cap. */
+const safeVersion = (value) => collapseExcerpt(value, MAX_VERSION_CHARS);
+
+/** Memo for the installed-version disk read (see installedEngineVersion). */
+let _installedRead = false;
+let _installedCache;
+/** Whether the "cannot name this server" notice has already been printed. */
+let _identityNoticeSent = false;
+
+/** Test-only: clear the standing records, the read memo and the notice latch. */
+function _resetEngineSkew() {
+  _resetSkewRecords();
+  _installedRead = false;
+  _installedCache = undefined;
+  _identityNoticeSent = false;
+}
+
+/**
+ * Read the engine version out of the RUNNING install's node_modules.
+ *
+ * Roots come from `path-setup.js :: opencodeRoots()` with no argument — the same
+ * resolver `engine-ensure`/`hasOpencodeBinary` use to decide whether THIS
+ * process's engine binary exists, so "the engine we would run" and "the engine
+ * we version-check" are the same by construction.
+ *
+ * Reading `opencode-ai`'s own package.json (rather than anything next to the
+ * binary) mirrors `engine-install-scan.js :: defaultReadEngineVersion`, whose
+ * docblock records why: a faithful proxy, because opencode-ai exact-pins all 12
+ * platform sub-packages and the binary's own directory has no package.json on
+ * POSIX at all.
+ * @param {object} [deps]
+ * @param {object} [deps.fs] - fs module seam (readFileSync)
+ * @param {string[]} [deps.roots] - node_modules roots seam
+ * @returns {string|undefined} undefined on every miss path
+ */
+function defaultReadInstalledEngineVersion(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const roots = deps.roots || require('./path-setup').opencodeRoots();
+  for (const root of roots) {
+    try {
+      const raw = fs.readFileSync(path.join(root, 'opencode-ai', 'package.json'), 'utf-8');
+      const v = JSON.parse(raw).version;
+      if (v) { return String(v); }
+    } catch (_e) { /* try the next root */ }
+  }
+  return undefined;
+}
+
+/**
+ * The installed engine version, read at most ONCE per process.
+ *
+ * node_modules cannot change under a live process, and this is consulted on
+ * every session create (every fanout leg, every council seat) — a per-session
+ * stat of two roots would be pure waste. The memo is cleared only by
+ * `_resetEngineSkew()`, so a test that swaps seams must reset between cases;
+ * production has exactly one call path and never does.
+ * @param {object} [deps] - defaultReadInstalledEngineVersion seams, plus:
+ * @param {() => (string|undefined)} [deps.readInstalledVersion] - reader seam
+ * @returns {string|undefined}
+ */
+function installedEngineVersion(deps = {}) {
+  if (!_installedRead) {
+    _installedRead = true;
+    try {
+      _installedCache = deps.readInstalledVersion
+        ? deps.readInstalledVersion()
+        : defaultReadInstalledEngineVersion(deps);
+    } catch (_e) {
+      _installedCache = undefined;
+    }
+  }
+  return _installedCache;
+}
+
+/**
+ * The default sink for BOTH one-time notices here — skew, and identity loss.
+ * Written to stderr, NOT through `logger.warn`.
+ *
+ * MEASURED: `utils/logger.js :: getCurrentLevel` defaults `LOG_LEVEL` to
+ * `'error'`, so `logger.warn` is filtered out on every default install — a
+ * self-diagnosis routed there would be silent exactly where it matters. stderr
+ * with an `[amicus] ` prefix is the house pattern for notices the user must see
+ * (`mcp-server.js`'s update notice, `engine-ensure.js`'s self-heal) and is safe
+ * under MCP stdio, where stdout carries the protocol.
+ * @param {string} msg
+ */
+function defaultNotify(msg) {
+  try { process.stderr.write(`[amicus] ${msg}\n`); } catch (_e) { /* EPIPE at shutdown */ }
+}
+
+/**
+ * The announcement text. Names both versions (the whole point — #133 cost 30
+ * minutes because nothing printed the two numbers side by side) and then the
+ * action that ends it: make the two copies the same version.
+ *
+ * It deliberately does NOT say "see amicus doctor" (W10 round-1 review B1).
+ * Doctor's skew check is structurally blind to THIS skew — the module docblock
+ * above records the measurement — so pointing there would spend the user's next
+ * five minutes on a check that reports clean by construction.
+ *
+ * BOTH VERSIONS ARE SANITIZED (round-3 reviews B1+C2). `server` is whatever the
+ * server chose to say, and it landed verbatim on stderr: an escape sequence, a
+ * bidi override or a newline could recolour the terminal, reverse the sentence,
+ * or forge a second `[amicus] ` line under our prefix. `installed` goes through
+ * it too — also file content, and one rule beats two.
+ * @param {{server: string, installed: string}} skew
+ * @returns {string} one line
+ */
+function formatSkewWarning({ server, installed }) {
+  return `engine version skew: server ${safeVersion(server)} ≠ installed ${safeVersion(installed)} — `
+    + 'MCP and CLI may be running different engines; update whichever copy is behind '
+    + '(`npm i -g amicus`, or re-run the failing surface\'s installer). '
+    + '`amicus doctor` cannot see this skew: its baseline compares npx against global, '
+    + 'not the server actually answering.';
+}
+
+/**
+ * The clause appended to an enriched failure message. EMPTY when there is no
+ * standing skew, so every message that would not have carried it is
+ * byte-identical to what it was before this module existed.
+ *
+ * Sanitized on the same terms as the notice, and for a sharper reason: this
+ * clause rides out through MCP into whatever renders a leg's death report.
+ * @param {{server: string, installed: string}|null} [skew]
+ * @returns {string}
+ */
+function formatSkewSuffix(skew) {
+  if (!skew) { return ''; }
+  return ` (engine skew: server ${safeVersion(skew.server)} ≠ installed ${safeVersion(skew.installed)})`;
+}
+
+/**
+ * Say so, ONCE, when a client was handed to us and we could not name its server.
+ *
+ * Round-3 review C1(a). `serverKeyForClient` reads `client._client.getConfig()`,
+ * a PRIVATE SDK handle and the only route to the base URL. If a future SDK
+ * renames it, that read returns UNKNOWN_SERVER_KEY, every server in the process
+ * silently shares one degraded bucket — where a record can be attributed to the
+ * wrong server AND cleared by the wrong one — and nothing says so. That is the
+ * correct-but-silent degrade the product principle rates as bad as a crash.
+ *
+ * A CLIENT WAS PROVIDED is the whole trigger: the caller had a server to name
+ * and we could not name it. No client at all is not a shape change — it is a
+ * caller that never claimed to have one — so `currentEngineSkew`, whose callers
+ * legitimately ask "any skew here?" with nothing in hand, does not raise it.
+ * Once per process: this runs on every create, and a wave of dead legs must not
+ * each print it. (b) is the other half — a CI shape pin over a REAL SDK client,
+ * in tests/utils/engine-skew.test.js.
+ */
+function noteIdentityLoss(key, deps) {
+  if (_identityNoticeSent || !deps.client || key !== UNKNOWN_SERVER_KEY) { return; }
+  _identityNoticeSent = true;
+  const notify = deps.notify || defaultNotify;
+  try {
+    notify('server identity unavailable — skew attribution is process-wide; '
+      + 'SDK shape may have changed');
+  } catch (_e) { /* best-effort, exactly like the skew notice */ }
+}
+
+/**
+ * Record a server-reported session version as the LAST comparison for that
+ * server, announcing a mismatch the first time that server shows it.
+ *
+ * REFRESHED ON EVERY CREATE, not written once (W10 round-1 review A3+B3): a
+ * matching version RETRACTS a standing skew for that server, so a mid-run fix
+ * stops being reported; a different mismatch REPLACES it, the newer observation
+ * being the true one. Records are per server identity, so a skewed server's
+ * clause never rides out on an unrelated server's death report.
+ *
+ * A version-less create CLEARS that server's record (round-2 review B4).
+ * Absence of the field means an older SDK or engine is answering — not evidence
+ * of SKEW, but evidence that what the record describes is no longer what is on
+ * that URL. Unknown beats stale: it announces nothing and returns null, exactly
+ * like a match. An unreadable INSTALLED version is different — with one side of
+ * the comparison missing there is no observation at all, so it touches nothing.
+ *
+ * BOTH CLEARS APPLY UNDER `UNKNOWN_SERVER_KEY` TOO, deliberately (round-2
+ * review B3, which proposed the opposite). Under that shared bucket a clear can
+ * be wrong — server B's healthy create can delete server A's real skew — so the
+ * rule was re-derived against "never attribute a skew to a server that does not
+ * have it" and MEASURED over A skewed, B healthy, A fixed, A regresses:
+ *   retract       → B dies clean, A-after-fix dies clean, A's regression is
+ *                   re-recorded on its very next create
+ *   never retract → B wears A's skew, A wears its own stale skew after the fix,
+ *                   and NOTHING can ever clear either
+ * Retraction's error is self-healing (this runs on EVERY create); the other is a
+ * wrong attribution no later observation can undo. The bucket stays genuinely
+ * degraded — see `noteIdentityLoss` above, which now says so out loud.
+ *
+ * The notice repeats only when the record CHANGES: the skewed leg of a 20-seat
+ * wave must not print 20 identical lines.
+ * @param {string|undefined} serverVersion - `Session.version` from the create response
+ * @param {object} [deps] - installedEngineVersion seams, plus:
+ * @param {object} [deps.client] - the SDK client, for the server identity
+ * @param {(msg: string) => void} [deps.notify] - notice sink seam
+ * @returns {{server: string, installed: string}|null} that server's record
+ */
+function noteSessionVersion(serverVersion, deps = {}) {
+  const key = serverKeyForClient(deps.client);
+  noteIdentityLoss(key, deps);
+  if (typeof serverVersion !== 'string' || !serverVersion) {
+    forgetSkew(key); // an older engine answers here NOW — unknown beats stale
+    return null;
+  }
+  const installed = installedEngineVersion(deps);
+  if (typeof installed !== 'string' || !installed) { return null; }
+  if (serverVersion === installed) {
+    forgetSkew(key); // the two agree NOW — any older mismatch is stale
+    return null;
+  }
+
+  const prior = skewForKey(key);
+  const skew = { server: serverVersion, installed };
+  // Record BEFORE announcing: a notifier that throws must not cost us the
+  // enrichment clause too.
+  rememberSkew(key, skew);
+  if (prior && prior.server === skew.server && prior.installed === skew.installed) { return skew; }
+  const notify = deps.notify || defaultNotify;
+  try { notify(formatSkewWarning(skew)); } catch (_e) { /* best-effort */ }
+  return skew;
+}
+
+// Ordered so the FUNCTIONS this module is used for come first: the generated
+// `Key Exports` cell in CLAUDE.md keeps five names and renders each as `name()`,
+// so a constant in that window reads as a function it is not (round-2 B8).
+module.exports = {
+  noteSessionVersion,
+  currentEngineSkew,
+  serverKeyForClient,
+  formatSkewWarning,
+  formatSkewSuffix,
+  installedEngineVersion,
+  defaultReadInstalledEngineVersion,
+  UNKNOWN_SERVER_KEY,
+  MAX_SKEW_SERVERS,
+  _resetEngineSkew,
+};

package/src/utils/gateway-router.js

@@ -10,6 +10,17 @@
 const { resolved, routeError, selectionRequired, parseDescriptor } = require('./model-descriptor');
 const { classifyModel } = require('./model-classification');
 const { isDirectProvider } = require('./provider-registry');
+const HINTS = require('./remediation-hints');
+
+/**
+ * Which gateway an executable id routes through (issue 214). The inverse of
+ * `executableFor`. Non-string input reads as 'direct' rather than throwing --
+ * callers pass raw values off run metadata.
+ * @param {*} id @returns {'openrouter'|'direct'}
+ */
+function gatewayOf(id) {
+  return typeof id === 'string' && id.startsWith('openrouter/') ? 'openrouter' : 'direct';
+}
 
 /** Build the executable id for a gateway. */
 function executableFor(gateway, vendor, model) {
@@ -86,8 +97,15 @@ function catalogGate({ id, gateway, req }) {
   if (req.allowSelection) {
     return { ok: false, result: selectionRequired({ requested: req.descriptor.raw, suggestions: [] }) };
   }
-  return { ok: false, result: routeError({ requested: req.descriptor.raw, reason: 'model_not_found',
-    preferredGateway: gateway, suggestions: [] }) };
+  const e = routeError({ requested: req.descriptor.raw, reason: 'model_not_found',
+    preferredGateway: gateway, suggestions: [] });
+  // B2 (V16): a bare id invalid on direct whose openrouter/ twin IS catalog-
+  // confirmed is exactly doctor's repairable fabricated-alias class — point at
+  // the repair. Hint only; reason and shape unchanged.
+  if (gateway === 'direct' && classifyModel(`openrouter/${id}`, 'openrouter', req.catalogInfo) === 'valid') {
+    e.hint = HINTS.repairFabricatedAlias;
+  }
+  return { ok: false, result: e };
 }
 
 /**
@@ -191,4 +209,4 @@ function resolveRoute(req) {
   return routeError({ requested: d.raw, reason: 'no_key_for_vendor', preferredGateway: 'direct', suggestions: [] });
 }
 
-module.exports = { resolveRoute };
+module.exports = { gatewayOf, resolveRoute };

package/src/utils/model-canonicalization.js

@@ -32,7 +32,19 @@
 
 'use strict';
 
-const { toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
+/*
+ * Why `stripGatewayPrefix` (curated-models.js) is not the function to reach for:
+ * under its old name `toCanonicalDefault` it read as the CORRECT answer, and three
+ * callers took it at its word and persisted ids the direct API may not serve — the
+ * wizard's hand-copy `toBareIfDirect`, `toStorableRoute`, and `toDefaultAliases`
+ * before it was rewritten. Issue 214 renamed it rather than giving it a
+ * `catalogInfo` parameter, because that is circular: it PRODUCES the candidate id
+ * that `classifyModel` then checks against the catalog. The evidence check belongs
+ * one level up, here. Direct use of the primitive is correct only when normalising
+ * two strings before COMPARING them (alias-shadow.js).
+ */
+
+const { stripGatewayPrefix, DIVERGENT_VENDORS } = require('./curated-models');
 const { classifyModel } = require('./model-classification');
 
 /**
@@ -41,10 +53,47 @@ const { classifyModel } = require('./model-classification');
  * @param {{models: Array<{id:string, authoritative?: boolean}>}} catalogInfo
  * @returns {string} the bare direct id when not proven invalid, else `orId` unchanged
  */
+/**
+ * #208: did THIS vendor's direct namespace get ATTEMPTED and REJECTED for the
+ * catalog in hand? An empty namespace has two causes and `classifyModel`
+ * cannot tell them apart -- it returns 'unknown' for both. "Never fetched"
+ * (offline, no key) leaves optimism reasonable; "fetched and refused" means we
+ * know nothing about the namespace, and synthesising a direct id out of no
+ * knowledge is exactly how `deepseek/deepseek-v4-flash-0731` -- an id no
+ * gateway serves -- reached a real user config. Keyed on the VENDOR, never on
+ * "any failure": one provider's 401 says nothing about another's namespace.
+ * @param {string} vendor
+ * @param {{providerFailures?: Array<{provider: string}>}} catalogInfo
+ * @returns {boolean}
+ */
+function namespaceFetchFailed(vendor, catalogInfo) {
+  const failures = catalogInfo && catalogInfo.providerFailures;
+  return Array.isArray(failures) && failures.some(f => f && f.provider === vendor);
+}
+
+/**
+ * Vendor segment of an executable id: `openrouter/<vendor>/<rest>` or
+ * `<vendor>/<rest>`. Council #216 (A2/B1): both guards below used to key on the
+ * CALLER's `vendor` argument while classifyModel derived its own from the id, so
+ * a caller passing none -- which toStorableRoute's JSDoc permits
+ * (`vendorPath?:string`) -- silently lost the DIVERGENT and namespace-rejection
+ * checks while the catalog check kept working. Deriving closes that asymmetry.
+ * @param {*} id @returns {string} '' when the id carries no vendor segment
+ */
+function vendorOfId(id) {
+  if (typeof id !== 'string') { return ''; }
+  const rest = id.startsWith('openrouter/') ? id.slice('openrouter/'.length) : id;
+  const idx = rest.indexOf('/');
+  return idx > 0 ? rest.slice(0, idx) : '';
+}
+
 function directFormIfSafe(vendor, orId, catalogInfo) {
-  if (DIVERGENT_VENDORS.has(vendor)) { return orId; }
-  const bare = toCanonicalDefault(orId);
+  const v = vendor || vendorOfId(orId);
+  if (DIVERGENT_VENDORS.has(v)) { return orId; }
+  const bare = stripGatewayPrefix(orId);
   if (bare === orId) { return orId; } // gateway-only vendor -- no direct integration at all
+  // Optimism is only justified when the namespace was never attempted.
+  if (namespaceFetchFailed(v, catalogInfo)) { return orId; }
   return classifyModel(bare, 'direct', catalogInfo) === 'invalid' ? orId : bare;
 }
 
@@ -55,10 +104,10 @@ function directFormIfSafe(vendor, orId, catalogInfo) {
  * @returns {string} the bare direct id only when PROVEN valid, else `orId` unchanged
  */
 function directFormIfProven(vendor, orId, catalogInfo) {
-  if (DIVERGENT_VENDORS.has(vendor)) { return orId; }
-  const bare = toCanonicalDefault(orId);
+  if (DIVERGENT_VENDORS.has(vendor || vendorOfId(orId))) { return orId; }
+  const bare = stripGatewayPrefix(orId);
   if (bare === orId) { return orId; }
   return classifyModel(bare, 'direct', catalogInfo) === 'valid' ? bare : orId;
 }
 
-module.exports = { directFormIfSafe, directFormIfProven };
+module.exports = { directFormIfSafe, directFormIfProven, namespaceFetchFailed, vendorOfId };

package/src/utils/model-catalog.js

@@ -19,7 +19,7 @@ const path = require('path');
 // this module is first required (the test pattern re-mocks mid-test).
 function _getConfigDir() { return require('./config').getConfigDir(); }
 function _readApiKeyValues() { return require('./api-key-store').readApiKeyValues(); }
-async function _fetchAllModels(keys) { return require('./model-fetcher').fetchAllModels(keys); }
+async function _fetchAllModels(keys) { return require('./model-fetcher').fetchAllModelsDetailed(keys); }
 
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
 const CATALOG_SCHEMA_VERSION = 2;
@@ -69,8 +69,16 @@ function writeCacheDoc(doc) {
 }
 
 /** Write a successful fetch: fresh models/fetchedAt, outcome fields cleared. @param {Array} models */
-function writeCache(models) {
-  writeCacheDoc({ schemaVersion: CATALOG_SCHEMA_VERSION, fetchedAt: Date.now(), models });
+function writeCache(models, providerFailures) {
+  writeCacheDoc({
+    schemaVersion: CATALOG_SCHEMA_VERSION,
+    fetchedAt: Date.now(),
+    models,
+    // #209: which providers were ATTEMPTED and REJECTED for this fetch. Persisted
+    // alongside the rows because it describes THESE rows -- a cache served later
+    // is still a catalog whose deepseek namespace is empty for a reason.
+    providerFailures: Array.isArray(providerFailures) ? providerFailures : [],
+  });
 }
 
 /**
@@ -80,9 +88,17 @@ function writeCache(models) {
  * carries only the outcome fields (no models/fetchedAt to report).
  * @param {string} reason short error-class string
  */
-function writeRefreshFailure(reason) {
+function writeRefreshFailure(reason, providerFailures) {
   const existing = readCache() || { schemaVersion: CATALOG_SCHEMA_VERSION };
-  writeCacheDoc({ ...existing, lastRefreshAttempt: Date.now(), lastRefreshError: reason });
+  const doc = { ...existing, lastRefreshAttempt: Date.now(), lastRefreshError: reason };
+  // Council C1 (PR 215): a TOTAL outage is exactly when the per-provider
+  // breakdown matters most, and this path used to discard the failures the
+  // refresh had just computed. Only overwrite when this attempt produced some --
+  // an attempt that learned nothing must not erase a previous attempt's detail.
+  if (Array.isArray(providerFailures) && providerFailures.length > 0) {
+    doc.providerFailures = providerFailures;
+  }
+  writeCacheDoc(doc);
 }
 
 /**
@@ -91,7 +107,7 @@ function writeRefreshFailure(reason) {
  */
 async function refreshCatalog() {
   const keys = _readApiKeyValues();
-  const models = await _fetchAllModels(keys);
+  const { rows: models, failures: providerFailures } = await _fetchAllModels(keys);
   // The anthropic rows are a hardcoded zero-network floor: a result containing
   // ONLY them means every network provider failed. Treat that as a failed
   // refresh — never clobber a previously-good cache with the floor (the
@@ -105,10 +121,10 @@ async function refreshCatalog() {
     const reason = (models || []).length > 0
       ? 'floor-only: all providers returned no network rows'
       : 'network-error: all providers unreachable';
-    writeRefreshFailure(reason);
+    writeRefreshFailure(reason, providerFailures);
     return [];
   }
-  writeCache(models);
+  writeCache(models, providerFailures);
   return models;
 }
 
@@ -149,7 +165,9 @@ async function getCatalogInfo(opts = {}) {
     fetchedAt: cache ? cache.fetchedAt : null,
     lastRefreshAttempt: (doc && doc.lastRefreshAttempt) || null,
     lastRefreshError: (doc && doc.lastRefreshError) || null,
+    // #209: namespace-level fetch outcomes for the CACHED rows above.
+    providerFailures: (doc && Array.isArray(doc.providerFailures)) ? doc.providerFailures : [],
   };
 }
 
-module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION };
+module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION, DEFAULT_MAX_AGE_MS };