amicus 4.9.0 → 4.9.2

package/src/utils/gateway-router.js

@@ -12,6 +12,16 @@ 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) {
   return gateway === 'openrouter' ? `openrouter/${vendor}/${model}` : `${vendor}/${model}`;
@@ -199,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,6 +165,8 @@ 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 : [],
   };
 }
 

package/src/utils/model-fetcher.js

@@ -136,48 +136,85 @@ function fetchModelsFromProvider(provider, key) {
 }
 
 /**
- * Perform the HTTPS fetch + normalize for a single configured provider.
- * Resolves to `[]` on any non-200 response, network error, timeout, or parse error.
+ * Perform the HTTPS fetch + normalize for a single configured provider,
+ * REPORTING why it failed (issue #209). The four failure modes used to
+ * collapse to a bare `[]`, which made a rejected fetch indistinguishable from
+ * a provider that legitimately serves no models -- and that ambiguity is what
+ * lets `classifyModel` return 'unknown' for a namespace whose fetch was
+ * actually refused (see #208).
  * @param {string} provider - Key into PROVIDER_FETCH_CONFIG
  * @param {string} key - API key
- * @returns {Promise<Array>} Normalized model rows, or [] on any failure
+ * @returns {Promise<{rows: Array, failure: {reason: string, status?: number, detail?: string}|null}>}
  */
-function fetchViaConfig(provider, key) {
+function fetchViaConfigDetailed(provider, key) {
   const config = PROVIDER_FETCH_CONFIG[provider];
   const url = config.buildUrl ? config.buildUrl(key) : config.url;
   const headers = config.authHeader(key);
 
   return new Promise((resolve) => {
     let chunks = '';
+    const ok = (rows) => resolve({ rows, failure: null });
+    const fail = (failure) => resolve({ rows: [], failure });
+
     const timer = setTimeout(() => {
       req.destroy();
-      resolve([]);
+      fail({ reason: 'timeout', detail: `no response within ${FETCH_TIMEOUT_MS}ms` });
     }, FETCH_TIMEOUT_MS);
 
     const req = https.get(url, { headers }, (res) => {
       if (res.statusCode !== 200) {
         clearTimeout(timer);
         res.on('data', () => {});
-        res.on('end', () => resolve([]));
+        res.on('end', () => fail({ reason: 'http-status', status: res.statusCode }));
         return;
       }
       res.on('data', (chunk) => { chunks += chunk; });
       res.on('end', () => {
         clearTimeout(timer);
         try {
-          resolve(config.normalize(chunks));
-        } catch (_err) {
-          resolve([]);
+          ok(config.normalize(chunks));
+        } catch (err) {
+          fail({ reason: 'parse-error', detail: err.message });
         }
       });
     });
-    req.on('error', () => {
+    req.on('error', (err) => {
       clearTimeout(timer);
-      resolve([]);
+      fail({ reason: 'network-error', detail: err.message });
     });
   });
 }
 
+/**
+ * Rows-only view of `fetchViaConfigDetailed`, preserving the historical
+ * contract (`[]` on any failure) for existing callers.
+ * @param {string} provider @param {string} key @returns {Promise<Array>}
+ */
+function fetchViaConfig(provider, key) {
+  return fetchViaConfigDetailed(provider, key).then(r => r.rows);
+}
+
+/**
+ * Per-provider fetch WITH failure reporting. Mirrors
+ * `fetchModelsFromProvider`'s special cases exactly:
+ *  - anthropic without a key: the hardcoded floor, no network, NOT a failure.
+ *  - anthropic with a key that yields nothing: floor rows, failure reported.
+ *  - unknown provider: no rows, not a failure (nothing was attempted).
+ * @param {string} provider @param {string} key
+ * @returns {Promise<{rows: Array, failure: object|null}>}
+ */
+function fetchModelsFromProviderDetailed(provider, key) {
+  const floor = () => ANTHROPIC_MODELS.map(r => ({ ...r, authoritative: false }));
+  if (provider === 'anthropic') {
+    if (!key) { return Promise.resolve({ rows: floor(), failure: null }); }
+    return fetchViaConfigDetailed('anthropic', key).then(({ rows, failure }) =>
+      (rows.length > 0 ? { rows, failure: null } : { rows: floor(), failure }));
+  }
+  const config = PROVIDER_FETCH_CONFIG[provider];
+  if (!config) { return Promise.resolve({ rows: [], failure: null }); }
+  return fetchViaConfigDetailed(provider, key);
+}
+
 /** Providers to fetch: every keyed provider + openrouter (keyless-capable) + anthropic. */
 function providersToFetch(keys) {
   const set = new Set(Object.keys(keys).filter(p => keys[p]));
@@ -190,12 +227,16 @@ function providersToFetch(keys) {
  * Fetch models from all providers that have keys configured; openrouter is
  * always included (keyless public endpoint) as is anthropic (hardcoded list).
  * @param {Object<string, string>} keys - Map of provider → API key string
- * @returns {Promise<Array<{id: string, name: string, contextLength: number|null, pricing: object|null}>>} Combined model list
+ * @returns {Promise<{rows: Array, failures: Array<{provider: string, reason: string, status?: number, detail?: string}>}>}
  */
-async function fetchAllModels(keys) {
+async function fetchAllModelsDetailed(keys) {
   const providers = providersToFetch(keys);
-  const results = await Promise.all(providers.map(p => fetchModelsFromProvider(p, keys[p] || '')));
-  const rows = results.flat();
+  const results = await Promise.all(providers.map(p =>
+    fetchModelsFromProviderDetailed(p, keys[p] || '').then(r => ({ provider: p, ...r }))));
+  const rows = results.flatMap(r => r.rows);
+  const failures = results
+    .filter(r => r.failure)
+    .map(r => ({ provider: r.provider, ...r.failure }));
   // v4.2 §4.4: append local-provider rows via the scheme-aware probe (5s, [] on failure).
   try {
     const { getLocalProviders } = require('./local-providers');
@@ -205,7 +246,17 @@ async function fetchAllModels(keys) {
       listLocalModels(e, { timeoutMs: 5000, bearer: e.apiKeyEnv ? process.env[e.apiKeyEnv] : undefined })));
     for (const r of localResults) { rows.push(...r); }
   } catch (_err) { /* local rows are best-effort — never break the cloud catalog */ }
-  return rows;
+  return { rows, failures };
+}
+
+/**
+ * Rows-only view of `fetchAllModelsDetailed` — the historical signature, kept
+ * so existing callers and their tests are unaffected.
+ * @param {Object<string, string>} keys
+ * @returns {Promise<Array>} Combined model list
+ */
+async function fetchAllModels(keys) {
+  return (await fetchAllModelsDetailed(keys)).rows;
 }
 
 /**
@@ -236,6 +287,8 @@ function groupModelsByFamily(models) {
 module.exports = {
   fetchModelsFromProvider,
   fetchAllModels,
+  fetchAllModelsDetailed,
+  fetchModelsFromProviderDetailed,
   providersToFetch,
   groupModelsByFamily,
   ANTHROPIC_MODELS,

package/src/utils/model-shortlist.js

@@ -60,7 +60,8 @@ function compareShortlistRows(a, b) {
 
 /**
  * @param {string} vendor e.g. 'deepseek'
- * @param {{catalog?: Array<object>, recommendedId?: string, limit?: number}} [options]
+ * @param {{catalog?: Array<object>, recommendedId?: string, limit?: number,
+ *   providerFailures?: Array<{provider:string}>}} [options]
  * @returns {{recommendedId: (string|null), suggested: Array<object>,
  *   rest: Array<object>, total: number}}
  */
@@ -69,7 +70,9 @@ function buildModelShortlist(vendor, options = {}) {
   const limit = Number.isInteger(options.limit) && options.limit > 0
     ? options.limit : SHORTLIST_LIMIT;
 
-  const { preselectedId, rows } = buildProviderDefaultChoices(vendor, { catalog });
+  const { preselectedId, rows } = buildProviderDefaultChoices(vendor, {
+    catalog, providerFailures: options.providerFailures,
+  });
   if (!rows || rows.length === 0) {
     return { recommendedId: null, suggested: [], rest: [], total: 0 };
   }

package/src/utils/provider-default-picker.js

@@ -118,9 +118,11 @@ function chooseRowId(vendor, isDirect, row, paired, catalogInfo) {
  * @param {string} vendor
  * @returns {Array<{id:string,name:string,contextLength:(number|null),pricePerMInput:(number|null),isPreselected:boolean}>}
  */
-function buildRows(catalog, vendor) {
+function buildRows(catalog, vendor, providerFailures) {
   const byId = new Map(catalog.filter(r => r && typeof r.id === 'string').map(r => [r.id, r]));
-  const catalogInfo = { models: catalog };
+  // issue 208: providerFailures MUST ride along -- this rebuilds catalogInfo from a bare
+  // array, so dropping it leaves directFormIfSafe's namespace gate dead in production.
+  const catalogInfo = { models: catalog, providerFailures: providerFailures || [] };
   const directPrefix = `${vendor}/`;
   const orPrefix = `openrouter/${vendor}/`;
   // Hoisted: `vendor` is fixed for the whole call, so this is decided once
@@ -229,7 +231,7 @@ function buildProviderDefaultChoices(vendor, options = {}) {
   if (typeof vendor !== 'string' || !vendor) { return { preselectedId: null, rows: [] }; }
 
   const catalog = Array.isArray(options.catalog) ? options.catalog : [];
-  const rows = buildRows(catalog, vendor);
+  const rows = buildRows(catalog, vendor, options.providerFailures);
   if (rows.length === 0) { return { preselectedId: null, rows: [] }; }
 
   const preselectedId = computePreselectedId(vendor, options.tier, catalog, rows);
@@ -271,6 +273,7 @@ function buildProviderDefaultChoices(vendor, options = {}) {
  * @returns {{alias: string, setAsDefault: boolean}}
  */
 function applyProviderDefault(vendor, chosenId, { seedDefaultIfAbsent = true, catalog } = {}) {
+  // Council C4 (PR 215): NO providerFailures -- directFormIfProven strips only on POSITIVE evidence, so a failed/empty namespace ('unknown') already returns chosenId untouched.
   const catalogInfo = { models: Array.isArray(catalog) ? catalog : [] };
   const storedId = directFormIfProven(vendor, chosenId, catalogInfo);
 

package/src/utils/quick-picks.js

@@ -10,7 +10,8 @@
 
 'use strict';
 
-const { getFamilies, toDefaultAliases, toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
+const { getFamilies, toDefaultAliases, DIVERGENT_VENDORS } = require('./curated-models');
+const { directFormIfSafe } = require('./model-canonicalization');
 
 const MARKER_RE = /(-preview|-exp|-beta|-latest|:free)+$/;
 
@@ -84,12 +85,20 @@ function resolveQuickPicks(catalog) {
  * @param {{vendorPath?:string, routes?:Object<string,string>}} pick
  * @returns {string|undefined}
  */
-function toStorableRoute(pick) {
+function toStorableRoute(pick, catalogInfo) {
   const routes = (pick && pick.routes) || {};
   if (pick && DIVERGENT_VENDORS.has(pick.vendorPath)) {
     return routes[pick.vendorPath] || routes.openrouter;
   }
-  return toCanonicalDefault(routes.openrouter || Object.values(routes)[0]);
+  const route = routes.openrouter || Object.values(routes)[0];
+  if (!route) { return undefined; }
+  // issue 214 remedy 1: this value is PERSISTED (sidecar/setup.js writes it into
+  // config.aliases; toLiveSeedAliases seeds a fresh config with it), so it must
+  // not be a blind prefix strip. directFormIfSafe keeps the optimism for a
+  // namespace that was never fetched while refusing for one the catalog
+  // disproves OR whose fetch was rejected -- the gap #208 closed on the picker
+  // path and left open here.
+  return directFormIfSafe(pick.vendorPath, route, catalogInfo || { models: [] });
 }
 
 /**
@@ -98,15 +107,44 @@ function toStorableRoute(pick) {
  * overlaid value is not a raw prefix strip.
  * @returns {Object<string,string>}
  */
-function toLiveSeedAliases(catalog) {
+function toLiveSeedAliases(catalogOrInfo) {
+  // Accepts the bare models array (historical callers) or a full catalogInfo.
+  // issue 214: the evidence was always handed in and then discarded.
+  const info = Array.isArray(catalogOrInfo)
+    ? { models: catalogOrInfo }
+    : (catalogOrInfo || { models: [] });
   const seeds = toDefaultAliases();
-  for (const r of resolveQuickPicks(catalog || [])) {
+  for (const r of resolveQuickPicks(info.models || [])) {
     if (r.source === 'live' && r.routes.openrouter) {
-      const stored = toStorableRoute(r);
+      const stored = toStorableRoute(r, info);
       if (stored) { seeds[r.alias] = stored; }
     }
   }
   return seeds;
 }
 
-module.exports = { compareIdsDesc, pickCurrent, resolveQuickPicks, toLiveSeedAliases, toStorableRoute };
+
+/**
+ * Per-provider SAFE storable form for a resolved quick pick (issue 214).
+ *
+ * The wizard renderer used to derive this itself, via a hand-copy of
+ * `stripGatewayPrefix` (`toBareIfDirect`) that dropped both of the real
+ * primitive's guards: it stripped `openrouter/` for DIVERGENT_VENDORS
+ * (fabricating anthropic's dot id, which the direct API rejects) and stripped
+ * for a namespace whose fetch had failed. The renderer cannot `require()`, so
+ * the decision is made here -- once, with the catalog in hand -- and shipped
+ * to the page as data.
+ * @param {{vendorPath: string, routes: Object<string,string>}} pick
+ * @param {{models: Array<{id:string}>, providerFailures?: Array<{provider:string}>}} catalogInfo
+ * @returns {Object<string,string>} provider -> safe storable id
+ */
+function canonicalRoutesFor(pick, catalogInfo) {
+  const out = {};
+  const routes = (pick && pick.routes) || {};
+  for (const [provider, route] of Object.entries(routes)) {
+    out[provider] = directFormIfSafe(pick.vendorPath, route, catalogInfo || { models: [] });
+  }
+  return out;
+}
+
+module.exports = { compareIdsDesc, canonicalRoutesFor, pickCurrent, resolveQuickPicks, toLiveSeedAliases, toStorableRoute };

package/src/utils/result-schema.js

@@ -231,7 +231,8 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
  *   probeSkipped?: string|null}} opts
  */
 function buildAuditDoc({
-  stale, catalogAvailable, gatewayFindings = [], drifted = [], probe = [], probeSkipped = null
+  stale, catalogAvailable, gatewayFindings = [], drifted = [], probe = [], probeSkipped = null,
+  providerFailures = []
 }) {
   return {
     schemaVersion: SCHEMA_VERSION,
@@ -246,6 +247,11 @@ function buildAuditDoc({
     probeCount: probe.length,
     probe,
     probeSkipped,
+    // issue 209: providers ATTEMPTED and REJECTED for the catalog in hand. An
+    // empty namespace is otherwise indistinguishable from a provider that
+    // genuinely serves nothing.
+    providerFailuresCount: providerFailures.length,
+    providerFailures,
   };
 }
 

package/src/utils/session-status.js

@@ -0,0 +1,73 @@
+/**
+ * @module utils/session-status
+ * #202: render the engine's SESSION STATUS as a clause on a leg's death report.
+ *
+ * ⚠️ The JSDoc leads this file, ahead of `'use strict'`, matching
+ * `utils/ttft.js` / `utils/text-sanitize.js` / `utils/engine-skew.js`:
+ * `scripts/generate-docs.js` only reads a block comment that starts at byte
+ * zero, so a `// path` line above it would leave this module's CLAUDE.md row
+ * blank.
+ *
+ * WHY THIS EXISTS. `headless.js` asks the engine for session status only inside
+ * `if (mirror.output.length > 0)` — a gate a zero-output leg never satisfies. So
+ * the one leg that needs diagnosing is precisely the one that never asks, and
+ * every silent death was reported as "no output in Ns" with no cause attached.
+ * The pinned SDK publishes `SessionStatus` as
+ * `{type:'idle'} | {type:'retry', attempt, message, next} | {type:'busy'}`, and
+ * the `retry` arm carries the upstream error verbatim.
+ *
+ * NONE of the three types is suppressed as uninteresting — they point in
+ * DIFFERENT directions, and which one comes back is the discrimination #202
+ * spent six CI runs failing to make by argument:
+ *   · `busy`  — the engine is still waiting on the provider ⇒ provider-side.
+ *   · `idle`  — the engine believes it is DONE having produced nothing ⇒
+ *               engine-side, which is the shape #133 turned out to be.
+ *   · `retry` — the engine is re-attempting, and says why ⇒ the named cause.
+ *
+ * ⚠️ APPEND-ONLY, exactly like `engine-skew.js :: formatSkewSuffix`: no status
+ * (or an unusable one) returns `''`, so a reason string built without one is
+ * byte-for-byte what it was before this module existed, and
+ * `sidecar/models-probe.js`'s `/^NO_OUTPUT_BACKSTOP:/` classification — a PREFIX
+ * test — is unaffected either way.
+ *
+ * ⚠️ `message` is UNTRUSTED third-party text: it originates at the provider,
+ * lands in run.json, and on CI is rendered into a sticky PR comment. It goes
+ * through the house sanitizer (`text-sanitize.js :: collapseExcerpt`) at a short
+ * cap rather than being trusted to the workflow's downstream sed rules — one
+ * sanitizer, one dialect, per that module's own ruling.
+ */
+
+'use strict';
+
+const { collapseExcerpt } = require('./text-sanitize');
+
+/** Short cap: this is a clause on a one-line death report, not a log dump. */
+const MAX_STATUS_MESSAGE_CHARS = 200;
+
+/**
+ * The death-report clause for an engine session status.
+ * @param {*} status - an SDK SessionStatus, or anything at all
+ * @returns {string} ` (session: …)`, or '' when nothing usable was observed
+ */
+function formatSessionStatusSuffix(status) {
+  if (!status || typeof status !== 'object') { return ''; }
+  // A non-string `type` is DROPPED rather than coerced: `String({})` renders
+  // '[object Object]', which would read as an observation rather than as the
+  // absence it actually is.
+  if (typeof status.type !== 'string') { return ''; }
+  // ⚠️ CLASSIFY on the RAW value, RENDER the sanitized one (#219 round 2,
+  // deepseek). Branching on the sanitized type let the sanitizer's own
+  // normalisation decide the arm — anything collapsing to 'retry' took the retry
+  // path — so a future SDK identifier could be misclassified by a function whose
+  // job is display, not semantics. Only the exact published identifier routes.
+  const type = collapseExcerpt(status.type, 40);
+  if (!type) { return ''; }
+  // An unrecognised type is still reported. A future SDK arm must not read as
+  // "no status was observed" — that silence is what this clause removes.
+  if (status.type !== 'retry') { return ` (session: ${type})`; }
+  const attempt = Number.isFinite(status.attempt) ? ` attempt ${status.attempt}` : '';
+  const raw = collapseExcerpt(status.message, MAX_STATUS_MESSAGE_CHARS);
+  return ` (session: retry${attempt}${raw ? ` — ${raw}` : ''})`;
+}
+
+module.exports = { formatSessionStatusSuffix, MAX_STATUS_MESSAGE_CHARS };

package/src/utils/ttft.js

@@ -9,12 +9,23 @@
  * blank the way `utils/result-schema.js`'s already is.
  *
  * `ttftMs` is produced once — in `src/headless.js`'s poll loop, as a
- * `Date.now()` delta — and then passes four EMIT GATES on its way to a
+ * `Date.now()` delta — and then passes five EMIT GATES on its way to a
  * document: `headless.js`'s three returns, `sidecar/fanout-leg.js`'s leg patch,
- * `utils/result-schema.js :: buildRunResult`, and
- * `council/run-stats-entry.js :: buildRunStatsEntry`. Every gate used to spell
- * its own `typeof x === 'number'` test, which is four chances to disagree and
- * four ways to publish a value both schemas forbid.
+ * `utils/result-schema.js :: buildRunResult`,
+ * `council/run-stats-entry.js :: buildRunStatsEntry`, and
+ * `council/tally.js :: tally`'s runStats re-projection. Every gate used to spell
+ * its own `typeof x === 'number'` test, which is five chances to disagree and
+ * five ways to publish a value both schemas forbid.
+ *
+ * ⚠️ The fifth gate is different in KIND from the four above it, which is why it
+ * was missed for a release (#202). Those four are PRODUCERS — each writes the
+ * field onto a document it is building. `tally.js` is a RE-PROJECTION: it copies
+ * an already-built row through a hand-maintained allowlist, so omitting the field
+ * there does not fail to produce it, it DESTROYS one already produced. Between
+ * v4.9.0 and v4.9.1 that is exactly what happened — the probe wrote real values
+ * into tally-input.json and every one was stripped before tally.json and
+ * verdict.json, the only run artifacts CI uploads (MEASURED, run 33030485388:
+ * 11 of 12 rows carried it going in, 0 of 12 coming out).
  *
  * ⚠️ `typeof` is not the schema's contract. `schemas/run.schema.json` and
  * `schemas/council-tally.schema.json` both declare this field
@@ -35,7 +46,7 @@
  * already means "no honest measurement was made", and a dishonest number is
  * exactly that. `0` itself stays a real, emittable measurement.
  *
- * ⚠️ Three of the four gates import this. The fourth,
+ * ⚠️ Four of the five gates import this. The one that does not,
  * `council/run-stats-entry.js`, is pinned REQUIRE-FREE (P3,
  * tests/council/run-stats-entry.test.js — the pin fires on the character
  * sequence anywhere in that file, comments included) so require-free consumers