amicus 3.2.0 → 3.2.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "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,34 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [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.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

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

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,9 @@ 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(),
     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 +147,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(guard('engine-mcp', 'OpenCode engine (MCP launch path)', () => engineCheck.evaluateEngineInstalls(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

@@ -636,7 +636,11 @@ async function startServer(options = {}) {
     || require('./utils/path-setup').hasOpencodeBinary;
   if (!hasOpencodeBinary()) {
     const HINTS = require('./utils/remediation-hints');
-    throw new Error(HINTS.engineMissing);
+    // 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 createOpencodeServer = await getCreateOpencodeServer();

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

@@ -0,0 +1,71 @@
+/**
+ * @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 };
+}
+
+module.exports = { evaluateEngineInstalls };

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