amicus 4.9.5 → 4.9.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.5",
+  "version": "4.9.7",
   "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,244 @@
 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.7] - 2026-09-09
+
+Three findings deferred from the v4.9.6 cut, and the two open questions filed beside them. The
+council run that raised the three reviewed at **2 of 4 seats**, so each carried the weight of two
+seats — and on the one that mattered most, the filing turned out to be right about the defect and
+wrong about the fix.
+
+### Fixed
+
+- **A promote can no longer delete a working install that was cross-installed for another
+  platform.** v4.9.6 captured and restored a `path.txt` naming another platform's executable, but
+  the guard that decides whether a `dist/` may be removed in place still asked only about THIS
+  platform's default name. On a package installed through `npm_config_platform`, a promote whose
+  retirement rename failed therefore restored the pointer and deleted the tree it pointed at —
+  reproduced against the shipped code with a real filesystem and only `renameSync` injected to
+  throw the EPERM the fallback exists for.
+
+  The guard now judges by what `path.txt` actually names. **As a union with the platform default,
+  never as a replacement** — which is the part the finding did not say, and implementing its
+  sentence literally destroys a working `dist/electron.exe` on three shapes the old guard protected:
+  a whitespace-only `path.txt`, one with a trailing newline (`existsSync` of a name ending in `\n`
+  is false on Windows), and a TRUNCATED one — `electr`, the shape this function's own best-effort
+  put-back can leave. The platform-default arm runs first and is unchanged, so the set of trees a
+  promote will delete can only ever shrink.
+
+  The `path.txt` name additionally has to be **contained** in `dist/` and has to be a **file**: a
+  `path.txt` of `..`, `.` or `../SIBLING` names something that exists but that the delete never
+  touches, and every truncation of the darwin name (`Electron.app`, `Electron.app/Contents`,
+  `.../MacOS`) is a real directory — accepting either would refuse every promote forever while
+  reporting that `dist/` "holds a usable Electron.app". The refusal message now names the executable
+  that was found rather than the one that was looked for, because `docs/troubleshooting.md` tells
+  the user that refusal means the tree holds a usable executable.
+
+  An **unreadable** `path.txt` now refuses rather than guessing; an absent one still heals. The rule
+  itself moved to `src/sidecar/electron-exe-rel.js` and `resolveElectronBinary` now calls it, with a
+  table-driven test asserting both sides agree over seven `path.txt` shapes on three platforms with
+  and without `ELECTRON_OVERRIDE_DIST_PATH`. Two copies of one rule are what let these drift, and
+  the finding's own words for the defect were "did not carry one function over".
+
+- **(docs)** `.github/workflows/ci.yml` claimed `--omit=optional` "skips the Electron download". It
+  skips the optional *package*; there is no download on the default path to skip, because
+  `electron@43.1.1` ships no install script at all. Measured on run `34246117877` across all three
+  runner platforms.
+
+### Security
+
+- **The rescue boundary now reads BOTH tables an archive declares its entry names in.** A zip
+  carries its names twice — in the central directory and in each local file header — and amicus
+  read only the first. An archive can blind that one while leaving every local header whole: cutting
+  the tail off does it by accident, and four one-field edits to a *complete* end-of-central-directory
+  record do it on purpose. Measured against the real extractor with the hatch armed, **seven such
+  archives carrying a `../../../` entry reached a native extractor, and two ran to completion and
+  promoted the result.** Nothing escaped only because the Windows tools refuse `..` themselves — the
+  exact reliance this subsystem says amicus will not make.
+
+  The two tables can also disagree, and the tools do not agree on which to believe: measured,
+  `tar.exe` wrote the name from the local header while `Expand-Archive` wrote the one from the
+  central directory. A refusal in either table now refuses the archive.
+
+  **It costs no measured availability.** On six real Electron artifacts the local walk enumerates
+  every name in 0-1 ms and agrees with the central table entry-for-entry; on a truncated archive,
+  where the central walk goes blind, it still reads them all. The archives this rescue exists for
+  are still rescued. And the notice printed before a spawn now says *which* names were checked —
+  all of them, some of them, or none — because a real artifact truncated by a few kilobytes leaves
+  both walks incomplete while every name it found was read and cleared, and a two-state notice would
+  have claimed nothing was checked over dozens that were.
+
+  **Two council rounds then found the first cut of this incomplete, and the second cut of it
+  incomplete again — both in the same direction.** A walk that could not follow the chain used to
+  STOP, and an entry it never reached is an entry it cannot refuse: a lying size jumped one, and
+  later a *standard* data-descriptor entry (general-purpose bit 3 with a zero size — an ordinary
+  streaming encoding, not a malformed one) hid everything behind it. Neither needed an exotic
+  archive. So the walk now DEMOTES its claim and keeps going wherever it still has an offset to
+  follow — because a name it can still read is a name it can still refuse — and where it genuinely
+  has none, it SWEEPS the region it could not reach for local headers and puts their names through
+  the same rule. It can only add refusals, so an archive that is rescued today stops being rescued
+  only if it declares a hostile name. **The practical consequence for a user: an archive carrying a
+  traversal name behind an unreadable point is now refused where it previously reached the native
+  extractor.**
+
+  The claim "every name was checked" also became a conjunction rather than a disjunction. The two
+  tables carry different names and the two extractors read different ones, so one readable table
+  never meant both were clean — measured, a stopped local walk beside a benign central directory
+  reported all-clear and printed nothing while `tar.exe` reached a `../../../` entry only the local
+  table carried.
+
+### Added
+
+- **A macOS job that runs the real extract path over the real Electron `.app` artifact**
+  (`.github/workflows/darwin-bundle.yml`, `scripts/probe-darwin-extract.js`). v4.9.6 shipped a
+  symlink target-escape check that `extract-zip` does not have, and disclosed that it might *reject*
+  a layout that previously worked. **It does not** — measured against the real
+  `electron-v43.1.1-darwin-arm64.zip`: 585 records, 14 symlinks, every target relative, none with a
+  `..` component, none absolute, and none of the 585 entry names traversing a symlinked component.
+  The linux artifacts hold zero symlink entries, so that path is unreachable there at all.
+
+  What was left was coverage rather than risk, and the job closes it: a real `symlinkSync`, a real
+  `realpathSync` behind the chain control, the absolute-target branch on POSIX arithmetic, and
+  `Electron --version` loading the framework through two of the fourteen links. Ten assertions, each
+  naming the one-line mutation it catches. The parity diff against `@electron-internal/extract-zip`'s
+  own tree ships **report-only** on its first cut — that comparison has never been measured, and a
+  gate that has never been run once is not evidence.
+
+### Changed
+
+- **The claim that the native extractors refuse traversal themselves is now re-measured on every CI
+  run, instead of being asserted once.** That claim is the compensating control the rescue's
+  boundary leans on, and a claim nothing re-measures is a claim that rots.
+  `tests/sidecar/native-extractor-containment.test.js` drives 12 escape shapes through every
+  strategy that resolves on the machine. Newly measured this way: Info-ZIP `unzip` contains its own
+  escapes by stripping them, and GNU `tar` cannot read a zip at all — both were previously written
+  down as unmeasured. **`ditto`, the first macOS strategy, is now the only unmeasured one**, and the
+  macOS runner already in the matrix measures it the first time this suite runs there.
+
+  A proposed runtime "fence" around the Electron package directory was **refused rather than
+  deferred**, and the reasons are recorded because they were measured: a names-diff fence is blind
+  to an overwrite of `dist/electron.exe` or `path.txt`; and signalling a breach through the
+  available channel deletes the user's cached artifact and reports it corrupt — which a *false*
+  breach, reachable from a concurrent provision, would then do to the air-gapped machine this whole
+  feature exists for.
+
+  Half of the finding that prompted it was already false: everything the rescue writes lives under a
+  private incoming directory that is deleted unconditionally, so only an absolute write outside that
+  tree survives a failed strategy. Two shipped documents said otherwise and are corrected. The child
+  now also runs with that directory as its working directory — measured neutral, and it costs a line.
+
+- **The CI council bench reserves 64,000 output tokens per leg instead of the engine's 32,000
+  default** — for every PR whose base carries the change. The alias map is fetched from the BASE
+  REF, so a branch cannot change the reviewers of its own PR; the config therefore lands on `main`
+  separately and takes effect for runs opened after it, never for the branch carrying it. Measured:
+  the run on the PR that first carried this reported `outputBudget is unset` and lost a seat at the
+  32,000 default exactly as before. Across the five paid council runs on the v4.9.6 branch the bench averaged **2.8 of 4
+  seats**, and four of the six lost seats died at the reservation with `finish: 'length'` and
+  0–651 usable output tokens.
+
+  **64,000 is measured, not chosen.** Against the pinned engine with the bare descriptors CI
+  registers, it lands unclamped on all four seats and the chair in both catalogue states. The
+  binding ceiling is **65,536**, and on a cold read it is shared by **two** rows — the chair and
+  `deepseek-v4-flash-0731` — not by the chair alone: the flag at 100,000 arrives as
+  `max_tokens 65536` on both. A budget above it would land in full on three seats while two were
+  silently clamped, and a run would stop reserving one number. The pre-flight step now fails before
+  any spend on a budget above the ceiling or on one amicus would reject and silently replace with
+  32,000; the alias map's own validator inspects aliases only, so nothing caught that before.
+
+  **What it does not fix, said up front:** the other two lost seats — and ten of the eleven failed
+  first attempts — produced nothing at all and never reached a reservation. Expect roughly 3.6 of 4,
+  not 4 of 4. Read the death class rather than the seat count: three of the four targeted legs ran
+  529–596 s of a 960 s leg cap, so an `OUTPUT_LENGTH` death can convert into a generic timeout,
+  which is the same lost seat with a worse diagnosis. The leg cap deliberately did not move in the
+  same change — raising it busts the 75-minute job cap, and a bust cancels the job, which deletes
+  the run-directory artifact every diagnosis of this class rests on.
+
+## [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.*

package/README.md

@@ -455,7 +455,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/docs/ROADMAP.md

@@ -13,13 +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.5** (2026-09-07). Each 4.x rev below leads with the benefit, not the
+Amicus is at **v4.9.7** (2026-09-09). 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) it did so to make an existing promise
-true, not to widen it. See `CHANGELOG.md` for what each one contained.
+`output-budget` doctor row, v4.9.5's Electron digest gate, v4.9.6's artifact custody, v4.9.7's dual name-table rescue boundary) 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.5 patch releases —
+**Status:** v4.0 through **v4.9.0** have **shipped**, plus the v4.9.1–v4.9.7 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,13 +109,22 @@ 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-exe-rel.js  # WHICH exe a package resolves through, and whether a `dist/` HOLDS one.
 │   ├── 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-provision.js  # Electron CONTROLLED provision — the pinned download, and what happens to a
+│   ├── 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, the gate, and the env scrub.
+│   ├── 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
@@ -155,7 +164,12 @@ 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-local-name-scan.js  # THE OTHER TABLE AN ARCHIVE DECLARES ITS NAMES IN — the local file headers.
+│   ├── 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
@@ -405,6 +419,7 @@ scripts/
 ├── integration-test.sh
 ├── mark-test-passed.js  # Writes the current git HEAD SHA to .test-passed for the pre-push SHA cache
 ├── postinstall.js  # Post-install script for amicus
+├── probe-darwin-extract.js
 ├── probe-max-tokens.js  # Wire probe for issue #218: what max_tokens / reasoning / thinking does the
 ├── run-integration-keyless.js
 ├── setup-hooks.js  # Configure git to run the version-controlled hooks in .husky/.
@@ -550,14 +565,23 @@ 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-exe-rel.js` | WHICH exe a package resolves through, and whether a `dist/` HOLDS one. | `platformExe()`, `writePathTxt()`, `heldExeRel()`, `distHeldExe()` |
 | `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-provision.js` | Electron CONTROLLED provision — the pinned download, and what happens to a | `cacheRootFor()`, `controlledProvision()`, `mayDeleteRejectedZip()`, `rejectCachedZip()`, `isUnsafeArchive()` |
+| `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, the gate, and the env scrub. | `electronTrustPolicy()`, `resolveAnchor()`, `expectedDigest()`, `verifyArtifact()`, `sha256File()` |
+| `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()` |
@@ -594,10 +618,15 @@ 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-local-name-scan.js` | THE OTHER TABLE AN ARCHIVE DECLARES ITS NAMES IN — the local file headers. | `scanLocalNames()`, `declaredCentralOffset()` |
+| `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,17 +343,22 @@ 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. 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 one case only: you deliberately run a **rebuilt** Electron whose bytes legitimately differ. 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 does not re-enable
-> anything else. `npm_config_electron_mirror`, `npm_package_config_electron_*`,
-> `npm_config_electron_use_remote_checksums`, `npm_config_platform` and
-> `npm_config_arch` stay stripped from the Electron installer's environment
-> whether it is set or not — those are the names a *repository* can plant in a
-> child process 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. It also does not change where the download comes from — a real
+| `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
@@ -361,6 +366,109 @@ These variables control the polling loop that drives headless sessions. The defa
 > (`@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 entry names the archive declares and refuses any that yauzl would have
+> refused**, before it hands anything to a native extractor — and it reads them in
+> **both of the tables a zip declares them in**, the central directory and the
+> local file headers. That second walk is not belt-and-braces. An archive can
+> blind the central directory while leaving every local header whole — a
+> truncation does it by accident, and four one-field edits to a complete
+> end-of-central-directory record do it on purpose — and measured, seven such
+> archives carrying a `../../../` entry reached a native extractor before this
+> was added, two of them running to completion. The tables can also **disagree**,
+> and the tools do not agree on which one to believe: measured, `tar.exe` wrote
+> the name from the LOCAL header and `Expand-Archive` the one from the CENTRAL
+> directory. A refusal in either table refuses the archive.
+>
+> Residuals survive, and none is engineered away:
+>
+> - An archive that defeats **both** walks still reaches the native extractor.
+>   That is rarer than it was — a truncated zip, the commonest thing this rescue
+>   exists for, still yields all of its local names — but it is not impossible,
+>   and the notice printed before the spawn now tells you **which** names were
+>   checked rather than letting you assume they all were.
+> - 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.
+> - The name walk trusts a local header's declared size to find the next one, and
+>   a wrong size is a property of exactly the corrupt archives this rescue is for.
+>   A desynchronised walk can read a "name" out of payload bytes. It fails toward
+>   **refusing**, so it can cost a rescue and never grant one.
+>
+> When a name check cannot see it, the remaining check is the extractor's own, and
+> those are measured on every CI run rather than asserted here
+> (`tests/sidecar/native-extractor-containment.test.js`, 12 escape shapes per
+> strategy). At the time of writing: `tar.exe` refuses `..` (`Path contains '..'`,
+> exit 1) and strips absolute and drive-letter names into the destination;
+> `Expand-Archive` refuses `..` (`Can not process invalid archive entry '…'`) and
+> errors out on drive-letter and `\\?\` shapes with an empty destination; Info-ZIP
+> `unzip` contains by stripping the escaping components and writing the entry
+> inside the destination under a mangled name (its own `-hh` text documents this
+> as the default, with `-:` as the opt-out, which amicus does not pass); GNU `tar`
+> cannot read a zip at all. **`ditto`, the first macOS strategy, is the one that
+> remains unmeasured.**
+>
+> Everything amicus writes for a rescue goes under a private incoming directory
+> that is deleted unconditionally afterwards, and the child is run with that
+> directory as its working directory, so a relative write lands where the cleanup
+> reaches. What amicus cannot clean up is a write a native tool makes to an
+> absolute path outside that tree. 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.
+
 ---
 
 ## Process Lifecycle