amicus 1.6.0 → 1.7.0

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/opencode-client.js

@@ -107,15 +107,34 @@ async function createClient(baseUrl) {
   return createOpencodeClient(config);
 }
 
+/**
+ * Build an optional `query: { directory }` fragment to spread into an SDK call.
+ *
+ * Returns an EMPTY object when no directory is supplied so spreading it is a
+ * true no-op — the emitted request is byte-for-byte identical to a call that
+ * never knew about `directory`. Only when a directory IS passed does a
+ * `query: { directory }` key appear on the wire (the SDK accepts
+ * `query?: { directory?: string }` on every session endpoint).
+ *
+ * @param {string} [directory] - Optional project directory to scope the call to.
+ * @returns {{query?: {directory: string}}} Fragment to spread into SDK args.
+ */
+function directoryQuery(directory) {
+  return directory === undefined ? {} : { query: { directory } };
+}
+
 /**
  * Create a new session
  *
  * @param {import('@opencode-ai/sdk').OpencodeClient} client - SDK client
+ * @param {string} [directory] - Optional project directory to scope the session
+ *   to (threaded to the SDK as query.directory). Omitting it keeps the call
+ *   byte-for-byte identical to before.
  * @returns {Promise<string>} Session ID
  * @throws {Error} If session creation fails
  */
-async function createSession(client) {
-  const result = await client.session.create({});
+async function createSession(client, directory) {
+  const result = await client.session.create({ ...directoryQuery(directory) });
 
   if (result.error) {
     throw new Error(result.error.message || 'Failed to create session');
@@ -145,10 +164,13 @@ async function createSession(client) {
  * @param {object} [options.reasoning] - Reasoning/thinking configuration
  * @param {string} [options.reasoning.effort] - Effort level: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'none'
  * @param {object} [options.watchdog] - IdleWatchdog instance to signal busy/idle around the API call
+ * @param {string} [options.directory] - Optional project directory to scope the
+ *   call to (threaded to the SDK as query.directory). Omitting it keeps the
+ *   call byte-for-byte identical to before.
  * @returns {Promise<object>} API response
  */
 async function sendPrompt(client, sessionId, options) {
-  const { model, system, parts, agent, tools, reasoning, watchdog } = options;
+  const { model, system, parts, agent, tools, reasoning, watchdog, directory } = options;
 
   // Parse model string to SDK format
   const modelSpec = parseModelString(model);
@@ -185,7 +207,8 @@ async function sendPrompt(client, sessionId, options) {
   try {
     result = await client.session.promptAsync({
       path: { id: sessionId },
-      body
+      body,
+      ...directoryQuery(directory)
     });
   } finally {
     if (watchdog) {
@@ -227,11 +250,15 @@ async function sendPrompt(client, sessionId, options) {
  *
  * @param {import('@opencode-ai/sdk').OpencodeClient} client - SDK client
  * @param {string} sessionId - Session ID
+ * @param {string} [directory] - Optional project directory to scope the call to
+ *   (threaded to the SDK as query.directory). Omitting it keeps the call
+ *   byte-for-byte identical to before.
  * @returns {Promise<Array>} Array of messages
  */
-async function getMessages(client, sessionId) {
+async function getMessages(client, sessionId, directory) {
   const result = await client.session.messages({
-    path: { id: sessionId }
+    path: { id: sessionId },
+    ...directoryQuery(directory)
   });
 
   return result.data || [];
@@ -314,10 +341,13 @@ async function listSessions(client) {
  *
  * @param {import('@opencode-ai/sdk').OpencodeClient} client - SDK client
  * @param {string} sessionId - Session ID to abort
+ * @param {string} [directory] - Optional project directory to scope the call to
+ *   (threaded to the SDK as query.directory). Omitting it keeps the call
+ *   byte-for-byte identical to before.
  * @returns {Promise<void>}
  */
-async function abortSession(client, sessionId) {
-  await client.session.abort({ path: { id: sessionId } });
+async function abortSession(client, sessionId, directory) {
+  await client.session.abort({ path: { id: sessionId }, ...directoryQuery(directory) });
 }
 
 /**
@@ -325,11 +355,15 @@ async function abortSession(client, sessionId) {
  *
  * @param {import('@opencode-ai/sdk').OpencodeClient} client - SDK client
  * @param {string} sessionId - Session ID
+ * @param {string} [directory] - Optional project directory to scope the call to
+ *   (threaded to the SDK as query.directory). Omitting it keeps the call
+ *   byte-for-byte identical to before.
  * @returns {Promise<Object>} Session status
  */
-async function getSessionStatus(client, sessionId) {
+async function getSessionStatus(client, sessionId, directory) {
   const result = await client.session.status({
-    path: { id: sessionId }
+    path: { id: sessionId },
+    ...directoryQuery(directory)
   });
 
   return result.data || {};

package/src/session-manager.js

@@ -113,6 +113,11 @@ function createSession(projectDir, taskId, metadata) {
 
   // Create empty conversation.jsonl
   fs.writeFileSync(path.join(sessionDir, 'conversation.jsonl'), '', { mode: 0o600 });
+
+  // #40: record the taskId -> project mapping in the global index so a later
+  // lookup that defaults to a DIFFERENT project can still find this session.
+  // Best-effort: recordSession never throws.
+  require('./utils/session-index').recordSession(taskId, metadata.project || projectDir);
 }
 
 /**

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(