amicus 1.7.5 → 1.7.7

package/src/sidecar/resume.js

@@ -110,7 +110,10 @@ function updateSessionStatus(sessionDir, status) {
   return meta;
 }
 
-/** Resume a previous sidecar session - Spec Reference: §4.3, §8.3 */
+/**
+ * Resume a previous sidecar session - Spec Reference: §4.3, §8.3
+ * @returns {Promise<number>} process exit code
+ */
 async function resumeSidecar(options) {
   const {
     taskId, project = process.cwd(), headless = false, timeout = 15,
@@ -163,6 +166,7 @@ async function resumeSidecar(options) {
     heartbeat = createHeartbeat();
 
     let summary;
+    let result;
     const effectiveAgent = metadata.agent || 'Build';
 
     // Load conversation for both paths (interactive already did this, headless didn't)
@@ -173,7 +177,7 @@ async function resumeSidecar(options) {
 
     if (headless) {
       const userMessage = buildResumeUserMessage(metadata.briefing || '', existingConversation);
-      const result = await runHeadless(
+      result = await runHeadless(
         metadata.model, resumePrompt, userMessage,
         taskId, project, timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers }
       );
@@ -184,7 +188,7 @@ async function resumeSidecar(options) {
     } else {
       logger.info('Launching interactive resume', { taskId, model: metadata.model });
 
-      const result = await runInteractive(
+      result = await runInteractive(
         metadata.model, resumePrompt, metadata.briefing || '',
         taskId, project,
         {
@@ -202,10 +206,22 @@ async function resumeSidecar(options) {
     // Output summary
     outputSummary(summary);
 
-    // Finalize session (use updatedMetadata which has resumedAt). Pass status
-    // explicitly to preserve the pre-#36 default ('complete') and stay out of
-    // the empty-summary guard — interactive resume legitimately has no summary.
-    finalizeSession(sessionDir, summary, project, updatedMetadata, { status: 'complete' });
+    // Map the run result to the canonical terminal status + exit code —
+    // mirrors start.js. Explicit status preserves the interactive
+    // empty-summary carve-out (the #36 guard never re-classifies it).
+    const { resolveTerminalState } = require('./session-finalize');
+    const terminal = resolveTerminalState(result);
+    const metaPath = SessionPaths.metadataFile(sessionDir);
+    if (terminal.status === 'error') {
+      updatedMetadata.status = 'error';
+      updatedMetadata.reason = (result && result.error) ? String(result.error) : 'Incomplete';
+      updatedMetadata.completedAt = new Date().toISOString();
+      fs.writeFileSync(metaPath, JSON.stringify(updatedMetadata, null, 2), { mode: 0o600 });
+      logger.error('Resume completed with error', { taskId, error: updatedMetadata.reason });
+    } else {
+      finalizeSession(sessionDir, summary, project, updatedMetadata, { status: terminal.status });
+    }
+    return terminal.exitCode; // finally below still releases the lock first
   } finally {
     if (heartbeat) { heartbeat.stop(); }
     releaseLock(sessionDir);

package/src/sidecar/setup-window.js

@@ -55,6 +55,14 @@ async function launchSetupWindow() {
       logger.debug('Setup window stderr', { data: chunk.trim() });
     });
 
+    // A spawn failure (ENOENT/EACCES) emits 'error' and NEVER 'close'. Without
+    // this listener the Promise would hang forever and Node would treat the
+    // unhandled child 'error' as a crash. Resolve with a clear failure instead.
+    proc.on('error', (err) => {
+      logger.error('Setup window failed to spawn', { error: err.message });
+      resolve({ success: false, error: `Failed to start setup window: ${err.message}` });
+    });
+
     proc.on('close', (code) => {
       logger.info('Setup window closed', { code });
 

package/src/sidecar/start.js

@@ -23,6 +23,7 @@ const { acquireLock, releaseLock } = require('../utils/session-lock');
 const { loadMcpConfig, parseMcpSpec } = require('../opencode-client');
 const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { discoverParentMcps } = require('../utils/mcp-discovery');
+const { stripSelfMcpEntries } = require('../utils/mcp-self-identity');
 
 /** Generate a unique 8-character hex task ID */
 function generateTaskId() {
@@ -79,10 +80,12 @@ function createSessionMetadata(taskId, project, options) {
  * @param {string} [options.clientType] - Parent client type for discovery
  * @param {boolean} [options.noMcp] - Skip MCP inheritance from parent
  * @param {string[]} [options.excludeMcp] - Server names to exclude
+ * @param {string} [options.projectDir] - Target project directory used to resolve
+ *   a project-scoped opencode.json (NOT process.cwd() under Claude Code/MCP/Cowork)
  * @returns {object|null} MCP server configs or null
  */
 function buildMcpConfig(options) {
-  const { mcp, mcpConfig, clientType, noMcp, excludeMcp } = options;
+  const { mcp, mcpConfig, clientType, noMcp, excludeMcp, projectDir } = options;
   let mcpServers = null;
 
   // Layer 1: Discover parent MCPs (unless --no-mcp)
@@ -94,8 +97,10 @@ function buildMcpConfig(options) {
     }
   }
 
-  // Layer 2: File config (opencode.json) overrides discovered
-  const fileConfig = loadMcpConfig(mcpConfig);
+  // Layer 2: File config (opencode.json) overrides discovered.
+  // Resolve the project-scoped opencode.json against the target project dir,
+  // not process.cwd() (which differs under Claude Code/MCP/Cowork).
+  const fileConfig = loadMcpConfig(mcpConfig, projectDir);
   if (fileConfig) {
     mcpServers = mcpServers ? { ...mcpServers, ...fileConfig } : { ...fileConfig };
     logger.debug('Loaded MCP config from file', { serverCount: Object.keys(fileConfig).length });
@@ -113,13 +118,11 @@ function buildMcpConfig(options) {
     }
   }
 
-  // Always exclude the sidecar itself to prevent recursive spawning.
-  // When launched from Cowork, the discovered MCP list includes "sidecar"
-  // which would cause an infinite spawn loop.
-  if (mcpServers && mcpServers.sidecar) {
-    delete mcpServers.sidecar;
-    logger.debug('Auto-excluded sidecar MCP (recursive spawn prevention)');
-  }
+  // Always exclude amicus itself — under ANY registered name or aliased
+  // invocation — to prevent recursive spawning. When launched from Cowork or
+  // Claude Code the discovered list includes 'amicus'/'sidecar' (and possibly
+  // a user alias), which would cause an infinite spawn loop.
+  if (mcpServers) { stripSelfMcpEntries(mcpServers, logger); }
 
   // Apply explicit exclusions
   if (excludeMcp && Array.isArray(excludeMcp) && mcpServers) {
@@ -154,7 +157,9 @@ async function startSidecar(options) {
   const effectiveSession = sessionId || session;
   const effectiveProject = cwd || project;
   const effectiveHeadless = noUi !== undefined ? noUi : headless;
-  const mcpServers = buildMcpConfig({ mcp, mcpConfig, clientType: client, noMcp, excludeMcp });
+  const mcpServers = buildMcpConfig({
+    mcp, mcpConfig, clientType: client, noMcp, excludeMcp, projectDir: effectiveProject
+  });
   const taskId = options.taskId || generateTaskId();
   const reasoning = thinking ? { effort: thinking } : undefined;
 

package/src/utils/atomic-write.js

@@ -0,0 +1,39 @@
+/**
+ * Atomic file write helper.
+ *
+ * Writes data to a unique temp file alongside the target, then renames it into
+ * place. Rename is atomic on a single filesystem, so a crash mid-write leaves
+ * the original file intact rather than a truncated/corrupt one. This is the
+ * pattern already used by council/verdict.js, session-index.js, and
+ * model-catalog.js; this module shares it for metadata writes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Atomically write `data` to `filePath` via temp file + rename.
+ *
+ * The temp name is unique per write (pid + random suffix) so concurrent writers
+ * never collide on the same temp file. On any failure the temp file is cleaned
+ * up best-effort. Errors propagate to the caller.
+ *
+ * @param {string} filePath - Destination path.
+ * @param {string|Buffer} data - Content to write.
+ * @param {{mode?: number}} [opts] - Write options; `mode` sets file permissions.
+ */
+function writeFileAtomic(filePath, data, opts = {}) {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const tmp = path.join(dir, `.${base}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, data, { mode: opts.mode });
+    fs.renameSync(tmp, filePath); // atomic on a single filesystem
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+module.exports = { writeFileAtomic };

package/src/utils/error-doc.js

@@ -48,6 +48,9 @@ function failJson(useJson, { code, message, hint = null, command = null }) {
     process.stdout.write(JSON.stringify(buildErrorDoc({ code, message, hint, command }), null, 2) + '\n');
   } else {
     process.stderr.write(message + '\n');
+    // Parity with --json (whose envelope carries error.hint): surface the
+    // actionable hint to humans too, in doctor's arrow style.
+    if (hint) { process.stderr.write(`  → ${hint}\n`); }
   }
   return 1;
 }

package/src/utils/format-duration.js

@@ -0,0 +1,24 @@
+// src/utils/format-duration.js
+'use strict';
+
+/**
+ * @module utils/format-duration
+ * Single ms->human duration formatter shared by the fanout and council
+ * renderers. Rolls minutes up ("1m5s" / "42s") and lets each caller pick its
+ * own null placeholder ("-" for fanout stdout, "—" for the council report).
+ */
+
+/**
+ * Format a millisecond duration as "1m5s" / "42s".
+ * @param {number|null|undefined} ms - Duration in milliseconds.
+ * @param {string} [empty='-'] - Placeholder for null/undefined input.
+ * @returns {string}
+ */
+function formatDuration(ms, empty = '-') {
+  if (ms === null || ms === undefined) { return empty; }
+  const s = Math.round(ms / 1000);
+  const m = Math.floor(s / 60);
+  return m > 0 ? `${m}m${s % 60}s` : `${s}s`;
+}
+
+module.exports = { formatDuration };

package/src/utils/mcp-discovery.js

@@ -12,6 +12,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { logger } = require('./logger');
+const { stripSelfMcpEntries } = require('./mcp-self-identity');
 
 /**
  * Normalize .mcp.json to a flat { name: config } map.
@@ -70,15 +71,13 @@ function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
     const settingsPath = path.join(baseDir, 'settings.json');
     if (!fs.existsSync(settingsPath)) {
       // No settings.json — skip plugin discovery, may still have claude.json servers
-      const merged = { ...claudeJsonServers };
-      delete merged.sidecar;
+      const merged = stripSelfMcpEntries({ ...claudeJsonServers }, logger);
       return Object.keys(merged).length > 0 ? merged : null;
     }
     const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
     const enabledPlugins = settings.enabledPlugins;
     if (!enabledPlugins || typeof enabledPlugins !== 'object') {
-      const merged = { ...claudeJsonServers };
-      delete merged.sidecar;
+      const merged = stripSelfMcpEntries({ ...claudeJsonServers }, logger);
       return Object.keys(merged).length > 0 ? merged : null;
     }
 
@@ -133,11 +132,9 @@ function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
     logger.debug('Failed to read Claude Code settings', { error: err.message });
   }
 
-  // Merge: plugin servers first, then claude.json overwrites (higher priority)
-  const merged = { ...pluginServers, ...claudeJsonServers };
-
-  // Always exclude sidecar itself to prevent recursive spawning
-  delete merged.sidecar;
+  // Merge: plugin servers first, then claude.json overwrites (higher priority).
+  // Recursive-spawn guard: drop every entry that resolves to amicus itself.
+  const merged = stripSelfMcpEntries({ ...pluginServers, ...claudeJsonServers }, logger);
 
   return Object.keys(merged).length > 0 ? merged : null;
 }

package/src/utils/mcp-self-identity.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * @module mcp-self-identity
+ * Recursive-spawn guard. A child sidecar that inherits an MCP entry launching
+ * amicus itself would spawn amicus inside amicus, forever. The shipped server
+ * registers as 'amicus' (scripts/postinstall.js, .claude-plugin/plugin.json)
+ * plus a deprecated 'sidecar' shim — and users can alias it under ANY name —
+ * so we exclude both reserved names AND any entry whose command+args resolve
+ * to an amicus MCP invocation.
+ */
+
+/** Server names amicus registers itself under. */
+const SELF_MCP_NAMES = Object.freeze(['amicus', 'sidecar']);
+
+/** Shipped bin aliases (package.json "bin") → ./bin/amicus.js */
+const SELF_BIN_NAMES = new Set(['amicus', 'am', 'sidecar', 'claude-sidecar']);
+
+/**
+ * Normalize one command/arg token for identity matching: lower-case, forward
+ * slashes, basename, strip a trailing .exe/.cmd/.js, strip an @version spec.
+ * 'C:\\x\\bin\\amicus.js' → 'amicus'; 'amicus@latest' → 'amicus'; 'npx' → 'npx'.
+ * @param {unknown} token
+ * @returns {string}
+ */
+function normalizeToken(token) {
+  const t = String(token).toLowerCase().replace(/\\/g, '/');
+  const base = t.includes('/') ? t.slice(t.lastIndexOf('/') + 1) : t;
+  return base.replace(/\.(exe|cmd|js)$/, '').replace(/@[^@]*$/, '');
+}
+
+/**
+ * True when this MCP server config would launch amicus's own MCP server:
+ * some non-flag token resolves to an amicus binary/package and a LATER token
+ * is 'mcp'. URL-only (command-less) configs are never self.
+ * @param {{command?:string, args?:unknown[]}|null|undefined} config
+ * @returns {boolean}
+ */
+function isAmicusMcpConfig(config) {
+  if (!config || typeof config !== 'object' || !config.command) { return false; }
+  const tokens = [config.command, ...(Array.isArray(config.args) ? config.args : [])].map(String);
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i].startsWith('-')) { continue; } // flags (-y, --yes) are never the binary
+    if (SELF_BIN_NAMES.has(normalizeToken(tokens[i]))) {
+      return tokens.slice(i + 1).some((t) => String(t).toLowerCase() === 'mcp');
+    }
+  }
+  return false;
+}
+
+/**
+ * Delete every self entry (reserved name OR command identity) from an
+ * mcpServers map. Mutates and returns the same object.
+ * @param {object|null|undefined} mcpServers
+ * @param {{debug?:Function}} [log]
+ * @returns {object|null|undefined}
+ */
+function stripSelfMcpEntries(mcpServers, log) {
+  if (!mcpServers || typeof mcpServers !== 'object') { return mcpServers; }
+  for (const name of Object.keys(mcpServers)) {
+    if (SELF_MCP_NAMES.includes(name) || isAmicusMcpConfig(mcpServers[name])) {
+      delete mcpServers[name];
+      if (log && log.debug) { log.debug('Auto-excluded amicus MCP entry (recursive spawn prevention)', { name }); }
+    }
+  }
+  return mcpServers;
+}
+
+module.exports = { SELF_MCP_NAMES, isAmicusMcpConfig, stripSelfMcpEntries, normalizeToken };

package/src/utils/server-setup.js

@@ -4,8 +4,8 @@
  * Handles port management and cleanup for the OpenCode server.
  */
 
-const { execFileSync } = require('child_process');
 const { logger } = require('./logger');
+const { findListenerPid } = require('./port-pid');
 
 const DEFAULT_PORT = 4096;
 
@@ -15,18 +15,9 @@ const DEFAULT_PORT = 4096;
  * @returns {number|null} PID or null if not in use
  */
 function getPortPid(port) {
-  try {
-    // Use execFileSync with arguments array (safe from injection)
-    const result = execFileSync('lsof', ['-ti', `:${port}`], {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    const pid = parseInt(result.trim(), 10);
-    return isNaN(pid) ? null : pid;
-  } catch {
-    // lsof returns non-zero if no process found
-    return null;
-  }
+  // Delegate to the cross-platform lookup (netstat on Windows, lsof elsewhere)
+  // so the port-in-use check and kill path work off Unix too.
+  return findListenerPid(port);
 }
 
 /**

package/src/utils/session-abort.js

@@ -11,6 +11,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { writeFileAtomic } = require('./atomic-write');
 
 /**
  * Synchronously write a terminal status to a session's metadata. Best-effort: never throws.
@@ -28,7 +29,8 @@ function markTerminal(sessionDir, status, reason) {
     meta.status = status;
     meta.reason = reason;
     meta[status === 'aborted' ? 'abortedAt' : 'completedAt'] = new Date().toISOString();
-    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+    // Atomic (temp + rename): a crash mid-write must not corrupt the marker.
+    writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
     return true;
   } catch {
     return false;

package/src/utils/shared-server.js

@@ -11,6 +11,7 @@ const { getCompatEnv } = require('./env-compat');
 const MAX_RESTARTS = 3;
 const RESTART_WINDOW = 5 * 60 * 1000;
 const RESTART_BACKOFF = 2000;
+const CRASH_POLL_INTERVAL = 5000; // ms; env-tunable via AMICUS_CRASH_POLL_MS
 
 /**
  * SharedServerManager - manages a single shared OpenCode server for MCP sessions.
@@ -45,6 +46,16 @@ class SharedServerManager {
 
     /** @type {number[]} Timestamps of recent restart attempts */
     this._restartTimestamps = [];
+
+    /** @type {NodeJS.Timeout|null} goPid liveness poll (H7) */
+    this._crashPoll = null;
+
+    /** @type {NodeJS.Timeout|null} Pending crash-restart backoff timer */
+    this._restartTimer = null;
+
+    /** Pid-liveness probe (test seam). Lazy default keeps construction light. */
+    this._isProcessAlive = options.isProcessAlive
+      || ((pid) => require('../sidecar/session-utils').isProcessAlive(pid));
   }
 
   /**
@@ -73,6 +84,7 @@ class SharedServerManager {
       this.server = server;
       this.client = client;
       this._starting = null;
+      this._wireCrashListener(server);
       this._serverWatchdog = new IdleWatchdog({
         mode: 'server',
         onTimeout: () => {
@@ -162,6 +174,8 @@ class SharedServerManager {
       this._serverWatchdog.cancel();
       this._serverWatchdog = null;
     }
+    this._stopCrashPoll();
+    if (this._restartTimer) { clearTimeout(this._restartTimer); this._restartTimer = null; }
     if (this.server) {
       this.server.close();
       this.server = null;
@@ -169,19 +183,68 @@ class SharedServerManager {
     }
   }
 
+  /**
+   * Wire crash detection onto a freshly started server handle. The REAL handle
+   * from buildServerHandle is { url, goPid, close } — it surfaces NO lifecycle
+   * events, so the emitter path alone was dead code (H7). Detection now polls
+   * the Go engine pid; emitter wiring is kept for handles that do expose events.
+   * @param {object} server - Server handle returned by _doStartServer
+   */
+  _wireCrashListener(server) {
+    const emitter = (server && typeof server.on === 'function')
+      ? server
+      : (server && server.process && typeof server.process.on === 'function')
+        ? server.process
+        : null;
+    if (emitter && !emitter._amicusCrashWired) {
+      emitter._amicusCrashWired = true;
+      const onExit = (code) => {
+        if (this.server !== server) { return; } // stale handle already replaced/closed
+        this._onServerCrash(code);
+      };
+      emitter.on('exit', onExit);
+      emitter.on('close', onExit);
+    }
+    if (server && server.goPid) {
+      this._startCrashPoll(server);
+    } else if (!emitter) {
+      this.logger.debug?.('Server handle has no goPid and no emitter — crash detection unavailable');
+    }
+  }
+
+  /** Poll the Go engine pid; pid death IS the crash signal (H7). */
+  _startCrashPoll(server) {
+    this._stopCrashPoll();
+    const interval = Number(getCompatEnv('CRASH_POLL_MS')) || CRASH_POLL_INTERVAL;
+    this._crashPoll = setInterval(() => {
+      if (this.server !== server) { this._stopCrashPoll(); return; }
+      if (!this._isProcessAlive(server.goPid)) {
+        this._stopCrashPoll();
+        this._onServerCrash(null);
+      }
+    }, interval);
+    if (this._crashPoll.unref) { this._crashPoll.unref(); }
+  }
+
+  _stopCrashPoll() {
+    if (this._crashPoll) { clearInterval(this._crashPoll); this._crashPoll = null; }
+  }
+
   /**
    * Handle a server crash: log, notify sessions, then schedule restart.
    *
    * @param {number} exitCode - Process exit code from the crashed server
    */
   _onServerCrash(exitCode) {
+    this._stopCrashPoll();
     this.logger.error?.('Shared server crashed', { exitCode });
     for (const [id] of this._sessionWatchdogs) {
       this.logger.warn?.('Session interrupted by server crash', { sessionId: id });
     }
     this.server = null;
     this.client = null;
-    setTimeout(() => this._handleRestart(), RESTART_BACKOFF);
+    this._restartTimer = setTimeout(() => this._handleRestart(), RESTART_BACKOFF);
+    if (this._restartTimer.unref) { this._restartTimer.unref(); }
   }
 
   /**