amicus 4.9.3 → 4.9.5

package/skills/sidecar/SKILL.md

@@ -236,14 +236,7 @@ amicus start \
 - `--context-turns <N>`: Max conversation turns to include (default: 50)
 - `--context-since <duration>`: Time filter for context (e.g., `2h`, `30m`, `1d`). Overrides `--context-turns`.
 - `--context-max-tokens <N>`: Max context size (default: 80000)
-- `--thinking <level>`: Model thinking/reasoning effort level:
-  - `none` - No extended thinking
-  - `minimal` - Minimal thinking (may be adjusted if unsupported by model)
-  - `low` - Low thinking effort
-  - `medium` - Medium thinking effort (default)
-  - `high` - High thinking effort
-  - `xhigh` - Extra high thinking effort
-  Note: If the model doesn't support the specified level, it will be automatically adjusted.
+- `--thinking <level>`: Reasoning effort — `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (the levels the curated routes declare between them). Omit it for the provider's own default effort (nothing is sent then). A level the model does not declare is refused before anything is sent (`VARIANT_UNDECLARED`, naming the declared set); a declared level whose thinking budget would push the reservation over `outputBudget` on the direct Anthropic route is refused too (`VARIANT_OVER_BUDGET`); a model the engine's catalogue does not know in time is sent the level unverified (`variantUnverified: true` on the record). Nothing is adjusted.
 - `--summary-length <length>`: Summary verbosity:
   - `brief` - Concise summary
   - `normal` - Standard summary (default)

package/src/cli-handlers-doctor.js

@@ -14,6 +14,7 @@ const electronMcpCheck = require('./utils/doctor-electron-mcp-check');
 const localProvidersCheck = require('./utils/doctor-local-providers-check');
 // v4.6.2 PR1 (spec §4) — the 'anthropic-base-url' check body.
 const baseUrlCheck = require('./utils/doctor-base-url-check');
+const outputBudgetCheck = require('./utils/doctor-output-budget-check'); // #218 PR 2 — the 'output-budget' row.
 // B3 (council review of PR 198, issue 195) — the 'aliases' check body,
 // including its --fix repair of fabricated bare ids. Same split rationale.
 const aliasCheck = require('./utils/doctor-alias-check');
@@ -45,6 +46,7 @@ function realDeps() {
     resolveModel: () => require('./utils/config').resolveModel(),
     readCache: () => require('./utils/model-catalog').readCache(),
     collectAliasSources: () => require('./utils/alias-audit').collectAliasSources(),
+    readOutputBudgetRaw: () => (require('./utils/config').loadConfig() || {}).outputBudget, // #218 PR 2: as stored, so a malformed value is echoed
     findStaleAliases: (s, c) => require('./utils/alias-audit').findStaleAliases(s, c),
     findDriftedStoredAliases: (s, c) => require('./utils/alias-audit').findDriftedStoredAliases(s, c),
     // B3: the narrow fabricated-bare-id repair class (pure detection) + the
@@ -171,6 +173,7 @@ async function runDoctorChecks(depsOverride = {}) {
   // utils/doctor-alias-check.js for the check body and utils/alias-audit.js's
   // findFabricatedAliasRepairs for the detection rule.
   checks.push(guard('aliases', 'Model aliases', () => aliasCheck.evaluateAliasesCheck(d)));
+  checks.push(guard('output-budget', 'Output budget', () => outputBudgetCheck.evaluateOutputBudget(d))); // #218 PR 2
 
   checks.push(guard('anthropic-base-url', 'ANTHROPIC_BASE_URL',
     () => baseUrlCheck.evaluateAnthropicBaseUrl(d)));

package/src/cli-handlers-fanout.js

@@ -8,7 +8,7 @@
 
 'use strict';
 
-const { validateTaskId, validateTag } = require('./utils/validators');
+const { validateTaskId, validateTag, validateThinkingLevel } = require('./utils/validators');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { GATEWAY_MODES } = require('./utils/model-descriptor');
 const { applyTemplateForArgs } = require('./cli-template-args');
@@ -54,6 +54,15 @@ async function handleFanout(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
   }
 
+  // #218 PR 4 whole-branch review (VCMD-2): the same vocabulary check `start` runs in
+  // validateStartArgs (cli.js) — fanout never did, so a typo (or a pack's) reached sendPrompt:
+  // sent unverified to an unknown model, a per-leg VARIANT_UNDECLARED after the spawn on a
+  // known one. Named mutant "FANOUTTHINKINGUNCHECKED" (tests/fanout-cli.test.js): drop this block.
+  const thinkingCheck = validateThinkingLevel(args.thinking);
+  if (!thinkingCheck.valid) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: thinkingCheck.error }));
+  }
+
   const { resolvePromptSource } = require('./utils/prompt-source');
   let promptRes;
   if (args.prompt !== undefined || args['prompt-file'] !== undefined || args.template === undefined) {

package/src/cli-handlers-resume-continue.js

@@ -32,6 +32,21 @@ async function handleResume(args) {
       message: 'Error: --tag is not supported on resume — the tag is inherited from the parent session',
     }));
   }
+  // #218 PR 4, council #235 r1 (D6): the same silently-ignored-flag shape as --tag
+  // above. `--thinking` parses on every command because getKnownFlags()
+  // (utils/known-flags.js) scrapes the whole usage string and start's block declares
+  // it (cli.js), this handler never reads it, and validateStartArgs — PR 4's
+  // vocabulary check — runs only on `start` (cli-handlers-run.js), so even
+  // `--thinking bogus` used to exit 0 here having done nothing. Before PR 4 the level
+  // reached nothing on any path (probe F1) and the commands behaved alike by accident;
+  // it is the engine's `variant` on start/fanout now. Named mutant
+  // "RESUMETHINKINGSILENT" (tests/cli-handlers-resume-continue.test.js): drop this guard.
+  if (args.thinking !== undefined) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: --thinking is not supported on resume — the level belongs to the run that started the session, and resume reopens that session',
+    }));
+  }
   const taskId = requireValidTaskId(args, useJson, 'resume', 'Usage: amicus resume <task_id>');
   requireNoUiForJson(args, useJson);
 
@@ -71,6 +86,16 @@ async function handleContinue(args) {
       message: 'Error: --tag is not supported on continue — the tag is inherited from the parent session',
     }));
   }
+  // #218 PR 4, council #235 r1 (D6): same rationale as handleResume above — the flag
+  // parses here, is read by nobody, and is not even vocabulary-checked. A continuation
+  // is a NEW session, so a level for it belongs on the `start` that opens one. Named
+  // mutant "CONTINUETHINKINGSILENT" (tests/cli-handlers-resume-continue.test.js).
+  if (args.thinking !== undefined) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: --thinking is not supported on continue — the level belongs to the run that starts a session; use `amicus start --thinking <level>` to open one with a level',
+    }));
+  }
   const taskId = requireValidTaskId(args, useJson, 'continue', 'Usage: amicus continue <task_id> --prompt "..."');
 
   // BL-1: accept --prompt-file (XOR --prompt) so the MCP handler can pass a long

package/src/cli.js

@@ -326,16 +326,13 @@ function validateStartArgs(args) {
     return { valid: false, error: `Error: --summary-length must be one of: ${validSummaryLengths.join(', ')}` };
   }
 
-  // Validate thinking effort level (if provided), with model-specific support check
-  const thinkingCheck = validateThinkingLevel(args.thinking, args.model);
+  // Validate the thinking level's VOCABULARY (#218 PR 4). Whether the model
+  // declares it is checked against the engine's own catalogue at send time
+  // (opencode-client.js :: sendPrompt); nothing is adjusted here any more.
+  const thinkingCheck = validateThinkingLevel(args.thinking);
   if (!thinkingCheck.valid) {
     return thinkingCheck;
   }
-  // If model doesn't support the level, adjust it and warn
-  if (thinkingCheck.warning) {
-    logger.warn('Thinking level adjusted', { warning: thinkingCheck.warning, adjustedLevel: thinkingCheck.adjustedLevel });
-    args.thinking = thinkingCheck.adjustedLevel;
-  }
 
   // Validate API key is present for the model's provider
   const apiKeyCheck = validateApiKey(args.model);
@@ -444,7 +441,7 @@ Options for 'start':
   --context-since <duration>   Time filter (e.g., 2h). Overrides turns.
    --context-max-tokens <N>     Max context tokens (default: 80000)
    --summary-length <length>    Summary verbosity: brief, normal (default), verbose
-   --thinking <level>           Reasoning effort: none, minimal, low, medium, high, xhigh
+   --thinking <level>           Reasoning effort: none, minimal, low, medium, high, xhigh, max (omit for the provider's default)
    --mcp <spec>                 Add MCP server. Formats:
                                 - name=url (remote server)
                                 - name=command (local server)

package/src/council/briefings-chair.js

@@ -148,7 +148,7 @@ function seatKeyedOrder(order, orderSeats) {
  * changing it would move a shipped tally schema. These are three arrays each
  * with one consistently-typed field, not one polymorphic field. PR #189's
  * council raised it as D1 (major, CONTESTED a1/d1/n1); declined on that reading.
- * @param {{reviews: Array<{model: string, text: string, seat?: ?object}>,
+ * @param {{reviews: Array<{model: string, text: string, seat?: ?object, cut?: boolean}>,
  *   rankings: Array<{judge: string, seat?: ?string, order: Array<string|string[]>,
  *     orderSeats?: ?Array<?string|Array<?string>>}>,
  *   adjudications: Array<{findingId: string, judge: string, seat?: ?string, verdict: string}>,
@@ -182,7 +182,9 @@ function buildChairPacket({ reviews, rankings, adjudications, tierCounts, date,
   // construction — and the review projection that feeds site (1) applies that
   // same rule for a reason its own comment gives.
   const reviewBlocks = reviews
-    .map(r => `--- Review by ${displayName(r.seat) || r.model} ---\n${r.text}`).join('\n\n');
+    // #218 PR 3 (council #232 r2 B1): a cut review says so in its header, so the
+    // chair weighs it as partial. Named mutant "NOMARKER".
+    .map(r => `--- Review by ${displayName(r.seat) || r.model}${r.cut ? ' — CUT at its output reservation (the provider stopped for length; the text ends where the reservation ended)' : ''} ---\n${r.text}`).join('\n\n');
   const rankingLines = (rankings || [])
     .map(r => `${r.seat || r.judge}: ${JSON.stringify(seatKeyedOrder(r.order, r.orderSeats))}`)
     .join('\n');

package/src/council/run-assemble.js

@@ -254,14 +254,19 @@ function buildChairPacketFile({ runDir, reviews, claudeReview, tallyInput, recor
   const packet = buildChairPacket({
     // §4.4: the chair sees Claude's de-anonymized review like any other; it casts
     // no rankings/adjudications, so it appears ONLY as one more review block.
-    // The projection is DELIBERATE — it drops findings/conformance/role/leg; v4.8
+    // The projection is DELIBERATE — it drops findings/conformance/role/leg;
+    // `cut` (r2 B1) is the one leg fact forwarded, emit-when-cut. v4.8
     // SI-25 adds `seat`, ⚠️ EMIT-WHEN-DIFFERENT like rankings/adjudications above:
     // `r.model` is the leg's `modelInput || model`, which falls back to the RESOLVED
     // id, so an unconditional forward breaks §4.2 byte identity on a NO-TWIN bench.
     // Mutant: tests/council/chair-packet-seat-mutants.js :: HDRSEATFWD.
     // ⚠️ The Claude review keeps NO seat and renders `claude` via the fallback.
+    // #218 PR 3 (council #232 r2 B1): a review the provider cut at the output
+    // reservation is MARKED for the chair, emit-when-cut so an uncut bench's
+    // packet stays byte-identical. Named mutant "CUTDROPPED".
     reviews: reviews.map(r => ({ model: r.model, text: r.text,
-      ...(r.seat && r.seat.id !== r.seat.alias ? { seat: r.seat } : {}) }))
+      ...(r.seat && r.seat.id !== r.seat.alias ? { seat: r.seat } : {}),
+      ...(r.leg && r.leg.finish === 'length' ? { cut: true } : {}) }))
       .concat(claudeReview ? [{ model: 'claude', text: claudeReview.text }] : []),
     rankings: tallyInput.rankings,
     adjudications: tallyInput.adjudications,

package/src/council/run-retry-notes.js

@@ -179,5 +179,25 @@ function missingLegStillDeadNote(seat, ff, unit, counts) {
     data: { seat, status: null, reason: null, firstFailure: ff, retryWaveId: unit.waveId } };
 }
 
+/**
+ * #218 PR 3: a review that reached the packet but was cut at the reservation.
+ * `kind: 'info'` -- announced, never a loss (utils/degrade.js on the channel).
+ * The counts are the engine's own token record for the leg; the remedy names
+ * the one lever that exists today.
+ * @param {string} seat the alias every note renders — `materializeReviews` has
+ *   already resolved it (`leg.modelInput || leg.model`), so the caller passes
+ *   `m.modelInput` as-is
+ * @param {object} leg the leg run document (finish === 'length')
+ */
+function truncatedReviewNote(seat, leg) {
+  const t = (leg.usage && leg.usage.tokens) || {};
+  return { kind: 'info', channel: 'output-truncated',
+    what: `seat ${seat}'s review was cut at its output reservation`,
+    why: `the provider stopped for length (finish 'length') after ${t.reasoning || 0} reasoning / ${t.output || 0} output tokens; the review ends where the reservation ended`,
+    effect: 'The review is in the packet as far as it got, and its header in the chair packet says it was cut; nothing else changes',
+    remedy: 'raise outputBudget in config.json (docs/configuration.md, Output budget)',
+    data: { seat, finish: 'length', reasoningTokens: t.reasoning || 0, outputTokens: t.output || 0 } };
+}
+
 module.exports = { waveStillDeadNote, skippedWaveNote, srcLegStillDeadNote,
-  retryLegStillDeadNote, missingLegStillDeadNote };
+  retryLegStillDeadNote, missingLegStillDeadNote, truncatedReviewNote };

package/src/council/run-stages.js

@@ -27,7 +27,7 @@ const { launchStage1 } = require('./run-stage1-launch');
 const { buildRunStatsEntry } = require('./run-assemble');
 const { pushDeadSeatRows } = require('./run-stage1-rows');
 const { bindStage1Waves, orphanLegNote, missingSeatDeadWave } = require('./stage1-bind');
-const { skippedWaveNote } = require('./run-retry-notes');
+const { skippedWaveNote, truncatedReviewNote } = require('./run-retry-notes');
 // slug lives in ./seats (v4.8 PR1) so that module can stay require-free;
 // re-exported below — run-stages.test.js imports it from here.
 const { slug } = require('./seats');
@@ -139,6 +139,13 @@ async function runStage1(ctx) {
   // it is the twin clobber this PR removes (two healed twins, one file).
   const allSeatOf = new Map([...seatOf, ...retry.seatOf]);
   const materialized = materializeReviews(o.runDir, [...legs, ...retry.recoveredLegs], allSeatOf);
+  // #218 PR 3: a review the provider cut at the reservation still counts -- it
+  // is announced, not lost. Only MATERIALIZED legs qualify (a length-stopped
+  // leg with no answer text is a dead leg and never reaches this list); named
+  // mutants "DEADNOTED" (iterate `legs` instead) and "NONOTE" (drop the loop).
+  for (const m of materialized) {
+    if (m.leg && m.leg.finish === 'length') { ctx.degrade.note(truncatedReviewNote(m.modelInput, m.leg)); }
+  }
   const stillDeadLegs = [...retry.skippedDeadLegs, ...retry.stillDeadLegs];
   const stillDeadWaves = [...retry.skippedDeadWaves, ...retry.stillDeadWaves];
 

package/src/headless.js

@@ -259,6 +259,22 @@ function formatNoOutputBackstopReason({ ms, fromEnv, engineLogExcerpt, engineSke
   return `${quoted}${formatSkewSuffix(engineSkew)}${formatSessionStatusSuffix(sessionStatus)}`;
 }
 
+/**
+ * #218 PR 3: the budget for the OUTPUT_LENGTH reason string. The engine's own
+ * handle carries the value it was spawned with (opencode-client.js ::
+ * startServer, council #232 r1 B3) and wins; config is read only for a handle
+ * from outside amicus (a test seam or an older caller), and `undefined` when
+ * that read fails -- the string then says so rather than claiming "unset".
+ * `read` is a test seam (options._readOutputBudget).
+ * @param {{outputBudget?: number|null}} [server] the leg's server handle
+ * @param {() => (number|null)} [read]
+ * @returns {number|null|undefined}
+ */
+function readOutputBudgetSafe(server, read) {
+  if (server && Object.prototype.hasOwnProperty.call(server, 'outputBudget')) { return server.outputBudget; }
+  try { return (read || require('./utils/config').getOutputBudget)(); } catch { return undefined; }
+}
+
 /**
  * v4.9 W10 (#133 piece 2): the engine-log lookup, wrapped so it can never
  * become the failure it reports on. The resolver is already best-effort
@@ -349,8 +365,11 @@ async function waitForServer(client, checkHealthFn, maxAttempts = 30) {
  * @param {object} [options] - Additional options
  * @param {object} [options.mcp] - MCP server configurations
  * @param {string} [options.summaryLength='normal'] - Desired summary length
- * @param {object} [options.reasoning] - Reasoning/thinking configuration
- * @param {string} [options.reasoning.effort] - Effort level: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'none'
+ * @param {string} [options.variant] - #218 PR 4: the effort level, sent as the engine's `variant`
+ *   prompt field and validated by sendPrompt against the model's declaration; a refusal is thrown
+ *   before any request and becomes this leg's standard error result through the outer exception
+ *   handler below (zero spend, nothing polled). The result carries `variant` (emit-when-sent) and
+ *   `variantUnverified: true` when the engine's catalogue did not know the model in time.
  * @param {string} [options.nonce] - Per-run fold nonce (15b.3, #BL-7 residual). The
  *   PROMPT the caller built (prompt-builder.js buildPrompts) must have instructed the
  *   model with this SAME nonce — runHeadless only DETECTS, it never re-derives one from
@@ -372,7 +391,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     getSessionStatus
   } = require('./opencode-client');
 
-  const { reasoning } = options;
+  const { variant } = options;
   // 15b.3: never fall back to bare-marker detection — an omitted nonce still
   // gets ONE generated here so findTrailingFoldMarker always has something to
   // match, but since the prompt (built by the caller) never advertised THIS
@@ -635,9 +654,16 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     const agentConfig = mapAgentToOpenCode(agent || 'build');
     promptOptions.agent = agentConfig.agent;
 
-    // Add reasoning/thinking configuration if provided
-    if (reasoning) {
-      promptOptions.reasoning = reasoning;
+    // #218 PR 4: the effort level goes out as the engine's `variant` prompt field
+    // (probe F2), validated in sendPrompt against what the model declares; the
+    // budget the engine was spawned with rides the handle (readOutputBudgetSafe,
+    // PR 3) so the direct-Anthropic fit check (M2/M17) judges the same number the
+    // death report names. Named mutant "VARIANTNOTSENT" (tests/headless-variant.test.js).
+    const sendAbort = new AbortController();
+    if (variant) {
+      promptOptions.variant = variant;
+      promptOptions.outputBudget = readOutputBudgetSafe(server, options._readOutputBudget);
+      promptOptions.signal = sendAbort.signal; // #218 PR 4 whole-branch review (EP-2): see the backstop catch below
     }
 
     // v4.6.2 PR2 amendment (controller live smoke, field evidence): arm BEFORE
@@ -760,6 +786,11 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       // internally, so this is defensive belt-and-suspenders, not load-bearing
       // — verified empirically before relying on it).
       sendPromptPromise.catch(() => {});
+      // #218 PR 4 whole-branch review (EP-2): the send may still be INSIDE its declaration
+      // wait (sendPrompt reads /config/providers for up to 5 s when a variant was asked for);
+      // this leg is finalized and its session aborted below, so the orphan must not send.
+      // Named mutant "ORPHANSENDS" (tests/headless-variant.test.js): drop the abort.
+      sendAbort.abort();
       backstopFired = true;
       logger.warn('No-output backstop fired before the prompt send resolved', {
         taskId, sessionId, backstopMs: noOutputBackstopMs,
@@ -780,6 +811,27 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       sessionError = await noOutputBackstopReason();
     }
 
+    // #218 PR 4: what was SENT, for the leg record (emit-when-sent; named mutants
+    // "VARIANTDROPPED" / "UNVERIFIEDHIDDEN" in tests/headless-variant.test.js). A refused
+    // variant never reaches here: sendPrompt throws before the request and the outer
+    // exception handler returns the standard error result.
+    const sent = promptResult && promptResult.sentVariant;
+    const sentVariantFields = sent
+      ? { variant: sent.variant, ...(sent.verified ? {} : { variantUnverified: true }) }
+      : {};
+    if (sent && !sent.verified) {
+      const { formatUnverifiedVariantNote } = require('./utils/engine-variants');
+      const note = formatUnverifiedVariantNote({ model, variant: sent.variant, waitedMs: sent.waitedMs, unreadable: sent.unreadable });
+      logger.warn('Variant sent unverified', { taskId, sessionId, note });
+      // council #235 r2 (B2): logger.warn is DROPPED at the shipped default
+      // (LOG_LEVEL defaults to 'error', utils/logger.js), so the structured line alone
+      // told the user nothing — the silent degrade the product principle forbids, and the
+      // same invisibility this release cites against 4.9.3's silent adjustment. stderr
+      // carries it in every mode; stdout keeps the run document intact. Named mutant
+      // "UNVERIFIEDNOTICESILENT": drop the stderr write.
+      process.stderr.write(`Notice: ${note}\n`);
+    }
+
     // Hard provider failure detected at the client boundary (#37): a non-2xx /
     // 402 from promptAsync surfaces here even when the server never emits an
     // assistant message carrying info.error. Seed sessionError so the loop's
@@ -996,6 +1048,11 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         // seven first, and nothing observes them afterwards.
         // Hoisting the whole block (rather than adding a second stamp beside each
         // gate) is what keeps ONE definition of the predicate and ONE stamp site.
+        // #218 PR 3: the mirror's promotion reset (conversation-mirror.js ::
+        // mirrorMessages) can SHRINK output once -- the poll where real answer
+        // text replaces a longer promoted stand-in reads no growth here. Bounded
+        // to that poll: TTFT and the backstop were already latched by the
+        // reasoning growth, and the next growth compares against the new length.
         const outputGrew = mirror.output.length > lastOutputLength;
         lastOutputLength = mirror.output.length;
         const toolActivity = mirror.toolCalls.length > lastToolCallCount;
@@ -1120,6 +1177,30 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           break;
         }
 
+        // #218 PR 3: the engine finalized the message with finish 'length' and
+        // no answer text -- the Mode 2 death (probe row L1: hidden reasoning,
+        // no content part); decided on THAT message's parts, not on the
+        // session's accumulated output (council #232 r1 B2/D1).
+        // Nothing more will arrive from that message. With EMPTY output (hidden
+        // reasoning, L1) every exit below requires output, so without this one
+        // the leg waits out the no-output backstop and dies under ITS name,
+        // which says "silence past the deadline" about a message the engine had
+        // already finished with a reason. With output -- reasoning the mirror
+        // promoted (L2/L4; the backstop is already disarmed by that growth) or
+        // an earlier message's text -- the idle exits would end it instead: in
+        // this same poll on SDK idle, up to stableFinishedPolls later on the
+        // heuristic. This exit is the same death, no later. Gated on 'length'
+        // only: the finalized message's finish is never a step-level
+        // 'tool-calls' (B4's measured evidence below: time.completed lands after
+        // the tool ends), and a 'stop' with no text is a different, unnamed
+        // death. The message flag here matches the post-loop decision, which is
+        // the pinned one (named mutants NOEXIT and SESSIONWIDE in
+        // tests/headless-output-length.test.js).
+        if (assistantFinished && mirror.lastAssistantFinish === 'length' && !mirror.lastAssistantHasText) {
+          logger.error('Assistant message finished for length with no answer text, exiting', { taskId, pollCount });
+          break;
+        }
+
         // Authoritative idle signal from the OpenCode SDK (preferred over the heuristic).
         // Gate on real output so a pre-processing 'idle' cannot end the run early.
         // Best-effort: on any error, fall back to the activity heuristic below.
@@ -1478,6 +1559,33 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     const { sumPerMessageUsage } = require('./utils/pricing');
     const usage = sumPerMessageUsage(mirror.usageByMsg);
 
+    // #218 PR 3: name the Mode 2 death. The engine records `finish: 'length'`
+    // when the provider stopped at the max_tokens reservation (probe rows
+    // A/H1/L1-L4); with no answer text that is a dead leg, and it used to leave
+    // here as `completed` with an empty summary -- or with its THINKING promoted
+    // to the summary (L2/L4's shape). Named through the channel every other
+    // death uses (sessionError -> leg.error -> metadata.reason -> the dead-leg
+    // note), so no consumer needs a new case. An error the engine itself put on
+    // the message wins: its own name is the better observation. Named mutants
+    // (tests/headless-output-length.test.js): "ENGINEERRORLOST" drops the
+    // `!sessionError` guard; "DEATHNOTFORCED" drops `|| outputLengthDeath` from
+    // failedWithNoUsableOutput below.
+    //
+    // Decided on the LAST message's own facts (council #232 r1 B2/D1): a tool
+    // loop's earlier text or promoted reasoning is not this message's answer.
+    // The ambient flag rides the handle beside the budget (council #232 r3 B1); named mutant "AMBIENTNOTREAD" drops it here.
+    const { isOutputLengthDeath, formatOutputLengthReason } = require('./utils/output-length');
+    const finish = mirror.lastAssistantFinish;
+    const reasoningOnly = mirror.lastAssistantHasReasoning && !mirror.lastAssistantHasText;
+    const outputLengthDeath = isOutputLengthDeath({ finish, hasText: mirror.lastAssistantHasText });
+    if (outputLengthDeath && !sessionError) {
+      sessionError = formatOutputLengthReason({
+        tokens: usage.tokens, budget: readOutputBudgetSafe(server, options._readOutputBudget), reasoningOnly,
+        ambientFlag: server && typeof server.ambientOutputTokenFlag === 'string' ? server.ambientOutputTokenFlag : null,
+      });
+      logger.error('Leg stopped for length with no answer text', { taskId, error: sessionError });
+    }
+
     // ---- v4.4 B3: one TERMINAL progress record carrying the settled usage ----
     // progress.json's `usage` block was previously stamped only on 'receiving'
     // flushes, which fire on text/tool/reasoning GROWTH — always strictly before
@@ -1550,7 +1658,10 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     //
     // `failedWithNoUsableOutput` is hoisted out of the `if` below so the stage
     // and the returned shape are decided by ONE predicate and cannot drift.
-    const failedWithNoUsableOutput = !!(sessionError && (!mirror.output || pollFailureBail || toolStalled));
+    // #218 PR 3: an OUTPUT_LENGTH death can have a non-empty mirror.output -- a
+    // tool loop's earlier message text, or reasoning promoted before the answer
+    // was known -- and must still fail.
+    const failedWithNoUsableOutput = !!(sessionError && (!mirror.output || pollFailureBail || toolStalled || outputLengthDeath));
     const { resolveTerminalState } = require('./sidecar/session-finalize');
     const terminalStage = resolveTerminalState({
       completed,
@@ -1578,6 +1689,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         ...settleResult,
         ...subtreeFlags,
         ...subtreeResult,
+        ...sentVariantFields,
         // #133 P1: sessionId was assigned at :413/:417, well before this
         // return — guaranteed set here, same as `taskId` above.
         opencodeSessionId: sessionId,
@@ -1587,6 +1699,8 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         // and must keep it. (PR #207 round 3, B3: emit-when-VALID too — see the
         // clock-skew ruling at the stamp site above.)
         ...(isMeasuredTtft(ttftMs) ? { ttftMs } : {}),
+        // #218 PR 3: the engine's finish for the last assistant message, emit-when-set like ttftMs.
+        ...(typeof finish === 'string' ? { finish } : {}),
         error: sessionError
       };
     }
@@ -1602,10 +1716,13 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       ...settleResult,
       ...subtreeFlags,
       ...subtreeResult,
+      ...sentVariantFields,
       // #133 P1: see the comment on the sibling return above — guaranteed set.
       opencodeSessionId: sessionId,
       // v4.9 W13 Task A: emit-when-set — see the sibling return above.
       ...(isMeasuredTtft(ttftMs) ? { ttftMs } : {}),
+      // #218 PR 3: the engine's finish for the last assistant message, emit-when-set like ttftMs.
+      ...(typeof finish === 'string' ? { finish } : {}),
       exitCode: 0
     };
 
@@ -1778,6 +1895,7 @@ module.exports = {
   findTrailingFoldMarker,
   formatFoldOutput,
   formatNoOutputBackstopReason,
+  readOutputBudgetSafe,
   DEFAULT_TIMEOUT,
   FOLD_MARKER,
   COMPLETE_MARKER,

package/src/mcp-server.js

@@ -332,6 +332,20 @@ const handlers = {
       };
     }
 
+    // #218 PR 4 whole-branch review (VCMD-1): the zod enum closes the TYPED door only — a pack
+    // fills `thinking` onto `input` after zod ran (pack-resolve.js), and the in-process
+    // shared-server branch below never runs validateStartArgs. The same vocabulary check the
+    // CLI runs (cli.js), here for both paths. Named mutant "PACKTHINKINGUNCHECKED"
+    // (tests/pack/mcp-pack-params.test.js): drop this block.
+    {
+      const { validateThinkingLevel } = require('./utils/thinking-validators');
+      const thinkingCheck = validateThinkingLevel(input.thinking);
+      if (!thinkingCheck.valid) {
+        const { buildErrorDoc, ERROR_CODES } = require('./utils/error-doc');
+        return { isError: true, content: [{ type: 'text', text: JSON.stringify(buildErrorDoc({ code: ERROR_CODES.BAD_ARGS, message: thinkingCheck.error, hint: null })) }] };
+      }
+    }
+
     // Model routing (#61 Task 6.2): route through the gateway router for MCP
     // parity with the CLI's resolveLaunchModel (start-helpers.js). Unlike the
     // CLI, this handler must never process.exit — the MCP server is long-lived
@@ -527,6 +541,7 @@ const handlers = {
           // so without them status/list/read show a briefing-less, mode-less run.
           mode: 'headless',
           agent: agent || 'build',
+          ...(input.thinking ? { thinking: input.thinking } : {}), // #218 PR 4 whole-branch review (REC-1): emit-when-requested, as createSessionMetadata does (start-metadata.js)
           // v4.5 HOLD-gate decision 1: the RENDERED prompt (byte-identical to
           // input.prompt when no pack template applied) — parity with the CLI,
           // whose briefing.md on disk is always the rendered text (spec §4).
@@ -598,6 +613,11 @@ const handlers = {
             // moment a consumer (e.g. metadata/fold-output) needs it (12a.1/B02).
             amicusClient: detectedClient,
             nonce: foldNonce,
+            // #218 PR 4 whole-branch review (REC-1/VCMD-1/PRT-1): the level goes to the engine
+            // on THIS path too — it was argv-only (:434), which this branch never reads, so
+            // `thinking` was dropped silently while the tool text promised a refusal.
+            // Named mutant "SHAREDPATHNOVARIANT" (tests/mcp-server-wait-wiring.test.js).
+            variant: input.thinking || undefined,
           }
         ).then((result) => {
           // Session done — route through resolveTerminalState (same single source
@@ -1305,6 +1325,12 @@ const handlers = {
         && (typeof input.timeout !== 'number' || !Number.isFinite(input.timeout) || input.timeout <= 0)) {
       return textResult('Error: timeout must be a positive number of minutes.', true);
     }
+    // #218 PR 4 whole-branch review (VCMD-2): a pack-filled `thinking` bypasses the zod enum here too.
+    {
+      const { validateThinkingLevel } = require('./utils/thinking-validators');
+      const thinkingCheck = validateThinkingLevel(input.thinking);
+      if (!thinkingCheck.valid) { return textResult(thinkingCheck.error, true); }
+    }
 
     // Resolve a single effective models list (council OR models), validated
     // BEFORE any wave dir / metadata is written so a bad request never strands

package/src/mcp-tools.js

@@ -80,9 +80,9 @@ function getTools() {
         'Run headless without GUI. Default false (opens Electron window).'
       ),
       thinking: z.enum([
-        'none', 'minimal', 'low', 'medium', 'high', 'xhigh'
+        'none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'
       ]).optional().describe(
-        'Reasoning effort level. Default: medium.'
+        'Reasoning effort level. Omitted: nothing is sent and the provider\'s own default effort governs. A level the model does not declare is refused before anything is spent (the engine lists what each model declares). A model the engine\'s catalogue does not know in time is sent the level unverified (variantUnverified: true on the record).'
       ),
       timeout: z.number().optional().describe(
         'Headless timeout in minutes. Default: 15. Only applies when noUi is true.'
@@ -347,8 +347,8 @@ function getTools() {
       agent: z.enum(['Plan', 'Build']).optional().describe(
         'Agent mode for every leg. Build (default): full tool access. Plan: read-only analysis. Chat is not supported headless.'
       ),
-      thinking: z.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh']).optional().describe(
-        'Reasoning effort for every leg. Default: medium.'
+      thinking: z.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']).optional().describe(
+        'Reasoning effort for every leg. Omitted: nothing is sent and each provider\'s own default effort governs. A leg whose model does not declare the level is refused before anything is spent; the other legs run. A leg whose model the engine\'s catalogue does not know in time is sent the level unverified.'
       ),
       timeout: z.number().positive('timeout must be a positive number of minutes').optional().describe(
         'Per-leg timeout in minutes (wall-clock ≈ slowest leg). Default: 15.'