amicus 1.7.6 → 1.8.0

package/src/utils/legacy-mcp-migration.js

@@ -0,0 +1,119 @@
+// src/utils/legacy-mcp-migration.js
+'use strict';
+
+/**
+ * Legacy 'sidecar' MCP registration cleanup (Phase 4 tool de-bloat).
+ *
+ * Through v1.7.x scripts/postinstall.js registered the SAME stdio MCP server
+ * under two names — 'amicus' and legacy 'sidecar' — in Claude Code
+ * (~/.claude.json) and Claude Desktop/Cowork (claude_desktop_config.json).
+ * Combined with the in-server sidecar_* tool aliases this quadrupled the
+ * client-visible tool surface (13 real tools -> 52).
+ *
+ * This module removes a legacy 'sidecar' server entry, but ONLY when it is
+ * identical-in-effect to the amicus registration: its command must resolve to
+ * an amicus MCP invocation per isAmicusMcpConfig() (./mcp-self-identity,
+ * Phase 1). A 'sidecar' entry pointing anywhere else is user customization
+ * and is NEVER touched.
+ *
+ * Consumers: scripts/postinstall.js (one-shot migration on install/upgrade)
+ * and src/cli-handlers-doctor.js (duplicate check + `doctor --fix`).
+ * All functions are synchronous, never throw, and report via return values.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { writeFileAtomic } = require('./atomic-write');
+
+/** ~/.claude.json — where BOTH Claude Code registration paths (CLI + file fallback) land. */
+function claudeCodeConfigPath() {
+  return path.join(os.homedir(), '.claude.json');
+}
+
+/** claude_desktop_config.json — platform-aware; mirrors postinstall registerClaudeDesktop. */
+function claudeDesktopConfigPath() {
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+  }
+  return path.join(os.homedir(), '.config', 'claude', 'claude_desktop_config.json');
+}
+
+function defaultTargets(deps = {}) {
+  return [
+    { target: 'Claude Code', configPath: deps.codePath || claudeCodeConfigPath() },
+    { target: 'Claude Desktop', configPath: deps.desktopPath || claudeDesktopConfigPath() },
+  ];
+}
+
+/**
+ * Inspect one config file for a legacy 'sidecar' MCP entry.
+ * @returns {{status:'absent'|'removable'|'customized'|'unreadable', config?:object}}
+ */
+function inspectLegacySidecarEntry(configPath, deps = {}) {
+  const isAmicus = deps.isAmicusMcpConfig
+    || require('./mcp-self-identity').isAmicusMcpConfig;
+  let parsed;
+  try {
+    if (!fs.existsSync(configPath)) { return { status: 'absent' }; }
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch {
+    return { status: 'unreadable' };
+  }
+  const entry = parsed && parsed.mcpServers ? parsed.mcpServers.sidecar : undefined;
+  if (!entry) { return { status: 'absent' }; }
+  // 'removable' means VERIFIED duplicate, not just amicus-shaped. Two edges
+  // must fall back to 'customized' (left alone) instead:
+  //  (a) no 'amicus' twin present — this may be the user's ONLY working
+  //      registration (scripts-skipped / manual pre-rebrand install); deleting
+  //      it would leave them with nothing.
+  //  (b) the sidecar entry carries a non-empty `env` (API keys,
+  //      AMICUS_LEGACY_ALIASES itself) — not identical-in-effect to the bare
+  //      'amicus' entry, so removing it would silently lose configuration.
+  const hasAmicusTwin = !!(parsed.mcpServers && parsed.mcpServers.amicus);
+  const hasNonEmptyEnv = !!(entry.env && typeof entry.env === 'object' && Object.keys(entry.env).length > 0);
+  if (!hasAmicusTwin || hasNonEmptyEnv) { return { status: 'customized', config: entry }; }
+  return isAmicus(entry)
+    ? { status: 'removable', config: entry }
+    : { status: 'customized', config: entry };
+}
+
+/**
+ * Remove the legacy 'sidecar' entry from one config file — ONLY when it is an
+ * amicus self-invocation. Preserves every other key in the file.
+ * @returns {'absent'|'removed'|'customized'|'unreadable'|'write-failed'}
+ */
+function removeLegacySidecarEntry(configPath, deps = {}) {
+  const inspected = inspectLegacySidecarEntry(configPath, deps);
+  if (inspected.status !== 'removable') { return inspected.status; }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    delete parsed.mcpServers.sidecar;
+    // Atomic temp+rename write — a crash mid-write must never corrupt the
+    // user's main Claude Code state file. 0o600 is a no-op on NTFS; kept for
+    // parity with addMcpToConfigFile.
+    writeFileAtomic(configPath, JSON.stringify(parsed, null, 2), { mode: 0o600 });
+    return 'removed';
+  } catch {
+    return 'write-failed';
+  }
+}
+
+/** Inspect every known registry (doctor check). */
+function inspectAllLegacySidecarEntries(deps = {}) {
+  return defaultTargets(deps).map((t) => ({ ...t, ...inspectLegacySidecarEntry(t.configPath, deps) }));
+}
+
+/** Remove identical-in-effect legacy entries everywhere. Idempotent. */
+function migrateLegacySidecar(deps = {}) {
+  return defaultTargets(deps).map((t) => ({ ...t, result: removeLegacySidecarEntry(t.configPath, deps) }));
+}
+
+module.exports = {
+  claudeCodeConfigPath, claudeDesktopConfigPath,
+  inspectLegacySidecarEntry, removeLegacySidecarEntry,
+  inspectAllLegacySidecarEntries, migrateLegacySidecar,
+};

package/src/utils/lifecycle.js

@@ -12,7 +12,7 @@
 // when done (F3 #15). Deliberately EXCLUDED: `mcp` (long-lived server), and
 // `setup`/`update` (no OpenCode server to leak, and `setup` can be a long-lived
 // interactive Electron flow that must never be force-exited).
-const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor' /* local-only: no OpenCode server, no stray handles */]);
+const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'status', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor' /* local-only: no OpenCode server, no stray handles */]);
 
 /** @param {string} command @returns {boolean} */
 function isOneShotCommand(command) {

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/remediation-hints.js

@@ -64,6 +64,14 @@ const REMEDIATION_HINTS = Object.freeze({
    * 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)',
+
+  /**
+   * Duplicate legacy 'sidecar' MCP registration (Phase 4 de-bloat): pre-1.8
+   * postinstalls registered the same server twice. `doctor --fix` removes the
+   * twin only when it points at amicus; a customized entry is never touched.
+   */
+  removeLegacySidecar:
+    "amicus doctor --fix  (removes the duplicate legacy 'sidecar' MCP entry — same server registered twice; the 'amicus' entry stays)",
 });
 
 module.exports = REMEDIATION_HINTS;

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));
   }
 
   /**
@@ -163,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;
@@ -171,12 +184,10 @@ class SharedServerManager {
   }
 
   /**
-   * Wire crash detection onto a freshly started server handle so an unexpected
-   * exit triggers _onServerCrash (and the restart machinery). The OpenCode
-   * server handle is a plain wrapper; it may surface lifecycle events either on
-   * itself or on an underlying child `process`. Attach to whichever is an event
-   * emitter, guarding against double-wiring across restarts.
-   *
+   * 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) {
@@ -185,19 +196,38 @@ class SharedServerManager {
       : (server && server.process && typeof server.process.on === 'function')
         ? server.process
         : null;
-    if (!emitter || emitter._amicusCrashWired) {
-      return;
+    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');
     }
-    emitter._amicusCrashWired = true;
-    const onExit = (code) => {
-      // Ignore exits from a stale handle we have already replaced/closed.
-      if (this.server !== server) {
-        return;
+  }
+
+  /** 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);
       }
-      this._onServerCrash(code);
-    };
-    emitter.on('exit', onExit);
-    emitter.on('close', onExit);
+    }, interval);
+    if (this._crashPoll.unref) { this._crashPoll.unref(); }
+  }
+
+  _stopCrashPoll() {
+    if (this._crashPoll) { clearInterval(this._crashPoll); this._crashPoll = null; }
   }
 
   /**
@@ -206,13 +236,15 @@ class SharedServerManager {
    * @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(); }
   }
 
   /**