amicus 4.9.1 → 4.9.3

package/src/utils/doctor-key-auth-check.js

@@ -0,0 +1,271 @@
+/**
+ * @module doctor-key-auth-check
+ * The `key-auth` doctor row (issue #210), split out of src/cli-handlers-doctor.js
+ * to keep that file under the 300-line size gate (mirrors
+ * doctor-base-url-check.js / doctor-alias-check.js / doctor-local-providers-check.js).
+ *
+ * WHY IT EXISTS: doctor's `keys` row tests PRESENCE only — readApiKeys()
+ * returns booleans — and validateApiKey() was called at exactly two SAVE-TIME
+ * sites (electron/ipc-setup.js, src/cli-handlers.js). A key that rotted after
+ * it was entered, or that reached .env by any path other than the wizard /
+ * `amicus key`, was never re-checked: #210's reporter had a green doctor while
+ * the stored DeepSeek key returned 401 and the catalog served 0 deepseek rows.
+ *
+ * THE STATUS RULE (the whole design problem is FALSE ALARMS):
+ *   - HTTP 401 → 'error'. That is the server saying "this credential is not
+ *     accepted", and nothing else in the space says it that plainly.
+ *   - EVERYTHING else → 'warn'. Timeout, DNS/socket error, 5xx, 429, an
+ *     unexpected 4xx, a result with no status at all: none of these
+ *     distinguish a rotted key from a laptop on a plane. Unrecognised input
+ *     falls to the ambiguous side ON PURPOSE — the failure mode of a false
+ *     'error' here is a user re-entering a perfectly good key.
+ *   - HTTP 403 is explicitly on the WARN side (council finding 1, PR 221). It
+ *     read as definitive at first, which was wrong: Google returns 403 for
+ *     "API not enabled" and for quota, and a WAF returns it for bot
+ *     protection. Treating it as a verdict traded the false-GREEN this check
+ *     was built to kill for a false-ALARM of the same shape.
+ *   - a stored key with NO validation endpoint → 'warn'. It cannot be probed,
+ *     so this check cannot vouch for it (council finding C1, first review).
+ *   - no keys stored → 'ok' + "skipped" (mirrors the openrouter-credit skip).
+ *
+ * The evidence is the STRUCTURED `status` field, not the prose.
+ * classifyProbeFailure used to regex "(401)" out of the error string, which
+ * made control flow depend on message wording — a reword upstream that dropped
+ * the parentheses would have degraded every row to a permanent "unverified"
+ * with nothing failing to announce it (council finding 2, PR 221).
+ *
+ * NO KEY MATERIAL, NO URLs, EVER. Four layers, each structural:
+ *   1. Only provider IDS and a reason built here reach the row — the raw error
+ *      string is never echoed.
+ *   2. Every live authenticated request realDeps() can make goes through the
+ *      probe wrappers below (probeApiKey, probeOpenRouterCredit), which share
+ *      one gate. An earlier version of this note claimed probeApiKey alone was
+ *      that gate while checkOpenRouterCredit sat beside it unguarded — the
+ *      claim is now true rather than merely written down.
+ *   3. api-key-validation.js redacts the key from any message before it
+ *      escapes, and resolves rather than rejecting on a synchronous throw from
+ *      https.get. That is the ROOT fix (council finding 3, PR 221): the Google
+ *      probe embeds the key as `?key=...`, and the two save-time call sites
+ *      have no protection of their own — electron/ipc-setup.js hands
+ *      `err.message` to the renderer and logs it, and src/cli-handlers.js has
+ *      no try/catch at all.
+ *   4. Each probe here is STILL individually caught, because this module must
+ *      not depend on an injected validator honouring that contract.
+ *
+ * Probes run in PARALLEL: validateApiKey's own timeout is 10s, so five stored
+ * keys probed sequentially would add up to 50s to a `doctor` run. Fan-out is
+ * bounded by the number of configured providers (5 today), so no pool is needed.
+ */
+
+'use strict';
+
+const { VALIDATION_ENDPOINTS } = require('./api-key-validation');
+
+const ID = 'key-auth';
+const NAME = 'API key auth';
+
+/** Statuses that are an authoritative "this credential is not accepted". */
+// 401 only. 403 was here and is not a credential verdict — see
+// classifyProbeFailure (council finding 1, PR 221).
+const DEFINITIVE_STATUSES = new Set([401]);
+
+const REENTER_HINT = (providers) =>
+  `amicus key <provider> <key>  (re-enter the rejected key for: ${providers.join(', ')})`;
+
+const UNPROBEABLE_HINT =
+  'Not a rejection — amicus has no validation endpoint for this provider, so the '
+  + 'key could not be checked either way. Add one in utils/api-key-validation.js '
+  + '(VALIDATION_ENDPOINTS) to bring it under this check.';
+
+const UNVERIFIED_HINT =
+  'Not a rejection — the probe could not reach the provider (offline, DNS failure, '
+  + '5xx or timeout). Re-run `amicus doctor` when connectivity is restored.';
+
+/**
+ * Whether a live authenticated request is allowed right now. The shared gate
+ * for BOTH probes below — that sharing is the point, see layer 2 in the header.
+ *
+ * Council finding 7 (PR 221): `runDoctorChecks` merges a caller's deps over
+ * `realDeps()`, so ANY suite that builds deps by hand and forgets to inject a
+ * double — i.e. bypasses tests/helpers/doctor-base-deps.js — would fire live
+ * authenticated HTTPS requests using the developer's REAL
+ * ~/.config/amicus/.env keys. Nothing would fail; the suite would just be
+ * slower and quietly spending someone's credentials. Suites that DO inject a
+ * double are unaffected: theirs wins the merge and these are never called.
+ *
+ * @returns {boolean}
+ */
+function liveProbesDisabled() {
+  return !require('./live-probes').liveProbesAllowed();
+}
+
+/** Marker string the classifier recognises, so a skip reads as a skip. */
+const SKIPPED_REASON = 'probe skipped (live probes disabled)';
+
+const SKIPPED = () => Promise.resolve({
+  valid: false, status: null, skipped: true, error: SKIPPED_REASON,
+});
+
+/**
+ * The key-validation probe `realDeps()` injects, behind the shared gate.
+ * A skip resolves as an ordinary unverified result, so the row warns rather
+ * than claiming health it did not establish.
+ * @returns {Promise<{valid: boolean, status: number|null, error?: string}>}
+ */
+function probeApiKey(provider, key) {
+  if (liveProbesDisabled()) { return SKIPPED(); }
+  return require('./api-key-validation').validateApiKey(provider, key);
+}
+
+/**
+ * The OpenRouter credit probe, behind the SAME guard.
+ *
+ * ⚠️ This exists because the claim above was FALSE when first written. The
+ * header said probeApiKey was "the one place" a live authenticated request is
+ * decided, while realDeps() still injected `checkOpenRouterCredit` as an
+ * unguarded raw require — an authenticated call to openrouter.ai/api/v1/key
+ * with the developer's stored key, reachable by exactly the hand-built dep
+ * suites the guard was written for. Council review of PR 222 falsified the
+ * claim; routing both probes through one gate makes it true instead of
+ * deleting it. Resolves the same shape checkOpenRouterCredit does, so the
+ * caller's `res.warning` branch is unaffected.
+ */
+function probeOpenRouterCredit(key) {
+  if (liveProbesDisabled()) {
+    // ⚠️ `warning: null` alone is what checkOpenRouterCredit resolves when the
+    // account is FINE, so returning it here made a skipped probe render as
+    // "credit ok" — a false green reporting a funded account nobody checked.
+    // Introduced in the same commit that removed the identical shape from the
+    // anthropic branch, one function over, with a test blessing it. Council
+    // review of PR 222. `skipped` is what the row branches on now.
+    return Promise.resolve({
+      skipped: true, checked: false,
+      warning: null, isFreeTier: false, limitRemaining: null, limit: null, usage: null,
+    });
+  }
+  return require('./api-key-validation').checkOpenRouterCredit(key);
+}
+
+/**
+ * Classify one validateApiKey failure as a definitive auth rejection or an
+ * ambiguous one, and produce the SANITIZED reason that may be printed.
+ *
+ * Reads the STRUCTURED `status` field. This used to regex the status out of
+ * `error` — which made a control-flow decision depend on message wording, so a
+ * reword upstream that dropped the parentheses would have silently degraded
+ * every row to a permanent "unverified" with no test failing to say so
+ * (council finding 2, PR 221). api-key-validation.js returns the status as
+ * data now. A result with no status is ambiguous, which is the fail-safe side.
+ *
+ * The returned `reason` is built here from scratch — it never contains any
+ * substring of `error`, which is what makes the no-URL/no-key guarantee
+ * structural rather than a hope about provider prose.
+ *
+ * @param {{status: number|null, error?: string}} [res] validateApiKey's result
+ * @returns {{definitive: boolean, reason: string}}
+ */
+function classifyProbeFailure(res) {
+  const r = (res && typeof res === 'object') ? res : {};
+  const status = (typeof r.status === 'number' && Number.isFinite(r.status)) ? r.status : null;
+
+  if (status !== null && DEFINITIVE_STATUSES.has(status)) {
+    return { definitive: true, reason: `rejected (HTTP ${status})` };
+  }
+  if (status === 403) {
+    // Deliberately NOT definitive (council finding 1). Google returns 403 for
+    // "API not enabled" and for quota; a WAF returns it for bot protection.
+    // Telling someone to re-enter a working key is the false-ALARM twin of the
+    // false-GREEN this check exists to kill, and this check's whole design
+    // premise is that a false error costs more than a warn.
+    return { definitive: false, reason: 'unverified (HTTP 403 — forbidden, may not be the key)' };
+  }
+  if (status !== null) {
+    return { definitive: false, reason: `unverified (HTTP ${status})` };
+  }
+  if (r.skipped) {
+    // Named, not folded into "unreachable" — the two have different fixes and
+    // conflating them is the kind of small dishonesty this row exists to avoid.
+    return { definitive: false, reason: 'unverified (probe skipped)' };
+  }
+  if (/timed?\s*out|timeout/i.test(typeof r.error === 'string' ? r.error : '')) {
+    return { definitive: false, reason: 'unverified (timed out)' };
+  }
+  return { definitive: false, reason: 'unverified (unreachable)' };
+}
+
+/**
+ * Probe one stored key. Always resolves; never surfaces `error`/`e.message`.
+ * @returns {Promise<{provider: string, part: string, rejected: boolean, unverified: boolean}>}
+ */
+async function probeOne(d, provider, key) {
+  let res;
+  try {
+    res = await d.validateApiKey(provider, key);
+  } catch (_e) {
+    // See rule 2 in the file header: _e.message can carry the Google probe URL,
+    // key included. It is deliberately dropped rather than logged.
+    return { provider, part: `${provider}: unverified (probe failed)`, rejected: false, unverified: true };
+  }
+  if (res && res.valid) {
+    return { provider, part: `${provider}: valid`, rejected: false, unverified: false };
+  }
+  const { definitive, reason } = classifyProbeFailure(res);
+  return { provider, part: `${provider}: ${reason}`, rejected: definitive, unverified: !definitive };
+}
+
+/**
+ * @param {{readApiKeyValues: () => Object<string,string>,
+ *          validateApiKey: (provider:string, key:string)
+ *            => Promise<{valid:boolean, status:number|null, error?:string}>}} d
+ * @returns {Promise<{id:string, name:string, status:string, message:string, hint:?string}>}
+ */
+async function evaluateKeyAuth(d) {
+  const values = d.readApiKeyValues() || {};
+  // Object.keys + bracket access (never `for..in`) — same prototype-chain
+  // discipline as doctor-local-providers-check.js.
+  const stored = Object.keys(values).filter((p) => values[p]);
+
+  if (stored.length === 0) {
+    return { id: ID, name: NAME, status: 'ok', message: 'no keys stored — skipped', hint: null };
+  }
+
+  // A stored key for a provider with no validation endpoint cannot be probed at
+  // all — so this check cannot vouch for it, and must not imply that it can.
+  //
+  // ⚠️ This originally reported such a key but still returned `ok`, on the
+  // reasoning that adding a provider to provider-registry.js ahead of an
+  // endpoint in api-key-validation.js should not turn every doctor run yellow.
+  // Council finding C1 on PR #221 (raised by `gpt`) is right that this is the
+  // EXACT false-green class #210 exists to close: a row that says "ok" while a
+  // stored credential was never checked. It warns now. The cost is zero today —
+  // PROVIDER_ENV_MAP and VALIDATION_ENDPOINTS carry identical key sets, so
+  // `unprobeable` is always empty and this can only fire once someone actually
+  // creates the gap. Silence is not health.
+  const probeable = stored.filter((p) => VALIDATION_ENDPOINTS[p]);
+  const unprobeable = stored.filter((p) => !VALIDATION_ENDPOINTS[p]);
+
+  // Parallel by construction — see the file header.
+  const results = await Promise.all(probeable.map((p) => probeOne(d, p, values[p])));
+
+  const parts = results.map((r) => r.part)
+    .concat(unprobeable.map((p) => `${p}: not probeable (no validation endpoint)`));
+  const message = parts.join('; ');
+
+  const rejected = results.filter((r) => r.rejected).map((r) => r.provider);
+  if (rejected.length > 0) {
+    return { id: ID, name: NAME, status: 'error', message, hint: REENTER_HINT(rejected) };
+  }
+  // Unprobeable counts as unverified (C1): 'ok' here would vouch for a key
+  // nothing checked. A definitive rejection still outranks it above.
+  if (results.some((r) => r.unverified) || unprobeable.length > 0) {
+    const hint = unprobeable.length > 0 && !results.some((r) => r.unverified)
+      ? UNPROBEABLE_HINT : UNVERIFIED_HINT;
+    return { id: ID, name: NAME, status: 'warn', message, hint };
+  }
+  return { id: ID, name: NAME, status: 'ok', message, hint: null };
+}
+
+module.exports = {
+  evaluateKeyAuth, classifyProbeFailure,
+  probeApiKey, probeOpenRouterCredit, liveProbesDisabled, SKIPPED_REASON,
+};

package/src/utils/live-probes.js

@@ -0,0 +1,53 @@
+/**
+ * @module live-probes
+ * The single gate on outbound AUTHENTICATED network probes made by diagnostics
+ * (`amicus doctor` / `init` / the setup finale), which run with the user's real
+ * stored keys.
+ *
+ * OPT-IN, NOT OPT-OUT. `bin/amicus.js` — the one entry point every command
+ * routes through — calls enable() at startup. Nothing else does, so a module
+ * required directly (by a test, a script, another tool) can never probe.
+ *
+ * ⚠️ WHY IT IS SHAPED THIS WAY. The first version detected test RUNNERS
+ * instead: JEST_WORKER_ID, VITEST, NODE_TEST_CONTEXT. That is a blocklist
+ * heuristic, and a blocklist is only as good as its enumeration — a bespoke
+ * runner, a plain `node script.js`, or a harness nobody thought of walks
+ * straight past it and spends the developer's credentials. Council review of
+ * PR 222. Detecting "am I in a test?" is unbounded; asserting "I am the CLI"
+ * is a single known fact, so the burden moved to the side that can actually
+ * discharge it.
+ *
+ * ⚠️ AND WHY THAT IS SAFE. Inverting a default risks the opposite failure: miss
+ * an entry point and production silently stops probing. That is survivable
+ * ONLY because a skipped probe is never reported as healthy — callers must
+ * surface it as unverified (see doctor-key-auth-check.js and the
+ * `openrouter-credit` row). Worst case is a visible warn, never a false green.
+ * If you add an entry point that should probe, call enable() there; if you
+ * forget, `doctor` says so out loud.
+ */
+
+'use strict';
+
+let enabled = false;
+
+/** Allow live probes for the remainder of this process. Called by bin/amicus.js. */
+function enableLiveProbes() {
+  enabled = true;
+}
+
+/**
+ * Whether a live authenticated probe may run right now.
+ * `AMICUS_NO_NETWORK_PROBES=1` forces off even for the CLI — an escape hatch
+ * for air-gapped or rate-limited environments.
+ */
+function liveProbesAllowed() {
+  if (process.env.AMICUS_NO_NETWORK_PROBES === '1') { return false; }
+  return enabled;
+}
+
+/** Test-only: restore the default (disabled) state. */
+function _resetLiveProbes() {
+  enabled = false;
+}
+
+module.exports = { enableLiveProbes, liveProbesAllowed, _resetLiveProbes };

package/src/utils/model-fetcher.js

@@ -45,6 +45,8 @@ const PROVIDER_FETCH_CONFIG = {
         id: `openrouter/${m.id}`,
         name: m.name || m.id,
         contextLength: m.context_length ?? null,
+        // #218: real output ceiling (411/417 rows); clamps outputBudget -- see utils/model-output-limit.js.
+        maxOutputTokens: (m.top_provider && m.top_provider.max_completion_tokens) ?? null,
         pricing: m.pricing
           ? { prompt: m.pricing.prompt ?? null,
               completion: m.pricing.completion ?? null }

package/src/utils/model-output-limit.js

@@ -0,0 +1,124 @@
+/**
+ * @module model-output-limit
+ * Issue #218 — the per-model `limit` descriptor amicus hands opencode.
+ *
+ * THE PROBLEM: every council leg reserved `max_tokens: 32000` regardless of the
+ * model's real ceiling. OpenRouter validates that RESERVATION against remaining
+ * credit BEFORE serving, so legs died in 2.2s with zero tokens and a literal
+ * "You requested up to 32000 tokens, but can only afford 354". amicus never set
+ * the value — `buildProviderModels` registered every model as `{}`, leaving
+ * opencode's own default to govern.
+ *
+ * WHERE 32000 COMES FROM (measured, in the pinned 1.18.15 binary, not inferred):
+ *
+ *     var MY=32000
+ *     function Hy($,Z=MY){return Math.min($.limit.output,Z)||Z}
+ *
+ * i.e. `ProviderTransform.maxOutputTokens(model) = Math.min(model.limit.output,
+ * OUTPUT_TOKEN_MAX)`. Three consequences, each a trap:
+ *
+ *   1. Supplying the model's REAL ceiling is ARITHMETICALLY INERT. kimi-k3's
+ *      true ceiling is 943,718 and Math.min(943718, 32000) is still 32000. Only
+ *      a value BELOW 32000 changes the outbound request. The issue's headline
+ *      framing ("a 32,000 reservation against a 943,718 ceiling is arbitrary")
+ *      reads as though feeding the real ceiling would help. It would not.
+ *   2. `limit.context` is MANDATORY whenever `limit` is present. A `limit` with
+ *      only `output` is a hard ConfigInvalidError — and it poisons the ENTIRE
+ *      config for the server's lifetime, not just that model. Measured against
+ *      a live `opencode serve` + GET /config/providers.
+ *   3. `output: 0` is swallowed by the `|| Z` and falls back to 32000.
+ *
+ * WHAT THIS DOES NOT FIX. #218 conflates two modes that pull in OPPOSITE
+ * directions on this one knob. Mode 1 (credit rejection) needs the reservation
+ * LOWERED — that is what this module enables. Mode 2 (a leg spending its whole
+ * allowance on reasoning and emitting 0-2 output tokens) would need it RAISED,
+ * which the descriptor cannot do at all because of the Math.min; its real cause
+ * is reasoning effort, a knob amicus already owns (`sidecar/fanout.js` →
+ * `body.reasoning`). Lowering the budget makes those legs fail faster and
+ * cheaper. It does not make them produce output. No claim is made that it does.
+ *
+ * POLICY: opt-in, no default change. With no configured budget every model is
+ * still registered as `{}` — byte-identical to pre-#218 behaviour.
+ */
+
+'use strict';
+
+/**
+ * A usable positive, finite INTEGER count. Rejects strings, booleans, NaN,
+ * Infinity, and anything that floors to zero.
+ *
+ * ⚠️ Order matters, and getting it wrong was council finding C2 on PR #221.
+ * Testing `v > 0` BEFORE flooring let 0.5 through and returned `Math.floor(0.5)`
+ * === 0 — breaking this function's own "positive integer, or null" contract.
+ * Downstream that was worse than a bad number: computeModelLimit's
+ * `Math.max(1, ...)` guard, which exists to stop `output: 0` reaching opencode,
+ * laundered the bogus 0 into a bogus `output: 1` — a ONE-TOKEN reservation on
+ * every leg. A hardening masking the very input it was meant to reject. Floor
+ * first, then test positivity, so a sub-1 value is rejected outright.
+ */
+function positiveCount(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) { return null; }
+  const n = Math.floor(v);
+  return n > 0 ? n : null;
+}
+
+/**
+ * Coerce a configured output budget to a usable integer, or null.
+ * null means "emit no limit" — the opt-in default, and today's behaviour.
+ * @param {*} v raw `config.outputBudget`
+ * @returns {number|null}
+ */
+function normalizeOutputBudget(v) {
+  // `typeof true === 'boolean'` and `'8000'` is a string: both rejected. A
+  // config knob is only honoured when it is unambiguously a number.
+  return positiveCount(v);
+}
+
+/**
+ * Index catalog rows by full route id for O(1) lookup during route walking.
+ * A Map (not an object) so a model id colliding with an Object.prototype member
+ * — 'constructor', 'toString' — cannot resolve to an inherited function. Same
+ * discipline as the `__proto__: null` alias table in config.js.
+ * @param {Array<{id:string, contextLength:?number, maxOutputTokens:?number}>} models
+ * @returns {Map<string, {contextLength:?number, maxOutputTokens:?number}>}
+ */
+function buildLimitLookup(models) {
+  const out = new Map();
+  if (!Array.isArray(models)) { return out; }
+  for (const m of models) {
+    if (!m || typeof m !== 'object' || typeof m.id !== 'string') { continue; }
+    out.set(m.id, {
+      contextLength: m.contextLength ?? null,
+      maxOutputTokens: m.maxOutputTokens ?? null,
+    });
+  }
+  return out;
+}
+
+/**
+ * The `limit` descriptor for one model, or null when it must not be emitted.
+ *
+ * Returns null — meaning "register as `{}`, exactly as before" — whenever any
+ * input is missing or unusable. That is deliberate: a partial descriptor is not
+ * a partial improvement here, it is a fatal config error (rule 2 above).
+ *
+ * @param {?{contextLength:?number, maxOutputTokens:?number}} row catalog row
+ * @param {?number} budget normalized output budget
+ * @returns {?{context:number, output:number}}
+ */
+function computeModelLimit(row, budget) {
+  const want = positiveCount(budget);
+  if (want === null || !row || typeof row !== 'object') { return null; }
+
+  const context = positiveCount(row.contextLength);
+  const ceiling = positiveCount(row.maxOutputTokens);
+  // Both or neither. Without a known ceiling a blanket budget would REGRESS a
+  // small model: an 8000 budget against a real 4096 ceiling sends an
+  // over-ceiling max_tokens, where today opencode's own Math.min keeps it
+  // correct. The ceiling is a hard requirement for clamping, not a nicety.
+  if (context === null || ceiling === null) { return null; }
+
+  return { context, output: Math.max(1, Math.min(ceiling, want)) };
+}
+
+module.exports = { normalizeOutputBudget, buildLimitLookup, computeModelLimit };

package/src/utils/openrouter-credit.js

@@ -0,0 +1,104 @@
+/**
+ * @module openrouter-credit
+ * The OpenRouter credit/limit probe, split out of api-key-validation.js to keep
+ * that module under the 300-line size gate — the same reason it was itself
+ * split out of api-key-store.js. Different concern, too: this asks what the
+ * ACCOUNT can afford, not whether the credential is accepted.
+ *
+ * Re-exported from api-key-validation.js so every existing call site keeps
+ * working unchanged.
+ */
+
+'use strict';
+
+const https = require('https');
+
+/** Warning string for a zero-credit OpenRouter key (paid models will 402). */
+const OPENROUTER_NO_CREDIT_WARNING =
+  'OpenRouter key has no remaining credit — paid models will fail (402). ' +
+  'Add credit at openrouter.ai/credits, or build a free council (amicus setup → option 2).';
+
+/** Warning string for a free-tier OpenRouter key. */
+const OPENROUTER_FREE_TIER_WARNING =
+  'OpenRouter key is free tier — only :free models will route; paid models will fail (402). ' +
+  'Add credit at openrouter.ai/credits to use paid models.';
+
+/**
+ * Non-blocking credit/limit check for an OpenRouter key.
+ *
+ * Hits GET https://openrouter.ai/api/v1/key (returns limit, usage,
+ * is_free_tier, limit_remaining) and produces a WARNING — never an error —
+ * when is_free_tier is true or limit_remaining <= 0. Any failure (non-200,
+ * network error, malformed body) resolves with warning:null so setup is
+ * never blocked. Free-tier councils against free models are legitimate.
+ *
+ * @param {string} key OpenRouter API key
+ * @returns {Promise<{checked: boolean, warning: string|null, isFreeTier: boolean,
+ *   limitRemaining: number|null, limit: number|null, usage: number|null}>}
+ *   `checked` is false whenever no answer was obtained. Never infer health
+ *   from `warning: null` alone — see the note on `none` below.
+ */
+function checkOpenRouterCredit(key) {
+  // ⚠️ `checked: false` is the whole point. Every failure path below resolves
+  // THIS object, and `warning: null` is also what a perfectly healthy account
+  // resolves — so a caller branching on `warning` alone cannot tell "the
+  // account is fine" from "the probe never got an answer", and renders the
+  // first for the second. That is the false green the fourth council pass
+  // found still alive on the network-failure path after it had been fixed only
+  // for the gate-disabled one. Intent-to-probe and result-of-probe are
+  // different facts and now have different fields.
+  const none = {
+    checked: false,
+    warning: null, isFreeTier: false, limitRemaining: null, limit: null, usage: null
+  };
+  if (!key || key.trim().length === 0) {
+    return Promise.resolve(none);
+  }
+
+  const headers = { 'Authorization': `Bearer ${key.trim()}` };
+
+  return new Promise((resolve) => {
+    const req = https.get('https://openrouter.ai/api/v1/key', { headers }, (res) => {
+      let body = '';
+      // Same response-stream gap as validateApiKey (#224). `none` carries
+      // checked:false, so a mid-flight death reports "could not be checked"
+      // rather than falling through to "credit ok".
+      res.on('error', () => { resolve(none); });
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) { resolve(none); return; }
+        let data;
+        try {
+          data = (JSON.parse(body) || {}).data || {};
+        } catch (_e) {
+          resolve(none);
+          return;
+        }
+        const isFreeTier = data.is_free_tier === true;
+        const limitRemaining = (typeof data.limit_remaining === 'number')
+          ? data.limit_remaining : null;
+        const limit = (typeof data.limit === 'number') ? data.limit : null;
+        const usage = (typeof data.usage === 'number') ? data.usage : null;
+
+        let warning = null;
+        if (limitRemaining !== null && limitRemaining <= 0) {
+          warning = OPENROUTER_NO_CREDIT_WARNING;
+        } else if (isFreeTier) {
+          warning = OPENROUTER_FREE_TIER_WARNING;
+        }
+        resolve({ checked: true, warning, isFreeTier, limitRemaining, limit, usage });
+      });
+    });
+    req.setTimeout(10000, () => {
+      req.destroy();
+      resolve(none);
+    });
+    req.on('error', () => { resolve(none); });
+  });
+}
+
+module.exports = {
+  checkOpenRouterCredit,
+  OPENROUTER_NO_CREDIT_WARNING,
+  OPENROUTER_FREE_TIER_WARNING,
+};

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