amicus 2.2.0 → 3.0.0

package/.claude-plugin/plugin.json

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

@@ -5,6 +5,43 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-07-15
+
+### ⚠️ Breaking
+
+- **Node >=22.12 is now required** (`engines.node`). Amicus 3.0 fails fast on older Node with a
+  clear message instead of a confusing error deep in provisioning. This is driven by
+  `@electron/get` 5.x (ESM-only, requires Node >=22.12), which the Electron self-heal depends on.
+  Node 18/20 users — **including headless / council-only users who never touch the GUI** — must
+  upgrade Node.
+- **Electron upgraded 28 -> 43.1.1**, which drops OS support for **Windows 8/8.1, Windows Server
+  2012/2012 R2, and macOS 11**. The interactive GUI will not run there; headless runs and the
+  council are unaffected.
+
+### Changed
+
+- **Electron 28.3.3 -> 43.1.1**, clearing the outstanding high-severity `npm audit` finding
+  (ASAR Integrity Bypass, GHSA-vmqv-hx8q-j7mg). Amicus runs Electron **unpackaged**, so the
+  ASAR-integrity attack class never applied to its deployment — the concrete effect is a clean
+  audit and staying on a supported Electron line.
+- **Content view migrated from the deprecated `BrowserView` to `WebContentsView`**
+  (`mainWindow.contentView.addChildView`). All four windows now set `sandbox` explicitly.
+- **`@electron/get` 2.x -> 5.x** (now a direct `dependency`, ESM-only). The self-heal defers a
+  lazy dynamic `import()` to the network path and bounds the download with an `AbortSignal`
+  timeout (5.x dropped the old `got`-style timeout).
+- CI matrices raised to Node 22/24.
+
+### Fixed
+
+- Runtime Node-version guard (`src/utils/node-version-guard.js`) fires early in `bin/amicus.js`,
+  before heavy imports, so an unsupported Node fails with an actionable message.
+
+### Known limitations
+
+- `@electron/get` 5.x uses native `fetch`, which does **not** honor `HTTPS_PROXY` / `NO_PROXY`.
+  Provisioning Electron behind a corporate proxy needs a manual cache copy or `ELECTRON_MIRROR`
+  (see `docs/troubleshooting.md`). Headless runs and the council never download Electron.
+
 ## [2.2.0] - 2026-07-14
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 **A multi-model LLM Council for Claude — with a parallel AI window underneath.**
 
-![Amicus: an LLM Council and a parallel AI window for Claude](./docs/hero.png)
+![The Amicus council mid-ritual: five models — Gemini 3 Pro, Llama 4, Grok 4, Claude Opus — reading the same material independently, chaired by GPT-5](./docs/council.png)
 
 Hand Claude a plan, a design, a diff, an architecture decision, a manuscript — anything — and say *council review this*: Amicus routes it through several models from different families, has them anonymously cross-review each other, and a non-Claude chair synthesizes a verdict you turn into accept/deny edits. Or skip the ceremony and **fork** a single conversation to Gemini, GPT, DeepSeek, or any other model — it works in parallel with full context, and you **fold** the result back when you're ready. Claude orchestrates throughout; you stay in your editor.
 
@@ -53,10 +53,6 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 
 ![What one install delivers: council skill, chat skill, CLI + MCP, live catalog](./docs/what-is-amicus.png)
 
-The council skill in one picture — independent review, before cross-review or the verdict, with Claude Opus seated among the models it's judging:
-
-![The Amicus council mid-ritual: five models — Gemini 3 Pro, Llama 4, Grok 4, Claude Opus — reading the same material independently, chaired by GPT-5](./docs/council.png)
-
 ---
 
 ## Quick start
@@ -323,7 +319,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -7,6 +7,11 @@
  * Routes commands to appropriate handlers.
  */
 
+// Node version guard: fail fast on unsupported Node versions
+const { checkNodeVersion } = require('../src/utils/node-version-guard');
+const _nv = checkNodeVersion(process.version);
+if (!_nv.ok) { process.stderr.write(_nv.message + '\n'); process.exit(1); }
+
 // Load API keys from all sources: process.env > amicus .env > auth.json
 const { loadCredentials } = require('../src/utils/env-loader');
 loadCredentials();

package/electron/close-guard.js

@@ -54,9 +54,9 @@
  * @param {() => boolean} [deps.hasCompleted] - Whether the fold's
  *   `[SIDECAR_FOLD]` stdout write has actually succeeded. Falls back to
  *   `hasFolded()` when omitted.
- * @param {(mainWindow: object, contentView: object) => Promise<void>} deps.triggerFold
+ * @param {(mainWindow: object, opencodeView: object) => Promise<void>} deps.triggerFold
  *   - The SAME fold.js closure used by the shortcut/toolbar/IPC paths.
- * @returns {{ handleClose: (event: object, mainWindow: object, contentView: object) => void }}
+ * @returns {{ handleClose: (event: object, mainWindow: object, opencodeView: object) => void }}
  */
 function createCloseGuard({ hasFolded, isFolding, hasCompleted, triggerFold }) {
   const checkIsFolding = isFolding || hasFolded;
@@ -78,7 +78,7 @@ function createCloseGuard({ hasFolded, isFolding, hasCompleted, triggerFold }) {
     }
   }
 
-  function handleClose(event, mainWindow, contentView) {
+  function handleClose(event, mainWindow, opencodeView) {
     if (checkHasCompleted()) {
       // Fold already completed — proceed exactly like the pre-existing
       // behavior (no interception, no destroy call from the guard itself;
@@ -110,7 +110,7 @@ function createCloseGuard({ hasFolded, isFolding, hasCompleted, triggerFold }) {
     }
     closeFoldAttempted = true;
 
-    Promise.resolve(triggerFold(mainWindow, contentView)).then(() => {
+    Promise.resolve(triggerFold(mainWindow, opencodeView)).then(() => {
       // triggerFold can RESOLVE without ever calling mainWindow.close() —
       // its outer catch swallows failures (including a synchronous throw
       // from the post-write nudge-overlay executeJavaScript call, which can

package/electron/fold.js

@@ -41,13 +41,13 @@ function createFoldHandler(state) {
   let folded = false;
   let completed = false;
 
-  async function triggerFold(mainWindow, contentView) {
+  async function triggerFold(mainWindow, opencodeView) {
     if (folded) { return; }
     folded = true;
     completed = false;
 
     // Show fold progress in toolbar and content overlay
-    showFoldOverlay(mainWindow, contentView);
+    showFoldOverlay(mainWindow, opencodeView);
 
     try {
       // Ask the model to generate a structured summary
@@ -76,8 +76,8 @@ function createFoldHandler(state) {
       logger.info('Fold completed', { taskId: state.taskId });
 
       // Show nudge overlay before closing
-      if (contentView) {
-        await contentView.webContents.executeJavaScript(`
+      if (opencodeView) {
+        await opencodeView.webContents.executeJavaScript(`
           (function() {
             var overlay = document.getElementById('amicus-fold-overlay');
             if (overlay) {
@@ -147,7 +147,7 @@ function createFoldHandler(state) {
  * Note: The JS strings below contain only hardcoded markup (no user input),
  * so there is no XSS risk from DOM manipulation.
  */
-function showFoldOverlay(mainWindow, contentView) {
+function showFoldOverlay(mainWindow, opencodeView) {
   if (mainWindow) {
     mainWindow.webContents.executeJavaScript(`
       (function() {
@@ -174,7 +174,7 @@ function showFoldOverlay(mainWindow, contentView) {
       })();
     `).catch(() => {});
   }
-  if (contentView) {
+  if (opencodeView) {
     // Scope token vars to the overlay container so var(--x) resolves without
     // touching OpenCode's own :root (which would clobber its CSS variables).
     const rawCss = tokenCss({ absoluteFontUrls: true });
@@ -182,9 +182,9 @@ function showFoldOverlay(mainWindow, contentView) {
     // custom properties are defined on #amicus-fold-overlay and inherited by
     // its descendants. @font-face blocks are left at global scope (no selector).
     const scopedCss = rawCss.replace(/:root\s*\{/, '#amicus-fold-overlay {');
-    contentView.webContents.insertCSS(scopedCss).catch(() => {});
+    opencodeView.webContents.insertCSS(scopedCss).catch(() => {});
 
-    contentView.webContents.executeJavaScript(`
+    opencodeView.webContents.executeJavaScript(`
       (function() {
         if (!document.getElementById('fold-spin-style')) {
           var style = document.createElement('style');

package/electron/ipc-guard.js

@@ -5,8 +5,8 @@
  * unit-testable (main.js itself runs heavy Electron side effects at import).
  *
  *  - isPrivilegedSender: pin privileged IPC handlers to the toolbar window so a
- *    compromised/remote page in the OpenCode BrowserView cannot invoke them (M9).
- *  - isAllowedContentNavigation: pin the OpenCode BrowserView to its localhost
+ *    compromised/remote page in the OpenCode WebContentsView cannot invoke them (M9).
+ *  - isAllowedContentNavigation: pin the OpenCode WebContentsView to its localhost
  *    origin so it cannot be navigated off to an attacker-controlled page (M9).
  *  - handleFatalException: EPIPE stays a no-op; any other uncaught exception is
  *    logged and then quits the app rather than leaving a wedged invisible shell
@@ -26,7 +26,7 @@ function isPrivilegedSender(event, getToolbarWindow) {
 }
 
 /**
- * Whether a navigation target is allowed for the OpenCode content BrowserView.
+ * Whether a navigation target is allowed for the OpenCode content WebContentsView.
  * Only the OpenCode localhost origin (any path) is permitted; everything else
  * (external http(s), file:, etc.) is blocked. data: URLs are allowed so the
  * in-app load-error page can render.

package/electron/main.js

@@ -1,7 +1,7 @@
 /**
  * Amicus Electron Shell - v3
  *
- * Uses BrowserView to split the window into two physical areas:
+ * Uses WebContentsView to split the window into two physical areas:
  *   - Top: OpenCode Web UI (gets its own viewport, no CSS conflicts)
  *   - Bottom 40px: Amicus toolbar (branding, task ID, timer, fold button)
  *
@@ -12,7 +12,7 @@
  * Spec Reference: §4.4 Electron Wrapper
  */
 
-const { app, BrowserWindow, BrowserView, globalShortcut, ipcMain, screen } = require('electron');
+const { app, BrowserWindow, WebContentsView, globalShortcut, ipcMain, screen } = require('electron');
 const path = require('path');
 const { logger } = require('../src/utils/logger');
 const { buildToolbarHTML, TOOLBAR_H, getBrandName } = require('./toolbar');
@@ -84,7 +84,7 @@ const OPENCODE_URL = `http://localhost:${OPENCODE_PORT}`;
 // ============================================================================
 
 let mainWindow = null;
-let contentView = null;
+let opencodeView = null;
 let currentToolbarH = TOOLBAR_H;
 
 const foldHandler = createFoldHandler({
@@ -127,7 +127,7 @@ function createAmicusWindow() {
     icon: ICON_PATH,
     webPreferences: {
       preload: path.join(__dirname, 'preload.js'),
-      contextIsolation: true, nodeIntegration: false,
+      contextIsolation: true, nodeIntegration: false, sandbox: true,
     }
   });
 
@@ -157,27 +157,27 @@ function createAmicusWindow() {
   mainWindow.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(toolbarHtml)}`);
   mainWindow.webContents.on('page-title-updated', (e) => e.preventDefault());
 
-  // BrowserView for OpenCode content. It uses a MINIMAL preload that exposes no
+  // WebContentsView for OpenCode content. It uses a MINIMAL preload that exposes no
   // privileged bridge — the OpenCode page must not be able to reach the fold /
   // settings / update IPC (M9). The toolbar window keeps preload.js.
-  contentView = new BrowserView({
+  opencodeView = new WebContentsView({
     webPreferences: {
       preload: path.join(__dirname, 'preload-content.js'),
-      contextIsolation: true, nodeIntegration: false,
+      contextIsolation: true, nodeIntegration: false, sandbox: true,
     }
   });
 
   // Pin the content view to the OpenCode localhost origin: block any attempt to
   // navigate it off-origin or open new windows (defense-in-depth, M9). data:
   // URLs (the in-app load-error page) are still allowed by the guard.
-  contentView.webContents.on('will-navigate', (event, targetUrl) => {
+  opencodeView.webContents.on('will-navigate', (event, targetUrl) => {
     if (!isAllowedContentNavigation(targetUrl, OPENCODE_URL)) {
       logger.warn('Blocked content-view navigation', { targetUrl });
       event.preventDefault();
     }
   });
-  contentView.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
-  // Load OpenCode off-screen first; only attach BrowserView after rebranding
+  opencodeView.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
+  // Load OpenCode off-screen first; only attach WebContentsView after rebranding
   // to prevent the OpenCode logo/splash from flashing during load.
   mainWindow.on('resize', updateContentBounds);
 
@@ -190,9 +190,9 @@ function createAmicusWindow() {
   // is token-driven — it inlines tokenCss() and remaps OpenCode's own :root
   // custom properties — so it tracks the toolbar without brittle class
   // selectors. insertCSS is more reliable than preload DOM injection in a
-  // BrowserView. NOTE: the live visual match is a user-side CDP/manual check.
-  contentView.webContents.on('dom-ready', () => {
-    contentView.webContents.insertCSS(buildOpencodeThemeCSS()).catch(() => {});
+  // WebContentsView. NOTE: the live visual match is a user-side CDP/manual check.
+  opencodeView.webContents.on('dom-ready', () => {
+    opencodeView.webContents.insertCSS(buildOpencodeThemeCSS()).catch(() => {});
   });
 
   // Navigate directly to the session URL to bypass the project selection screen.
@@ -205,7 +205,7 @@ function createAmicusWindow() {
   // failsafe, a failed/stalled UI load leaves an invisible window and a
   // silently hung process (the historical "Starting up... | 0 messages" bug).
   const failsafe = attachLoadFailsafe({
-    webContents: contentView.webContents,
+    webContents: opencodeView.webContents,
     timeoutMs: parseInt(process.env.AMICUS_GUI_LOAD_TIMEOUT_MS || '', 10) || undefined,
     onFail: ({ reason, errorCode, errorDescription, validatedURL }) => {
       logger.error('OpenCode UI failed to load', {
@@ -215,12 +215,12 @@ function createAmicusWindow() {
         const html = buildLoadErrorHTML({
           url: validatedURL || contentUrl, errorCode, errorDescription
         });
-        contentView.webContents
+        opencodeView.webContents
           .loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(html)}`)
           .catch(() => {});
       }
       // On timeout, show whatever is in flight rather than aborting the load.
-      mainWindow.addBrowserView(contentView);
+      mainWindow.contentView.addChildView(opencodeView);
       updateContentBounds();
       if (!process.env.AMICUS_HEADLESS_TEST) {
         mainWindow.show();
@@ -228,16 +228,16 @@ function createAmicusWindow() {
     }
   });
 
-  contentView.webContents.loadURL(contentUrl);
+  opencodeView.webContents.loadURL(contentUrl);
 
-  contentView.webContents.on('did-finish-load', () => {
+  opencodeView.webContents.on('did-finish-load', () => {
     // Wait for React to render, then rebrand and show window
     setTimeout(() => {
       rebrandUI().then(() => {
         // Disarm only once the window is actually about to show, so a wedged
         // rebrand/executeJavaScript is still covered by the timeout.
         failsafe.cancel();
-        mainWindow.addBrowserView(contentView);
+        mainWindow.contentView.addChildView(opencodeView);
         updateContentBounds();
         if (!process.env.AMICUS_HEADLESS_TEST) {
           mainWindow.show();
@@ -247,7 +247,7 @@ function createAmicusWindow() {
   });
 
   globalShortcut.register(FOLD_SHORTCUT, () => {
-    foldHandler.triggerFold(mainWindow, contentView);
+    foldHandler.triggerFold(mainWindow, opencodeView);
   });
 
   // Poll toolbar for button clicks (IPC doesn't work with data: URLs).
@@ -258,7 +258,7 @@ function createAmicusWindow() {
       if (!action) { return; }
       mainWindow.webContents.executeJavaScript('window.__amicusToolbarAction = null');
       if (action === 'fold') {
-        foldHandler.triggerFold(mainWindow, contentView);
+        foldHandler.triggerFold(mainWindow, opencodeView);
       } else if (action === 'open-settings') {
         createSettingsChildWindow();
       }
@@ -300,11 +300,11 @@ function createAmicusWindow() {
   }
 
   mainWindow.on('close', (event) => {
-    closeGuard.handleClose(event, mainWindow, contentView);
+    closeGuard.handleClose(event, mainWindow, opencodeView);
   });
   mainWindow.on('closed', () => {
     mainWindow = null;
-    contentView = null;
+    opencodeView = null;
     globalShortcut.unregisterAll();
     app.quit();
   });
@@ -334,7 +334,7 @@ async function createSetupWindow() {
     resizable: false,
     webPreferences: {
       preload: path.join(__dirname, 'preload-setup.js'),
-      contextIsolation: true, nodeIntegration: false,
+      contextIsolation: true, nodeIntegration: false, sandbox: false, // preload-setup.js require()s shell (not sandbox-safe)
     }
   });
 
@@ -356,9 +356,9 @@ async function createSetupWindow() {
 // ============================================================================
 
 function updateContentBounds() {
-  if (!mainWindow || !contentView) { return; }
+  if (!mainWindow || !opencodeView) { return; }
   const [w, h] = mainWindow.getContentSize();
-  contentView.setBounds({ x: 0, y: 0, width: w, height: h - currentToolbarH });
+  opencodeView.setBounds({ x: 0, y: 0, width: w, height: h - currentToolbarH });
 }
 
 // Amicus wordmark SVG in the same pixel/block art style as the OpenCode logo.
@@ -387,12 +387,12 @@ const AMICUS_WORDMARK = [
 ].join('');
 
 function rebrandUI() {
-  if (!contentView) { return Promise.resolve(); }
+  if (!opencodeView) { return Promise.resolve(); }
   const brandName = getBrandName(CLIENT);
   // The OpenCode logo may be hidden (display:none/visibility:hidden) by preload.js
   // or insertCSS before this runs. Use a MutationObserver with a fallback timeout
   // to catch it whenever React renders it into the DOM.
-  return contentView.webContents.executeJavaScript(`
+  return opencodeView.webContents.executeJavaScript(`
     (function() {
       document.title = '${brandName}';
       var header = document.querySelector('#root > div > header');
@@ -436,7 +436,7 @@ function rebrandUI() {
 // ============================================================================
 
 // These handlers are privileged (fold/settings/update/resize). Only the toolbar
-// window may invoke them — the OpenCode content BrowserView must not (M9). The
+// window may invoke them — the OpenCode content WebContentsView must not (M9). The
 // content view no longer gets a bridge preload, but we still validate the
 // sender as belt-and-suspenders in case a future preload change reintroduces one.
 const fromToolbar = (event) => isPrivilegedSender(event, () => mainWindow);
@@ -444,7 +444,7 @@ const fromToolbar = (event) => isPrivilegedSender(event, () => mainWindow);
 // Amicus mode: fold
 ipcMain.handle('sidecar:fold', (event) => {
   if (!fromToolbar(event)) { return; }
-  return foldHandler.triggerFold(mainWindow, contentView);
+  return foldHandler.triggerFold(mainWindow, opencodeView);
 });
 
 // Amicus mode: open settings in a child window
@@ -498,7 +498,7 @@ function createSettingsChildWindow() {
     resizable: false,
     webPreferences: {
       preload: path.join(__dirname, 'preload-setup.js'),
-      contextIsolation: true, nodeIntegration: false,
+      contextIsolation: true, nodeIntegration: false, sandbox: false, // shares preload-setup.js (shell)
     }
   });
 

package/electron/opencode-theme.js

@@ -3,7 +3,7 @@
 /**
  * Issue #49 — token-driven theme for the embedded OpenCode web UI.
  *
- * main.js injects this via `contentView.webContents.insertCSS(...)` on
+ * main.js injects this via `opencodeView.webContents.insertCSS(...)` on
  * `dom-ready`. Before #49 that hook only HID OpenCode's header/wordmark; this
  * module extends it so the embedded chat surface inherits the clay/gold tokens
  * and matches the token-driven Amicus toolbar (toolbar.js).
@@ -13,7 +13,7 @@
  * PREFER overriding OpenCode's OWN :root CSS custom properties — a much more
  * stable surface than `.css-abc123` class selectors. We:
  *   1. inline the canonical token CSS (tokenCss) so OUR vars + @font-face are
- *      available inside the BrowserView (absolute font URLs, same as toolbar.js
+ *      available inside the WebContentsView (absolute font URLs, same as toolbar.js
  *      / setup-ui-styles.js / load-failsafe.js do),
  *   2. remap a generous superset of OpenCode's plausible theme custom-property
  *      names to our tokens (var(--...)), covering the prefixes OpenCode has
@@ -115,7 +115,7 @@ const ELEMENT_FALLBACKS = `
 `;
 
 /**
- * Build the full theme CSS string injected into the OpenCode BrowserView.
+ * Build the full theme CSS string injected into the OpenCode WebContentsView.
  * @returns {string} hide-chrome + inlined tokens + :root overrides + fallbacks.
  */
 function buildOpencodeThemeCSS() {

package/electron/preload-content.js

@@ -1,5 +1,5 @@
 /**
- * Content Preload - OpenCode BrowserView (minimal, no privileged bridge)
+ * Content Preload - OpenCode WebContentsView (minimal, no privileged bridge)
  *
  * The OpenCode Web UI is remote-ish content: it should NOT be able to reach the
  * privileged sidecar IPC (fold/open-settings/perform-update/...). This preload

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "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": [
@@ -69,6 +69,7 @@
     "check:tarball": "node scripts/check-tarball-lifecycle.js"
   },
   "dependencies": {
+    "@electron/get": "^5.0.0",
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@opencode-ai/sdk": "^1.1.36",
     "dotenv": "^17.2.3",
@@ -78,7 +79,7 @@
     "zod": "^3.0.0"
   },
   "optionalDependencies": {
-    "electron": "^28.0.0"
+    "electron": "^43.1.1"
   },
   "devDependencies": {
     "chrome-remote-interface": "^0.33.3",
@@ -90,7 +91,7 @@
     "ws": "^8.19.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "lint-staged": {
     "src/**/*.js": [

package/src/sidecar/electron-install.js

@@ -146,7 +146,7 @@ function cacheRootFor(env = process.env) {
  * @returns {Promise<void>}
  */
 async function controlledProvision({
-  electronDir, platform, arch, version, downloadArtifact, extract, fs, env = process.env,
+  electronDir, platform, arch, version, downloadArtifact, extract, fs, env = process.env, downloadMs = 480000,
 }) {
   const zip = await downloadArtifact({
     version,
@@ -155,11 +155,7 @@ async function controlledProvision({
     cacheRoot: cacheRootFor(env),
     platform,
     arch,
-    checksums: undefined,
-    // Bound the fetch so a stalled/blocked network aborts (got v11 timeouts:
-    // socket = inactivity, request = total) instead of hanging the repair —
-    // a hung-then-killed download is what orphaned the single-flight lock.
-    downloadOptions: { timeout: { socket: 60000, request: 480000 } },
+    downloadOptions: { signal: AbortSignal.timeout(downloadMs) }, // 5.x native fetch: bound stalled downloads, free the lock
   });
   await extractFromCache({ zip, electronDir, platform, extract, fs });
 }
@@ -214,7 +210,11 @@ async function repairElectron({
   const spawn = deps.spawn || ((cmd, args, o) => spawnSync(cmd, args, { ...o, timeout: timeoutMs || 480000 }));
   const findZip = deps.cachedZip || ((o) => cachedZip(o));
   const acquireLock = deps.acquireLock || ((o) => acquireRepairLock({ ...o, fs }));
-  const downloadArtifact = deps.downloadArtifact || require('@electron/get').downloadArtifact;
+  // Lazy: import the ESM-only @electron/get only on the network path, so cacheOnly
+  // repairs and injected mocks stay parseable under Jest (which can't import() ESM).
+  const resolveDownloadArtifact = deps.downloadArtifact
+    ? async () => deps.downloadArtifact
+    : async () => (await import('@electron/get')).downloadArtifact;
 
   if (!version) {
     try {
@@ -268,8 +268,9 @@ async function repairElectron({
     // download that produced no usable exe is a FAILURE (no false success; #53).
     let controlledExtracted = false;
     try {
+      const downloadArtifact = await resolveDownloadArtifact();
       await controlledProvision({
-        electronDir, platform, arch, version, downloadArtifact, extract, fs, env: process.env,
+        electronDir, platform, arch, version, downloadArtifact, extract, fs, env: process.env, downloadMs: timeoutMs,
       });
       controlledExtracted = true; // download + extract returned without throwing
     } catch {

package/src/utils/node-version-guard.js

@@ -0,0 +1,16 @@
+'use strict';
+const MIN_NODE = '22.12.0';
+
+/** @param {string} current @param {string} min @returns {{ok:boolean,message:string|null}} */
+function checkNodeVersion(current, min = MIN_NODE) {
+  const c = current.replace(/^v/, '').split('.').map(Number);
+  const m = min.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((c[i] || 0) > (m[i] || 0)) { return { ok: true, message: null }; }
+    if ((c[i] || 0) < (m[i] || 0)) {
+      return { ok: false, message: `Amicus 3.0 requires Node >=${min}; you are on ${current.replace(/^v/, '')}. Upgrade Node and retry.` };
+    }
+  }
+  return { ok: true, message: null };
+}
+module.exports = { checkNodeVersion, MIN_NODE };