amicus 1.6.1 → 1.7.1

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [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.
+
+### 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.

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/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

@@ -22,6 +22,8 @@ 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');
 
@@ -98,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: {
@@ -148,13 +150,14 @@ 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.
@@ -290,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,
@@ -443,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/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.6.1",
+  "version": "1.7.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.",
   "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 };