amicus 4.9.2 → 4.9.4

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.'

package/src/opencode-client.js

@@ -186,8 +186,21 @@ async function createSession(client, directory) {
  * @param {Array} options.parts - Message parts
  * @param {string} [options.agent] - Agent to use (e.g., 'build', 'explore')
  * @param {object} [options.tools] - Tool configuration
- * @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 to request, sent as the
+ *   engine's `variant` prompt field (probe F2 — the `reasoning` object sent before PR 4 was
+ *   never a prompt field, F1). Validated against the model's DECLARED variants first
+ *   (utils/engine-variants.js): refused with a VariantRefusedError (code VARIANT_UNDECLARED
+ *   or VARIANT_OVER_BUDGET) BEFORE any request when the engine would drop it silently or add
+ *   its thinking budget over the budget; sent unverified when the engine's catalogue does not
+ *   know the model within the wait. On a send the result carries
+ *   `sentVariant: {variant, verified, waitedMs, unreadable?}` (decorated like `providerError`;
+ *   `unreadable` names why `/config/providers` could not be read, when that is why the send is
+ *   unverified). The verdict does not depend on `outputBudget` (council #235 r3, C1/B1).
+ * @param {number|null} [options.outputBudget] - the budget the engine serving this session
+ *   was spawned with (the server handle's `outputBudget`); `null` = unset; omitted = unknown.
+ *   Only the fit check reads it.
+ * @param {object} [options._declaration] - test seam: readModelDeclaration's opts (waitMs/pollMs/sleep/now/catalogCeiling/readCache/readTimeoutMs — the per-read deadline, council #235 r2 A1)
+ * @param {{aborted: boolean}} [options.signal] - abandon signal (headless.js): when set before the send, nothing is sent
  * @param {object} [options.watchdog] - IdleWatchdog instance to signal busy/idle around the API call
  * @param {string} [options.directory] - Optional project directory to scope the
  *   call to (threaded to the SDK as query.directory). Omitting it keeps the
@@ -195,7 +208,7 @@ async function createSession(client, directory) {
  * @returns {Promise<object>} API response
  */
 async function sendPrompt(client, sessionId, options) {
-  const { model, system, parts, agent, tools, reasoning, watchdog, directory } = options;
+  const { model, system, parts, agent, tools, variant, outputBudget, watchdog, directory } = options;
 
   // Parse model string to SDK format
   const modelSpec = parseModelString(model);
@@ -220,8 +233,26 @@ async function sendPrompt(client, sessionId, options) {
     body.tools = tools;
   }
 
-  if (reasoning) {
-    body.reasoning = reasoning;
+  // #218 PR 4: `variant` is the engine's prompt field for effort (F2); `reasoning`
+  // never was one and is not forwarded (F1 — named mutant "REASONINGLEAK" in
+  // tests/opencode-client.test.js). Validated against the engine's own declaration
+  // BEFORE the request, so a refusal sends nothing (mutant "SENTANYWAY") and the
+  // declaration is read only when a variant was asked for (mutant "ALWAYSREAD").
+  let sentVariant = null;
+  if (variant) {
+    const { readModelDeclaration, checkVariant, VariantRefusedError } = require('./utils/engine-variants');
+    const modelId = `${modelSpec.providerID}/${modelSpec.modelID}`;
+    const declaration = await readModelDeclaration(client, modelId, { ...(options._declaration || {}), signal: options.signal });
+    // #218 PR 4 whole-branch review (EP-2): headless races this call against its no-output
+    // backstop; when the window is shorter than the declaration wait the leg is already
+    // finalized and its session aborted by the time the wait ends. Never send after that —
+    // and never let a refusal reach the leg's swallowed orphan as if it had been a send.
+    // Named mutant "SENDAFTERABANDON" (tests/opencode-client.test.js): drop this check.
+    if (options.signal && options.signal.aborted) { throw new Error('sendPrompt abandoned: the caller gave up during the declaration wait; nothing was sent'); }
+    const verdict = checkVariant({ variant, model: modelId, declaration, outputBudget });
+    if (!verdict.ok) { throw new VariantRefusedError(verdict.code, verdict.reason); }
+    body.variant = variant;
+    sentVariant = { variant, verified: verdict.verified, waitedMs: declaration.waitedMs, ...(declaration.unreadable ? { unreadable: declaration.unreadable } : {}) };
   }
 
   if (watchdog) {
@@ -241,6 +272,10 @@ async function sendPrompt(client, sessionId, options) {
     }
   }
 
+  // #218 PR 4: what was SENT, for the leg record (headless.js reads it). Same
+  // decoration-of-the-SDK-result precedent as `providerError` below.
+  if (sentVariant && result && typeof result === 'object') { result.sentVariant = sentVariant; }
+
   // Detect a hard provider failure at the client boundary (#37). A non-2xx /
   // 402 here must surface as a session error EVEN WHEN the server emits no
   // assistant message carrying info.error — otherwise the run looks idle/empty.
@@ -493,6 +528,8 @@ function resolveServerStartTimeoutMs(options = {}, env, platform) {
  * @param {string} [options.client] - Client type ('cowork', 'code-local', etc.)
  * @param {string} [options.systemPrompt] - System prompt to set on agent config (hidden from UI)
  * @param {string} [options.agentName] - Agent to set systemPrompt on (default: 'chat')
+ * @param {number|null} [options.outputBudget] - #218 PR 3: the per-leg output budget startServer
+ *   already read; omitted means buildProviderModels reads config itself
  * @returns {object} Server options ready for createOpencodeServer
  */
 function buildServerOptions(options = {}) {
@@ -573,7 +610,7 @@ function buildServerOptions(options = {}) {
   const resolvedForProvider = (Array.isArray(options.models) && options.models.length)
     ? options.models
     : (options.model ? [options.model] : []);
-  config.provider = buildProviderModels(resolvedForProvider);
+  config.provider = buildProviderModels(resolvedForProvider, options.outputBudget);
 
   // v4.6.2 PR1 (spec §4, D1/D2): a host-form ANTHROPIC_BASE_URL is correct
   // for Anthropic SDKs (they append /v1) and fatal for OpenCode's
@@ -764,7 +801,31 @@ async function startServer(options = {}) {
   // path is otherwise unreachable from a unit test.
   const createOpencodeServer = options._createOpencodeServer
     || await getCreateOpencodeServer();
-  const serverOptions = buildServerOptions(options);
+
+  // #218 PR 3: ONE config read feeds both levers. The descriptor
+  // (buildProviderModels, inside buildServerOptions) and the engine flag
+  // (withOutputTokenFlag below) used to call loadConfig() separately; a config
+  // write between the two reads could hand the engine a descriptor from one
+  // budget and a flag from another. Named mutant "DOUBLEREAD"
+  // (tests/opencode-client-output-flag.test.js: buildProviderModels must
+  // receive the value startServer read).
+  const { getOutputBudget } = require('./utils/config');
+  const outputBudget = getOutputBudget();
+  const serverOptions = buildServerOptions({ ...options, outputBudget });
+
+  // #218 PR 2: the engine reads OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX from the
+  // env it is SPAWNED with, and the pinned SDK spreads process.env into that
+  // spawn synchronously, before its first await. So the flag is set around the
+  // synchronous call only and is restored before the promise is awaited — it
+  // never reaches the caller's env or any other child amicus starts. The budget
+  // is the ONE value read above and handed to buildProviderModels as well, so
+  // the two levers cannot disagree (measured agreeing: probe rows C2, K6). Unit
+  // pin: tests/opencode-client-output-flag.test.js through the
+  // `_createOpencodeServer` seam. SDK-side canary for the spread-before-await
+  // fact: tests/opencode-client-sdk-spawn-timing.test.js drives the REAL SDK
+  // against a fake engine on PATH. Engine-side canary: probe rows K6/K12/K13,
+  // run in CI's keyless job by tests/probe-flag-canary.integration.test.js.
+  const { withOutputTokenFlag, OUTPUT_TOKEN_FLAG } = require('./utils/engine-output-flag');
 
   // Measure the healthy path. The v4.5.2 timeout had to be sized from the
   // asymmetry of the failure (a slow start costs latency, a failed one costs a
@@ -772,7 +833,14 @@ async function startServer(options = {}) {
   // margin against the ceiling was unmeasurable on exactly the slow boxes that
   // needed it. Now it is one debug line, not an inference.
   const startedAt = Date.now();
-  const sdkServer = await createOpencodeServer(serverOptions);
+  // #218 PR 3 (council #232 r3 B1): with no budget the wrapper leaves an ambient
+  // OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX untouched (PR 2 ruling R2) and the
+  // engine honours it (probe C3/J2), so a death report must name THAT value, not
+  // the 32000 default. Read here, before the spawn, from the same env the wrapper
+  // reads; null whenever a budget is set (the wrapper overrides the flag then).
+  const ambientOutputTokenFlag = outputBudget === null && typeof process.env[OUTPUT_TOKEN_FLAG] === 'string'
+    ? process.env[OUTPUT_TOKEN_FLAG] : null;
+  const sdkServer = await withOutputTokenFlag(outputBudget, () => createOpencodeServer(serverOptions));
   const { logger } = require('./utils/logger');
   logger.debug('OpenCode server started', {
     startMs: Date.now() - startedAt,
@@ -785,6 +853,14 @@ async function startServer(options = {}) {
   // findListenerPid may return null if the port isn't bound yet (startup race);
   // in that case close() degrades to SIGTERM-only, which is acceptable best-effort.
   const server = buildServerHandle(sdkServer);
+  // #218 PR 3 (council #232 r1 B3): the budget this engine was SPAWNED with
+  // rides its handle, so a death report names the reservation that produced
+  // the finish, not whatever config.json says by then (headless.js ::
+  // readOutputBudgetSafe reads it first). null = unset.
+  server.outputBudget = outputBudget;
+  // Stamped beside the budget for the same reader (headless.js's death report).
+  // Named mutant "AMBIENTNOTSTAMPED" (tests/opencode-client-output-flag.test.js).
+  server.ambientOutputTokenFlag = ambientOutputTokenFlag;
 
   return { client, server };
 }

package/src/pack/pack-validate.js

@@ -64,6 +64,9 @@ function validatePack(pack, { mode } = { mode: 'run' }) {
     for (const key of Object.keys(opts)) {
       if (!KIND_OPTIONS[pack.kind].includes(key)) { errors.push(`unknown option '${key}' for kind '${pack.kind}'`); }
     }
+    // #218 PR 4 whole-branch review (VCMD-2): the VALUE too — a saved 'turbo' would reach the wire.
+    const { VARIANT_LEVELS } = require('../utils/thinking-validators');
+    if (opts.thinking !== undefined && !VARIANT_LEVELS.includes(opts.thinking)) { errors.push(`options.thinking must be one of: ${VARIANT_LEVELS.join(', ')}`); }
   }
 
   const { getEffectiveAliases, getCouncilWithSource } = require('../utils/config');

package/src/session-manager.js

@@ -78,7 +78,7 @@ function resolveExistingSessionDir(projectDir, taskId) {
  * @param {string} metadata.project - Project path
  * @param {string} [metadata.briefing] - Task briefing
  * @param {string} [metadata.mode] - Mode: 'interactive' or 'headless'
- * @param {string} [metadata.thinking='medium'] - Thinking/reasoning intensity level
+ * @param {string} [metadata.thinking] - Reasoning effort requested; recorded only when one was (#218 PR 4)
  * @throws {Error} If session already exists
  */
 function createSession(projectDir, taskId, metadata) {
@@ -99,7 +99,7 @@ function createSession(projectDir, taskId, metadata) {
     project: metadata.project || projectDir,
     briefing: metadata.briefing || '',
     mode: metadata.mode || 'interactive',
-    thinking: metadata.thinking || 'medium',
+    ...(metadata.thinking ? { thinking: metadata.thinking } : {}), // #218 PR 4: emit-when-requested (see start-metadata.js)
     status: SESSION_STATUS.RUNNING,
     createdAt: new Date().toISOString(),
     completedAt: null,

package/src/sidecar/continue.js

@@ -15,6 +15,7 @@ const {
   createHeartbeat
 } = require('./session-utils');
 const { acquireLock, releaseLock } = require('../utils/session-lock');
+const { noticeDroppedLevel } = require('./reopen-notices');
 const { runHeadless } = require('../headless');
 const { buildPrompts } = require('../prompt-builder');
 const { generateFoldNonce } = require('../utils/fold-marker');
@@ -140,6 +141,7 @@ async function continueSidecar(options) {
   // Load previous session data
   const { metadata: oldMetadata, summary: previousSummary, conversation: previousConversation } =
     loadPreviousSession(oldTaskId, project);
+  noticeDroppedLevel(oldMetadata, { taskId: oldTaskId, kind: 'continue' }); // council #235 r5 (J1/A3): read against the PARENT's metadata — a continuation opens a NEW session, sends no variant, and `continue` rejects --thinking, so a level the parent ran with silently becomes the provider's default here. Named mutant "CONTINUELEVELSILENT" (tests/sidecar/reopen-thinking-notice.test.js).
 
   // Lock the previous (EXISTING) session directory to prevent concurrent
   // continue operations — resolve dual-dir so a legacy session is locked too.
@@ -245,11 +247,14 @@ async function continueSidecar(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 "CONTINUEERRORNOVARIANT", tests/continue-resume-spend.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('Continuation completed with error', { taskId: newTaskId, error: meta.reason });
   } else {
-    finalizeSession(sessionDir, summary, project, meta, { quietStdout: json, status: terminal.status });
+    finalizeSession(sessionDir, summary, project, meta, { quietStdout: json, status: terminal.status, finish: result && result.finish, variant: result && result.variant, variantUnverified: result && result.variantUnverified }); // named mutant "CONTINUEVARIANTDROPPED" (tests/continue-resume-spend.test.js): drop the variant args
   }
   // v4.3: attribute continue spend (C9/E4). Reload meta, write usage + append a
   // ledger row (status: statusFromResult, matching start.js — not terminal.status).