amicus 4.9.2 → 4.9.4

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/doctor-output-budget-check.js

@@ -0,0 +1,198 @@
+/**
+ * @module doctor-output-budget-check
+ * #218 PR 2: the 'output-budget' doctor row.
+ *
+ * VERIFIABLE voice (same rule as doctor-base-url-check.js): the row states only
+ * what it read — the configured `outputBudget` as stored, the ambient
+ * OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX this process sees, and which alias
+ * routes the cached catalog can clamp. It never claims what a provider will do.
+ *
+ * What earns a WARN, and why (probe rows in brackets, BACKLOG "v4.9.4 records"):
+ *   - a malformed budget or a malformed ambient flag: the engine falls back to
+ *     32000 SILENTLY (D1/D2) — the one failure the product principle forbids;
+ *     only a plain decimal integer (digits, no leading zero) is measured to be
+ *     honoured, so any other form is reported as unmeasured, never healthy;
+ *   - a value above the engine default with alias routes the catalog cannot
+ *     clamp: the engine clamps routes its own catalog knows (K5), but a model
+ *     neither catalog knows receives the value as-is (J2/K13);
+ *   - a reservation of at least half a route's context window: input plus
+ *     max_tokens has to fit the window, and the engine subtracts the same
+ *     reservation from the window before compaction (read in the binary), so
+ *     such a value starves the prompt;
+ *   - nothing for a direct openai route: it carries no reservation field at
+ *     all (M5/M13/M22), so it is listed apart from the clamped/unclamped counts.
+ * A configured budget and a valid ambient flag get the SAME analysis: they
+ * govern the same spawns (council #231 r2 D2). So does a valid ambient flag
+ * beside a malformed budget (r4 B1).
+ */
+'use strict';
+
+const { normalizeOutputBudget, buildLimitLookup, computeModelLimit, positiveCount } = require('./model-output-limit');
+const {
+  OUTPUT_TOKEN_FLAG, ENGINE_DEFAULT_OUTPUT_TOKENS, outputTokenFlagValue, PLAIN_OUTPUT_TOKEN_FLAG,
+} = require('./engine-output-flag');
+
+const ID = 'output-budget';
+const NAME = 'Output budget';
+const row = (status, message, hint = null) => ({ id: ID, name: NAME, status, message, hint });
+
+/** Up to three names, then "+N more". @param {string[]} names @returns {string} */
+function shortList(names) {
+  const head = names.slice(0, 3).join(', ');
+  return names.length > 3 ? `${head}, +${names.length - 3} more` : head;
+}
+
+/**
+ * What a per-leg value reaches, by the cached catalog's numbers: which alias
+ * routes have a ceiling to clamp against, which do not, and which would give
+ * at least half their context window to the reservation. `value` is the
+ * configured budget or — with none configured — the ambient flag: the engine
+ * spawn is governed the same way either way (K5/K12: min(value, the ceiling
+ * the engine knows); J2/K13: the value as-is on a model neither catalog knows),
+ * so both get the same analysis (council #231 r2 D2).
+ * @param {object} d doctor deps
+ * @param {?object} cache readCache() result
+ * @param {number} value positive integer
+ * @param {string} lowerHint the hint that names the knob to lower
+ * @returns {{clauses:string, status:'ok'|'warn', hint:?string}}
+ */
+function analyseRoutes(d, cache, value, lowerHint) {
+  const shown = outputTokenFlagValue(value);
+  const aboveDefault = value > ENGINE_DEFAULT_OUTPUT_TOKENS;
+  if (!cache || !Array.isArray(cache.models)) {
+    // At or below the engine default the flag alone never raises what goes
+    // out (K12), so a missing cache is informational; above it an unknown model
+    // receives the value as-is (J2/K13) and the cache is what would name a
+    // ceiling. Named mutant "NOCACHEALWAYSWARN": make this branch warn regardless.
+    // Named mutant "NOCACHEOPENAI" (tests/doctor-output-budget.test.js): drop the openai clause.
+    return {
+      clauses: `; no catalog cache, so no route has a known ceiling here (the engine clamps routes its own catalog knows; an unknown model receives ${shown} as-is; an openai/ id carries no output reservation on a leg that resolves DIRECT — the Responses API request has no output-limit field, probe M5/M13/M22 — while the openrouter/openai/… form of the same model does, M1/M9; which gateway a leg takes is a launch-time decision this row cannot read)`,
+      status: aboveDefault ? 'warn' : 'ok',
+      hint: aboveDefault ? 'amicus models --refresh — with no cache nothing can be checked; a model neither catalog knows receives the value unclamped, so lower it if any route is one' : null,
+    };
+  }
+  const limits = buildLimitLookup(cache.models);
+  const routes = [...new Set(d.collectAliasSources()
+    .map((s) => s && s.model)
+    .filter((m) => typeof m === 'string' && m.length > 0))];
+  // #218 PR 4 (probe M5/M13/M22): the engine drives the direct `openai` provider
+  // through the Responses API, whose request body carries NO output-limit field
+  // — with a bare descriptor, with limit.output 8000 and the flag at 8000, for
+  // gpt-5.6-terra and gpt-4o alike. Neither lever reaches that route, so it is
+  // reported apart, never as clamped. Named mutant "OPENAIGOVERNED".
+  // council #235 r4 (C6): the id prefix partitions the LIST — it does not predict the ROUTE. This
+  // row cannot see a future invocation's `--gateway`, `routing.prefer` or which keys are present,
+  // and the `openrouter/openai/…` form of the same model DOES carry the reservation (M1/M9), so the
+  // clause states the outcome of a leg that resolves DIRECT and says the choice is made at launch.
+  // Named mutant "OPENAIOUTCOMEASSERTED": restore the unconditional "carries no output reservation
+  // at all … so the value does not apply there" in both clauses below.
+  const ungoverned = routes.filter((id) => id.startsWith('openai/'));
+  const governed = routes.filter((id) => !id.startsWith('openai/'));
+  const unclamped = [];
+  const starved = [];
+  for (const id of governed) {
+    const limit = computeModelLimit(limits.get(id), value);
+    if (!limit) { unclamped.push(id); continue; }
+    if (limit.output * 2 >= limit.context) { starved.push(`${id} (${limit.output} of ${limit.context})`); }
+  }
+  let clauses = `; ${governed.length - unclamped.length} of ${governed.length} alias routes have a known catalog ceiling`;
+  let status = 'ok';
+  let hint = null;
+  if (unclamped.length > 0) {
+    clauses += `; ${unclamped.length} without one (${shortList(unclamped)}) — the engine clamps those its own catalog knows, an unknown model receives ${shown} as-is`;
+    // At or below the default the flag never raises what the engine sends
+    // (K12); above it an unknown model is the one place the number goes out
+    // unclamped (J2/K13), so that is the only case worth a warning.
+    // Named mutant "NODEFAULTGATE": drop this condition.
+    if (aboveDefault) {
+      status = 'warn';
+      hint = 'lower the value if one of those routes is a model neither catalog knows (it receives it unclamped); amicus models --refresh if the catalog is just stale';
+    }
+  }
+  if (starved.length > 0) {
+    clauses += `; reserves at least half the context window of ${shortList(starved)}`;
+    status = 'warn';
+    // Starvation leads: a catalog refresh cannot fix it, lowering the value can.
+    hint = lowerHint + (hint ? `; ${hint}` : '');
+  }
+  if (ungoverned.length > 0) {
+    const plural = ungoverned.length === 1 ? '' : 's';
+    const carry = ungoverned.length === 1 ? 'carries' : 'carry';
+    clauses += `; ${ungoverned.length} openai/ alias route${plural} (${shortList(ungoverned)}) ${carry} no output reservation on a leg that resolves DIRECT to that provider — the engine drives it through the Responses API, whose request has no output-limit field (probe M5/M13/M22); which gateway a leg takes is a launch-time decision this row cannot read (--gateway, routing.prefer, key presence), and the openrouter/openai/… form of the same model DOES carry the reservation (M1/M9)`;
+  }
+  return { clauses, status, hint };
+}
+
+/**
+ * @param {{readOutputBudgetRaw:Function, readCache:Function, collectAliasSources:Function,
+ *   getConfigDir?:Function, env?:NodeJS.ProcessEnv}} d
+ * @returns {{id:string,name:string,status:string,message:string,hint:?string}}
+ */
+function evaluateOutputBudget(d) {
+  const env = d.env || process.env;
+  const ambient = env[OUTPUT_TOKEN_FLAG];
+  const raw = d.readOutputBudgetRaw();
+  // Not "32000 per leg": under the default a leg reserves min(32000, the
+  // ceiling the engine's catalog knows for it) — probe B sent 4096 for a
+  // 4096-ceiling row with no flag at all.
+  const dflt = `the engine default applies (OUTPUT_TOKEN_MAX ${ENGINE_DEFAULT_OUTPUT_TOKENS}: each leg reserves min(${ENGINE_DEFAULT_OUTPUT_TOKENS}, the ceiling the engine's catalog knows for it))`;
+
+  // Only PLAIN_OUTPUT_TOKEN_FLAG (engine-output-flag.js) is measured to be honoured:
+  // it is the shape amicus itself writes (engine-output-flag.js ::
+  // outputTokenFlagValue) and the shape the probe ran (C1, K5, K12). `64000abc` and
+  // `0` fall back to 32000 silently (D1/D2); ' 64000 ', '064000', '1e5', '0x10' and
+  // '64000.7' have never been probed, so they are reported as unmeasured rather than
+  // as healthy (council #231 r1 finding 3, r2 D5).
+  const ambientOk = (ambient !== undefined && PLAIN_OUTPUT_TOKEN_FLAG.test(ambient)) ? positiveCount(Number(ambient)) : null;
+  const ambientBad = ambient !== undefined && ambientOk === null;
+  const ambientBadText = `${OUTPUT_TOKEN_FLAG}=${ambient} in this environment is not a plain positive integer — the only form measured to be honoured (probe D1/D2: 64000abc and 0 fell back to ${ENGINE_DEFAULT_OUTPUT_TOKENS} silently); any other form is unmeasured`;
+  const ambientHint = `unset ${OUTPUT_TOKEN_FLAG}, or set it to a plain positive integer`;
+
+  if (raw === undefined) {
+    if (ambient === undefined) { return row('ok', `not set — ${dflt}`); }
+    if (ambientBad) { return row('warn', `not set — ${ambientBadText}`, ambientHint); }
+    // A valid ambient value governs every engine amicus starts exactly as a
+    // budget would, so it gets the same route analysis (council #231 r2 D2).
+    const shown = outputTokenFlagValue(ambientOk);
+    const lead = `not set — ${OUTPUT_TOKEN_FLAG}=${ambient} in this environment sets the engine's OUTPUT_TOKEN_MAX to ${shown} (its default is ${ENGINE_DEFAULT_OUTPUT_TOKENS}): each leg reserves min(${shown}, the ceiling the engine's catalog knows for it), and ${shown} as-is on a model it does not know`;
+    const a = analyseRoutes(d, d.readCache(), ambientOk, `lower ${OUTPUT_TOKEN_FLAG} — input plus the reservation must fit the context window`);
+    return row(a.status, lead + a.clauses, a.hint);
+  }
+
+  const budget = normalizeOutputBudget(raw);
+  if (budget === null) {
+    // A malformed budget sets no flag (engine-output-flag.js), so whatever is
+    // ambient governs the spawn — the row has to say which value that leaves,
+    // and a VALID ambient value gets the same route analysis a budget would
+    // (council #231 r4 B1). Named mutant "MALFORMEDNOANALYSIS": drop the
+    // analyseRoutes call below.
+    // `getConfigDir` is always in the doctor deps; the fallback keeps a hand-built
+    // deps object from printing "undefined/config.json" (council #231 r2 C2).
+    const cfgDir = typeof d.getConfigDir === 'function' ? d.getConfigDir() : '~/.config/amicus';
+    const fixHint = `set outputBudget to a positive integer in ${cfgDir}/config.json, or remove it`;
+    const lead = `${JSON.stringify(raw)} is not a positive integer — ignored; `;
+    if (ambient === undefined) { return row('warn', lead + dflt, fixHint); }
+    if (ambientBad) { return row('warn', `${lead}${dflt} (${ambientBadText})`, fixHint); }
+    const shownA = outputTokenFlagValue(ambientOk);
+    const a = analyseRoutes(d, d.readCache(), ambientOk, `lower ${OUTPUT_TOKEN_FLAG} — input plus the reservation must fit the context window`);
+    return row('warn',
+      `${lead}${OUTPUT_TOKEN_FLAG}=${ambient} in this environment governs engines amicus starts (OUTPUT_TOKEN_MAX ${shownA}: each leg reserves min(${shownA}, the ceiling the engine's catalog knows for it))${a.clauses}`,
+      fixHint + (a.hint ? `; ${a.hint}` : ''));
+  }
+  // A malformed ambient value never reaches an engine amicus starts — the
+  // budget overrides it — so the row stays ok, but it says the value is
+  // malformed rather than only "overridden" (council #231 r4 D1).
+  const overridden = ambient === undefined ? ''
+    : (ambientBad
+      ? `; ${OUTPUT_TOKEN_FLAG}=${ambient} in this environment is not a plain positive integer and is overridden by outputBudget for engines amicus starts (an engine started outside amicus would read it and fall back to ${ENGINE_DEFAULT_OUTPUT_TOKENS} silently)`
+      : `; ${OUTPUT_TOKEN_FLAG}=${ambient} in this environment is overridden by outputBudget for engines amicus starts`);
+  // normalizeOutputBudget floors a fractional number; say so rather than report
+  // a value the user never typed as if they had (council #231 B2).
+  const floored = (typeof raw === 'number' && raw !== budget) ? ` (floored from ${raw})` : '';
+  const shown = outputTokenFlagValue(budget); // plain digits even above 1e21, the same form the flag carries
+  const lead = `budget ${shown}${floored} — each leg reserves min(${shown}, its ceiling where one is known)`;
+  const a = analyseRoutes(d, d.readCache(), budget, 'lower outputBudget — input plus the reservation must fit the context window');
+  return row(a.status, lead + a.clauses + overridden, a.hint);
+}
+
+module.exports = { evaluateOutputBudget };

package/src/utils/engine-output-flag.js

@@ -0,0 +1,105 @@
+/**
+ * @module engine-output-flag
+ * #218 PR 2 — the one engine env flag amicus sets: OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX.
+ *
+ * WHY A FLAG AT ALL. The per-model `limit` descriptor (model-output-limit.js)
+ * can only LOWER a leg's max_tokens reservation: the pinned engine computes
+ * `Math.min(limit.output, OUTPUT_TOKEN_MAX)` and OUTPUT_TOKEN_MAX defaults to
+ * 32000. Raising it is this flag's job. The engine reads the flag from the env
+ * it is SPAWNED with, as a positive integer; `64000abc` and `0` fall back to
+ * 32000 with no error anywhere (probe rows D1/D2), and a negative value is
+ * rejected by the same positive-integer check, read in the pinned binary
+ * (`Number.isInteger(w) && w > 0`), not wire-measured.
+ *
+ * THE ONE RULE: when `outputBudget` is configured, the flag is set TO THE BUDGET
+ * for every engine amicus starts — around the synchronous spawn only, restored
+ * before anything is awaited. Measured on the wire by scripts/probe-max-tokens.js
+ * (BACKLOG "v4.9.4 records", the PR 2 record):
+ *   - a route the amicus catalog can clamp gets min(budget, ceiling) through the
+ *     descriptor, and the flag never exceeds it (C2, K6);
+ *   - a bare `{}` route the ENGINE knows gets min(engine ceiling, budget)
+ *     (C3, K5, K12) — the flag reaches rows the amicus catalog cannot name;
+ *   - a route neither knows gets the budget as-is (J2, K13), exactly as it got
+ *     the raw 32000 before;
+ *   - an ambient value the user exported themselves is honoured untouched when no
+ *     budget is configured, and overridden for the spawn (then restored) when one is.
+ *
+ * WHY AROUND THE SYNCHRONOUS CALL. The pinned @opencode-ai/sdk spreads
+ * process.env into the child's env inside createOpencodeServer BEFORE its first
+ * await (node_modules/@opencode-ai/sdk/dist/server.js), so the flag has to be in
+ * process.env at call time and may be gone by the time the promise settles.
+ * Restoring in `finally` keeps it out of every OTHER child amicus spawns
+ * (Electron, the MCP child, on-complete hooks) and out of the caller's own env.
+ * The unit pin is tests/opencode-client-output-flag.test.js; the SDK-side pin is
+ * tests/opencode-client-sdk-spawn-timing.test.js (the real SDK against a fake engine
+ * on PATH); the engine-side canary is the probe's K6/K12/K13 rows, which CI's
+ * keyless job runs on every push (tests/probe-flag-canary.integration.test.js).
+ */
+'use strict';
+
+const { positiveCount } = require('./model-output-limit');
+
+const OUTPUT_TOKEN_FLAG = 'OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX';
+/** The engine's own default when the flag is absent or malformed (probe rows A, D1, D2). */
+const ENGINE_DEFAULT_OUTPUT_TOKENS = 32000;
+
+/**
+ * The ONE form of OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX measured to be honoured:
+ * a plain decimal integer with no leading zero -- the shape amicus writes
+ * (outputTokenFlagValue) and the shape the probe ran (C1, K5, K12). `64000abc`
+ * and `0` fell back to 32000 silently (D1/D2); ' 64000 ', '064000', '1e5',
+ * '0x10' and '64000.7' have never been probed. Shared by the doctor row
+ * (doctor-output-budget-check.js :: evaluateOutputBudget) and the death report
+ * (output-length.js :: formatOutputLengthReason) so the two gates cannot drift.
+ */
+const PLAIN_OUTPUT_TOKEN_FLAG = /^[1-9]\d*$/;
+
+/**
+ * The flag value a budget produces, or null when no flag should be set.
+ * Exactly normalizeOutputBudget's acceptance rule (a positive finite integer,
+ * floored), rendered as plain decimal digits even above 1e21; everything else
+ * is "no flag".
+ * @param {*} budget raw or normalized outputBudget
+ * @returns {string|null}
+ */
+function outputTokenFlagValue(budget) {
+  const n = positiveCount(budget);
+  if (n === null) { return null; }
+  // String(1e21) is '1e+21', which the engine would read as malformed (D1) and
+  // the doctor row would report as unmeasured. BigInt renders every
+  // integer-valued double as plain digits, so the flag always has the one shape
+  // measured to be honoured and a configured budget is never silently dropped
+  // (council #231 B1/C2).
+  return n >= 1e21 ? BigInt(n).toString() : String(n);
+}
+
+/**
+ * Run `fn` with the flag set to `budget` in `env`, restoring the previous state
+ * (absent, or the ambient value) before returning — whether `fn` returned a
+ * value, returned a promise, or threw. With no usable budget `fn` runs untouched.
+ *
+ * `delete`, not `= undefined`: assigning undefined to a process.env key stores
+ * the string 'undefined', which the engine would read as a malformed flag.
+ * @template T
+ * @param {*} budget outputBudget (positive integer, else no-op)
+ * @param {() => T} fn called synchronously, exactly once
+ * @param {NodeJS.ProcessEnv} [env] defaults to process.env — the env the SDK spreads
+ * @returns {T} whatever fn returned (a promise is returned, never awaited here)
+ */
+function withOutputTokenFlag(budget, fn, env = process.env) {
+  const value = outputTokenFlagValue(budget);
+  if (value === null) { return fn(); }
+  const had = Object.prototype.hasOwnProperty.call(env, OUTPUT_TOKEN_FLAG);
+  const saved = env[OUTPUT_TOKEN_FLAG];
+  env[OUTPUT_TOKEN_FLAG] = value;
+  try {
+    return fn();
+  } finally {
+    if (had) { env[OUTPUT_TOKEN_FLAG] = saved; } else { delete env[OUTPUT_TOKEN_FLAG]; }
+  }
+}
+
+module.exports = {
+  withOutputTokenFlag, outputTokenFlagValue, OUTPUT_TOKEN_FLAG, ENGINE_DEFAULT_OUTPUT_TOKENS,
+  PLAIN_OUTPUT_TOKEN_FLAG,
+};