amicus 4.9.3 → 4.9.4

package/src/utils/model-catalog.js

@@ -20,6 +20,10 @@ const path = require('path');
 function _getConfigDir() { return require('./config').getConfigDir(); }
 function _readApiKeyValues() { return require('./api-key-store').readApiKeyValues(); }
 async function _fetchAllModels(keys) { return require('./model-fetcher').fetchAllModelsDetailed(keys); }
+async function _enrichCeilings(rows) { return require('./model-ceilings-modelsdev').enrichCeilings(rows); }
+function _emptyOutcome(failure) { return require('./model-ceilings-modelsdev').emptyOutcome(failure); }
+/** #218 P3 opt-out: `modelsDevCeilings: false` in config.json, and ONLY a literal false. */
+function _modelsDevEnabled() { return require('./config').loadConfig()?.modelsDevCeilings !== false; }
 
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
 const CATALOG_SCHEMA_VERSION = 2;
@@ -68,8 +72,13 @@ function writeCacheDoc(doc) {
   }
 }
 
-/** Write a successful fetch: fresh models/fetchedAt, outcome fields cleared. @param {Array} models */
-function writeCache(models, providerFailures) {
+/**
+ * Write a successful fetch: fresh models/fetchedAt, outcome fields cleared.
+ * @param {Array} models
+ * @param {Array} [providerFailures]
+ * @param {object|null} [ceilingEnrichment] #218 P3 outcome for THESE rows (model-ceilings-modelsdev.js)
+ */
+function writeCache(models, providerFailures, ceilingEnrichment) {
   writeCacheDoc({
     schemaVersion: CATALOG_SCHEMA_VERSION,
     fetchedAt: Date.now(),
@@ -78,6 +87,7 @@ function writeCache(models, providerFailures) {
     // alongside the rows because it describes THESE rows -- a cache served later
     // is still a catalog whose deepseek namespace is empty for a reason.
     providerFailures: Array.isArray(providerFailures) ? providerFailures : [],
+    ceilingEnrichment: ceilingEnrichment || null,
   });
 }
 
@@ -124,7 +134,27 @@ async function refreshCatalog() {
     writeRefreshFailure(reason, providerFailures);
     return [];
   }
-  writeCache(models, providerFailures);
+  // #218 P3: fill direct-provider ceilings from models.dev AFTER the floor-only
+  // check (a failed refresh is never enriched, so "stale cache stands" holds)
+  // and IN PLACE on the fresh row objects, so `authoritative`/`local` ride
+  // through untouched. enrichCeilings never rejects; the belt-and-braces catch
+  // keeps a bug there from failing a refresh that already succeeded.
+  // Council #230 D1/C2: `modelsDevCeilings: false` means models.dev is never
+  // contacted. The persisted outcome still carries the full counter set, so
+  // `--json` readers and the `Ceilings:` line see "disabled", not a blank.
+  let ceilingEnrichment;
+  if (!_modelsDevEnabled()) {
+    ceilingEnrichment = { ..._emptyOutcome(null), skipped: 'disabled' };
+  } else {
+    try {
+      ceilingEnrichment = await _enrichCeilings(models);
+    } catch (err) {
+      // Same shape enrichCeilings' own failures use (council #230 C4/D5), so every
+      // reader of ceilingEnrichment sees the full counter set however it failed.
+      ceilingEnrichment = _emptyOutcome({ reason: 'exception', detail: err.message });
+    }
+  }
+  writeCache(models, providerFailures, ceilingEnrichment);
   return models;
 }
 
@@ -154,7 +184,7 @@ async function getCatalog(opts = {}) {
  * #13: also threads the last-refresh outcome so callers can tell "current"
  * apart from "stale because refreshing keeps failing" — null/null when the
  * last attempt on record succeeded (or none has happened yet).
- * @returns {Promise<{models: Array, fetchedAt: number|null, lastRefreshAttempt: number|null, lastRefreshError: string|null}>}
+ * @returns {Promise<{models: Array, fetchedAt: number|null, lastRefreshAttempt: number|null, lastRefreshError: string|null, providerFailures: Array, ceilingEnrichment: object|null}>}
  */
 async function getCatalogInfo(opts = {}) {
   const models = await getCatalog(opts);
@@ -167,6 +197,8 @@ async function getCatalogInfo(opts = {}) {
     lastRefreshError: (doc && doc.lastRefreshError) || null,
     // #209: namespace-level fetch outcomes for the CACHED rows above.
     providerFailures: (doc && Array.isArray(doc.providerFailures)) ? doc.providerFailures : [],
+    // #218 P3: where the direct-provider ceilings came from, or why they did not.
+    ceilingEnrichment: (doc && doc.ceilingEnrichment) || null,
   };
 }
 

package/src/utils/model-ceilings-modelsdev.js

@@ -0,0 +1,230 @@
+/**
+ * @module model-ceilings-modelsdev
+ * #218 P3 — output ceilings for the direct-provider catalog rows.
+ *
+ * WHY: computeModelLimit (model-output-limit.js) refuses to emit a `limit`
+ * descriptor unless the catalog knows BOTH a model's context and its output
+ * ceiling — a blanket budget against an unknown ceiling would send an
+ * over-ceiling max_tokens. OpenRouter publishes its ceiling on /models; the
+ * direct openai/anthropic/deepseek lists do not (google's does, lifted
+ * first-party in model-fetcher.js). models.dev publishes all of them, keyless.
+ *
+ * WHAT THIS DOES NOT CHANGE: the engine already resolves every `{}` descriptor's
+ * limit from its own models.dev copy. This gives AMICUS the same numbers so it
+ * can clamp an outputBudget on the direct anthropic/deepseek routes through the
+ * descriptor (a route it cannot clamp still gets the budget through the engine
+ * flag — engine-output-flag.js) and name a reservation in a dead-leg note. The
+ * direct openai route is the exception: the engine drives that provider through
+ * the Responses API, whose request carries no output-limit field at all, so the
+ * ceiling filled here shows in `amicus models` but neither the descriptor nor
+ * the flag reaches the wire there — a direct openai row sends no output
+ * reservation at all (#218 PR 4, probe M5/M13/M22). It reads models.dev
+ * directly, not the engine's cache file, because that file's path and refresh
+ * flags are engine-private.
+ *
+ * RULES (measured 2026-09-04 against live data, see the plan):
+ *   - the provider's own value WINS: models.dev fills a field only when the
+ *     provider gave no usable positive integer — null, 0, negative or malformed
+ *     — and a usable provider value is never overwritten (OpenRouter and
+ *     models.dev disagree on 24 of 344 openrouter ceilings);
+ *   - a zero/absent models.dev limit is never written (openai image rows);
+ *   - `openrouter/openrouter/*` meta-routers are skipped (models.dev says
+ *     2,000,000 for `auto`, a number no underlying model honours);
+ *   - local rows are skipped; the fill is IN PLACE so `authoritative`/`local`
+ *     flags on the row objects ride through untouched;
+ *   - the FETCH ITSELF is skipped when no candidate row is missing a ceiling,
+ *     and `model-catalog.js` skips this module entirely when the config key
+ *     `modelsDevCeilings` is `false` (council #230 D1/C2): a refresh that has
+ *     nothing to fill must not spend up to 10 s asking.
+ */
+'use strict';
+
+const { positiveCount } = require('./model-output-limit');
+
+const MODELS_DEV_URL = 'https://models.dev/api.json';
+const MODELS_DEV_TIMEOUT_MS = 10000;
+/** The vendors amicus catalogs under these exact id prefixes (model-fetcher.js normalizers). */
+const VENDORS = ['anthropic', 'openai', 'google', 'deepseek', 'openrouter'];
+
+/**
+ * Index a models.dev api.json document by amicus catalog id. A positive
+ * finite integer count, or null — reuses `positiveCount` from
+ * model-output-limit.js so this module holds the same discipline as that one.
+ * @param {*} api parsed https://models.dev/api.json
+ * @returns {Map<string, {context: number|null, output: number|null}>}
+ */
+function limitsFromModelsDev(api) {
+  const out = new Map();
+  if (!api || typeof api !== 'object') { return out; }
+  for (const vendor of VENDORS) {
+    const models = api[vendor] && api[vendor].models;
+    if (!models || typeof models !== 'object') { continue; }
+    for (const [modelId, m] of Object.entries(models)) {
+      const limit = (m && typeof m === 'object' && m.limit) || {};
+      const context = positiveCount(limit.context);
+      const output = positiveCount(limit.output);
+      if (context === null && output === null) { continue; }
+      out.set(`${vendor}/${modelId}`, { context, output });
+    }
+  }
+  return out;
+}
+
+/**
+ * Why this row is not a fill candidate, or null when it is one. THE single
+ * definition: `fillCeilings` counts each class and `needsFillCount` collapses
+ * them to a boolean, so the pass and the nothing-to-fill check cannot disagree
+ * about which rows the fetch could serve.
+ * @param {*} row a catalog row
+ * @returns {null|'malformed'|'local'|'router'}
+ */
+function skipClass(row) {
+  if (!row || typeof row !== 'object' || typeof row.id !== 'string') { return 'malformed'; }
+  if (row.local === true) { return 'local'; }
+  if (row.id.startsWith('openrouter/openrouter/')) { return 'router'; }
+  return null;
+}
+
+/**
+ * Does this row still lack a number outputBudget needs? computeModelLimit
+ * refuses to emit a descriptor unless BOTH ceilings are known, so one usable
+ * field is not "known" for any purpose the fill exists to serve.
+ * @param {object} row a catalog row
+ * @returns {boolean}
+ */
+function missingACeiling(row) {
+  return positiveCount(row.contextLength) === null || positiveCount(row.maxOutputTokens) === null;
+}
+
+/**
+ * Fill contextLength / maxOutputTokens in place. A field is filled ONLY when the
+ * provider gave no usable positive integer for it — `positiveCount(...) === null`,
+ * i.e. null, 0, negative, below 1 or non-numeric. (`positiveCount` FLOORS, so
+ * 1.5 is a usable 1; only a fraction below 1 falls through.) A usable provider
+ * value is never overwritten. A filled row is stamped `limitSource: 'models.dev'`,
+ * which marks a row where AT LEAST ONE field was filled from models.dev — not a
+ * claim that both numbers came from there (council #230 D2).
+ *
+ * COUNTERS. `filled` / `alreadyKnown` / `unknown` describe what the pass did;
+ * `stillMissing` describes the STATE it left behind and deliberately overlaps
+ * them. `alreadyKnown` means both fields were usable BEFORE the pass, and is
+ * decided BEFORE the models.dev lookup (council #230 A2) — a complete row
+ * models.dev does not list is `alreadyKnown`, not `unknown`. A row with one
+ * field known and the other unfillable is `stillMissing`, never "already known"
+ * (council #230 C1/D5): outputBudget cannot clamp it.
+ * @param {Array<object>} rows catalog rows (mutated)
+ * @param {Map<string, {context: number|null, output: number|null}>} limits
+ * @returns {{filled: number, alreadyKnown: number, unknown: number, stillMissing: number,
+ *   skippedRouters: number, skippedLocal: number}}
+ */
+function fillCeilings(rows, limits) {
+  const counts = { filled: 0, alreadyKnown: 0, unknown: 0, stillMissing: 0, skippedRouters: 0, skippedLocal: 0 };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const skip = skipClass(row);
+    if (skip === 'malformed') { continue; }
+    if (skip === 'local') { counts.skippedLocal++; continue; }
+    if (skip === 'router') { counts.skippedRouters++; continue; }
+    // BEFORE the lookup (council #230 A2): a row that already carries both
+    // usable numbers has nothing for models.dev to fill, so whether models.dev
+    // happens to list it is irrelevant. Looking first counted such a row
+    // `unknown` when models.dev did not have it — reporting a row outputBudget
+    // CAN clamp as one it knows nothing about.
+    if (!missingACeiling(row)) { counts.alreadyKnown++; continue; }
+    const lim = limits.get(row.id);
+    if (!lim) {
+      counts.unknown++;
+    } else {
+      let touched = false;
+      if (positiveCount(row.contextLength) === null && lim.context !== null) { row.contextLength = lim.context; touched = true; }
+      if (positiveCount(row.maxOutputTokens) === null && lim.output !== null) { row.maxOutputTokens = lim.output; touched = true; }
+      if (touched) { row.limitSource = 'models.dev'; counts.filled++; }
+    }
+    if (missingACeiling(row)) { counts.stillMissing++; }
+  }
+  return counts;
+}
+
+/**
+ * How many candidate rows the fetch could possibly help. Zero means the network
+ * call has nothing to do and is skipped entirely (council #230 D1/C2).
+ * @param {Array<object>} rows catalog rows
+ * @returns {number}
+ */
+function needsFillCount(rows) {
+  let n = 0;
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (skipClass(row) === null && missingACeiling(row)) { n++; }
+  }
+  return n;
+}
+
+/**
+ * The outcome a FAILED — or SKIPPED — enrichment persists: the failure plus
+ * every counter at zero. One shape, so this module's own failure returns and
+ * `model-catalog.js :: refreshCatalog`'s belt-and-braces catch cannot drift
+ * apart and `models-ceiling-line.js :: fmtCeilingLine` always has the counters
+ * it prints. `skipped` defaults to null and a caller that skipped the fetch
+ * spreads its own reason over it.
+ * @param {null|{reason: string, status?: number, detail?: string}} failure
+ * @returns {{source: 'models.dev', failure: object|null, skipped: null, filled: number,
+ *   alreadyKnown: number, unknown: number, stillMissing: number, skippedRouters: number,
+ *   skippedLocal: number}}
+ */
+function emptyOutcome(failure) {
+  return {
+    source: 'models.dev', failure, skipped: null,
+    filled: 0, alreadyKnown: 0, unknown: 0, stillMissing: 0, skippedRouters: 0, skippedLocal: 0,
+  };
+}
+
+/**
+ * Fetch models.dev and fill `rows`. ALWAYS resolves; the outcome travels with
+ * the rows it describes (model-catalog.js persists it as ceilingEnrichment).
+ * Failure reasons are http-get's (`timeout`, `network-error`, `http-status`,
+ * `too-large`, `parse-error`) plus `bad-shape` and `exception`.
+ *
+ * NO CALL IS MADE when no candidate row is missing a ceiling: the outcome is
+ * `skipped: 'nothing-to-fill'` and models.dev is never contacted (council #230
+ * D1/C2 — a refresh on a fully-known catalog paid up to 10 s for nothing).
+ * @param {Array<object>} rows catalog rows (mutated in place)
+ * @param {{getJson?: Function}} [deps] test seam
+ * @returns {Promise<{source: 'models.dev', failure: null|{reason: string, status?: number, detail?: string},
+ *   skipped: null|'nothing-to-fill', filled: number, alreadyKnown: number, unknown: number,
+ *   stillMissing: number, skippedRouters: number, skippedLocal: number}>}
+ */
+async function enrichCeilings(rows, deps = {}) {
+  const getJson = deps.getJson || require('./http-get').getJson;
+  if (needsFillCount(rows) === 0) {
+    return { ...emptyOutcome(null), skipped: 'nothing-to-fill' };
+  }
+  let res;
+  try {
+    res = await getJson(MODELS_DEV_URL, {
+      timeoutMs: MODELS_DEV_TIMEOUT_MS,
+      followRedirects: true,
+      headers: { 'User-Agent': `amicus/${require('../../package.json').version}` },
+    });
+  } catch (err) {
+    return emptyOutcome({ reason: 'exception', detail: err.message });
+  }
+  if (!res || !res.ok) {
+    return emptyOutcome((res && res.failure) || { reason: 'exception', detail: 'no result' });
+  }
+  const limits = limitsFromModelsDev(res.json);
+  // A 200 that parses but carries no recognised vendor limits — `{}`, an error
+  // object, a reshaped api.json — would otherwise persist as a SUCCESSFUL
+  // enrichment with every candidate row `unknown`, silently leaving direct-provider
+  // ceilings unfilled and outputBudget unable to clamp them (council #230 C1).
+  // It is a failure, and the rows are not touched.
+  if (limits.size === 0) {
+    return emptyOutcome({ reason: 'bad-shape', detail: 'no recognised vendor limits in api.json' });
+  }
+  return { source: 'models.dev', failure: null, skipped: null, ...fillCeilings(rows, limits) };
+}
+
+// `enrichCeilings` — the entry point — is first so the generated architecture
+// map, which lists a module's first five exports, actually names it.
+module.exports = {
+  enrichCeilings, fillCeilings, needsFillCount, limitsFromModelsDev, emptyOutcome,
+  MODELS_DEV_URL, MODELS_DEV_TIMEOUT_MS,
+};

package/src/utils/model-fetcher.js

@@ -5,7 +5,7 @@
  * Uses the same HTTPS pattern as api-key-store.js validateApiKey().
  */
 
-const https = require('https');
+const { httpGetText } = require('./http-get');
 
 /**
  * Hardcoded Anthropic floor: the anthropic/ rows a KEYLESS user (or a
@@ -64,6 +64,9 @@ const PROVIDER_FETCH_CONFIG = {
         id: `google/${m.name.replace('models/', '')}`,
         name: m.displayName || m.name.replace('models/', ''),
         contextLength: m.inputTokenLimit ?? null,
+        // #218 P3: Google's ListModels publishes the ceiling first-party; models.dev fills only
+        // what the provider left empty or unusable.
+        maxOutputTokens: m.outputTokenLimit ?? null,
         pricing: null
       }));
     }
@@ -148,43 +151,16 @@ function fetchModelsFromProvider(provider, key) {
  * @param {string} key - API key
  * @returns {Promise<{rows: Array, failure: {reason: string, status?: number, detail?: string}|null}>}
  */
-function fetchViaConfigDetailed(provider, key) {
+async function fetchViaConfigDetailed(provider, key) {
   const config = PROVIDER_FETCH_CONFIG[provider];
   const url = config.buildUrl ? config.buildUrl(key) : config.url;
-  const headers = config.authHeader(key);
-
-  return new Promise((resolve) => {
-    let chunks = '';
-    const ok = (rows) => resolve({ rows, failure: null });
-    const fail = (failure) => resolve({ rows: [], failure });
-
-    const timer = setTimeout(() => {
-      req.destroy();
-      fail({ reason: 'timeout', detail: `no response within ${FETCH_TIMEOUT_MS}ms` });
-    }, FETCH_TIMEOUT_MS);
-
-    const req = https.get(url, { headers }, (res) => {
-      if (res.statusCode !== 200) {
-        clearTimeout(timer);
-        res.on('data', () => {});
-        res.on('end', () => fail({ reason: 'http-status', status: res.statusCode }));
-        return;
-      }
-      res.on('data', (chunk) => { chunks += chunk; });
-      res.on('end', () => {
-        clearTimeout(timer);
-        try {
-          ok(config.normalize(chunks));
-        } catch (err) {
-          fail({ reason: 'parse-error', detail: err.message });
-        }
-      });
-    });
-    req.on('error', (err) => {
-      clearTimeout(timer);
-      fail({ reason: 'network-error', detail: err.message });
-    });
-  });
+  const res = await httpGetText(url, { headers: config.authHeader(key), timeoutMs: FETCH_TIMEOUT_MS });
+  if (!res.ok) { return { rows: [], failure: res.failure }; }
+  try {
+    return { rows: config.normalize(res.body), failure: null };
+  } catch (err) {
+    return { rows: [], failure: { reason: 'parse-error', detail: err.message } };
+  }
 }
 
 /**

package/src/utils/model-output-limit.js

@@ -17,11 +17,13 @@
  * i.e. `ProviderTransform.maxOutputTokens(model) = Math.min(model.limit.output,
  * OUTPUT_TOKEN_MAX)`. Three consequences, each a trap:
  *
- *   1. Supplying the model's REAL ceiling is ARITHMETICALLY INERT. kimi-k3's
- *      true ceiling is 943,718 and Math.min(943718, 32000) is still 32000. Only
- *      a value BELOW 32000 changes the outbound request. The issue's headline
- *      framing ("a 32,000 reservation against a 943,718 ceiling is arbitrary")
- *      reads as though feeding the real ceiling would help. It would not.
+ *   1. Supplying the model's REAL ceiling through THIS DESCRIPTOR ALONE is
+ *      ARITHMETICALLY INERT. kimi-k3's true ceiling is 943,718 and
+ *      Math.min(943718, 32000) is still 32000. Through the descriptor only a
+ *      value BELOW OUTPUT_TOKEN_MAX changes the outbound request. Raising
+ *      OUTPUT_TOKEN_MAX itself is engine-output-flag.js's job (PR 2): with the
+ *      flag set to the same budget the two levers agree on min(budget, ceiling)
+ *      — measured, probe rows C2 and K6.
  *   2. `limit.context` is MANDATORY whenever `limit` is present. A `limit` with
  *      only `output` is a hard ConfigInvalidError — and it poisons the ENTIRE
  *      config for the server's lifetime, not just that model. Measured against
@@ -30,15 +32,21 @@
  *
  * WHAT THIS DOES NOT FIX. #218 conflates two modes that pull in OPPOSITE
  * directions on this one knob. Mode 1 (credit rejection) needs the reservation
- * LOWERED — that is what this module enables. Mode 2 (a leg spending its whole
- * allowance on reasoning and emitting 0-2 output tokens) would need it RAISED,
- * which the descriptor cannot do at all because of the Math.min; its real cause
- * is reasoning effort, a knob amicus already owns (`sidecar/fanout.js` →
- * `body.reasoning`). Lowering the budget makes those legs fail faster and
- * cheaper. It does not make them produce output. No claim is made that it does.
+ * LOWERED — this descriptor does that. Mode 2 (a leg spending its whole
+ * allowance on reasoning and emitting 0-2 output tokens) needs it RAISED, which
+ * this descriptor cannot do (the Math.min) and the engine flag can
+ * (engine-output-flag.js) — but its real cause is reasoning effort, which #218
+ * PR 4 now delivers: `--thinking` reaches the engine as its `variant` field, not
+ * the `reasoning` object the prompt API never read (F1), and is checked against
+ * the model's own declaration first — so on the one route where a variant moves
+ * the reservation the leg is refused, not silently overshot (M2: 24000 + 16000 =
+ * 40000; the fit that lands the sum on the budget is M17). Lowering the budget
+ * makes such a leg fail faster and cheaper; raising it gives the reasoning more
+ * room. Neither makes it produce output, and no claim is made that either does.
  *
  * POLICY: opt-in, no default change. With no configured budget every model is
- * still registered as `{}` — byte-identical to pre-#218 behaviour.
+ * still registered as `{}` and no engine flag is set — byte-identical to
+ * pre-#218 behaviour.
  */
 
 'use strict';
@@ -121,4 +129,4 @@ function computeModelLimit(row, budget) {
   return { context, output: Math.max(1, Math.min(ceiling, want)) };
 }
 
-module.exports = { normalizeOutputBudget, buildLimitLookup, computeModelLimit };
+module.exports = { normalizeOutputBudget, buildLimitLookup, computeModelLimit, positiveCount };

package/src/utils/output-length.js

@@ -0,0 +1,90 @@
+/**
+ * @module utils/output-length
+ * #218 PR 3: name the "Mode 2" death.
+ *
+ * THE PROBLEM. A council leg whose provider stopped for length before any
+ * answer text -- the whole max_tokens reservation went to reasoning (the #218
+ * ledger rows: 32000 reasoning, 0-2 output, $0.63 billed for nothing) -- came
+ * back `complete` with an empty summary and was announced as "the leg ended
+ * 'complete' with no usable output"; with VISIBLE reasoning it came back
+ * `complete` with its thinking promoted to the review and was adjudicated as one.
+ *
+ * WHAT THE ENGINE RECORDS (scripts/probe-max-tokens.js rows A/H1/L1-L4, engine
+ * 1.18.15): `finish: 'length'` on the assistant message on both provider
+ * families; a reasoning/output token split on OpenAI-compatible routes
+ * (L3: output = completion - reasoning) but NOT on the direct Anthropic route
+ * (L4: everything is `output`, reasoning 0); and, with visible reasoning, a
+ * `reasoning` part and no `text` part (L2/L4), which
+ * sidecar/conversation-mirror.js :: mirrorMessages promotes to `output` -- so
+ * `output` cannot be the test; the mirror records the last message's own facts
+ * and this module reads only those. No row carries an engine error for the stop.
+ *
+ * So the death is keyed on `finish` plus "no answer text arrived", never on a
+ * token count; the counts are reported, not decided on. Pure: no I/O, no clock.
+ * headless.js :: runHeadless calls both functions once, post-loop.
+ */
+'use strict';
+
+const {
+  outputTokenFlagValue, ENGINE_DEFAULT_OUTPUT_TOKENS, OUTPUT_TOKEN_FLAG, PLAIN_OUTPUT_TOKEN_FLAG,
+} = require('./engine-output-flag');
+
+/** The prefix a consumer can classify on, like `NO_OUTPUT_BACKSTOP:`. */
+const OUTPUT_LENGTH_PREFIX = 'OUTPUT_LENGTH:';
+
+/**
+ * Is this leg the Mode 2 death? The provider stopped for length AND the LAST
+ * assistant message carries no answer text: nothing at all (L1), or only
+ * reasoning (L2/L4). Decided per message, never on the session's accumulated
+ * output (council #232 r1 B2/D1). Named mutants (tests/utils/output-length.test.js):
+ * "NOTLENGTH" drops the finish check, "TEXTIGNORED" drops the text check.
+ * @param {{finish?: string|null, hasText?: boolean}} last the last assistant message's facts
+ * @returns {boolean}
+ */
+function isOutputLengthDeath({ finish, hasText }) {
+  return finish === 'length' && hasText !== true;
+}
+
+/**
+ * The reason string. Every clause is an observation: `finish` and the two
+ * counts are the engine's own record of the message; the budget clause is what
+ * the engine serving the leg was spawned with: the budget (`null` = unset,
+ * `undefined` = unknown — no handle value and config unreadable) or, when no
+ * budget was set, the ambient flag. The remedy names the one
+ * lever that exists today; PR 4 adds the effort lever. Named mutant
+ * "BUDGETUNSET": always print the unset clause.
+ * @param {{tokens?: {reasoning?: number, output?: number}|null,
+ *   budget?: number|null, reasoningOnly?: boolean,
+ *   ambientFlag?: string|null}} args `reasoningOnly` = the
+ *   message carried reasoning parts and no text -- L2/L4; `ambientFlag` = the
+ *   ambient `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` the engine was started with
+ *   when no budget was set (`null` when none, or when a budget overrode it);
+ *   named mutant "AMBIENTIGNORED".
+ * @returns {string}
+ */
+function formatOutputLengthReason({ tokens, budget, reasoningOnly, ambientFlag }) {
+  const t = tokens || {};
+  const count = (n) => (Number.isFinite(n) ? n : 0);
+  const streamed = reasoningOnly
+    ? 'only reasoning was streamed, no answer text'
+    : 'no answer text arrived';
+  // PLAIN_OUTPUT_TOKEN_FLAG is the one form measured to be honoured (C1, K5,
+  // K12); 64000abc and 0 fell back to 32000 (D1/D2); every other form is
+  // unmeasured, and the clause below says so -- shared with the doctor row
+  // (doctor-output-budget-check.js :: evaluateOutputBudget) so the gates agree.
+  const ambient = typeof ambientFlag === 'string' ? ambientFlag : null;
+  const knob = budget === undefined
+    ? 'outputBudget could not be read'
+    : budget !== null
+      ? `outputBudget is ${outputTokenFlagValue(budget)}`
+      : ambient === null
+        ? `outputBudget is unset — the engine's ${ENGINE_DEFAULT_OUTPUT_TOKENS} default reservation governs`
+        : PLAIN_OUTPUT_TOKEN_FLAG.test(ambient)
+          ? `outputBudget is unset — the ambient ${OUTPUT_TOKEN_FLAG}=${ambient} the engine was started with governs (each leg reserves min(${ambient}, the ceiling the engine's catalog knows for it))`
+          : `outputBudget is unset and the ambient ${OUTPUT_TOKEN_FLAG}=${ambient} the engine was started with 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`;
+  return `${OUTPUT_LENGTH_PREFIX} the provider stopped at the max_tokens reservation (finish 'length') and ${streamed} — `
+    + `${count(t.reasoning)} reasoning / ${count(t.output)} output tokens; ${knob} — `
+    + 'raise outputBudget in config.json (docs/configuration.md, Output budget)';
+}
+
+module.exports = { OUTPUT_LENGTH_PREFIX, isOutputLengthDeath, formatOutputLengthReason };

package/src/utils/result-schema.js

@@ -50,6 +50,7 @@ function durationBetween(createdAt, completedAt) {
  *   metadata.pack was recorded (solo session launched via --pack), sourced straight off
  *   `metadata` like `usage`/`opencodeSessionId` already are (no new function parameter needed).
  *   `tag` (v4.7 F8/D13) is additive the same way — present only when metadata.tag was recorded.
+ *   `finish` (#218 PR 3) likewise — the engine's finish reason for the leg's last assistant message. `variant` / `variantUnverified` (#218 PR 4) likewise — the effort level SENT, and whether the engine's catalogue knew the model when it was sent.
  */
 function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null, usage = null }) {
   const status = result ? statusFromResult(result) : (metadata.status || 'unknown');
@@ -80,6 +81,8 @@ function buildRunResult({ taskId, metadata = {}, result = null, summary = null,
     // (B3): emit-when-VALID via the shared predicate — `metadata` is read off
     // disk, so NaN/±Infinity/negatives/fractions all reach here. See ./ttft.js.
     ...(isMeasuredTtft(metadata.ttftMs) ? { ttftMs: metadata.ttftMs } : {}),
+    ...(typeof metadata.finish === 'string' ? { finish: metadata.finish } : {}), // #218 PR 3: emit-when-set (named mutant FINISHCOERCED)
+    ...(typeof metadata.variant === 'string' ? { variant: metadata.variant } : {}), ...(metadata.variantUnverified === true ? { variantUnverified: true } : {}), // #218 PR 4: emit-when-sent (named mutants VARIANTCOERCED / UNVERIFIEDCOERCED)
     usage: usage !== null ? usage : (metadata.usage || null),
     ...(metadata.pack ? { pack: metadata.pack } : {}),
     ...(metadata.tag ? { tag: metadata.tag } : {}),
@@ -184,10 +187,11 @@ const { buildRunResultFromSession, buildWaveResultFromSession } = require('./res
  * #13: lastRefreshAttempt/lastRefreshError are additive — null/null when the
  * last refresh attempt on record succeeded (or none has happened yet).
  * @param {{models: Array, fetchedAt: number|null, refreshed?: boolean, search?: string|null,
- *   lastRefreshAttempt?: number|null, lastRefreshError?: string|null}} opts
+ *   lastRefreshAttempt?: number|null, lastRefreshError?: string|null,
+ *   ceilingEnrichment?: object|null}} opts
  */
 function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
-  lastRefreshAttempt = null, lastRefreshError = null }) {
+  lastRefreshAttempt = null, lastRefreshError = null, ceilingEnrichment = null }) {
   return {
     schemaVersion: SCHEMA_VERSION,
     type: 'model-catalog',
@@ -198,6 +202,7 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
     models,
     lastRefreshAttempt: lastRefreshAttempt || null,
     lastRefreshError: lastRefreshError || null,
+    ceilingEnrichment: ceilingEnrichment || null, // #218 P3: additive within SCHEMA_VERSION
   };
 }
 

package/src/utils/spend-ledger.js

@@ -62,11 +62,13 @@ const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
  * @param {number} [opts.attempt] fallback attempt count (omitted if absent)
  * @param {string} [opts.substitutedFor] substituted model (omitted if absent)
  * @param {string} [opts.retryOfWaveId] wave id being retried (omitted if absent)
+ * @param {string} [opts.finish] the leg's finish reason (omitted if absent) — #218 PR 3: 'length' on a row is the Mode 2 receipt
+ * @param {string} [opts.variant] the effort level sent (omitted if absent) — #218 PR 4
  * @param {{dir?:string}} [ctx] test seam — dir overrides getConfigDir()
  */
 function appendSpend({ taskId, waveId, model, mode, usage,
   op, status, councilRunId, councilName, project, gateway, tag,
-  attempt, substitutedFor, retryOfWaveId }, ctx = {}) {
+  attempt, substitutedFor, retryOfWaveId, finish, variant }, ctx = {}) {
   if (!usage) { return; }
   try {
     const dir = ctx.dir || getConfigDir();
@@ -96,6 +98,8 @@ function appendSpend({ taskId, waveId, model, mode, usage,
     if (attempt !== undefined) { row.attempt = attempt; }
     if (substitutedFor !== undefined) { row.substitutedFor = substitutedFor; }
     if (retryOfWaveId !== undefined) { row.retryOfWaveId = retryOfWaveId; }
+    if (typeof finish === 'string') { row.finish = finish; }
+    if (typeof variant === 'string') { row.variant = variant; } // #218 PR 4: emit-when-sent (named mutant "VARIANTNULLED")
     // v4.4.1 CA-2: a leg whose OWN cost is known but which spawned a child
     // session the walk could not price writes a PRICED row — so `unpricedRows`
     // never catches it and `amicus spend` reads as a complete measurement while