amicus 1.5.1 → 1.6.1

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');
@@ -289,7 +303,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       agent: promptOptions.agent,
       userMessageLength: userMessage.length
     });
-    await sendPromptAsync(client, sessionId, promptOptions);
+    const promptResult = await sendPromptAsync(client, sessionId, promptOptions);
     writeProgress(sessionDir, 'prompt_sent');
     logger.info('Prompt sent successfully, entering polling loop', {
       sessionId,
@@ -302,6 +316,16 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     let aborted = false;
     let sessionError = null; // Captures model/SDK errors from assistant messages
 
+    // Hard provider failure detected at the client boundary (#37): a non-2xx /
+    // 402 from promptAsync surfaces here even when the server never emits an
+    // assistant message carrying info.error. Seed sessionError so the loop's
+    // "error with no output" gate ends the run promptly with a usable reason.
+    const boundaryProviderError = !!(promptResult && promptResult.providerError);
+    if (boundaryProviderError) {
+      sessionError = promptResult.providerError;
+      logger.error('Provider error at client boundary', { taskId, sessionId, reason: sessionError });
+    }
+
     // Poll for completion by checking messages
     const startTime = Date.now();
     const deadline = startTime + timeoutMs;
@@ -334,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 });
             }
@@ -350,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'
         );
@@ -383,6 +407,17 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           break;
         }
 
+        // Hard provider failure at the client boundary (#37): the request was
+        // rejected (e.g., 402) so no assistant message will ever arrive. Exit as
+        // soon as we confirm nothing streamed — don't wait for assistantFinished
+        // (which never flips here) or the full timeout.
+        if (boundaryProviderError && !mirror.output) {
+          logger.error('Provider error at boundary with no output, exiting', {
+            sessionError, pollCount
+          });
+          break;
+        }
+
         // If the model returned an error with no output, exit immediately
         // (don't wait for timeout — the model won't produce anything)
         if (sessionError && !mirror.output && assistantFinished) {
@@ -399,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'
             );
@@ -488,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 });
@@ -551,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

@@ -10,16 +10,121 @@ const { safeSessionDir } = require('./utils/validators');
 const { getSessionDir, SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('./session-manager');
 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
+ * end by completedAt/abortedAt/crashedAt so a delayed poll of a finished run
+ * reports the run duration, not time-since-start. Falls back to now() while
+ * still running. Returns 0 if createdAt is missing/malformed.
+ */
+function elapsedMs(metadata) {
+  const end = metadata.completedAt || metadata.abortedAt || metadata.crashedAt
+    || new Date().toISOString();
+  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 */
@@ -124,13 +229,19 @@ const handlers = {
         const { buildContext } = require('./sidecar/context-builder');
         const { buildPrompts } = require('./prompt-builder');
         const { runHeadless } = require('./headless');
-        const { finalizeSession } = require('./sidecar/session-utils');
+        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({
@@ -182,13 +293,16 @@ 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) => {
-          // Session complete - finalize and remove from tracking
+          // Session done — route through resolveTerminalState (same single source
+          // of truth as the CLI start.js path) so an errored/timed-out/aborted run
+          // can never silently default to 'complete' with a 0-byte summary (#36).
           try {
             const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-            finalizeSession(sessionDir, result.summary || '', cwd, meta);
+            finalizeHeadlessResult(sessionDir, result, cwd, meta);
           } catch (finErr) {
             logger.warn('Failed to finalize session', { error: finErr.message });
           }
@@ -231,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({
@@ -259,7 +374,10 @@ const handlers = {
     const cwd = project || getProjectDir(input.project);
     const sessionDir = safeSessionDir(cwd, input.taskId);
     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.type === 'wave') {
       const legs = (metadata.legs || []).map((legId) => {
@@ -306,7 +424,7 @@ const handlers = {
         }
       }
 
-      const ms = Date.now() - new Date(metadata.createdAt).getTime();
+      const ms = elapsedMs(metadata);
       const response = {
         taskId: metadata.taskId, type: 'wave', status: metadata.status,
         legsComplete: done, legsTotal: legs.length, legs,
@@ -333,7 +451,7 @@ const handlers = {
       }
     }
 
-    const ms = Date.now() - new Date(metadata.createdAt).getTime();
+    const ms = elapsedMs(metadata);
     const response = {
       taskId: metadata.taskId, status: metadata.status,
       elapsed: `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`,
@@ -372,7 +490,8 @@ const handlers = {
     const cwd = project || getProjectDir(input.project);
     const sessionDir = safeSessionDir(cwd, input.taskId);
     if (!fs.existsSync(sessionDir)) {
-      return textResult(`Session ${input.taskId} not found.`, true);
+      return textResult(`Session ${input.taskId} not found in project ${cwd}. ` +
+        'If you ran it in a different project, pass the original "project".', true);
     }
 
     const readMeta = (() => {
@@ -404,15 +523,26 @@ 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 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 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);
   },
 
@@ -495,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.',
@@ -504,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}).`);
     }
@@ -576,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);
     }
@@ -636,6 +774,15 @@ const handlers = {
   },
 
   async amicus_setup() {
+    const { checkElectronAvailable } = require('./sidecar/interactive');
+    if (!checkElectronAvailable()) {
+      return textResult(
+        'The setup GUI cannot open because Electron is not installed, so no '
+        + 'window appeared. Run `amicus setup` in your terminal instead — it '
+        + 'falls back to a headless (readline) wizard for API key configuration.',
+        true
+      );
+    }
     try { spawnSidecarProcess(['setup']); } catch (err) {
       return textResult(`Failed to launch setup: ${err.message}`, true);
     }
@@ -662,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);
@@ -692,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

@@ -27,6 +27,40 @@ async function getCreateOpencodeServer() {
   return sdk.createOpencodeServer;
 }
 
+/**
+ * Shared reason string for an HTTP 402 from the provider.
+ * Exported so #36 and a later pre-flight credit check can reuse the exact phrasing
+ * instead of re-deriving it.
+ */
+const INSUFFICIENT_CREDITS_REASON = 'Insufficient credits';
+
+/**
+ * Map an SDK request result to a propagated provider-failure reason.
+ *
+ * Keys on the actual HTTP status (result.response.status, falling back to
+ * result.error.status) so benign informational `error` payloads that ride on a
+ * 2xx response stay "continue to poll" — only a real non-2xx status becomes a
+ * session error.
+ *
+ *   402            -> 'Insufficient credits'
+ *   other non-2xx  -> 'Provider error: <status>'
+ *   2xx / unknown  -> null
+ *
+ * @param {{response?: {status?: number}, error?: {status?: number}}} [result]
+ * @returns {string|null} Reason string, or null when there is no hard failure.
+ */
+function providerErrorReason(result) {
+  if (!result) { return null; }
+  const status = (result.response && result.response.status)
+    || (result.error && result.error.status);
+  // No usable status — cannot distinguish a benign warning from a failure, so
+  // do not regress the "continue to poll" behavior.
+  if (typeof status !== 'number') { return null; }
+  if (status >= 200 && status < 300) { return null; }
+  if (status === 402) { return INSUFFICIENT_CREDITS_REASON; }
+  return `Provider error: ${status}`;
+}
+
 /**
  * Parse a model string into SDK format
  *
@@ -73,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');
@@ -111,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);
@@ -151,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) {
@@ -159,11 +216,25 @@ async function sendPrompt(client, sessionId, options) {
     }
   }
 
-  // Log but don't throw on promptAsync errors.
-  // promptAsync is fire-and-forget: the server queues the prompt for async
-  // processing. Errors here may be informational (e.g., model config warnings)
-  // rather than fatal. The polling loop will detect real failures via timeout.
-  if (result.error) {
+  // Detect a hard provider failure at the client boundary (#37). A non-2xx /
+  // 402 here must surface as a session error EVEN WHEN the server emits no
+  // assistant message carrying info.error — otherwise the run looks idle/empty.
+  // Keyed on HTTP status so benign informational errors (model config warnings
+  // on a 2xx) keep the fire-and-forget "continue to poll" behavior below.
+  const reason = providerErrorReason(result);
+  if (reason) {
+    result.providerError = reason;
+    const { logger } = require('./utils/logger');
+    logger.error('promptAsync returned a hard provider error', {
+      reason,
+      status: (result.response && result.response.status) || (result.error && result.error.status),
+      sessionId
+    });
+  } else if (result.error) {
+    // Log but don't throw on benign promptAsync errors.
+    // promptAsync is fire-and-forget: the server queues the prompt for async
+    // processing. These errors are informational (e.g., model config warnings)
+    // rather than fatal. The polling loop will detect real failures via timeout.
     const { logger } = require('./utils/logger');
     logger.error('promptAsync returned error (continuing to poll)', {
       error: result.error.message || JSON.stringify(result.error),
@@ -179,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 || [];
@@ -266,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) });
 }
 
 /**
@@ -277,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 || {};
@@ -595,6 +677,8 @@ function parseMcpSpec(spec) {
 }
 
 module.exports = {
+  INSUFFICIENT_CREDITS_REASON,
+  providerErrorReason,
   parseModelString,
   createClient,
   createSession,

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

@@ -200,8 +200,9 @@ async function continueSidecar(options) {
   const metaPath = SessionPaths.metadataFile(sessionDir);
   const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
 
-  // Finalize session
-  finalizeSession(sessionDir, summary, project, meta);
+  // Finalize session. Interactive mode legitimately returns an empty summary,
+  // so pass status explicitly to stay out of the #36 empty-summary guard.
+  finalizeSession(sessionDir, summary, project, meta, { status: 'complete' });
 }
 
 module.exports = {