amicus 1.7.0 → 1.7.2

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [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
+- **The Electron GUI now shows the current rail-yard brand mark.** The window/taskbar icon, the setup
+  wizard's header and footer, and the session toolbar were still rendering the pre-redesign squiggle
+  mark; they now use the shipped clay→gold rail-yard mark (matching the site favicon). The inline
+  glyphs stay token-bound (clay tracks / gold mainline) so they follow the design system.
+
 ## [1.7.0] - 2026-06-30
 
 Electron self-heal, a real `amicus doctor`, and the GUI on the design system — plus MCP/diagnostics correctness.

package/electron/assets/icon.svg

@@ -1,5 +1,12 @@
-<svg width="1024" height="1024" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <rect width="16" height="16" rx="3" fill="#2D2B2A"/>
-  <path d="M3 2v12" stroke="#D97757" stroke-width="2" stroke-linecap="round"/>
-  <path d="M10 2v5c0 2-3 3-7 5" stroke="#D97757" stroke-width="2" stroke-linecap="round" stroke-opacity="0.6"/>
+<svg width="1024" height="1024" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="32" height="32" rx="7" fill="#2D2B2A"/>
+  <g stroke="#D97757" stroke-width="1.2" stroke-linecap="round" stroke-linejoin="miter">
+    <path d="M4 8H19"/>
+    <path d="M4 11H14L19 8"/>
+    <path d="M4 14H13L19 8"/>
+    <path d="M4 17H12L19 8"/>
+    <path d="M4 20H11L19 8"/>
+    <path d="M4 23H10L19 8"/>
+  </g>
+  <path d="M19 8H28" stroke="#E8B24A" stroke-width="1.2" stroke-linecap="round"/>
 </svg>

package/electron/setup-ui-styles.js

@@ -18,7 +18,8 @@ function __rawWizardCSS() {
     padding: 10px 20px; border-bottom: 1px solid var(--border);
   }
   .header svg { flex-shrink: 0; }
-  .header svg path { stroke: var(--accent); }
+  .header svg path { stroke: var(--accent); stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: miter; }
+  .header svg path.brand-main { stroke: var(--gold-400); }
   .header-title {
     color: var(--accent); font-size: 12px; font-weight: 600;
     letter-spacing: 0.8px; text-transform: uppercase;
@@ -319,7 +320,8 @@ function __rawWizardCSS() {
     letter-spacing: 0.8px; text-transform: uppercase;
     display: flex; align-items: center; gap: 6px;
   }
-  .footer-brand svg path { stroke: var(--accent); }
+  .footer-brand svg path { stroke: var(--accent); stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: miter; }
+  .footer-brand svg path.brand-main { stroke: var(--gold-400); }
   .footer-nav { display: flex; gap: 6px; }
   .nav-btn {
     padding: 6px 16px; border: 1px solid var(--border);

package/electron/setup-ui.js

@@ -33,7 +33,7 @@ function buildSetupHTML(options = {}) {
   return `<!DOCTYPE html>
 <html><head><meta charset="utf-8"><title>Amicus Setup</title>
 <style>${css}</style></head><body>
-  <div class="header"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M3 2v12" stroke-width="2" stroke-linecap="round"/><path d="M10 2v5c0 2-3 3-7 5" stroke-width="2" stroke-linecap="round" stroke-opacity="0.6"/></svg><span class="header-title">${brandName} Setup</span></div>
+  <div class="header"><svg width="18" height="18" viewBox="0 0 32 32" fill="none"><path d="M4 8H19"/><path d="M4 11H14L19 8"/><path d="M4 14H13L19 8"/><path d="M4 17H12L19 8"/><path d="M4 20H11L19 8"/><path d="M4 23H10L19 8"/><path class="brand-main" d="M19 8H28"/></svg><span class="header-title">${brandName} Setup</span></div>
   <div class="progress-bar"><div class="progress-step active" id="step-1"><span class="progress-dot">1</span><span>API Keys</span></div><div class="progress-connector"></div><div class="progress-step" id="step-2"><span class="progress-dot">2</span><span>Models</span></div><div class="progress-connector"></div><div class="progress-step" id="step-3"><span class="progress-dot">3</span><span>Routing</span></div><div class="progress-connector"></div><div class="progress-step" id="step-4"><span class="progress-dot">4</span><span>Review</span></div></div>
   <div class="content">
     <div class="wizard-step visible" id="wizard-step-1"><div id="import-notice"></div>${keysHtml}</div>
@@ -50,7 +50,7 @@ function buildSetupHTML(options = {}) {
       </div>
     </div>
   </div>
-  <div class="footer"><div class="footer-brand"><svg width="14" height="14" viewBox="0 0 16 16" fill="none"><path d="M3 2v12" stroke-width="2" stroke-linecap="round"/><path d="M10 2v5c0 2-3 3-7 5" stroke-width="2" stroke-linecap="round" stroke-opacity="0.6"/></svg> ${brandName}</div><div class="footer-nav"><button class="nav-btn" id="back-btn" style="display:none">Back</button><button class="nav-btn primary" id="next-btn" disabled>Next</button><button class="nav-btn primary" id="finish-btn" style="display:none">Finish</button></div></div>
+  <div class="footer"><div class="footer-brand"><svg width="15" height="15" viewBox="0 0 32 32" fill="none"><path d="M4 8H19"/><path d="M4 11H14L19 8"/><path d="M4 14H13L19 8"/><path d="M4 17H12L19 8"/><path d="M4 20H11L19 8"/><path d="M4 23H10L19 8"/><path class="brand-main" d="M19 8H28"/></svg> ${brandName}</div><div class="footer-nav"><button class="nav-btn" id="back-btn" style="display:none">Back</button><button class="nav-btn primary" id="next-btn" disabled>Next</button><button class="nav-btn primary" id="finish-btn" style="display:none">Finish</button></div></div>
 ${buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson)}
 </body></html>`;
 }

package/electron/toolbar.js

@@ -70,7 +70,8 @@ function buildToolbarHTML(options = {}) {
     letter-spacing: 0.8px;
     text-transform: uppercase;
   }
-  .logo path { stroke: var(--accent); }
+  .logo path { stroke: var(--accent); stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: miter; }
+  .logo path.brand-main { stroke: var(--gold-400); }
   .sep { color: var(--border-strong); font-size: 14px; }
   .detail, .timer {
     color: var(--text-3);
@@ -136,9 +137,10 @@ function buildToolbarHTML(options = {}) {
   }
   .update-banner .dismiss-btn:hover { color: var(--text-1); }`;
 
-  const logoSvg = `<svg class="logo" width="16" height="16" viewBox="0 0 16 16" fill="none">
-      <path d="M3 2v12" stroke-width="2" stroke-linecap="round"/>
-      <path d="M10 2v5c0 2-3 3-7 5" stroke-width="2" stroke-linecap="round" stroke-opacity="0.6"/>
+  const logoSvg = `<svg class="logo" width="16" height="16" viewBox="0 0 32 32" fill="none">
+      <path d="M4 8H19"/><path d="M4 11H14L19 8"/><path d="M4 14H13L19 8"/>
+      <path d="M4 17H12L19 8"/><path d="M4 20H11L19 8"/><path d="M4 23H10L19 8"/>
+      <path class="brand-main" d="M19 8H28"/>
     </svg>`;
 
   if (mode === 'setup') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.0",
+  "version": "1.7.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.",
   "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,9 +15,7 @@
  *   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';
@@ -28,6 +26,7 @@ const os = require('os');
 const { spawnSync } = require('child_process');
 
 const { resolveCacheRoots } = require('./electron-cache');
+const { avHint, verifyExtractOutcome: verifyQuarantine } = require('./electron-quarantine');
 
 /** Default on-disk location of the installed electron package. */
 function defaultElectronDir() {
@@ -116,15 +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
@@ -154,6 +144,41 @@ 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,
+  });
+  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');
@@ -190,6 +215,7 @@ async function repairElectron({
   const spawn = deps.spawn || ((cmd, args, o) => spawnSync(cmd, args, { ...o, timeout: timeoutMs }));
   const findZip = deps.cachedZip || ((o) => cachedZip(o));
   const acquireLock = deps.acquireLock || ((o) => defaultAcquireLock({ ...o, fs }));
+  const downloadArtifact = deps.downloadArtifact || require('@electron/get').downloadArtifact;
 
   if (!version) {
     try {
@@ -214,20 +240,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-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)',