amicus 1.6.1 → 1.7.1

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('');
 

package/src/utils/project-root-sanity.js

@@ -0,0 +1,66 @@
+// src/utils/project-root-sanity.js
+'use strict';
+
+/**
+ * Project-root sanity heuristic (#43).
+ *
+ * `amicus doctor` resolves the project dir from process.cwd(); when a user
+ * launches amicus from a packaged-app/install directory (e.g. the Claude
+ * Desktop app dir) instead of their repo, sessions land in the wrong place.
+ * This pure helper inspects a path string + its directory markers and decides
+ * whether to WARN. It never touches the filesystem and never throws.
+ */
+
+/**
+ * Path fragments that signal a packaged-app / install directory rather than a
+ * user project. Matched case-insensitively against the normalized path.
+ */
+const INSTALL_PATTERNS = [
+  /anthropicclaude/i,        // Claude Desktop app dir
+  /[\\/]app-\d/i,            // versioned electron app dir, e.g. app-1.2.3
+  /appdata[\\/]local/i,      // Windows per-user app data
+  /program files/i,          // Windows install root
+  /[\\/]\.asar/i,            // packaged electron resources
+];
+
+/** @returns {boolean} true if the path looks like an app/install dir */
+function looksLikeInstallDir(dir) {
+  if (!dir || typeof dir !== 'string') { return false; }
+  return INSTALL_PATTERNS.some((re) => re.test(dir));
+}
+
+/**
+ * Assess a resolved project dir.
+ *
+ * @param {string} dir Resolved project directory (e.g. process.cwd()).
+ * @param {{hasGit?:boolean, hasPackageJson?:boolean, hasClaude?:boolean}} markers
+ *   Presence of .git / package.json / .claude in `dir`.
+ * @returns {{status:'ok'|'warn', message:string, hint:string|null}}
+ */
+function assessProjectRoot(dir, markers) {
+  const m = markers || {};
+  const safeDir = (dir && typeof dir === 'string') ? dir : '';
+  const hint =
+    'pass an explicit project (amicus … --project <path>) or cd into your repo before running amicus';
+
+  if (looksLikeInstallDir(safeDir)) {
+    return {
+      status: 'warn',
+      message: `${safeDir || '(empty)'} looks like an app/install dir, not a project`,
+      hint,
+    };
+  }
+
+  const hasMarker = !!(m.hasGit || m.hasPackageJson || m.hasClaude);
+  if (!hasMarker) {
+    return {
+      status: 'warn',
+      message: `${safeDir || '(empty)'} has no project markers (.git / package.json / .claude)`,
+      hint,
+    };
+  }
+
+  return { status: 'ok', message: safeDir, hint: null };
+}
+
+module.exports = { assessProjectRoot, looksLikeInstallDir, INSTALL_PATTERNS };

package/src/utils/remediation-hints.js

@@ -0,0 +1,51 @@
+// src/utils/remediation-hints.js
+'use strict';
+
+/**
+ * Shared, copy-paste remediation hint strings.
+ *
+ * One source of truth for the fix commands surfaced by `amicus doctor` and by
+ * failure messages across the CLI, so the guidance never drifts. Consumed by
+ * src/cli-handlers-doctor.js (per-check hints) and reused by sweep'd failure
+ * sites (#32) and the MCP recovery surface (#43).
+ *
+ * The object is frozen — these are a stable copy-paste contract; callers read
+ * fields, they do not mutate them.
+ */
+const REMEDIATION_HINTS = Object.freeze({
+  /** Canonical global (re)install. */
+  reinstall: 'npm install -g amicus',
+
+  /** `npm cache clean --force` — clears a corrupt npm cache before reinstalling. */
+  cacheClean: 'npm cache clean --force',
+
+  /**
+   * Engine binaries missing/rolled back. A transient install error can roll
+   * back the platform engine packages; re-run, or clean the cache and reinstall.
+   */
+  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)',
+
+  /** Electron absent — reinstall to add the interactive GUI (headless still works). */
+  reinstallElectron: 'npm install -g amicus  (reinstall to add Electron)',
+
+  /**
+   * Electron present but broken (ABI mismatch / partial unpack). Delete the
+   * vendored copy and reinstall to force a clean rebuild.
+   */
+  rebuildElectron:
+    'rm -rf node_modules/electron && npm install -g amicus  (rebuild Electron after an ABI mismatch or partial unpack)',
+
+  /** Point the user at the single recovery hub. */
+  runDoctor: 'run: amicus doctor  (diagnoses config, keys, engine & MCP, with copy-paste fixes)',
+
+  /**
+   * Self-heal the optional Electron GUI in place (#56). This is the convergence
+   * target for the three "reinstall to fix Electron" hints — it provisions the
+   * binary from cache (or downloads on demand) WITHOUT a global reinstall, so it
+   * can't loop the way `npm install -g amicus` could when the rollback recurs.
+   */
+  doctorFix: 'amicus doctor --fix  (self-heal the Electron GUI in place — provisions the binary; no reinstall, so it can\'t loop)',
+});
+
+module.exports = REMEDIATION_HINTS;

package/src/utils/result-schema.js

@@ -106,9 +106,19 @@ function waveExitCode(waveStatus) {
  * @param {object} opts
  * @param {string} opts.waveId
  * @param {Array<object>} opts.legs - run documents (in --models order)
- * Counts track the four primary terminal statuses (complete/error/timeout/aborted);
- * legs with other statuses (e.g. 'crashed', 'running' in a rebuilt wave) count toward
- * `total` only, so total may exceed the sum of the named buckets.
+ *
+ * COUNTS REMAINDER RULE (stable, no schemaVersion bump): `counts` exposes four
+ * NAMED terminal buckets — complete, error, timeout, aborted — plus `total`
+ * (= legs.length). The remaining TERMINAL_STATUSES ('crashed', 'idle-timeout')
+ * and any non-terminal status (e.g. 'running' in a live-rebuilt wave) are
+ * deliberately NOT given their own bucket; they are reflected ONLY in `total`.
+ * Therefore a consumer must treat the unnamed remainder as
+ *   total − (complete + error + timeout + aborted)
+ * and must NOT assume the named buckets sum to `total`. Adding new buckets
+ * would change the document shape and REQUIRES bumping SCHEMA_VERSION.
+ * This agrees with the MCP wave path (mcp-server.js), which counts a leg as
+ * "done" iff its status is in TERMINAL_STATUSES — including 'crashed' — so a
+ * crashed leg is done/total there exactly as it is total-only here.
  * @param {{source: string, file: string|null, chars: number}|null} [opts.promptMeta]
  * @param {string|null} [opts.createdAt]
  * @param {string|null} [opts.completedAt]
@@ -117,6 +127,9 @@ function waveExitCode(waveStatus) {
  */
 function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null }) {
   const { sumWaveUsage } = require('./pricing');
+  // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
+  // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
+  // only, so total may exceed complete+error+timeout+aborted.
   const counts = {
     total: legs.length,
     complete: legs.filter(l => l.status === 'complete').length,

package/src/utils/version-info.js

@@ -0,0 +1,49 @@
+/**
+ * @module utils/version-info — running vs. on-disk amicus version (#33)
+ *
+ * After an `npm i -g amicus` upgrade, a long-lived MCP server process keeps
+ * running the OLD code until the client restarts it. That staleness is
+ * invisible from inside an agent session. These helpers surface the running
+ * version in MCP responses and, via a CALL-TIME re-read of the on-disk
+ * package.json, flag when the two have diverged.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/** Absolute path to this install's package.json (repo root). */
+const PKG_PATH = path.join(__dirname, '..', '..', 'package.json');
+
+/**
+ * The version baked into the running process at load time. Free: package.json
+ * is already require()'d elsewhere, so this hits the module cache.
+ */
+const RUNNING_VERSION = require('../../package.json').version;
+
+/**
+ * Re-read the on-disk package.json version at call time. Wrapped in try/catch
+ * — the file may be mid-rewrite, missing, or unreadable during/after an
+ * upgrade — and returns null on any failure rather than throwing.
+ * @returns {string|null}
+ */
+function readOnDiskVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(PKG_PATH, 'utf-8'));
+    return (pkg && typeof pkg.version === 'string') ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One-line staleness warning, or null when there's nothing to warn about
+ * (on-disk version unreadable or identical to the running version).
+ * @returns {string|null}
+ */
+function versionWarning() {
+  const onDisk = readOnDiskVersion();
+  if (!onDisk || onDisk === RUNNING_VERSION) { return null; }
+  return `Amicus was upgraded on disk (running v${RUNNING_VERSION}, on-disk v${onDisk}). `
+    + `Restart your MCP client to load v${onDisk}.`;
+}
+
+module.exports = { RUNNING_VERSION, readOnDiskVersion, versionWarning, PKG_PATH };