amicus 4.9.2 → 4.9.4

package/src/utils/api-key-validation.js

@@ -31,15 +31,123 @@ const VALIDATION_ENDPOINTS = {
   }
 };
 
-/** Validate an API key by making a test request to the provider's API */
+/**
+ * A printable message from any throwable — Error, string, or object (#224).
+ *
+ * ⚠️ EVERY step is inside the try, including reading `.message`. `String(x)`
+ * THROWS for a null-prototype object ("Cannot convert object to primitive
+ * value") and for one whose toString throws, and a `message` getter can throw
+ * too. This runs synchronously inside the res.on('error') listener added for
+ * #224, so a throw here escapes the promise as an uncaught async exception —
+ * trading the crash that issue removed for a narrower one. Caught in the
+ * council review of PR 225; measured, not hypothesised.
+ *
+ * (A Symbol is NOT among the hazards: String(Symbol()) is well-defined. Only
+ * `'' + sym` throws, and this never does that.)
+ */
+function messageOf(err) {
+  try {
+    if (err === null || err === undefined) { return ''; }
+    const m = err.message;
+    if (typeof m === 'string' && m.length > 0) { return m; }
+    return String(err);
+  } catch (_e) {
+    return '(unprintable error)';
+  }
+}
+
+const FORBIDDEN_MESSAGE =
+  'Forbidden (403) — the request was rejected, but this may be a disabled API, '
+  + 'a quota, or a region/bot block rather than the key';
+
+/**
+ * Strip every spelling of a secret out of a message before it can escape.
+ *
+ * The Google probe embeds the key in the URL as `?key=...`, so ANY error text
+ * that quotes the request URL quotes the key with it — Node's ERR_INVALID_URL
+ * and several socket errors do exactly that. Redacting here, at the source,
+ * is what protects the callers that never look: electron/ipc-setup.js returns
+ * `err.message` straight to the renderer AND logs it, and src/cli-handlers.js
+ * awaits this function with no try/catch at all. (Council finding 3, PR 221.)
+ *
+ * Two passes, in this order:
+ *   1. Mask `key=` / `api_key=` / `access_token=` query parameters
+ *      structurally. This is what actually protects the Google probe, and it
+ *      works for a key of ANY length.
+ *   2. Remove the key's own spellings — raw, percent-encoded, and the
+ *      form-encoded `+`-for-space variant — but only when the key is at least
+ *      8 characters. Blind substring replacement of a 1-2 character key
+ *      rewrote unrelated diagnostics (every "a" in a DNS error became ***)
+ *      while protecting nothing real. Council review of PR 222.
+ */
+function redactSecret(text, key) {
+  // Coerce, don't discard. This returned '' for anything that was not a
+  // string, so a thrown string or a non-Error object (`throw 'boom'`) turned
+  // a diagnostic into a blank message — the caller then reported a failure it
+  // could not describe. Issue #224.
+  // Same hazard as messageOf: this is exported and callers may hand it
+  // anything, so the coercion cannot be allowed to throw (council review of
+  // PR 225).
+  let raw;
+  if (typeof text === 'string') {
+    raw = text;
+  } else if (text === null || text === undefined) {
+    raw = '';
+  } else {
+    try { raw = String(text); } catch (_e) { raw = '(unprintable error)'; }
+  }
+  if (raw.length === 0) { return ''; }
+  if (!key) { return raw; }
+  const text_ = raw;
+
+  // 1. Mask the query parameter STRUCTURALLY, before touching the key at all.
+  //    This is what actually protects the Google probe (`?key=...`) and it
+  //    works for a key of any length, including ones too short to substring-
+  //    match safely.
+  let out = text_.replace(/([?&](?:key|api_key|access_token)=)[^&\s"')]+/gi, '$1***');
+
+  // 2. Then remove the key itself — but only when it is long enough that a
+  //    substring match means something. Blind replacement of a 1-2 character
+  //    key rewrote unrelated text ("a" -> "***" across a whole DNS error),
+  //    which corrupts diagnostics without protecting anything real. Council
+  //    review of PR 222.
+  const MIN_SUBSTRING_LEN = 8;
+  if (key.length >= MIN_SUBSTRING_LEN) {
+    const spellings = new Set([key]);
+    try {
+      const encoded = encodeURIComponent(key);
+      spellings.add(encoded);
+      // application/x-www-form-urlencoded spells a space '+', not '%20'.
+      spellings.add(encoded.replace(/%20/g, '+'));
+    } catch (_e) { /* un-encodable key: the raw spelling below still runs */ }
+    for (const s of spellings) {
+      if (s) { out = out.split(s).join('***'); }
+    }
+  }
+  return out;
+}
+
+/**
+ * Validate an API key by making a test request to the provider's API.
+ *
+ * ALWAYS RESOLVES — never rejects, even on a synchronous throw from https.get
+ * (see redactSecret). Two of the three call sites have no catch.
+ *
+ * @returns {Promise<{valid: boolean, status: number|null, error?: string}>}
+ *   `status` is the HTTP status, or null when no response was received. It is
+ *   returned as DATA so callers never have to recover it by parsing `error`
+ *   (council finding 2): that coupled control flow to message wording, and a
+ *   reword that dropped the parentheses would have silently degraded detection
+ *   to a permanent "unverified" with nothing failing to announce it.
+ */
 function validateApiKey(provider, key) {
   if (!key || key.trim().length === 0) {
-    return Promise.resolve({ valid: false, error: 'API key is required' });
+    return Promise.resolve({ valid: false, status: null, error: 'API key is required' });
   }
 
   const endpoint = VALIDATION_ENDPOINTS[provider];
   if (!endpoint) {
-    return Promise.resolve({ valid: false, error: `Unknown provider: ${provider}` });
+    return Promise.resolve({ valid: false, status: null, error: `Unknown provider: ${provider}` });
   }
 
   const trimmedKey = key.trim();
@@ -53,114 +161,95 @@ function validateApiKey(provider, key) {
   const headers = endpoint.authHeader(trimmedKey);
 
   return new Promise((resolve) => {
-    const req = https.get(url, { headers }, (res) => {
-      res.on('data', () => {});
-      res.on('end', () => {
-        // Anthropic returns 401 for invalid key, 400/405 for valid key with no body
-        if (provider === 'anthropic') {
-          if (res.statusCode === 401) {
-            resolve({ valid: false, error: 'Invalid API key (401)' });
-          } else if (res.statusCode >= 500 || res.statusCode === 429) {
-            resolve({ valid: false, error: `Server error (${res.statusCode})` });
+    let req;
+    try {
+      req = https.get(url, { headers }, (res) => {
+        const code = res.statusCode;
+        // ⚠️ req.on('error') below covers the CONNECTION phase only. An error
+        // once `res` exists — a socket reset mid-body, a TLS failure after
+        // headers — is an 'error' event on this emitter, and an unhandled one
+        // is a THROW, not a rejection: the promise never settles and the
+        // process dies. Two of the three callers have no protection against
+        // that (src/cli-handlers.js has no try/catch; electron/ipc-setup.js
+        // has one, but the throw lands on a later tick outside it). Issue #224.
+        res.on('error', (err) => {
+          resolve({ valid: false, status: null, error: redactSecret(messageOf(err), trimmedKey) });
+        });
+        res.on('data', () => {});
+        res.on('end', () => {
+          // Anthropic: the probe is a GET against /v1/messages, so in practice
+          // a WORKING key answers with a method/shape complaint (400/404/405).
+          // 200 is allowed too — defensively, in case the endpoint ever answers
+          // one — which is why it appears in the allowlist below. The earlier
+          // wording said "never 200" while listing 200 as success; the comment
+          // and the code disagreed (council review of PR 222).
+          //
+          // ⚠️ This used to be `else { valid: true }` — every code that was not
+          // 401/429/5xx passed, INCLUDING 403. A region block or WAF therefore
+          // reported the key as good: a false GREEN, inside the very function
+          // rewritten to stop treating 403 as a verdict, and the exact failure
+          // class #210 exists to kill. Council review of PR 222 caught it.
+          // Success is an ALLOWLIST now; anything unlisted is not-valid.
+          if (provider === 'anthropic') {
+            if (code === 401) {
+              resolve({ valid: false, status: code, error: 'Invalid API key (401)' });
+            } else if (code === 403) {
+              resolve({ valid: false, status: code, error: FORBIDDEN_MESSAGE });
+            } else if (code >= 500 || code === 429) {
+              resolve({ valid: false, status: code, error: `Server error (${code})` });
+            } else if (code === 200 || code === 400 || code === 404 || code === 405) {
+              resolve({ valid: true, status: code });
+            } else {
+              resolve({ valid: false, status: code, error: `Unexpected response (${code})` });
+            }
+            return;
+          }
+
+          if (code === 200) {
+            resolve({ valid: true, status: code });
+          } else if (code === 401) {
+            resolve({ valid: false, status: code, error: 'Invalid API key (401)' });
+          } else if (code === 403) {
+            // NOT stated as a bad key (council finding 1). Google returns 403
+            // for "API not enabled" and for quota; a WAF returns it for bot
+            // protection. Calling that an invalid credential sends someone off
+            // to re-enter a key that works — the false-ALARM twin of the
+            // false-GREEN this endpoint exists to catch. Callers decide.
+            resolve({ valid: false, status: code, error: FORBIDDEN_MESSAGE });
           } else {
-            resolve({ valid: true });
+            resolve({ valid: false, status: code, error: `Unexpected response (${code})` });
           }
-          return;
-        }
-
-        if (res.statusCode === 200) {
-          resolve({ valid: true });
-        } else if (res.statusCode === 401 || res.statusCode === 403) {
-          resolve({ valid: false, error: `Invalid API key (${res.statusCode})` });
-        } else {
-          resolve({ valid: false, error: `Unexpected response (${res.statusCode})` });
-        }
+        });
       });
-    });
+    } catch (err) {
+      // Synchronous throw (ERR_INVALID_URL and friends). Its message quotes the
+      // request URL — key included for Google. Redact, resolve, never reject.
+      resolve({ valid: false, status: null, error: redactSecret(messageOf(err), trimmedKey) });
+      return;
+    }
     req.setTimeout(10000, () => {
       req.destroy();
-      resolve({ valid: false, error: 'Request timed out' });
+      resolve({ valid: false, status: null, error: 'Request timed out' });
     });
     req.on('error', (err) => {
-      resolve({ valid: false, error: err.message });
+      resolve({ valid: false, status: null, error: redactSecret(messageOf(err), trimmedKey) });
     });
   });
 }
 
-/** 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<{warning: string|null, isFreeTier: boolean,
- *   limitRemaining: number|null, limit: number|null, usage: number|null}>}
- */
-function checkOpenRouterCredit(key) {
-  const none = {
-    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 = '';
-      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({ warning, isFreeTier, limitRemaining, limit, usage });
-      });
-    });
-    req.setTimeout(10000, () => {
-      req.destroy();
-      resolve(none);
-    });
-    req.on('error', () => { resolve(none); });
-  });
-}
+// The OpenRouter credit probe lives in utils/openrouter-credit.js (same
+// size-gate split rationale as this file's own header). Re-exported below so
+// existing call sites are unaffected.
+const {
+  checkOpenRouterCredit, OPENROUTER_NO_CREDIT_WARNING, OPENROUTER_FREE_TIER_WARNING,
+} = require('./openrouter-credit');
 
 // Backwards compat alias
 const validateOpenRouterKey = validateApiKey;
 
 module.exports = {
   validateApiKey,
+  redactSecret,
   validateOpenRouterKey,
   checkOpenRouterCredit,
   OPENROUTER_NO_CREDIT_WARNING,

package/src/utils/config.js

@@ -340,11 +340,33 @@ const LOCAL_REQUEST_TIMEOUT_MS = 300000;
  * serve (fixed in v4.1.2). Aliases the user has overridden fall back to the
  * prefix form, since no authored gateway route describes them.
  * @param {string[]} [resolvedRoutes] executable model id(s) actually launched
+ * @param {number|null} [outputBudget] the budget to clamp with. `undefined` (every
+ *   caller but startServer) reads config here; `null` means unset. #218 PR 3:
+ *   opencode-client.js :: startServer reads config ONCE and hands the same value
+ *   to this descriptor and to the engine flag, so a config write between two
+ *   reads can no longer split the levers. Named mutant "PARAMIGNORED".
  * @returns {object} e.g. { openrouter: { models: { "x-ai/grok-4.3": {}, ... } } } */
-function buildProviderModels(resolvedRoutes = []) {
+function buildProviderModels(resolvedRoutes = [], outputBudget) {
   const aliases = getEffectiveAliases();
   const providers = {};
 
+  // #218: opt-in per-model output budget. `budget === null` (the default) makes
+  // computeModelLimit return null for every model, so each descriptor stays `{}`
+  // exactly as before. The catalog read is lazy and failure-tolerant: no cache,
+  // a corrupt one, or rows predating the maxOutputTokens field all degrade to
+  // `{}` rather than to a PARTIAL limit -- a limit missing `context` is a fatal
+  // ConfigInvalidError that poisons the whole config, not a per-model degrade.
+  const { normalizeOutputBudget, buildLimitLookup, computeModelLimit } =
+    require('./model-output-limit');
+  const budget = normalizeOutputBudget(outputBudget === undefined ? getOutputBudget() : outputBudget);
+  let limits = new Map();
+  if (budget !== null) {
+    try {
+      const cache = require('./model-catalog').readCache();
+      limits = buildLimitLookup(cache && cache.models);
+    } catch (_e) { /* no catalog -> no limits -> unchanged behaviour */ }
+  }
+
   const addRoute = (fullModel) => {
     if (!fullModel || typeof fullModel !== 'string') { return; }
     const parts = fullModel.split('/');
@@ -365,7 +387,23 @@ function buildProviderModels(resolvedRoutes = []) {
     if (!Object.prototype.hasOwnProperty.call(providers, providerID)) {
       providers[providerID] = { models: {} };
     }
-    providers[providerID].models[modelID] = {};
+    // #218 PR 2: direct `anthropic/*` is no longer held out (council #230 A1
+    // held it out until descriptor x thinking-budget was measured). Measured,
+    // probe rows K1/K2/K3/K4/K9/K10: the descriptor lowers the reservation on
+    // that route exactly as on OpenRouter (K1: 8000); a thinking variant's
+    // budget is ADDED on top of it (K2: 8000 + 16000 = 24000); and the sum is
+    // clamped to the model's real ceiling whatever the descriptor or flag said
+    // (K3/K4/K10: 64000 for haiku). No descriptor can push a thinking leg over
+    // the ceiling. #218 PR 4 now sends `--thinking` to the engine as its `variant`
+    // field, validated against the model's own declaration before any request,
+    // so these are the numbers a thinking leg now reserves: M2 is K2's
+    // arithmetic at the shipped budget (24000 + 16000 = 40000, refused rather
+    // than sent), and M17 is the fit (8000 + 16000 = 24000) that would need the
+    // variant's budget before the spawn.
+    // Named mutant "ANTHROPICHELDOUT" in tests/build-provider-models-output-limit.test.js.
+    // #218: `{}` unless a budget is set AND the catalog knows both numbers.
+    const limit = computeModelLimit(limits.get(fullModel), budget);
+    providers[providerID].models[modelID] = limit ? { limit } : {};
   };
 
   for (const [alias, fullModel] of Object.entries(aliases)) {
@@ -593,6 +631,30 @@ function resolveCouncilMembers(name, catalog = []) {
   return { models, dropped, droppedMembers };
 }
 
+/**
+ * #218: the configured per-leg output budget, or null when unset.
+ *
+ * OPT-IN BY DESIGN — unset means "register every model as `{}` and set no
+ * engine flag", which is pre-#218 behaviour exactly. Set it and every leg
+ * reserves min(budget, the model's real ceiling) wherever a ceiling is known.
+ * This one value feeds BOTH levers so they can never disagree: the per-model
+ * `limit` descriptor (buildProviderModels, for routes the amicus catalog knows)
+ * and OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX (opencode-client.js :: startServer,
+ * set to the budget for every engine amicus starts and clamped by the engine's
+ * own catalog). Values above 32000 are LIVE since PR 2 (probe K6: 100000 on the
+ * wire); a model neither catalog knows receives the budget as-is (J2/K13).
+ *
+ * ⚠️ The descriptor half needs a catalog refreshed since #218 added
+ * `maxOutputTokens` (`amicus models --refresh`); the flag half needs nothing.
+ * `amicus doctor`'s `output-budget` row says which routes get which.
+ *
+ * @returns {number|null} positive integer, or null when unset/malformed
+ */
+function getOutputBudget() {
+  const config = loadConfig() || {};
+  return require('./model-output-limit').normalizeOutputBudget(config.outputBudget);
+}
+
 /** @returns {{prefer:'direct'|'openrouter', migration_notified:Object}} routing config with defaults */
 function getRoutingConfig() {
   const config = loadConfig() || {};
@@ -716,6 +778,7 @@ module.exports = {
   classifyCouncilMembers,
   resolveCouncilMembers,
   getRoutingConfig,
+  getOutputBudget,
   resolveGatewayMode,
   markMigrationNotified,
   COST_TIERS,

package/src/utils/curated-models.js

@@ -98,14 +98,14 @@ const CARDLESS = [
   // (live smoke wave 47278069) — the entry was OpenRouter-only at authoring.
   { alias: 'fable', routes: { openrouter: 'openrouter/anthropic/claude-fable-5',
                               anthropic: 'anthropic/claude-fable-5' } },
-  // qwen/kimi refreshed 2026-08-26 (v4.9 W13): both were a model generation
-  // behind. These are the FALLBACK FLOOR — a caller or fork with no CI alias map
-  // resolves its whole bench through this table (see `inkling` below), while the
-  // owner's machine and .github/amicus-ci-aliases.json already ran the newer ids.
-  // Cardless entries have no `idPattern`, so `models --check` can only ask
-  // whether the OLD id still EXISTS — which is how a pin sits a generation back
-  // with every gate green (scripts/check-ci-alias-pins.js asks the other one).
-  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.8-max' } },
+  // qwen/kimi refreshed 2026-08-26 (v4.9 W13); qwen again 2026-09-05, when
+  // OpenRouter and models.dev dropped the un-dated `qwen3.8-max` for the dated
+  // `qwen3.8-max-0902` (the #218 PR 2 probe caught it: F4 went silent). These are
+  // the FALLBACK FLOOR — a fork with no CI alias map resolves its bench here; the
+  // owner's machine and .github/amicus-ci-aliases.json (qwen3.8-27b) run newer ids.
+  // Cardless entries have no `idPattern`, so `models --check` only asks whether the
+  // OLD id still EXISTS (scripts/check-ci-alias-pins.js asks the other question).
+  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.8-max-0902' } },
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
   { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
   { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-medium-3-5' } },

package/src/utils/degrade.js

@@ -17,6 +17,13 @@ const DEGRADE_CHANNELS = Object.freeze(new Set([
   'dropped-members', 'chair-skipped-cost-ceiling', 'chair-failed',
   'thin-cross-review', 'debate-degraded', 'inexact-under-ceiling',
   'stage1-retry',
+  // #218 PR 3: a Stage-1 review the provider cut at the max_tokens reservation
+  // (the leg's `finish` is 'length' and it still carried answer text). kind
+  // 'info' only -- the review is in the packet, nothing was lost, the exit code
+  // does not move; the chair just reads a review that ends where the
+  // reservation ended. A cut with NO answer text is a dead leg (leg.error
+  // starts `OUTPUT_LENGTH:`) and rides `dead-leg` like every other death.
+  'output-truncated',
   // v4.9 task mode: a task run writes no reliability-ledger rows — announced as kind:'info'.
   'ledger-skipped',
   // v4.8: the seat<->leg join failed. THREE shapes, one channel: a launched seat whose wave

package/src/utils/doctor-credit-check.js

@@ -0,0 +1,61 @@
+/**
+ * @module doctor-credit-check
+ * The `openrouter-credit` doctor row (#43), 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-key-auth-check.js).
+ *
+ * Warns, never errors: a zero-credit or free-tier key is a real constraint but
+ * not a broken install, and free councils against :free models are legitimate.
+ *
+ * ⚠️ "credit ok" MEANS CHECKED. checkOpenRouterCredit resolves `warning: null`
+ * for a healthy account, for a skipped probe, AND for every failure — so
+ * branching on `warning` alone reported a funded account for one nobody
+ * reached, concealing quota exhaustion behind a green row.
+ *
+ * Two flags separate the three cases, and both are required: `skipped` (we
+ * chose not to look) and `checked` (we looked and got an answer). Fixing only
+ * `skipped` left the false green alive on the network-failure path — which is
+ * exactly what the fourth council pass on PR 222 found, because the test
+ * pinning the fix ran with the gate CLOSED and could never enter the path it
+ * claimed to protect.
+ */
+
+'use strict';
+
+const ID = 'openrouter-credit';
+const NAME = 'OpenRouter credit';
+
+/**
+ * @param {{readApiKeyValues: () => Object<string,string>,
+ *          checkOpenRouterCredit: (key:string) => Promise<object>}} d
+ * @returns {Promise<{id,name,status,message,hint}>}
+ */
+async function evaluateOpenRouterCredit(d) {
+
+    const values = d.readApiKeyValues() || {};
+    const key = values.openrouter;
+    if (!key) {
+      return { id: ID, name: NAME, status: 'ok', message: 'no OpenRouter key — skipped', hint: null };
+    }
+    // Reuses the #38 non-blocking probe; resolves warning:null on any failure.
+    const res = (await d.checkOpenRouterCredit(key)) || {};
+    if (res.skipped) {
+      // Never 'ok': nothing was checked, so quota exhaustion or a free-tier cap
+      // would be concealed behind a green row (council review of PR 222).
+      return { id: ID, name: NAME, status: 'warn', message: 'credit not checked — live probes disabled', hint: 'Unset AMICUS_NO_NETWORK_PROBES, or run `amicus doctor` from the CLI.' };
+    }
+    // A probe that ran but got no answer (timeout, 5xx, socket reset, garbage
+    // body) is NOT evidence of a funded account. Distinct message from the
+    // skip above: one means "we chose not to look", this means "we looked and
+    // could not see".
+    if (res.checked !== true) {
+      return { id: ID, name: NAME, status: 'warn', message: 'credit could not be checked — the probe did not complete', hint: 'Transient: re-run `amicus doctor` when the network settles.' };
+    }
+    if (res.warning) {
+      return { id: ID, name: NAME, status: 'warn', message: res.warning, hint: 'Add credit at openrouter.ai/credits, or build a free council (amicus setup → option 2).' };
+    }
+    const remaining = (typeof res.limitRemaining === 'number') ? ` ($${res.limitRemaining} remaining)` : '';
+    return { id: ID, name: NAME, status: 'ok', message: `credit ok${remaining}`, hint: null };
+}
+
+module.exports = { evaluateOpenRouterCredit };