amicus 1.6.0 → 1.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "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,65 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-06-30
+
+Electron self-heal, a real `amicus doctor`, and the GUI on the design system — plus MCP/diagnostics correctness.
+
+### Added
+- **Electron self-heal.** Amicus now detects a broken or quarantined Electron install (a half-extracted
+  or AV-removed binary) and repairs it from the local download cache — **fully offline**. New
+  `amicus doctor --fix` heals in place, the GUI lazily provisions itself on first use, and an opt-in
+  `AMICUS_PREFETCH_ELECTRON=1` aggressively prewarms it. Install-time provisioning is cache-only (no
+  network during `npm install`) and never fails the install.
+- **`amicus doctor` is now a recovery hub.** Checks carry copy-paste remediation hints, report
+  OpenRouter credit/free-tier status, and warn when the resolved project root looks like an app/install
+  directory rather than your repo.
+- **Running version in MCP responses.** `amicus_status` / `amicus_guide` now report the running amicus
+  version and warn when the on-disk package is newer (restart your MCP client to load it).
+- **The GUI is on the design system.** The embedded OpenCode session UI is themed to the clay/gold
+  tokens, the load-failsafe error page and window backgrounds are token-driven, and a drift guard keeps
+  new hardcoded colors/fonts out of `electron/`.
+
+### Fixed
+- **Electron no longer reads "installed" when the binary is missing.** Runtime checks (including
+  `amicus doctor` and the GUI launch path) now stat the actual executable instead of trusting
+  `path.txt`, so a quarantined/half-extracted Electron is correctly detected — the root cause of the
+  silently-broken setup wizard.
+- **`amicus_fanout` forwards Cowork session pinning** (`--cowork-process` / parent session) to its
+  spawned legs, so context-inheriting fan-outs pin the right parent.
+- **`amicus_status` annotation corrected** — it is no longer declared read-only/idempotent, since its
+  wave branch updates metadata during crash detection.
+- **Wave counts account for crashed / idle-timeout legs** (documented remainder rule), so consumers
+  summing the named buckets no longer mismatch the total.
+
+## [1.6.1] - 2026-06-30
+
+Project-directory and session-addressing correctness — agents, sessions, and the interactive GUI now agree on which project they're in.
+
+### Added
+- **`AMICUS_PROJECT_DIR` + MCP `roots` support.** When the project is not passed explicitly, the MCP
+  server now resolves the working directory from the client's first `file://` workspace root (falling
+  back to `AMICUS_PROJECT_DIR`, then the process cwd) — so a stdio MCP server spawned by a desktop
+  client no longer roots agents in the app install directory where they can't see your files.
+- **Global session index.** `amicus_status` / `amicus_read` / `amicus_list` now consult a global
+  `taskId -> project` index on a per-project miss, so a session created in one project is still found
+  when looked up from another.
+- **Per-command help for the rest of the CLI.** `amicus council --help` (and `continue`, `resume`,
+  `doctor`, `setup`, `key`, `mcp`) now print their own scoped usage instead of the full global help.
+
+### Fixed
+- **Interactive `--cwd`: follow-up prompts no longer fail "unable to retrieve session."** When the
+  launch directory differs from `--cwd` (the normal sidecar-skill pattern), the OpenCode session is now
+  scoped to the project directory and the Electron Web-UI route is built from the **server-echoed**
+  session directory rather than a guessed one, so turn 2+ resolve correctly.
+- **Shared-server MCP sessions are scoped to the project directory** — every create and follow-up call
+  carries the directory, so headless MCP sessions are found on a server shared across projects.
+- **`amicus_read` surfaces the failure reason** for crashed / timed-out / aborted runs that wrote no
+  summary, instead of a bare "No summary available."
+- **`amicus_abort`'s "session not found"** now names the resolved project, matching `status` / `read`.
+- Internal: a single `canonicalProjectPath()` now normalizes project paths (slash direction, drive-letter
+  case, trailing slash, UNC shares) so creation and lookup always agree.
+
 ## [1.6.0] - 2026-06-30
 
 Install resilience and council-failure correctness — the first two blocks of the post-1.5 backlog program.

package/electron/load-failsafe.js

@@ -14,6 +14,8 @@
 
 'use strict';
 
+const { tokenCss } = require('../src/design/tokens');
+
 const DEFAULT_TIMEOUT_MS = 15000;
 const ERR_ABORTED = -3; // benign: fires on in-page redirects/navigation replacement
 
@@ -62,14 +64,19 @@ function escapeHTML(value) {
  * @returns {string} full HTML document
  */
 function buildLoadErrorHTML({ url, errorCode, errorDescription }) {
+  // This page renders after the OpenCode UI definitively failed to load, in a
+  // data: URL context. Inline the design tokens with absolute font URLs so the
+  // bundled webfonts resolve and var(--x) references work with no external CSS.
   return `<!DOCTYPE html>
 <html><head><style>
-  body { background: #2D2B2A; color: #D4D0CC; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+${tokenCss({ absoluteFontUrls: true })}
+  body { background: var(--bg); color: var(--text-2);
+         font-family: var(--font-sans);
          display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; }
   .box { max-width: 440px; padding: 24px; }
-  h1 { color: #D97757; font-size: 16px; margin: 0 0 12px; }
-  p { font-size: 13px; line-height: 1.5; color: #A09B96; margin: 0 0 10px; }
-  code { font-family: 'SF Mono', Menlo, Consolas, monospace; font-size: 11px; color: #D4D0CC;
+  h1 { color: var(--accent); font-size: 16px; margin: 0 0 12px; }
+  p { font-size: 13px; line-height: 1.5; color: var(--text-2); margin: 0 0 10px; }
+  code { font-family: var(--font-mono); font-size: 11px; color: var(--text-1);
          word-break: break-all; }
 </style></head><body>
   <div class="box">

package/electron/main.js

@@ -21,6 +21,9 @@ const { createFoldHandler } = require('./fold');
 const { registerSetupHandlers } = require('./ipc-setup');
 const { computeWindowPosition } = require('./window-position');
 const { attachLoadFailsafe, buildLoadErrorHTML } = require('./load-failsafe');
+const { buildSessionRoute } = require('./session-route');
+const { buildOpencodeThemeCSS } = require('./opencode-theme');
+const { TOKENS } = require('../src/design/tokens');
 
 const ICON_PATH = path.join(__dirname, 'assets', 'icon.png');
 
@@ -51,6 +54,11 @@ const MODE = getCompatEnv('MODE') || 'sidecar';
 const TASK_ID = getCompatEnv('TASK_ID') || 'unknown';
 const MODEL = getCompatEnv('MODEL') || 'unknown';
 const CWD = getCompatEnv('CWD') || process.cwd();
+// The directory the OpenCode session was actually scoped to (#45). Set by the
+// interactive launcher as canonicalProjectPath(--cwd) so the Web-UI route is
+// built from the SAME directory createSession used. Falls back to CWD for
+// back-compat with launchers that predate this env var.
+const SESSION_DIRECTORY = getCompatEnv('SESSION_DIRECTORY') || CWD;
 const CLIENT = getCompatEnv('CLIENT') || 'code-local';
 const OPENCODE_PORT = parseInt(getCompatEnv('OPENCODE_PORT') || '4096', 10);
 const OPENCODE_SESSION_ID = getCompatEnv('SESSION_ID');
@@ -92,7 +100,7 @@ function createAmicusWindow() {
     width: WIN_W, height: WIN_H, minWidth: 550, minHeight: 600,
     x: winX, y: winY,
     show: false,
-    frame: true, backgroundColor: '#2D2B2A',
+    frame: true, backgroundColor: TOKENS.bg,
     title: 'Amicus',
     icon: ICON_PATH,
     webPreferences: {
@@ -142,20 +150,21 @@ function createAmicusWindow() {
     url: OPENCODE_URL, sessionId: OPENCODE_SESSION_ID, taskId: TASK_ID
   });
 
-  // Use Electron's insertCSS API on dom-ready to hide OpenCode branding.
-  // This is more reliable than preload DOM injection in BrowserView.
+  // Use Electron's insertCSS API on dom-ready to hide OpenCode branding AND
+  // theme the embedded chat surface to the clay/gold tokens (#49). The theme
+  // is token-driven — it inlines tokenCss() and remaps OpenCode's own :root
+  // custom properties — so it tracks the toolbar without brittle class
+  // selectors. insertCSS is more reliable than preload DOM injection in a
+  // BrowserView. NOTE: the live visual match is a user-side CDP/manual check.
   contentView.webContents.on('dom-ready', () => {
-    contentView.webContents.insertCSS(`
-      #root > div > header { display: none !important; }
-      svg[viewBox="0 0 234 42"] { visibility: hidden !important; }
-    `).catch(() => {});
+    contentView.webContents.insertCSS(buildOpencodeThemeCSS()).catch(() => {});
   });
 
   // Navigate directly to the session URL to bypass the project selection screen.
-  // OpenCode's router format: /<base64url(projectPath)>/session/<sessionId>
-  const contentUrl = OPENCODE_SESSION_ID
-    ? `${OPENCODE_URL}/${Buffer.from(CWD).toString('base64url')}/session/${OPENCODE_SESSION_ID}`
-    : OPENCODE_URL;
+  // Build the route from SESSION_DIRECTORY — the directory the session was
+  // actually scoped to — NOT a fresh base64url(CWD) guess, so Web-UI follow-up
+  // prompts resolve the session even when process cwd != --cwd (#45).
+  const contentUrl = buildSessionRoute(OPENCODE_URL, OPENCODE_SESSION_ID, SESSION_DIRECTORY);
 
   // The window only becomes visible on the success path below. Without this
   // failsafe, a failed/stalled UI load leaves an invisible window and a
@@ -284,7 +293,7 @@ async function createSetupWindow() {
 
   mainWindow = new BrowserWindow({
     width: 560, height: 680, minWidth: 480, minHeight: 580,
-    frame: true, backgroundColor: '#2D2B2A',
+    frame: true, backgroundColor: TOKENS.bg,
     title: `${getBrandName(CLIENT)} Setup`,
     icon: ICON_PATH,
     resizable: false,
@@ -437,7 +446,7 @@ function createSettingsChildWindow() {
   const settingsWin = new BrowserWindow({
     width: 560, height: 680,
     parent: mainWindow, modal: false,
-    frame: true, backgroundColor: '#2D2B2A',
+    frame: true, backgroundColor: TOKENS.bg,
     title: `${getBrandName(CLIENT)} Settings`,
     icon: ICON_PATH,
     resizable: false,

package/electron/opencode-theme.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Issue #49 — token-driven theme for the embedded OpenCode web UI.
+ *
+ * main.js injects this via `contentView.webContents.insertCSS(...)` on
+ * `dom-ready`. Before #49 that hook only HID OpenCode's header/wordmark; this
+ * module extends it so the embedded chat surface inherits the clay/gold tokens
+ * and matches the token-driven Amicus toolbar (toolbar.js).
+ *
+ * Robustness note (the fragile bit): OpenCode (1.17.11 at time of writing) is a
+ * SolidStart app whose generated class names can change between releases. So we
+ * PREFER overriding OpenCode's OWN :root CSS custom properties — a much more
+ * stable surface than `.css-abc123` class selectors. We:
+ *   1. inline the canonical token CSS (tokenCss) so OUR vars + @font-face are
+ *      available inside the BrowserView (absolute font URLs, same as toolbar.js
+ *      / setup-ui-styles.js / load-failsafe.js do),
+ *   2. remap a generous superset of OpenCode's plausible theme custom-property
+ *      names to our tokens (var(--...)), covering the prefixes OpenCode has
+ *      shipped (--sst-*, --theme-*, --ock-*, --color-*), and
+ *   3. add a few low-specificity element fallbacks (body/font) for the case
+ *      where a release renames its root vars entirely.
+ *
+ * Keep this side-effect-free and Electron-free so it stays unit-testable
+ * without booting Electron (main.js boots Electron on require).
+ *
+ * NOT verifiable headless: the live visual match against a running OpenCode
+ * session is a USER-SIDE CDP/manual check.
+ */
+
+const { tokenCss } = require('../src/design/tokens');
+
+/**
+ * The original hide-only rules (header + wordmark) preserved from the pre-#49
+ * dom-ready hook. rebrandUI() swaps the wordmark; these keep OpenCode's own
+ * chrome out of view until/while that runs.
+ */
+const HIDE_CHROME = `
+  #root > div > header { display: none !important; }
+  svg[viewBox="0 0 234 42"] { visibility: hidden !important; }
+`;
+
+/**
+ * Map OpenCode's own theme custom properties onto our clay/gold tokens. We list
+ * the property names under every prefix OpenCode has used so a rename in one
+ * family still leaves the others driving the surface. Unknown vars are simply
+ * inert — setting an unused custom property has no effect — so over-listing is
+ * safe and is the robust play here.
+ */
+const OPENCODE_ROOT_OVERRIDES = `
+  :root {
+    /* --- backgrounds / surfaces --- */
+    --sst-color-background: var(--bg);
+    --sst-color-background-panel: var(--surface-1);
+    --sst-color-background-element: var(--surface-2);
+    --theme-background: var(--bg);
+    --theme-background-panel: var(--surface-1);
+    --theme-background-element: var(--surface-2);
+    --ock-background: var(--bg);
+    --ock-background-panel: var(--surface-1);
+    --color-background: var(--bg);
+    --color-surface: var(--surface-1);
+    --color-surface-raised: var(--surface-2);
+
+    /* --- borders --- */
+    --sst-color-border: var(--border);
+    --theme-border: var(--border);
+    --ock-border: var(--border);
+    --color-border: var(--border);
+    --color-border-strong: var(--border-strong);
+
+    /* --- text --- */
+    --sst-color-text: var(--text-1);
+    --sst-color-text-secondary: var(--text-2);
+    --sst-color-text-muted: var(--text-3);
+    --theme-text: var(--text-1);
+    --theme-text-muted: var(--text-2);
+    --ock-text: var(--text-1);
+    --ock-text-muted: var(--text-2);
+    --color-text: var(--text-1);
+    --color-text-muted: var(--text-2);
+
+    /* --- brand accent (clay) --- */
+    --sst-color-primary: var(--accent-500);
+    --sst-color-accent: var(--accent-500);
+    --theme-primary: var(--accent-500);
+    --theme-accent: var(--accent-500);
+    --ock-primary: var(--accent-500);
+    --ock-accent: var(--accent-500);
+    --color-primary: var(--accent-500);
+    --color-accent: var(--accent-500);
+    --color-link: var(--accent-400);
+
+    /* --- counter-accent (gold) --- */
+    --sst-color-secondary: var(--gold-400);
+    --theme-secondary: var(--gold-400);
+    --ock-secondary: var(--gold-400);
+    --color-secondary: var(--gold-400);
+  }
+`;
+
+/**
+ * Low-specificity element fallbacks. These only bite if OpenCode renamed its
+ * root vars entirely (so the overrides above no-op); they intentionally avoid
+ * generated class names. Kept gentle so they don't fight OpenCode's layout.
+ */
+const ELEMENT_FALLBACKS = `
+  html, body {
+    background-color: var(--bg);
+    color: var(--text-1);
+    font-family: var(--font-sans);
+  }
+  a { color: var(--accent-500); }
+  ::selection { background: var(--accent-soft); }
+`;
+
+/**
+ * Build the full theme CSS string injected into the OpenCode BrowserView.
+ * @returns {string} hide-chrome + inlined tokens + :root overrides + fallbacks.
+ */
+function buildOpencodeThemeCSS() {
+  return [
+    HIDE_CHROME,
+    tokenCss({ absoluteFontUrls: true }),
+    OPENCODE_ROOT_OVERRIDES,
+    ELEMENT_FALLBACKS,
+  ].join('\n');
+}
+
+module.exports = { buildOpencodeThemeCSS };

package/electron/preload.js

@@ -34,7 +34,7 @@ function injectBrandingCss() {
   try {
     const style = document.createElement('style');
     style.textContent = [
-      'html, body { background-color: #2D2B2A !important; }',
+      'html, body { background-color: var(--bg, #0a0a0a) !important; }',
       '#root > div > header { display: none !important; }',
       'svg[viewBox="0 0 234 42"] { display: none !important; }',
     ].join('\n');

package/electron/session-route.js

@@ -0,0 +1,28 @@
+/**
+ * Web-UI session route builder (#45).
+ *
+ * OpenCode's router format is `/<base64url(projectPath)>/session/<sessionId>`.
+ * The route MUST be built from the directory the OpenCode session was actually
+ * created/scoped to — NOT a fresh base64url(process.cwd()) guess. When the
+ * amicus process cwd != --cwd (the normal sidecar-skill launch), a CWD-derived
+ * route points at a project route with no matching session, so Web-UI follow-up
+ * prompts fail "unable to retrieve session". The caller passes the same
+ * directory it used to scope createSession (the server-echoed session.directory,
+ * or a consistent canonicalProjectPath(--cwd) fallback).
+ *
+ * Pure function: no electron, no fs, no process state. Safe to unit-test.
+ *
+ * @param {string} baseUrl - OpenCode server base URL (e.g. http://localhost:4096)
+ * @param {string} [sessionId] - OpenCode session id; falsy → return baseUrl only
+ * @param {string} sessionDirectory - The directory the session is scoped to
+ * @returns {string} Fully-qualified route URL, or baseUrl when no session id.
+ */
+function buildSessionRoute(baseUrl, sessionId, sessionDirectory) {
+  if (!sessionId) {
+    return baseUrl;
+  }
+  const seg = Buffer.from(sessionDirectory).toString('base64url');
+  return `${baseUrl}/${seg}/session/${sessionId}`;
+}
+
+module.exports = { buildSessionRoute };

package/package.json

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

@@ -13,8 +13,14 @@ const path = require('path');
 const os = require('os');
 const { execFileSync } = require('child_process');
 
+const { repairElectron } = require('../src/sidecar/electron-install');
+const HINTS = require('../src/utils/remediation-hints');
+
 const SETUP_HOOKS_SCRIPT = path.join(__dirname, 'setup-hooks.js');
 
+/** Short cache-only provision budget: a slow disk must never hang the install. */
+const PROVISION_TIMEOUT_MS = 15000;
+
 const SKILL_SOURCE = path.join(__dirname, '..', 'skills', 'sidecar', 'SKILL.md');
 const COUNCIL_SOURCE_DIR = path.join(__dirname, '..', 'skills', 'second-opinion');
 
@@ -175,40 +181,56 @@ function registerClaudeDesktop() {
 }
 
 /**
- * Resolve the Electron binary path the same way src/sidecar/interactive.js
- * getElectronPath() does: require('electron') returns the absolute path to the
- * binary (or throws if the optionalDependency never installed/extracted).
- * @returns {string|null} Path to the Electron binary, or null if unresolvable.
- */
-function resolveElectron() {
-  try {
-    return require('electron');
-  } catch {
-    return null;
-  }
-}
-
-/**
- * NON-FATAL verification that the OPTIONAL electron binary actually extracted.
- * Electron is an optionalDependency: npm exits 0 even if its download/extract
- * fails (or AV quarantines electron.exe), so without this the user only finds
- * out the GUI is broken much later. Warn clearly that headless runs + the
- * council still work, and point at `amicus doctor` / reinstall to get the GUI.
+ * NON-FATAL, CACHE-ONLY provisioning of the OPTIONAL electron binary (#57,
+ * supersedes #30's warn-only verifyElectron). Electron is an optionalDependency:
+ * npm exits 0 even if its download/extract failed (or AV quarantined
+ * electron.exe), so without this the user only finds out the GUI is broken much
+ * later.
+ *
+ * We heal from the LOCAL cache via repairElectron({cacheOnly:true}) — NO network
+ * during install. When a cached zip extracts cleanly the GUI just works. When
+ * there is no cache (or the repair defers/contends), we emit a clear notice that
+ * the GUI provisions on first use and that headless runs + the council already
+ * work, then point at `amicus doctor --fix` (#56) — NOT a reinstall, which can
+ * loop. A short timeout keeps a slow disk from ever hanging the install.
+ *
+ * This MUST never throw out of postinstall — the whole body (sync setup, the
+ * awaited repair, and a synchronous-throw resolver) is guarded so nothing here
+ * can turn into a non-zero exit (#29 always-exit-0 guard preserved).
  *
- * This MUST never throw out of postinstall — the whole body is guarded so a
- * resolver failure or a missing fs can never turn into a non-zero exit.
+ * OPT-IN PREWARM (#60): when AMICUS_PREFETCH_ELECTRON=1 the user has asked to
+ * aggressively prewarm the GUI at install time. We additionally drive a full
+ * (possibly-networked) fetch via repairElectron({force:true}). This is the ONLY
+ * path that may hit the network during install; it stays opt-in and non-fatal
+ * (a throw here is swallowed and exit 0 is preserved). The DEFAULT remains
+ * cache-only (#57).
  *
- * @param {object} deps - { resolveElectron } override for testing.
+ * @param {object} deps - { repairElectron } override for testing.
+ * @returns {Promise<void>}
  */
-function verifyElectron(deps = {}) {
+async function provisionElectron(deps = {}) {
   try {
-    const _resolve = deps.resolveElectron || resolveElectron;
-    const binPath = _resolve();
-    if (binPath && fs.existsSync(binPath)) { return; }
-    console.warn('[amicus] Warning: the Electron binary did not install — the interactive GUI / setup-wizard is unavailable.');
-    console.warn('[amicus] Headless runs and the council still work. Run `amicus doctor` to check, or `npm install -g amicus` to reinstall and add the GUI.');
+    const _repair = deps.repairElectron || repairElectron;
+
+    // Opt-in aggressive prewarm (#60): full fetch if needed. Non-fatal.
+    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)) {
+        console.log('[amicus] Electron GUI binary prewarmed.');
+        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; }
+    // 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}`);
   } catch {
-    // Never let the electron check throw out of postinstall.
+    // Never let provisioning throw out of postinstall.
   }
 }
 
@@ -247,7 +269,7 @@ function setupHooks(deps = {}) {
   }
 }
 
-function main(deps = {}) {
+async function main(deps = {}) {
   if (process.env.AMICUS_SKIP_POSTINSTALL === '1') {
     console.log('[amicus] AMICUS_SKIP_POSTINSTALL set — skipping global setup (plugin channel handles registration).');
     return;
@@ -257,6 +279,7 @@ function main(deps = {}) {
   const _registerClaudeCode = deps.registerClaudeCode || registerClaudeCode;
   const _registerClaudeDesktop = deps.registerClaudeDesktop || registerClaudeDesktop;
   const _setupHooks = deps.setupHooks || setupHooks;
+  const _provisionElectron = deps.provisionElectron || provisionElectron;
 
   console.log('[amicus] Installing...');
   // Dev-only: configure git hooks (no-op for consumers). Folded in from the
@@ -267,8 +290,9 @@ function main(deps = {}) {
   _registerClaudeCode();
   _registerClaudeDesktop();
 
-  // Non-fatal: warn (only) if the optional Electron binary failed to extract.
-  verifyElectron(deps);
+  // Non-fatal, cache-only: heal the optional Electron binary from local cache
+  // or emit a deferred notice (GUI provisions on first use). Never throws.
+  await _provisionElectron(deps);
 
   console.log('');
   console.log('[amicus] Setup:');
@@ -282,9 +306,9 @@ function main(deps = {}) {
  * package, but skill-copy + MCP registration are optional — amicus itself still
  * works without them. Warn clearly and exit 0 (mirrors scripts/setup-hooks.js).
  */
-function runCli(deps = {}) {
+async function runCli(deps = {}) {
   try {
-    main(deps);
+    await main(deps);
   } catch (err) {
     console.warn(`[amicus] Warning: optional post-install setup failed: ${err && err.message}`);
     console.warn('[amicus] Skill install + MCP registration are optional — amicus itself still works.');
@@ -299,4 +323,4 @@ if (require.main === module) {
   runCli();
 }
 
-module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill, setupHooks, verifyElectron, resolveElectron, COUNCIL_FILES };
+module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill, setupHooks, provisionElectron, COUNCIL_FILES };