amicus 4.9.2 → 4.9.3

package/src/cli-handlers-doctor.js

@@ -17,6 +17,8 @@ const baseUrlCheck = require('./utils/doctor-base-url-check');
 // B3 (council review of PR 198, issue 195) — the 'aliases' check body,
 // including its --fix repair of fabricated bare ids. Same split rationale.
 const aliasCheck = require('./utils/doctor-alias-check');
+const creditCheck = require('./utils/doctor-credit-check');
+const keyAuthCheck = require('./utils/doctor-key-auth-check'); // #210 — 'keys' tests presence only; this re-validates.
 
 const { DEFAULT_MAX_AGE_MS: MAX_CATALOG_AGE_MS } = require('./utils/model-catalog'); // 24h — single source
 
@@ -32,7 +34,8 @@ function realDeps() {
     nodeVersion: process.version,
     readApiKeys: () => require('./utils/api-key-store').readApiKeys(),
     readApiKeyValues: () => require('./utils/api-key-store').readApiKeyValues(),
-    checkOpenRouterCredit: (key) => require('./utils/api-key-validation').checkOpenRouterCredit(key),
+    checkOpenRouterCredit: (key) => keyAuthCheck.probeOpenRouterCredit(key), // #210 — same gate as validateApiKey
+    validateApiKey: (p, k) => keyAuthCheck.probeApiKey(p, k), // #210
     getCwd: () => process.cwd(),
     readProjectMarkers: (dir) => {
       const exists = (name) => { try { return fs.existsSync(path.join(dir, name)); } catch (_e) { return false; } };
@@ -141,6 +144,7 @@ async function runDoctorChecks(depsOverride = {}) {
       : { id: 'keys', name: 'API keys', status: 'error', message: 'no provider keys configured', hint: 'amicus key <provider> <key>  (or run: amicus setup)' };
   }));
 
+  checks.push(await guardAsync('key-auth', 'API key auth', () => keyAuthCheck.evaluateKeyAuth(d))); // #210
   checks.push((() => {
     try {
       const model = d.resolveModel();
@@ -211,21 +215,10 @@ async function runDoctorChecks(depsOverride = {}) {
 
   checks.push(guard('session-metadata-tmp', 'Session metadata tmp files', () => metaSweep.evaluateSessionMetadataTmpSweep(d)));
 
-  // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no key.
-  checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit', async () => {
-    const values = d.readApiKeyValues() || {};
-    const key = values.openrouter;
-    if (!key) {
-      return { id: 'openrouter-credit', name: 'OpenRouter credit', 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.warning) {
-      return { id: 'openrouter-credit', name: 'OpenRouter credit', 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: 'openrouter-credit', name: 'OpenRouter credit', status: 'ok', message: `credit ok${remaining}`, hint: null };
-  }));
+  // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no
+  // key. Body in utils/doctor-credit-check.js (same split as the others).
+  checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit',
+    () => creditCheck.evaluateOpenRouterCredit(d)));
 
   // v4.2 §4.7 C8: configured local / OpenAI-compatible providers (Ollama, LM
   // Studio, vLLM, generic) — reachability only; warn, never error (a napping

package/src/cli-handlers.js

@@ -176,7 +176,23 @@ async function handleKey(args) {
 
   console.log(`Validating ${provider} key...`);
   const validation = await validateApiKey(provider, keyArg);
-  if (!validation.valid) {
+  // 401 is the only status that means "this credential is not accepted".
+  // Everything else — 403 (disabled API, quota, region/bot block), 429, any
+  // 5xx, a 404 from a moved endpoint, a Cloudflare 52x during an origin
+  // outage, or no status at all because the machine is offline — says
+  // something about the REQUEST, not the key. Refusing to save on those is
+  // the false ALARM the doctor classifier stopped raising.
+  //
+  // ⚠️ An ALLOWLIST of what blocks, deliberately. This was a blocklist of
+  // what does NOT block, which left every unenumerated status falling through
+  // to process.exit(1) while the comment above it claimed only 401 blocked —
+  // the code and the narrative disagreed, and the narrative was the nicer of
+  // the two. An allowlist cannot rot as new status codes appear.
+  const BLOCKS_SAVE = new Set([401]);
+  if (!validation.valid && !BLOCKS_SAVE.has(validation.status)) {
+    console.warn(`Warning: ${validation.error}`);
+    console.warn('Saving the key anyway — run `amicus doctor` to re-check it later.');
+  } else if (!validation.valid) {
     console.error(`Error: ${validation.error}`);
     process.exit(1);
   }

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

@@ -345,6 +345,23 @@ function buildProviderModels(resolvedRoutes = []) {
   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(getOutputBudget());
+  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 +382,9 @@ function buildProviderModels(resolvedRoutes = []) {
     if (!Object.prototype.hasOwnProperty.call(providers, providerID)) {
       providers[providerID] = { models: {} };
     }
-    providers[providerID].models[modelID] = {};
+    // #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 +612,28 @@ 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 `{}`", which is
+ * pre-#218 behaviour exactly. Set it and each leg reserves min(budget, the
+ * model's real ceiling) instead of opencode's fixed 32000 default.
+ *
+ * ⚠️ Values >= 32000 are ACCEPTED but INERT: opencode computes
+ * `Math.min(limit.output, 32000)` (measured in the 1.18.15 binary), so the
+ * reservation can only be lowered here, never raised. Raising it at all
+ * requires OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX, a different lever.
+ *
+ * ⚠️ Requires a catalog refreshed since #218 added `maxOutputTokens`
+ * (`amicus models --refresh`); older rows have no ceiling and stay `{}`.
+ *
+ * @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 +757,7 @@ module.exports = {
   classifyCouncilMembers,
   resolveCouncilMembers,
   getRoutingConfig,
+  getOutputBudget,
   resolveGatewayMode,
   markMigrationNotified,
   COST_TIERS,

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