amicus 1.6.0 → 1.6.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": { "name": "Christian Wagner" },
   "homepage": "https://bourbondog.github.io/amicus/",

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-06-30
+
+Project-directory and session-addressing correctness — agents, sessions, and the interactive GUI now agree on which project they're in.
+
+### Added
+- **`AMICUS_PROJECT_DIR` + MCP `roots` support.** When the project is not passed explicitly, the MCP
+  server now resolves the working directory from the client's first `file://` workspace root (falling
+  back to `AMICUS_PROJECT_DIR`, then the process cwd) — so a stdio MCP server spawned by a desktop
+  client no longer roots agents in the app install directory where they can't see your files.
+- **Global session index.** `amicus_status` / `amicus_read` / `amicus_list` now consult a global
+  `taskId -> project` index on a per-project miss, so a session created in one project is still found
+  when looked up from another.
+- **Per-command help for the rest of the CLI.** `amicus council --help` (and `continue`, `resume`,
+  `doctor`, `setup`, `key`, `mcp`) now print their own scoped usage instead of the full global help.
+
+### Fixed
+- **Interactive `--cwd`: follow-up prompts no longer fail "unable to retrieve session."** When the
+  launch directory differs from `--cwd` (the normal sidecar-skill pattern), the OpenCode session is now
+  scoped to the project directory and the Electron Web-UI route is built from the **server-echoed**
+  session directory rather than a guessed one, so turn 2+ resolve correctly.
+- **Shared-server MCP sessions are scoped to the project directory** — every create and follow-up call
+  carries the directory, so headless MCP sessions are found on a server shared across projects.
+- **`amicus_read` surfaces the failure reason** for crashed / timed-out / aborted runs that wrote no
+  summary, instead of a bare "No summary available."
+- **`amicus_abort`'s "session not found"** now names the resolved project, matching `status` / `read`.
+- Internal: a single `canonicalProjectPath()` now normalizes project paths (slash direction, drive-letter
+  case, trailing slash, UNC shares) so creation and lookup always agree.
+
 ## [1.6.0] - 2026-06-30
 
 Install resilience and council-failure correctness — the first two blocks of the post-1.5 backlog program.

package/electron/main.js

@@ -21,6 +21,7 @@ const { createFoldHandler } = require('./fold');
 const { registerSetupHandlers } = require('./ipc-setup');
 const { computeWindowPosition } = require('./window-position');
 const { attachLoadFailsafe, buildLoadErrorHTML } = require('./load-failsafe');
+const { buildSessionRoute } = require('./session-route');
 
 const ICON_PATH = path.join(__dirname, 'assets', 'icon.png');
 
@@ -51,6 +52,11 @@ const MODE = getCompatEnv('MODE') || 'sidecar';
 const TASK_ID = getCompatEnv('TASK_ID') || 'unknown';
 const MODEL = getCompatEnv('MODEL') || 'unknown';
 const CWD = getCompatEnv('CWD') || process.cwd();
+// The directory the OpenCode session was actually scoped to (#45). Set by the
+// interactive launcher as canonicalProjectPath(--cwd) so the Web-UI route is
+// built from the SAME directory createSession used. Falls back to CWD for
+// back-compat with launchers that predate this env var.
+const SESSION_DIRECTORY = getCompatEnv('SESSION_DIRECTORY') || CWD;
 const CLIENT = getCompatEnv('CLIENT') || 'code-local';
 const OPENCODE_PORT = parseInt(getCompatEnv('OPENCODE_PORT') || '4096', 10);
 const OPENCODE_SESSION_ID = getCompatEnv('SESSION_ID');
@@ -152,10 +158,10 @@ function createAmicusWindow() {
   });
 
   // Navigate directly to the session URL to bypass the project selection screen.
-  // OpenCode's router format: /<base64url(projectPath)>/session/<sessionId>
-  const contentUrl = OPENCODE_SESSION_ID
-    ? `${OPENCODE_URL}/${Buffer.from(CWD).toString('base64url')}/session/${OPENCODE_SESSION_ID}`
-    : OPENCODE_URL;
+  // Build the route from SESSION_DIRECTORY — the directory the session was
+  // actually scoped to — NOT a fresh base64url(CWD) guess, so Web-UI follow-up
+  // prompts resolve the session even when process cwd != --cwd (#45).
+  const contentUrl = buildSessionRoute(OPENCODE_URL, OPENCODE_SESSION_ID, SESSION_DIRECTORY);
 
   // The window only becomes visible on the success path below. Without this
   // failsafe, a failed/stalled UI load leaves an invisible window and a

package/electron/session-route.js

@@ -0,0 +1,28 @@
+/**
+ * Web-UI session route builder (#45).
+ *
+ * OpenCode's router format is `/<base64url(projectPath)>/session/<sessionId>`.
+ * The route MUST be built from the directory the OpenCode session was actually
+ * created/scoped to — NOT a fresh base64url(process.cwd()) guess. When the
+ * amicus process cwd != --cwd (the normal sidecar-skill launch), a CWD-derived
+ * route points at a project route with no matching session, so Web-UI follow-up
+ * prompts fail "unable to retrieve session". The caller passes the same
+ * directory it used to scope createSession (the server-echoed session.directory,
+ * or a consistent canonicalProjectPath(--cwd) fallback).
+ *
+ * Pure function: no electron, no fs, no process state. Safe to unit-test.
+ *
+ * @param {string} baseUrl - OpenCode server base URL (e.g. http://localhost:4096)
+ * @param {string} [sessionId] - OpenCode session id; falsy → return baseUrl only
+ * @param {string} sessionDirectory - The directory the session is scoped to
+ * @returns {string} Fully-qualified route URL, or baseUrl when no session id.
+ */
+function buildSessionRoute(baseUrl, sessionId, sessionDirectory) {
+  if (!sessionId) {
+    return baseUrl;
+  }
+  const seg = Buffer.from(sessionDirectory).toString('base64url');
+  return `${baseUrl}/${seg}/session/${sessionId}`;
+}
+
+module.exports = { buildSessionRoute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -404,6 +404,56 @@ 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
+`,
+  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,9 @@ 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');
 
 /**
  * Elapsed run duration: time between createdAt and the run's end, bounding the
@@ -24,15 +27,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 */
@@ -140,10 +232,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 +293,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 +345,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({
@@ -423,21 +523,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 +625,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 +635,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 +710,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);
     }
@@ -697,14 +809,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 +847,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,
+};

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/interactive.js

@@ -13,6 +13,7 @@ const { logger } = require('../utils/logger');
 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).
@@ -32,7 +33,7 @@ function checkElectronAvailable() {
 
 /** Build environment variables for Electron process */
 function buildElectronEnv(taskId, model, project, nodeModulesBin, existingPath, options = {}) {
-  const { agent, isResume, conversation, mcp, client, windowPosition } = options;
+  const { agent, isResume, conversation, mcp, client, windowPosition, sessionDirectory } = options;
   const env = {
     ...process.env,
     PATH: `${nodeModulesBin}${path.delimiter}${existingPath}`,
@@ -43,6 +44,10 @@ function buildElectronEnv(taskId, model, project, nodeModulesBin, existingPath,
 
   if (client) { env.AMICUS_CLIENT = client; }
   if (windowPosition) { env.AMICUS_WINDOW_POSITION = windowPosition; }
+  // The directory the OpenCode session is scoped to (#45). Electron builds the
+  // Web-UI route from THIS, not a fresh base64url(CWD) guess, so follow-up
+  // prompts resolve the session when process cwd != --cwd.
+  if (sessionDirectory) { env.AMICUS_SESSION_DIRECTORY = sessionDirectory; }
 
   if (agent) {
     const agentConfig = mapAgentToOpenCode(agent);
@@ -100,6 +105,14 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
 
   const { agent, isResume, conversation, mcp, reasoning, opencodeSessionId, client } = options;
 
+  // Scope the OpenCode session to the project/--cwd (#45). The SDK Session
+  // object echoes a `directory`, but createSession() returns only the id, so we
+  // use the canonicalized --cwd CONSISTENTLY for BOTH the create scope and the
+  // Web-UI route — the documented fallback that keeps them matching even when
+  // the amicus process cwd != --cwd. undefined when project is falsy → calls
+  // stay byte-for-byte identical to before.
+  const sessionDirectory = canonicalProjectPath(project);
+
   // Start OpenCode server with system prompt baked into agent config.
   // Agent config prompts are hidden from the UI, unlike promptAsync's system field.
   const agentConfig = mapAgentToOpenCode(agent);
@@ -126,14 +139,15 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
       sessionId = opencodeSessionId;
       logger.info('Reconnecting to existing session', { sessionId });
     } else {
-      // New session: create and send initial prompt
-      sessionId = await createSession(ocClient);
+      // New session: create and send initial prompt, scoped to --cwd (#45).
+      sessionId = await createSession(ocClient, sessionDirectory);
 
       // System prompt is set on agent config (hidden from UI).
       // Do NOT pass system here — promptAsync's system field is visible in the UI.
       const promptOptions = {
         model,
-        parts: [{ type: 'text', text: userMessage }]
+        parts: [{ type: 'text', text: userMessage }],
+        directory: sessionDirectory
       };
 
       // Always set agent — defaults to 'chat' when not specified
@@ -171,13 +185,13 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
   // Keep the idle clock from killing an actively-working session: poll OpenCode
   // session status and touch the watchdog on any non-idle (busy/retry) state.
   const activityPoller = createActivityPoller({
-    getStatus: () => getSessionStatus(ocClient, sessionId),
+    getStatus: () => getSessionStatus(ocClient, sessionId, sessionDirectory),
     onActivity: () => watchdog.touch(),
   });
 
   const sessionDir = getSessionDir(project, taskId);
   const mirror = startInteractiveMirror({
-    getMessages: () => getMessages(ocClient, sessionId),
+    getMessages: () => getMessages(ocClient, sessionId, sessionDirectory),
     sessionDir,
     onActivity: () => watchdog.touch(),
   });
@@ -190,7 +204,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     const existingPath = process.env.PATH || '';
     const env = buildElectronEnv(
       taskId, model, project, nodeModulesBin, existingPath,
-      { agent, isResume, conversation, mcp, client }
+      { agent, isResume, conversation, mcp, client, sessionDirectory }
     );
     env.AMICUS_OPENCODE_PORT = serverPort;
     env.AMICUS_SESSION_ID = sessionId;

package/src/utils/project-path.js

@@ -0,0 +1,61 @@
+/**
+ * Canonical project-path helper.
+ *
+ * A project/cwd path can be written many incidental ways that all refer to the
+ * SAME logical directory. If a path used to CREATE a session differs (by any of
+ * these) from the path used to LOOK IT UP or build a route, the two won't match
+ * and the session/route is lost. This module collapses those incidental
+ * differences to ONE canonical string.
+ *
+ * Canonical form (documented contract):
+ *   - forward slashes ('/'), never backslashes
+ *   - duplicate/mixed separators collapsed to a single '/'
+ *   - a leading UNC double-slash is preserved ('\\\\server\\share' -> '//server/share')
+ *     so a network share never collapses into (and collides with) a local path
+ *   - Windows drive letter upper-cased (c: -> C:)
+ *   - no trailing slash, EXCEPT a bare root is preserved ('C:/' and '/')
+ *
+ * Pure function: no fs, no network, no process state. Safe to call anywhere.
+ */
+
+/**
+ * Normalize a project/cwd path to its canonical string form.
+ *
+ * @param {string} p - A filesystem path (Windows or POSIX style).
+ * @returns {string} The canonical path, or the input unchanged when falsy.
+ */
+function canonicalProjectPath(p) {
+  // Preserve falsy input (''/undefined/null) so callers can pass through an
+  // absent directory without special-casing.
+  if (!p) {
+    return p;
+  }
+
+  // 1. Backslashes -> forward slashes.
+  let out = p.replace(/\\/g, '/');
+  // A leading UNC double-slash (\\server\share) must survive the separator
+  // collapse below — flattening it to a single '/' would turn a network share
+  // into a local-looking path that could collide with one. Remember it, collapse
+  // duplicate/mixed separators, then restore the UNC prefix.
+  const isUnc = out.startsWith('//');
+  out = out.replace(/\/+/g, '/');
+  if (isUnc) {
+    out = `/${out}`;
+  }
+
+  // 2. Upper-case a leading Windows drive letter (c: -> C:).
+  out = out.replace(/^([a-z]):/, (_m, d) => `${d.toUpperCase()}:`);
+
+  // 3. Strip a trailing slash, but keep a bare root ('C:/' or '/').
+  if (out.length > 1 && out.endsWith('/')) {
+    const withoutSlash = out.slice(0, -1);
+    // 'C:/' -> withoutSlash is 'C:' (a bare drive); keep the root slash.
+    if (!/^[A-Z]:$/.test(withoutSlash)) {
+      out = withoutSlash;
+    }
+  }
+
+  return out;
+}
+
+module.exports = { canonicalProjectPath };

package/src/utils/session-index.js

@@ -0,0 +1,98 @@
+/**
+ * Global session index (issue #40).
+ *
+ * The on-disk session store is PROJECT-scoped:
+ *   <project>/.claude/amicus_sessions/<taskId>/
+ * but the project a lookup resolves to can differ from the one a session was
+ * created under (a stdio MCP server defaults to its install-dir cwd, MCP roots
+ * may be absent, etc.). When that happens a perfectly valid session reads back
+ * as "not found".
+ *
+ * This module maintains ONE global index, under the config dir, mapping
+ *   taskId -> canonicalProjectPath(project)
+ * written at session START and consulted ONLY on a per-project miss. It is a
+ * navigation aid, never authoritative: a corrupt/partial index must NEVER crash
+ * a lookup, so every read is guarded and degrades to "no entry".
+ *
+ * Concurrency: parallel fan-out/council runs write here at once. Writes are
+ * atomic via write-temp + rename (rename is atomic on a single filesystem), and
+ * a unique temp name per write avoids two writers colliding on the temp file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { getConfigDir } = require('./config');
+const { canonicalProjectPath } = require('./project-path');
+
+/** Index filename under the config dir. */
+const INDEX_FILENAME = 'sessions-index.json';
+
+/** @returns {string} Absolute path to the index file. */
+function indexPath() {
+  return path.join(getConfigDir(), INDEX_FILENAME);
+}
+
+/**
+ * Read the index, returning a plain object. Never throws: a missing,
+ * unreadable, or corrupt file yields an empty map.
+ * @returns {Record<string, string>}
+ */
+function readIndex() {
+  try {
+    const raw = fs.readFileSync(indexPath(), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // Missing / unreadable / corrupt — fall through to a fresh map.
+  }
+  return {};
+}
+
+/**
+ * Record taskId -> canonical project path at session START.
+ *
+ * Best-effort and crash-safe: a failure here must never block starting a
+ * session, and a pre-existing corrupt index is recovered to a fresh map rather
+ * than propagated. The write is atomic (temp file + rename).
+ *
+ * @param {string} taskId
+ * @param {string} project - any spelling of the project dir; canonicalized here.
+ */
+function recordSession(taskId, project) {
+  if (!taskId || !project) { return; }
+  const canonical = canonicalProjectPath(project);
+  try {
+    const dir = getConfigDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const index = readIndex(); // already guarded; corrupt -> {}
+    index[taskId] = canonical;
+    const target = path.join(dir, INDEX_FILENAME);
+    // Unique temp name so concurrent writers never clobber the same temp file.
+    const tmp = path.join(dir, `.${INDEX_FILENAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(index, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, target); // atomic on a single filesystem
+  } catch {
+    // Index is a navigation aid; never let its failure break a session start.
+  }
+}
+
+/**
+ * Look up the canonical project path a taskId was created under.
+ * @param {string} taskId
+ * @returns {string|null} canonical project path, or null if unknown.
+ */
+function lookupSessionProject(taskId) {
+  if (!taskId) { return null; }
+  const index = readIndex(); // guarded; never throws
+  const project = index[taskId];
+  return (typeof project === 'string' && project) ? project : null;
+}
+
+module.exports = {
+  INDEX_FILENAME,
+  recordSession,
+  lookupSessionProject,
+};

package/src/utils/session-path.js

@@ -0,0 +1,68 @@
+/**
+ * Session path resolution.
+ *
+ * Resolves the on-disk directory for a session taskId under a project, with the
+ * path-traversal guard, the legacy sidecar_sessions shim, and (issue #40) a
+ * cross-project fallback via the global session index when the session is not
+ * found under the project this lookup defaulted to.
+ *
+ * Extracted from validators.js to keep that module under the size gate.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('../session-manager');
+const { lookupSessionProject } = require('./session-index');
+const { canonicalProjectPath } = require('./project-path');
+
+/** Resolve a session path under a single root, throwing on path traversal. */
+function safeSessionDirUnder(project, root, taskId) {
+  // Resolve so both sides share the same drive/separator form; on Windows path.join
+  // yields a driveless root (\tmp\...) while path.resolve(taskId) adds the drive.
+  const sessionsDir = path.resolve(path.join(project, '.claude', root));
+  const resolved = path.resolve(sessionsDir, taskId);
+  if (!resolved.startsWith(sessionsDir + path.sep)) {
+    throw new Error('Invalid task ID: path traversal detected');
+  }
+  return resolved;
+}
+
+/** Probe both roots (canonical, then legacy) under one project; null if neither exists. */
+function existingDirUnderProject(project, taskId) {
+  const canonical = safeSessionDirUnder(project, SESSIONS_DIR, taskId);
+  if (fs.existsSync(canonical)) { return canonical; }
+  const legacy = safeSessionDirUnder(project, LEGACY_SESSIONS_DIR, taskId);
+  if (fs.existsSync(legacy)) { return legacy; }
+  return null;
+}
+
+/**
+ * Resolve an EXISTING session path: prefer canonical amicus, fall back to the
+ * legacy sidecar_sessions dir (shim). The traversal guard runs against BOTH
+ * roots, so a malicious taskId is rejected regardless of root.
+ *
+ * On a per-project MISS (#40), consult the global index for the project the
+ * taskId was actually recorded under and probe there — so a session created
+ * under project A is still found when the lookup defaulted to project B. The
+ * index read is guarded (corrupt index → null), the indexed project is
+ * re-validated through the same traversal guard, and an index hit is only
+ * returned when the dir actually exists; otherwise fall back to the canonical
+ * (writeable) path under the given project.
+ *
+ * @throws {Error} If resolved path escapes the sessions directory
+ */
+function safeSessionDir(project, taskId) {
+  const local = existingDirUnderProject(project, taskId);
+  if (local) { return local; }
+
+  const indexedProject = lookupSessionProject(taskId);
+  if (indexedProject && canonicalProjectPath(indexedProject) !== canonicalProjectPath(project)) {
+    const indexed = existingDirUnderProject(indexedProject, taskId);
+    if (indexed) { return indexed; }
+  }
+
+  // Default to the canonical (writeable) path under the given project.
+  return safeSessionDirUnder(project, SESSIONS_DIR, taskId);
+}
+
+module.exports = { safeSessionDir, safeSessionDirUnder };

package/src/utils/validators.js

@@ -45,33 +45,9 @@ function validateTaskId(taskId) {
   return { valid: true };
 }
 
-const { SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('../session-manager');
-
-/** Resolve a session path under a single root, throwing on path traversal. */
-function safeSessionDirUnder(project, root, taskId) {
-  // Resolve so both sides share the same drive/separator form; on Windows path.join
-  // yields a driveless root (\tmp\...) while path.resolve(taskId) adds the drive.
-  const sessionsDir = path.resolve(path.join(project, '.claude', root));
-  const resolved = path.resolve(sessionsDir, taskId);
-  if (!resolved.startsWith(sessionsDir + path.sep)) {
-    throw new Error('Invalid task ID: path traversal detected');
-  }
-  return resolved;
-}
-
-/**
- * Resolve an EXISTING session path: prefer canonical amicus, fall back to the
- * legacy sidecar_sessions dir (shim). The traversal guard runs against BOTH
- * roots, so a malicious taskId is rejected regardless of root.
- * @throws {Error} If resolved path escapes the sessions directory
- */
-function safeSessionDir(project, taskId) {
-  const canonical = safeSessionDirUnder(project, SESSIONS_DIR, taskId);
-  if (fs.existsSync(canonical)) { return canonical; }
-  const legacy = safeSessionDirUnder(project, LEGACY_SESSIONS_DIR, taskId);
-  if (fs.existsSync(legacy)) { return legacy; }
-  return canonical;
-}
+// Session path resolution (incl. #40 cross-project index fallback) lives in its
+// own module to keep this file under the size gate; re-exported below.
+const { safeSessionDir } = require('./session-path');
 
 /**
  * Validate prompt content is not empty or whitespace-only