amicus 1.7.2 → 1.7.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "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" },
   "homepage": "https://bourbondog.github.io/amicus/",

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.7.4] - 2026-06-30
+
+### Fixed
+- **The Electron GUI self-heal survives a stalled `extract-zip` on Node 24.** On some Node 24 boxes the
+  bundled `extract-zip@2.0.1` (its latest release — it cannot be bumped) stalls mid-extract: its promise
+  never resolves *and* never rejects. Because the self-heal `await`s it, the event loop drains and the
+  process exits `0` with a half-extracted `dist/` and **no `electron.exe`** — so the repair looked like it
+  "did nothing." Extraction is now hardened two ways: `extract-zip` is bounded by an idle + max timer (a
+  stall becomes a caught error instead of a silent hang, and the live timer prevents the premature exit),
+  and if it stalls, throws, or produces no files, amicus falls back to a **native OS unzip** (Windows:
+  bundled `bsdtar`, then PowerShell `Expand-Archive`; macOS: `ditto`, then `unzip`; Linux: `unzip`, then
+  `tar`) — each verified to extract the exact Electron zip that `extract-zip` choked on. Success is still
+  reported **only** when the real binary lands on disk (the existing exe-stat verify is unchanged), so no
+  path can claim a false repair.
+
+## [1.7.3] - 2026-06-30
+
+### Fixed
+- **The Electron self-heal no longer wedges itself.** A repair that was killed or hung mid-run (or a
+  pre-1.7.3 build) could leave an orphaned single-flight lockfile, after which *every* subsequent repair
+  — including `amicus doctor --fix` and the GUI launch — reported "another electron repair is already in
+  progress" and did nothing. The lock now records the holder's PID + timestamp and reclaims an orphaned
+  lock (dead holder, older than a 15-minute TTL, or the old empty format), so the GUI can self-heal
+  again; a live, recent holder still yields honest contention (no double-extract). The controlled
+  download is time-boxed (and the last-resort installer bounded) so a stalled fetch can't recreate the
+  stuck lock. **After upgrading, an already-stuck lock clears itself on the next repair.**
+
 ## [1.7.2] - 2026-06-30
 
 The Electron self-heal now tells the truth, heals the cases it can, and clearly explains the ones it can't.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "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": [
     "claude",

package/src/sidecar/electron-install.js

@@ -22,11 +22,17 @@
 
 const fsDefault = require('fs');
 const path = require('path');
-const os = require('os');
 const { spawnSync } = require('child_process');
 
 const { resolveCacheRoots } = require('./electron-cache');
 const { avHint, verifyExtractOutcome: verifyQuarantine } = require('./electron-quarantine');
+const { acquireRepairLock } = require('./electron-lock');
+const { robustExtract } = require('./unzip');
+
+/** Self-heal progress line to stderr (visible during first-GUI provision). */
+function stderrLog(msg) {
+  try { process.stderr.write(`${msg}\n`); } catch { /* stderr closed */ }
+}
 
 /** Default on-disk location of the installed electron package. */
 function defaultElectronDir() {
@@ -115,22 +121,6 @@ function cachedZip({ version, platform = process.platform, arch = process.arch,
   return null;
 }
 
-/**
- * Single-flight lockfile: only one caller may extract/install at a time, so
- * concurrent callers don't double-extract (Windows EBUSY). Throws an
- * EEXIST-coded error when another holder is active.
- */
-function defaultAcquireLock({ electronDir, fs = fsDefault }) {
-  const lockPath = path.join(os.tmpdir(), `amicus-electron-repair-${Buffer.from(electronDir).toString('hex').slice(0, 16)}.lock`);
-  const fd = fs.openSync(lockPath, 'wx'); // EEXIST if held
-  return {
-    release() {
-      try { fs.closeSync(fd); } catch { /* ignore */ }
-      try { fs.rmSync(lockPath, { force: true }); } catch { /* ignore */ }
-    },
-  };
-}
-
 /** Restore path.txt so electron/index.js resolves the freshly-extracted exe. */
 function writePathTxt({ electronDir, platform, fs }) {
   fs.writeFileSync(path.join(electronDir, 'path.txt'), platformExe(platform));
@@ -166,6 +156,10 @@ async function controlledProvision({
     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 } },
   });
   await extractFromCache({ zip, electronDir, platform, extract, fs });
 }
@@ -211,10 +205,15 @@ async function repairElectron({
   deps = {},
 } = {}) {
   const fs = deps.fs || fsDefault;
-  const extract = deps.extract || require('extract-zip');
-  const spawn = deps.spawn || ((cmd, args, o) => spawnSync(cmd, args, { ...o, timeout: timeoutMs }));
+  // Default extract: extract-zip bounded (idle/max) + native-unzip fallback (extract-zip-node24 stall).
+  const extract = deps.extract
+    || ((zipPath, o) => robustExtract(zipPath, { ...o, platform, deps: { fs, log: stderrLog } }));
+  // Default-bound the last-resort installer spawn (8 min) so a first-GUI-use
+  // provision that reaches runInstaller without an explicit timeoutMs can't hang
+  // the holder — the caller's timeoutMs still wins when provided.
+  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) => defaultAcquireLock({ ...o, fs }));
+  const acquireLock = deps.acquireLock || ((o) => acquireRepairLock({ ...o, fs }));
   const downloadArtifact = deps.downloadArtifact || require('@electron/get').downloadArtifact;
 
   if (!version) {

package/src/sidecar/electron-lock.js

@@ -0,0 +1,95 @@
+/**
+ * Stale-aware single-flight lock for the electron self-heal (#53).
+ *
+ * Only one process may extract/install electron at a time (concurrent extracts
+ * trip Windows EBUSY). The lock is a file in the OS temp dir keyed by the
+ * electron dir. It records the holder PID + a timestamp so a LATER caller can
+ * detect — and STEAL — a lock orphaned by a killed/crashed/rebooted repair (or
+ * left by a pre-v1.7.3 build, which wrote an empty lockfile). A bare wx lock
+ * with no staleness recovery wedges EVERY future repair forever with "another
+ * electron repair is already in progress" once the holder dies without
+ * releasing — which is exactly what it did in the field.
+ */
+
+'use strict';
+
+const fsDefault = require('fs');
+const path = require('path');
+const os = require('os');
+
+/** A real repair (even a ~170MB download) finishes well within this. */
+const STALE_MS = 15 * 60 * 1000;
+
+/** Temp-dir lockfile path, keyed by the electron install dir. */
+function lockPathFor(electronDir) {
+  const key = Buffer.from(electronDir).toString('hex').slice(0, 16);
+  return path.join(os.tmpdir(), `amicus-electron-repair-${key}.lock`);
+}
+
+/**
+ * Is an existing lockfile orphaned? Stale when it predates STALE_MS, its holder
+ * process is gone (ESRCH), or it is empty / corrupt / pre-v1.7.3 format. A lock
+ * held by a LIVE, recent process is NOT stale (real contention).
+ * @returns {boolean}
+ */
+function isStaleLock(lockPath, fs = fsDefault, now = Date.now()) {
+  let raw;
+  try {
+    raw = fs.readFileSync(lockPath, 'utf-8');
+  } catch {
+    return false; // already gone — absent, not stale
+  }
+  let meta;
+  try {
+    meta = JSON.parse(raw);
+  } catch {
+    return true; // empty / corrupt / pre-v1.7.3 empty lockfile -> orphaned
+  }
+  if (typeof meta.at === 'number' && now - meta.at > STALE_MS) {
+    return true; // older than any real repair
+  }
+  if (typeof meta.pid === 'number') {
+    try {
+      process.kill(meta.pid, 0); // throws if the process is gone
+      return false; // holder alive
+    } catch (err) {
+      return !!(err && err.code === 'ESRCH'); // ESRCH => dead/stale; EPERM => alive (not ours)
+    }
+  }
+  return true; // no usable pid/timestamp -> treat as orphaned
+}
+
+/**
+ * Acquire the single-flight repair lock. Throws an EEXIST-coded error ONLY when
+ * a live, recent process genuinely holds it; otherwise steals an orphaned lock.
+ * @returns {{ release: () => void }}
+ */
+function acquireRepairLock({ electronDir, fs = fsDefault }) {
+  const lockPath = lockPathFor(electronDir);
+
+  function create() {
+    // Atomic exclusive create WITH content in a single call: the file is never
+    // observable empty (no open-then-write gap a concurrent reader could
+    // misjudge as a corrupt orphan and steal). 'wx' throws EEXIST if held.
+    fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, at: Date.now() }), { flag: 'wx' });
+  }
+
+  try {
+    create();
+  } catch (e) {
+    if (!e || e.code !== 'EEXIST') { throw e; }
+    if (!isStaleLock(lockPath, fs)) { throw e; } // genuinely held by a live process
+    // Steal the orphan, then re-create. If a real process races us into the
+    // gap, the second create() throws EEXIST and we surface honest contention.
+    try { fs.rmSync(lockPath, { force: true }); } catch { /* ignore */ }
+    create();
+  }
+
+  return {
+    release() {
+      try { fs.rmSync(lockPath, { force: true }); } catch { /* ignore */ }
+    },
+  };
+}
+
+module.exports = { acquireRepairLock, isStaleLock, lockPathFor, STALE_MS };

package/src/sidecar/unzip.js

@@ -0,0 +1,231 @@
+/**
+ * Robust unzip for the electron self-heal (#53 follow-up; extract-zip-node24).
+ *
+ * FIELD BUG: on some Node 24 boxes `extract-zip@2.0.1` STALLS mid-extract — its
+ * promise never resolves AND never rejects. Because the self-heal `await`s it,
+ * when the event loop drains Node exits 0 with a partial extract and no
+ * electron.exe, so `repairElectron` silently no-ops. extract-zip 2.0.1 is the
+ * LATEST published release, so "just bump it" is impossible.
+ *
+ * robustExtract() survives that with three independent layers, none of which
+ * can report a false success:
+ *   1. BOUND extract-zip with an idle timer (reset on each onEntry) + a hard max
+ *      timer, so a stall becomes a catchable outcome — and the live timer keeps
+ *      the event loop alive so the process can't exit 0 before we fall back.
+ *   2. FALL BACK to a native OS unzip (tar / Expand-Archive on Windows,
+ *      ditto / unzip on macOS, unzip / tar on Linux) — each confirmed to extract
+ *      the exact electron zip the field box choked on.
+ *   3. Only report success when files actually landed on disk. The electron
+ *      exe-stat verify stays upstream (electron-quarantine.verifyExtractOutcome).
+ *
+ * Everything network/spawn/timer-facing is dependency-INJECTABLE so tests never
+ * hit the real clock, spawn a real process, or extract a real binary.
+ */
+
+'use strict';
+
+const path = require('path');
+const fsDefault = require('fs');
+const { spawnSync } = require('child_process');
+
+// No-progress window: if extract-zip reports no new entry for this long AND has
+// not settled, treat it as the silent stall. Reset on every onEntry so a slow-
+// but-progressing extract is never falsely aborted.
+const IDLE_MS = 30_000;
+// Hard cap so a "drips one entry forever" pathology can't run unbounded.
+const MAX_MS = 240_000;
+
+/** PowerShell single-quoted string literal, injection-safe (double any quote). */
+function psQuote(s) {
+  return `'${String(s).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Native OS unzip strategies, tried in order per platform. Each writes the
+ * zip's entries at the ROOT of `dir` — the SAME on-disk layout extract-zip
+ * produces (electron.exe, resources/, locales/, ...). Confirmed on the field
+ * box (Expand-Archive) and locally (tar/bsdtar + Expand-Archive, both <1s).
+ * @returns {Array<{name:string, cmd:string, args:string[]}>}
+ */
+function nativeUnzipPlan(zip, dir, platform = process.platform) {
+  if (platform === 'win32') {
+    // ABSOLUTE path to System32 bsdtar (Win10 1803+/11). A bare "tar" resolves
+    // to GNU tar when git-bash/MSYS is on PATH — GNU tar reads "C:\..." as a
+    // remote host ("Cannot connect to C:") and can't read zips at all. path.win32
+    // keeps this a valid Windows path even when the plan is built off-Windows.
+    const winTar = path.win32.join(process.env.SystemRoot || process.env.windir || 'C:\\Windows', 'System32', 'tar.exe');
+    return [
+      // bsdtar — fast, auto-detects zip format. If absent (rare/WOW64), the
+      // spawn errors ENOENT and we fall through to Expand-Archive below.
+      { name: 'tar', cmd: winTar, args: ['-xf', zip, '-C', dir] },
+      // Universal Windows fallback; silence progress so stdio:'ignore' is clean.
+      {
+        name: 'Expand-Archive',
+        cmd: 'powershell',
+        args: ['-NoProfile', '-NonInteractive', '-Command',
+          `$ProgressPreference='SilentlyContinue'; Expand-Archive -LiteralPath ${psQuote(zip)} -DestinationPath ${psQuote(dir)} -Force`],
+      },
+    ];
+  }
+  if (platform === 'darwin') {
+    return [
+      { name: 'ditto', cmd: 'ditto', args: ['-x', '-k', zip, dir] },
+      { name: 'unzip', cmd: 'unzip', args: ['-o', '-q', zip, '-d', dir] },
+    ];
+  }
+  return [
+    { name: 'unzip', cmd: 'unzip', args: ['-o', '-q', zip, '-d', dir] },
+    { name: 'tar', cmd: 'tar', args: ['-xf', zip, '-C', dir] },
+  ];
+}
+
+/** True if `dir` exists and holds at least one entry. */
+function dirNonEmpty(fs, dir) {
+  try {
+    return fs.readdirSync(dir).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Remove everything inside `dir` (best-effort) so the next strategy starts clean. */
+function cleanDir(fs, dir) {
+  try {
+    for (const entry of fs.readdirSync(dir)) {
+      fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Run extract-zip bounded by an idle timer (reset on each onEntry) and a hard
+ * max timer. NEVER rejects — resolves {ok:true} on completion, {ok:false,reason}
+ * on stall/throw. The timers keep the event loop alive so a stalled extract
+ * can't let the process exit 0 before we fall back. NOTE: a stalled extract-zip
+ * promise is abandoned (2.0.1 has no cancel API); it holds a fd until the short-
+ * lived process exits — acceptable versus a wedged, no-op self-heal.
+ */
+function runExtractZipBounded({ zip, dir, onEntry, extractZip, idleMs, maxMs, setTimer, clearTimer }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let idleTimer = null;
+    let maxTimer = null;
+    const done = (val) => {
+      if (settled) { return; }
+      settled = true;
+      if (idleTimer !== null) { clearTimer(idleTimer); }
+      if (maxTimer !== null) { clearTimer(maxTimer); }
+      resolve(val);
+    };
+    const armIdle = () => {
+      if (idleTimer !== null) { clearTimer(idleTimer); }
+      idleTimer = setTimer(() => done({ ok: false, reason: `stalled: no extract progress for ${idleMs}ms` }), idleMs);
+    };
+    maxTimer = setTimer(() => done({ ok: false, reason: `stalled: exceeded ${maxMs}ms` }), maxMs);
+    armIdle();
+    try {
+      const result = extractZip(zip, {
+        dir,
+        onEntry: (entry, zipfile) => {
+          armIdle(); // progress → restart the idle window
+          if (onEntry) {
+            try { onEntry(entry, zipfile); } catch { /* caller onEntry must not break extraction */ }
+          }
+        },
+      });
+      Promise.resolve(result).then(
+        () => done({ ok: true }),
+        (e) => done({ ok: false, reason: (e && e.message) || 'extract-zip threw' }),
+      );
+    } catch (e) {
+      done({ ok: false, reason: (e && e.message) || 'extract-zip threw synchronously' });
+    }
+  });
+}
+
+/**
+ * Extract `zip` into `dir`, surviving a stalled or broken extract-zip.
+ *
+ * CONTRACT: a returned {strategy} means files LANDED in `dir` — NOT that any
+ * specific payload (e.g. electron.exe) is present. Callers needing a usable
+ * binary MUST still stat it (electron-quarantine.verifyExtractOutcome does).
+ *
+ * @param {string} zip absolute path to the .zip
+ * @param {object} opts
+ * @param {string}   opts.dir destination dir (created if absent)
+ * @param {function} [opts.onEntry] forwarded to extract-zip's onEntry
+ * @param {string}   [opts.platform] override process.platform (native plan)
+ * @param {number}   [opts.idleMs] no-progress window before treating as stalled
+ * @param {number}   [opts.maxMs] hard cap for both extract-zip and each spawn
+ * @param {object}   [opts.deps] injected { fs, extractZip, spawn, setTimeout, clearTimeout, log }
+ * @returns {Promise<{strategy:string, fallback?:boolean, extractZipReason?:string}>}
+ * @throws {Error} code 'UNZIP_ALL_FAILED' when no strategy produced files.
+ */
+async function robustExtract(zip, opts = {}) {
+  const {
+    dir,
+    onEntry,
+    platform = process.platform,
+    idleMs = IDLE_MS,
+    maxMs = MAX_MS,
+    deps = {},
+  } = opts;
+  const fs = deps.fs || fsDefault;
+  const extractZip = deps.extractZip || require('extract-zip');
+  const spawn = deps.spawn || spawnSync;
+  const setTimer = deps.setTimeout || setTimeout;
+  const clearTimer = deps.clearTimeout || clearTimeout;
+  const log = deps.log || (() => {});
+
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Strategy 1: extract-zip, bounded. Trust it only if it RESOLVED and files landed.
+  const z = await runExtractZipBounded({ zip, dir, onEntry, extractZip, idleMs, maxMs, setTimer, clearTimer });
+  if (z.ok && dirNonEmpty(fs, dir)) {
+    return { strategy: 'extract-zip' };
+  }
+
+  // extract-zip stalled / threw / produced nothing → clean partial output, go native.
+  const zipReason = z.ok ? 'extract-zip produced no files' : z.reason;
+  cleanDir(fs, dir);
+  log(`[amicus] extract-zip did not complete (${zipReason}); falling back to native unzip.`);
+
+  const failures = [];
+  for (const strat of nativeUnzipPlan(zip, dir, platform)) {
+    let res;
+    try {
+      res = spawn(strat.cmd, strat.args, { stdio: 'ignore', windowsHide: true, timeout: maxMs });
+    } catch (e) {
+      failures.push(`${strat.name}: spawn ${(e && e.code) || (e && e.message) || 'threw'}`);
+      continue;
+    }
+    // A spawn error OR an external signal-kill (status:null, e.g. SIGKILL/OOM,
+    // possibly leaving partial files) is a FAILURE — never trust dirNonEmpty here.
+    if (res && (res.error || res.signal)) {
+      failures.push(`${strat.name}: ${res.error ? (res.error.code || res.error.message) : `killed by ${res.signal}`}`);
+      cleanDir(fs, dir);
+      continue;
+    }
+    if (res && typeof res.status === 'number' && res.status !== 0) {
+      failures.push(`${strat.name}: exit ${res.status}`);
+      cleanDir(fs, dir);
+      continue;
+    }
+    if (dirNonEmpty(fs, dir)) {
+      log(`[amicus] recovered via native unzip (${strat.name}).`);
+      return { strategy: strat.name, fallback: true, extractZipReason: zipReason };
+    }
+    failures.push(`${strat.name}: produced no files`);
+    cleanDir(fs, dir);
+  }
+
+  const err = new Error(
+    `unzip failed for ${zip} (extract-zip: ${zipReason}; native: ${failures.join('; ') || 'no native strategy available'})`,
+  );
+  err.code = 'UNZIP_ALL_FAILED';
+  throw err;
+}
+
+module.exports = { robustExtract, nativeUnzipPlan, IDLE_MS, MAX_MS };