amicus 4.9.1 → 4.9.3

package/src/headless.js

@@ -25,6 +25,8 @@ const { envNumber } = require('./utils/env-num');
 const { engineErrorForSession } = require('./utils/engine-log');
 // v4.9 W10 (#133 piece 3): the standing engine version-skew record, if any.
 const { currentEngineSkew, formatSkewSuffix } = require('./utils/engine-skew');
+// #202: the session-status clause on a death report (see utils/session-status.js).
+const { formatSessionStatusSuffix } = require('./utils/session-status');
 // v4.9 W13 Task A (PR #207 round 3, B3): the one honesty predicate every ttftMs
 // emit gate shares — see src/utils/ttft.js for why `typeof` was not it.
 const { isMeasuredTtft } = require('./utils/ttft');
@@ -85,7 +87,18 @@ const STABLE_FINISHED_POLLS = Number(process.env.AMICUS_STABLE_FINISHED_POLLS) |
 const STABLE_IDLE_POLLS = Number(process.env.AMICUS_STABLE_IDLE_POLLS) || 30;          // ~60s at 2s — no completion signal
 const POLL_CALL_TIMEOUT_MS = Number(process.env.AMICUS_POLL_CALL_TIMEOUT_MS) || 30000; // per getMessages call (used by a later task)
 const MAX_CONSECUTIVE_POLL_FAILURES = Number(process.env.AMICUS_MAX_CONSECUTIVE_POLL_FAILURES) || 15; // ≈30s at 2s polls
-const TOOL_CALL_STALL_MS = Number(process.env.AMICUS_TOOL_CALL_STALL_MS) || 180000; // B53: wedged tool call w/ no progress
+// B53: wedged tool call w/ no progress.
+// ⚠️ 180000 -> 300000 (#219, council glm minor). 180 s was condemned by this
+// file's OWN measurement — the 190.6 s `task` call recorded below, taken on a
+// developer machine, not on CI. #202 widened only the CI override and left every
+// local and library consumer on the number the evidence had already disproved.
+// 300000 matches the sibling constant that same measurement set (USAGE/settle
+// deferral below), so one measurement now governs both windows it bears on.
+const TOOL_CALL_STALL_MS = Number(process.env.AMICUS_TOOL_CALL_STALL_MS) || 300000;
+// #202: budget for the ONE session-status read on a death report. Short on
+// purpose — this runs on a leg already known to be dying, so the report must not
+// wait on the same engine that just failed to produce anything.
+const STATUS_PROBE_MS = 5000;
 /**
  * v4.4 B1 — bounded post-loop usage reconciliation. The fold-marker (:~540) and
  * SDK-idle (:~568) fast paths break WITHOUT requiring `info.time.completed`, but
@@ -120,9 +133,11 @@ const USAGE_SETTLE_CALL_TIMEOUT_MS = envNumber('AMICUS_USAGE_SETTLE_CALL_TIMEOUT
  * unbounded wait is not an option.
  *
  * WHY 5 MINUTES. The measured duration of the real subagent call that exposed
- * this is **190.6 s** (`task`, 04:35:08.427 → 04:38:19.061) — already longer
- * than B53's 180 s TOOL_CALL_STALL_MS, so anything at that scale would kill a
- * healthy `task` leg 10 s short of its answer. 300 s clears the measured case
+ * this is **190.6 s** (`task`, 04:35:08.427 → 04:38:19.061) — which was longer
+ * than B53's THEN-180 s TOOL_CALL_STALL_MS, so anything at that scale would kill
+ * a healthy `task` leg 10 s short of its answer. (#219 finally moved B53 itself
+ * to 300 s for this exact reason; for four releases this measurement corrected
+ * the neighbour and left its own subject alone.) 300 s clears the measured case
  * with margin and still lands far inside the 15-minute default `--timeout`.
  * Set to 0 to disable the deferral entirely (pre-v4.4 behaviour).
  *
@@ -228,7 +243,7 @@ function withTimeout(promise, ms, label) {
  *          engineSkew?: {server: string, installed: string}|null}} args
  * @returns {string}
  */
-function formatNoOutputBackstopReason({ ms, fromEnv, engineLogExcerpt, engineSkew }) {
+function formatNoOutputBackstopReason({ ms, fromEnv, engineLogExcerpt, engineSkew, sessionStatus }) {
   const observed = 'NO_OUTPUT_BACKSTOP: no output, reasoning, or tool calls in '
     + `${Math.round(ms / 1000)}s — `
     + (fromEnv
@@ -237,7 +252,11 @@ function formatNoOutputBackstopReason({ ms, fromEnv, engineLogExcerpt, engineSke
   // Append-only: absent/empty excerpt ⇒ the string above, unchanged byte for byte.
   const quoted = engineLogExcerpt ? `${observed} — engine log: ${engineLogExcerpt}` : observed;
   // Append-only for the same reason: no skew ⇒ formatSkewSuffix returns ''.
-  return `${quoted}${formatSkewSuffix(engineSkew)}`;
+  // #202 adds a THIRD clause on the same terms, and LAST so both clauses above
+  // stay byte-stable: no status (or an unreadable one) ⇒ '' — see
+  // utils/session-status.js. With none of the three the string is byte-for-byte
+  // what it was before any of them existed.
+  return `${quoted}${formatSkewSuffix(engineSkew)}${formatSessionStatusSuffix(sessionStatus)}`;
 }
 
 /**
@@ -259,6 +278,45 @@ function engineErrorExcerptSafe(sessionId, engineLogOptions) {
   }
 }
 
+/**
+ * #202: read the engine's session status FOR A DEATH REPORT — best-effort and
+ * bounded, with the same "never become the failure it reports on" discipline as
+ * `engineErrorExcerptSafe` above, and one more constraint that read does not
+ * have: this one does I/O against the very engine that just failed to produce
+ * anything, so it must also be unable to HANG. Both belts are load-bearing and
+ * both are pinned (S-W4 rejects, S-W5 hangs).
+ *
+ * A failed probe returns `null`, which `formatSessionStatusSuffix` renders as
+ * '' — so a leg whose status could not be read carries the byte-for-byte reason
+ * string it carried before #202, rather than a clause claiming nothing was
+ * happening. Absence keeps its one meaning.
+ *
+ * `readStatus` is a parameter rather than a module import because
+ * `getSessionStatus` is destructured inside runHeadless from the injectable
+ * client module — taking it here keeps this helper pure and directly testable.
+ * @returns {Promise<object|null>}
+ */
+async function sessionStatusSafe(readStatus, client, sessionId, dirArgs, ms) {
+  // `!(ms > 0)` covers 0 (the documented disable), negatives and NaN — and it is
+  // why 0 is never handed to withTimeout, which would read it as UNBOUNDED.
+  if (typeof readStatus !== 'function' || !sessionId || !(ms > 0)) { return null; }
+  try {
+    return await withTimeout(
+      readStatus(client, sessionId, ...(dirArgs || [])), ms, 'getSessionStatus(death-report)');
+  } catch (err) {
+    // #219 (council, deepseek minor): returning null is right for the REPORT —
+    // absence keeps its one meaning — but it made a probe that timed out on a
+    // loaded engine indistinguishable from a leg whose engine reported nothing,
+    // i.e. a silent revert to pre-#202 behaviour. The engine log is where that
+    // belongs: the death report stays byte-identical, and the degradation
+    // becomes diagnosable instead of invisible.
+    logger.debug('session-status probe failed; the death report will carry no session clause', {
+      sessionId, error: err && err.message,
+    });
+    return null;
+  }
+}
+
 /**
  * Wait for the OpenCode server to be ready using SDK health check
  */
@@ -616,6 +674,19 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // "time since the leg asked for output" (see the block comment above), so
     // the TTFT probe below measures from exactly the instant the backstop
     // starts counting — the two can never disagree about when the wait began.
+    // #202: resolved HERE, not with the poll-loop options below. The pre-send
+    // firing site calls noOutputBackstopReason() upstream of that block, so a
+    // later `const` put this in its TDZ and the death report became
+    // "Cannot access 'statusProbeMs' before initialization" — the exact class of
+    // silent-diagnosis loss #202 exists to remove. Pinned by S-W6.
+    // ⚠️ `=== undefined`, not `||` (#219 round 2, deepseek): 0 is a meaningful
+    // value in this codebase's convention (usageSettlePolls,
+    // AMICUS_NO_OUTPUT_BACKSTOP_MS) and must survive injection. It cannot be
+    // FORWARDED as 0 though — withTimeout reads `ms <= 0` as NO timeout, so an
+    // honest-looking 0 would make this probe unbounded on a leg already known to
+    // be dying. sessionStatusSafe therefore SKIPS on a non-positive window.
+    const statusProbeMs = options.statusProbeMs === undefined
+      ? STATUS_PROBE_MS : options.statusProbeMs;
     const outputClockStartedAt = Date.now();
     const noOutputBackstop = createNoOutputBackstop({ ms: noOutputBackstopMs, startedAt: outputClockStartedAt });
     let backstopFired = false;
@@ -642,10 +713,20 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // was fixed mid-run, or one that belongs to another server this process
     // also talks to, cannot ride out on this death report. The read is a Map
     // lookup and does no I/O, so unlike the log read it needs no guard.
-    const noOutputBackstopReason = () => formatNoOutputBackstopReason({
+    //
+    // #202 (piece 4): the closure is now ASYNC, because the third clause costs
+    // one bounded HTTP call. The engine's session status is asked for at
+    // :~1045 only when `mirror.output.length > 0` — a gate a zero-output leg
+    // never satisfies — so the leg that most needs diagnosing was the only one
+    // that never asked, and every silent death reported a window with no cause.
+    // Asked for HERE instead, at the two firing sites and nowhere else, so a
+    // living leg still makes no extra call. The read is best-effort and
+    // bounded: `sessionStatusSafe` can neither throw nor hang (S-W4/S-W5).
+    const noOutputBackstopReason = async () => formatNoOutputBackstopReason({
       ms: noOutputBackstopMs, fromEnv: backstopFromEnv,
       engineLogExcerpt: engineErrorExcerptSafe(sessionId, options._engineLog),
       engineSkew: currentEngineSkew(client),
+      sessionStatus: await sessionStatusSafe(getSessionStatus, client, sessionId, dirArgs, statusProbeMs),
     });
 
     // Send prompt asynchronously (returns immediately, we poll for results) —
@@ -696,7 +777,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // skipped entirely on this path — see the while-condition and the
     // backstop-abort block further down).
     if (backstopFired) {
-      sessionError = noOutputBackstopReason();
+      sessionError = await noOutputBackstopReason();
     }
 
     // Hard provider failure detected at the client boundary (#37): a non-2xx /
@@ -1065,7 +1146,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         // loop; the post-loop block below mirrors the timeout path.
         if (noOutputBackstop.tick(substantiveActivity, Date.now()) === 'fired') {
           backstopFired = true;
-          sessionError = noOutputBackstopReason();
+          sessionError = await noOutputBackstopReason();
           logger.warn('No-output backstop fired', { taskId, backstopMs: noOutputBackstopMs });
           break;
         }

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/degrade.js

@@ -24,6 +24,14 @@ const DEGRADE_CHANNELS = Object.freeze(new Set([
   // a leg that DID match a slot but whose join key names no judge the wave launched.
   // Never a guess — silent mis-attribution is the failure seat identity exists to kill (§4.4).
   'seat-unbound',
+  // #202: a Stage-2 JUDGE leg that came back dead — bound to its seat, so
+  // neither `seat-unbound` nor an orphan, and until now it had no channel at all
+  // and no case in run-stage2.js. Deliberately its own channel rather than
+  // `dead-leg`: that one is the Stage-1 BENCH roster's, feeds the retry pass and
+  // the seat-loss surface, and a judge death reused on it would be counted as a
+  // lost reviewer by consumers that only ever meant seats (verdict-seat-loss.js
+  // already gates the Stage-2 notes out of `seat-unbound` for the same reason).
+  'stage2-judge',
   'internal',
   // doctor channels
   'doctor-check-failed', 'doctor-fix',

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