amicus 1.6.0 → 1.7.0

package/src/sidecar/interactive.js

@@ -13,26 +13,33 @@ const { logger } = require('../utils/logger');
 const { getCompatEnv } = require('../utils/env-compat');
 const { startInteractiveMirror } = require('./interactive-mirror');
 const { getSessionDir } = require('../session-manager');
-
-/** Get the Electron binary path via require('electron').
- *  Works in all install contexts (global, local, npx hoisted).
- *  @returns {string|null} Full path to Electron binary, or null if not installed */
+const { canonicalProjectPath } = require('../utils/project-path');
+const { ensureElectron } = require('./electron-ensure');
+
+/** Resolve the Electron binary path ONLY when the exe actually exists on disk.
+ *  #54: path.txt surviving (require('electron') resolving) is NOT enough — a
+ *  quarantined/missing dist/<exe> must read as not-installed. Delegates to the
+ *  stat-the-exe probe so the runtime check matches postinstall's strictness.
+ *  Stays a PURE PROBE: no download/extract side-effect.
+ *  @returns {string|null} Full path to a usable Electron binary, or null. */
 function getElectronPath() {
   try {
-    return require('electron');
+    const { isElectronUsable, resolveElectronBinary } = require('./electron-install');
+    return isElectronUsable() ? resolveElectronBinary() : null;
   } catch {
     return null;
   }
 }
 
-/** Check if Electron is available (lazy loading guard) */
+/** Check if Electron is available (lazy loading guard). Pure probe — stats the
+ *  exe via getElectronPath(), never provisions. */
 function checkElectronAvailable() {
   return getElectronPath() !== null;
 }
 
 /** 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 +50,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);
@@ -90,16 +101,28 @@ function handleElectronProcess(electronProcess, taskId, resolve) {
 
 /** Run sidecar in interactive mode (Electron GUI) */
 async function runInteractive(model, systemPrompt, userMessage, taskId, project, options = {}) {
-  if (!checkElectronAvailable()) {
-    logger.error('Electron not installed — interactive mode unavailable');
+  // Lazily PROVISION electron on FIRST GUI use (#55). ensureElectron() is the
+  // one place network provisioning is allowed; the probes stay pure. When it
+  // returns ok:false the GUI is unavailable — fail gracefully toward --no-ui.
+  const ensured = await ensureElectron();
+  if (!ensured.ok) {
+    logger.error('Electron not available — interactive mode unavailable', { reason: ensured.reason });
     return {
       summary: '', completed: false, timedOut: false, taskId,
-      error: 'Interactive mode requires electron. Install with: npm install -g amicus (or use --no-ui for headless mode)'
+      error: `Interactive mode requires electron. ${ensured.reason} (or use --no-ui for headless mode)`
     };
   }
 
   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 +149,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,26 +195,28 @@ 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(),
   });
 
   return new Promise((resolve, _reject) => {
-    const electronPath = getElectronPath();
+    // Prefer the path ensureElectron() resolved: a same-process first-use
+    // provision can leave require('electron') cached as a stale null (#55).
+    const electronPath = ensured.path || getElectronPath();
     const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
 
     const nodeModulesBin = path.join(__dirname, '..', '..', 'node_modules', '.bin');
     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/sidecar/setup-window.js

@@ -10,19 +10,24 @@ const { spawn } = require('child_process');
 const path = require('path');
 const { logger } = require('../utils/logger');
 const { getElectronPath } = require('./interactive');
+const { ensureElectron } = require('./electron-ensure');
 const { getCompatEnv } = require('../utils/env-compat');
 
 /**
- * Launch the Electron setup window for API key entry
+ * Launch the Electron setup window for API key entry.
+ * Lazily PROVISIONS electron on first GUI use (#55) via ensureElectron() — the
+ * one place network provisioning is allowed; getElectronPath() stays a pure probe.
  * @returns {Promise<{ success: boolean, error?: string }>}
  */
-function launchSetupWindow() {
+async function launchSetupWindow() {
+  const ensured = await ensureElectron();
+  if (!ensured.ok) {
+    return { success: false, error: ensured.reason || 'Electron not installed' };
+  }
   return new Promise((resolve) => {
-    const electronPath = getElectronPath();
-    if (!electronPath) {
-      resolve({ success: false, error: 'Electron not installed' });
-      return;
-    }
+    // Prefer the path ensureElectron() resolved: a same-process first-use
+    // provision can leave require('electron') cached as a stale null (#55).
+    const electronPath = ensured.path || getElectronPath();
     const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
 
     const env = {

package/src/sidecar/setup.js

@@ -266,8 +266,10 @@ async function runReadlineSetup() {
     if (foundKeys.length > 0) {
       console.log(`API keys detected: ${foundKeys.join(', ')}`);
     } else {
+      const { runDoctor } = require('../utils/remediation-hints');
       console.log('No API keys detected.');
       console.log('Set OPENROUTER_API_KEY to get started, or run: amicus setup');
+      console.log(`Not sure what's wrong? ${runDoctor}`);
     }
     console.log('');
 

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/project-root-sanity.js

@@ -0,0 +1,66 @@
+// src/utils/project-root-sanity.js
+'use strict';
+
+/**
+ * Project-root sanity heuristic (#43).
+ *
+ * `amicus doctor` resolves the project dir from process.cwd(); when a user
+ * launches amicus from a packaged-app/install directory (e.g. the Claude
+ * Desktop app dir) instead of their repo, sessions land in the wrong place.
+ * This pure helper inspects a path string + its directory markers and decides
+ * whether to WARN. It never touches the filesystem and never throws.
+ */
+
+/**
+ * Path fragments that signal a packaged-app / install directory rather than a
+ * user project. Matched case-insensitively against the normalized path.
+ */
+const INSTALL_PATTERNS = [
+  /anthropicclaude/i,        // Claude Desktop app dir
+  /[\\/]app-\d/i,            // versioned electron app dir, e.g. app-1.2.3
+  /appdata[\\/]local/i,      // Windows per-user app data
+  /program files/i,          // Windows install root
+  /[\\/]\.asar/i,            // packaged electron resources
+];
+
+/** @returns {boolean} true if the path looks like an app/install dir */
+function looksLikeInstallDir(dir) {
+  if (!dir || typeof dir !== 'string') { return false; }
+  return INSTALL_PATTERNS.some((re) => re.test(dir));
+}
+
+/**
+ * Assess a resolved project dir.
+ *
+ * @param {string} dir Resolved project directory (e.g. process.cwd()).
+ * @param {{hasGit?:boolean, hasPackageJson?:boolean, hasClaude?:boolean}} markers
+ *   Presence of .git / package.json / .claude in `dir`.
+ * @returns {{status:'ok'|'warn', message:string, hint:string|null}}
+ */
+function assessProjectRoot(dir, markers) {
+  const m = markers || {};
+  const safeDir = (dir && typeof dir === 'string') ? dir : '';
+  const hint =
+    'pass an explicit project (amicus … --project <path>) or cd into your repo before running amicus';
+
+  if (looksLikeInstallDir(safeDir)) {
+    return {
+      status: 'warn',
+      message: `${safeDir || '(empty)'} looks like an app/install dir, not a project`,
+      hint,
+    };
+  }
+
+  const hasMarker = !!(m.hasGit || m.hasPackageJson || m.hasClaude);
+  if (!hasMarker) {
+    return {
+      status: 'warn',
+      message: `${safeDir || '(empty)'} has no project markers (.git / package.json / .claude)`,
+      hint,
+    };
+  }
+
+  return { status: 'ok', message: safeDir, hint: null };
+}
+
+module.exports = { assessProjectRoot, looksLikeInstallDir, INSTALL_PATTERNS };

package/src/utils/remediation-hints.js

@@ -0,0 +1,51 @@
+// src/utils/remediation-hints.js
+'use strict';
+
+/**
+ * Shared, copy-paste remediation hint strings.
+ *
+ * One source of truth for the fix commands surfaced by `amicus doctor` and by
+ * failure messages across the CLI, so the guidance never drifts. Consumed by
+ * src/cli-handlers-doctor.js (per-check hints) and reused by sweep'd failure
+ * sites (#32) and the MCP recovery surface (#43).
+ *
+ * The object is frozen — these are a stable copy-paste contract; callers read
+ * fields, they do not mutate them.
+ */
+const REMEDIATION_HINTS = Object.freeze({
+  /** Canonical global (re)install. */
+  reinstall: 'npm install -g amicus',
+
+  /** `npm cache clean --force` — clears a corrupt npm cache before reinstalling. */
+  cacheClean: 'npm cache clean --force',
+
+  /**
+   * Engine binaries missing/rolled back. A transient install error can roll
+   * back the platform engine packages; re-run, or clean the cache and reinstall.
+   */
+  reinstallEngine:
+    '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)',
+
+  /** Electron absent — reinstall to add the interactive GUI (headless still works). */
+  reinstallElectron: 'npm install -g amicus  (reinstall to add Electron)',
+
+  /**
+   * Electron present but broken (ABI mismatch / partial unpack). Delete the
+   * vendored copy and reinstall to force a clean rebuild.
+   */
+  rebuildElectron:
+    'rm -rf node_modules/electron && npm install -g amicus  (rebuild Electron after an ABI mismatch or partial unpack)',
+
+  /** Point the user at the single recovery hub. */
+  runDoctor: 'run: amicus doctor  (diagnoses config, keys, engine & MCP, with copy-paste fixes)',
+
+  /**
+   * Self-heal the optional Electron GUI in place (#56). This is the convergence
+   * target for the three "reinstall to fix Electron" hints — it provisions the
+   * binary from cache (or downloads on demand) WITHOUT a global reinstall, so it
+   * can't loop the way `npm install -g amicus` could when the rollback recurs.
+   */
+  doctorFix: 'amicus doctor --fix  (self-heal the Electron GUI in place — provisions the binary; no reinstall, so it can\'t loop)',
+});
+
+module.exports = REMEDIATION_HINTS;

package/src/utils/result-schema.js

@@ -106,9 +106,19 @@ function waveExitCode(waveStatus) {
  * @param {object} opts
  * @param {string} opts.waveId
  * @param {Array<object>} opts.legs - run documents (in --models order)
- * Counts track the four primary terminal statuses (complete/error/timeout/aborted);
- * legs with other statuses (e.g. 'crashed', 'running' in a rebuilt wave) count toward
- * `total` only, so total may exceed the sum of the named buckets.
+ *
+ * COUNTS REMAINDER RULE (stable, no schemaVersion bump): `counts` exposes four
+ * NAMED terminal buckets — complete, error, timeout, aborted — plus `total`
+ * (= legs.length). The remaining TERMINAL_STATUSES ('crashed', 'idle-timeout')
+ * and any non-terminal status (e.g. 'running' in a live-rebuilt wave) are
+ * deliberately NOT given their own bucket; they are reflected ONLY in `total`.
+ * Therefore a consumer must treat the unnamed remainder as
+ *   total − (complete + error + timeout + aborted)
+ * and must NOT assume the named buckets sum to `total`. Adding new buckets
+ * would change the document shape and REQUIRES bumping SCHEMA_VERSION.
+ * This agrees with the MCP wave path (mcp-server.js), which counts a leg as
+ * "done" iff its status is in TERMINAL_STATUSES — including 'crashed' — so a
+ * crashed leg is done/total there exactly as it is total-only here.
  * @param {{source: string, file: string|null, chars: number}|null} [opts.promptMeta]
  * @param {string|null} [opts.createdAt]
  * @param {string|null} [opts.completedAt]
@@ -117,6 +127,9 @@ function waveExitCode(waveStatus) {
  */
 function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null }) {
   const { sumWaveUsage } = require('./pricing');
+  // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
+  // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
+  // only, so total may exceed complete+error+timeout+aborted.
   const counts = {
     total: legs.length,
     complete: legs.filter(l => l.status === 'complete').length,

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

package/src/utils/version-info.js

@@ -0,0 +1,49 @@
+/**
+ * @module utils/version-info — running vs. on-disk amicus version (#33)
+ *
+ * After an `npm i -g amicus` upgrade, a long-lived MCP server process keeps
+ * running the OLD code until the client restarts it. That staleness is
+ * invisible from inside an agent session. These helpers surface the running
+ * version in MCP responses and, via a CALL-TIME re-read of the on-disk
+ * package.json, flag when the two have diverged.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/** Absolute path to this install's package.json (repo root). */
+const PKG_PATH = path.join(__dirname, '..', '..', 'package.json');
+
+/**
+ * The version baked into the running process at load time. Free: package.json
+ * is already require()'d elsewhere, so this hits the module cache.
+ */
+const RUNNING_VERSION = require('../../package.json').version;
+
+/**
+ * Re-read the on-disk package.json version at call time. Wrapped in try/catch
+ * — the file may be mid-rewrite, missing, or unreadable during/after an
+ * upgrade — and returns null on any failure rather than throwing.
+ * @returns {string|null}
+ */
+function readOnDiskVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(PKG_PATH, 'utf-8'));
+    return (pkg && typeof pkg.version === 'string') ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One-line staleness warning, or null when there's nothing to warn about
+ * (on-disk version unreadable or identical to the running version).
+ * @returns {string|null}
+ */
+function versionWarning() {
+  const onDisk = readOnDiskVersion();
+  if (!onDisk || onDisk === RUNNING_VERSION) { return null; }
+  return `Amicus was upgraded on disk (running v${RUNNING_VERSION}, on-disk v${onDisk}). `
+    + `Restart your MCP client to load v${onDisk}.`;
+}
+
+module.exports = { RUNNING_VERSION, readOnDiskVersion, versionWarning, PKG_PATH };