amicus 4.9.6 → 4.9.7

package/.claude-plugin/plugin.json

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

package/README.md

@@ -455,7 +455,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.6",
+  "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.6** (2026-09-08). 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, v4.9.6's artifact custody) it did so to
+`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.6 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

@@ -112,6 +112,7 @@ src/
 │   ├── 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).
@@ -166,6 +167,7 @@ src/
 │   ├── 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/
@@ -417,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/.
@@ -566,6 +569,7 @@ evals/
 | `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()` |
@@ -620,6 +624,7 @@ evals/
 | `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()` |

package/docs/configuration.md

@@ -405,26 +405,54 @@ These variables control the polling loop that drives headless sessions. The defa
 > 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:
+> 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.
 >
-> - 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.**
+> 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.**
 >
-> 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.
+> 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

package/docs/electron-testing.md

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

package/docs/troubleshooting.md

@@ -452,10 +452,13 @@ That is what a swapped mirror or a planted cache file looks like. It is **also**
 
 **Fix, in order:**
 
-- **Online, do nothing.** Amicus downloads the artifact again with the digest pinned. A truncated download heals itself.
+- **Online, do nothing.** Amicus downloads the artifact again with the digest pinned. A truncated download
+  heals itself. The exception is an archive amicus refuses outright for path traversal — that is terminal
+  by design and is not re-fetched, because the problem is what the archive *contains*, not that it arrived
+  incomplete.
 - **Air-gapped, re-copy first.** Copy the cache directory again from the machine that downloaded it. A partial copy is the usual cause, and a fresh copy costs you nothing.
 - **Only if you cannot obtain another copy: the native-extractor rescue.** Set `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` and provision again. You do not have to have set it in advance: the run that printed the message above left the archive in place precisely so this one has something to work on. Amicus then writes the bytes it hashed to a path inside the Electron package and hands that path to your OS's own extractor (`tar` / `Expand-Archive` / `ditto` / `unzip`) — the same tools that handled the archive before amicus extracted in memory at all. **This is not a safe operation, and it is not described as one.** Between amicus writing the file and the child process opening it, anything running as your user can substitute it, and what that child extracts is promoted into `dist/` without being hashed again. Amicus prints the whole trade on stderr before it spawns anything, and the result is reported `unverified` even when the artifact's own sha256 matched. Unset the variable afterwards: it also downgrades a digest-mismatch refusal to a warning ([configuration.md](./configuration.md#gui-and-debug)).
-- **What the rescue will *not* do,** whatever this variable is set to: retry an archive refused for path traversal (`REFUSED (unsafe archive)` — terminal by design), retry an extraction that *stalled* (the timeout exists to stop work, not to hand it to a child process), rescue bytes that contradict the published digest (they are known wrong), or paper over a full or unwritable disk. Each of those says something different from "this archive cannot be read", and only the last of those is a rescue amicus was given. Before it hands anything over, amicus also reads the archive's *entry names* and refuses any that would write outside the destination — because an archive can break the extractor early enough that its own traversal check never ran. 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.
+- **What the rescue will *not* do,** whatever this variable is set to: retry an archive refused for path traversal (`REFUSED (unsafe archive)` — terminal by design), retry an extraction that *stalled* (the timeout exists to stop work, not to hand it to a child process), rescue bytes that contradict the published digest (they are known wrong), or paper over a full or unwritable disk. Each of those says something different from "this archive cannot be read", and only the last of those is a rescue amicus was given. Before it hands anything over, amicus also reads the archive's *entry names* and refuses any that would write outside the destination — because an archive can break the extractor early enough that its own traversal check never ran. It reads them in **both** tables a zip declares them in, so cutting the tail off an archive no longer hides its names, and the two tables disagreeing does not let one through. It still cannot see a symlink target, and an archive that defeats both walks still reaches the extractor — the notice printed before the spawn says which names were checked; [configuration.md](./configuration.md#gui-and-debug) states every residual and names which extractors were measured to refuse a `..` entry themselves.
 - Headless runs and the full council work without the GUI throughout.
 
 ---
@@ -514,11 +517,15 @@ The third line names which way the read failed:
   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.
+  the way (a handle held on it, or an AV filter denying the move) and it holds a usable executable —
+  the one `path.txt` names, or this platform's default when `path.txt` is absent, unreadable or blank
+  — the repair refuses and leaves it untouched rather than deleting it with no way back. That covers
+  a package cross-installed for another platform through `npm_config_platform`, whose `path.txt` names
+  an executable this platform never looks for; through v4.9.6 the guard asked only about this
+  platform's default name, so such a tree was read as "not an install" and a promote that FAILED
+  deleted it. If it holds neither, it is not an install, and it is replaced. In the one case where the
+  tree was renamed away and neither the swap nor the rollback could run, the previous `dist/` is
+  intact at `.amicus-retired-<hex>` and the error names it — rename it back to `dist/` to restore it.
 - **A related refusal**, `Refusing to provision electron: … is not a usable artifact name`, means the
   `version` in the Electron package's own `package.json` is not a plausible version string. Amicus
   builds the artifact filename from it and refuses to use anything that is not a plain filename, since

package/docs/usage.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.6",
+  "version": "4.9.7",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [