amicus 1.6.0 → 1.7.0

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);
 }
@@ -404,6 +405,58 @@ Options for 'read':
   --conversation               Show full conversation
   --metadata                   Show session metadata
   --json                       Emit the run/wave result as stable JSON
+`,
+  continue: `
+Options for 'continue':
+  <task_id>                    Required. Session to build on (positional)
+  --prompt <text>              Required. Briefing for the new session
+  --model <model>              Optional. Override the model (alias or provider/model)
+  --cwd <path>                 Project directory (default: cwd)
+  --no-ui                      Run without GUI (autonomous mode)
+  --timeout <minutes>          Headless timeout (default: 15)
+  --context-turns <N>          Max conversation turns (default: 50)
+  --context-max-tokens <N>     Max context tokens (default: 80000)
+`,
+  resume: `
+Options for 'resume':
+  <task_id>                    Required. Session to reopen (positional)
+  --cwd <path>                 Project directory (default: cwd)
+  --no-ui                      Run without GUI (autonomous mode)
+  --timeout <minutes>          Headless timeout (default: 15)
+`,
+  council: `
+Subcommands for 'council':
+  tally <input.json>           Tally findings → tiers/street-cred (appends to ledger)
+    --no-ledger                Compute the record without appending to the ledger
+    --json                     Machine-readable output
+  stats                        Reviewer-reliability aggregates from the ledger
+    --json                     Machine-readable output
+  report <verdict.json>        Disagreement + verdict report
+    --wave <wave.json>         Include per-leg run stats from a wave file
+    --md                       Emit Markdown (default)
+    --html                     Emit a self-contained HTML page
+`,
+  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':
+  (no args)                    Run the interactive setup wizard
+  --api-keys                   Open the API key setup window
+  --add-alias <name=model>     Add a model alias without the full wizard
+`,
+  key: `
+Usage for 'key':
+  key <provider> <apikey>      Validate and save a key
+  key <provider> --remove      Remove a saved key
+  key                          List all configured providers
+`,
+  mcp: `
+Usage for 'mcp':
+  mcp                          Start the MCP server (stdio transport)
 `
 };
 

package/src/headless.js

@@ -99,6 +99,17 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
   const sessionDir = getSessionDir(project, taskId);
   const conversationPath = path.join(sessionDir, 'conversation.jsonl');
 
+  // #47: scope every per-session SDK call to the project directory so a SHARED
+  // OpenCode server (one server, many projects) files and finds this session
+  // under the right ?directory=. `dirArgs` is the trailing arg list for the
+  // positional client wrappers (createSession/getMessages/getSessionStatus/
+  // abortSession) and is EMPTY when no directory is supplied — so the un-scoped
+  // (owned-server) call shape stays byte-for-byte identical. A scoped create
+  // with un-scoped follow-ups reproduces the identical "session not found"
+  // failure, so ALL of them must carry it.
+  const { directory } = options;
+  const dirArgs = directory === undefined ? [] : [directory];
+
   // Ensure session directory exists
   if (!fs.existsSync(sessionDir)) {
     fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
@@ -204,7 +215,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       logger.debug('Using existing session', { sessionId });
     } else {
       try {
-        sessionId = await createSession(client);
+        sessionId = await createSession(client, ...dirArgs);
       } catch (error) {
         if (watchdog) { watchdog.cancel(); }
         if (!externalServer) { server.close(); }
@@ -242,7 +253,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           markAborted(sessionDir, signal);
           try {
             const { abortSession } = require('./opencode-client');
-            abortSession(client, sessionId).catch(() => {});
+            abortSession(client, sessionId, ...dirArgs).catch(() => {});
           } catch { /* best-effort */ }
           try { server.close(); } catch { /* best-effort */ }
           const { resolveTerminalState } = require('./sidecar/session-finalize');
@@ -272,6 +283,9 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       system: systemPrompt,
       parts: [{ type: 'text', text: userMessage }]
     };
+    // #47: scope the prompt to the project on a shared server. Only set when a
+    // directory was supplied so the owned-server options object is unchanged.
+    if (directory !== undefined) { promptOptions.directory = directory; }
 
     // Default to 'build' in headless mode — 'chat' stalls without user interaction
     const agentConfig = mapAgentToOpenCode(agent || 'build');
@@ -344,7 +358,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             logger.info('External abort signal received', { taskId });
             try {
               const { abortSession } = require('./opencode-client');
-              await abortSession(client, sessionId);
+              await abortSession(client, sessionId, ...dirArgs);
             } catch (abortErr) {
               logger.warn('Failed to abort OpenCode session', { error: abortErr.message });
             }
@@ -360,7 +374,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       try {
         const remaining = deadline - Date.now();
         const messages = await withTimeout(
-          getMessages(client, sessionId),
+          getMessages(client, sessionId, ...dirArgs),
           Math.min(pollCallTimeoutMs, remaining),
           'getMessages'
         );
@@ -420,7 +434,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           try {
             const remainingForStatus = deadline - Date.now();
             const statusData = await withTimeout(
-              getSessionStatus(client, sessionId),
+              getSessionStatus(client, sessionId, ...dirArgs),
               Math.min(pollCallTimeoutMs, remainingForStatus),
               'getSessionStatus'
             );
@@ -509,7 +523,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       // Abort the OpenCode session on timeout (agent keeps running otherwise)
       try {
         const { abortSession } = require('./opencode-client');
-        await abortSession(client, sessionId);
+        await abortSession(client, sessionId, ...dirArgs);
         logger.info('Session aborted after timeout', { taskId, sessionId });
       } catch (abortErr) {
         logger.warn('Failed to abort session after timeout', { error: abortErr.message });
@@ -572,7 +586,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     if (sessionId) {
       try {
         const { abortSession } = require('./opencode-client');
-        await abortSession(client, sessionId);
+        await abortSession(client, sessionId, ...dirArgs);
       } catch {
         // Ignore abort errors during error handling
       }

package/src/mcp-server.js

@@ -11,6 +11,10 @@ const { getSessionDir, SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('./session-
 const { readProgress, isStalled } = require('./sidecar/progress');
 const { SharedServerManager } = require('./utils/shared-server');
 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
@@ -24,15 +28,104 @@ function elapsedMs(metadata) {
   return durationBetween(metadata.createdAt, end) ?? 0;
 }
 
+// Non-complete terminal statuses: a run that ended in one of these failed (or
+// was stopped) and may have no usable summary. amicus_read surfaces
+// metadata.reason for these instead of a bare "No summary available" (#36).
+// 'timed-out' is the canonical single-session value persisted by
+// resolveTerminalState/finalizeHeadlessResult (session-finalize.js); 'timeout'
+// is the wave/leg value from statusFromResult (kept here for defensive
+// coverage); 'idle-timeout' is the shared-server idle-eviction value.
+const FAILED_TERMINAL_STATUSES = ['error', 'crashed', 'timeout', 'timed-out', 'idle-timeout', 'aborted'];
+
 const sharedServer = new SharedServerManager({ logger });
 
-/** Resolve the project directory with smart fallback. */
+/**
+ * Resolve the project directory synchronously.
+ *
+ * Resolution order (the MCP-roots step is async and lives in resolveProjectDir,
+ * which slots between the env override and the cwd fallback here):
+ *   explicit project arg → AMICUS_PROJECT_DIR env → process.cwd() → $HOME.
+ *
+ * A stdio MCP server spawned by a desktop app inherits the APP INSTALL DIR as
+ * cwd, so AMICUS_PROJECT_DIR lets the launcher pin the real project before the
+ * cwd fallback ever fires. The resolved path is canonicalized so it matches
+ * however a later lookup spells the same directory.
+ */
 function getProjectDir(explicitProject) {
-  if (explicitProject && fs.existsSync(explicitProject)) { return explicitProject; }
+  if (explicitProject && fs.existsSync(explicitProject)) {
+    return canonicalProjectPath(explicitProject);
+  }
+  const envProject = process.env.AMICUS_PROJECT_DIR;
+  if (envProject && fs.existsSync(envProject)) {
+    return canonicalProjectPath(envProject);
+  }
   const cwd = process.cwd();
-  if (cwd !== '/' && fs.existsSync(cwd)) { return cwd; }
+  if (cwd !== '/' && fs.existsSync(cwd)) { return canonicalProjectPath(cwd); }
   if (cwd === '/') { logger.warn('cwd is root (/), falling back to $HOME'); }
-  return os.homedir();
+  return canonicalProjectPath(os.homedir());
+}
+
+// Cache the client's roots/list result once per server so concurrent tool
+// calls don't each pay a round-trip. Keyed by the McpServer wrapper so distinct
+// servers (e.g. across tests) don't share state.
+const _rootsCache = new WeakMap();
+
+/**
+ * Fetch the client's first file:// root via a roots/list round-trip, cached.
+ * Returns a canonical path string, or null when roots are unavailable
+ * (no client, no roots capability, empty list, non-file roots, or an error).
+ * @param {object} mcpServer - the McpServer wrapper exposing `.server`.
+ * @returns {Promise<string|null>}
+ */
+async function getClientRoot(mcpServer) {
+  const core = mcpServer && mcpServer.server;
+  if (!core || typeof core.listRoots !== 'function') { return null; }
+  if (_rootsCache.has(mcpServer)) { return _rootsCache.get(mcpServer); }
+
+  let resolved = null;
+  try {
+    const caps = typeof core.getClientCapabilities === 'function'
+      ? core.getClientCapabilities() : undefined;
+    if (caps && caps.roots) {
+      const { roots } = await core.listRoots();
+      const fileRoot = Array.isArray(roots)
+        ? roots.find((r) => r && typeof r.uri === 'string' && r.uri.startsWith('file:'))
+        : null;
+      if (fileRoot) {
+        const p = fileURLToPath(fileRoot.uri);
+        if (fs.existsSync(p)) { resolved = canonicalProjectPath(p); }
+      }
+    }
+  } catch (err) {
+    logger.warn('roots/list failed, falling back to cwd', { error: err.message });
+  }
+  _rootsCache.set(mcpServer, resolved);
+  return resolved;
+}
+
+/**
+ * Resolve the project directory, consulting the MCP client's roots when no
+ * explicit project / env override is given.
+ *
+ * Order: explicit project arg → AMICUS_PROJECT_DIR env → client first file://
+ * root → process.cwd() → $HOME. All branches are canonicalized.
+ * @param {string|undefined} explicitProject
+ * @param {object} [mcpServer] - the McpServer wrapper (for the roots round-trip).
+ * @returns {Promise<string>}
+ */
+async function resolveProjectDir(explicitProject, mcpServer) {
+  if (explicitProject && fs.existsSync(explicitProject)) {
+    return canonicalProjectPath(explicitProject);
+  }
+  const envProject = process.env.AMICUS_PROJECT_DIR;
+  if (envProject && fs.existsSync(envProject)) {
+    return canonicalProjectPath(envProject);
+  }
+  if (mcpServer) {
+    const root = await getClientRoot(mcpServer);
+    if (root) { return root; }
+  }
+  return getProjectDir(undefined);
 }
 
 /** Read session metadata from disk, or null if not found */
@@ -50,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 }}
@@ -140,10 +244,16 @@ const handlers = {
         const { finalizeHeadlessResult } = require('./sidecar/session-finalize');
         // resolvedModel is already available from validateStartInputs() above
 
-        sessionId = await createSession(client);
+        // #47: the shared OpenCode server is shared across projects, so the
+        // session must be created scoped to the resolved project directory
+        // (cwd, already canonicalized by getProjectDir/#39) — otherwise it is
+        // found by id but NOT by a ?directory= query. runHeadless then scopes
+        // every follow-up call to the SAME directory (passed via options.directory).
+        sessionId = await createSession(client, cwd);
 
         // Write initial metadata (MCP handler owns this, runHeadless skips it)
         fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+        recordSession(taskId, cwd); // #40: global index for cross-project lookup
         const metaPath = path.join(sessionDir, 'metadata.json');
         const serverPort = server.url ? new URL(server.url).port : null;
         fs.writeFileSync(metaPath, JSON.stringify({
@@ -195,6 +305,7 @@ const handlers = {
         runHeadless(resolvedModel, systemPrompt, userMessage, taskId, cwd,
           timeoutMs, agent, {
             client, server, watchdog, sessionId,
+            directory: cwd, // #47: scope every per-session follow-up call to the project
             mcp: undefined, // shared server already has MCP config
           }
         ).then((result) => {
@@ -246,6 +357,7 @@ const handlers = {
 
     if (child && child.pid) {
       fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+      recordSession(taskId, cwd); // #40: global index for cross-project lookup
       const metaPath = path.join(sessionDir, 'metadata.json');
       if (!fs.existsSync(metaPath)) {
         fs.writeFileSync(metaPath, JSON.stringify({
@@ -329,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) {
@@ -355,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; }
 
@@ -379,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) {
@@ -423,21 +539,25 @@ const handlers = {
     }
     // Default: summary
     const summaryPath = path.join(sessionDir, 'summary.md');
-    if (!fs.existsSync(summaryPath)) {
-      return textResult('No summary available (session may still be running or was not folded).');
-    }
     const metaForRead = (() => {
       try { return JSON.parse(fs.readFileSync(path.join(sessionDir, 'metadata.json'), 'utf-8')); }
       catch { return {}; }
     })();
-    const summaryText = fs.readFileSync(summaryPath, 'utf-8');
+    const summaryText = fs.existsSync(summaryPath)
+      ? fs.readFileSync(summaryPath, 'utf-8')
+      : '';
     const header = metaForRead.model ? `**Model:** ${metaForRead.model}\n\n` : '';
-    // A failed shared-server run writes an EXISTING 0-byte summary.md (so we hit
-    // this file-exists branch, not "No summary available"). Surface the failure
-    // reason instead of returning an empty/uninformative body (#36).
-    if ((metaForRead.status === 'error' || metaForRead.status === 'crashed') && !summaryText.trim()) {
+    // A run that ended in a failed terminal status may have no usable summary:
+    // a crashed/timed-out run never writes summary.md, and a fast-failed
+    // shared-server run writes an EXISTING 0-byte summary.md. In both cases
+    // surface metadata.reason instead of a bare "No summary available" or an
+    // empty body (#36). Complete/partial-summary runs are unaffected.
+    if (FAILED_TERMINAL_STATUSES.includes(metaForRead.status) && !summaryText.trim()) {
       const reason = metaForRead.reason || 'Unknown error';
-      return textResult(`${header}**Status:** ${metaForRead.status}\n**Reason:** ${reason}\n\n(No summary — the session ended with an error.)`);
+      return textResult(`${header}**Status:** ${metaForRead.status}\n**Reason:** ${reason}\n\n(No summary — the session ended in status '${metaForRead.status}'.)`);
+    }
+    if (!summaryText.trim()) {
+      return textResult('No summary available (session may still be running or was not folded).');
     }
     return textResult(header + summaryText);
   },
@@ -521,6 +641,7 @@ const handlers = {
     try { spawnSidecarProcess(args, sessionDir); } catch (err) {
       return textResult(`Failed to continue: ${err.message}`, true);
     }
+    recordSession(newTaskId, cwd); // #40: global index for cross-project lookup
     return textResult(JSON.stringify({
       taskId: newTaskId, status: 'running',
       message: 'Continuation started. Use amicus_status to check progress.',
@@ -530,7 +651,10 @@ const handlers = {
   async amicus_abort(input, project) {
     const cwd = project || getProjectDir(input.project);
     const metadata = readMetadata(input.taskId, cwd);
-    if (!metadata) { return textResult(`Session ${input.taskId} not found.`, true); }
+    if (!metadata) {
+      return textResult(`Session ${input.taskId} not found in project ${cwd}. ` +
+        'If you ran it in a different project, pass the original "project".', true);
+    }
     if (metadata.status !== 'running') {
       return textResult(`Session ${input.taskId} is not running (status: ${metadata.status}).`);
     }
@@ -602,6 +726,10 @@ const handlers = {
         taskId: waveId, type: 'wave', status: 'running', legs: legIds,
         models: effectiveModels, headless: true, createdAt: new Date().toISOString(),
       }, null, 2), { mode: 0o600 });
+      // #40: index the wave AND each leg so status/read of any leg resolves the
+      // project even when the default later defaults to a different one.
+      recordSession(waveId, cwd);
+      for (const legId of legIds) { recordSession(legId, cwd); }
     } catch (err) {
       return textResult(`Failed to prepare fan-out wave: ${err.message}`, true);
     }
@@ -617,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'
@@ -697,14 +829,22 @@ const LEGACY_TOOL_ALIASES = {
 async function startMcpServer() {
   const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
   const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-  const server = new McpServer({ name: 'amicus', version: require('../package.json').version });
+  const server = new McpServer(
+    { name: 'amicus', version: require('../package.json').version },
+    // Declare the `roots` capability so the client advertises its roots and we
+    // can request them (roots/list) when no explicit project is supplied.
+    { capabilities: { roots: {} } }
+  );
 
   for (const tool of getTools()) {
     const register = (name) => server.registerTool(
       name,
       { description: tool.description, inputSchema: tool.inputSchema, annotations: tool.annotations },
       async (input) => {
-        try { return await handlers[tool.name](input, getProjectDir(input.project)); }
+        try {
+          const project = await resolveProjectDir(input.project, server);
+          return await handlers[tool.name](input, project);
+        }
         catch (err) {
           logger.error(`MCP tool error: ${name}`, { error: err.message });
           return textResult(`Error: ${err.message}`, true);
@@ -727,4 +867,7 @@ async function startMcpServer() {
   process.stderr.write('[amicus] MCP server running on stdio\n');
 }
 
-module.exports = { handlers, startMcpServer, getProjectDir, LEGACY_TOOL_ALIASES };
+module.exports = {
+  handlers, startMcpServer, getProjectDir, resolveProjectDir, getClientRoot,
+  LEGACY_TOOL_ALIASES,
+};