amicus 4.9.2 → 4.9.4

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

package/src/utils/http-get.js

@@ -0,0 +1,284 @@
+/**
+ * @module http-get
+ * One HTTPS GET, always resolved, never rejected — the timer/destroy/failure
+ * core that model-fetcher.js :: fetchViaConfigDetailed carried inline (#209)
+ * and that the models.dev ceiling fetch (#218 P3) needs too. Extracted rather
+ * than copied so a second caller cannot drift from the first: the same failure
+ * reasons and the same {reason, status?, detail?} shape the catalog persists
+ * as providerFailures.
+ *
+ * The call shape is deliberately `https.get(url, { headers }, cb)` — the one
+ * tests/model-fetcher.test.js mocks — so that suite keeps intercepting after
+ * the extraction.
+ *
+ * REDIRECTS ARE OPT-IN, AND THEN FOLLOWED AT MOST TWICE (council #230 A2, made
+ * opt-in by #230 D4). Without `followRedirects: true` a 3xx is the terminal
+ * `http-status` failure it has always been — the keyed provider fetches in
+ * `model-fetcher.js` never hop, so a provider's redirect stays a visible
+ * failure rather than a silent behavioural change. With the option on, a
+ * 301/302/303/307/308 carrying a `Location` is resolved against the URL that
+ * produced it and re-issued under the SAME deadline — one timeout covers the
+ * whole chain, so a hop never buys the server more time. The target must be
+ * `https:`. A plain-http Location, a missing Location and a third redirect are
+ * each an `http-status` failure carrying the status plus a `detail` naming
+ * which, so a domain move that loops or downgrades stays visible on the
+ * caller's failure line (for the models.dev ceiling fetch, the `Ceilings:` line
+ * of `amicus models --refresh`) instead of being chased silently.
+ *
+ * ONLY AN ALLOWLIST OF HEADERS CROSSES AN ORIGIN (council #230 C3). `model-fetcher.js`
+ * hands this module `Authorization: Bearer <key>` (openrouter/openai/deepseek)
+ * or `x-api-key` (anthropic), so a 302 — or an open redirect — on a provider
+ * host would otherwise forward a live key to whatever host the `Location`
+ * named. A same-origin hop keeps every header; a CROSS-ORIGIN hop keeps ONLY
+ * `user-agent`, `accept` and `accept-language` (matched
+ * case-insensitively) and drops everything else. An allowlist rather than a
+ * deny-list because the deny-list has to be extended for every new vendor
+ * header — `x-goog-api-key` was not on it — and the one that is forgotten is
+ * the one that leaks. Once dropped, stay dropped: the stripped set is what the
+ * next hop carries, so a same-origin third hop cannot resurrect a credential.
+ * `accept-encoding` is NOT on the allowlist (council #230 C3): nothing here
+ * decodes a content-encoded body, so forwarding it would invite compressed
+ * bytes to be concatenated into the body as text.
+ *
+ * A REFUSED 3xx RELEASES THE CONNECTION (council #230 C1). Each refusal branch
+ * settles the promise first and then retires the response and destroys the live
+ * request: the chain's single deadline is cleared the moment the promise
+ * settles, so a refused redirect whose body never ends would otherwise hold the
+ * socket open with nothing left to close it.
+ *
+ * The body is capped at `maxBytes` (council #230 B3): a response that keeps
+ * coming is destroyed and reported as `too-large` rather than accumulated in a
+ * string until the process dies.
+ */
+
+'use strict';
+
+const https = require('https');
+
+const DEFAULT_TIMEOUT_MS = 5000;
+/** 16 MiB. models.dev's api.json is ~4.5 MB, so this is headroom, not a budget. */
+const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+/** Two hops, then `redirect limit reached`. */
+const MAX_REDIRECTS = 2;
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+/**
+ * The ONLY headers a cross-origin hop keeps. Lower-case: callers spell headers
+ * freely. `accept-encoding` is deliberately NOT here (council #230 C3): this
+ * module never decodes a content-encoded body, so forwarding it would invite a
+ * compressed response to be concatenated into a string as text.
+ */
+const CROSS_ORIGIN_HEADERS = new Set(['user-agent', 'accept', 'accept-language']);
+
+/**
+ * The headers the NEXT hop may carry. A same-origin hop keeps the caller's
+ * object untouched; a cross-origin hop gets a copy holding ONLY the allowlisted
+ * names. A current URL that will not parse counts as cross-origin — the safe
+ * direction, since the comparison cannot be made.
+ * @param {object} headers the headers this hop was issued with
+ * @param {string} from the URL that produced the redirect
+ * @param {URL} to the resolved target
+ * @returns {object} `headers` itself, or an allowlisted copy
+ */
+function hopHeaders(headers, from, to) {
+  let fromOrigin = null;
+  try { fromOrigin = new URL(from).origin; } catch (err) { fromOrigin = null; }
+  if (fromOrigin !== null && fromOrigin === to.origin) { return headers; }
+  const kept = {};
+  for (const name of Object.keys(headers)) {
+    if (CROSS_ORIGIN_HEADERS.has(name.toLowerCase())) { kept[name] = headers[name]; }
+  }
+  return kept;
+}
+
+/**
+ * Retire a response the chain has finished with — either before the next hop starts, or on a
+ * refused redirect (`refuseRedirect`). Its `data`/`end`
+ * listeners and — the point of this — the chain's `error` listener are detached
+ * first, so an abrupt close on the abandoned socket can no longer settle a
+ * promise the live hop now owns. `error` is REPLACED by a swallow rather than
+ * simply removed: a destroyed stream still emits, and an 'error' with no
+ * listener at all throws as an uncaught exception.
+ * @param {object} res the http.IncomingMessage the chain has moved on from
+ */
+function retire(res) {
+  res.removeAllListeners('data');
+  res.removeAllListeners('end');
+  res.removeAllListeners('error');
+  res.on('error', () => {});
+  if (typeof res.destroy === 'function') { res.destroy(); }
+}
+
+/**
+ * A REFUSED 3xx: settle with the failure, then release the connection it came
+ * on. Draining alone was not enough (council #230 C1) — settling clears the
+ * chain's only deadline, so after the refusal nothing would ever close a socket
+ * whose body never ends. The failure is raised FIRST and the teardown second,
+ * because destroying the request can emit `error` on it and `ctx.onError` is
+ * still attached; single-settle then makes that late event a no-op instead of
+ * rewriting the reason as `network-error`.
+ * @param {object} res the http.IncomingMessage
+ * @param {{fail: Function, destroy: Function}} ctx
+ * @param {{reason: string, status: number, detail: string}} failure
+ */
+function refuseRedirect(res, ctx, failure) {
+  ctx.fail(failure);
+  retire(res);
+  ctx.destroy();
+}
+
+/**
+ * One hop's 3xx: resolve `Location` against the URL that produced it, retire
+ * this response, and hand the target plus its (possibly stripped) headers to
+ * `ctx.hop` — or fail with the status and a `detail` naming why the hop was
+ * refused. Every refusal goes through `refuseRedirect`, which releases the
+ * connection as well as failing.
+ * @param {object} res the http.IncomingMessage
+ * @param {{url: string, left: number, headers: object}} hop the hop it answered
+ * @param {{hop: Function, fail: Function, destroy: Function, retireRequest: Function}} ctx
+ */
+function followRedirect(res, hop, ctx) {
+  const status = res.statusCode;
+  const loc = (res.headers && res.headers.location) || null;
+  if (loc === null) { refuseRedirect(res, ctx, { reason: 'http-status', status, detail: 'redirect without Location' }); return; }
+  if (hop.left <= 0) { refuseRedirect(res, ctx, { reason: 'http-status', status, detail: 'redirect limit reached' }); return; }
+  let next;
+  try {
+    next = new URL(loc, hop.url);
+  } catch (err) {
+    refuseRedirect(res, ctx, { reason: 'http-status', status, detail: `redirect to an unparseable Location: ${err.message}` });
+    return;
+  }
+  // https ONLY: a downgrade would re-send the caller's headers in clear text.
+  if (next.protocol !== 'https:') { refuseRedirect(res, ctx, { reason: 'http-status', status, detail: 'redirect to non-https location' }); return; }
+  const headers = hopHeaders(hop.headers, hop.url, next);
+  retire(res);  // BEFORE the next hop exists, so the two can never race
+  ctx.retireRequest();  // and its REQUEST's 'error' listener with it
+  ctx.hop({ url: next.toString(), left: hop.left - 1, headers });
+}
+
+/**
+ * One hop's response: a 3xx goes to followRedirect WHEN the caller opted in,
+ * any other non-200 — an un-opted-in 3xx included — is an `http-status` failure
+ * once the body drains, a 200 accumulates under the byte cap.
+ * @param {object} res the http.IncomingMessage
+ * @param {{url: string, left: number, headers: object}} hop the hop it answered
+ * @param {{hop: Function, fail: Function, done: Function, onError: Function, destroy: Function,
+ *   retireRequest: Function, maxBytes: number, followRedirects: boolean}} ctx
+ */
+function readResponse(res, hop, ctx) {
+  // Decode once, at the stream: `chunks += chunk` decodes each Buffer on its
+  // own and mangles any multi-byte character split across a chunk boundary.
+  res.setEncoding('utf8');
+  // A mid-body stream error is emitted on `res`, NOT on `req`. With no listener
+  // here node rethrows it as an uncaught exception and the promise never
+  // settles — so it is attached once, ahead of the status check, and covers the
+  // redirect and non-200 drain branches too.
+  res.on('error', ctx.onError);
+  if (ctx.followRedirects && REDIRECT_STATUS.has(res.statusCode)) { followRedirect(res, hop, ctx); return; }
+  if (res.statusCode !== 200) {
+    // The deadline stays armed until `end`: a non-200 whose body never ends
+    // must still time out rather than leave the promise pending for ever.
+    res.on('data', () => {});
+    res.on('end', () => { ctx.fail({ reason: 'http-status', status: res.statusCode }); });
+    return;
+  }
+  let body = '';
+  let bytes = 0;
+  res.on('data', (chunk) => {
+    // Bytes, not `body.length`: the cap is named in bytes and the stream is
+    // already decoded, so a multi-byte body would otherwise pass an over-budget
+    // payload through under the character count.
+    bytes += Buffer.byteLength(chunk, 'utf8');
+    if (bytes > ctx.maxBytes) {
+      ctx.destroy();
+      ctx.fail({ reason: 'too-large', detail: `body exceeded ${ctx.maxBytes} bytes` });
+      return;
+    }
+    body += chunk;
+  });
+  res.on('end', () => { ctx.done({ ok: true, body }); });
+}
+
+/**
+ * GET `url`; resolve with the raw body on a 200. Caps the body at `maxBytes`.
+ * With `followRedirects: true` it follows at most two https redirects under a
+ * single deadline, keeping only the allowlisted headers on a cross-origin hop;
+ * without it a 3xx is a terminal `http-status` failure.
+ * @param {string} url
+ * @param {{headers?: object, timeoutMs?: number, maxBytes?: number, followRedirects?: boolean}} [opts]
+ * @returns {Promise<{ok: true, body: string}|{ok: false, failure: {reason: string, status?: number, detail?: string}}>}
+ */
+function httpGetText(url, opts = {}) {
+  const headers = opts.headers || {};
+  const timeoutMs = opts.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : opts.timeoutMs;
+  const maxBytes = opts.maxBytes === undefined ? DEFAULT_MAX_BYTES : opts.maxBytes;
+  const followRedirects = opts.followRedirects === true;
+  return new Promise((resolve) => {
+    // CHAIN-SCOPED. The deadline and the size trip must destroy the LIVE hop, so
+    // every hop assigns this from inside itself BEFORE dispatching its response.
+    // An outer `req = https.get(...)` cannot: https.get may call back
+    // synchronously, and the next hop's assignment would then be undone by the
+    // outer one completing afterwards.
+    let current = null;
+    let timer = null;
+    let settled = false;
+    // Single-settle: a timeout, a stream error, a size trip and an `end` can all
+    // race, and across a redirect chain the losing hops are still live.
+    const done = (v) => { if (settled) { return; } settled = true; clearTimeout(timer); resolve(v); };
+    const fail = (failure) => { done({ ok: false, failure }); };
+    const onError = (err) => { fail({ reason: 'network-error', detail: err.message }); };
+    const destroy = () => { if (current) { current.destroy(); } };
+    // A superseded hop's REQUEST keeps `onError` attached, so a late socket
+    // error on the abandoned connection would settle a chain the live hop now
+    // owns. Swapped for a swallow rather than merely removed: 'error' with no
+    // listener at all throws as an uncaught exception. Not destroyed — the
+    // response side already is, and destroying the request would fire this.
+    const retireRequest = () => {
+      if (!current) { return; }
+      current.removeAllListeners('error');
+      current.on('error', () => {});
+    };
+    // ONE deadline for the WHOLE chain — armed before the first hop, never rearmed.
+    timer = setTimeout(() => { destroy(); fail({ reason: 'timeout', detail: `no response within ${timeoutMs}ms` }); }, timeoutMs);
+    const ctx = { fail, done, onError, maxBytes, destroy, retireRequest, followRedirects, hop: null };
+    ctx.hop = (hop) => {
+      let res = null;
+      let armed = false;
+      let request;
+      try {
+        request = https.get(hop.url, { headers: hop.headers }, (r) => { res = r; if (armed) { readResponse(r, hop, ctx); } });
+      } catch (err) {
+        // `https.get` throws SYNCHRONOUSLY on a malformed URL (and on a bad
+        // option object). "Always resolves, never rejects" has to hold for that.
+        onError(err);
+        return;
+      }
+      current = request;
+      request.on('error', onError);
+      armed = true;
+      // A callback that already fired SYNCHRONOUSLY is replayed here, now that
+      // `current` is this hop's request rather than the previous one's.
+      if (res) { readResponse(res, hop, ctx); }
+    };
+    ctx.hop({ url, left: MAX_REDIRECTS, headers });
+  });
+}
+
+/**
+ * GET + JSON.parse. A body that is not JSON is a 'parse-error' failure, so a
+ * caller sees the transport reasons plus exactly this one more.
+ * @param {string} url
+ * @param {{headers?: object, timeoutMs?: number, maxBytes?: number, followRedirects?: boolean}} [opts]
+ * @returns {Promise<{ok: true, json: any}|{ok: false, failure: {reason: string, status?: number, detail?: string}}>}
+ */
+async function getJson(url, opts) {
+  const res = await httpGetText(url, opts);
+  if (!res.ok) { return res; }
+  try {
+    return { ok: true, json: JSON.parse(res.body) };
+  } catch (err) {
+    return { ok: false, failure: { reason: 'parse-error', detail: err.message } };
+  }
+}
+
+module.exports = { httpGetText, getJson, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_BYTES, MAX_REDIRECTS };