amicus 1.6.1 → 1.7.1

package/src/cli-handlers-doctor.js

@@ -1,8 +1,13 @@
 // src/cli-handlers-doctor.js
 'use strict';
 
+const HINTS = require('./utils/remediation-hints');
+
 const MAX_CATALOG_AGE_MS = 24 * 60 * 60 * 1000; // 24h (mirrors model-catalog DEFAULT_MAX_AGE_MS)
 
+/** #56: keep `doctor --fix`'s electron self-heal from ever hanging on a slow disk/network. */
+const FIX_TIMEOUT_MS = 90 * 1000;
+
 /** Default real helpers; tests override via deps. */
 function realDeps() {
   const fs = require('fs');
@@ -11,6 +16,13 @@ function realDeps() {
   return {
     nodeVersion: process.version,
     readApiKeys: () => require('./utils/api-key-store').readApiKeys(),
+    readApiKeyValues: () => require('./utils/api-key-store').readApiKeyValues(),
+    checkOpenRouterCredit: (key) => require('./utils/api-key-validation').checkOpenRouterCredit(key),
+    getCwd: () => process.cwd(),
+    readProjectMarkers: (dir) => {
+      const exists = (name) => { try { return fs.existsSync(path.join(dir, name)); } catch (_e) { return false; } };
+      return { hasGit: exists('.git'), hasPackageJson: exists('package.json'), hasClaude: exists('.claude') };
+    },
     getConfigDir: () => require('./utils/config').getConfigDir(),
     resolveModel: () => require('./utils/config').resolveModel(),
     readCache: () => require('./utils/model-catalog').readCache(),
@@ -27,6 +39,10 @@ function realDeps() {
       return candidates.some(p => fs.existsSync(p));
     },
     getElectronPath: () => require('./sidecar/interactive').getElectronPath(),
+    // #56: self-heal primitive for `doctor --fix`. Pure probe (getElectronPath)
+    // stays separate; repair only runs when fix is requested.
+    repairElectron: (opts) => require('./sidecar/electron-install').repairElectron(opts),
+    fix: false,
     discoverClaudeCodeMcps: () => require('./utils/mcp-discovery').discoverClaudeCodeMcps(),
     discoverCoworkMcps: () => require('./utils/mcp-discovery').discoverCoworkMcps(),
     skillInstalled: () => {
@@ -43,12 +59,19 @@ function guard(id, name, fn) {
   catch (e) { return { id, name, status: 'error', message: e.message, hint: null }; }
 }
 
+/** Async variant of guard; a thrown/rejected fn becomes an error line. */
+async function guardAsync(id, name, fn) {
+  try { return await fn(); }
+  catch (e) { return { id, name, status: 'error', message: e.message, hint: null }; }
+}
+
 /**
- * Compose the health checks. Never throws.
+ * Compose the health checks. Never throws (async; awaits non-blocking
+ * network checks such as the OpenRouter credit probe).
  * @param {object} [depsOverride]
- * @returns {Array<{id,name,status,message,hint}>}
+ * @returns {Promise<Array<{id,name,status,message,hint}>>}
  */
-function runDoctorChecks(depsOverride = {}) {
+async function runDoctorChecks(depsOverride = {}) {
   const d = { ...realDeps(), ...depsOverride };
   const checks = [];
 
@@ -105,19 +128,43 @@ function runDoctorChecks(depsOverride = {}) {
   checks.push(guard('opencode-bin', 'OpenCode binary', () => (
     d.hasOpencodeBinary()
       ? { id: 'opencode-bin', name: 'OpenCode binary', status: 'ok', message: 'found', hint: null }
-      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: '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)' }
+      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: HINTS.reinstallEngine }
   )));
 
-  checks.push(guard('electron', 'Electron (interactive GUI)', () => (
-    d.getElectronPath()
-      ? { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed', hint: null }
-      : { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: 'not installed — headless still works', hint: 'npm install -g amicus  (reinstall to add Electron)' }
-  )));
+  checks.push(await guardAsync('electron', 'Electron (interactive GUI)', async () => {
+    if (d.getElectronPath()) {
+      return { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed', hint: null };
+    }
+    // Broken (missing / quarantined). With --fix, self-heal in place (#56):
+    // repairElectron provisions the binary; {deferred} (no cache, no network)
+    // maps to WARN — a deferred download is not a failure. Without --fix, just
+    // point the user at `amicus doctor --fix`.
+    if (d.fix) {
+      let res;
+      try {
+        res = await d.repairElectron({ timeoutMs: FIX_TIMEOUT_MS });
+      } catch (e) {
+        return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: `repair failed: ${e.message} — headless still works`, hint: HINTS.doctorFix };
+      }
+      res = res || {};
+      if (res.repaired || res.usable) {
+        return { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed (self-healed)', hint: null };
+      }
+      const why = res.reason ? ` — ${res.reason}` : '';
+      const detail = res.deferred
+        ? `deferred${why}`
+        : res.contended
+          ? `repair already in progress${why}`
+          : `not provisioned${why}`;
+      return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: `${detail} — headless still works`, hint: HINTS.doctorFix };
+    }
+    return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: 'not installed — headless still works', hint: HINTS.doctorFix };
+  }));
 
   checks.push(guard('skills', 'Skills installed', () => (
     d.skillInstalled()
       ? { id: 'skills', name: 'Skills installed', status: 'ok', message: '~/.claude/skills/{sidecar,second-opinion}', hint: null }
-      : { id: 'skills', name: 'Skills installed', status: 'warn', message: 'one or both skills missing', hint: 'npm install -g amicus  (re-runs the skill install)' }
+      : { id: 'skills', name: 'Skills installed', status: 'warn', message: 'one or both skills missing', hint: `${HINTS.reinstall}  (re-runs the skill install)` }
   )));
 
   checks.push(guard('mcp', 'MCP registration', () => {
@@ -127,12 +174,37 @@ function runDoctorChecks(depsOverride = {}) {
     const inCowork = !!(cowork && cowork.amicus);
     // Primary signal: Claude Code MCP registration. Cowork/Desktop is reported as bonus only.
     if (!inCode) {
-      return { id: 'mcp', name: 'MCP registration', status: 'warn', message: 'not registered in Claude Code', hint: 'npm install -g amicus  (or install the amicus plugin)' };
+      return { id: 'mcp', name: 'MCP registration', status: 'warn', message: 'not registered in Claude Code', hint: `${HINTS.reinstall}  (or install the amicus plugin)` };
     }
     const extra = inCowork ? ', Cowork/Desktop' : '';
     return { id: 'mcp', name: 'MCP registration', status: 'ok', message: `registered: Claude Code${extra}`, hint: null };
   }));
 
+  // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no key.
+  checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit', async () => {
+    const values = d.readApiKeyValues() || {};
+    const key = values.openrouter;
+    if (!key) {
+      return { id: 'openrouter-credit', name: 'OpenRouter credit', status: 'ok', message: 'no OpenRouter key — skipped', hint: null };
+    }
+    // Reuses the #38 non-blocking probe; resolves warning:null on any failure.
+    const res = (await d.checkOpenRouterCredit(key)) || {};
+    if (res.warning) {
+      return { id: 'openrouter-credit', name: 'OpenRouter credit', status: 'warn', message: res.warning, hint: 'Add credit at openrouter.ai/credits, or build a free council (amicus setup → option 2).' };
+    }
+    const remaining = (typeof res.limitRemaining === 'number') ? ` ($${res.limitRemaining} remaining)` : '';
+    return { id: 'openrouter-credit', name: 'OpenRouter credit', status: 'ok', message: `credit ok${remaining}`, hint: null };
+  }));
+
+  // #43: project-root sanity — warns when cwd looks like an app/install dir or lacks project markers.
+  checks.push(guard('project-root', 'Project root', () => {
+    const dir = d.getCwd();
+    const markers = d.readProjectMarkers(dir);
+    const { assessProjectRoot } = require('./utils/project-root-sanity');
+    const r = assessProjectRoot(dir, markers);
+    return { id: 'project-root', name: 'Project root', status: r.status, message: r.message, hint: r.hint };
+  }));
+
   return checks;
 }
 
@@ -151,14 +223,18 @@ function renderHuman(checks) {
 }
 
 /**
- * `amicus doctor [--json]`. Injectable `runChecks` for tests.
- * @param {{_:string[], json?:boolean}} args
+ * `amicus doctor [--json] [--fix]`. Injectable `runChecks` for tests.
+ * `--fix` (#56) self-heals fixable checks in place (electron via repairElectron).
+ * @param {{_:string[], json?:boolean, fix?:boolean}} args
  * @param {(deps?:object)=>Array} [runChecks]
  * @returns {Promise<number>} exit code
  */
 async function handleDoctor(args, runChecks = runDoctorChecks) {
   const useJson = !!args.json;
-  const checks = runChecks();
+  // #56: --fix flows into runDoctorChecks as a dep so fixable checks (electron)
+  // self-heal in place. Omitted (not false) when absent so the injected
+  // test-double sees a clean "no fix" call.
+  const checks = await runChecks(args.fix ? { fix: true } : undefined);
   if (useJson) {
     const { buildDoctorDoc } = require('./utils/result-schema');
     const VERSION = require('../package.json').version;

package/src/cli-handlers-run.js

@@ -173,6 +173,10 @@ async function handleFanout(args) {
     contextTurns: args['context-turns'],
     contextSince: args['context-since'],
     contextMaxTokens: args['context-max-tokens'],
+    // #10: forward the Cowork parent so MCP-spawned fanout legs pin the right
+    // session (mirrors handleStart's coworkProcess plumbing). Without this the
+    // spawned `--cowork-process` flag is dropped and buildContext gets null.
+    coworkProcess: args['cowork-process'],
     mcp: args.mcp,
     mcpConfig: args['mcp-config'],
     noMcp: args['no-mcp'],

package/src/cli.js

@@ -116,6 +116,7 @@ function isBooleanFlag(key) {
      'no-ledger',            // council tally: compute the record without appending to the reliability ledger
      'html',                 // council report: emit a self-contained HTML page
      'md',                   // council report: emit Markdown (default)
+     'fix',                  // doctor: self-heal fixable checks in place (#56)
    ];
   return booleanFlags.includes(key);
 }
@@ -438,6 +439,8 @@ Subcommands for 'council':
   doctor: `
 Options for 'doctor':
   --json                       Machine-readable output
+  --fix                        Self-heal fixable checks in place (provisions the
+                               Electron GUI binary; no global reinstall)
 `,
   setup: `
 Options for 'setup':

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 };