amicus 4.9.5 → 4.9.7

package/docs/electron-testing.md

@@ -469,3 +469,136 @@ setTimeout(() => { ws.close(); process.exit(0); }, 3000);
 ```
 
 **Note:** `window.sidecar` is `undefined` in the toolbar (see Known Limitations above). The toolbar communicates with the main process via `window.__amicusUpdateAction` polling, not IPC.
+
+---
+
+## The darwin `.app` bundle — what CI proves, and what it still does not
+
+`.github/workflows/darwin-bundle.yml` drives `scripts/probe-darwin-extract.js` on
+`macos-latest`. It is the only place amicus's real extract path meets a real `.app`
+bundle, a real POSIX `fs.symlinkSync`, a real `fs.realpathSync` and a real dyld.
+
+### The filing it closes, and the way it closes it
+
+v4.9.6 added a symlink target-escape check (`src/sidecar/zip-entry-write.js ::
+writeSymlink`) that `extract-zip` does not have. The v4.9.7 filing was that it could
+**reject** a real darwin layout. That is **refuted by measurement on the real bytes**,
+not by this job:
+
+| artifact | bytes | records | symlinks | dir entries |
+| --- | --- | --- | --- | --- |
+| `electron-v43.1.1-darwin-arm64.zip` | 122,054,683 | 585 | 14 | 310 |
+| `electron-v43.1.1-darwin-x64.zip` | 123,952,132 | 585 | 14 | 310 |
+| `electron-v43.1.1-linux-x64.zip` | 124,861,804 | 74 | **0** | 0 |
+| `electron-v43.1.1-linux-arm64.zip` | 124,456,257 | 74 | **0** | 0 |
+
+All 14 darwin targets are relative (`A`, `Versions/Current/Resources`, …); none carries a
+`..` component; none is absolute; **0 of the 585 entry names traverse a symlinked
+component**. The check is purely lexical (`path.resolve` then `path.relative`), so on that
+shape it cannot fire. The extraction root is itself realpath'd
+(`src/sidecar/zip-from-buffer.js :: extractZipBuffer`), which is why macOS's
+`/var` -> `/private/var` does not turn every link into an escape — the one mechanism that
+could have made the filing correct.
+
+**Linux is settled outright and gets no job**: both linux artifacts hold 74 entries and
+zero symlinks, so `writeSymlink` is unreachable there. The filing's "darwin/linux" narrows
+to "darwin".
+
+### What each assertion pins, and the mutant it kills
+
+| id | assertion | mutant it kills |
+| --- | --- | --- |
+| A1a | `resolveAnchor({selfElectronDir: null})` reads the `checksums.json` under test | dropping the `selfElectronDir` override, which silently re-anchors on the repo's own `node_modules` |
+| A1b | `repairElectron({cacheOnly:true})` repairs **and** the gate says `verified` | any change that stops a byte-exact artifact verifying — extract and exec both stay green |
+| A1c | with **no** anchor the same bytes extract but are marked `unverified` | dropping the `verdict !== 'verified'` mark, i.e. a silent degrade of the trust route |
+| A2 | `resolveElectronBinary` names the real launcher and its exec bit survived | a wrong `platformExe` darwin arm, or a `path.txt` naming a different basename |
+| A3a | all 14 archive symlinks are symlinks on disk with byte-identical targets | deleting the `if (symlink)` branch in `placeEntry` — links become regular files |
+| A3b | the five structural framework links exist with their exact targets | writing the **resolved absolute** path instead of the archive's relative target (still runs on the runner; breaks when the tree moves) |
+| A4 | parity vs the tree `@electron-internal/extract-zip` produced | a flat file mode, or a `continue` that silently drops entries — **report-only on its first cut** |
+| A5 | `Electron --version` runs | the same mutant as A3a, observed through dyld: the launcher's Mach-O carries `LC_RPATH @executable_path/../Frameworks` and `LC_LOAD_DYLIB @rpath/Electron Framework.framework/Electron Framework`, so it loads the ~192 MB framework **through two of the fourteen links** |
+| A6i | an escaping relative target is refused, nothing planted | dropping the `..`-prefix limbs of the three-limb test |
+| A6ii | an **absolute POSIX** target is refused | dropping the `startsWith('..' + sep)` limb — on win32 `/etc/passwd` becomes `C:\etc\passwd` and a *different* limb catches it, so the Windows suite proves the wrong arithmetic |
+| A6iii | SYMLINKCHAIN refused by a **real** `realpath`: 3 links made, no victim | reverting the target resolution to `path.dirname(dest)` — the lexical-dirname bug that extracts with no error at all |
+
+A4 is deliberately **report-only, exit 0, full diff printed** on its first cut: nothing has
+ever measured that the two extractors agree on directory modes under the runner's umask, so
+making an unmeasured comparison a blocking gate buys a red for reasons unrelated to
+symlinks. Promote it once one clean run exists. Everything else gates from day one.
+
+A6iii is the assertion that matters most: in the jest suite the same archive is pinned by a
+`realpathSync` **the test itself injects** (`tests/electron-custody.test.js`, describe
+`symlinks — the darwin .app shape, which cannot be run here`). That is a rule read off the
+surface its own writer wrote. On the runner the three `.` links exist on disk and the kernel
+answers.
+
+### `npm ci` does NOT provision Electron — the job asks for it explicitly
+
+`electron@43.1.1` ships **no install script at all**: its `package.json` has no `scripts`
+field (it exposes `install.js` only as the `install-electron` bin), and `package-lock.json`
+carries no `hasInstallScript` for it. So npm never fetches the ~122 MB binary, on any
+platform or any install path. Measured on run `34246117877`: plain `npm ci` on ubuntu,
+macos and windows alike finished in 15-38 s and left amicus's own postinstall reporting
+`the Electron GUI binary is not provisioned yet` — an empty electron cache. The lockfile's
+per-platform installable counts (588 / 588 / 587) match the observed `added N packages`
+exactly **with `electron` included**, so the package is present and only the binary is
+missing.
+
+The job therefore runs `node node_modules/electron/install.js` in its own step, with one
+retry. It deliberately does **not** use `AMICUS_PREFETCH_ELECTRON=1`, which
+`scripts/postinstall.js` routes through amicus's own `repairElectron` — the A4 diff would
+then compare amicus against amicus.
+
+### What it does not prove
+
+- **darwin x64.** `macos-latest` is arm64. The x64 artifact was measured at an identical
+  shape (585 / 14 / 310), so the residual is small, but no x64 leg exists. Intel runner
+  labels changed during 2025 — check GitHub's current list before adding one.
+- **`mas`.** Unreachable in production; no caller passes `platform: 'mas'`.
+- **A case-sensitive APFS volume.** Runners default to case-insensitive; 0 case-insensitive
+  name collisions were measured across the 585 entries, but "low exposure" there is
+  inference, not measurement.
+- **Future electron layouts, between bumps.** The job proves the version pinned in
+  `package-lock.json` at run time. A bump is caught by the `package-lock.json` path filter on
+  `pull_request`/`push`, not by the cron.
+- **The native-rescue hatch.** `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1`, `ditto` and Info-ZIP
+  `unzip` symlink behaviour on darwin stay unmeasured — that is the B2 lane, not this one.
+- **`codesign`.** The archive carries **zero** `_CodeSignature` entries, so
+  `codesign --verify` on the extracted bundle would assert nothing. Only the embedded ad-hoc
+  Mach-O signature exists, and A5 succeeding is the only evidence it survived byte-exact
+  extraction. Do not add a codesign step and call it coverage.
+- **Destination-failure classification on darwin** (ENOSPC, read-only `dist/`, EACCES) and
+  **`promoteDist` on APFS** — the job calls the promote once, on a happy path.
+- **A trailing-slash symlink entry.** An entry whose *name* ends with `/` while its mode bits
+  say `IFLNK` is turned into a real directory before the symlink branch is reached, so the
+  escape check never runs. The real artifact has zero such entries, so no darwin job will
+  ever exercise it; it belongs in the platform-independent suite.
+
+### Triggers, cost, and the required-check caveat
+
+Paths-filtered `pull_request` **and** `push: [main]` (so a bump is proven at merge time),
+plus a weekly cron and `workflow_dispatch`. The cron re-proves the pinned version against the
+live release asset and the current runner image — the two inputs no path filter can see — and
+is the weakest trigger on purpose: a schedule GitHub delays or drops is silent.
+
+The job owns a ~122 MB download plus two ~600 MB extractions on a 3-vCPU / 8 GB runner;
+budget 4-6 minutes. It is not free, and macOS *concurrency* rather than minutes is the
+binding constraint on a public repo — `ci.yml` already burns two macOS legs per push.
+
+Because both event triggers carry a `paths:` filter, the job reports **skipped** when nothing
+matches, so **it cannot be a required status check as written**. Making it required means
+dropping `paths:` and moving the guard inside the job (a `git diff --name-only` early exit) —
+a pattern this repo does not currently use.
+
+### Running it by hand on a Mac
+
+```bash
+npm ci --foreground-scripts
+rm -rf node_modules/electron/dist node_modules/electron/path.txt
+node node_modules/electron/install.js          # the artifact + the A4 reference tree
+node scripts/probe-darwin-extract.js --preflight
+node scripts/probe-darwin-extract.js
+```
+
+The `rm -rf` is not cosmetic: `install.js` short-circuits on a populated `dist/`, and on a dev
+Mac that `dist/` may well be amicus's own self-heal output — which would make A4 compare
+amicus against amicus. The workflow does the same removal for the same reason.

package/docs/troubleshooting.md

@@ -421,18 +421,118 @@ The refused bytes are never extracted, so no Electron is installed *from them*.
 - **`npm install` (offline by design)** repeats the refusal reason in its notice and stops there — it never downloads.
 - **`amicus doctor --fix` and first GUI use** re-download the artifact with the digest pinned, so a one-off bad file self-heals and is reported as installed. Only when that retry cannot rescue it — no network, or the fresh download fails too — does `doctor` repeat the refusal reason instead of its generic "not provisioned".
 
-**Cause:** the bytes do not match the sha256 Electron itself publishes for that artifact (`node_modules/electron/checksums.json`). Amicus hashes a cached zip **before** extracting it, and pins the digest on the download, so bytes that *contradict* a published digest never become an Electron install. Where no published digest covers the artifact at all — an Electron package that ships no `checksums.json`, or one whose own `package.json` names a version amicus holds no entry for — there is nothing to contradict: those bytes are extracted and the outcome is marked `unverified` rather than refused, because refusing would strand every older Electron in a re-download loop. The gate is an integrity check against a digest amicus can obtain, not a promise that every artifact was vouched for.
+**Cause:** the bytes do not match the sha256 Electron itself publishes for that artifact (`node_modules/electron/checksums.json`). Amicus reads the artifact **once**, into its own memory, and everything after that — the sha256, the extraction — acts on those bytes and never on the file again: one `open`, one buffer, no second look at any path. So bytes that *contradict* a published digest never become an Electron install, and nothing on disk can be swapped between the hash and the extract, because after the read there is no path in play at all. Both routes work this way, the cached artifact and the fresh download. Where no published digest covers the artifact at all — an Electron package that ships no `checksums.json`, or one whose own `package.json` names a version amicus holds no entry for — there is nothing to contradict, and nothing to pin a download to: those bytes are extracted and the outcome is marked `unverified` rather than refused, because refusing would strand every older Electron in a re-download loop. That mark is not decorative: `npm install` prints a note when it installs one, the GUI says so on the launch that provisions it, and `amicus doctor --fix` names it in its self-heal line. **The mark covers the other unverified case too** — an artifact whose sha256 *contradicts* the published one and was installed anyway because `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` is set. That is the more alarming of the two, and both provision routes mark it: the only verdict that reports a clean repair is one where amicus's own hash matched a digest it anchored. Both routes say so on stderr as they do it — a cached artifact reports `no published sha256 for …, so its bytes could not be verified`, and a download reports `… could not be pinned`, meaning the bytes were checked only against the `SHASUMS256.txt` the mirror itself served. The gate is an integrity check against a digest amicus can obtain, not a promise that every artifact was vouched for.
 
 That is what a swapped mirror or a planted cache file looks like. It is **also** what a truncated download, a failing disk, or a corporate mirror serving a *rebuilt* Electron looks like — amicus cannot tell them apart, and says so rather than guessing.
 
 **Fix:**
 - **Let it retry.** Online, amicus removes the offending cache entry — only when its filename and its resolved location both say it really is that cache entry — and downloads again with the digest pinned. A one-off truncated download heals itself.
 - **Air-gapped / hand-seeded cache:** the refused file is deleted, so re-copy the cache directory from the machine that downloaded it. A partial copy is the usual cause. If the bytes are deliberately different (below), set the variable *before* you re-copy — the next refusal would remove the fresh copy too.
-- **You deliberately run a rebuilt Electron:** set `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` (see [configuration.md](./configuration.md#gui-and-debug)). It accepts a cached artifact that contradicts the published digest, and drops the digest pin on a download so a rebuilt artifact can be fetched from your own `ELECTRON_MIRROR` at all. It re-enables nothing else: the Electron installer's environment stays scrubbed of every `npm_config_electron_*` / `npm_package_config_electron_*` name either way.
+- **You deliberately run a rebuilt Electron:** set `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` (see [configuration.md](./configuration.md#gui-and-debug)). It accepts a cached artifact that contradicts the published digest, and drops the digest pin on a download so a rebuilt artifact can be fetched from your own `ELECTRON_MIRROR` at all. Everything it lets through is marked `unverified`, on both routes, and reported everywhere that mark is read. It widens **two** further things, and both are worth knowing before you set it. The first is the [native-extractor rescue](#amicus-could-not-read-this-electron-archive): with this variable set, an archive amicus's own extractor cannot read is written to a path and handed to your OS's extractor — which spends the custody property everything else on this page rests on, that amicus only ever writes bytes it hashed. The second is a residual on the environment strip. Every `npm_config_electron_*` / `npm_package_config_electron_*` name is stripped from the environment while amicus works out **where the artifact comes from**, so the zip still comes from the official `github.com/electron/electron/releases/download/…` even in a repository whose `.npmrc` names a mirror. But an unpinned download is exactly what this variable produces, and an unpinned download makes `@electron/get` fetch a `SHASUMS256.txt` of its own *after* those names are restored — so a repo-planted mirror **is** read again for that one fetch (measured on every test run by `tests/electron-env-scrub-get5-contract.test.js`). It cannot change which bytes you get, because the artifact's URL was already settled; it can only serve a checksum file that disagrees with the official artifact, which makes the download **fail**. If an unpinned download fails checksum validation on a machine whose `.npmrc` names an Electron mirror, unset the planted names. [configuration.md](./configuration.md#gui-and-debug) states the same residual with the measurement behind it.
 - **Otherwise treat it as real.** Check what `ELECTRON_MIRROR` is set to, and whether the directory you ran `npx -y amicus@latest` in is one you trust.
 - Headless runs and the full council work without the GUI in every one of these cases.
 
-**A second, rarer refusal:** `Electron artifact REFUSED (unsafe archive)` means entries inside the zip tried to write *outside* the destination directory. That one is terminal by design — amicus does not retry it with a different extractor, does not delete the file (it is the evidence), and `AMICUS_ALLOW_UNVERIFIED_ELECTRON` does not apply to it. Report the mirror or cache the archive came from.
+**A second, rarer refusal:** `Electron artifact REFUSED (unsafe archive)` means entries inside the zip tried to write *outside* the destination directory. That one is terminal by design — amicus does not retry it with a different extractor, does not delete the file (it is the evidence), and `AMICUS_ALLOW_UNVERIFIED_ELECTRON` does not apply to it, nor does the native-extractor rescue below. Report the mirror or cache the archive came from.
+
+---
+
+## amicus could not read this Electron archive
+
+**Symptom:** provisioning stops with
+
+```
+[amicus] amicus could not read this Electron archive: could not read the archive: ...
+[amicus] There is ONE rescue for that, and it is OFF. With
+[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 set BEFORE provisioning, amicus writes the bytes
+[amicus] it hashed into a private directory inside the electron package and hands that PATH
+[amicus] to a native extractor (tar / Expand-Archive / ditto / unzip) — ...
+```
+
+**Cause:** amicus extracts the artifact **in memory**, from the buffer it hashed, so that the bytes it writes are always the bytes it verified. This message means that extractor could not read the archive at all — a truncated or malformed zip, or a shape it does not handle. The bytes are not written anywhere and no Electron is installed from them. A *cached* artifact identified this way is normally discarded, because a positively-unreadable archive is the one failure that says the cached file is worthless — but **not on the run that prints this message**, which leaves it exactly where it is. The rescue below is the reason: an offer that tells you to set a variable and provision again cannot delete the only copy that re-run could act on. Amicus discards the artifact once the rescue has actually been tried and every native extractor has failed on it too.
+
+**Fix, in order:**
+
+- **Online, do nothing.** Amicus downloads the artifact again with the digest pinned. A truncated download
+  heals itself. The exception is an archive amicus refuses outright for path traversal — that is terminal
+  by design and is not re-fetched, because the problem is what the archive *contains*, not that it arrived
+  incomplete.
+- **Air-gapped, re-copy first.** Copy the cache directory again from the machine that downloaded it. A partial copy is the usual cause, and a fresh copy costs you nothing.
+- **Only if you cannot obtain another copy: the native-extractor rescue.** Set `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` and provision again. You do not have to have set it in advance: the run that printed the message above left the archive in place precisely so this one has something to work on. Amicus then writes the bytes it hashed to a path inside the Electron package and hands that path to your OS's own extractor (`tar` / `Expand-Archive` / `ditto` / `unzip`) — the same tools that handled the archive before amicus extracted in memory at all. **This is not a safe operation, and it is not described as one.** Between amicus writing the file and the child process opening it, anything running as your user can substitute it, and what that child extracts is promoted into `dist/` without being hashed again. Amicus prints the whole trade on stderr before it spawns anything, and the result is reported `unverified` even when the artifact's own sha256 matched. Unset the variable afterwards: it also downgrades a digest-mismatch refusal to a warning ([configuration.md](./configuration.md#gui-and-debug)).
+- **What the rescue will *not* do,** whatever this variable is set to: retry an archive refused for path traversal (`REFUSED (unsafe archive)` — terminal by design), retry an extraction that *stalled* (the timeout exists to stop work, not to hand it to a child process), rescue bytes that contradict the published digest (they are known wrong), or paper over a full or unwritable disk. Each of those says something different from "this archive cannot be read", and only the last of those is a rescue amicus was given. Before it hands anything over, amicus also reads the archive's *entry names* and refuses any that would write outside the destination — because an archive can break the extractor early enough that its own traversal check never ran. It reads them in **both** tables a zip declares them in, so cutting the tail off an archive no longer hides its names, and the two tables disagreeing does not let one through. It still cannot see a symlink target, and an archive that defeats both walks still reaches the extractor — the notice printed before the spawn says which names were checked; [configuration.md](./configuration.md#gui-and-debug) states every residual and names which extractors were measured to refuse a `..` entry themselves.
+- Headless runs and the full council work without the GUI throughout.
+
+---
+
+## Electron artifact NOT extracted (could not be read)
+
+**Symptom:** provisioning stops with
+
+```
+[amicus] Electron artifact NOT extracted: electron-v43.1.1-win32-x64.zip
+[amicus]   C:\Users\me\AppData\Local\electron\Cache\<sha>\electron-v43.1.1-win32-x64.zip
+[amicus]   could not be opened or read at all (EACCES: permission denied, open '...')
+[amicus] amicus reads an artifact ONCE, into memory, and hashes and extracts THOSE
+[amicus] bytes. It could not read these, so it has nothing it could vouch for and
+[amicus] has extracted nothing. The file was left exactly where it is.
+```
+
+**Cause:** amicus reads an Electron artifact exactly once, through a single file descriptor, into a
+buffer of its own. The sha256 and the extraction both act on that buffer. Anything that can write the
+download cache — which, on your own machine, includes anything running as you — can change the file
+afterwards, and it changes nothing: the bytes amicus hashed are already the bytes it is going to
+write. When the read itself cannot be completed there is nothing to vouch for, so amicus refuses
+rather than extracting something it never saw whole.
+
+The third line names which way the read failed:
+
+| line | what happened |
+|---|---|
+| `could not be opened or read at all` | permissions, a broken path, a disconnected drive — the fs error is quoted |
+| `is not a regular file` | the cache entry is a directory, a fifo, or a device node |
+| `is empty` | a zero-byte file, usually an interrupted download |
+| `is far larger than any electron artifact` | above the 1 GiB ceiling; a real artifact is ~140–160 MB |
+| `ended early while amicus was reading it` | the file is shorter than it said it was |
+| `changed size while amicus was reading it` | it grew under the read — what an active swap looks like |
+
+**Fix:**
+- Delete the cache entry the message names and provision again; amicus re-downloads it.
+- Check the permissions on the cache root (`ELECTRON_CACHE`, or `%LOCALAPPDATA%\electron\Cache` /
+  `~/Library/Caches/electron` / `~/.cache/electron`).
+- Headless runs and the full council work without the GUI meanwhile.
+
+**Notes:**
+- **Your cached artifact is never moved, copied, or deleted by this refusal.** The download cache is
+  exactly as it was, whether the repair succeeded, was refused, or was interrupted — which matters
+  most on an air-gapped machine whose cache was hand-seeded. Nothing is written to the temp directory
+  either: earlier versions staged a ~170 MB copy there, and no longer do.
+- **A killed run can leave one directory behind, and the next provision sweeps it.** Extraction
+  happens in `<electron package>/.amicus-incoming-<hex>/`, which is promoted into `dist/` by a single
+  rename at the end and removed afterwards — but that removal is an in-process `finally`, and a kill
+  does not run it. Ctrl-C during `npm install`, a lid close or an AV kill can therefore leave one
+  behind, as can the sibling `.amicus-retired-<hex>` when an Electron is running off the tree being
+  replaced (Windows refuses to delete it). Both live inside the Electron package directory, where no
+  OS temp cleaner reaches them, so **amicus sweeps them itself: every provision removes any
+  `.amicus-incoming-*` or `.amicus-retired-*` in that directory that is more than a day old.** The
+  age rule is deliberate — it cannot take a tree another run may still be writing. What is still
+  guaranteed either way: a half-written tree is never what `dist/` contains, and a kill mid-extract
+  leaves the previous `dist/` exactly where it was.
+- **A promote never removes a working `dist/` to make room.** If the old tree cannot be renamed out of
+  the way (a handle held on it, or an AV filter denying the move) and it holds a usable executable —
+  the one `path.txt` names, or this platform's default when `path.txt` is absent, unreadable or blank
+  — the repair refuses and leaves it untouched rather than deleting it with no way back. That covers
+  a package cross-installed for another platform through `npm_config_platform`, whose `path.txt` names
+  an executable this platform never looks for; through v4.9.6 the guard asked only about this
+  platform's default name, so such a tree was read as "not an install" and a promote that FAILED
+  deleted it. If it holds neither, it is not an install, and it is replaced. In the one case where the
+  tree was renamed away and neither the swap nor the rollback could run, the previous `dist/` is
+  intact at `.amicus-retired-<hex>` and the error names it — rename it back to `dist/` to restore it.
+- **A related refusal**, `Refusing to provision electron: … is not a usable artifact name`, means the
+  `version` in the Electron package's own `package.json` is not a plausible version string. Amicus
+  builds the artifact filename from it and refuses to use anything that is not a plain filename, since
+  it would otherwise be joined into a path. Reinstall the `electron` package.
+- **`Cached electron artifact … was NOT extracted (…); it was LEFT IN PLACE`** is the other half of
+  the same rule: the archive was fine and the *destination* was not (no space, an unwritable `dist/`,
+  a path too long). A cached artifact is only ever evicted when the archive itself is bad.
 
 ---
 

package/docs/usage.md

@@ -540,7 +540,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.5",
+  "version": "4.9.7",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.5",
+  "version": "4.9.7",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
@@ -84,6 +84,7 @@
     "opencode-ai": "1.18.15",
     "tiktoken": "^1.0.0",
     "update-notifier": "^7.3.1",
+    "yauzl": "^2.10.0",
     "zod": "^3.0.0"
   },
   "optionalDependencies": {

package/scripts/postinstall.js

@@ -42,7 +42,18 @@ const PROVISION_TIMEOUT_MS = 15000;
  * there is no cache (or the repair defers/contends), we emit a clear notice that
  * the GUI provisions on first use and that headless runs + the council already
  * work, then point at `amicus doctor --fix` (#56) — NOT a reinstall, which can
- * loop. A short timeout keeps a slow disk from ever hanging the install.
+ * loop.
+ *
+ * WHAT IS ACTUALLY BOUNDED HERE, stated precisely because the old sentence
+ * ("a short timeout keeps a slow disk from ever hanging the install") named a
+ * bound that does not exist on the default path. `PROVISION_TIMEOUT_MS` reaches
+ * `repairElectron` as `timeoutMs`, and `timeoutMs` becomes the DOWNLOAD budget
+ * (`electron-provision.js`'s `downloadMs`) — which the cache-only default path
+ * never uses, because it never downloads. The extract is what could hang here,
+ * and it is bounded by the extractor's own idle and hard caps
+ * (`zip-from-buffer.js`: 30 s with no progress, 240 s total), whose live timer
+ * handle is also what stops Node exiting 0 in the middle of a stall. Both
+ * bounds are real; neither is the other.
  *
  * This MUST never throw out of postinstall — the whole body (sync setup, the
  * awaited repair, and a synchronous-throw resolver) is guarded so nothing here
@@ -58,6 +69,15 @@ const PROVISION_TIMEOUT_MS = 15000;
  * @param {object} deps - { repairElectron } override for testing.
  * @returns {Promise<void>}
  */
+function warnIfUnverified(result) {
+  if (!result || !result.unverified) { return; }
+  console.warn('[amicus] Note: the Electron GUI binary was installed UNVERIFIED — either no published sha256');
+  console.warn('[amicus]   covered this artifact, so its bytes were checked only against whatever the mirror');
+  console.warn('[amicus]   served, or its sha256 CONTRADICTED the published one and');
+  console.warn('[amicus]   AMICUS_ALLOW_UNVERIFIED_ELECTRON accepted it anyway.');
+  console.warn('[amicus]   See docs/troubleshooting.md (Electron artifact REFUSED).');
+}
+
 async function provisionElectron(deps = {}) {
   try {
     const _repair = deps.repairElectron || repairElectron;
@@ -65,9 +85,10 @@ async function provisionElectron(deps = {}) {
     // Opt-in aggressive prewarm (#60): full fetch if needed. Non-fatal.
     if (process.env.AMICUS_PREFETCH_ELECTRON === '1') {
       console.log('[amicus] AMICUS_PREFETCH_ELECTRON=1 — prewarming the Electron GUI binary (may download)...');
-      const forced = await _repair({ force: true });
+      const forced = await _repair();
       if (forced && forced.repaired) {
         console.log('[amicus] Electron GUI binary prewarmed.');
+        warnIfUnverified(forced);
         return;
       }
       if (forced && forced.quarantined) {
@@ -80,7 +101,7 @@ async function provisionElectron(deps = {}) {
     }
 
     const result = await _repair({ cacheOnly: true, timeoutMs: PROVISION_TIMEOUT_MS });
-    if (result && result.repaired) { return; }
+    if (result && result.repaired) { warnIfUnverified(result); return; }
     // AV quarantine (electron.exe deleted right after extract) needs ACTION, not
     // a generic "provisions on first use" notice — re-extracting can never win,
     // so print the allow-list instruction verbatim instead. (No retry loop.)

package/src/sidecar/electron-cache.js

@@ -10,6 +10,7 @@
 
 'use strict';
 
+const fsDefault = require('fs');
 const path = require('path');
 const os = require('os');
 
@@ -39,4 +40,43 @@ function resolveCacheRoots(env = process.env) {
   return [...new Set(roots.filter(Boolean))];
 }
 
-module.exports = { resolveCacheRoots, defaultCacheRoot };
+/**
+ * Locate a previously-downloaded electron zip in the env-configurable cache
+ * roots. Walks <root>/<sha>/electron-v<ver>-<platform>-<arch>.zip.
+ *
+ * MOVED here from electron-install.js (v4.9.6 F1): that file sits at the 300-line
+ * gate with no headroom, and the F1 staging wiring had to go somewhere. Cache
+ * LOOKUP belongs beside cache-root RESOLUTION anyway; electron-install.js
+ * re-exports it so `ei.cachedZip` stays a valid import.
+ *
+ * The `<sha>` directory names come from `readdirSync` on a directory an attacker
+ * may write, so the returned path is attacker-INFLUENCED. Callers must treat it
+ * as such: read it ONCE into memory and hash and extract THOSE bytes, never
+ * resolving the name a second time (sidecar/electron-custody.js), and never
+ * print it unsanitized (utils/text-sanitize.js).
+ * @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;
+}
+
+module.exports = { resolveCacheRoots, defaultCacheRoot, cachedZip };

package/src/sidecar/electron-custody.js

@@ -0,0 +1,180 @@
+/**
+ * CUSTODY of the Electron artifact: one open, one read, one Buffer.
+ *
+ * THE PROPERTY THIS MODULE EXISTS TO MAKE TRUE, and the only one it claims:
+ *
+ *   **Amicus never itself writes, or reports as verified, bytes it did not hash.**
+ *
+ * Deliberately NOT "the user launches genuine Electron". A live attacker
+ * running as the same uid can overwrite `<electronDir>/dist/electron.exe`
+ * directly, at any moment, with no artifact involved at all — so no
+ * acquisition-time design can promise that, and claiming it would be the
+ * overclaim this whole change exists to stop.
+ *
+ * WHY A BUFFER, AND NOT A FILE DESCRIPTOR. Two council designs independently
+ * probed the fd remedy and both refuted it: a descriptor names an INODE, not a
+ * version of an inode. A same-uid `writeFileSync` at the path truncates and
+ * rewrites that same inode, and a positional read through our retained fd then
+ * returns the attacker's bytes (MEASURED twice, on Windows 11 / NTFS / Node
+ * 24.18: `"CLEANCLEANCLEAN"` before, `"POISONPOISONPOI"` after, through the
+ * SAME fd). A Buffer is different in kind: once the bytes are in this process's
+ * heap, no filesystem write can reach them. That is the whole design.
+ *
+ * WHY NOT A PRIVATE COPY EITHER — the remedy this replaces. v4.9.6 copied the
+ * artifact into a fresh 0700 `mkdtempSync` directory and asserted the attacker
+ * had "no name for it and no handle on it". MEASURED false on both halves: a
+ * spinner found the fixed `amicus-electron-stage-` prefix on its FIRST readdir
+ * of `os.tmpdir()`, opened the copy `r+` as the same user, and overwrote it;
+ * and on Windows `mkdtempSync` yields mode 666 while the module skipped its own
+ * `chmod(0o700)` on win32, so the 0700 was never even attempted. 0700 excludes
+ * OTHER users; the attacker in this threat model is THIS user.
+ *
+ * WHAT THE THREAT MODEL IS. An attacker who can write the Electron download
+ * cache directory, running as the same user as amicus. Out of scope, and stated
+ * rather than implied: that same user can also read and write amicus's process
+ * memory (`WriteProcessMemory`, or `process_vm_writev` under
+ * `yama.ptrace_scope=0`), rewrite amicus's own `node_modules`, or edit its
+ * config. Against THAT capability nothing here matters — an attacker in our
+ * address space can simply flip the gate's own verdict. This module closes the
+ * attacker whose capability is WRITING FILES, which is the one the digest gate
+ * makes sense against: a less-trusted cache root — a shared build box, a
+ * restored CI cache volume, a container bind-mount — read by a process whose
+ * own tree is trusted.
+ *
+ * NEAR-LEAF MODULE: `fs` + `path`, plus the pure house sanitizer
+ * `utils/text-sanitize`. Requires nothing in this cluster, so it can be
+ * required from either side of the electron-install -> electron-provision arrow.
+ *
+ * @module sidecar/electron-custody
+ */
+
+'use strict';
+
+const fsDefault = require('fs');
+const path = require('path');
+
+/** Positional-read chunk. 8 MiB keeps the loop at ~18 reads for a 138 MiB artifact. */
+const READ_CHUNK = 8 * 1024 * 1024;
+
+/**
+ * An electron artifact larger than this is not an electron artifact. The real
+ * win32 x64 artifact measured 138 MiB (144,265,219 bytes); darwin and linux are
+ * the same order. The cap is checked against `fstat`'s size BEFORE anything is
+ * allocated, so a 4 GiB sparse file planted in the cache costs one `fstat`.
+ */
+const MAX_ARTIFACT_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * The ONLY shape allowed to become a path component:
+ * `electron-v<version>-<platform>-<arch>.zip`, with each field restricted to
+ * characters an electron version / platform / arch can actually contain.
+ *
+ * An ALLOW-list on purpose. A deny-list of `..` and separators is the shape
+ * that keeps losing — it has to anticipate every dialect (`..`, `%2e%2e`, a
+ * bare `\` that only win32's `path` treats as a separator), and it fails open
+ * on the one it did not think of. This fails closed on everything it was not
+ * written for.
+ *
+ * MOVED HERE from the deleted `electron-stage.js`, unchanged. It is still
+ * load-bearing: `version` is read out of `<electronDir>/package.json` whenever
+ * the caller supplies none, and `doctor --fix` — the one production caller —
+ * supplies none, for a directory it located by SCANNING npx caches. MEASURED
+ * before the check, end to end, with a planted `"version": "43.1.1/../../victim"`:
+ * a path two levels outside the intended directory was written and a
+ * pre-existing file there was destroyed.
+ */
+const ARTIFACT_NAME = /^electron-v[0-9A-Za-z][0-9A-Za-z.+-]*-[0-9A-Za-z_]+-[0-9A-Za-z_]+\.zip$/;
+
+/**
+ * True when `fileName` is a plain filename amicus itself could have produced.
+ *
+ * Both halves are checked deliberately. The pattern is the real control; the
+ * `path.basename` equality states the property in the platform's OWN dialect,
+ * so the claim "this is a filename, not a path" is asserted by the module that
+ * defines what a path is rather than only by a regex that has to imitate it.
+ * @param {*} fileName
+ * @returns {boolean}
+ */
+function isSafeArtifactName(fileName) {
+  return typeof fileName === 'string'
+    && fileName === path.basename(fileName)
+    && ARTIFACT_NAME.test(fileName);
+}
+
+/**
+ * Read `zip` into memory EXACTLY ONCE, through ONE descriptor.
+ *
+ * THE PATH IS RESOLVED ONCE AND NEVER AGAIN. `fstatSync(fd)` — never
+ * `statSync(zip)` — so even the size we act on comes from the handle we opened;
+ * a symlink is already resolved, and a swap after this point cannot change the
+ * answer. Every read is POSITIONAL (`readSync(fd, buf, off, len, POSITION)`),
+ * so the shared file offset is never used and nothing else in this process can
+ * perturb it.
+ *
+ * THERE IS NO "COULD NOT ALLOCATE" BRANCH, and that is deliberate. Two council
+ * designs promised one; both were MEASURED wrong. `Buffer.allocUnsafe` does not
+ * throw when the machine is out of memory — the process dies, exactly as it
+ * does today when extract-zip inflates a 215 MiB entry. Writing a clean
+ * `{why:'no-memory'}` refusal and claiming it works would be a failure branch
+ * this change never executed. What DOES protect the allocation is `maxBytes`,
+ * checked against `fstat` before a byte is reserved.
+ *
+ * A TORN READ NEEDS NO SPECIAL HANDLING. If the attacker mutates the file while
+ * we are reading it, the buffer we assembled is what would have been extracted,
+ * its sha256 will not match the anchor, and the gate refuses. `grew` and
+ * `short-read` exist to name the shape, not to provide the security.
+ *
+ * @param {object} o
+ * @param {string} o.zip        attacker-influenced path (a cache entry, or what
+ *                              `downloadArtifact` handed back)
+ * @param {number} [o.maxBytes] default MAX_ARTIFACT_BYTES
+ * @param {object} [o.fs]
+ * @returns {{bytes: Buffer, size: number}
+ *         | {bytes: null, why: 'unreadable'|'not-a-file'|'empty'|'too-large'|'short-read'|'grew',
+ *            detail: string}}
+ */
+function readArtifactBytes({ zip, maxBytes = MAX_ARTIFACT_BYTES, fs = fsDefault }) {
+  let fd;
+  try {
+    fd = fs.openSync(zip, 'r');
+  } catch (e) {
+    return { bytes: null, why: 'unreadable', detail: (e && e.message) || String(e) };
+  }
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) {
+      return { bytes: null, why: 'not-a-file', detail: 'it is not a regular file' };
+    }
+    if (st.size === 0) {
+      return { bytes: null, why: 'empty', detail: 'it is empty' };
+    }
+    if (st.size > maxBytes) {
+      return { bytes: null, why: 'too-large', detail: `${st.size} bytes exceeds the ${maxBytes}-byte ceiling` };
+    }
+    const bytes = Buffer.allocUnsafe(st.size);
+    let off = 0;
+    while (off < st.size) {
+      const n = fs.readSync(fd, bytes, off, Math.min(READ_CHUNK, st.size - off), off);
+      if (!(n > 0)) {
+        return { bytes: null, why: 'short-read', detail: `the file ended after ${off} of ${st.size} bytes` };
+      }
+      off += n;
+    }
+    // One positional read PAST the size we trusted. A file that grew under us is
+    // what an active swap looks like, and it means the bytes we hold are a prefix
+    // of something else — say that, rather than hashing a truncation.
+    const tail = Buffer.allocUnsafe(1);
+    if (fs.readSync(fd, tail, 0, 1, st.size) > 0) {
+      return { bytes: null, why: 'grew', detail: 'it changed size while amicus was reading it' };
+    }
+    return { bytes, size: st.size };
+  } catch (e) {
+    return { bytes: null, why: 'unreadable', detail: (e && e.message) || String(e) };
+  } finally {
+    try { fs.closeSync(fd); } catch { /* already closed */ }
+  }
+}
+
+module.exports = {
+  readArtifactBytes, isSafeArtifactName, MAX_ARTIFACT_BYTES, READ_CHUNK,
+};

package/src/sidecar/electron-ensure.js

@@ -45,7 +45,7 @@ function _resetEnsureElectron() {
  * @param {object} [opts.deps] injected
  *   { isElectronUsable, resolveElectronBinary, repairElectron, logProgress }.
  * @param {object} [opts.repairOptions] forwarded to repairElectron (electronDir, etc.).
- * @returns {Promise<{ok:boolean, path?:string, reason?:string}>}
+ * @returns {Promise<{ok:boolean, path?:string, reason?:string, unverified?:boolean}>}
  */
 function ensureElectron({ deps = {}, repairOptions = {} } = {}) {
   const usable = deps.isElectronUsable || defaultIsUsable;
@@ -71,11 +71,32 @@ function ensureElectron({ deps = {}, repairOptions = {} } = {}) {
       return { ok: false, reason: `Electron provisioning failed: ${err && err.message}` };
     }
     if (usable()) {
+      // A2/B3 (council, confirmed 4 of 4): `unverified` was WRITTEN on both
+      // provision routes and read by nothing in src/ or scripts/, while the docs
+      // said the outcome was "marked unverified". A flag no code and no human
+      // ever sees establishes no property at all. This is the launch-time
+      // reader; scripts/postinstall.js is the install-time one and
+      // doctor-electron-mcp-check.js reports it from `--fix`.
+      if (result && result.unverified) {
+        logProgress('[amicus] NOTE: this Electron binary is UNVERIFIED — either no published sha256 covered');
+        logProgress('[amicus]   the artifact it came from, so its bytes were vouched for only by the');
+        logProgress('[amicus]   mirror that served them, or its sha256 CONTRADICTED the published one and');
+        logProgress('[amicus]   AMICUS_ALLOW_UNVERIFIED_ELECTRON accepted it anyway.');
+      }
       logProgress('[amicus] Electron GUI ready.');
-      return { ok: true, path: resolve() };
+      return { ok: true, path: resolve(), ...(result && result.unverified ? { unverified: true } : {}) };
     }
-    const reason = (result && result.reason)
-      || `Electron could not be provisioned; the GUI is unavailable. ${HINTS.doctorFix} (or use --no-ui).`;
+    // THE POINTER IS NOT OPTIONAL. This used to be `result.reason || <the
+    // pointer>`, so the moment `repairElectron` started returning a reason for a
+    // failed controlled download (v4.9.6, when the last-resort installer was
+    // deleted and the failure became something to REPORT), the one line telling
+    // the user what to do next silently disappeared. A more detailed message is
+    // not a reason to stop giving advice.
+    const detail = (result && result.reason) || 'Electron could not be provisioned; the GUI is unavailable.';
+    // Matched on the COMMAND, not on the whole hint string: the AV-quarantine
+    // reason already ends with a bare `amicus doctor --fix` and must not be
+    // given a second, longer copy of the same advice.
+    const reason = detail.includes('doctor --fix') ? detail : `${detail} ${HINTS.doctorFix} (or use --no-ui).`;
     return { ok: false, reason };
   })().then((r) => {
     // Only memoize SUCCESS; a failure clears the guard so a later launch retries.