amicus 1.7.1 → 1.7.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "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,43 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [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.
+
+### Fixed
+- **The Electron self-heal no longer claims success when it didn't heal.** `repairElectron`'s
+  installer-fallback path always reported the GUI as "provisioned"/"fixed" even when the binary wasn't
+  actually on disk — so `amicus doctor --fix` and the install-time prewarm could falsely report
+  success. Every self-heal / provision path now declares success **only** when the Electron binary is
+  verified present on disk.
+
+### Changed
+- **The GUI repair is now controlled and introspectable.** Instead of blindly re-running Electron's own
+  installer (the postinstall npm had already silently suppressed), the repair downloads and extracts the
+  binary itself (via `@electron/get`) and verifies the result; a corrupt cached download is cleared and
+  re-fetched once.
+- **Antivirus quarantine is detected and explained, not retried forever.** When Windows Defender / AV
+  removes `electron.exe` right after extraction (the common Windows failure), amicus now tells you to
+  allow-list the binary and re-run `amicus doctor --fix`, instead of silently looping a repair that
+  cannot win.
+- **Clear, actionable error when the OpenCode engine binary is missing.** The engine ships via
+  per-platform binaries that npm can silently skip (or AV can quarantine); when it's absent, amicus now
+  surfaces a specific instruction (run `amicus doctor`, reinstall, allow-list `opencode.exe`) instead of
+  an opaque spawn failure.
+
 ## [1.7.1] - 2026-06-30
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "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/scripts/postinstall.js

@@ -216,16 +216,29 @@ async function provisionElectron(deps = {}) {
     if (process.env.AMICUS_PREFETCH_ELECTRON === '1') {
       console.log('[amicus] AMICUS_PREFETCH_ELECTRON=1 — prewarming the Electron GUI binary (may download)...');
       const forced = await _repair({ force: true });
-      if (forced && (forced.repaired || forced.usable)) {
+      if (forced && forced.repaired) {
         console.log('[amicus] Electron GUI binary prewarmed.');
         return;
       }
+      if (forced && forced.quarantined) {
+        console.warn(`[amicus] Note: the Electron GUI binary could not be installed — ${forced.reason || 'antivirus quarantine.'}`);
+        console.warn('[amicus] Headless runs and the council already work without the GUI.');
+        return;
+      }
       console.warn('[amicus] Note: Electron prewarm did not complete now — the GUI provisions on first use.');
       return;
     }
 
     const result = await _repair({ cacheOnly: true, timeoutMs: PROVISION_TIMEOUT_MS });
-    if (result && (result.repaired || result.usable)) { return; }
+    if (result && result.repaired) { return; }
+    // AV quarantine (electron.exe deleted right after extract) needs ACTION, not
+    // a generic "provisions on first use" notice — re-extracting can never win,
+    // so print the allow-list instruction verbatim instead. (No retry loop.)
+    if (result && result.quarantined) {
+      console.warn(`[amicus] Note: the Electron GUI binary could not be installed — ${result.reason || 'antivirus quarantine.'}`);
+      console.warn('[amicus] Headless runs and the council already work without the GUI.');
+      return;
+    }
     // No cache hit (deferred), contended, or otherwise not provisioned now.
     console.warn('[amicus] Note: the Electron GUI binary is not provisioned yet — it will download on first use of the interactive GUI / setup-wizard.');
     console.warn(`[amicus] Headless runs and the council already work. To provision the GUI now: ${HINTS.doctorFix}`);

package/src/cli-handlers-doctor.js

@@ -29,14 +29,10 @@ function realDeps() {
     collectAliasSources: () => require('./utils/alias-audit').collectAliasSources(),
     findStaleAliases: (s, c) => require('./utils/alias-audit').findStaleAliases(s, c),
     hasOpencodeBinary: () => {
-      const { ensureNodeModulesBinInPath } = require('./utils/path-setup');
+      // Single source of truth shared with the runtime server-start guard.
+      const { ensureNodeModulesBinInPath, hasOpencodeBinary } = require('./utils/path-setup');
       ensureNodeModulesBinInPath();
-      const root = path.join(__dirname, '..', 'node_modules');
-      const candidates = process.platform === 'win32'
-        ? [path.join(root, `opencode-windows-${os.arch() === 'arm64' ? 'arm64' : 'x64'}`, 'bin', 'opencode.exe'),
-           path.join(root, `opencode-windows-${os.arch() === 'arm64' ? 'arm64' : 'x64'}-baseline`, 'bin', 'opencode.exe')]
-        : [path.join(root, '.bin', 'opencode')];
-      return candidates.some(p => fs.existsSync(p));
+      return hasOpencodeBinary();
     },
     getElectronPath: () => require('./sidecar/interactive').getElectronPath(),
     // #56: self-heal primitive for `doctor --fix`. Pure probe (getElectronPath)
@@ -128,7 +124,7 @@ async function runDoctorChecks(depsOverride = {}) {
   checks.push(guard('opencode-bin', 'OpenCode binary', () => (
     d.hasOpencodeBinary()
       ? { id: 'opencode-bin', name: 'OpenCode binary', status: 'ok', message: 'found', hint: null }
-      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: HINTS.reinstallEngine }
+      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: HINTS.reinstallEngineAv }
   )));
 
   checks.push(await guardAsync('electron', 'Electron (interactive GUI)', async () => {
@@ -147,15 +143,20 @@ async function runDoctorChecks(depsOverride = {}) {
         return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: `repair failed: ${e.message} — headless still works`, hint: HINTS.doctorFix };
       }
       res = res || {};
-      if (res.repaired || res.usable) {
+      if (res.repaired) {
         return { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed (self-healed)', hint: null };
       }
       const why = res.reason ? ` — ${res.reason}` : '';
-      const detail = res.deferred
-        ? `deferred${why}`
-        : res.contended
-          ? `repair already in progress${why}`
-          : `not provisioned${why}`;
+      // Quarantine (AV deleted electron.exe post-extract) is NOT a deferral and
+      // must NEVER be silently retried: surface the allow-list instruction as a
+      // WARN and STOP. No re-run of repairElectron here (no loop).
+      const detail = res.quarantined
+        ? `antivirus quarantine${why}`
+        : res.deferred
+          ? `deferred${why}`
+          : res.contended
+            ? `repair already in progress${why}`
+            : `not provisioned${why}`;
       return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: `${detail} — headless still works`, hint: HINTS.doctorFix };
     }
     return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: 'not installed — headless still works', hint: HINTS.doctorFix };

package/src/opencode-client.js

@@ -565,6 +565,20 @@ 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.
+  const hasOpencodeBinary = options._hasOpencodeBinary
+    || require('./utils/path-setup').hasOpencodeBinary;
+  if (!hasOpencodeBinary()) {
+    const HINTS = require('./utils/remediation-hints');
+    throw new Error(HINTS.engineMissing);
+  }
+
   const createOpencodeServer = await getCreateOpencodeServer();
   const serverOptions = buildServerOptions(options);
 

package/src/sidecar/electron-install.js

@@ -15,19 +15,18 @@
  *   node_modules/electron/dist/<exe>  -> the actual binary
  * #59: when ELECTRON_OVERRIDE_DIST_PATH is set, the exe lives in that dir
  * instead of <pkg>/dist (mirrors electron/index.js + install.js semantics).
- *
- * Cache layout (@electron/get):
- *   <cacheRoot>/<sha256>/electron-v<ver>-<platform>-<arch>.zip
+ * Cache layout (@electron/get): <cacheRoot>/<sha256>/electron-v<ver>-<platform>-<arch>.zip
  */
 
 'use strict';
 
 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');
 
 /** Default on-disk location of the installed electron package. */
 function defaultElectronDir() {
@@ -116,31 +115,6 @@ function cachedZip({ version, platform = process.platform, arch = process.arch,
   return null;
 }
 
-/** Quarantine / AV note appended to win32 deferral reasons. */
-function avHint(platform) {
-  if (platform === 'win32') {
-    return ' Windows Defender / antivirus may have quarantined electron.exe; '
-      + 'allow it and re-run, or reinstall.';
-  }
-  return '';
-}
-
-/**
- * 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));
@@ -154,6 +128,45 @@ async function extractFromCache({ zip, electronDir, platform, extract, fs }) {
   writePathTxt({ electronDir, platform, fs });
 }
 
+/** Best-effort cache root for downloadArtifact (first resolved root). */
+function cacheRootFor(env = process.env) {
+  return resolveCacheRoots(env)[0];
+}
+
+/**
+ * CONTROLLED provision: fetch the zip ourselves with the SAME @electron/get
+ * api install.js uses (downloadArtifact, force:true), extract offline, and let
+ * the caller verify isElectronUsable(). No blind install.js spawn.
+ * @returns {Promise<void>}
+ */
+async function controlledProvision({
+  electronDir, platform, arch, version, downloadArtifact, extract, fs, env = process.env,
+}) {
+  const zip = await downloadArtifact({
+    version,
+    artifactName: 'electron',
+    force: true,
+    cacheRoot: cacheRootFor(env),
+    platform,
+    arch,
+    checksums: undefined,
+    // Bound the fetch so a stalled/blocked network aborts (got v11 timeouts:
+    // socket = inactivity, request = total) instead of hanging the repair —
+    // a hung-then-killed download is what orphaned the single-flight lock.
+    downloadOptions: { timeout: { socket: 60000, request: 480000 } },
+  });
+  await extractFromCache({ zip, electronDir, platform, extract, fs });
+}
+
+/** Bind the fs-aware probes for the post-extract AV-quarantine verify. */
+function verifyExtractOutcome({ electronDir, platform, fs }) {
+  return verifyQuarantine({
+    isElectronUsable: () => isElectronUsable({ electronDir, platform, fs }),
+    resolveExe: () => resolveElectronBinary({ electronDir, platform, fs }),
+    platform,
+  });
+}
+
 /** Drive electron's own install.js with force_no_cache semantics. */
 function runInstaller({ electronDir, force, spawn }) {
   const installScript = path.join(electronDir, 'install.js');
@@ -187,9 +200,13 @@ async function repairElectron({
 } = {}) {
   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-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) {
     try {
@@ -214,20 +231,50 @@ async function repairElectron({
     // Attempt 1: extract from cache (always preferred, fully offline).
     const zip = findZip({ version, platform, arch, env: process.env, fs });
     if (zip) {
-      await extractFromCache({ zip, electronDir, platform, extract, fs });
-      return { repaired: isElectronUsable({ electronDir, platform, fs }) };
-    }
-
-    if (cacheOnly) {
+      try {
+        await extractFromCache({ zip, electronDir, platform, extract, fs });
+        // Non-throwing extract w/ absent exe = the AV-quarantine signature.
+        return verifyExtractOutcome({ electronDir, platform, fs });
+      } catch (extractErr) {
+        // Corrupt cached artifact: delete the bad zip so it can't poison the
+        // cache, then fall through to a forced fresh download (unless offline).
+        try { fs.rmSync(zip, { force: true }); } catch { /* ignore */ }
+        if (cacheOnly) {
+          return {
+            repaired: false,
+            reason: `Cached electron zip for v${version} (${platform}-${arch}) was corrupt and removed; deferring re-download.${avHint(platform)}`,
+          };
+        }
+        // else: drop into the controlled download below.
+      }
+    } else if (cacheOnly) {
       return {
         deferred: true,
         reason: `No cached electron zip found for v${version} (${platform}-${arch}); deferring download.${avHint(platform)}`,
       };
     }
 
-    // Attempt 2: drive electron's installer (force_no_cache when forced).
-    runInstaller({ electronDir, force, spawn });
-    return { repaired: isElectronUsable({ electronDir, platform, fs }) || true };
+    // Attempt 2 (online): CONTROLLED download+extract instead of a blind
+    // install.js spawn — fetch via the SAME @electron/get api install.js uses,
+    // extract offline, then report the REAL usability. A structurally-successful
+    // download that produced no usable exe is a FAILURE (no false success; #53).
+    let controlledExtracted = false;
+    try {
+      await controlledProvision({
+        electronDir, platform, arch, version, downloadArtifact, extract, fs, env: process.env,
+      });
+      controlledExtracted = true; // download + extract returned without throwing
+    } catch {
+      // Controlled download/extract failed (network, checksum, unzip). Try the
+      // installer as a LAST resort — it can NEVER short-circuit the honest
+      // verify below; we always return isElectronUsable().
+      try { runInstaller({ electronDir, force, spawn }); } catch { /* ignore */ }
+    }
+    // A NON-throwing controlled extract that left no usable exe is the
+    // AV-quarantine signature — surface it actionably (no false success, no
+    // loop). A controlled FAILURE only reports plain repaired:false.
+    if (controlledExtracted) { return verifyExtractOutcome({ electronDir, platform, fs }); }
+    return { repaired: isElectronUsable({ electronDir, platform, fs }) };
   } finally {
     try { lock.release(); } catch { /* ignore */ }
   }

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/electron-quarantine.js

@@ -0,0 +1,70 @@
+/**
+ * AV / antivirus quarantine detection for the electron self-heal (#53).
+ *
+ * The DOMINANT real-world Windows failure: Windows Defender / antivirus deletes
+ * electron.exe right AFTER each extract. No re-extract can ever win that race —
+ * the user MUST allow-list the binary. This module owns the quarantine MESSAGE
+ * + the post-extract VERIFY so electron-install.js stays under the size gate and
+ * the wording lives in one place.
+ *
+ * Split out of src/sidecar/electron-install.js (kept <300 lines).
+ */
+
+'use strict';
+
+/** Quarantine / AV note appended to win32 deferral reasons. */
+function avHint(platform) {
+  if (platform === 'win32') {
+    return ' Windows Defender / antivirus may have quarantined electron.exe; '
+      + 'allow it and re-run, or reinstall.';
+  }
+  return '';
+}
+
+/**
+ * Actionable quarantine instruction. AV / Windows Defender deletes electron.exe
+ * right AFTER each extract, so no re-extract can win — the user MUST allow-list
+ * the binary. We name the exact path to allow and point at the in-place
+ * self-heal re-run (NOT a reinstall, which would loop). win32-specific; other
+ * platforms get the generic avHint fallback.
+ */
+function quarantineReason({ platform, exePath }) {
+  if (platform === 'win32') {
+    const target = exePath || 'node_modules/electron/dist/electron.exe';
+    return 'electron.exe was removed right after it was extracted — antivirus '
+      + '(e.g. Windows Defender) likely quarantined it. Allow '
+      + `${target} in your AV, then run amicus doctor --fix.`;
+  }
+  return 'The electron binary vanished right after extraction — your antivirus '
+    + `may have quarantined it. Allow it, then run amicus doctor --fix.${avHint(platform)}`;
+}
+
+/**
+ * Verify the outcome of a NON-throwing extract (cache OR controlled download).
+ *
+ * THE QUARANTINE SIGNATURE: the extract did not throw, yet isElectronUsable()
+ * is STILL false — the exe was written then vanished. On win32 that is almost
+ * always AV / Windows Defender quarantining electron.exe, and NO re-extract can
+ * win. We report { repaired:false, quarantined:true, reason } with an ACTIONABLE
+ * allow-list instruction — NEVER a false success, and the caller MUST NOT
+ * auto-retry (a quarantine loop is the bug we're killing).
+ *
+ * When the exe IS present, this is a clean { repaired:true }.
+ *
+ * @param {object} opts
+ * @param {() => boolean} opts.isElectronUsable bound usability probe.
+ * @param {() => string}  opts.resolveExe resolves the on-disk exe path.
+ * @param {string} opts.platform
+ */
+function verifyExtractOutcome({ isElectronUsable, resolveExe, platform }) {
+  if (isElectronUsable()) {
+    return { repaired: true };
+  }
+  return {
+    repaired: false,
+    quarantined: true,
+    reason: quarantineReason({ platform, exePath: resolveExe() }),
+  };
+}
+
+module.exports = { avHint, quarantineReason, verifyExtractOutcome };

package/src/utils/path-setup.js

@@ -36,6 +36,43 @@ function ensureNodeModulesBinInPath() {
   }
 }
 
+/**
+ * Resolve whether the opencode engine binary actually exists on disk.
+ *
+ * opencode-ai ships the engine via per-platform binary sub-packages declared as
+ * optionalDependencies, so a skipped install or an antivirus quarantine can
+ * leave the .exe silently absent — and then `spawn('opencode')` fails with an
+ * opaque ENOENT. This is the SINGLE source of truth shared by `amicus doctor`
+ * (the opencode-bin check) and the runtime server-start guard, so both agree on
+ * what "the binary is present" means.
+ *
+ * Mirrors the PATH resolution order: on Windows the platform sub-package (and
+ * its -baseline variant) bin/opencode.exe; elsewhere node_modules/.bin/opencode.
+ * Never throws — a probe failure reads as not-found.
+ *
+ * @param {object} [deps] - test seams
+ * @param {object} [deps.fs] - fs module (existsSync)
+ * @param {string} [deps.platform] - process.platform override
+ * @param {string} [deps.arch] - os.arch() override
+ * @param {string} [deps.nodeModulesRoot] - node_modules root 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')];
+
+  return candidates.some((p) => { try { return fs.existsSync(p); } catch (_e) { return false; } });
+}
+
 module.exports = {
   ensureNodeModulesBinInPath,
+  hasOpencodeBinary,
 };

package/src/utils/remediation-hints.js

@@ -26,6 +26,24 @@ const REMEDIATION_HINTS = Object.freeze({
   reinstallEngine:
     'npm install -g amicus  (a transient install error can roll back the engine binaries — re-run, or: npm cache clean --force && npm install -g amicus)',
 
+  /**
+   * Engine binary missing/rolled back AND possibly AV-quarantined. The doctor
+   * opencode-bin hint: combines the transient-rollback reinstall guidance with
+   * the Windows-Defender allow-list note, matching the electron avHint contract.
+   */
+  reinstallEngineAv:
+    'npm install -g amicus  (a transient install error can roll back the engine binaries — re-run, or: npm cache clean --force && npm install -g amicus). '
+    + 'If your antivirus (e.g. Windows Defender) quarantined opencode.exe, allow-list it first, then reinstall.',
+
+  /**
+   * Runtime server-start failure when the opencode engine binary does not
+   * resolve on disk. One clear, actionable message replacing the opaque
+   * spawn ENOENT — surfaced by startServer (the missing-binary boundary).
+   */
+  engineMissing:
+    'OpenCode engine binary not found — it was likely skipped during install or quarantined by antivirus. '
+    + 'Run "amicus doctor", reinstall with "npm i -g amicus", and allow-list opencode.exe in your antivirus.',
+
   /** Electron absent — reinstall to add the interactive GUI (headless still works). */
   reinstallElectron: 'npm install -g amicus  (reinstall to add Electron)',