amicus 4.9.5 → 4.9.6

package/src/sidecar/electron-install.js

@@ -13,20 +13,32 @@
  * #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
+ *
+ * AT THE SIZE GATE, so pieces live next door: `./electron-custody` reads the
+ * artifact into memory once, `./zip-from-buffer` extracts what was read,
+ * `./electron-layout` holds `platformExe`/`writePathTxt`/`extractBytesToDist`
+ * (`platformExe` re-exported here for `ei.platformExe`), `./electron-refuse`
+ * holds the refusal messages, `./electron-repair-cache` the whole cached-artifact
+ * route, `./electron-provision` the pinned download. The arrow points one way out
+ * of this file and never back.
  */
 
 'use strict';
 
 const fsDefault = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
 
-const { resolveCacheRoots } = require('./electron-cache');
+const { cachedZip } = require('./electron-cache');
+const { isSafeArtifactName } = require('./electron-custody');
 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');
+const { platformExe } = require('./electron-layout');
+const { controlledProvision } = require('./electron-provision');
+const { repairFromCache } = require('./electron-repair-cache');
+const { isUnsafeArchive, refuseUnsafeArchive } = require('./electron-refuse');
+const { artifactFileName, electronTrustPolicy, resolveAnchor } = require('./electron-trust');
+const { extractZipBuffer } = require('./zip-from-buffer');
+const { collapseExcerpt } = require('../utils/text-sanitize');
 
 /** Self-heal progress line to stderr (visible during first-GUI provision). */
 function stderrLog(msg) {
@@ -42,19 +54,6 @@ function defaultElectronDir() {
   }
 }
 
-/** Platform exe basename, matching electron's getPlatformPath(). */
-function platformExe(platform) {
-  switch (platform) {
-    case 'mas':
-    case 'darwin':
-      return path.join('Electron.app', 'Contents', 'MacOS', 'Electron');
-    case 'win32':
-      return 'electron.exe';
-    default:
-      return 'electron';
-  }
-}
-
 /**
  * Resolve the on-disk electron exe path from the package layout.
  * Mirrors ELECTRON_OVERRIDE_DIST_PATH semantics (#59): when set, the exe is
@@ -92,47 +91,6 @@ function isElectronUsable({ electronDir = defaultElectronDir(), env = process.en
   }
 }
 
-/**
- * Locate a previously-downloaded electron zip in the env-configurable cache
- * roots. Walks <root>/<sha>/electron-v<ver>-<platform>-<arch>.zip.
- * @returns {string|null} absolute zip path, or null when no cache hit.
- */
-function cachedZip({ version, platform = process.platform, arch = process.arch, env = process.env, fs = fsDefault } = {}) {
-  const zipName = `electron-v${version}-${platform}-${arch}.zip`;
-  for (const root of resolveCacheRoots(env)) {
-    let shaDirs;
-    try {
-      shaDirs = fs.readdirSync(root);
-    } catch {
-      continue;
-    }
-    for (const sha of shaDirs) {
-      const candidate = path.join(root, sha, zipName);
-      try {
-        if (fs.existsSync(candidate)) {
-          return candidate;
-        }
-      } catch {
-        /* ignore unreadable subdir */
-      }
-    }
-  }
-  return null;
-}
-
-/** Restore path.txt so electron/index.js resolves the freshly-extracted exe. */
-function writePathTxt({ electronDir, platform, fs }) {
-  fs.writeFileSync(path.join(electronDir, 'path.txt'), platformExe(platform));
-}
-
-/** Extract a cached zip into <electronDir>/dist offline. */
-async function extractFromCache({ zip, electronDir, platform, extract, fs }) {
-  const distDir = path.join(electronDir, 'dist');
-  fs.mkdirSync(distDir, { recursive: true });
-  await extract(zip, { dir: distDir });
-  writePathTxt({ electronDir, platform, fs });
-}
-
 /** Bind the fs-aware probes for the post-extract AV-quarantine verify. */
 function verifyExtractOutcome({ electronDir, platform, fs }) {
   return verifyQuarantine({
@@ -142,37 +100,25 @@ function verifyExtractOutcome({ electronDir, platform, fs }) {
   });
 }
 
-/**
- * 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 = scrubbedChildEnv({ env: process.env, platform, arch });
-  if (force) {
-    env.force_no_cache = 'true';
-  }
-  return spawn(process.execPath, [installScript], { env, stdio: 'ignore' });
-}
-
 /**
  * Heal a broken electron install.
  *
  * @param {object} opts
  * @param {boolean} [opts.cacheOnly] never hit the network; return
  *   {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 {number}  [opts.timeoutMs] best-effort download timeout.
+ * @param {object}  [opts.deps] injected { cachedZip, extract, acquireLock, fs,
  *   selfElectronDir } — the last pins the digest anchor's top rung (null disables it).
+ *
+ * THERE IS NO `force` OPTION. There was, and it did nothing: it only ever set
+ * `force_no_cache` for the install.js spawn (now deleted), and `force` is DEAD
+ * in @electron/get 5.0.0 anyway — `effectiveCacheMode` never reads it, MEASURED.
+ * An accepted-but-inert flag is worse than no flag, so it is gone rather than
+ * documented.
  * @returns {Promise<{repaired?:boolean, deferred?:boolean, contended?:boolean, reason?:string}>}
  */
 async function repairElectron({
   cacheOnly = false,
-  force = false,
   timeoutMs,
   electronDir = defaultElectronDir(),
   platform = process.platform,
@@ -181,12 +127,22 @@ async function repairElectron({
   deps = {},
 } = {}) {
   const fs = deps.fs || fsDefault;
-  // Default extract: extract-zip bounded (idle/max) + native-unzip fallback (extract-zip-node24 stall).
+  // Default extract: from the BUFFER amicus already hashed, never from a name.
+  // `unzip.js` is byte-for-byte unchanged; the one thing still taken from it is
+  // its native PLAN, and only behind the hatch (see ./electron-native-rescue).
+  //
+  // WHAT CAME WITH IT AND WHAT DID NOT. Its idle + hard-cap STALL BOUND is
+  // reimplemented in `zip-from-buffer.js` with the same numbers, so this path is
+  // bounded again (it was not, for three commits). Its NATIVE OS unzip fallback
+  // is NOT the default and never can be: `tar`/`Expand-Archive`/`ditto`/`unzip`
+  // all take a path, and feeding one either the artifact or a temp copy of our
+  // Buffer undoes the custody property outright. C2 re-wires it as a RESCUE for
+  // ONE failure class, reachable only with AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 —
+  // the flag whose documented meaning is already "I accept bytes amicus cannot
+  // vouch for". `spawn` is threaded for it, and stays injectable for tests.
   const extract = deps.extract
-    || ((zipPath, o) => robustExtract(zipPath, { ...o, platform, deps: { fs, log: stderrLog } }));
-  // 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 }));
+    || ((bytes, o) => extractZipBuffer(bytes, { ...o, deps: { fs, log: stderrLog } }));
+  const spawn = deps.spawn;
   const findZip = deps.cachedZip || ((o) => cachedZip(o));
   const acquireLock = deps.acquireLock || ((o) => acquireRepairLock({ ...o, fs }));
   // Lazy: import the ESM-only @electron/get only on the network path, so cacheOnly
@@ -204,6 +160,15 @@ async function repairElectron({
   // 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 });
+  // F#3: `version` may have just been read out of an UNTRUSTED <electronDir>/
+  // package.json (doctor --fix supplies none, for a dir it found by scanning npx
+  // caches), and `fileName` is joined into paths downstream. MEASURED before the
+  // check, with a planted "43.1.1/../../victim": a path two levels outside the
+  // intended directory was written and a pre-existing file there was destroyed.
+  // Nothing downstream ever sees a name that is not a plain filename.
+  if (!isSafeArtifactName(fileName)) {
+    return { repaired: false, integrity: 'unsafe-name', reason: `Refusing to provision electron: ${collapseExcerpt(fileName, 160)} is not a usable artifact name.` };
+  }
   const policy = electronTrustPolicy(process.env);
   const anchor = resolveAnchor({ electronDir, fs, selfElectronDir: deps.selfElectronDir });
 
@@ -220,36 +185,18 @@ async function repairElectron({
 
   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).
+    // Attempt 1: extract from cache (always preferred, fully offline). The whole
+    // route lives in ./electron-repair-cache — read once into memory, hash THOSE
+    // bytes, extract THOSE bytes — and answers `done` when nothing is left to try.
     const zip = findZip({ version, platform, arch, env: process.env, fs });
     if (zip) {
-      // 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.
-        }
-      }
+      const attempt = await repairFromCache({
+        zip, fileName, anchor, policy, electronDir, platform, arch, version, cacheOnly,
+        extract, verifyOutcome: () => verifyExtractOutcome({ electronDir, platform, fs }),
+        fs, spawn, env: process.env, log: stderrLog,
+      });
+      if (attempt.done) { return attempt.result; }
+      refusal = attempt.refusal;
     } else if (cacheOnly) {
       return { deferred: true, reason: `No cached electron zip found for v${version} (${platform}-${arch}); deferring download.${avHint(platform)}` };
     }
@@ -257,32 +204,75 @@ async function repairElectron({
     // 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;
+    // A non-null `provision` means download + extract returned without throwing;
+    // its `pinned:false` means the extracted bytes were vouched for only by the
+    // mirror — either no `checksums` went out (no anchor row, or the hatch dropped
+    // the pin) or amicus's own hash of the bytes it read did not say `verified`.
+    // F3 marks that, as both docs already promise it does.
+    let provision = null;
+    let provisionReason = null;
     try {
       const downloadArtifact = await resolveDownloadArtifact();
-      await controlledProvision({
-        electronDir, platform, arch, version, anchor, downloadArtifact, extract, extractFromCache,
-        fs, env: process.env, downloadMs: timeoutMs, policy, log: stderrLog,
+      const result = await controlledProvision({
+        electronDir, platform, arch, version, anchor, downloadArtifact, extract,
+        fs, spawn, env: process.env, downloadMs: timeoutMs, policy, log: stderrLog,
       });
-      controlledExtracted = true; // download + extract returned without throwing
+      // F3 (seat B4) — FAIL CLOSED ON A SHAPE NOBODY RECOGNISES. This used to be
+      // `|| { pinned: false }`, described as "an unrecognisable return marks,
+      // never claims a pin". It did worse than that: a function that returned
+      // NOTHING became a successful unpinned provision, so `verifyExtractOutcome`
+      // ran on a directory nothing had written and reported the missing exe as
+      // the AV-QUARANTINE signature — "electron.exe was removed right after it
+      // was extracted", advice about an extraction that never happened. An
+      // unrecognised return is a FAILURE, reported through the same path a throw
+      // takes, because that path already says the true thing.
+      if (!result || typeof result !== 'object' || typeof result.pinned !== 'boolean') {
+        throw Object.assign(
+          new Error(`the controlled provision returned no usable result (${result === undefined ? 'undefined' : typeof result})`),
+          { code: 'PROVISION_NO_RESULT' },
+        );
+      }
+      provision = result;
     } 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.
+      // C4: an unsafe archive is terminal — it is never retried through another
+      // extractor, and it is not reported as an ordinary failure.
       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, platform, arch }); } catch { /* ignore */ }
+      // B1: this is where the last-resort install.js spawn used to be. It is gone
+      // (see electron-provision.js), so the failure is REPORTED rather than
+      // routed around. `provision` stays null and `out.repaired` is the honest
+      // stat of the exe, but the REASON must survive — a bare {repaired:false}
+      // is what made a failed provision indistinguishable from "not provisioned".
+      provisionReason = collapseExcerpt((provisionErr && provisionErr.message) || String(provisionErr));
+      stderrLog(`[amicus] the controlled Electron download did not complete: ${provisionReason}`);
+      stderrLog('[amicus] Headless runs and the council work without the GUI.');
+    }
+    // F#2: the download hashed the bytes it read and refused them, or could not
+    // read them at all. Nothing was extracted, so there is no outcome to verify —
+    // return the refusal, carrying any cache refusal that preceded it.
+    if (provision && provision.refused) {
+      // A4/D4: this used to drop the cache refusal whenever the two shared an
+      // `integrity` class — so TWO mismatches (a poisoned cache entry AND a
+      // hostile mirror, the single most alarming pair this code can observe)
+      // reported only the second, and never told the user the cached artifact had
+      // also been refused and possibly deleted. Dedupe on the SENTENCE instead:
+      // identical text is noise, a different path or a different digest is not.
+      const carried = refusal && refusal.reason !== provision.refused.reason ? refusal.reason : null;
+      return { ...provision.refused, reason: [carried, provision.refused.reason].filter(Boolean).join(' ') };
     }
     // A NON-throwing controlled extract that left no usable exe is the
     // AV-quarantine signature — surface it actionably (no false success, no loop).
-    const out = controlledExtracted
+    const out = provision
       ? 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(' ') }; }
+    if (!out.repaired && (refusal || provisionReason)) {
+      const parts = [refusal && refusal.reason, provisionReason && `The controlled download failed: ${provisionReason}.`, out.reason];
+      return { ...out, ...(refusal ? { integrity: refusal.integrity } : {}), reason: parts.filter(Boolean).join(' ') };
+    }
+    // F3: the SAME mark the cache route already applies, on the route that omitted it.
+    if (out.repaired && provision && !provision.pinned) { return { ...out, unverified: true }; }
     return out;
   } finally {
     try { lock.release(); } catch { /* ignore */ }

package/src/sidecar/electron-layout.js

@@ -0,0 +1,300 @@
+/**
+ * The on-disk LAYOUT of an installed `electron` package: where the executable
+ * lives, and how VERIFIED BYTES become a `dist/`.
+ *
+ * Layout (npm `electron`): `path.txt` -> the exe basename, `dist/<exe>` -> the
+ * binary. A promote writes `path.txt` FIRST and puts back what it overwrote on
+ * every failure exit, so one that fails breaks nothing that resolved (`promoteDist`).
+ *
+ * SPLIT OUT of electron-install.js (v4.9.6, second council round): that file is
+ * at the repo's 300-line gate, and the round's repairs had to land inside
+ * `repairElectron` itself. These functions answer "where does the package keep
+ * its exe", which is a different question from "how do I heal a broken install".
+ *
+ * WHAT CHANGED IN THE SECOND ROUND. `extractFromCache({zip, ...})` is GONE. It
+ * took a PATH, which is the whole finding: the bytes that were hashed and the
+ * bytes an extractor re-opens at a path are not the same bytes when the attacker
+ * shares our uid. Its replacement, `extractBytesToDist`, takes a BUFFER the
+ * caller already hashed and writes `dist/` by extract-into-incoming + promote
+ * (see `promoteDist`).
+ *
+ * TRUE LEAF: `path` only, with `fs` and the extractor injected by the caller —
+ * so electron-provision.js requires it too without any risk of a cycle.
+ *
+ * @module sidecar/electron-layout
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const path = require('path');
+
+/** Platform exe basename, matching electron's getPlatformPath(). */
+function platformExe(platform) {
+  switch (platform) {
+    case 'mas':
+    case 'darwin':
+      return path.join('Electron.app', 'Contents', 'MacOS', 'Electron');
+    case 'win32':
+      return 'electron.exe';
+    default:
+      return 'electron';
+  }
+}
+
+/** Write path.txt: the basename `electron/index.js` joins onto `dist/`. */
+function writePathTxt({ electronDir, platform, fs }) {
+  fs.writeFileSync(path.join(electronDir, 'path.txt'), platformExe(platform));
+}
+
+/**
+ * The two litter prefixes this module creates, and how long one may survive.
+ *
+ * WHY A SWEEPER EXISTS AT ALL. Both trees are removed in the happy path — the
+ * retired one right after the swap, the incoming one in `extractBytesToDist`'s
+ * `finally` — and the docs said "a killed run leaves nothing to sweep up". That
+ * was MEASURED FALSE twice. A `finally` does not run for a SIGKILL, a Ctrl-C
+ * during `npm install`, a laptop lid close or an AV kill: a child SIGKILLed
+ * mid-extract left `.amicus-incoming-<hex>` holding a partial tree, and a
+ * subsequent `extractBytesToDist` on the same electronDir did not remove it. And
+ * the retired tree leaks on its own path: on Windows 11 / NTFS with a process
+ * running from `dist\\electron.exe`, `renameSync(dist, retired)` SUCCEEDS and the
+ * follow-up `rmSync(retired)` fails EPERM with every entry still present — so
+ * any repair that runs while an Electron is live off that tree strands the whole
+ * previous ~350 MB dist, and the code comment said "swept next time" naming a
+ * sweep that did not exist.
+ *
+ * Unlike the `amicus-electron-stage-*` litter this design replaced, these live
+ * INSIDE the electron package directory, where no OS temp cleaner ever reaches
+ * them. Ten interrupted provisions on a CI box was ten abandoned trees with no
+ * code path that would ever remove them.
+ *
+ * THE AGE RULE, and why it is not zero. A provision holds the per-electronDir
+ * repair lock, so in production nothing else is mid-extract in this directory —
+ * but `promoteDist` and `extractBytesToDist` are callable without that lock, and
+ * deleting a tree another process is actively writing is a worse failure than
+ * leaving one behind. So the sweep takes only what is older than
+ * `LITTER_MAX_AGE_MS`, which is the rule the deleted `sweepStaleStages` used and
+ * the rule the docs stated honestly before this design replaced them: the next
+ * provision sweeps any that is more than a day old.
+ */
+const LITTER_PREFIXES = ['.amicus-incoming-', '.amicus-retired-'];
+const LITTER_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Remove abandoned incoming/retired trees from `electronDir`. BEST-EFFORT: a
+ * tree that cannot be stat'ed or removed is left for the next run, and nothing
+ * here can fail a provision.
+ *
+ * @param {object} o
+ * @param {string} o.electronDir
+ * @param {object} o.fs
+ * @param {number} [o.maxAgeMs]
+ * @param {number} [o.now]
+ * @param {string} [o.keep] an absolute path never to remove (this run's own)
+ * @returns {string[]} the names actually removed
+ */
+function sweepPromoteLitter({
+  electronDir, fs, maxAgeMs = LITTER_MAX_AGE_MS, now = Date.now(), keep = null,
+}) {
+  let names;
+  try {
+    names = fs.readdirSync(electronDir);
+  } catch {
+    return [];
+  }
+  const swept = [];
+  for (const name of names) {
+    if (!LITTER_PREFIXES.some((p) => name.startsWith(p))) { continue; }
+    const full = path.join(electronDir, name);
+    if (keep && full === keep) { continue; }
+    try {
+      if (now - fs.statSync(full).mtimeMs < maxAgeMs) { continue; }
+      fs.rmSync(full, { recursive: true, force: true });
+      swept.push(name);
+    } catch { /* a tree we cannot stat or remove waits for the next run */ }
+  }
+  return swept;
+}
+
+/**
+ * RETIRE AND SWAP. Move a freshly-extracted tree into place as `dist/`, and
+ * leave the previous one recoverable until the swap has actually happened.
+ *
+ * WHY NOT EXTRACT STRAIGHT INTO `dist/`, which is what every earlier cut did.
+ * Because a half-written `dist/` IS a shape the rest of the self-heal cluster
+ * reads as an install: `isElectronUsable` stats the exe, `verifyExtractOutcome`
+ * calls a non-throwing extract with no exe the AV-quarantine signature. A kill
+ * or an ENOSPC halfway through a 347 MB write used to leave exactly that, on top
+ * of whatever was there before. Extraction now lands in
+ * `<electronDir>/.amicus-incoming-<hex>/dist`, so a partial tree is never in the
+ * place anything looks, and `dist/` changes in ONE rename.
+ *
+ * ORDER, and what survives each failure:
+ *   0. write `path.txt` unless already right — a throw REFUSES, and puts it back
+ *   1. rename `dist` -> `.amicus-retired-<hex>`   — old tree still whole, elsewhere
+ *   2. rename `<incoming>/dist` -> `dist`         — the swap
+ *   3. on a step-2 failure, rename the retired tree BACK                (rollback)
+ *   4. delete the retired tree, then the incoming directory       (best-effort)
+ *
+ * WHAT A STEP-1 FAILURE MAY DO, AND THE CLAIM THAT WAS MEASURED FALSE. Step 1
+ * failing means the old tree cannot be MOVED (a Windows handle held on the live
+ * tree; an AV filter driver denying MoveFile on a tree holding a freshly written
+ * electron.exe — this module's most-documented field failure). This used to fall
+ * back to `rmSync(distDir)`, which is IRREVERSIBLE and has no rollback, while
+ * the docblock asserted "No exit path can leave the user with neither the old
+ * tree nor the new one".
+ *
+ * MEASURED FALSE (injected fs, every `renameSync` throwing EPERM, real
+ * `rmSync`): the catch deleted the working tree, `retiredExists` stayed false,
+ * the step-2 rename then failed with NO rollback, and `extractBytesToDist`'s
+ * `finally` deleted the new tree immediately afterwards —
+ * `{"threw":"EPERM","distExists":false,"userHasOldTree":false}`. A user who had
+ * a working GUI was left with an electron package holding no `dist/` at all,
+ * and the caller then downloaded 138 MB and repeated the same promote.
+ *
+ * So the in-place removal now happens ONLY when there is nothing to lose: a
+ * `dist/` that holds no `platformExe` is not an install, and destroying it costs
+ * the user nothing they had. When the old tree DOES hold an executable, the
+ * promote REFUSES and that tree is untouched — the repair fails, which is
+ * strictly better than a working GUI becoming no GUI.
+ *
+ * THE GUARANTEE, stated so it is checkable:
+ *   **A promote never removes a `dist/` that held an executable unless the new
+ *   tree is already in its place.**
+ * The one exit that can still leave a user without a usable `dist/` is both
+ * renames failing after step 1 SUCCEEDED. The old tree is then whole and
+ * undeleted at `.amicus-retired-<hex>`, and the thrown message names it so the
+ * user can rename it back.
+ *
+ * `path.txt` IS WRITTEN FIRST (B2). Writing it LAST made "dist but no path.txt"
+ * unobservable only while that write SUCCEEDED, and it ran after the old tree was
+ * retired AND DELETED, so one ENOSPC/EPERM/AV-locked 12-byte write left a `dist/`
+ * that `electron/index.js` cannot resolve — amicus's own resolver falls back to
+ * `platformExe`, that entry point does not. RULING on undoing the pre-write:
+ * usually nothing to undo — the old tree resolved through that same string, and an
+ * absent or EMPTY `path.txt` resolves through it in both resolvers — but it BREAKS
+ * on one naming a DIFFERENT basename (`npm_config_platform` cross-installs one).
+ * So step 0 sits INSIDE the same `try` as the swap, and its own refusal puts the
+ * value back too: the write TRUNCATES at open (MEASURED — a real 12-byte path.txt
+ * is 0 bytes after `openSync(p,'w')`, before any write can fail), so a refusal
+ * that skipped the put-back destroyed the value it existed to keep. Best-effort:
+ * a put-back that itself fails, or an UNREADABLE path.txt, loses the old basename.
+ * @param {object} o
+ * @param {string} o.electronDir
+ * @param {string} o.incomingDist the extracted tree to promote
+ * @param {string} o.platform
+ * @param {object} o.fs
+ */
+function promoteDist({ electronDir, incomingDist, platform, fs }) {
+  const distDir = path.join(electronDir, 'dist');
+  const pathFile = path.join(electronDir, 'path.txt');
+  let replaced = null;                    // step 0's overwritten DIFFERENT value
+  try { replaced = fs.readFileSync(pathFile, 'utf8'); } catch { /* absent or unreadable */ }
+  try {
+    if (replaced === platformExe(platform)) { replaced = null; } else {
+      try { writePathTxt({ electronDir, platform, fs }); } catch (e) {
+        throw new Error(`${(e && e.message) || e} — path.txt could not be written, so the promote was refused and dist/ is exactly as it was`);
+      }
+    }
+    const retired = path.join(electronDir, `.amicus-retired-${crypto.randomBytes(6).toString('hex')}`);
+    let retiredExists = false;
+    if (fs.existsSync(distDir)) {
+      try {
+        fs.renameSync(distDir, retired);
+        retiredExists = true;
+      } catch (e) {
+        // The old tree cannot be moved. Removing it in place is irreversible, so
+        // it is allowed only when the tree is not an install anyway.
+        if (fs.existsSync(path.join(distDir, platformExe(platform)))) {
+          throw new Error(`${(e && e.message) || e} — the existing dist/ holds a usable `
+            + `${platformExe(platform)} and was left exactly as it was`);
+        }
+        fs.rmSync(distDir, { recursive: true, force: true });
+      }
+    }
+    try {
+      fs.renameSync(incomingDist, distDir);
+    } catch (e) {
+      if (retiredExists) {
+        try {
+          fs.renameSync(retired, distDir);
+        } catch {
+          // Both renames failed. The retired tree is WHOLE and is NOT deleted —
+          // say where it is, because this is the only exit that leaves a user
+          // without the dist/ they had.
+          throw new Error(`${(e && e.message) || e} — the previous dist/ is intact at `
+            + `${path.basename(retired)}; rename it back to dist/ to restore it`);
+        }
+      }
+      throw e;
+    }
+    if (retiredExists) { try { fs.rmSync(retired, { recursive: true, force: true }); } catch { /* sweepPromoteLitter takes it */ } }
+  } catch (e) {                           // EVERY exit undoes step 0 (see the RULING)
+    if (replaced !== null) { try { fs.writeFileSync(pathFile, replaced); } catch { /* best-effort; the tree is what matters */ } }
+    throw e;
+  }
+}
+
+/**
+ * A failure that is about the DESTINATION, not the archive.
+ *
+ * The distinction is load-bearing, and getting it wrong here was MEASURED on
+ * this very function: an EPERM from `renameSync` (a Windows handle held on the
+ * live `dist/`) propagated out untagged, `repairFromCache` read "an extract
+ * failure I cannot classify" as "the archive is bad", and DELETED the user's
+ * cached artifact while telling them it "was corrupt and removed". The archive
+ * was fine; the promote was not. Council finding D2 is the same shape one
+ * function away, and this is the second place it could bite.
+ */
+function destinationFailure(e, what) {
+  const err = new Error(`could not ${what}: ${(e && e.message) || e}`);
+  err.code = 'UNZIP_DEST_FAILED';
+  return err;
+}
+
+/**
+ * Turn VERIFIED BYTES into `<electronDir>/dist`, offline.
+ *
+ * `bytes` is a Buffer whose sha256 the caller has ALREADY matched against the
+ * anchor. There is no `zip` parameter and no path to the artifact anywhere in
+ * this call, which is the property the whole change exists to establish:
+ * **amicus never itself writes bytes it did not hash.**
+ *
+ * `extract` is injected — `zip-from-buffer.extractZipBuffer` in production —
+ * and receives the Buffer, never a name.
+ *
+ * It also SWEEPS, first: the incoming tree is removed in a `finally`, which a
+ * kill does not run, and the retired tree's removal can fail EPERM while an
+ * Electron is live off it. Both leak inside the electron package directory,
+ * where no OS temp cleaner reaches them. See `sweepPromoteLitter`.
+ * @returns {Promise<void>}
+ */
+async function extractBytesToDist({ bytes, electronDir, platform, extract, fs }) {
+  const incoming = path.join(electronDir, `.amicus-incoming-${crypto.randomBytes(6).toString('hex')}`);
+  const incomingDist = path.join(incoming, 'dist');
+  // A killed run's `finally` never ran, and an EPERM `rmSync` of a retired tree
+  // never finished. Take what they left before adding one more.
+  sweepPromoteLitter({ electronDir, fs, keep: incoming });
+  try {
+    try {
+      fs.mkdirSync(incomingDist, { recursive: true });
+    } catch (e) {
+      throw destinationFailure(e, `create ${incomingDist}`);
+    }
+    // NOT wrapped: the extractor classifies its own failures, and an archive
+    // failure must keep saying so — it is the one thing that may evict.
+    await extract(bytes, { dir: incomingDist });
+    try {
+      promoteDist({ electronDir, incomingDist, platform, fs });
+    } catch (e) {
+      throw destinationFailure(e, 'promote the extracted tree into dist/');
+    }
+  } finally {
+    try { fs.rmSync(incoming, { recursive: true, force: true }); } catch { /* litter, not a failure */ }
+  }
+}
+
+module.exports = {
+  platformExe, writePathTxt, promoteDist, extractBytesToDist, sweepPromoteLitter, LITTER_MAX_AGE_MS,
+};