amicus 1.6.1 → 1.7.0

package/src/mcp-server.js

@@ -14,6 +14,7 @@ const { durationBetween } = require('./utils/result-schema');
 const { canonicalProjectPath } = require('./utils/project-path');
 const { recordSession } = require('./utils/session-index');
 const { fileURLToPath } = require('url');
+const { RUNNING_VERSION, versionWarning } = require('./utils/version-info');
 
 /**
  * Elapsed run duration: time between createdAt and the run's end, bounding the
@@ -142,6 +143,17 @@ function textResult(text, isError) {
   return result;
 }
 
+/**
+ * Append a stale-version warning content block (#33) when the on-disk
+ * package.json has been upgraded under the running process. No-op when in
+ * sync or unreadable (versionWarning() returns null). Mutates `content`.
+ */
+function appendVersionWarning(content) {
+  const warn = versionWarning();
+  if (warn) { content.push({ type: 'text', text: warn }); }
+  return content;
+}
+
 /**
  * Compute next poll hint for headless sessions.
  * @returns {{ hint: string }}
@@ -429,15 +441,17 @@ const handlers = {
         taskId: metadata.taskId, type: 'wave', status: metadata.status,
         legsComplete: done, legsTotal: legs.length, legs,
         elapsed: `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`,
+        version: RUNNING_VERSION,
       };
       if (metadata.status === 'crashed' || metadata.status === 'error') {
         response.reason = metadata.reason || 'Unknown error';
       }
-      const responseText = JSON.stringify(response);
+      const content = [{ type: 'text', text: JSON.stringify(response) }];
+      appendVersionWarning(content);
       if (metadata.status === 'running') {
-        return { content: [{ type: 'text', text: responseText }, { type: 'text', text: HEADLESS_STATUS_REMINDER }] };
+        content.push({ type: 'text', text: HEADLESS_STATUS_REMINDER });
       }
-      return textResult(responseText);
+      return { content };
     }
 
     if (metadata.status === 'running' && metadata.pid) {
@@ -455,6 +469,7 @@ const handlers = {
     const response = {
       taskId: metadata.taskId, status: metadata.status,
       elapsed: `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`,
+      version: RUNNING_VERSION,
     };
     if (metadata.model) { response.model = metadata.model; }
 
@@ -479,11 +494,12 @@ const handlers = {
     if (metadata.status === 'crashed' || metadata.status === 'error') {
       response.reason = metadata.reason || 'Unknown error';
     }
-    const responseText = JSON.stringify(response);
+    const content = [{ type: 'text', text: JSON.stringify(response) }];
+    appendVersionWarning(content);
     if (metadata.status === 'running' && metadata.headless) {
-      return { content: [{ type: 'text', text: responseText }, { type: 'text', text: HEADLESS_STATUS_REMINDER }] };
+      content.push({ type: 'text', text: HEADLESS_STATUS_REMINDER });
     }
-    return textResult(responseText);
+    return { content };
   },
 
   async amicus_read(input, project) {
@@ -729,6 +745,10 @@ const handlers = {
     if (input.timeout)       { args.push('--timeout', String(input.timeout)); }
     if (input.summaryLength) { args.push('--summary-length', input.summaryLength); }
     if (input.includeContext === false) { args.push('--no-context'); }
+    // #10: forward cowork session pinning to the legs (parity with amicus_start),
+    // so context-inheriting fanout launched from Cowork resolves the right parent.
+    if (input.coworkProcess) { args.push('--cowork-process', input.coworkProcess); }
+    if (input.parentSession) { args.push('--session-id', input.parentSession); }
 
     try { spawnSidecarProcess(args, waveDir); } catch (err) {
       // Best-effort: never leave a pid-less wave record claiming 'running'

package/src/mcp-tools.js

@@ -115,7 +115,7 @@ function getTools() {
   },
   {
     name: 'amicus_status',
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     description:
       'Check the status of a running Amicus session. Returns status ' +
       '(running/complete), elapsed time, and progress info. Primarily ' +
@@ -279,6 +279,14 @@ function getTools() {
       includeContext: z.boolean().optional().default(true).describe(
         'Include parent conversation context (built once, shared by all legs). Set false for self-contained briefings.'
       ),
+      coworkProcess: z.string().optional().describe(
+        'Cowork VM process name (e.g., "modest-laughing-goodall"). ' +
+        'Extract from CWD: /sessions/<name>/. Required for parent context loading from Cowork.'
+      ),
+      parentSession: z.string().optional().describe(
+        'Claude Code session UUID for exact context matching. ' +
+        'Prevents ambiguity when multiple sessions are active in the same project.'
+      ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -360,13 +368,21 @@ function getTools() {
  */
 function getGuideText() {
   const { getEffectiveAliases } = require('./utils/config');
+  const { RUNNING_VERSION, versionWarning } = require('./utils/version-info');
   const aliases = getEffectiveAliases();
   const aliasRows = Object.entries(aliases)
     .map(([name, model]) => `| ${name} | ${model} |`)
     .join('\n');
+  // #33: surface the running version (and a call-time staleness warning) so a
+  // post-upgrade agent session can tell it's running old code.
+  const warn = versionWarning();
+  const versionLine = `**Running amicus version:** ${RUNNING_VERSION}`
+    + (warn ? `\n\n> ⚠️ ${warn}` : '');
 
   return `# Amicus Usage Guide
 
+${versionLine}
+
 ## What Is Amicus?
 Amicus spawns parallel conversations with different LLMs and folds results back into your context.
 

package/src/sidecar/electron-cache.js

@@ -0,0 +1,42 @@
+/**
+ * Electron download-cache root resolution (#53 helper).
+ *
+ * Split out of electron-install.js to keep that module under the 300-line
+ * size gate. Mirrors @electron/get's cache-root precedence:
+ *   - electron_config_cache (npm config / .npmrc)
+ *   - ELECTRON_CACHE (env override)
+ *   - the platform default from env-paths('electron').cache
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+/** Platform default cache dir, mirroring env-paths('electron',{suffix:''}).cache. */
+function defaultCacheRoot(env = process.env) {
+  const home = env.HOME || os.homedir();
+  if (process.platform === 'win32') {
+    const localAppData = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    return path.join(localAppData, 'electron', 'Cache');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Caches', 'electron');
+  }
+  const xdg = env.XDG_CACHE_HOME || path.join(home, '.cache');
+  return path.join(xdg, 'electron');
+}
+
+/**
+ * Ordered, de-duplicated list of cache roots to probe for a cached zip.
+ * @returns {string[]}
+ */
+function resolveCacheRoots(env = process.env) {
+  const roots = [];
+  if (env.electron_config_cache) { roots.push(env.electron_config_cache); }
+  if (env.ELECTRON_CACHE) { roots.push(env.ELECTRON_CACHE); }
+  roots.push(defaultCacheRoot(env));
+  return [...new Set(roots.filter(Boolean))];
+}
+
+module.exports = { resolveCacheRoots, defaultCacheRoot };

package/src/sidecar/electron-ensure.js

@@ -0,0 +1,92 @@
+/**
+ * ensureElectron() — lazy first-GUI provisioning (#55).
+ *
+ * This is the ONLY entry point allowed to PROVISION (download/extract) electron,
+ * and only on FIRST GUI use. getElectronPath()/checkElectronAvailable() stay
+ * PURE PROBES: the doctor check (cli-handlers-doctor.js) and MCP amicus_setup
+ * (mcp-server.js) depend on that purity — making a probe provision would silently
+ * fetch ~170MB. Kept in its own module so src/sidecar/electron-install.js stays
+ * under the 300-line size gate.
+ */
+
+'use strict';
+
+const {
+  isElectronUsable: defaultIsUsable,
+  resolveElectronBinary: defaultResolve,
+  repairElectron: defaultRepair,
+} = require('./electron-install');
+const HINTS = require('../utils/remediation-hints');
+
+/**
+ * Module-level single-flight guard. Holds the in-flight (or last SUCCESSFUL)
+ * provision promise so repeated GUI launches in one process never re-download.
+ * A FAILED provision is cleared so a later launch may retry.
+ */
+let _ensurePromise = null;
+
+/** Test-only: clear the once-guard so each test starts single-flight-clean. */
+function _resetEnsureElectron() {
+  _ensurePromise = null;
+}
+
+/**
+ * Lazily PROVISION electron on FIRST GUI use.
+ *
+ * Flow: if isElectronUsable() return the resolved path (NO repair). Otherwise
+ * call repairElectron({cacheOnly:false}) — network ALLOWED here, this is an
+ * explicit first-use provision — with progress messaging, then re-check.
+ *
+ * Single-flight: the in-flight / last-successful promise is memoized so
+ * concurrent and repeated launches share ONE provision. A failed attempt is
+ * NOT cached (the guard is cleared) so a later launch can retry.
+ *
+ * @param {object} opts
+ * @param {object} [opts.deps] injected
+ *   { isElectronUsable, resolveElectronBinary, repairElectron, logProgress }.
+ * @param {object} [opts.repairOptions] forwarded to repairElectron (electronDir, etc.).
+ * @returns {Promise<{ok:boolean, path?:string, reason?:string}>}
+ */
+function ensureElectron({ deps = {}, repairOptions = {} } = {}) {
+  const usable = deps.isElectronUsable || defaultIsUsable;
+  const resolve = deps.resolveElectronBinary || defaultResolve;
+  const repair = deps.repairElectron || defaultRepair;
+  const logProgress = deps.logProgress
+    || ((msg) => { try { process.stderr.write(`${msg}\n`); } catch { /* ignore */ } });
+
+  // Fast path: already provisioned. Cheap stat — safe to run every launch.
+  if (usable()) {
+    return Promise.resolve({ ok: true, path: resolve() });
+  }
+
+  // Single-flight: reuse an in-flight (or already-succeeded) provision.
+  if (_ensurePromise) { return _ensurePromise; }
+
+  _ensurePromise = (async () => {
+    logProgress('[amicus] Provisioning the Electron GUI binary (first GUI use, ~170MB). This runs once...');
+    let result;
+    try {
+      result = await repair({ cacheOnly: false, ...repairOptions });
+    } catch (err) {
+      return { ok: false, reason: `Electron provisioning failed: ${err && err.message}` };
+    }
+    if (usable()) {
+      logProgress('[amicus] Electron GUI ready.');
+      return { ok: true, path: resolve() };
+    }
+    const reason = (result && result.reason)
+      || `Electron could not be provisioned; the GUI is unavailable. ${HINTS.doctorFix} (or use --no-ui).`;
+    return { ok: false, reason };
+  })().then((r) => {
+    // Only memoize SUCCESS; a failure clears the guard so a later launch retries.
+    if (!r.ok) { _ensurePromise = null; }
+    return r;
+  }, (err) => {
+    _ensurePromise = null;
+    throw err;
+  });
+
+  return _ensurePromise;
+}
+
+module.exports = { ensureElectron, _resetEnsureElectron };

package/src/sidecar/electron-install.js

@@ -0,0 +1,244 @@
+/**
+ * Electron self-heal primitive (#53, #59).
+ *
+ * Electron is an optionalDependency (^28.0.0). A flaky / interrupted extract
+ * — or Windows Defender quarantining electron.exe — can leave the package's
+ * path.txt on disk while dist/<exe> is MISSING, so the GUI silently fails.
+ *
+ * This module is the keystone the rest of the self-heal cluster (#54-#57)
+ * imports. It does NOT wire itself into any caller. Everything that downloads,
+ * extracts, spawns, or locks is dependency-INJECTABLE so tests never hit the
+ * network or extract a real binary.
+ *
+ * Layout reference (npm `electron` package):
+ *   node_modules/electron/path.txt    -> "electron.exe" (the exe basename)
+ *   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
+ */
+
+'use strict';
+
+const fsDefault = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const { resolveCacheRoots } = require('./electron-cache');
+
+/** Default on-disk location of the installed electron package. */
+function defaultElectronDir() {
+  try {
+    return path.dirname(require.resolve('electron/package.json'));
+  } catch {
+    return path.join(__dirname, '..', '..', 'node_modules', 'electron');
+  }
+}
+
+/** Platform exe basename, matching electron's getPlatformPath(). */
+function platformExe(platform) {
+  switch (platform) {
+    case 'mas':
+    case 'darwin':
+      return path.join('Electron.app', 'Contents', 'MacOS', 'Electron');
+    case 'win32':
+      return 'electron.exe';
+    default:
+      return 'electron';
+  }
+}
+
+/**
+ * Resolve the on-disk electron exe path from the package layout.
+ * Mirrors ELECTRON_OVERRIDE_DIST_PATH semantics (#59): when set, the exe is
+ * <override>/<exeBasename>; otherwise it is <electronDir>/dist/<exeBasename>.
+ * @returns {string|null} resolved exe path, or null if path.txt is unreadable.
+ */
+function resolveElectronBinary({ electronDir = defaultElectronDir(), env = process.env, platform = process.platform, fs = fsDefault } = {}) {
+  let exeRel;
+  const pathFile = path.join(electronDir, 'path.txt');
+  try {
+    exeRel = fs.readFileSync(pathFile, 'utf-8').trim();
+  } catch {
+    exeRel = '';
+  }
+  if (!exeRel) {
+    exeRel = platformExe(platform);
+  }
+  const override = env.ELECTRON_OVERRIDE_DIST_PATH;
+  if (override) {
+    return path.join(override, exeRel);
+  }
+  return path.join(electronDir, 'dist', exeRel);
+}
+
+/**
+ * True ONLY if the resolved exe actually EXISTS on disk. This is the
+ * stat-the-exe check #54 reuses — path.txt surviving is NOT enough.
+ */
+function isElectronUsable({ electronDir = defaultElectronDir(), env = process.env, platform = process.platform, fs = fsDefault } = {}) {
+  const exe = resolveElectronBinary({ electronDir, env, platform, fs });
+  try {
+    return fs.existsSync(exe);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate a previously-downloaded electron zip in the env-configurable cache
+ * roots. Walks <root>/<sha>/electron-v<ver>-<platform>-<arch>.zip.
+ * @returns {string|null} absolute zip path, or null when no cache hit.
+ */
+function cachedZip({ version, platform = process.platform, arch = process.arch, env = process.env, fs = fsDefault } = {}) {
+  const zipName = `electron-v${version}-${platform}-${arch}.zip`;
+  for (const root of resolveCacheRoots(env)) {
+    let shaDirs;
+    try {
+      shaDirs = fs.readdirSync(root);
+    } catch {
+      continue;
+    }
+    for (const sha of shaDirs) {
+      const candidate = path.join(root, sha, zipName);
+      try {
+        if (fs.existsSync(candidate)) {
+          return candidate;
+        }
+      } catch {
+        /* ignore unreadable subdir */
+      }
+    }
+  }
+  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));
+}
+
+/** Extract a cached zip into <electronDir>/dist offline. */
+async function extractFromCache({ zip, electronDir, platform, extract, fs }) {
+  const distDir = path.join(electronDir, 'dist');
+  fs.mkdirSync(distDir, { recursive: true });
+  await extract(zip, { dir: distDir });
+  writePathTxt({ electronDir, platform, fs });
+}
+
+/** Drive electron's own install.js with force_no_cache semantics. */
+function runInstaller({ electronDir, force, spawn }) {
+  const installScript = path.join(electronDir, 'install.js');
+  const env = { ...process.env };
+  if (force) {
+    env.force_no_cache = 'true';
+  }
+  return spawn(process.execPath, [installScript], { env, stdio: 'ignore' });
+}
+
+/**
+ * Heal a broken electron install.
+ *
+ * @param {object} opts
+ * @param {boolean} [opts.cacheOnly] never hit the network; return
+ *   {deferred,reason} when there is no cached zip.
+ * @param {boolean} [opts.force] force a fresh (no-cache) installer download.
+ * @param {number}  [opts.timeoutMs] best-effort installer timeout.
+ * @param {object}  [opts.deps] injected { cachedZip, extract, spawn, acquireLock, fs }.
+ * @returns {Promise<{repaired?:boolean, deferred?:boolean, contended?:boolean, reason?:string}>}
+ */
+async function repairElectron({
+  cacheOnly = false,
+  force = false,
+  timeoutMs,
+  electronDir = defaultElectronDir(),
+  platform = process.platform,
+  version,
+  arch = process.arch,
+  deps = {},
+} = {}) {
+  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 }));
+  const findZip = deps.cachedZip || ((o) => cachedZip(o));
+  const acquireLock = deps.acquireLock || ((o) => defaultAcquireLock({ ...o, fs }));
+
+  if (!version) {
+    try {
+      version = require(path.join(electronDir, 'package.json')).version;
+    } catch {
+      version = undefined;
+    }
+  }
+
+  // Single-flight: bail out gracefully if another caller is already repairing.
+  let lock;
+  try {
+    lock = acquireLock({ electronDir, fs });
+  } catch (e) {
+    if (e && e.code === 'EEXIST') {
+      return { contended: true, reason: 'Another electron repair is already in progress.' };
+    }
+    throw e;
+  }
+
+  try {
+    // 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) {
+      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 };
+  } finally {
+    try { lock.release(); } catch { /* ignore */ }
+  }
+}
+
+module.exports = {
+  resolveElectronBinary,
+  isElectronUsable,
+  cachedZip,
+  repairElectron,
+  // exported for sibling/self-heal modules + tests
+  platformExe,
+  defaultElectronDir,
+};

package/src/sidecar/fanout.js

@@ -102,6 +102,7 @@ function writeWaveMetadata(waveDir, patch) {
  * Run a fan-out wave. Spec §4.3.
  * @param {object} options - models, prompt, promptMeta, waveId?, project, agent?,
  *   thinking?, timeout? (minutes), summaryLength?, includeContext?, sessionId?,
+ *   coworkProcess? (#10: Cowork parent-session pin, forwarded to buildContext),
  *   contextTurns?, contextSince?, contextMaxTokens?, mcp?, mcpConfig?, noMcp?,
  *   excludeMcp?, noValidateModel?, json?, client?, quiet? (suppress stdout — tests)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
@@ -183,6 +184,8 @@ async function runFanout(options) {
     ? buildContext(project, options.sessionId || 'current', {
         contextTurns: options.contextTurns, contextSince: options.contextSince,
         contextMaxTokens: options.contextMaxTokens, client: options.client,
+        // #10: pin the right Cowork parent session for every leg (built once).
+        coworkProcess: options.coworkProcess,
       })
     : '[Context excluded by caller - briefing is self-contained]';
   const { system: systemPrompt, userMessage } = buildPrompts(

package/src/sidecar/interactive.js

@@ -14,19 +14,25 @@ const { getCompatEnv } = require('../utils/env-compat');
 const { startInteractiveMirror } = require('./interactive-mirror');
 const { getSessionDir } = require('../session-manager');
 const { canonicalProjectPath } = require('../utils/project-path');
-
-/** Get the Electron binary path via require('electron').
- *  Works in all install contexts (global, local, npx hoisted).
- *  @returns {string|null} Full path to Electron binary, or null if not installed */
+const { ensureElectron } = require('./electron-ensure');
+
+/** Resolve the Electron binary path ONLY when the exe actually exists on disk.
+ *  #54: path.txt surviving (require('electron') resolving) is NOT enough — a
+ *  quarantined/missing dist/<exe> must read as not-installed. Delegates to the
+ *  stat-the-exe probe so the runtime check matches postinstall's strictness.
+ *  Stays a PURE PROBE: no download/extract side-effect.
+ *  @returns {string|null} Full path to a usable Electron binary, or null. */
 function getElectronPath() {
   try {
-    return require('electron');
+    const { isElectronUsable, resolveElectronBinary } = require('./electron-install');
+    return isElectronUsable() ? resolveElectronBinary() : null;
   } catch {
     return null;
   }
 }
 
-/** Check if Electron is available (lazy loading guard) */
+/** Check if Electron is available (lazy loading guard). Pure probe — stats the
+ *  exe via getElectronPath(), never provisions. */
 function checkElectronAvailable() {
   return getElectronPath() !== null;
 }
@@ -95,11 +101,15 @@ function handleElectronProcess(electronProcess, taskId, resolve) {
 
 /** Run sidecar in interactive mode (Electron GUI) */
 async function runInteractive(model, systemPrompt, userMessage, taskId, project, options = {}) {
-  if (!checkElectronAvailable()) {
-    logger.error('Electron not installed — interactive mode unavailable');
+  // Lazily PROVISION electron on FIRST GUI use (#55). ensureElectron() is the
+  // one place network provisioning is allowed; the probes stay pure. When it
+  // returns ok:false the GUI is unavailable — fail gracefully toward --no-ui.
+  const ensured = await ensureElectron();
+  if (!ensured.ok) {
+    logger.error('Electron not available — interactive mode unavailable', { reason: ensured.reason });
     return {
       summary: '', completed: false, timedOut: false, taskId,
-      error: 'Interactive mode requires electron. Install with: npm install -g amicus (or use --no-ui for headless mode)'
+      error: `Interactive mode requires electron. ${ensured.reason} (or use --no-ui for headless mode)`
     };
   }
 
@@ -197,7 +207,9 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
   });
 
   return new Promise((resolve, _reject) => {
-    const electronPath = getElectronPath();
+    // Prefer the path ensureElectron() resolved: a same-process first-use
+    // provision can leave require('electron') cached as a stale null (#55).
+    const electronPath = ensured.path || getElectronPath();
     const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
 
     const nodeModulesBin = path.join(__dirname, '..', '..', 'node_modules', '.bin');

package/src/sidecar/setup-window.js

@@ -10,19 +10,24 @@ const { spawn } = require('child_process');
 const path = require('path');
 const { logger } = require('../utils/logger');
 const { getElectronPath } = require('./interactive');
+const { ensureElectron } = require('./electron-ensure');
 const { getCompatEnv } = require('../utils/env-compat');
 
 /**
- * Launch the Electron setup window for API key entry
+ * Launch the Electron setup window for API key entry.
+ * Lazily PROVISIONS electron on first GUI use (#55) via ensureElectron() — the
+ * one place network provisioning is allowed; getElectronPath() stays a pure probe.
  * @returns {Promise<{ success: boolean, error?: string }>}
  */
-function launchSetupWindow() {
+async function launchSetupWindow() {
+  const ensured = await ensureElectron();
+  if (!ensured.ok) {
+    return { success: false, error: ensured.reason || 'Electron not installed' };
+  }
   return new Promise((resolve) => {
-    const electronPath = getElectronPath();
-    if (!electronPath) {
-      resolve({ success: false, error: 'Electron not installed' });
-      return;
-    }
+    // Prefer the path ensureElectron() resolved: a same-process first-use
+    // provision can leave require('electron') cached as a stale null (#55).
+    const electronPath = ensured.path || getElectronPath();
     const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
 
     const env = {

package/src/sidecar/setup.js

@@ -266,8 +266,10 @@ async function runReadlineSetup() {
     if (foundKeys.length > 0) {
       console.log(`API keys detected: ${foundKeys.join(', ')}`);
     } else {
+      const { runDoctor } = require('../utils/remediation-hints');
       console.log('No API keys detected.');
       console.log('Set OPENROUTER_API_KEY to get started, or run: amicus setup');
+      console.log(`Not sure what's wrong? ${runDoctor}`);
     }
     console.log('');