amicus 4.9.3 → 4.9.5

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

package/src/sidecar/conversation-mirror.js

@@ -32,18 +32,39 @@ function createMirrorState() {
     receivingReported: false,
     output: '',                 // accumulated assistant text
     seenReasoningParts: new Map(), // partId -> last captured reasoning length
-    reasoningOutput: '',        // accumulated reasoning text (promoted to output only if no text part arrives)
+    reasoningOutput: '',        // accumulated reasoning text (promoted to output when no text part has arrived; see promotedOutput)
     usageByMsg: new Map(),      // msgId -> {tokens, cost}
+    // #218 PR 3: three facts about the LAST assistant message in the snapshot
+    // -- its `finish` (stamped at finalization, beside tokens/cost), whether it
+    // carries answer text, whether it carries reasoning -- the whole input of
+    // the death test in utils/output-length.js. Per MESSAGE on purpose: `output`
+    // above accumulates across a tool loop's messages and would let earlier
+    // text hide a final length stop, or earlier promoted reasoning condemn a
+    // later message that answered (council #232 r1 B2/D1).
+    lastAssistantFinish: null,
+    lastAssistantHasText: false,
+    lastAssistantHasReasoning: false,
+    promotedOutput: '',         // the reasoning a promotion put into `output` as a stand-in; the first real answer text on a later message replaces it (council #232 r1)
   };
 }
 
 /**
- * Capture one assistant message's usage snapshot into `state.usageByMsg`.
+ * Capture one assistant message's usage snapshot AND its finish into the state.
  * The poll loop re-reads ALL messages every poll, so the latest snapshot per
  * message id wins (keyed Map, never additive) — see pricing.sumPerMessageUsage.
  * @returns {boolean} true when this message carried a usage payload
  */
 function captureMsgUsage(msg, state) {
+  // #218 PR 3: `finish` was observed beside tokens/cost on every probe L row, so
+  // both mirror passes record it here; the last assistant message in the
+  // snapshot wins, and one still streaming (no finish yet) resets it to null; '' counts as none (council #232 r3 C1; mutant "EMPTYFINISH").
+  // The two part flags are read off THIS message's parts, never off `output`
+  // (council #232 r1 B2/D1). Named mutants "NOFINISH", "TEXTOFFOUTPUT"
+  // (tests/conversation-mirror.test.js).
+  state.lastAssistantFinish = (typeof msg.info.finish === 'string' && msg.info.finish.length > 0) ? msg.info.finish : null;
+  const parts = Array.isArray(msg.parts) ? msg.parts : [];
+  state.lastAssistantHasText = parts.some((p) => p && p.type === 'text' && typeof p.text === 'string' && p.text.trim().length > 0);
+  state.lastAssistantHasReasoning = parts.some((p) => p && p.type === 'reasoning' && typeof p.text === 'string' && p.text.length > 0);
   if (msg.info.tokens || typeof msg.info.cost === 'number') {
     state.usageByMsg.set(msg.info.id, { tokens: msg.info.tokens, cost: msg.info.cost });
     return true;
@@ -52,9 +73,9 @@ function captureMsgUsage(msg, state) {
 }
 
 /**
- * USAGE-ONLY mirror pass (v4.4 B1). Captures `info.tokens`/`info.cost` from a
- * fresh getMessages() snapshot and NOTHING else — no appendLines, no
- * `state.output` growth, no progress updates, no pending-tool bookkeeping.
+ * USAGE-ONLY mirror pass (v4.4 B1). Captures `info.tokens`/`info.cost` — and, since #218 PR 3,
+ * the last assistant message's `finish` — from a fresh getMessages() snapshot and NOTHING else —
+ * no appendLines, no `state.output` growth, no progress updates, no pending-tool bookkeeping.
  *
  * This exists because the headless poll loop's fast-path exits (trailing fold
  * marker, SDK `idle`) break BEFORE OpenCode stamps usage at finalization, so a
@@ -63,7 +84,7 @@ function captureMsgUsage(msg, state) {
  * conversation.jsonl a second time; this function cannot, because it never
  * touches seenTextParts/output at all.
  * @param {Array} messages getMessages() snapshot
- * @param {object} state from createMirrorState() (only usageByMsg is mutated)
+ * @param {object} state from createMirrorState() (only usageByMsg and the three lastAssistant* facts are mutated)
  * @returns {number} count of messages whose usage was captured
  */
 function mirrorUsageOnly(messages, state) {
@@ -138,6 +159,9 @@ function mirrorMessages(messages, state, opts = {}) {
         if (part.text.length > prevLen) {
           // Append only the new portion (handles streaming growth)
           const newText = part.text.slice(prevLen);
+          // The first non-whitespace text replaces the stand-in; output restarts from the answer;
+          // conversation.jsonl keeps its reasoning. KEEPPROMOTED; WHITESPACERESET drops the trim.
+          if (state.promotedOutput && newText.trim().length > 0) { state.output = ''; state.promotedOutput = ''; }
           state.output += newText;
           state.seenTextParts.set(partId, part.text.length);
           appendLines.push({ role: 'assistant', content: newText, timestamp: now() });
@@ -244,12 +268,12 @@ function mirrorMessages(messages, state, opts = {}) {
   const lastAssistant = list.filter(m => m.info && m.info.role === 'assistant').pop();
   assistantFinished = !!(lastAssistant && lastAssistant.info.time && lastAssistant.info.time.completed);
 
-  // Reasoning-only fallback: if the assistant finished but emitted only reasoning
-  // parts (no visible text), promote the reasoning text to `output` so the headless
-  // completion gates fire and the answer isn't lost as "No Output". Runs once — once
-  // `output` is non-empty this is skipped on subsequent polls.
+  // Reasoning-only fallback: if the assistant finished but emitted only reasoning parts (no
+  // visible text), promote the reasoning text to `output` so the headless completion gates fire
+  // and the answer isn't lost as "No Output". Runs once — a non-empty `output` skips it on later
+  // polls. `promotedOutput` records the stand-in, which the first real text part replaces above.
   if (assistantFinished && !state.output && state.reasoningOutput) {
-    state.output = state.reasoningOutput;
+    state.output = state.promotedOutput = state.reasoningOutput;
     appendLines.push({ role: 'assistant', content: state.reasoningOutput, timestamp: now() });
   }
 

package/src/sidecar/electron-install.js

@@ -1,21 +1,18 @@
 /**
  * Electron self-heal primitive (#53, #59).
  *
- * Electron is an optionalDependency (^28.0.0). A flaky / interrupted extract
- * — or Windows Defender quarantining electron.exe — can leave the package's
- * path.txt on disk while dist/<exe> is MISSING, so the GUI silently fails.
+ * Electron is an optionalDependency (^28.0.0). A flaky / interrupted extract —
+ * or Windows Defender quarantining electron.exe — can leave the package's
+ * path.txt on disk while dist/<exe> is MISSING, so the GUI silently fails. This
+ * module is the keystone the rest of the self-heal cluster (#54-#57) imports; it
+ * wires itself into no caller, and everything that downloads, extracts, spawns or
+ * locks is dependency-INJECTABLE so tests never hit the network or extract a real
+ * binary.
  *
- * This module is the keystone the rest of the self-heal cluster (#54-#57)
- * imports. It does NOT wire itself into any caller. Everything that downloads,
- * extracts, spawns, or locks is dependency-INJECTABLE so tests never hit the
- * network or extract a real binary.
- *
- * Layout reference (npm `electron` package):
- *   node_modules/electron/path.txt    -> "electron.exe" (the exe basename)
- *   node_modules/electron/dist/<exe>  -> the actual binary
- * #59: when ELECTRON_OVERRIDE_DIST_PATH is set, the exe lives in that dir
- * instead of <pkg>/dist (mirrors electron/index.js + install.js semantics).
- * Cache layout (@electron/get): <cacheRoot>/<sha256>/electron-v<ver>-<platform>-<arch>.zip
+ * Layout (npm `electron`): path.txt -> the exe basename, dist/<exe> -> the binary.
+ * #59: ELECTRON_OVERRIDE_DIST_PATH moves the exe to <override>/<exe> (mirrors
+ * electron/index.js + install.js semantics). Cache layout (@electron/get):
+ * <cacheRoot>/<sha256>/electron-v<ver>-<platform>-<arch>.zip
  */
 
 'use strict';
@@ -27,6 +24,8 @@ const { spawnSync } = require('child_process');
 const { resolveCacheRoots } = require('./electron-cache');
 const { avHint, verifyExtractOutcome: verifyQuarantine } = require('./electron-quarantine');
 const { acquireRepairLock } = require('./electron-lock');
+const { controlledProvision, isUnsafeArchive, refuseUnsafeArchive, rejectCachedZip } = require('./electron-provision');
+const { artifactFileName, electronTrustPolicy, resolveAnchor, scrubbedChildEnv, verifyArtifact } = require('./electron-trust');
 const { robustExtract } = require('./unzip');
 
 /** Self-heal progress line to stderr (visible during first-GUI provision). */
@@ -134,32 +133,6 @@ async function extractFromCache({ zip, electronDir, platform, extract, fs }) {
   writePathTxt({ electronDir, platform, fs });
 }
 
-/** Best-effort cache root for downloadArtifact (first resolved root). */
-function cacheRootFor(env = process.env) {
-  return resolveCacheRoots(env)[0];
-}
-
-/**
- * CONTROLLED provision: fetch the zip ourselves with the SAME @electron/get
- * api install.js uses (downloadArtifact, force:true), extract offline, and let
- * the caller verify isElectronUsable(). No blind install.js spawn.
- * @returns {Promise<void>}
- */
-async function controlledProvision({
-  electronDir, platform, arch, version, downloadArtifact, extract, fs, env = process.env, downloadMs = 480000,
-}) {
-  const zip = await downloadArtifact({
-    version,
-    artifactName: 'electron',
-    force: true,
-    cacheRoot: cacheRootFor(env),
-    platform,
-    arch,
-    downloadOptions: { signal: AbortSignal.timeout(downloadMs) }, // 5.x native fetch: bound stalled downloads, free the lock
-  });
-  await extractFromCache({ zip, electronDir, platform, extract, fs });
-}
-
 /** Bind the fs-aware probes for the post-extract AV-quarantine verify. */
 function verifyExtractOutcome({ electronDir, platform, fs }) {
   return verifyQuarantine({
@@ -169,10 +142,16 @@ function verifyExtractOutcome({ electronDir, platform, fs }) {
   });
 }
 
-/** Drive electron's own install.js with force_no_cache semantics. */
-function runInstaller({ electronDir, force, spawn }) {
+/**
+ * Drive electron's own install.js with force_no_cache semantics. C3: the spawn env
+ * is SCRUBBED — install.js honours `npm_config_electron_mirror` AND
+ * `npm_config_electron_use_remote_checksums` (which turns its own bundled pin off),
+ * so `{...process.env}` here would funnel a blocked attacker into an unpinned
+ * downloader and undo the pin on the route above.
+ */
+function runInstaller({ electronDir, force, spawn, platform, arch }) {
   const installScript = path.join(electronDir, 'install.js');
-  const env = { ...process.env };
+  const env = scrubbedChildEnv({ env: process.env, platform, arch });
   if (force) {
     env.force_no_cache = 'true';
   }
@@ -187,7 +166,8 @@ function runInstaller({ electronDir, force, spawn }) {
  *   {deferred,reason} when there is no cached zip.
  * @param {boolean} [opts.force] force a fresh (no-cache) installer download.
  * @param {number}  [opts.timeoutMs] best-effort installer timeout.
- * @param {object}  [opts.deps] injected { cachedZip, extract, spawn, acquireLock, fs }.
+ * @param {object}  [opts.deps] injected { cachedZip, extract, spawn, acquireLock, fs,
+ *   selfElectronDir } — the last pins the digest anchor's top rung (null disables it).
  * @returns {Promise<{repaired?:boolean, deferred?:boolean, contended?:boolean, reason?:string}>}
  */
 async function repairElectron({
@@ -204,9 +184,8 @@ async function repairElectron({
   // Default extract: extract-zip bounded (idle/max) + native-unzip fallback (extract-zip-node24 stall).
   const extract = deps.extract
     || ((zipPath, o) => robustExtract(zipPath, { ...o, platform, deps: { fs, log: stderrLog } }));
-  // Default-bound the last-resort installer spawn (8 min) so a first-GUI-use
-  // provision that reaches runInstaller without an explicit timeoutMs can't hang
-  // the holder — the caller's timeoutMs still wins when provided.
+  // Default-bound (8 min) so a first-GUI-use provision that reaches runInstaller
+  // without an explicit timeoutMs can't hang the holder; caller's value wins.
   const spawn = deps.spawn || ((cmd, args, o) => spawnSync(cmd, args, { ...o, timeout: timeoutMs || 480000 }));
   const findZip = deps.cachedZip || ((o) => cachedZip(o));
   const acquireLock = deps.acquireLock || ((o) => acquireRepairLock({ ...o, fs }));
@@ -217,13 +196,17 @@ async function repairElectron({
     : async () => (await import('@electron/get')).downloadArtifact;
 
   if (!version) {
-    try {
-      version = require(path.join(electronDir, 'package.json')).version;
-    } catch {
-      version = undefined;
-    }
+    try { version = require(path.join(electronDir, 'package.json')).version; } catch { version = undefined; }
   }
 
+  // The digest anchor and the trust policy, resolved ONCE for both routes. NOTE
+  // `version` is deliberately NOT passed to resolveAnchor: it may have just been
+  // read out of electronDir's own package.json above, and letting an untrusted
+  // directory pick which anchor judges its bytes is the ANCHORFROMTARGET hole.
+  const fileName = artifactFileName({ version, platform, arch });
+  const policy = electronTrustPolicy(process.env);
+  const anchor = resolveAnchor({ electronDir, fs, selfElectronDir: deps.selfElectronDir });
+
   // Single-flight: bail out gracefully if another caller is already repairing.
   let lock;
   try {
@@ -235,55 +218,72 @@ async function repairElectron({
     throw e;
   }
 
+  let refusal = null;   // a cache refusal the caller must still hear about if the download also fails
   try {
     // Attempt 1: extract from cache (always preferred, fully offline).
     const zip = findZip({ version, platform, arch, env: process.env, fs });
     if (zip) {
-      try {
-        await extractFromCache({ zip, electronDir, platform, extract, fs });
-        // Non-throwing extract w/ absent exe = the AV-quarantine signature.
-        return verifyExtractOutcome({ electronDir, platform, fs });
-      } catch (extractErr) {
-        // Corrupt cached artifact: delete the bad zip so it can't poison the
-        // cache, then fall through to a forced fresh download (unless offline).
-        try { fs.rmSync(zip, { force: true }); } catch { /* ignore */ }
-        if (cacheOnly) {
-          return {
-            repaired: false,
-            reason: `Cached electron zip for v${version} (${platform}-${arch}) was corrupt and removed; deferring re-download.${avHint(platform)}`,
-          };
-        }
+      // C2: anything that can write the cache dir can swap these bytes, so HASH
+      // BEFORE EXTRACT — extractFromCache must be unreachable for an artifact the
+      // anchor contradicts. A missing anchor is NOT a refusal (see verifyArtifact).
+      const gate = verifyArtifact({ zip, anchor, fileName, policy, fs, log: stderrLog });
+      if (!gate.allowed) {
+        refusal = rejectCachedZip({ gate, zip, fileName, env: process.env, fs, log: stderrLog });
+        if (cacheOnly) { return refusal; }
         // else: drop into the controlled download below.
+      } else {
+        try {
+          await extractFromCache({ zip, electronDir, platform, extract, fs });
+          // Non-throwing extract w/ absent exe = the AV-quarantine signature.
+          const outcome = verifyExtractOutcome({ electronDir, platform, fs });
+          return gate.verdict === 'no-digest' ? { ...outcome, unverified: true } : outcome;
+        } catch (extractErr) {
+          // C4 IS A CALL-SITE INVARIANT. A path-traversal refusal must not be
+          // deleted-and-retried, nor reported as "corrupt" — it stops here.
+          if (isUnsafeArchive(extractErr)) { return refuseUnsafeArchive({ err: extractErr, fileName, log: stderrLog }); }
+          // Corrupt cached artifact: delete the bad zip so it can't poison the
+          // cache, then fall through to a forced fresh download (unless offline).
+          try { fs.rmSync(zip, { force: true }); } catch { /* ignore */ }
+          if (cacheOnly) {
+            return { repaired: false, reason: `Cached electron zip for v${version} (${platform}-${arch}) was corrupt and removed; deferring re-download.${avHint(platform)}` };
+          }
+          // else: drop into the controlled download below.
+        }
       }
     } else if (cacheOnly) {
-      return {
-        deferred: true,
-        reason: `No cached electron zip found for v${version} (${platform}-${arch}); deferring download.${avHint(platform)}`,
-      };
+      return { deferred: true, reason: `No cached electron zip found for v${version} (${platform}-${arch}); deferring download.${avHint(platform)}` };
     }
 
-    // Attempt 2 (online): CONTROLLED download+extract instead of a blind
-    // install.js spawn — fetch via the SAME @electron/get api install.js uses,
-    // extract offline, then report the REAL usability. A structurally-successful
-    // download that produced no usable exe is a FAILURE (no false success; #53).
+    // Attempt 2 (online): CONTROLLED download+extract instead of a blind install.js
+    // spawn — the SAME @electron/get api install.js uses, extracted offline, then the
+    // REAL usability reported. A download that produced no usable exe is a FAILURE (#53).
     let controlledExtracted = false;
     try {
       const downloadArtifact = await resolveDownloadArtifact();
       await controlledProvision({
-        electronDir, platform, arch, version, downloadArtifact, extract, fs, env: process.env, downloadMs: timeoutMs,
+        electronDir, platform, arch, version, anchor, downloadArtifact, extract, extractFromCache,
+        fs, env: process.env, downloadMs: timeoutMs, policy, log: stderrLog,
       });
       controlledExtracted = true; // download + extract returned without throwing
-    } catch {
+    } catch (provisionErr) {
+      // C4 again: an unsafe archive here must NOT reach runInstaller, which would
+      // re-download and re-extract it through an extractor amicus does not drive.
+      if (isUnsafeArchive(provisionErr)) { return refuseUnsafeArchive({ err: provisionErr, fileName, log: stderrLog }); }
       // Controlled download/extract failed (network, checksum, unzip). Try the
       // installer as a LAST resort — it can NEVER short-circuit the honest
       // verify below; we always return isElectronUsable().
-      try { runInstaller({ electronDir, force, spawn }); } catch { /* ignore */ }
+      try { runInstaller({ electronDir, force, spawn, platform, arch }); } catch { /* ignore */ }
     }
     // A NON-throwing controlled extract that left no usable exe is the
-    // AV-quarantine signature — surface it actionably (no false success, no
-    // loop). A controlled FAILURE only reports plain repaired:false.
-    if (controlledExtracted) { return verifyExtractOutcome({ electronDir, platform, fs }); }
-    return { repaired: isElectronUsable({ electronDir, platform, fs }) };
+    // AV-quarantine signature — surface it actionably (no false success, no loop).
+    const out = controlledExtracted
+      ? verifyExtractOutcome({ electronDir, platform, fs })
+      : { repaired: isElectronUsable({ electronDir, platform, fs }) };
+    // A refusal the download did not rescue must reach doctor and the postinstall
+    // notice; plain {repaired:false} is what made a REFUSED artifact read as an
+    // ordinary "not provisioned" everywhere outside the cacheOnly path.
+    if (!out.repaired && refusal) { return { ...out, integrity: refusal.integrity, reason: [refusal.reason, out.reason].filter(Boolean).join(' ') }; }
+    return out;
   } finally {
     try { lock.release(); } catch { /* ignore */ }
   }