amicus 4.9.3 → 4.9.5

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

package/src/utils/engine-variants.js

@@ -0,0 +1,298 @@
+/**
+ * @module engine-variants
+ * The effort lever (#218 PR 4): --thinking sent as the engine's variant field, validated against the engine's own declaration.
+ * The engine's prompt endpoint selects reasoning
+ * effort through `variant: string` (probe F2); the `reasoning` object amicus sent
+ * for every `--thinking` until now was never a prompt field and reached nothing
+ * (F1). A variant the model does not DECLARE is a silent no-op that the engine
+ * still echoes on the assistant message (F3 on a known model, M7 on one with
+ * `variants {}`), so a run's own artifact can claim an effort the wire never
+ * saw. This module is the one place amicus asks the engine what a model declares
+ * (`/config/providers` -> `variants` + `limit`, M0) and decides, per leg, to send,
+ * refuse, or send unverified.
+ *
+ * Measured, engine 1.18.15 (BACKLOG "v4.9.4 records", the PR 4 table):
+ *   - a model newer than the engine's bundled catalogue reads `limit 0/0,
+ *     variants {}` until the startup models.dev refresh lands (M0: qwen3.8-max-0902,
+ *     glm-5.3 on a cold engine) and is known on the first poll of a WARM engine (M12: 36 ms on one run) —
+ *     so a read that finds the model unknown WAITS, bounded, before deciding;
+ *   - a variant does not move the reservation on OpenRouter (M1, M9), direct
+ *     Google (M15), direct DeepSeek (M16) or an adaptive-thinking Anthropic model
+ *     (M10b); only an entry shaped `thinking: {type: 'enabled', budgetTokens: N}`
+ *     adds N ON TOP of the reservation (M2: 24000 + 16000 = 40000; K2/K11),
+ *     clamped to the model's ceiling (K3/K4/K10);
+ *   - N is the engine's, not a formula of the ceiling (M0: opus-4-5 declares
+ *     16000 for low, medium AND high, and no max), so the post-spawn dump is the
+ *     only source of N — and nothing changes a descriptor after the spawn: a
+ *     runtime PATCH /config changes nothing the engine serves and writes a
+ *     config.json into its cwd (M3/M4/M11). The exact pre-spawn fit (descriptor
+ *     = budget − N, proven M17) is filed, not built; this module REFUSES the
+ *     over-budget shape with the numbers instead (BACKLOG C1's second clause).
+ *   - /config/providers echoes a descriptor amicus wrote (M3: a 24000 limit.output reads back as 24000), so the ceiling a fit judges against comes from amicus's own catalog when it knows the model and from the dump only for a bare descriptor. The echo overwrites `limit` and NOTHING else (M23), so it never hides whose row it is: the name, family, release date, prices, capabilities and variants beside it are filled by the engine's MERGED view of its own catalogue and the user's opencode config (council #235 r4, C3 — a config `reasoning: true` even synthesizes a variants map), and `engineSourced` below reads those.
+ */
+'use strict';
+
+const { positiveCount } = require('./model-output-limit');
+
+/** Every level the curated routes declare between them (M0), in effort order. */
+const VARIANT_LEVELS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+/** How long a read waits for the engine's startup refresh to make a model known (the cold wait is unmeasured — BACKLOG item 3; M12's 36 ms was a warm read). */
+const DECLARATION_WAIT_MS = 5000;
+const DECLARATION_POLL_MS = 500; // council #235 r1 (D2): ten reads across the bound, not twenty
+const DECLARATION_READ_TIMEOUT_MS = 2000; // council #235 r2 (A1): ONE read's own bound. A warm read measured 36-285 ms (M12), so 2 s is generous; without it a stalled endpoint runs to undici's ~306 s default and the 5 s "bound" below caps only the NUMBER of reads.
+
+/**
+ * Defang engine-sourced text before it enters a message. `/config/providers` is
+ * filled from the engine's remote models.dev refresh, so variant names are not
+ * ours; control characters and fence/tag characters are stripped so a poisoned
+ * catalogue cannot forge terminal escapes or markdown structure in a reason
+ * string. Mirrors sidecar/progress-fields.js :: sanitizePreview, which does the
+ * same job for briefings crossing the MCP boundary. Named mutant "RAWENGINETEXT".
+ * @param {string} s @returns {string}
+ */
+// eslint-disable-next-line no-control-regex
+const defang = (s) => String(s).replace(/[\u0000-\u001F\u007F]/g, '').replace(/[`<>]/g, '').replace(/\s+/g, ' ').trim();
+
+/** Thrown by opencode-client.js :: sendPrompt BEFORE any request when a variant is refused. */
+class VariantRefusedError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'VariantRefusedError';
+    this.code = code;
+  }
+}
+
+/** A non-empty string cell. */
+const filled = (v) => typeof v === 'string' && v.trim() !== '';
+
+/**
+ * Whose row is this — the engine's own catalogue, or nothing but the descriptor amicus registered? Amicus writes exactly ONE cell into a model's entry (`limit`, src/utils/config.js:406) and /config/providers echoes it (M3), so `limit` can never answer that; everything else can. Measured with the IDENTICAL descriptor on both rows (record M23, engine 1.18.15): an engine row keeps its display name, family, release date, prices, capabilities and variants, a config-only row reads `name === modelID`, empty family/release_date, cost 0, `variants {}`.
+ * THE DISJUNCTS ARE EXACTLY THESE EIGHT: `id`, `providerID`, `api`, `status`, `options`, `headers`, `capabilities.toolcall` and `capabilities.input/output.text` are populated on a config-only row TOO (M23), so adding any of them reads every model the engine has not learned yet as a declaration and refuses it falsely — named mutants "TOOLCALLDISJUNCT" and "ECHOSOURCED" (add `limit`); "ONEDISJUNCT" shrinks the OR. Cost is compared `> 0`, never through positiveCount, which FLOORS $0.05 to 0 — mutant "COSTVIAPOSITIVECOUNT".
+ * @param {string} modelID model half of the executable id
+ * @param {object|null} m the dump's entry for it
+ * @returns {boolean}
+ */
+function engineSourced(modelID, m) {
+  if (!m || typeof m !== 'object') { return false; }
+  const cost = (m.cost && typeof m.cost === 'object') ? m.cost : {};
+  const caps = (m.capabilities && typeof m.capabilities === 'object') ? m.capabilities : {};
+  const variants = (m.variants && typeof m.variants === 'object') ? m.variants : {};
+  return filled(m.release_date)
+    || filled(m.family)
+    || (filled(m.name) && m.name !== modelID)
+    || (typeof cost.input === 'number' && cost.input > 0)
+    || (typeof cost.output === 'number' && cost.output > 0)
+    || Object.keys(variants).length > 0
+    || caps.temperature === true || caps.reasoning === true || caps.attachment === true;
+}
+
+/**
+ * One read of `/config/providers` for one model. `known` is "the engine's own
+ * catalogue supplied this row" (engineSourced above, record M23) — NOT
+ * `limit.context > 0`, which reads the one cell amicus itself writes and the
+ * dump echoes back (M3). A model amicus registered that the engine's catalogue
+ * lacks carries nothing but that descriptor (J1, M0); a provider or model
+ * missing from the dump altogether is unknown too. Named mutant "LIMITISKNOWN".
+ * `limitOutput` is whatever the dump says — the engine's own ceiling for a bare descriptor, and the ECHO of a descriptor amicus wrote otherwise (M3).
+ * @param {object} client SDK client
+ * @param {string} providerID provider half of the executable id
+ * @param {string} modelID model half of the executable id
+ * @param {{signal?: object, readTimeoutMs?: number}} [opts] `signal` — the caller's abandon signal, joined to this read's own deadline when it is a real AbortSignal; `readTimeoutMs` — that deadline (default DECLARATION_READ_TIMEOUT_MS).
+ * @returns {Promise<{known: boolean, variants: object, limitOutput: number|null, unreadable: string|null}>}
+ */
+async function readDeclarationOnce(client, providerID, modelID, opts = {}) {
+  const readTimeoutMs = positiveCount(opts.readTimeoutMs) || DECLARATION_READ_TIMEOUT_MS;
+  // council #235 r2 (A1): the read gets its OWN deadline, and the caller's abandon
+  // signal is joined to it so an abort cancels the read in flight rather than only
+  // ending the loop. Named mutant "UNBOUNDEDREAD" (tests/utils/engine-variants.test.js):
+  // drop the signal from the call and the read runs to the transport's own default
+  // (the SDK deletes its own — node_modules/@opencode-ai/sdk/dist/client.js sets
+  // `req.timeout = false` — leaving undici's ~306 s; the triage measured one read at
+  // 306,639 ms against a socket that accepts and never answers).
+  const timeoutSignal = AbortSignal.timeout(readTimeoutMs);
+  // AbortSignal.any REJECTS a duck-typed `{aborted}` (TypeError: not of type AbortSignal),
+  // and both the documented `options.signal` type and the tests use that shape; only the
+  // real AbortController signal headless passes can be joined. The loop's own `signal.aborted`
+  // check still ends the wait for the duck-typed case — it just cannot cancel a read already
+  // in flight, which is exactly what the timeout above now bounds.
+  const joinable = opts.signal && typeof AbortSignal !== 'undefined' && opts.signal instanceof AbortSignal;
+  const readSignal = joinable ? AbortSignal.any([opts.signal, timeoutSignal]) : timeoutSignal;
+  let r;
+  try { r = await client.config.providers({ signal: readSignal }); } catch (err) {
+    // council #235 r1 (C1/D1/A2): a THROWN read — a transport error, a dead engine — is
+    // unreadable exactly like the returned non-2xx tuple below: one read, no wait, the level
+    // sent unverified with the note naming the error. Before this the rejection escaped
+    // sendPrompt and the leg died on it. Named mutant "THROWNREADFAILS"
+    // (tests/utils/engine-variants.test.js): drop the try/catch.
+    return { known: false, variants: {}, limitOutput: null, unreadable: `read threw: ${(err && err.message) || String(err)}` };
+  }
+  // #218 PR 4 whole-branch review (EP-3): the SDK returns a non-2xx as a VALUE ({error,
+  // response}, no data — opencode-client.js :: providerErrorReason keys on the same shape).
+  // A response with no providers array is UNREADABLE, not "model unknown": the wait must not
+  // burn 5 s on it and the note must not claim a read that never happened.
+  // Named mutant "UNREADABLEISCOLD" (tests/utils/engine-variants.test.js): `list = []` on that shape.
+  const list = (r && r.data && Array.isArray(r.data.providers)) ? r.data.providers : null;
+  if (list === null) {
+    const status = r && ((r.response && r.response.status) || (r.error && r.error.status));
+    return { known: false, variants: {}, limitOutput: null, unreadable: typeof status === 'number' ? `HTTP ${status}` : 'no providers array in the response' };
+  }
+  const p = list.find((x) => x && x.id === providerID);
+  const m = (p && p.models && Object.prototype.hasOwnProperty.call(p.models, modelID)) ? p.models[modelID] : null;
+  const limit = (m && m.limit && typeof m.limit === 'object') ? m.limit : {};
+  return {
+    known: engineSourced(modelID, m),
+    variants: (m && m.variants && typeof m.variants === 'object') ? m.variants : {},
+    limitOutput: positiveCount(limit.output),
+    unreadable: null,
+  };
+}
+
+/**
+ * The ceiling amicus's own catalog knows for `model` — the number
+ * config.js :: buildProviderModels clamps a budget-derived descriptor to — or
+ * null when it knows none (the descriptor was then bare).
+ * @param {string} model executable id
+ * @param {Function} [readCache] test seam for model-catalog.js :: readCache
+ * @returns {number|null}
+ */
+function catalogCeilingFor(model, readCache) {
+  try {
+    const { buildLimitLookup } = require('./model-output-limit');
+    const cache = (readCache || require('./model-catalog').readCache)();
+    const row = buildLimitLookup(cache && cache.models).get(model);
+    return row ? positiveCount(row.maxOutputTokens) : null;
+  } catch { return null; }
+}
+
+/**
+ * The engine's declaration for `model` ('provider/model', split at the FIRST
+ * slash — an OpenRouter id keeps its vendor path), waiting up to `waitMs` for
+ * the catalogue to know it. Named mutant "NOWAIT" (tests/utils/engine-variants.test.js).
+ * @param {object} client SDK client
+ * @param {string} model executable id
+ * @param {{waitMs?: number, pollMs?: number, sleep?: Function, now?: Function, catalogCeiling?: number|null, readCache?: Function, signal?: {aborted: boolean}, readTimeoutMs?: number}} [opts] test seams — `catalogCeiling` (explicit) wins over `readCache`. `readTimeoutMs` — each individual `/config/providers` read's own deadline (council #235 r2 A1).
+ * @returns {Promise<{known: boolean, variants: object, limitOutput: number|null, unreadable: string|null, ceiling: number|null, ceilingFrom: string, waitedMs: number}>} `ceiling` is what the fit judges against: the amicus catalog's ceiling when it knows the model, else `limitOutput`; `ceilingFrom` is `'catalog'` or `'engine'` accordingly, and checkVariant's OVER_BUDGET remedy reads it.
+ */
+async function readModelDeclaration(client, model, opts = {}) {
+  const idx = typeof model === 'string' ? model.indexOf('/') : -1;
+  const providerID = idx > 0 ? model.slice(0, idx) : String(model);
+  const modelID = idx > 0 ? model.slice(idx + 1) : '';
+  const waitMs = opts.waitMs === undefined ? DECLARATION_WAIT_MS : opts.waitMs;
+  const pollMs = opts.pollMs === undefined ? DECLARATION_POLL_MS : opts.pollMs;
+  const sleep = opts.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = opts.now || Date.now;
+  const catalogCeiling = opts.catalogCeiling !== undefined ? opts.catalogCeiling : catalogCeilingFor(model, opts.readCache);
+  const signal = opts.signal || null; // #218 PR 4 whole-branch review (EP-2): the caller's abandon signal
+  // council #235 r3 (C1/B1): the wait asks `known` and NOTHING about the budget. `known` is now
+  // "the engine's catalogue supplied this row" (engineSourced, M23), so the row that used to be
+  // indistinguishable from an echo — amicus's descriptor and nothing else — is positively
+  // identified and polled, and an engine row declaring no variants settles on the first read and
+  // is refused; both in EITHER budget state. The deleted `budgetInForce`/`couldBeEcho`/`ambiguous`
+  // machinery managed an ambiguity the response never had. Named mutant "COLDECHOKNOWN": stop polling once the dump reports any `limit.output` — the echo ends the wait on the first read again. Council #235 r4 (A2/C4): the bound is the WHOLE wait, not the number of reads. The condition is checked BEFORE the sleep+read that follows it, so an unclamped pair used to carry the wait to `waitMs + pollMs + readTimeoutMs` (7.5 s on the shipped 5000/500/2000; measured 7,361 ms against an endpoint answering in 1.9 s, which killed a leg under an `AMICUS_NO_OUTPUT_BACKSTOP_MS=6000` the docs present as safely above the wait). No read now starts without a poll interval left, and each in-loop read gets only the remaining budget. Named mutant "UNCLAMPEDPOLL": restore the plain `now() - start < waitMs` condition with an unclamped in-loop read.
+  const readTimeout = positiveCount(opts.readTimeoutMs) || DECLARATION_READ_TIMEOUT_MS;
+  const start = now();
+  let d = await readDeclarationOnce(client, providerID, modelID, { signal, readTimeoutMs: opts.readTimeoutMs });
+  while (!d.unreadable && !d.known && !(signal && signal.aborted) && waitMs - (now() - start) > pollMs) {
+    await sleep(pollMs);
+    const left = waitMs - (now() - start);
+    if (left < 1) { break; } // < 1, not <= 0: positiveCount FLOORS a sub-millisecond remainder to null, which would hand the read the full 2 s default back
+    const next = await readDeclarationOnce(client, providerID, modelID, { signal, readTimeoutMs: Math.min(readTimeout, left) });
+    if (next.unreadable && left < readTimeout) { break; } // council #235 r4 wave 5 repair: a read the WAIT'S OWN remainder truncated is not evidence the endpoint could not be read, and `unreadable` is what formatUnverifiedVariantNote turns into "could not be read (...; one read, no wait)". Measured: with the clamp above and no suppression here, an endpoint answering in 285 ms — the top of M12's warm range — ended 7 good reads and a full 5 s wait reported unreadable. The cold-catalogue outcome (`waitedMs`, no `unreadable`) is the true one; only a read that got its FULL deadline and still failed is a read failure. Named mutants "BUDGETABORTUNREADABLE" (drop this line) and "SUPPRESSALLINLOOP" (drop the `left < readTimeout` conjunct).
+    d = next;
+  }
+  // #218 PR 4 (found by probe row M20 in Task 2): /config/providers ECHOES the
+  // descriptor amicus wrote -- a budget-derived limit.output 24000 reads back as
+  // 24000 (M3's dump-after) -- so with a budget in force the dump cannot tell
+  // the model's ceiling. The fit judges against the ceiling amicus clamped that
+  // descriptor to (its own catalog's maxOutputTokens, the same number
+  // config.js :: buildProviderModels used) and against the dump's value only
+  // when the catalog has none: then the descriptor was bare and the dump is the
+  // engine's own ceiling (K5/K12). Named mutant "ECHOEDCEILING"
+  // (tests/utils/engine-variants.test.js): `ceiling: d.limitOutput` unconditionally.
+  // council #235 r2 (B1): `ceilingFrom` says whose number this is. 'engine' = a bare descriptor,
+  // so the dump IS the engine's ceiling (K5/K12) and the remedy below is provable. 'catalog' =
+  // the dump echoes what amicus wrote (M3), so the engine's real ceiling may be HIGHER and
+  // raising the budget to it can land inside the unrefused window. Named mutant "CEILINGPROVENANCE".
+  return { ...d, ceiling: catalogCeiling !== null ? catalogCeiling : d.limitOutput, ceilingFrom: catalogCeiling !== null ? 'catalog' : 'engine', waitedMs: now() - start };
+}
+
+/**
+ * Pure: send, refuse, or send unverified — in that order of tests.
+ *   1. unknown model -> {ok: true, verified: false} (mutant "UNKNOWNREFUSED");
+ *   2. known, undeclared -> VARIANT_UNDECLARED in one of TWO shapes (own properties only — mutant
+ *      "PROTOLOOKUP"): the declared set named when the row lists one, else the empty-set reason,
+ *      which says whose row it is and that a budget cannot change the verdict (mutants
+ *      "EMPTYSETSILENT", "MESSAGEOVERCLAIMS");
+ *   3. declared, entry `thinking: {type: 'enabled', budgetTokens: N}`, a positive budget B, and either a ceiling C above it or NO ceiling at all -> VARIANT_OVER_BUDGET reserving min(B + N, C), or the unclamped B + N when nothing declares a C (council #235 r4 C7, mutant "NULLCEILINGSENDS"); mutants "ALWAYSREFUSE": drop `B < C`; "FITWITHOUTBUDGET": default a null budget to 32000; "ANTHROPICONLY": key on the provider id instead of the shape.
+ *      The remedy has THREE shapes. With a C, keyed on `declaration.ceilingFrom` (council #235 r2 B1): an ENGINE-sourced ceiling gets "raise to at least C (the sum is then clamped, K4)", which the dump proves; a CATALOG-sourced one names C as amicus's own number and says to run `amicus models --refresh` first, because the engine's real ceiling may be higher and a budget in that gap is never re-checked (mutant "REMEDYALWAYSCATALOG"). With NO C it names the `limit` to declare and the only value that fits, B - N (M17), because declaring C = B silences the fit instead of shrinking the reservation;
+ *   4. otherwise {ok: true, verified: true, entry}.
+ * @param {{variant: string, model: string, declaration: object, outputBudget?: number|null}} a
+ * @returns {{ok: true, verified: boolean, entry?: object} | {ok: false, code: string, reason: string}}
+ */
+function checkVariant({ variant, model, declaration, outputBudget }) {
+  if (!declaration || !declaration.known) { return { ok: true, verified: false }; }
+  const variants = (declaration.variants && typeof declaration.variants === 'object') ? declaration.variants : {};
+  if (!Object.prototype.hasOwnProperty.call(variants, variant)) {
+    const names = Object.keys(variants);
+    // council #235 r3 (C1/B1): the EMPTY set is its own answer and gets its own reason. The
+    // row reached this branch because `known` says the engine's own catalogue supplied it
+    // (engineSourced, M23), so "declares no variants" is an observation, not an unfinished
+    // read — and it says so without claiming WHICH cell carried the evidence, because the
+    // predicate is an OR (10 of 50 openai rows have `name === id`; 26 of 361 openrouter
+    // `:free` rows price at zero, and both are engine-sourced through other cells). Named
+    // mutants "EMPTYSETSILENT" (fall back to the listed wording) and "MESSAGEOVERCLAIMS"
+    // (assert the row carries its name, family, release date AND prices). Council #235 r3 wave 4 repair, three more ways one string misleads: the enumeration also names the DISPLAY NAME, since `name !== modelID` is a disjunct too ("NAMECELLUNNAMED"); the reason echoes the level the user typed, which docs/troubleshooting.md promises and a fanout needs ("MESSAGEDROPSLEVEL"); and the mirror hint says "sometimes", not "often" — measured during the wave-4 review on a live dump, 2 of 196 variant-less engine rows had a mirror that declares levels, and gpt-4o's own (openrouter/openai/gpt-4o-2024-08-06) does not ("MIRROROFTEN"). Council #235 r4 (C3), the message only: `/config/providers` serves the MERGED config-and-catalogue view, so metadata a user declares in their own opencode.json (name, release_date, cost, reasoning) satisfies `engineSourced` without the engine's catalogue knowing the model — the verdict is still honest there (a merged view declaring no variants makes the send a no-op either way), so the sentence stops asserting that the engine's own catalogue is the source and says the row reads as a declaration in that merged view. The second `config.get()` read that would subtract config-set cells is FILED, not built (BACKLOG, #218 PR 4). Named mutant "CATALOGUEPROVENANCE": restore "carries cells only the engine's own catalogue fills".
+    if (names.length === 0) {
+      return { ok: false, code: 'VARIANT_UNDECLARED', reason: `VARIANT_UNDECLARED: ${model} declares no variants at all, so '${variant}' is not among them — the row the engine returned for it (/config/providers, the engine's merged view of its own catalogue and your opencode config) carries catalogue-style metadata (a display name, family, release date, pricing or capabilities), so it reads as a declaration and not an unfinished read; an undeclared variant is a silent no-op on the wire (probe F3/M7), so nothing was sent. Omit --thinking to run at the provider's own default effort, or pick a route whose row declares levels (a gateway mirror of the same model sometimes does). Setting an outputBudget does not change this verdict (council #235 r3, C1/B1); on a first engine start the bundled catalogue can declare a smaller set than the live one, so the same level can be accepted on the next run` };
+    }
+    // council #235 r2 (B4): the names come from the engine's remote models.dev refresh, so
+    // they are defanged before they enter a message that reaches a log and a terminal.
+    // `model` is NOT defanged and must not be: it is amicus's own resolved config id, not
+    // engine-sourced text.
+    const listed = defang(names.join(', '));
+    return { ok: false, code: 'VARIANT_UNDECLARED', reason: `VARIANT_UNDECLARED: ${model} does not declare a '${variant}' variant — the engine's catalogue lists ${listed} for it (/config/providers); an undeclared variant is a silent no-op on the wire (probe F3/M7), so nothing was sent. Pick one of the listed levels, or omit --thinking to run at the provider's own default effort` };
+  }
+  const entry = variants[variant];
+  const thinking = (entry && entry.thinking && typeof entry.thinking === 'object') ? entry.thinking : null;
+  const budgetTokens = (thinking && thinking.type === 'enabled') ? positiveCount(thinking.budgetTokens) : null;
+  const budget = positiveCount(outputBudget);
+  const ceiling = declaration.ceiling;
+  if (budgetTokens !== null && budget !== null && (ceiling === null || budget < ceiling)) {
+    const sum = budget + budgetTokens;
+    const reservation = ceiling === null ? sum : Math.min(sum, ceiling);
+    const how = ceiling === null ? `${budget} + ${budgetTokens}, with no ceiling declared anywhere to clamp it` : (sum > ceiling ? `${budget} + ${budgetTokens}, clamped to the model's ${ceiling} ceiling` : `${budget} + ${budgetTokens}`);
+    // council #235 r2 (B1): the remedy must not walk the user into the one unrefused window.
+    // With a budget in force the dump ECHOES the descriptor amicus wrote (M3), so `ceiling` is
+    // amicus's own catalog number; if the engine's real ceiling is higher, a budget raised to
+    // exactly this number sits in [C_catalog, C_engine) — the fit falls silent there and the leg
+    // still reserves up to C_catalog + N on the wire. Named mutant "REMEDYALWAYSCATALOG".
+    // council #235 r4 (C7): a NULL ceiling is "no clamp anyone declared", not "no risk" — a row that declares the level with the `enabled + budgetTokens` shape and carries no `limit.output` anywhere (a model declared in the user's own opencode.json with a variants block and no limit, which amicus's catalog has no row for either) used to skip the fit entirely and send verified, while `budget + N` with N >= 1 always exceeds the budget. Its remedy must name the ceiling that is MISSING, never tell the user to raise the budget to a number nothing declares. Named mutant "NULLCEILINGSENDS": restore the `ceiling !== null` conjunct above. Wave 5 repair, that remedy's own two false notes: a declared `limit.output` is a DESCRIPTOR, not a clamp on the sum (K9 measured `limit.output 40000` + `max` reserving 63999; K3/K4/K10 record the sum clamped at the model's REAL ceiling "regardless of what the descriptor or the flag said"), and the obvious value to declare — the budget itself — makes `budget < ceiling` false, so the fit falls SILENT and the same over-budget leg sends verified (the r2 B1 window again). The remedy names the fitting value instead, `budget - N` (the exact fit, M17). Named mutants "DECLAREDLIMITCLAMPS" and "REMEDYWITHOUTFIT".
+    const raise = ceiling !== null ? (declaration.ceilingFrom === 'catalog' ? `Raise outputBudget to at least ${ceiling} — the ceiling amicus's own catalog carries for this model, which is what the fit can read once a budget is set (M3); if the engine's real ceiling is higher, a budget in that gap is not re-checked, so prefer \`amicus models --refresh\` first` : `Raise outputBudget to at least ${ceiling} (the sum is then clamped to the ceiling, K4)`) : `Declare a \`limit\` for this model in your opencode config — its \`output\` is the ceiling this fit judges against and has to leave room for the ${budgetTokens} the engine adds ON TOP (${budget > budgetTokens ? `at most ${budget - budgetTokens}, the value that lands the sum exactly on the budget — the exact fit, M17` : `no value fits — the engine adds ${budgetTokens} on top of whatever it reserves, more than this whole budget`}); a value at or above ${budget} silences this fit while the leg still reserves ${budgetTokens} over the budget, and declaring one does not clamp the sum — only the model's real ceiling does that (K3/K9/K10), and nothing declares one here — or clear outputBudget, which leaves the leg the engine's own default reservation with the ${budgetTokens} tokens added to it`;
+    return { ok: false, code: 'VARIANT_OVER_BUDGET', reason: `VARIANT_OVER_BUDGET: the '${variant}' variant on ${model} carries a ${budgetTokens}-token thinking budget that the engine adds ON TOP of the reservation on this route (probe M2: 24000 + 16000 = 40000; K2), so with outputBudget ${budget} this leg would reserve ${reservation} (${how}) — ${reservation - budget} over the budget; nothing was sent. ${raise}, route the model through OpenRouter (a variant leaves the reservation at the budget there — M1: 8000 stayed 8000 under 'low'; M9: 32000 with 'high' on both of the engine's catalogues), or use an adaptive-thinking model such as claude-sonnet-5 (M10b)` };
+  }
+  return { ok: true, verified: true, entry };
+}
+
+/**
+ * The log line for a variant sent to a model the catalogue did not know in time.
+ * TWO shapes with TWO tails (council #235 r5, J4/A1/B2): they used to share one, and the shared
+ * tail said the level applies once the engine LEARNS the model — true of a cold catalogue, false
+ * of a read that failed, where nothing was learned or unlearned. Both tails now also say that the
+ * over-budget fit did not run for this leg, because `known === false` entails an empty variants
+ * map (it is one of the disjuncts of `known`), so the fit had no budgetTokens to read and CANNOT
+ * be made to run here -- the refusal the seats asked for is refused; naming what did not run is
+ * the whole remedy for the first-run-versus-later-run inconsistency. Named mutant "NOTEHIDESFIT".
+ * @param {{model: string, variant: string, waitedMs: number, unreadable?: string|null}} a
+ * @returns {string}
+ */
+function formatUnverifiedVariantNote({ model, variant, waitedMs, unreadable }) {
+  if (unreadable) {
+    // council #235 r2 (B4): `unreadable` carries an engine/transport error message -- defanged before it reaches a log line and a terminal. `model` stays raw: it is amicus's own id.
+    return `the engine's /config/providers could not be read (${defang(unreadable)}; one read, no wait), so '${variant}' was sent unverified: NEITHER check ran for this leg — not the declared-set check and not the over-budget fit — so the level applies if and only if ${model} declares it, and on the direct-Anthropic additive shape (a variant entry whose thinking type is 'enabled' with a budgetTokens N) the engine adds that N on top of the output budget (probe M2: 24000 + 16000 = 40000; K2) with nothing here to catch it.`;
+  }
+  // council #235 r3 (C1/B1): two shapes, not three. The `ambiguous` branch named a state the dump never had -- a row carrying only amicus's descriptor is positively identified now.
+  return `the engine's catalogue did not know ${model} within ${waitedMs} ms (its /config/providers entry carries nothing but the descriptor amicus registered, or the model is absent from the dump), so '${variant}' was sent unverified: it applies only if the engine learns the model before it builds the request (its startup models.dev refresh — probe M12 saw qwen3.8-max-0902 known on the first poll of a warm engine, 36 ms on one run, and unknown at the first read of a cold one, M0) and is a silent no-op otherwise (M7). The over-budget fit did not run for this leg either, so once the engine's catalogue knows the model the same command can refuse with VARIANT_OVER_BUDGET.`;
+}
+
+module.exports = { VARIANT_LEVELS, VariantRefusedError, readModelDeclaration, checkVariant, formatUnverifiedVariantNote };