amicus 4.9.3 → 4.9.4

package/src/sidecar/start.js

@@ -125,7 +125,7 @@ async function startSidecar(options) {
     mcp, mcpConfig, clientType: client, noMcp, excludeMcp, projectDir: effectiveProject
   });
   const taskId = options.taskId || generateTaskId();
-  const reasoning = thinking ? { effort: thinking } : undefined;
+  const variant = thinking || undefined; // #218 PR 4: the level itself is the engine's `variant` field (named mutant "STARTVARIANTDROPPED", tests/sidecar/start.test.js: drop `variant` from the two options objects below)
   // 15b.3: one nonce per run, generated BEFORE prompt construction so the
   // SAME value can be baked into the prompt's instruction (buildPrompts) and
   // handed to the detector (runHeadless.options.nonce / the GUI fold writer
@@ -158,7 +158,7 @@ async function startSidecar(options) {
         result = await runHeadless(
           model, systemPrompt, userMessage, taskId, effectiveProject,
           timeout * 60 * 1000, agent || 'build',
-          { mcp: mcpServers, summaryLength, reasoning, port: opencodePort, nonce: foldNonce }
+          { mcp: mcpServers, summaryLength, variant, port: opencodePort, nonce: foldNonce }
         );
       } catch (err) {
         if (!json) { throw err; }
@@ -174,7 +174,7 @@ async function startSidecar(options) {
       logger.info('Launching interactive sidecar', { taskId, model, agent: effectiveAgent });
       result = await runInteractive(
         model, systemPrompt, userMessage, taskId, effectiveProject,
-        { agent, mcp: mcpServers, reasoning, client, windowPosition: position, foldNonce }
+        { agent, mcp: mcpServers, variant, client, windowPosition: position, foldNonce }
       );
       summary = result.summary || '';
       if (result.error) { logger.error('Interactive task error', { taskId, error: result.error }); }
@@ -200,12 +200,15 @@ async function startSidecar(options) {
   if (terminal.status === 'error') {
     meta.status = 'error';
     meta.reason = (result && result.error) ? String(result.error) : 'Incomplete';
+    if (result && typeof result.finish === 'string') { meta.finish = result.finish; } // #218 PR 3: emit-when-set; a fresh session's metadata has no prior finish to remove (resume's does -- resume.js)
+    if (result && typeof result.variant === 'string') { meta.variant = result.variant; } // #218 PR 4: emit-when-set, like finish (named mutant "SOLOERRORNOVARIANT", tests/start-terminal-status.test.js)
+    if (result && result.variantUnverified === true) { meta.variantUnverified = true; }
     meta.completedAt = new Date().toISOString();
     writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
     logger.error('Session completed with error', { taskId, error: meta.reason });
   } else {
     // complete / timed-out / aborted: persist the (possibly partial) summary with the correct status.
-    finalizeSession(sessDir, summary, effectiveProject, meta, { quietStdout: json, status: terminal.status });
+    finalizeSession(sessDir, summary, effectiveProject, meta, { quietStdout: json, status: terminal.status, finish: result && result.finish, variant: result && result.variant, variantUnverified: result && result.variantUnverified });
   }
 
   const { resolveUsage } = require('../utils/pricing');
@@ -223,6 +226,8 @@ async function startSidecar(options) {
       appendSpend({
         taskId, model, mode: effectiveHeadless ? 'headless' : 'interactive', usage: runUsage,
         op: 'start', status: statusFromResult(result), project: effectiveProject,
+        finish: result && result.finish, // #218 PR 3: appendSpend keeps it only when it is a string
+        variant: result && result.variant, // #218 PR 4: same emit-when-set rule (named mutant "SOLOROWNOVARIANT", tests/start-json.test.js)
         // ⚠️ DE-ROT: `metadata` is NOT in scope at startSidecar's finalize site — the objects
         // there are `meta` (createSessionMetadata result) and `m`; `metadata` is a local only
         // inside createSessionMetadata. Reading `metadata.gateway` throws a ReferenceError the
@@ -232,7 +237,7 @@ async function startSidecar(options) {
         // (To also attribute v4.2 'local': thread the resolved route gateway — dropped today at
         // cli-handlers-run.js:47 — into createSessionMetadata and read `meta.gateway`, as continue.js:111 does.)
         // v4.7 F8 D16: same in-scope-value rule as gateway above — `m` is the
-        // just-re-read metadata (line 214), which carries `tag` when
+        // just-re-read metadata (line 215), which carries `tag` when
         // createSessionMetadata stored one (absent otherwise); `|| null` folds
         // that into spend-ledger.js's null-not-absent dim convention.
         tag: m.tag || null,

package/src/utils/config.js

@@ -340,8 +340,13 @@ 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 = {};
 
@@ -353,7 +358,7 @@ function buildProviderModels(resolvedRoutes = []) {
   // ConfigInvalidError that poisons the whole config, not a per-model degrade.
   const { normalizeOutputBudget, buildLimitLookup, computeModelLimit } =
     require('./model-output-limit');
-  const budget = normalizeOutputBudget(getOutputBudget());
+  const budget = normalizeOutputBudget(outputBudget === undefined ? getOutputBudget() : outputBudget);
   let limits = new Map();
   if (budget !== null) {
     try {
@@ -382,6 +387,20 @@ function buildProviderModels(resolvedRoutes = []) {
     if (!Object.prototype.hasOwnProperty.call(providers, providerID)) {
       providers[providerID] = { models: {} };
     }
+    // #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 } : {};
@@ -615,17 +634,19 @@ function resolveCouncilMembers(name, catalog = []) {
 /**
  * #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.
+ * 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).
  *
- * ⚠️ 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 `{}`.
+ * ⚠️ 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
  */

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