amicus 4.9.3 → 4.9.5

package/src/sidecar/models-ceiling-line.js

@@ -0,0 +1,72 @@
+/**
+ * @module models-ceiling-line
+ * The one `Ceilings:` line `amicus models --refresh` prints (#218 P3).
+ *
+ * It is an honest report of where the direct-provider context/output ceilings
+ * came from, or why they did not come at all — filled, already complete, still
+ * missing a number, failed, or skipped.
+ *
+ * Extracted from `models.js` (council #230 r4) because that file sat at 298 of
+ * the 300-line budget and this round adds two more branches to the formatter.
+ * It owns the WORDING only: the outcome object it renders is built by
+ * `src/utils/model-ceilings-modelsdev.js` and persisted by
+ * `src/utils/model-catalog.js` as the cache document's `ceilingEnrichment`.
+ */
+
+'use strict';
+
+/**
+ * How a ceiling-enrichment failure is worded, keyed by its `failure.reason`
+ * (council #230 D4/C1). `http-status`, `parse-error`, `too-large` and
+ * `bad-shape` all mean models.dev ANSWERED; `exception` — and any reason a later
+ * failure invents — is a local bug, so it falls through to a neutral lead.
+ */
+const CEILING_FAILURE_LEAD = {
+  timeout: 'models.dev unreachable',
+  'network-error': 'models.dev unreachable',
+  'http-status': 'models.dev answered but could not be used',
+  'parse-error': 'models.dev answered but could not be used',
+  'too-large': 'models.dev answered but could not be used',
+  'bad-shape': 'models.dev answered but could not be used',
+};
+
+/**
+ * #218 P3: one honest line about where the direct-provider ceilings came from.
+ * @param {object|null} e the persisted `ceilingEnrichment` outcome
+ * @returns {string}
+ */
+function fmtCeilingLine(e) {
+  // Unreachable in production after #218 P3 (every successful refresh persists a
+  // ceilingEnrichment object); kept for a hand-built or pre-field cache doc.
+  if (!e) { return 'Ceilings: not attempted'; }
+  if (e.failure) {
+    const f = e.failure;
+    const why = f.reason + (f.status ? ` ${f.status}` : '') + (f.detail ? `: ${f.detail}` : '');
+    const lead = CEILING_FAILURE_LEAD[f.reason] || 'ceiling enrichment failed';
+    // #218 PR 4 (whole-branch review VCMD-4): the flag never reaches a direct openai row — M5/M13/M22, the same fact the disabled literal below states.
+    return `Ceilings: ${lead} (${why}); rows without a ceiling get an outputBudget through the engine flag alone, clamped only where the engine's own catalog knows the model; direct openai rows send no output reservation at all (#218 PR 4, M5/M13/M22)`;
+  }
+  // A skip is not a failure and not a fill: naming which one it was is the
+  // difference between "you turned this off" and "there was nothing to do".
+  if (e.skipped === 'disabled') {
+    // Named, not "direct routes": Google publishes its own ceiling first-party
+    // and OpenRouter rows keep OpenRouter's. Since PR 2 the budget still
+    // reaches the anthropic/deepseek rows through the engine flag, clamped by
+    // the engine's own catalog (probe K5/K12); it never reaches a direct
+    // openai row at all (#218 PR 4, M5/M13/M22).
+    return 'Ceilings: models.dev lookup disabled (modelsDevCeilings: false); anthropic/deepseek direct rows carry no ceiling here and are clamped by the engine\'s own catalog instead; direct openai rows send no output reservation at all (#218 PR 4) (Google publishes its own ceiling and OpenRouter rows keep OpenRouter\'s)';
+  }
+  if (e.skipped === 'nothing-to-fill') {
+    // NOT "every row": routers, local rows and malformed rows are not
+    // candidates and are never asked about (council #230 C2).
+    return 'Ceilings: nothing to fill (no candidate row is missing a number)';
+  }
+  // `?? 0`: a hand-built or pre-field cache doc can carry a partial object, and
+  // `undefined already complete` would be a worse lie than a zero. `stillMissing`
+  // deliberately overlaps the other counters — it is the STATE the pass left,
+  // and it is the number that says whether outputBudget can clamp those rows.
+  return `Ceilings: ${e.filled ?? 0} rows filled from models.dev (${e.alreadyKnown ?? 0} already complete, ` +
+    `${e.unknown ?? 0} unknown to models.dev, ${e.stillMissing ?? 0} still missing a number)`;
+}
+
+module.exports = { fmtCeilingLine };

package/src/sidecar/models.js

@@ -22,6 +22,7 @@ const { pickCurrent } = require('../utils/quick-picks');
 const { probeStoredAliases, selectStoredAliases } = require('./models-probe');
 const { DEFAULT_MAX_LEGS } = require('./fanout-validate');
 const { fmtRow, fmtGatewayFinding, fmtProbeLine, fmtProviderFailure } = require('./models-render');
+const { fmtCeilingLine } = require('./models-ceiling-line');
 
 const CHECK_EXIT_CAP = 100;
 
@@ -87,7 +88,7 @@ function fmtLiveSkipped(reason) {
 
 async function runRefresh(args) {
   const models = await refreshCatalog();
-  const { fetchedAt, lastRefreshAttempt, lastRefreshError } = await getCatalogInfo({ maxAgeMs: Number.POSITIVE_INFINITY });
+  const { fetchedAt, lastRefreshAttempt, lastRefreshError, ceilingEnrichment } = await getCatalogInfo({ maxAgeMs: Number.POSITIVE_INFINITY });
   // --refresh short-circuits --check below (args.check is guaranteed true here) — must announce, not silently skip.
   if (args.live) {
     const line = fmtLiveSkipped('refresh-precedes-check');
@@ -95,7 +96,7 @@ async function runRefresh(args) {
   }
   if (args.json) {
     process.stdout.write(JSON.stringify(buildCatalogDoc({
-      models, fetchedAt, refreshed: true, lastRefreshAttempt, lastRefreshError
+      models, fetchedAt, refreshed: true, lastRefreshAttempt, lastRefreshError, ceilingEnrichment
     }), null, 2) + '\n');
     return models.length === 0 && !fetchedAt ? 1 : 0;
   }
@@ -112,6 +113,7 @@ async function runRefresh(args) {
     return 1; // no cache at all: a real failure
   }
   process.stdout.write(`Refreshed catalog: ${models.length} models.\n`);
+  process.stdout.write(fmtCeilingLine(ceilingEnrichment) + '\n');
   process.stdout.write(`Cache: ${catalogPath()}\n`);
   return 0;
 }

package/src/sidecar/reopen-notices.js

@@ -0,0 +1,97 @@
+/**
+ * @module reopen-notices
+ * The stderr Notice a reopen owes the user for the effort level it does NOT carry (#218 PR 4, council #235 r5 J1/A3).
+ * A session started with `--thinking <level>` sends no variant on any resumed or
+ * continued leg, and since council #235 r2 both commands REJECT the flag, so the
+ * user cannot ask for one there either. Level inheritance was scoped out of this PR
+ * deliberately and stays out (filed, not built) — but the silence is the defect: it
+ * is the same mid-conversation degrade this release cites against 4.9.3, and the
+ * project's rule is that a level which will not take effect says so. Named mutants
+ * "RESUMELEVELSILENT" / "CONTINUELEVELSILENT" (tests/sidecar/reopen-thinking-notice.test.js):
+ * drop the call at either reopen site.
+ *
+ * Notices go to STDERR only — stdout carries the `--json` run document and the
+ * fold summary, and nothing here may perturb either (same rule as the unverified
+ * note in src/headless.js and src/sidecar/interactive.js).
+ */
+
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
+/** Longest LEVEL echoed from on-disk metadata into a one-line Notice — a level is one word. */
+const MAX_LEVEL_CHARS = 40;
+/**
+ * Longest TASK ID echoed. It is not an attacker-shaped fragment: `validators.js ::
+ * TASK_ID_PATTERN` is `/^[a-zA-Z0-9_-]{1,64}$/`, which already excludes every character the
+ * sanitizer strips — so the cap is what a VALID id can be. Capping it at the LEVEL's 40
+ * named a session that does not exist (council #235 r5 wave 6 repair).
+ */
+const MAX_TASK_ID_CHARS = 64;
+
+/**
+ * Collapse an on-disk fragment to one safe line.
+ * metadata.json is a FILE — a hand-edited or corrupted `thinking` value must not be
+ * able to forge a second `Notice:` line or smuggle control characters into a terminal
+ * (the hazard src/utils/alias-shadow.js :: safeFragment was written against).
+ *
+ * The SANITIZING is the house sanitizer's: `utils/text-sanitize.js :: collapseExcerpt` is the
+ * only one ("a second implementation would be a second set of holes", and the holes are the
+ * point — ANSI sequences and the PRINTABLE-range bidi controls are classes a private
+ * control-character regex cannot see, and this module quotes both straight out of a file).
+ * The fence/tag defang here is ADDITIVE and runs BEFORE that pass, so the house whitespace
+ * collapse and cap still govern the result: it adds a class, it never replaces one. Same
+ * shape as src/utils/alias-shadow.js :: safeFragment (council #235 r5 wave 6 repair).
+ * @param {unknown} value
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function safeFragment(value, maxChars) {
+  return collapseExcerpt(String(value).replace(/[`<>]/g, ' '), maxChars);
+}
+
+/**
+ * The value 4.9.3 and earlier stamped on EVERY session's metadata whether or not the flag was
+ * typed — and never sent (probe F1). It is the one recorded level whose provenance is unknowable
+ * from disk, so the line SAYS that rather than reporting it as something the user asked for.
+ */
+const LEGACY_UNCONDITIONAL_STAMP = 'medium';
+
+/**
+ * The Notice line for a reopen that drops the session's recorded effort level, or null.
+ * Null whenever the session records no level — nothing was asked for, so nothing is dropped.
+ *
+ * It reports what the metadata RECORDS, not what was typed (council #235 r5 wave 6 repair).
+ * Those are not the same proposition: 4.9.3 and earlier wrote `thinking: 'medium'` on every
+ * session, flag or no flag, so the entire on-disk session history at upgrade time reaches this
+ * line carrying a level nobody requested — and for those legs nothing degraded, because that
+ * `medium` was never sent either. Nothing on disk tells the two apart (the same reason this
+ * release refuses a pack migration), so the line states the record and names the ambiguity.
+ * @param {{taskId: string, level: unknown, kind: 'resume'|'continue'}} a
+ * @returns {string|null}
+ */
+function formatDroppedLevelNotice({ taskId, level, kind }) {
+  if (typeof level !== 'string') { return null; }
+  const shown = safeFragment(level, MAX_LEVEL_CHARS);
+  if (!shown) { return null; }
+  // Named mutant "NOTICECLAIMSINTENT": say "was started with" again, or drop this clause.
+  const provenance = shown === LEGACY_UNCONDITIONAL_STAMP
+    ? ' (4.9.3 and earlier recorded medium on every session, typed or not, and never sent it)'
+    : '';
+  const what = kind === 'continue'
+    ? 'this continuation opens a NEW session and sends no effort level, so it runs at the provider\'s default — a level belongs on the `start` that opens a session and is not carried across a reopen'
+    : 'this resumed leg sends no effort level and runs at the provider\'s default — a level is not carried across a reopen';
+  return `Notice: session ${safeFragment(taskId, MAX_TASK_ID_CHARS)} records --thinking ${shown}${provenance}; ${what}`;
+}
+
+/**
+ * Write that Notice to stderr when the session recorded a level. No-op otherwise.
+ * @param {object} metadata - the session metadata whose `thinking` is read (resume: the session's own; continue: the PARENT's)
+ * @param {{taskId: string, kind: 'resume'|'continue'}} a
+ * @returns {string|null} the line written, or null when nothing was written
+ */
+function noticeDroppedLevel(metadata, { taskId, kind }) {
+  const note = formatDroppedLevelNotice({ taskId, level: metadata && metadata.thinking, kind });
+  if (note) { process.stderr.write(`${note}\n`); }
+  return note;
+}
+
+module.exports = { formatDroppedLevelNotice, noticeDroppedLevel };

package/src/sidecar/reopen-spend.js

@@ -23,8 +23,9 @@ function finalizeSpendForReopen({ taskId, model, mode, op, result, status, proje
       const { gatewayOf } = require('../utils/gateway-router');
       const gateway = metadata.gateway || gatewayOf(model);
       // v4.7.1 Task 7 D16: null-not-absent, the OPPOSITE convention from
-      // metadata.tag's absent-not-null (D13) — same `|| null` idiom as start.js:237.
-      appendSpend({ taskId, model, mode, usage, op, status, project, gateway, tag: metadata.tag || null }, ctx);
+      // metadata.tag's absent-not-null (D13) — same `|| null` idiom as start.js:240.
+      // #218 PR 3/PR 4: `finish` and `variant` are the OPPOSITE — absent-not-null: appendSpend writes each key only when it is a string. Named mutant "SOLOROWNOVARIANT" (tests/continue-resume-spend.test.js): drop `variant`.
+      appendSpend({ taskId, model, mode, usage, op, status, project, gateway, tag: metadata.tag || null, finish: result && result.finish, variant: result && result.variant }, ctx);
     } catch { /* best-effort */ }
   }
   return { usage };

package/src/sidecar/resume.js

@@ -16,6 +16,7 @@ const {
   checkSessionLiveness
 } = require('./session-utils');
 const { acquireLock, releaseLock } = require('../utils/session-lock');
+const { noticeDroppedLevel } = require('./reopen-notices');
 const { runHeadless } = require('../headless');
 const { extractNonceFromText, generateFoldNonce, stripFoldMarkers } = require('../utils/fold-marker');
 const { logger } = require('../utils/logger');
@@ -41,7 +42,8 @@ function loadInitialContext(sessionDir) {
 /** Check for file drift - files that were read may have changed */
 function checkFileDrift(metadata, project) {
   const filesRead = metadata.filesRead || [];
-  const lastActivity = metadata.completedAt || metadata.createdAt;
+  // council #235 r5 (J2/A4): the previous attempt's terminal timestamps are all deleted on every running write (updateSessionStatus below), so this — their one legitimate reader — falls back through them. `abortedAt` is a terminal stamp of that attempt and later than its start, so it is read first (wave 6 repair); `resumedAt` is when a crashed attempt STARTED, strictly more accurate than the previous attempt's completion. Named mutants "DRIFTNORESUMEDAT" / "DRIFTNOABORTEDAT": drop either middle term.
+  const lastActivity = metadata.completedAt || metadata.abortedAt || metadata.resumedAt || metadata.createdAt;
   const lastActivityTime = new Date(lastActivity).getTime();
   const changedFiles = [];
 
@@ -112,6 +114,13 @@ function updateSessionStatus(sessionDir, status) {
   meta.status = status;
   if (status === 'running') {
     meta.resumedAt = new Date().toISOString();
+    // #218 PR 4 whole-branch review (REC-3): the per-attempt fields are this attempt's to stamp
+    // — an abort or crash of the resumed run must not ship the previous attempt's as its own
+    // (the terminal writers preserve every key they do not set). Named mutant
+    // "RESUMESTALEVARIANT" (tests/sidecar/resume.test.js): drop the three deletes.
+    // council #235 r5 (J2/A4): `reason` and the terminal timestamps are stamped ONLY by a terminal writer, so an attempt that never reaches one must not inherit the previous attempt's — a resume that crashes mid-attempt used to leave `status: 'running'` beside the last failure's reason and completion time, and both are read (src/utils/result-schema.js reports `metadata.reason` for every non-complete status and `completedAt || abortedAt` as the end; the MCP server prints the reason and adds `crashedAt` to that chain). ALL THREE timestamps go (wave 6 repair): `abortedAt` is the one an `amicus abort` writes and `completedAt` is never written on that path, so clearing only `completedAt` left the defect live on the commonest precursor to a resume — and, for an attempt that stamped both, made the reported end fall through to the OLDER one. Named mutants "RESUMESTALEREASON" (drop `reason`/`completedAt`) and "RESUMESTALEABORTEDAT" (drop `abortedAt`/`crashedAt`).
+    delete meta.finish; delete meta.variant; delete meta.variantUnverified;
+    delete meta.reason; delete meta.completedAt; delete meta.abortedAt; delete meta.crashedAt;
   }
   writeFileAtomic(metaPath, JSON.stringify(meta, null, 2));
   return meta;
@@ -135,6 +144,7 @@ async function resumeSidecar(options) {
 
   // Load previous session data
   const metadata = loadSessionMetadata(sessionDir);
+  noticeDroppedLevel(metadata, { taskId, kind: 'resume' }); // council #235 r5 (J1/A3): this leg sends no variant and `resume` rejects --thinking, so a session started with a level silently degrades to the provider's default — the very degrade this release cites against 4.9.3. Inheritance stays filed, not built; the silence does not. Named mutant "RESUMELEVELSILENT" (tests/sidecar/reopen-thinking-notice.test.js).
   const systemPrompt = loadInitialContext(sessionDir);
 
   // Dead-process detection: log if the previous process is no longer alive
@@ -242,11 +252,14 @@ async function resumeSidecar(options) {
     if (terminal.status === 'error') {
       updatedMetadata.status = 'error';
       updatedMetadata.reason = (result && result.error) ? String(result.error) : 'Incomplete';
+      if (result && typeof result.finish === 'string') { updatedMetadata.finish = result.finish; } else { delete updatedMetadata.finish; } // #218 PR 3: emit-when-set; a stale one is removed (council #232 r1 B1)
+      if (result && typeof result.variant === 'string') { updatedMetadata.variant = result.variant; } else { delete updatedMetadata.variant; } // #218 PR 4: same rule as finish (named mutant "RESUMEERRORNOVARIANT", tests/continue-resume-spend.test.js)
+      if (result && result.variantUnverified === true) { updatedMetadata.variantUnverified = true; } else { delete updatedMetadata.variantUnverified; }
       updatedMetadata.completedAt = new Date().toISOString();
       writeFileAtomic(metaPath, JSON.stringify(updatedMetadata, null, 2), { mode: 0o600 });
       logger.error('Resume completed with error', { taskId, error: updatedMetadata.reason });
     } else {
-      finalizeSession(sessionDir, summary, project, updatedMetadata, { quietStdout: json, status: terminal.status });
+      finalizeSession(sessionDir, summary, project, updatedMetadata, { quietStdout: json, status: terminal.status, finish: result && result.finish, variant: result && result.variant, variantUnverified: result && result.variantUnverified }); // named mutant "RESUMEVARIANTDROPPED" (tests/continue-resume-spend.test.js)
     }
     // v4.3: attribute resume spend (C9/E4). Reload metadata, write usage + append
     // a ledger row (status: statusFromResult, matching start.js — not terminal.status).

package/src/sidecar/session-finalize.js

@@ -51,6 +51,9 @@ function finalizeHeadlessResult(sessionDir, result, project, metadata) {
     fs.writeFileSync(SessionPaths.summaryFile(sessionDir), result && result.summary ? result.summary : '', { mode: 0o600 });
     metadata.status = 'error';
     metadata.reason = (result && result.error) ? String(result.error) : 'Incomplete';
+    if (result && typeof result.finish === 'string') { metadata.finish = result.finish; } else { delete metadata.finish; } // #218 PR 3: emit-when-set; a stale one is removed (council #232 r1 B1)
+    if (result && typeof result.variant === 'string') { metadata.variant = result.variant; } else { delete metadata.variant; } // #218 PR 4: same rule as finish (named mutant "SHAREDNOVARIANT", tests/shared-server-finalize.test.js)
+    if (result && result.variantUnverified === true) { metadata.variantUnverified = true; } else { delete metadata.variantUnverified; }
     metadata.completedAt = new Date().toISOString();
     writeFileAtomic(
       path.join(sessionDir, 'metadata.json'),
@@ -61,7 +64,7 @@ function finalizeHeadlessResult(sessionDir, result, project, metadata) {
   }
   // complete / timed-out / aborted: persist the (possibly partial) summary with
   // the resolved status. Explicit status means the #36 guard won't re-classify.
-  finalizeSession(sessionDir, (result && result.summary) || '', project, metadata, { status: terminal.status });
+  finalizeSession(sessionDir, (result && result.summary) || '', project, metadata, { status: terminal.status, finish: result && result.finish, variant: result && result.variant, variantUnverified: result && result.variantUnverified });
 }
 
 module.exports = { resolveTerminalState, finalizeHeadlessResult };

package/src/sidecar/session-utils.js

@@ -70,7 +70,7 @@ function saveInitialContext(sessionDir, systemPrompt, userMessage) {
   fs.writeFileSync(SessionPaths.contextFile(sessionDir), content, { mode: 0o600 });
 }
 
-/** Finalize session - detect conflicts, save summary, update metadata */
+/** Finalize session - detect conflicts, save summary, update metadata. opts.finish (#218 PR 3) stamps metadata.finish when set and REMOVES a prior one otherwise; opts.variant / opts.variantUnverified (#218 PR 4) follow the same rule — a resumed run reuses the same metadata and must not inherit the last attempt's finish (council #232 r1 B1). */
 function finalizeSession(sessionDir, summary, project, metadata, opts = {}) {
   const metaPath = SessionPaths.metadataFile(sessionDir);
 
@@ -102,6 +102,10 @@ function finalizeSession(sessionDir, summary, project, metadata, opts = {}) {
   // summary must never silently default to 'complete' — that hid errored/empty
   // shared-server runs behind a 0-byte summary and a false success.
   const hasSummary = typeof summary === 'string' && summary.trim().length > 0;
+  if (typeof opts.finish === 'string') { metadata.finish = opts.finish; } else { delete metadata.finish; }
+  // #218 PR 4: the effort level SENT and whether the engine's catalogue knew the model — the same emit-when-set / delete-when-absent rule as finish. Named mutants "SOLOVARIANTDROPPED" / "STALEVARIANT" (tests/sidecar/session-utils.test.js).
+  if (typeof opts.variant === 'string') { metadata.variant = opts.variant; } else { delete metadata.variant; }
+  if (opts.variantUnverified === true) { metadata.variantUnverified = true; } else { delete metadata.variantUnverified; }
   metadata.status = opts.status || (hasSummary ? 'complete' : 'error');
   metadata.completedAt = new Date().toISOString();
   writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });

package/src/sidecar/start-metadata.js

@@ -42,7 +42,7 @@ function createSessionMetadata(taskId, project, options) {
     briefing: effectiveBriefing,
     mode: isHeadless ? 'headless' : 'interactive',
     agent: agent || (isHeadless ? 'build' : 'chat'),
-    thinking: thinking || 'medium',
+    ...(thinking ? { thinking } : {}), // #218 PR 4: emit-when-requested — 'medium' was never sent (probe F1), so a run with no --thinking runs at the provider's default and records none (named mutant "MEDIUMDEFAULT")
     status: 'running',
     pid: existing.pid || process.pid,
     createdAt: existing.createdAt || new Date().toISOString(),

package/src/sidecar/start.js

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

package/src/sidecar/unzip.js

@@ -17,6 +17,8 @@
  *      the exact electron zip the field box choked on.
  *   3. Only report success when files actually landed on disk. The electron
  *      exe-stat verify stays upstream (electron-quarantine.verifyExtractOutcome).
+ * Layer 2 has ONE exception: a path-traversal REFUSAL is terminal and is never
+ * retried natively (UNSAFE_PATTERNS below).
  *
  * Everything network/spawn/timer-facing is dependency-INJECTABLE so tests never
  * hit the real clock, spawn a real process, or extract a real binary.
@@ -28,6 +30,32 @@ const path = require('path');
 const fsDefault = require('fs');
 const { spawnSync } = require('child_process');
 
+/**
+ * A SECURITY REFUSAL IS A REFUSAL, NOT A RETRY (M9).
+ *
+ * Strategy 1 used to collapse a stall, a plain throw, and extract-zip's / yauzl's
+ * own path-traversal refusals into ONE branch that cleans the directory and re-runs
+ * the IDENTICAL archive through OS extractors amicus does not control — laundering
+ * a "this archive tried to escape its directory" into an unsupervised retry.
+ *
+ * These four strings are verified against the installed versions:
+ *   extract-zip@2.0.1 raises `Out of bound path "<dir>" found while processing file <n>`
+ *   yauzl@2.10.0 validateFileName returns the other three, raised as new Error(msg).
+ * NOTE: with strictFileNames unset (extract-zip's default) yauzl rewrites
+ * backslashes before validating, so `invalid characters in fileName: ` is not
+ * reachable through extract-zip today. Classified anyway — it costs one line and
+ * yauzl's defaults can change.
+ *
+ * DELIBERATELY NARROW. A stall must still fall back, or the Node-24 workaround
+ * this whole module exists for is destroyed.
+ */
+const UNSAFE_PATTERNS = [
+  /^Out of bound path /,
+  /^absolute path: /,
+  /^invalid relative path: /,
+  /^invalid characters in fileName: /,
+];
+
 // No-progress window: if extract-zip reports no new entry for this long AND has
 // not settled, treat it as the silent stall. Reset on every onEntry so a slow-
 // but-progressing extract is never falsely aborted.
@@ -162,6 +190,8 @@ function runExtractZipBounded({ zip, dir, onEntry, extractZip, idleMs, maxMs, se
  * @param {object}   [opts.deps] injected { fs, extractZip, spawn, setTimeout, clearTimeout, log }
  * @returns {Promise<{strategy:string, fallback?:boolean, extractZipReason?:string}>}
  * @throws {Error} code 'UNZIP_ALL_FAILED' when no strategy produced files.
+ * @throws {Error} code 'UNZIP_UNSAFE_ARCHIVE' when the archive was REFUSED for a
+ *   path-traversal attempt — terminal, with no native retry (see UNSAFE_PATTERNS).
  */
 async function robustExtract(zip, opts = {}) {
   const {
@@ -202,6 +232,16 @@ async function robustExtract(zip, opts = {}) {
     return { strategy: 'extract-zip' };
   }
 
+  // TERMINAL: the archive was REFUSED for trying to write outside `dir`. Never
+  // cleanDir (the partial output is evidence), never fall back — handing the same
+  // archive to tar/Expand-Archive would ask a tool with no such check to do what
+  // extract-zip just declined to.
+  if (!z.ok && UNSAFE_PATTERNS.some((p) => p.test(z.reason || ''))) {
+    const err = new Error(`refusing to extract ${zip}: ${z.reason}`);
+    err.code = 'UNZIP_UNSAFE_ARCHIVE';
+    throw err;
+  }
+
   // extract-zip stalled / threw / produced nothing → clean partial output, go native.
   const zipReason = z.ok ? 'extract-zip produced no files' : z.reason;
   cleanDir(fs, dir);

package/src/utils/config.js

@@ -340,8 +340,13 @@ const LOCAL_REQUEST_TIMEOUT_MS = 300000;
  * serve (fixed in v4.1.2). Aliases the user has overridden fall back to the
  * prefix form, since no authored gateway route describes them.
  * @param {string[]} [resolvedRoutes] executable model id(s) actually launched
+ * @param {number|null} [outputBudget] the budget to clamp with. `undefined` (every
+ *   caller but startServer) reads config here; `null` means unset. #218 PR 3:
+ *   opencode-client.js :: startServer reads config ONCE and hands the same value
+ *   to this descriptor and to the engine flag, so a config write between two
+ *   reads can no longer split the levers. Named mutant "PARAMIGNORED".
  * @returns {object} e.g. { openrouter: { models: { "x-ai/grok-4.3": {}, ... } } } */
-function buildProviderModels(resolvedRoutes = []) {
+function buildProviderModels(resolvedRoutes = [], outputBudget) {
   const aliases = getEffectiveAliases();
   const providers = {};
 
@@ -353,7 +358,7 @@ function buildProviderModels(resolvedRoutes = []) {
   // ConfigInvalidError that poisons the whole config, not a per-model degrade.
   const { normalizeOutputBudget, buildLimitLookup, computeModelLimit } =
     require('./model-output-limit');
-  const budget = normalizeOutputBudget(getOutputBudget());
+  const budget = normalizeOutputBudget(outputBudget === undefined ? getOutputBudget() : outputBudget);
   let limits = new Map();
   if (budget !== null) {
     try {
@@ -382,6 +387,20 @@ function buildProviderModels(resolvedRoutes = []) {
     if (!Object.prototype.hasOwnProperty.call(providers, providerID)) {
       providers[providerID] = { models: {} };
     }
+    // #218 PR 2: direct `anthropic/*` is no longer held out (council #230 A1
+    // held it out until descriptor x thinking-budget was measured). Measured,
+    // probe rows K1/K2/K3/K4/K9/K10: the descriptor lowers the reservation on
+    // that route exactly as on OpenRouter (K1: 8000); a thinking variant's
+    // budget is ADDED on top of it (K2: 8000 + 16000 = 24000); and the sum is
+    // clamped to the model's real ceiling whatever the descriptor or flag said
+    // (K3/K4/K10: 64000 for haiku). No descriptor can push a thinking leg over
+    // the ceiling. #218 PR 4 now sends `--thinking` to the engine as its `variant`
+    // field, validated against the model's own declaration before any request,
+    // so these are the numbers a thinking leg now reserves: M2 is K2's
+    // arithmetic at the shipped budget (24000 + 16000 = 40000, refused rather
+    // than sent), and M17 is the fit (8000 + 16000 = 24000) that would need the
+    // variant's budget before the spawn.
+    // Named mutant "ANTHROPICHELDOUT" in tests/build-provider-models-output-limit.test.js.
     // #218: `{}` unless a budget is set AND the catalog knows both numbers.
     const limit = computeModelLimit(limits.get(fullModel), budget);
     providers[providerID].models[modelID] = limit ? { limit } : {};
@@ -615,17 +634,19 @@ function resolveCouncilMembers(name, catalog = []) {
 /**
  * #218: the configured per-leg output budget, or null when unset.
  *
- * OPT-IN BY DESIGN — unset means "register every model as `{}`", which is
- * pre-#218 behaviour exactly. Set it and each leg reserves min(budget, the
- * model's real ceiling) instead of opencode's fixed 32000 default.
+ * OPT-IN BY DESIGN — unset means "register every model as `{}` and set no
+ * engine flag", which is pre-#218 behaviour exactly. Set it and every leg
+ * reserves min(budget, the model's real ceiling) wherever a ceiling is known.
+ * This one value feeds BOTH levers so they can never disagree: the per-model
+ * `limit` descriptor (buildProviderModels, for routes the amicus catalog knows)
+ * and OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX (opencode-client.js :: startServer,
+ * set to the budget for every engine amicus starts and clamped by the engine's
+ * own catalog). Values above 32000 are LIVE since PR 2 (probe K6: 100000 on the
+ * wire); a model neither catalog knows receives the budget as-is (J2/K13).
  *
- * ⚠️ Values >= 32000 are ACCEPTED but INERT: opencode computes
- * `Math.min(limit.output, 32000)` (measured in the 1.18.15 binary), so the
- * reservation can only be lowered here, never raised. Raising it at all
- * requires OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX, a different lever.
- *
- * ⚠️ Requires a catalog refreshed since #218 added `maxOutputTokens`
- * (`amicus models --refresh`); older rows have no ceiling and stay `{}`.
+ * ⚠️ The descriptor half needs a catalog refreshed since #218 added
+ * `maxOutputTokens` (`amicus models --refresh`); the flag half needs nothing.
+ * `amicus doctor`'s `output-budget` row says which routes get which.
  *
  * @returns {number|null} positive integer, or null when unset/malformed
  */

package/src/utils/curated-models.js

@@ -98,14 +98,14 @@ const CARDLESS = [
   // (live smoke wave 47278069) — the entry was OpenRouter-only at authoring.
   { alias: 'fable', routes: { openrouter: 'openrouter/anthropic/claude-fable-5',
                               anthropic: 'anthropic/claude-fable-5' } },
-  // qwen/kimi refreshed 2026-08-26 (v4.9 W13): both were a model generation
-  // behind. These are the FALLBACK FLOOR — a caller or fork with no CI alias map
-  // resolves its whole bench through this table (see `inkling` below), while the
-  // owner's machine and .github/amicus-ci-aliases.json already ran the newer ids.
-  // Cardless entries have no `idPattern`, so `models --check` can only ask
-  // whether the OLD id still EXISTS — which is how a pin sits a generation back
-  // with every gate green (scripts/check-ci-alias-pins.js asks the other one).
-  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.8-max' } },
+  // qwen/kimi refreshed 2026-08-26 (v4.9 W13); qwen again 2026-09-05, when
+  // OpenRouter and models.dev dropped the un-dated `qwen3.8-max` for the dated
+  // `qwen3.8-max-0902` (the #218 PR 2 probe caught it: F4 went silent). These are
+  // the FALLBACK FLOOR — a fork with no CI alias map resolves its bench here; the
+  // owner's machine and .github/amicus-ci-aliases.json (qwen3.8-27b) run newer ids.
+  // Cardless entries have no `idPattern`, so `models --check` only asks whether the
+  // OLD id still EXISTS (scripts/check-ci-alias-pins.js asks the other question).
+  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.8-max-0902' } },
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
   { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
   { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-medium-3-5' } },

package/src/utils/degrade.js

@@ -17,6 +17,13 @@ const DEGRADE_CHANNELS = Object.freeze(new Set([
   'dropped-members', 'chair-skipped-cost-ceiling', 'chair-failed',
   'thin-cross-review', 'debate-degraded', 'inexact-under-ceiling',
   'stage1-retry',
+  // #218 PR 3: a Stage-1 review the provider cut at the max_tokens reservation
+  // (the leg's `finish` is 'length' and it still carried answer text). kind
+  // 'info' only -- the review is in the packet, nothing was lost, the exit code
+  // does not move; the chair just reads a review that ends where the
+  // reservation ended. A cut with NO answer text is a dead leg (leg.error
+  // starts `OUTPUT_LENGTH:`) and rides `dead-leg` like every other death.
+  'output-truncated',
   // v4.9 task mode: a task run writes no reliability-ledger rows — announced as kind:'info'.
   'ledger-skipped',
   // v4.8: the seat<->leg join failed. THREE shapes, one channel: a launched seat whose wave