amicus 3.2.0 → 3.2.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.2.0",
+  "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,51 @@ 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
+
+- **`opencode` engine now resolves under the npx-launched MCP.** The MCP server is
+  registered as `npx -y amicus@latest mcp`, which npm installs with the
+  `opencode-windows-*` engine packages **hoisted** beside `amicus/` rather than
+  nested under it. The resolver only probed the nested location, so a present,
+  runnable engine read as missing and every `amicus_fanout` / `amicus_start` leg
+  failed instantly with `engineMissing`. Both the PATH builder and the shared
+  binary resolver now probe the hoisted root too (#69).
+- **The AVX2 (default) `opencode` build is searched before the `-baseline`
+  fallback.** `ensureNodeModulesBinInPath()` prepended PATH one entry at a time, so
+  the search order was the reverse of the source order and AVX2-capable machines
+  silently ran the slower pre-AVX2 baseline build. PATH is now built as one ordered
+  group (default → baseline → `.bin`, across every candidate root).
+
+### Added
+
+- **`amicus doctor` cross-install engine check.** A new "OpenCode engine (MCP launch
+  path)" check enumerates every install that could serve the MCP — running, global,
+  and each npx-cache copy — and verifies the engine in each, so a green doctor can
+  no longer hide a broken copy the MCP actually launches. A broken single npx copy
+  (the unambiguous failure) is an error; ambiguous cases warn and name the exact
+  path.
+- The runtime `engineMissing` error now prints the roots it searched, making an
+  npx-cache-vs-global install divergence visible at the point of failure.
+
 ## [3.2.0] - 2026-07-16
 
 ### Added

package/README.md

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

package/package.json

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

@@ -4,6 +4,9 @@
 const HINTS = require('./utils/remediation-hints');
 // B14/4.3: 'mcp' + 'mcp-legacy' check bodies (mirrors the B15 tmpSweep split — see file header).
 const mcpChecks = require('./utils/doctor-mcp-checks');
+// engine-mcp check body — verifies the engine in the npx-cache copies the MCP
+// actually launches (bug report #1). Split out to keep this file under the gate.
+const engineCheck = require('./utils/doctor-engine-check');
 
 const MAX_CATALOG_AGE_MS = 24 * 60 * 60 * 1000; // 24h (mirrors model-catalog DEFAULT_MAX_AGE_MS)
 
@@ -36,6 +39,11 @@ function realDeps() {
       ensureNodeModulesBinInPath();
       return hasOpencodeBinary();
     },
+    // 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.
@@ -141,6 +149,11 @@ async function runDoctorChecks(depsOverride = {}) {
       : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: HINTS.reinstallEngineAv }
   )));
 
+  // 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(await guardAsync('engine-mcp', 'OpenCode engine (MCP launch path)', () => engineCheck.evaluateEngineMcp(d)));
+
   checks.push(await guardAsync('electron', 'Electron (interactive GUI)', async () => {
     if (d.getElectronPath()) {
       return { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed', hint: null };

package/src/opencode-client.js

@@ -625,18 +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');
-    throw new Error(HINTS.engineMissing);
+    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

@@ -0,0 +1,104 @@
+/**
+ * @module utils/doctor-engine-check
+ * The `engine-mcp` doctor check ("OpenCode engine (MCP launch path)"), split out
+ * of src/cli-handlers-doctor.js to keep that file under the 300-line gate
+ * (mirrors doctor-mcp-checks.js).
+ *
+ * The existing `opencode-bin` check verifies the engine in the RUNNING install.
+ * This one verifies the copies the MCP actually launches from — the npx-cache
+ * installs `npx -y amicus@latest mcp` resolves to — so a green doctor can no
+ * longer hide a broken npx copy (bug report #1). Reporting only; no self-heal.
+ */
+
+'use strict';
+
+const HINTS = require('./remediation-hints');
+
+const plural = (n, one, many) => (n === 1 ? one : many);
+
+/**
+ * @param {{scanEngineInstalls: () => {installs:Array, mcpLaunch:string}}} d
+ * @returns {{id,name,status,message,hint}}
+ */
+function evaluateEngineInstalls(d) {
+  const id = 'engine-mcp';
+  const name = 'OpenCode engine (MCP launch path)';
+  const { installs, mcpLaunch } = d.scanEngineInstalls();
+
+  if (mcpLaunch === 'none') {
+    return { id, name, status: 'ok', message: 'no amicus MCP registered — not checked', hint: null };
+  }
+  if (mcpLaunch === 'path') {
+    return {
+      id, name, status: 'ok',
+      message: 'MCP launches from a fixed path — covered by the OpenCode binary check', hint: null,
+    };
+  }
+
+  // 'npx' (and the 'unknown' fallback): verify the npx-cache copies, the ones
+  // subject to optional-dependency skips and AV quarantine on every re-resolve.
+  const npxCopies = installs.filter((i) => i.kind === 'npx');
+  if (npxCopies.length === 0) {
+    return {
+      id, name, status: 'warn',
+      message: 'MCP launches via npx; no cached copy to inspect yet — run one fanout, then re-run doctor',
+      hint: null,
+    };
+  }
+
+  const broken = npxCopies.filter((i) => !i.engineOk);
+  if (broken.length === 0) {
+    return {
+      id, name, status: 'ok',
+      message: `engine present in ${npxCopies.length} npx-cache ${plural(npxCopies.length, 'copy', 'copies')}`,
+      hint: null,
+    };
+  }
+
+  const detail = broken
+    .map((i) => `${i.pkgDir} (searched: ${(i.roots || []).join(', ')})`)
+    .join('; ');
+  // Exactly one npx copy and it is broken → unambiguous: that IS the copy the
+  // MCP will launch, and every call will fail. Elsewhere the hash npx selects is
+  // ambiguous, so warn (still naming the exact broken path) rather than error.
+  const status = npxCopies.length === 1 ? 'error' : 'warn';
+  const lead = status === 'error'
+    ? 'engine missing from the npx-cache copy the MCP launches'
+    : `engine missing from ${broken.length}/${npxCopies.length} npx-cache copies`;
+  return { id, name, status, message: `${lead}: ${detail}`, hint: HINTS.reinstallEngineAv };
+}
+
+/**
+ * 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-install-scan.js

@@ -0,0 +1,142 @@
+/**
+ * @module utils/engine-install-scan
+ * Discover + probe every amicus install that could serve the MCP (running,
+ * global, npx-cache), so `amicus doctor` verifies the copy the MCP actually
+ * launches — not just the copy doctor happens to run from.
+ *
+ * The MCP is registered as `npx -y amicus@latest mcp` (scripts/postinstall.js),
+ * so it runs from an npx-cache copy, while `amicus doctor` typically inspects the
+ * global install on PATH. When those diverge, doctor can report the engine
+ * "found" (global) while the npx copy the MCP launches is broken and every call
+ * fails — the bug report's green-while-broken defect (#1). This enumerates
+ * running + global + each npx-cache copy and probes the opencode engine in each
+ * via the #69 dual-root resolver.
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+/** Default npm cache dir: %LocalAppData%/npm-cache on win32, else ~/.npm. */
+function defaultNpmCacheDir(platform) {
+  if (platform === 'win32') {
+    const local = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(local, 'npm-cache');
+  }
+  return path.join(os.homedir(), '.npm');
+}
+
+/** Best-effort `npm root -g`. Never throws; returns null on any failure. */
+function defaultNpmRootG() {
+  try {
+    const { execFileSync } = require('child_process');
+    const out = execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf-8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return String(out).trim() || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/** Run fn, swallowing any throw and returning fallback. */
+function safe(fn, fallback) {
+  try { return fn(); } catch (_e) { return fallback; }
+}
+
+/** Drop installs whose pkgDir resolves to the same real path; keep the first. */
+function dedupByRealpath(installs, fs) {
+  const seen = new Set();
+  const out = [];
+  for (const inst of installs) {
+    const real = safe(() => fs.realpathSync(inst.pkgDir), inst.pkgDir);
+    const key = path.normalize(real);
+    if (seen.has(key)) { continue; }
+    seen.add(key);
+    out.push(inst);
+  }
+  return out;
+}
+
+/**
+ * The amicus installs that could serve the MCP, highest-priority first
+ * (running, global, then npx-cache copies). All I/O behind seams.
+ *
+ * @param {object} [deps]
+ * @param {object} [deps.fs] - fs module (existsSync/readdirSync/realpathSync)
+ * @param {string} [deps.platform] - process.platform override
+ * @param {string} [deps.runningPkgDir] - this process's amicus package root
+ * @param {string} [deps.npmCacheDir] - npm cache dir holding _npx/
+ * @param {() => (string|null)} [deps.npmRootG] - resolver for `npm root -g`
+ * @returns {Array<{kind:string, pkgDir:string}>}
+ */
+function listAmicusInstalls(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const platform = deps.platform || process.platform;
+  const runningPkgDir = deps.runningPkgDir || path.join(__dirname, '..', '..');
+  const npmCacheDir = deps.npmCacheDir || defaultNpmCacheDir(platform);
+  const npmRootG = deps.npmRootG || defaultNpmRootG;
+
+  const raw = [{ kind: 'running', pkgDir: runningPkgDir }];
+
+  // Global — best-effort; `npm root -g` → <root>/amicus. Never fails the scan.
+  const gRoot = safe(() => npmRootG(), null);
+  if (gRoot) {
+    const gDir = path.join(gRoot, 'amicus');
+    if (safe(() => fs.existsSync(gDir), false)) {
+      raw.push({ kind: 'global', pkgDir: gDir });
+    }
+  }
+
+  // npx caches — <cache>/_npx/<hash>/node_modules/amicus for each hash present.
+  const npxRoot = path.join(npmCacheDir, '_npx');
+  for (const hash of safe(() => fs.readdirSync(npxRoot), [])) {
+    const pkgDir = path.join(npxRoot, hash, 'node_modules', 'amicus');
+    if (safe(() => fs.existsSync(pkgDir), false)) {
+      raw.push({ kind: 'npx', pkgDir });
+    }
+  }
+
+  return dedupByRealpath(raw, fs);
+}
+
+/**
+ * Classify the MCP launch method from the amicus registration config.
+ * @param {{command?:string, args?:unknown[]}|null|undefined} config
+ * @returns {'npx'|'path'|'none'|'unknown'}
+ */
+function classifyLaunch(config) {
+  const { isAmicusMcpConfig, normalizeToken } = require('./mcp-self-identity');
+  if (!config || typeof config !== 'object') { return 'none'; }
+  if (config.command && normalizeToken(config.command) === 'npx') { return 'npx'; }
+  if (isAmicusMcpConfig(config)) { return 'path'; }
+  return 'unknown';
+}
+
+/**
+ * Enumerate serving installs, probe the engine in each, and classify how the
+ * MCP launches.
+ *
+ * @param {object} [deps] - listAmicusInstalls seams, plus:
+ * @param {(d:{pkgDir:string}) => boolean} [deps.hasOpencodeBinary]
+ * @param {(d:{pkgDir:string}) => string[]} [deps.opencodeRoots]
+ * @param {() => (object|null)} [deps.readAmicusMcpConfig]
+ * @returns {{installs: Array<{kind,pkgDir,engineOk,roots}>, mcpLaunch: string}}
+ */
+function scanEngineInstalls(deps = {}) {
+  const hasOpencodeBinary = deps.hasOpencodeBinary || require('./path-setup').hasOpencodeBinary;
+  const opencodeRoots = deps.opencodeRoots || require('./path-setup').opencodeRoots;
+  const readAmicusMcpConfig = deps.readAmicusMcpConfig
+    || (() => require('./mcp-discovery').readAmicusMcpConfig());
+
+  const installs = listAmicusInstalls(deps).map((i) => ({
+    ...i,
+    engineOk: !!hasOpencodeBinary({ pkgDir: i.pkgDir }),
+    roots: opencodeRoots({ pkgDir: i.pkgDir }),
+  }));
+  const mcpLaunch = classifyLaunch(safe(() => readAmicusMcpConfig(), null));
+  return { installs, mcpLaunch };
+}
+
+module.exports = { listAmicusInstalls, scanEngineInstalls, classifyLaunch };

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 };

package/src/utils/mcp-discovery.js

@@ -226,6 +226,32 @@ function discoverCoworkMcps(configDir) {
   }
 }
 
+/**
+ * The RAW amicus MCP registration config (never stripped) from either client —
+ * the first entry keyed 'amicus' or whose command/args resolve to an amicus MCP
+ * launch (isAmicusMcpConfig). Used by the doctor engine-scan to classify HOW the
+ * MCP launches (npx vs a fixed path). Distinct from hasAmicusRegistration (which
+ * returns only a boolean and reads Claude Code alone).
+ *
+ * @param {string} [claudeDir] - ~/.claude directory (for testing)
+ * @param {string} [claudeJsonPath] - ~/.claude.json path (for testing)
+ * @param {string} [coworkConfigDir] - Claude Desktop config dir (for testing)
+ * @returns {object|null} The amicus server config, or null if none is registered
+ */
+function readAmicusMcpConfig(claudeDir, claudeJsonPath, coworkConfigDir) {
+  const sources = [
+    readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath),
+    discoverCoworkMcps(coworkConfigDir),
+  ];
+  for (const servers of sources) {
+    if (!servers || typeof servers !== 'object') { continue; }
+    for (const [name, config] of Object.entries(servers)) {
+      if (name === 'amicus' || isAmicusMcpConfig(config)) { return config; }
+    }
+  }
+  return null;
+}
+
 /**
  * Discover MCP servers from the parent LLM's configuration.
  *
@@ -248,5 +274,6 @@ module.exports = {
   discoverClaudeCodeMcps,
   discoverCoworkMcps,
   hasAmicusRegistration,
+  readAmicusMcpConfig,
   normalizeMcpJson
 };

package/src/utils/path-setup.js

@@ -1,39 +1,84 @@
 const path = require('path');
 const os = require('os');
 
+/**
+ * The node_modules roots that may hold the opencode engine sub-packages.
+ *
+ * npm only NESTS a dependency under <pkg>/node_modules when it cannot hoist it.
+ * `npm i -g amicus` nests opencode-windows-*; `npx -y amicus@latest` — which is
+ * exactly how postinstall registers the MCP server — HOISTS it to a sibling of
+ * amicus/, leaving <pkg>/node_modules nonexistent. Both are valid installs, so
+ * probe both roots rather than assuming a layout. Assuming the nested one made a
+ * present, runnable engine read as missing and threw engineMissing on every
+ * fanout leg under npx (#69).
+ *
+ * Order is search priority: nested (amicus's own copy) before hoisted.
+ *
+ * @param {object} [deps] - test seams
+ * @param {string} [deps.nodeModulesRoot] - exact root override (wins outright)
+ * @param {string} [deps.pkgDir] - amicus package dir override
+ * @returns {string[]} candidate node_modules roots
+ */
+function opencodeRoots(deps = {}) {
+  if (deps.nodeModulesRoot) {
+    return [deps.nodeModulesRoot];
+  }
+  const pkgDir = deps.pkgDir || path.join(__dirname, '..', '..');
+  return [
+    path.join(pkgDir, 'node_modules'), // nested  — npm i -g
+    path.dirname(pkgDir), // hoisted — npx/pnpm: the node_modules holding amicus
+  ];
+}
+
 /**
  * Ensures that the project's node_modules/.bin directory is included in the PATH,
  * and on Windows also adds the platform-specific native opencode binary directory
  * so that `spawn('opencode', ...)` without shell:true can resolve the .exe.
  * The OpenCode SDK spawns the 'opencode' command, and this ensures it can be found.
+ * Walks every candidate root so hoisted installs resolve too (#69).
+ *
+ * PATH is a first-match search, so the array below IS the priority order — built
+ * highest-priority-first, then prepended as ONE group. Two orderings matter and
+ * both were once inverted by prepending one dir at a time (LIFO reverses intent):
+ *   - default (AVX2) before -baseline: an AVX2 machine must run the fast build,
+ *     with baseline only as the older-CPU fallback.
+ *   - every native .exe dir before any .bin: on Windows .bin holds a .cmd shim
+ *     that bare spawn() cannot execute, so a real .exe must always win — even a
+ *     .exe in the other candidate root beats a shim in this one.
+ * Hence the three tiers: all defaults, then all baselines, then all .bin — each
+ * tier spanning every root in opencodeRoots() priority order.
+ *
+ * @param {object} [deps] - test seams, forwarded to opencodeRoots()
+ * @param {string} [deps.nodeModulesRoot] - exact root override (wins outright)
+ * @param {string} [deps.pkgDir] - amicus package dir override
  */
-function ensureNodeModulesBinInPath() {
-  const nodeModulesRoot = path.join(__dirname, '..', '..', 'node_modules');
-  const nodeModulesBin = path.join(nodeModulesRoot, '.bin');
+function ensureNodeModulesBinInPath(deps = {}) {
+  const roots = opencodeRoots(deps);
+  const dirs = [];
 
-  if (!process.env.PATH.includes(nodeModulesBin)) {
-    process.env.PATH = `${nodeModulesBin}${path.delimiter}${process.env.PATH}`;
-  }
-
-  // On Windows, Node's spawn() does not execute .cmd shims without shell:true.
-  // Add the platform-specific native binary directory so `opencode` resolves
-  // to opencode.exe directly (Windows searches PATHEXT-aware when .exe is present).
   if (os.platform() === 'win32') {
     const archMap = { x64: 'x64', arm64: 'arm64' };
     const arch = archMap[os.arch()] || os.arch();
-    const nativeBin = path.join(nodeModulesRoot, `opencode-windows-${arch}`, 'bin');
-    if (!process.env.PATH.includes(nativeBin)) {
-      process.env.PATH = `${nativeBin}${path.delimiter}${process.env.PATH}`;
+    // Tier 1: default (AVX2) build in every root.
+    for (const root of roots) {
+      dirs.push(path.join(root, `opencode-windows-${arch}`, 'bin'));
     }
-    // Baseline variant: the default build needs AVX2; opencode ships a
-    // -baseline (pre-AVX2) build for older CPUs. Windows resolves the first
-    // PATH entry containing a real opencode.exe, so default-before-baseline
-    // order matters — do not delete this block as "dead code".
-    const nativeBinBaseline = path.join(nodeModulesRoot, `opencode-windows-${arch}-baseline`, 'bin');
-    if (!process.env.PATH.includes(nativeBinBaseline)) {
-      process.env.PATH = `${nativeBinBaseline}${path.delimiter}${process.env.PATH}`;
+    // Tier 2: -baseline (pre-AVX2) fallback in every root — searched only after
+    // every default build. Do not delete these entries as "dead code".
+    for (const root of roots) {
+      dirs.push(path.join(root, `opencode-windows-${arch}-baseline`, 'bin'));
     }
   }
+  // Tier 3: node_modules/.bin in every root, last (its shims spawn() cannot run).
+  for (const root of roots) {
+    dirs.push(path.join(root, '.bin'));
+  }
+
+  // Prepend the not-yet-present dirs as one group, preserving the order above.
+  const missing = dirs.filter((dir) => !process.env.PATH.includes(dir));
+  if (missing.length > 0) {
+    process.env.PATH = `${missing.join(path.delimiter)}${path.delimiter}${process.env.PATH}`;
+  }
 }
 
 /**
@@ -48,6 +93,8 @@ function ensureNodeModulesBinInPath() {
  *
  * Mirrors the PATH resolution order: on Windows the platform sub-package (and
  * its -baseline variant) bin/opencode.exe; elsewhere node_modules/.bin/opencode.
+ * Probes every candidate root (nested AND hoisted — see opencodeRoots), so a
+ * layout npm chose for us can never masquerade as a missing engine (#69).
  * Never throws — a probe failure reads as not-found.
  *
  * @param {object} [deps] - test seams
@@ -55,19 +102,24 @@ function ensureNodeModulesBinInPath() {
  * @param {string} [deps.platform] - process.platform override
  * @param {string} [deps.arch] - os.arch() override
  * @param {string} [deps.nodeModulesRoot] - node_modules root override
+ * @param {string} [deps.pkgDir] - amicus package dir override
  * @returns {boolean} true only when a real opencode binary resolves on disk
  */
 function hasOpencodeBinary(deps = {}) {
   const fs = deps.fs || require('fs');
   const platform = deps.platform || process.platform;
   const arch = deps.arch || os.arch();
-  const root = deps.nodeModulesRoot || path.join(__dirname, '..', '..', 'node_modules');
 
   const a = arch === 'arm64' ? 'arm64' : 'x64';
-  const candidates = platform === 'win32'
-    ? [path.join(root, `opencode-windows-${a}`, 'bin', 'opencode.exe'),
-       path.join(root, `opencode-windows-${a}-baseline`, 'bin', 'opencode.exe')]
-    : [path.join(root, '.bin', 'opencode')];
+  const candidates = [];
+  for (const root of opencodeRoots(deps)) {
+    if (platform === 'win32') {
+      candidates.push(path.join(root, `opencode-windows-${a}`, 'bin', 'opencode.exe'));
+      candidates.push(path.join(root, `opencode-windows-${a}-baseline`, 'bin', 'opencode.exe'));
+    } else {
+      candidates.push(path.join(root, '.bin', 'opencode'));
+    }
+  }
 
   return candidates.some((p) => { try { return fs.existsSync(p); } catch (_e) { return false; } });
 }
@@ -75,4 +127,5 @@ function hasOpencodeBinary(deps = {}) {
 module.exports = {
   ensureNodeModulesBinInPath,
   hasOpencodeBinary,
+  opencodeRoots,
 };