amicus 3.2.1 → 3.2.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "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,23 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [3.2.2] - 2026-07-17
+
+### Fixed
+
+- **A missing `opencode` engine now self-heals instead of failing every call.**
+  When the engine binary is absent at a fanout/start — a skipped
+  optional-dependency install or an antivirus quarantine of the npx-cache copy
+  the MCP launches — amicus recovers in place by copying the `opencode-*`
+  packages from a healthy sibling install (running, global, or another npx
+  copy), then proceeds, instead of throwing `engineMissing` on every leg
+  (report #2).
+
+### Added
+
+- **`amicus doctor --fix` repairs broken npx-cache engine copies**, self-healing
+  the copies the MCP actually launches, not just the running install.
+
 ## [3.2.1] - 2026-07-17
 
 ### Fixed

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "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": [
@@ -48,8 +48,8 @@
   "scripts": {
     "start": "node --experimental-top-level-await --experimental-vm-modules bin/amicus.js",
     "test": "jest",
-    "test:integration": "jest --testPathIgnorePatterns='\\.worktrees/' --testMatch='**/tests/**/*.integration.test.js'",
-    "test:all": "jest --testPathIgnorePatterns='/node_modules/' --testPathIgnorePatterns='\\.worktrees/' && node scripts/mark-test-passed.js",
+    "test:integration": "jest --testPathIgnorePatterns='worktrees' --testMatch='**/tests/**/*.integration.test.js'",
+    "test:all": "jest --testPathIgnorePatterns='/node_modules/' --testPathIgnorePatterns='worktrees' && node scripts/mark-test-passed.js",
     "test:e2e:mcp": "jest tests/mcp-repomix-e2e.integration.test.js --testTimeout=180000 --forceExit",
     "posttest": "node scripts/mark-test-passed.js",
     "lint": "eslint src/",

package/src/cli-handlers-doctor.js

@@ -42,6 +42,8 @@ function realDeps() {
     // engine-mcp check: probe the engine in every install that could serve the
     // MCP (running/global/npx-cache), not just the one doctor runs from (#1).
     scanEngineInstalls: () => require('./utils/engine-install-scan').scanEngineInstalls(),
+    // report #2: copy-from-sibling self-heal for `doctor --fix`.
+    repairEngine: (o) => require('./utils/engine-repair').repairEngine(o),
     getElectronPath: () => require('./sidecar/interactive-process').getElectronPath(),
     // #56: self-heal primitive for `doctor --fix`. Pure probe (getElectronPath)
     // stays separate; repair only runs when fix is requested.
@@ -150,7 +152,7 @@ async function runDoctorChecks(depsOverride = {}) {
   // Cross-install: verify the engine in the npx-cache copies the MCP actually
   // launches (`npx -y amicus@latest mcp`), so a green 'opencode-bin' (the running
   // install) can't hide a broken copy the MCP would spawn (bug report #1/#4).
-  checks.push(guard('engine-mcp', 'OpenCode engine (MCP launch path)', () => engineCheck.evaluateEngineInstalls(d)));
+  checks.push(await guardAsync('engine-mcp', 'OpenCode engine (MCP launch path)', () => engineCheck.evaluateEngineMcp(d)));
 
   checks.push(await guardAsync('electron', 'Electron (interactive GUI)', async () => {
     if (d.getElectronPath()) {

package/src/opencode-client.js

@@ -625,22 +625,27 @@ function buildServerHandle(sdkServer, deps = {}) {
  * @returns {Promise<{client: object, server: {url: string, close: Function}}>}
  */
 async function startServer(options = {}) {
-  // Fail fast with a CLEAR, actionable error when the opencode engine binary
-  // is absent (skipped optionalDependency install or AV quarantine). Without
-  // this, createOpencodeServer → spawn('opencode') fails with an opaque ENOENT.
-  // Checked BEFORE the SDK is loaded so the message is the first thing the user
-  // sees. `_hasOpencodeBinary` is a test seam; default is the shared resolver
-  // (single source of truth with `amicus doctor`). NOTE: this does NOT
-  // auto-repair — re-running the opencode postinstall is the same flaky trap.
+  // Fail fast when the opencode engine binary is absent (skipped
+  // optionalDependency install or AV quarantine). Before giving up, attempt an
+  // in-place self-heal: COPY the opencode-* packages from a healthy sibling
+  // install (engine-ensure) — NOT re-running the opencode postinstall, which is
+  // the same flaky optional-dependency trap. Only runs when truly missing; the
+  // fast path skips it. `_hasOpencodeBinary` / `_ensureEngine` are test seams.
   const hasOpencodeBinary = options._hasOpencodeBinary
     || require('./utils/path-setup').hasOpencodeBinary;
   if (!hasOpencodeBinary()) {
-    const HINTS = require('./utils/remediation-hints');
-    // Append the roots we actually probed so an npx-cache-vs-global divergence is
-    // visible at the point of failure, not just in `amicus doctor` (report #4).
-    const opencodeRoots = options._opencodeRoots
-      || require('./utils/path-setup').opencodeRoots;
-    throw new Error(`${HINTS.engineMissing} Searched: ${opencodeRoots().join(', ')}`);
+    const ensureEngine = options._ensureEngine
+      || require('./utils/engine-ensure').ensureEngine;
+    const healed = await ensureEngine().catch(() => ({ ok: false }));
+    if (!healed.ok) {
+      const HINTS = require('./utils/remediation-hints');
+      // Append the roots we probed so an npx-cache-vs-global divergence is visible
+      // at the point of failure, not just in `amicus doctor` (report #4).
+      const opencodeRoots = options._opencodeRoots
+        || require('./utils/path-setup').opencodeRoots;
+      const note = healed.reason ? ` (self-heal: ${healed.reason})` : '';
+      throw new Error(`${HINTS.engineMissing} Searched: ${opencodeRoots().join(', ')}${note}`);
+    }
   }
 
   const createOpencodeServer = await getCreateOpencodeServer();

package/src/utils/doctor-engine-check.js

@@ -68,4 +68,37 @@ function evaluateEngineInstalls(d) {
   return { id, name, status, message: `${lead}: ${detail}`, hint: HINTS.reinstallEngineAv };
 }
 
-module.exports = { evaluateEngineInstalls };
+/**
+ * Fix-aware wrapper. When d.fix and the scan shows broken npx-cache copies, copy
+ * the engine into each via d.repairEngine, then re-report from a fresh scan.
+ * Without d.fix — or when nothing is copy-fixable — returns the plain verdict.
+ * @param {object} d doctor deps (scanEngineInstalls, fix?, repairEngine?)
+ * @returns {Promise<{id,name,status,message,hint}>}
+ */
+async function evaluateEngineMcp(d) {
+  const verdict = evaluateEngineInstalls(d);
+  if (!d.fix || verdict.status === 'ok') { return verdict; }
+
+  const { installs } = d.scanEngineInstalls();
+  const broken = installs.filter((i) => i.kind === 'npx' && !i.engineOk);
+  if (broken.length === 0) { return verdict; }
+
+  const results = [];
+  for (const b of broken) {
+    let r;
+    try { r = await d.repairEngine({ destPkgDir: b.pkgDir }); }
+    catch (e) { r = { repaired: false, reason: e && e.message }; }
+    results.push({ pkgDir: b.pkgDir, ...r });
+  }
+
+  const after = evaluateEngineInstalls(d); // fresh scan reflects the copies
+  if (after.status === 'ok') {
+    const n = results.length;
+    return { ...after, message: `${after.message} (self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')})` };
+  }
+  const failed = results.filter((r) => !r.repaired)
+    .map((r) => `${r.pkgDir}${r.reason ? ` — ${r.reason}` : ''}`).join('; ');
+  return { ...after, message: `${after.message}; self-heal incomplete: ${failed}` };
+}
+
+module.exports = { evaluateEngineInstalls, evaluateEngineMcp };

package/src/utils/engine-ensure.js

@@ -0,0 +1,72 @@
+/**
+ * @module utils/engine-ensure
+ * ensureEngine() — runtime engine self-heal at server start (report #2).
+ *
+ * The single-flight wrapper opencode-client.startServer calls when the engine
+ * binary is missing: fast-path hasOpencodeBinary(); otherwise copy the engine
+ * from a healthy sibling install via engine-repair, refresh PATH, and re-check.
+ * A module-level promise stops concurrent fanout-leg server starts in one
+ * process from re-copying. Only success is memoized; a failed attempt clears the
+ * guard so a later call may retry. Mirrors src/sidecar/electron-ensure.js.
+ */
+
+'use strict';
+
+const { hasOpencodeBinary: defaultHas } = require('./path-setup');
+
+let _ensurePromise = null;
+
+/** Test-only: clear the single-flight guard so each test starts clean. */
+function _resetEnsureEngine() {
+  _ensurePromise = null;
+}
+
+/**
+ * Ensure the opencode engine is present, self-healing by copy if missing.
+ * @param {object} [opts]
+ * @param {object} [opts.deps] injected { hasOpencodeBinary, repairEngine, ensurePath, logProgress }
+ * @param {object} [opts.repairOptions] forwarded to repairEngine (destPkgDir, etc.)
+ * @returns {Promise<{ok:boolean, reason?:string, donor?:string}>}
+ */
+function ensureEngine({ deps = {}, repairOptions = {} } = {}) {
+  const has = deps.hasOpencodeBinary || defaultHas;
+  const repair = deps.repairEngine || ((o) => require('./engine-repair').repairEngine(o));
+  const ensurePath = deps.ensurePath || require('./path-setup').ensureNodeModulesBinInPath;
+  const logProgress = deps.logProgress
+    || ((msg) => { try { process.stderr.write(`${msg}\n`); } catch { /* ignore */ } });
+
+  // Fast path: already present. Cheap disk stat — safe every call.
+  if (has()) { return Promise.resolve({ ok: true }); }
+
+  // Single-flight: reuse an in-flight repair.
+  if (_ensurePromise) { return _ensurePromise; }
+
+  _ensurePromise = (async () => {
+    logProgress('[amicus] OpenCode engine missing — self-healing by copying from a healthy install...');
+    let result;
+    try {
+      result = await repair({ ...repairOptions });
+    } catch (err) {
+      return { ok: false, reason: `engine self-heal failed: ${err && err.message}` };
+    }
+    if (has()) {
+      logProgress('[amicus] OpenCode engine restored.');
+      return { ok: true, donor: result && result.donor };
+    }
+    return { ok: false, reason: (result && result.reason) || 'engine self-heal did not restore the binary' };
+  })().then((r) => {
+    if (r.ok) {
+      try { ensurePath(); } catch { /* ignore */ } // refresh PATH so spawn('opencode') resolves
+    } else {
+      _ensurePromise = null; // failure is not memoized — a later call may retry
+    }
+    return r;
+  }, (err) => {
+    _ensurePromise = null;
+    throw err;
+  });
+
+  return _ensurePromise;
+}
+
+module.exports = { ensureEngine, _resetEnsureEngine };

package/src/utils/engine-lock.js

@@ -0,0 +1,94 @@
+/**
+ * @module utils/engine-lock
+ * Stale-aware single-flight lock for the engine self-heal (report #2).
+ *
+ * Only one process may copy the opencode engine into a given install at a time:
+ * the report saw multiple live MCP processes, so two could self-heal the SAME
+ * npx-cache copy at once and a leg could spawn a half-written opencode.exe. The
+ * lock is a file in the OS temp dir keyed by the destination pkgDir, recording
+ * the holder PID + timestamp so a LATER caller can detect and STEAL a lock
+ * orphaned by a killed/crashed repair rather than wedging every future repair.
+ * Mirrors src/sidecar/electron-lock.js (kept separate so the shipped GUI heal is
+ * never touched).
+ */
+
+'use strict';
+
+const fsDefault = require('fs');
+const path = require('path');
+const os = require('os');
+
+/** A real engine copy (a few tens of MB) finishes well within this. */
+const STALE_MS = 15 * 60 * 1000;
+
+/** Temp-dir lockfile path, keyed by the destination install dir. */
+function lockPathFor(pkgDir) {
+  const key = require('crypto').createHash('sha1').update(pkgDir).digest('hex').slice(0, 16);
+  return path.join(os.tmpdir(), `amicus-engine-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. 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 -> orphaned
+  }
+  if (typeof meta.at === 'number' && now - meta.at > STALE_MS) {
+    return true;
+  }
+  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; EPERM => alive
+    }
+  }
+  return true;
+}
+
+/**
+ * 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.
+ * @param {{pkgDir:string, fs?:object}} opts
+ * @returns {{ release: () => void }}
+ */
+function acquireRepairLock({ pkgDir, fs = fsDefault }) {
+  const lockPath = lockPathFor(pkgDir);
+
+  function create() {
+    // Atomic exclusive create WITH content: never observable empty. '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; } // live holder -> 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/utils/engine-repair.js

@@ -0,0 +1,125 @@
+/**
+ * @module utils/engine-repair
+ * Engine self-heal primitive (report #2): make the opencode engine present ON
+ * DISK in a target amicus install by COPYING the opencode-* packages from a
+ * healthy sibling install (running/global/npx). No network, and the donor is on
+ * the same machine so its platform binaries match — unlike re-running the
+ * opencode postinstall, the flaky optional-dependency trap the startServer guard
+ * warns about.
+ *
+ * PURE copy — no PATH mutation — so it is targetable at ANY copy: the runtime
+ * path (engine-ensure) repairs the RUNNING copy; `amicus doctor --fix` repairs a
+ * foreign broken npx copy. Everything is injectable so tests never touch the real
+ * fs. Mirrors the Electron self-heal primitive (src/sidecar/electron-install.js).
+ */
+
+'use strict';
+
+const fsDefault = require('fs');
+const path = require('path');
+
+/** The running amicus package root (this file lives in <pkg>/src/utils). */
+function runningPkgDir() {
+  return path.join(__dirname, '..', '..');
+}
+
+/** First healthy install whose real path differs from the destination. */
+function findDonor({ installs, destPkgDir, fs }) {
+  const norm = (p) => { try { return path.normalize(fs.realpathSync(p)); } catch { return path.normalize(p); } };
+  const destReal = norm(destPkgDir);
+  return installs.find((i) => i.engineOk && norm(i.pkgDir) !== destReal) || null;
+}
+
+/** The donor root (nested or hoisted) that actually holds the engine binary. */
+function engineSourceRoot({ donorPkgDir, hasOpencodeBinary, opencodeRoots, fs }) {
+  for (const root of opencodeRoots({ pkgDir: donorPkgDir })) {
+    if (hasOpencodeBinary({ nodeModulesRoot: root, fs })) { return root; }
+  }
+  return null;
+}
+
+/** Copy every opencode-* package dir + the .bin/opencode* shims source→dest. */
+function copyEnginePackages({ sourceRoot, destRoot, fs }) {
+  const copied = [];
+  fs.mkdirSync(destRoot, { recursive: true });
+  for (const name of fs.readdirSync(sourceRoot)) {
+    if (!name.startsWith('opencode-')) { continue; }
+    fs.cpSync(path.join(sourceRoot, name), path.join(destRoot, name), { recursive: true, force: true });
+    copied.push(name);
+  }
+  // The engine resolver checks <root>/.bin/opencode on non-Windows, so carry the
+  // shims across too (relative symlinks resolve against the copied opencode-ai).
+  const srcBin = path.join(sourceRoot, '.bin');
+  let shims = [];
+  try { shims = fs.readdirSync(srcBin).filter((n) => n.startsWith('opencode')); } catch { shims = []; }
+  if (shims.length) {
+    const dstBin = path.join(destRoot, '.bin');
+    fs.mkdirSync(dstBin, { recursive: true });
+    for (const n of shims) {
+      fs.cpSync(path.join(srcBin, n), path.join(dstBin, n), { recursive: true, force: true });
+      copied.push(path.join('.bin', n));
+    }
+  }
+  return copied;
+}
+
+/**
+ * Copy the opencode engine into destPkgDir from a healthy sibling install.
+ * Never throws — every failure mode is a {repaired:false, ...} document.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.destPkgDir] install to repair (default: running copy)
+ * @param {object} [opts.deps] injected { fs, scanEngineInstalls, hasOpencodeBinary, opencodeRoots, acquireLock }
+ * @returns {Promise<{repaired:boolean, reason?:string, contended?:boolean, donor?:string, copied?:string[]}>}
+ */
+async function repairEngine({ destPkgDir = runningPkgDir(), deps = {} } = {}) {
+  const fs = deps.fs || fsDefault;
+  const scanEngineInstalls = deps.scanEngineInstalls
+    || (() => require('./engine-install-scan').scanEngineInstalls());
+  const hasOpencodeBinary = deps.hasOpencodeBinary || require('./path-setup').hasOpencodeBinary;
+  const opencodeRoots = deps.opencodeRoots || require('./path-setup').opencodeRoots;
+  const acquireLock = deps.acquireLock
+    || ((o) => require('./engine-lock').acquireRepairLock({ ...o, fs }));
+
+  // Already healthy — nothing to do (ensureEngine fast-paths, but doctor --fix
+  // may call us directly on a copy a prior leg already healed).
+  if (hasOpencodeBinary({ pkgDir: destPkgDir, fs })) {
+    return { repaired: true };
+  }
+
+  const { installs } = scanEngineInstalls();
+  const donor = findDonor({ installs, destPkgDir, fs });
+  if (!donor) {
+    return { repaired: false, reason: 'no healthy sibling install to copy the engine from' };
+  }
+
+  const sourceRoot = engineSourceRoot({ donorPkgDir: donor.pkgDir, hasOpencodeBinary, opencodeRoots, fs });
+  if (!sourceRoot) {
+    return { repaired: false, reason: `donor ${donor.pkgDir} has no resolvable engine root` };
+  }
+
+  let lock;
+  try {
+    lock = acquireLock({ pkgDir: destPkgDir });
+  } catch (e) {
+    if (e && e.code === 'EEXIST') {
+      return { repaired: false, contended: true, reason: 'another engine repair is in progress' };
+    }
+    return { repaired: false, reason: `could not acquire repair lock: ${e && e.message}` };
+  }
+
+  try {
+    const destRoot = path.join(destPkgDir, 'node_modules');
+    const copied = copyEnginePackages({ sourceRoot, destRoot, fs });
+    const repaired = !!hasOpencodeBinary({ pkgDir: destPkgDir, fs });
+    return repaired
+      ? { repaired: true, donor: donor.pkgDir, copied }
+      : { repaired: false, reason: 'engine still missing after copy', donor: donor.pkgDir, copied };
+  } catch (e) {
+    return { repaired: false, reason: `engine copy failed: ${e && e.message}` };
+  } finally {
+    try { lock.release(); } catch { /* ignore */ }
+  }
+}
+
+module.exports = { repairEngine, findDonor, engineSourceRoot, copyEnginePackages, runningPkgDir };