amicus 4.9.3 → 4.9.5

package/src/sidecar/electron-provision.js

@@ -0,0 +1,179 @@
+/**
+ * Electron CONTROLLED provision — the pinned download, and what happens to a
+ * cached artifact the digest gate refuses.
+ *
+ * Split out of electron-install.js because that file sits at the repo's 300-line
+ * gate and cannot grow. The require arrow is
+ * electron-install -> electron-provision -> electron-trust and must never point
+ * back, so `extractFromCache` arrives as an argument rather than an import.
+ *
+ * @module sidecar/electron-provision
+ */
+
+'use strict';
+
+const path = require('path');
+
+const { resolveCacheRoots } = require('./electron-cache');
+const { artifactFileName, expectedDigest } = require('./electron-trust');
+const { containsOnDisk } = require('../utils/path-fence');
+
+/** 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.
+ *
+ * C1 — THE PIN. `checksums` is what breaks the attack chain. Supplied, it makes
+ * @electron/get write a LOCAL SHASUMS256.txt from this table and never fetch one
+ * from the mirror, so a redirected download still has to produce bytes matching
+ * electron's own published sha256. Passed as the ONE entry for this artifact:
+ * an empty table is a hard throw upstream, and a table missing the requested
+ * name fails the download outright — which is why no anchor means no `checksums`
+ * key at all rather than an empty one. With no anchor, @electron/get falls back
+ * to its own remote SHASUMS256.txt fetch: weaker, but never a re-download loop.
+ *
+ * THE HATCH REACHES THIS ROUTE TOO. `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` used to
+ * be handed only to the cached-artifact gate, so the one case both docs describe
+ * — a machine whose electron bytes legitimately differ (a local rebuild, an
+ * internally-signed build on a corporate mirror) — still had its download pinned
+ * to the official digest and failed. MEASURED before this change: with the hatch
+ * set and nothing in any cache root, `checksums` was still sent and the call
+ * returned `{repaired:false}` with no reason at all. When the hatch is set the
+ * pin is dropped here and @electron/get falls back to the mirror's own
+ * SHASUMS256.txt, which is what a rebuild publishes. That is a real downgrade,
+ * so it is stated out loud on stderr every time rather than happening quietly —
+ * and it is reachable ONLY through a bare env name a repository cannot plant.
+ * @returns {Promise<void>}
+ */
+async function controlledProvision({
+  electronDir, platform, arch, version, anchor, downloadArtifact, extract, extractFromCache,
+  fs, env = process.env, downloadMs = 480000, policy = {}, log = () => {},
+}) {
+  const fileName = artifactFileName({ version, platform, arch });
+  let digest = expectedDigest(anchor, fileName);
+  if (digest && policy.allowUnverified) {
+    log('[amicus] WARNING: AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — downloading without the published');
+    log(`[amicus]   sha256 pin for ${fileName}; its digest comes from the mirror you are using.`);
+    digest = null;
+  }
+  const zip = await downloadArtifact({
+    version,
+    artifactName: 'electron',
+    force: true,
+    cacheRoot: cacheRootFor(env),
+    platform,
+    arch,
+    ...(digest ? { checksums: { [fileName]: digest } } : {}),
+    downloadOptions: { signal: AbortSignal.timeout(downloadMs) }, // 5.x native fetch: bound stalled downloads, free the lock
+  });
+  await extractFromCache({ zip, electronDir, platform, extract, fs });
+}
+
+/**
+ * May this refused artifact be deleted? STRICTLY NARROWER than the unconditional
+ * `fs.rmSync` on the corrupt-extract path: the basename must be exactly the
+ * artifact we asked for, AND the file must resolve inside a resolved cache root.
+ * `containsOnDisk` realpaths both sides and returns false on any error, so an
+ * unresolvable path is refused rather than trusted — deleting at an
+ * attacker-influenceable path is the one thing a poisoned cache could otherwise
+ * turn into a weapon.
+ *
+ * Cost if it returns a wrong false: the mismatched zip stays and is re-downloaded
+ * once per provision. An availability cost, never a safety one — the gate above
+ * still refuses to extract it.
+ */
+function mayDeleteRejectedZip({ zip, fileName, env = process.env }) {
+  if (path.basename(zip) !== fileName) { return false; }
+  return resolveCacheRoots(env).some((root) => containsOnDisk(root, zip));
+}
+
+/**
+ * Act on a REFUSED cached artifact: remove the poison when it is safe to, say
+ * plainly what happened, and hand back the result shape a cacheOnly caller
+ * returns. Deletion happens ONLY on `mismatch` — a `no-digest` artifact is not
+ * evidence of anything, and an `unreadable` one is a file we could not even hash.
+ * @returns {{repaired:false, integrity:string, reason:string}}
+ */
+function rejectCachedZip({ gate, zip, fileName, env = process.env, fs, log = () => {} }) {
+  let removed = false;
+  if (gate.verdict === 'mismatch' && mayDeleteRejectedZip({ zip, fileName, env })) {
+    try {
+      fs.rmSync(zip, { force: true });
+      removed = true;
+    } catch { /* a cache we cannot write is not a reason to fail the repair */ }
+  }
+  const what = gate.verdict === 'mismatch'
+    ? `sha256 ${gate.actual} does not match the published ${gate.expected}`
+    : gate.reason;
+  log(`[amicus] Electron artifact REFUSED: ${fileName}`);
+  log(`[amicus]   ${zip}`);
+  log(`[amicus]   ${what}`);
+  log('[amicus] This is what a swapped mirror or a planted cache file looks like. It is ALSO');
+  log('[amicus] what a truncated download, a failing disk, or a mirror serving a REBUILT');
+  log('[amicus] electron looks like — amicus cannot tell them apart.');
+  // ORDER MATTERS. The advice comes BEFORE the removal notice, and says what to
+  // do about a file that is already gone: a hand-seeded air-gapped cache is the
+  // one place the refused artifact was also the ONLY copy, and being told about
+  // the hatch after "The file has been removed." is being told too late to use
+  // it. The delete itself is required (a poisoned zip must not survive to be
+  // re-offered); the words around it are what make it recoverable.
+  log('[amicus] If you deliberately run a REBUILT electron, set');
+  log('[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 BEFORE provisioning again — it accepts these');
+  log('[amicus] bytes on the cache path and drops the digest pin on the download path.');
+  log(`[amicus]   ${removed
+    ? 'The file has been removed: re-copy it from the machine that downloaded it (or let'
+      + '\n[amicus]   amicus download it again) once that variable is set.'
+    : 'The file was left in place.'}`);
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: gate.verdict,
+    reason: `Cached electron artifact ${fileName} was REFUSED: ${what}.`
+      + `${removed ? ' It has been removed.' : ' It was left in place.'}`,
+  };
+}
+
+/** The terminal path-traversal refusal `robustExtract` throws (unzip.js C4). */
+function isUnsafeArchive(err) {
+  return !!err && err.code === 'UNZIP_UNSAFE_ARCHIVE';
+}
+
+/**
+ * C4 AT THE CALL SITE. unzip.js classifies extract-zip's path-traversal refusals
+ * as terminal so the same archive is never handed to an OS extractor that has no
+ * such check. That invariant held only INSIDE unzip.js: both of repairElectron's
+ * catch blocks used to swallow the refusal without reading `err.code` and launder
+ * it back into exactly the retry the control forbids — the network path spawned
+ * `node <electronDir>/install.js`, which re-downloads and re-extracts through
+ * @electron-internal/extract-zip with no amicus supervision (the forbidden move,
+ * one stack frame up), and the cache path deleted the zip through the UNFENCED
+ * `fs.rmSync` and told the user it "was corrupt and removed" — a security refusal
+ * reported as corruption. MEASURED both, before this change.
+ *
+ * So the refusal ends here: no retry, no fallback extractor, and no delete. The
+ * archive is left where it is, because a refused archive is evidence, and
+ * `err.message` already carries the path and extract-zip's own reason.
+ * @returns {{repaired:false, integrity:'unsafe-archive', reason:string}}
+ */
+function refuseUnsafeArchive({ err, fileName, log = () => {} }) {
+  const detail = (err && err.message) || 'the archive tried to write outside its destination';
+  log(`[amicus] Electron artifact REFUSED (unsafe archive): ${fileName}`);
+  log(`[amicus]   ${detail}`);
+  log('[amicus] Entries in that zip tried to write OUTSIDE the destination directory. amicus');
+  log('[amicus] will not retry it with another extractor, and has left the file in place.');
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: 'unsafe-archive',
+    reason: `Electron artifact ${fileName} was REFUSED: ${detail}. It was NOT retried and NOT removed.`,
+  };
+}
+
+module.exports = {
+  cacheRootFor, controlledProvision, mayDeleteRejectedZip, rejectCachedZip, isUnsafeArchive, refuseUnsafeArchive,
+};

package/src/sidecar/electron-trust.js

@@ -0,0 +1,299 @@
+/**
+ * Electron artifact TRUST core — the digest anchor, the gate, and the env scrub.
+ *
+ * A hostile REPOSITORY (a clone the user opens, an unpacked sample) controls the
+ * `.npmrc` and `package.json` of the directory amicus's own docs tell people to
+ * run `npx -y amicus@latest` in. MEASURED (npm 11.16.0): that reaches the child
+ * as exactly two name shapes — `npm_config_<key lowercased>` and
+ * `npm_package_config_<key case-preserved>` — and NOTHING else. Bare `ELECTRON_*`
+ * and `AMICUS_*` names are out of its reach. THAT is the trust boundary this
+ * module encodes: the escape hatch can be a plain environment variable, and a
+ * machine-level `ELECTRON_MIRROR` can still be honoured, precisely because a
+ * repository cannot write either one.
+ *
+ * The control is the DIGEST, not the URL. Supplying `checksums` to
+ * `downloadArtifact` makes `@electron/get` write a LOCAL `SHASUMS256.txt` and
+ * never fetch one from the mirror (@electron/get 5.0.0, dist/index.js, lines
+ * 28-40), so an attacker who redirects the download still has to produce bytes that match
+ * electron's own published sha256. Blocking the URL itself is defence in depth on
+ * top of a control that already works, and is deliberately NOT built here.
+ *
+ * LEAF MODULE: `crypto` + `path` + `fs` and nothing from this repo. The arrow is
+ * electron-install -> electron-provision -> electron-trust and must never point
+ * back; src/utils/path-fence.js:11-17 records what a cycle does to a destructured
+ * import in exactly this cluster.
+ *
+ * @module sidecar/electron-trust
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fsDefault = require('fs');
+const path = require('path');
+
+/**
+ * Env-name PREFIXES an untrusted REPOSITORY can plant. MEASURED, npm 11: a repo
+ * .npmrc key `k` reaches an `npm run` / `npm exec` child as
+ * `npm_config_<k lowercased>`; a repo package.json "config" key `k` reaches it as
+ * `npm_package_config_<k>` with case preserved. Nothing else.
+ *
+ * PREFIXES, not a hand-maintained name list. Two prefixes cover every
+ * `@electron/get` mirror knob in each repo-reachable spelling, plus electron's
+ * own `npm_config_electron_use_remote_checksums` (electron's install.js, lines
+ * 47-50 — that name turns electron's bundled pin OFF), plus any knob a future
+ * @electron/get adds in the same namespace. Contrast ENGINE_CREDENTIAL_ENV
+ * (scripts/run-integration-keyless.js:101), whose own docblock warns that nothing
+ * makes a name list follow an upstream bump.
+ *
+ * The BARE `electron_use_remote_checksums` is deliberately NOT removed: a bare
+ * lower-case name is not repo-injectable, so it carries the machine owner's
+ * intent, exactly like a bare `ELECTRON_MIRROR`.
+ *
+ * MATCHED CASE-INSENSITIVELY. This used to fold no case, on the claim that
+ * because the Windows environment block is case-insensitive, deleting the
+ * lower-case name also removed the `NPM_CONFIG_ELECTRON_*` view @electron/get
+ * reads second. That is true of `process.env` and FALSE of the `{...env}` PLAIN
+ * OBJECT this module actually deletes from — a plain object is case-sensitive on
+ * every platform, so the upper-case key survived and was handed to the child.
+ * RE-MEASURED (npm 11.16.0, Windows 11) — two ways a repository reaches an
+ * upper-case slot:
+ *   1. `.npmrc` `electron_mirror=…` while `NPM_CONFIG_ELECTRON_MIRROR` already
+ *      exists in the environment: npm overwrites that slot's VALUE and never
+ *      renames it, so the child sees the ATTACKER's URL under the upper-case name.
+ *   2. `package.json` `"config": {"ELECTRON_MIRROR": …}`: npm PRESERVES the key's
+ *      case, planting `npm_package_config_ELECTRON_MIRROR` with nothing
+ *      pre-existing at all — and @electron/get's own lookup for
+ *      `npm_package_config_electron_mirror` (dist/artifact-utils.js, line 28) finds it,
+ *      because the Windows lookup is case-insensitive too.
+ * The old docblock's POSIX half (`NPM_CONFIG_ELECTRON_*` is a distinct variable
+ * npm never writes there, so it is the machine owner's) is NOT measurable from
+ * this machine, and it is load-bearing in the fail-OPEN direction: wrong, it
+ * hands the child an attacker's mirror. Wrong the other way it costs one
+ * alternate spelling inside a last-resort spawn, while bare `ELECTRON_MIRROR`
+ * — which @electron/get ranks FIRST — still carries owner intent. So the fold is
+ * unconditional rather than resting on an unverified platform claim.
+ */
+const REPO_ENV_PREFIXES = ['npm_config_electron_', 'npm_package_config_electron_'];
+
+/** electron's install.js, lines 20-21 and 99 — these choose WHICH artifact it
+ *  fetches, and `.npmrc` `platform=`/`arch=` plants both. Same case fold. */
+const ELECTRON_INSTALL_TARGET_ENV = ['npm_config_platform', 'npm_config_arch'];
+
+/** A published sha256 is 64 LOWER-case hex characters. Anything else is not an anchor. */
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/** Leading 'v' applied exactly once — matches @electron/get's normalizeVersion. */
+function normalizeV(version) {
+  const v = String(version || '');
+  return v.startsWith('v') ? v : `v${v}`;
+}
+
+/** True for a name a hostile repository could have planted, in ANY case (see above). */
+function isRepoPlantedName(name) {
+  const lower = String(name).toLowerCase();
+  return REPO_ENV_PREFIXES.some((prefix) => lower.startsWith(prefix))
+    || ELECTRON_INSTALL_TARGET_ENV.includes(lower);
+}
+
+/**
+ * The amicus-namespaced trust policy. THE ONLY place the escape hatch is read.
+ * Never reads npm_config_* / npm_package_config_* / NPM_CONFIG_* — those are the
+ * attacker's channel, and a rule that read its own writer's surface would be no
+ * rule at all.
+ *
+ * `allowUnverified` is true for the string '1' and NOTHING else — 'true', 'yes',
+ * ' 1' are all false. A hatch that fails open on a typo is not a hatch.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ allowUnverified: boolean }}
+ */
+function electronTrustPolicy(env = process.env) {
+  return { allowUnverified: env.AMICUS_ALLOW_UNVERIFIED_ELECTRON === '1' };
+}
+
+/** `electron-v43.1.1-win32-x64.zip`. Matches BOTH electron's checksums.json keys
+ *  and @electron/get's getArtifactFileName + normalizeVersion. */
+function artifactFileName({ version, platform, arch }) {
+  return `electron-${normalizeV(version)}-${platform}-${arch}.zip`;
+}
+
+/**
+ * The electron package THIS amicus resolves — resolveAnchor rung 1. Duplicated
+ * (not imported from electron-install.defaultElectronDir) so this module stays a
+ * leaf and the require arrow keeps pointing one way.
+ * @returns {string|null}
+ */
+function selfElectronPackageDir() {
+  try {
+    return path.dirname(require.resolve('electron/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+/** Parse one checksums.json into a table of ONLY well-formed rows. Never throws. */
+function readChecksumTable(file, fs) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { return null; }
+    const table = {};
+    for (const [name, digest] of Object.entries(parsed)) {
+      if (typeof digest === 'string' && HEX64.test(digest)) { table[name] = digest; }
+    }
+    return Object.keys(table).length > 0 ? table : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the digest ANCHOR, offline. Precedence, highest first:
+ *   1. <selfElectronDir>/checksums.json — the RUNNING amicus's own table.
+ *   2. <electronDir>/checksums.json — ONLY when rung 1 offers no usable table.
+ *
+ * RUNG 1 IS LOAD-BEARING, not a convenience. `doctor --fix`
+ * (src/utils/doctor-electron-mcp-check.js:122-137) hands `repairElectron` an
+ * electronDir found by a FILESYSTEM SCAN of npx caches, so rung 2 on its own
+ * would read the anchor out of the same untrusted directory the bytes came from
+ * — the pin would vouch for the attacker's own zip. Rung 1 is the same published
+ * data out of a tree npm installed for amicus itself, before any hostile
+ * directory was visited.
+ *
+ * WHY RUNG 1 NO LONGER TESTS THE VERSION. It used to apply only when the self
+ * package's version equalled the requested one — but the requested `version` is
+ * itself read out of `<electronDir>/package.json` whenever the caller supplies
+ * none (electron-install.js `if (!version)`), and the ONE production caller,
+ * doctor --fix, supplies none. MEASURED on this tree: a planted
+ * `{"version":"99.0.0"}` demoted rung 1 by DATA alone, the scanned tree's own
+ * checksums.json then vouched for its own bytes, and repairElectron returned
+ * `{repaired:true}` after extracting POISONED-BYTES. A rule that reads its own
+ * selector off the surface it exists to distrust is not a rule. No version check
+ * is needed to keep a genuine version disagreement honest, because the table is
+ * keyed by the FULL artifact filename: a self table for 43.1.1 simply holds no
+ * `electron-v99.0.0-…zip` row, `expectedDigest` returns null, and the gate's
+ * `no-digest` verdict extracts-and-MARKS exactly as the brief requires — never a
+ * refusal, never a re-download loop.
+ *
+ * Rung 2 therefore survives for exactly one case: amicus's own electron package
+ * ships no readable checksums.json (an old electron, or the optionalDependency
+ * never installed). There the target's table is all there is, and it is still
+ * better than nothing against a truncated download.
+ *
+ * Pass `selfElectronDir: null` to disable rung 1.
+ * NEVER THROWS. Rejects a table whose values are not 64 lower-case hex.
+ * @returns {{ table: Record<string,string>, source: string } | null}
+ */
+function resolveAnchor({ electronDir, fs = fsDefault, selfElectronDir } = {}) {
+  const self = selfElectronDir === undefined ? selfElectronPackageDir() : selfElectronDir;
+  for (const dir of [self, electronDir]) {
+    if (!dir) { continue; }
+    const source = path.join(dir, 'checksums.json');
+    const table = readChecksumTable(source, fs);
+    if (table) { return { table, source }; }
+  }
+  return null;
+}
+
+/** @returns {string|null} the 64-hex digest for one artifact, or null. */
+function expectedDigest(anchor, fileName) {
+  if (!anchor || !anchor.table) { return null; }
+  const digest = anchor.table[fileName];
+  return typeof digest === 'string' && HEX64.test(digest) ? digest : null;
+}
+
+/** Chunked sha256 (1 MiB buffer, openSync/readSync). SYNC so it composes with
+ *  repairElectron's injected `fs`; chunked so a ~170 MB zip is never buffered whole. */
+function sha256File(file, fs = fsDefault) {
+  const hash = crypto.createHash('sha256');
+  const buffer = Buffer.alloc(1024 * 1024);
+  const fd = fs.openSync(file, 'r');
+  try {
+    let read = fs.readSync(fd, buffer, 0, buffer.length, null);
+    while (read > 0) {
+      hash.update(buffer.subarray(0, read));
+      read = fs.readSync(fd, buffer, 0, buffer.length, null);
+    }
+  } finally {
+    try { fs.closeSync(fd); } catch { /* already closed */ }
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * THE GATE. NEVER THROWS. `allowed` is the single decision bit callers act on.
+ *
+ * @returns {{verdict:'verified',   allowed:true,  actual:string}
+ *         | {verdict:'mismatch',   allowed:boolean, expected:string, actual:string}
+ *         | {verdict:'no-digest',  allowed:true}
+ *         | {verdict:'unreadable', allowed:false, reason:string}}
+ *
+ * `no-digest` is ALLOWED and merely marked. An electron package that predates
+ * `checksums.json` has no anchor through no fault of its own, and refusing it
+ * would push that machine into a permanent re-download loop for a file no
+ * download can improve.
+ *
+ * `unreadable` is refused whatever the policy says: bytes that cannot be hashed
+ * cannot be extracted either, so there is nothing to fail open to.
+ */
+function verifyArtifact({ zip, anchor, fileName, policy = {}, fs = fsDefault, log = () => {} }) {
+  const expected = expectedDigest(anchor, fileName);
+  if (!expected) {
+    log(`[amicus] NOTE: no published sha256 for ${fileName} (this electron package ships no`);
+    log('[amicus]   checksums.json entry for it), so its bytes could not be verified.');
+    return { verdict: 'no-digest', allowed: true };
+  }
+  let actual;
+  try {
+    actual = sha256File(zip, fs);
+  } catch (e) {
+    return { verdict: 'unreadable', allowed: false, reason: `could not hash ${fileName}: ${(e && e.message) || e}` };
+  }
+  if (actual === expected) { return { verdict: 'verified', allowed: true, actual }; }
+  if (policy.allowUnverified) {
+    log(`[amicus] WARNING: AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — accepting ${fileName} even though`);
+    log(`[amicus]   its sha256 ${actual} does not match the published ${expected}.`);
+    log('[amicus]   Unset that variable to fail closed.');
+    return { verdict: 'mismatch', allowed: true, expected, actual };
+  }
+  return { verdict: 'mismatch', allowed: false, expected, actual };
+}
+
+/**
+ * A COPY of env for the runInstaller SPAWN. Never mutates the argument.
+ *
+ * electron's own install.js honours `npm_config_electron_mirror` (through
+ * @electron/get) AND `npm_config_electron_use_remote_checksums` (its lines 47-50,
+ * which turns its bundled pin off), so spawning it with an unfiltered
+ * `{...process.env}` would funnel a blocked attacker straight into an unpinned
+ * downloader. `npm_config_platform` / `npm_config_arch` (its lines 20-21 and 99)
+ * choose WHICH artifact it fetches, so they are removed too and amicus's own
+ * resolution is pinned through `ELECTRON_INSTALL_PLATFORM`/`_ARCH`, which
+ * install.js ranks above them.
+ *
+ * LEAVES ALONE, deliberately — every one of these is a BARE name a repository
+ * cannot plant, so it is the machine owner's: `ELECTRON_MIRROR`,
+ * `ELECTRON_CUSTOM_*`, `electron_config_cache`, `ELECTRON_CACHE`,
+ * `electron_use_remote_checksums`, `HTTP_PROXY`/`HTTPS_PROXY`/`ELECTRON_GET_USE_PROXY`.
+ */
+function scrubbedChildEnv({ env = process.env, platform, arch } = {}) {
+  const out = { ...env };
+  for (const name of Object.keys(out)) {
+    if (isRepoPlantedName(name)) { delete out[name]; }
+  }
+  if (platform) { out.ELECTRON_INSTALL_PLATFORM = platform; }
+  if (arch) { out.ELECTRON_INSTALL_ARCH = arch; }
+  return out;
+}
+
+module.exports = {
+  electronTrustPolicy,
+  resolveAnchor,
+  expectedDigest,
+  verifyArtifact,
+  sha256File,
+  artifactFileName,
+  scrubbedChildEnv,
+  normalizeV,
+  REPO_ENV_PREFIXES,
+  ELECTRON_INSTALL_TARGET_ENV,
+};

package/src/sidecar/fanout-leg-fallback.js

@@ -47,6 +47,7 @@ function recordAttemptSpend({ doc, leg, currentModel, legId, waveId, project, at
       project, attempt: leg && leg.attempt, substitutedFor: leg && leg.substitutedFor,
       retryOfWaveId: leg && leg.retryOfWaveId,
       tag: (leg && leg.tag) || null,
+      finish: doc.finish, variant: doc.variant, // #218 PR 3 / PR 4: appendSpend keeps each only when it is a string (named mutant "LEGROWNOVARIANT", tests/sidecar/fanout.test.js)
     };
     if (attempt > 0) { row.attempt = attempt; row.substitutedFor = originalModel; }
     appendSpend(row, deps.spendDir ? { dir: deps.spendDir } : undefined);

package/src/sidecar/fanout-leg.js

@@ -76,7 +76,7 @@ function buildRoutingFailureLeg({ leg, legId, waveId, quiet }) {
  * Adds `.reason` (alias of buildRunResult's `.error`) and `.legId` so the
  * fallback loop reads a stable shape without re-deriving them.
  */
-async function runSingleAttempt({ leg, legId, waveId, project, directory, follow, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce, noOutputBackstopMs }) {
+async function runSingleAttempt({ leg, legId, waveId, project, directory, follow, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, variant, quiet, foldNonce, noOutputBackstopMs }) {
   const { IdleWatchdog } = require('../utils/idle-watchdog');
   const { markAborted } = require('../utils/session-abort');
   const { runHeadless } = require('../headless');
@@ -123,7 +123,7 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
     result = await runHeadless(
       leg.model, systemPrompt, userMessage, legId, project,
       timeoutMs, agent || 'build',
-      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce, directory, noOutputBackstopMs }
+      { client, server, watchdog, summaryLength, variant, nonce: foldNonce, directory, noOutputBackstopMs }
     );
   } catch (err) {
     result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId: legId };
@@ -215,6 +215,14 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
     // nothing whichever one holds: it is one `&&` against a value already in a
     // register, and it is dead code if `result` is truly always assigned.
     ttftMs: result && isMeasuredTtft(result.ttftMs) ? result.ttftMs : undefined,
+    // #218 PR 3: the engine's `finish` for the leg's last assistant message
+    // ('length' = stopped at the reservation), emit-when-set like ttftMs above.
+    finish: (result && typeof result.finish === 'string') ? result.finish : undefined,
+    // #218 PR 4: the effort level SENT (emit-when-sent) and whether the engine's
+    // catalogue knew the model when it was sent. Named mutant "LEGVARIANTDROPPED"
+    // (tests/sidecar/fanout.test.js).
+    variant: (result && typeof result.variant === 'string') ? result.variant : undefined,
+    variantUnverified: (result && result.variantUnverified === true) ? true : undefined,
   };
   let finalMeta = legPatch;
   if (legDir) {

package/src/sidecar/fanout.js

@@ -246,7 +246,7 @@ async function runFanout(options) {
         HEARTBEAT_INTERVAL
       );
   const timeoutMs = (options.timeout || 15) * 60 * 1000;
-  const reasoning = options.thinking ? { effort: options.thinking } : undefined;
+  const variant = options.thinking || undefined; // #218 PR 4: one level for every leg, sent as the engine's `variant` field (named mutant "FANOUTVARIANTDROPPED", tests/sidecar/fanout.test.js: drop `variant` from the runLeg args)
   let legDocs;
   try {
     // retryContexts/retryOfWaveId (v4.3 Task 19): absent on a normal wave, so
@@ -261,7 +261,7 @@ async function runFanout(options) {
         systemPrompt: saved ? rc.systemPrompt : systemPrompt,
         userMessage: saved ? rc.userMessage : userMessage,
         timeoutMs, agent: options.agent, client, server,
-        summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
+        summaryLength: options.summaryLength, variant, quiet: options.quiet,
         foldNonce, directory: options.directory, follow,
         fallback: options.fallback, catalog: options.catalog, noOutputBackstopMs: options.noOutputBackstopMs,
       });

package/src/sidecar/interactive.js

@@ -18,6 +18,7 @@ const { canonicalProjectPath } = require('../utils/project-path');
 const { ensureElectron } = require('./electron-ensure');
 const { writeProgress } = require('./progress');
 const { getElectronPath, buildElectronEnv, handleElectronProcess } = require('./interactive-process');
+const { readOutputBudgetSafe } = require('../headless');
 
 /** Run sidecar in interactive mode (Electron GUI) */
 async function runInteractive(model, systemPrompt, userMessage, taskId, project, options = {}) {
@@ -33,7 +34,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     };
   }
 
-  const { agent, isResume, conversation, mcp, reasoning, opencodeSessionId, client, foldNonce } = options;
+  const { agent, isResume, conversation, mcp, variant, opencodeSessionId, client, foldNonce } = options;
 
   // F6c: mirror headless's lifecycle stages (best-effort — a write failure must
   // never break the GUI) so the heartbeat/status never read "Starting up...".
@@ -70,6 +71,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     };
   }
 
+  let sent = null; // #218 PR 4 whole-branch review (EP-4): what sendPrompt SENT, for the record
   // Create or reconnect to session
   let sessionId;
   try {
@@ -93,9 +95,29 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
 
       // Always set agent — defaults to 'chat' when not specified
       promptOptions.agent = agentConfig.agent;
-      if (reasoning) { promptOptions.reasoning = reasoning; }
-
-      await sendPromptAsync(ocClient, sessionId, promptOptions);
+      // #218 PR 4: the engine's `variant` field, validated in sendPrompt; the
+      // spawn-time budget rides the handle (PR 3). A refusal lands in the catch
+      // below as "Session setup failed: VARIANT_…" — nothing was sent.
+      // Named mutants "GUIBUDGETDROPPED" / "GUIREFUSALPREFIX" (tests/sidecar/interactive-variant.test.js).
+      if (variant) {
+        promptOptions.variant = variant;
+        promptOptions.outputBudget = readOutputBudgetSafe(server); // council #235 r1 (A1): the SAME reader headless uses (src/headless.js :: readOutputBudgetSafe) — the handle's spawn value, else config
+      }
+
+      const promptResult = await sendPromptAsync(ocClient, sessionId, promptOptions);
+      sent = promptResult && promptResult.sentVariant;
+      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`);
+      }
       progressStage('prompt_sent');
     }
     logger.debug('Interactive session ready', { sessionId, isResume: !!isResume });
@@ -201,6 +223,11 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
       } catch (err) { logger.debug('mirror stop failed', { error: err.message }); }
       try { await server.close(); } catch { /* best-effort */ }
       logger.debug('OpenCode server closed after Electron exit');
+      // #218 PR 4 whole-branch review (EP-4/REC-2/PRT-2): the level SENT rides the interactive
+      // result too (emit-when-sent, the derivation headless.js:811-814 makes), so start.js's
+      // writers stamp `variant` / `variantUnverified` for the default GUI mode as well.
+      // Named mutant "INTERACTIVEVARIANTDROPPED" (tests/sidecar/interactive-variant.test.js).
+      if (sent) { result.variant = sent.variant; if (!sent.verified) { result.variantUnverified = true; } }
       result.opencodeSessionId = sessionId;
       resolve(result);
     });