amicus 2.0.0 → 2.1.0

package/src/sidecar/resume.js

@@ -119,7 +119,7 @@ function updateSessionStatus(sessionDir, status) {
 async function resumeSidecar(options) {
   const {
     taskId, project = process.cwd(), headless = false, timeout = 15,
-    mcp, mcpConfig, client, noMcp, excludeMcp
+    mcp, mcpConfig, client, noMcp, excludeMcp, json = false
   } = options;
 
   // Resume operates on an EXISTING session — resolve dual-dir (amicus, then legacy).
@@ -191,10 +191,17 @@ async function resumeSidecar(options) {
 
     if (headless) {
       const userMessage = buildResumeUserMessage(metadata.briefing || '', existingConversation);
-      result = await runHeadless(
-        metadata.model, resumePrompt, userMessage,
-        taskId, project, timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers, nonce: foldNonce }
-      );
+      try {
+        result = await runHeadless(
+          metadata.model, resumePrompt, userMessage,
+          taskId, project, timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers, nonce: foldNonce }
+        );
+      } catch (err) {
+        if (!json) { throw err; }
+        // --json contract: stdout must always carry a parseable run doc,
+        // even when the engine throws rather than returning {error}.
+        result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId };
+      }
       summary = result.summary || '## Sidecar Results: No Output\n\nResumed session completed without summary.';
 
       if (result.timedOut) { logger.warn('Resume task timed out', { taskId }); }
@@ -218,8 +225,8 @@ async function resumeSidecar(options) {
       if (result.error) { logger.error('Interactive resume error', { taskId, error: result.error }); }
     }
 
-    // Output summary
-    outputSummary(summary);
+    // Output summary (human mode only — json mode keeps stdout to the doc below)
+    if (!json) { outputSummary(summary); }
 
     // Map the run result to the canonical terminal status + exit code —
     // mirrors start.js. Explicit status preserves the interactive
@@ -234,8 +241,16 @@ async function resumeSidecar(options) {
       writeFileAtomic(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 });
+      finalizeSession(sessionDir, summary, project, updatedMetadata, { quietStdout: json, status: terminal.status });
     }
+
+    if (json) {
+      const { buildRunResult } = require('../utils/result-schema');
+      const finalMeta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      const doc = buildRunResult({ taskId, metadata: finalMeta, result, summary, sessionDir });
+      console.log(JSON.stringify(doc, null, 2));
+    }
+
     return terminal.exitCode; // finally below still releases the lock first
   } finally {
     if (heartbeat) { heartbeat.stop(); }

package/src/utils/abort-result.js

@@ -0,0 +1,36 @@
+/**
+ * @module abort-result
+ * The abort-result document builder for `abort <taskId|--all> --json` (B21-rest).
+ * Split out of result-schema.js purely to stay under the size gate — same
+ * versioning contract (fields only ADDED within a SCHEMA_VERSION) applies here.
+ */
+
+'use strict';
+
+const { SCHEMA_VERSION } = require('./result-schema-version');
+
+/**
+ * Build an abort-result document.
+ * `ok` is true iff at least one session/leg was actually marked aborted by this
+ * call — a no-op (nothing running) is a successful call with an empty list, but
+ * a specific taskId that exists yet was not running (already terminal) reports
+ * ok:false so a scripted caller can tell "nothing happened" from "you aborted N".
+ * @param {object} opts
+ * @param {'session'|'wave'|'all'} opts.scope
+ * @param {string|null} opts.taskId - null for scope:'all'
+ * @param {string[]} opts.aborted - ids actually marked aborted (session/wave id + any legs)
+ * @returns {object} abort document
+ */
+function buildAbortResult({ scope, taskId = null, aborted = [] }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'abort',
+    ok: aborted.length > 0 || scope === 'all',
+    scope,
+    taskId,
+    aborted,
+    count: aborted.length,
+  };
+}
+
+module.exports = { buildAbortResult };

package/src/utils/cli-preflight.js

@@ -0,0 +1,43 @@
+/**
+ * @module cli-preflight
+ * Tiny shared preflight guards used by more than one CLI run handler
+ * (start/resume/continue/fanout), split out so each handler file can stay
+ * under the size gate without duplicating the same few lines.
+ */
+
+'use strict';
+
+const { failJson, ERROR_CODES } = require('./error-doc');
+const { validateTaskId } = require('./validators');
+
+/** Shared --json requires --no-ui gate. Exits (never returns) on violation. */
+function requireNoUiForJson(args, useJson) {
+  if (args.json && !args['no-ui']) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --json requires --no-ui' }));
+  }
+}
+
+/**
+ * Shared task-id presence + format check. Exits (never returns) on violation.
+ * @param {object} args - parsed CLI args (positional task id at args._[1])
+ * @param {boolean} useJson
+ * @param {string} commandLabel - e.g. 'resume', 'continue'
+ * @param {string} [usage] - appended to the missing-id message
+ * @returns {string} the validated task id
+ */
+function requireValidTaskId(args, useJson, commandLabel, usage) {
+  const taskId = args._[1];
+  if (!taskId) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_SESSION,
+      message: `Error: task_id is required for ${commandLabel}${usage ? `\n${usage}` : ''}`,
+    }));
+  }
+  const check = validateTaskId(taskId);
+  if (!check.valid) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: check.error }));
+  }
+  return taskId;
+}
+
+module.exports = { requireNoUiForJson, requireValidTaskId };

package/src/utils/doctor-mcp-checks.js

@@ -0,0 +1,84 @@
+/**
+ * @module doctor-mcp-checks
+ * B14/Task 4.3: the two MCP-registration doctor checks ('mcp' and
+ * 'mcp-legacy'), split out of src/cli-handlers-doctor.js to keep that file
+ * under the 300-line size gate (mirrors how session-index-tmp-sweep.js holds
+ * the B15 sweep's evaluate* composer — src/cli-handlers-doctor.js just wraps
+ * these in guard() the same way).
+ *
+ * 'mcp' (evaluateMcpRegistration): PRIMARY signal is
+ * d.hasAmicusRegistration() — a RAW (unstripped) read of the same Claude
+ * Code sources discoverClaudeCodeMcps reads. discoverClaudeCodeMcps always
+ * strips every 'amicus'/'sidecar'-shaped entry as its own recursive-spawn
+ * guard (src/utils/mcp-self-identity.js), so testing `code.amicus` here
+ * would ALWAYS be false — that was the B14 false-negative. Cowork/Desktop
+ * discovery (d.discoverCoworkMcps) does not strip and stays a bonus signal.
+ *
+ * 'mcp-legacy' (evaluateLegacyMcpEntry): unchanged logic, moved verbatim.
+ */
+
+'use strict';
+
+const HINTS = require('./remediation-hints');
+
+/**
+ * @param {{hasAmicusRegistration: () => boolean, discoverCoworkMcps: () => object|null}} d
+ */
+function evaluateMcpRegistration(d) {
+  const id = 'mcp'; const name = 'MCP registration';
+  const inCode = !!d.hasAmicusRegistration();
+  const cowork = d.discoverCoworkMcps();
+  const inCowork = !!(cowork && cowork.amicus);
+  // Primary signal: Claude Code MCP registration. Cowork/Desktop is reported as bonus only.
+  if (!inCode) {
+    return { id, name, status: 'warn', message: 'not registered in Claude Code', hint: `${HINTS.reinstall}  (or install the amicus plugin)` };
+  }
+  const extra = inCowork ? ', Cowork/Desktop' : '';
+  return { id, name, status: 'ok', message: `registered: Claude Code${extra}`, hint: null };
+}
+
+/**
+ * Duplicate legacy 'sidecar' MCP registration (same server twice — doubles
+ * the client-visible tool list). Detection reads the raw config files via
+ * legacy-mcp-migration: mcp-discovery can't see it (it strips 'sidecar' as
+ * its own recursion guard). --fix removes only identical-in-effect twins.
+ * @param {{inspectLegacyMcpEntries: () => Array, fix?: boolean, migrateLegacyMcpEntries: () => Array}} d
+ */
+function evaluateLegacyMcpEntry(d) {
+  const id = 'mcp-legacy'; const name = 'Legacy sidecar MCP entry';
+  const entries = d.inspectLegacyMcpEntries() || [];
+  const dupes = entries.filter(e => e.status === 'removable');
+  const custom = entries.filter(e => e.status === 'customized');
+  // An unreadable config is neither "no problem" nor a duplicate we can act
+  // on — reporting it as ok/'none' would hide a config doctor (and --fix)
+  // could not actually inspect. Always surface it, even alongside dupes.
+  const unreadable = entries.filter(e => e.status === 'unreadable');
+  const unreadableNote = unreadable.length
+    ? `${unreadable.map(e => e.target).join(', ')} config unreadable — skipped`
+    : null;
+  if (dupes.length === 0) {
+    if (unreadableNote) {
+      const suffix = custom.length ? `; custom 'sidecar' entry in ${custom.map(e => e.target).join(', ')} — left alone` : '';
+      return { id, name, status: 'warn', message: `${unreadableNote}${suffix}`, hint: null };
+    }
+    const message = custom.length
+      ? `custom 'sidecar' entry in ${custom.map(e => e.target).join(', ')} — left alone`
+      : 'none';
+    return { id, name, status: 'ok', message, hint: null };
+  }
+  if (d.fix) {
+    const removed = (d.migrateLegacyMcpEntries() || []).filter(r => r.result === 'removed');
+    if (removed.length >= dupes.length) {
+      const message = `removed legacy entry from: ${removed.map(r => r.target).join(', ')}`;
+      return unreadableNote
+        ? { id, name, status: 'warn', message: `${message}; ${unreadableNote}`, hint: HINTS.removeLegacySidecar }
+        : { id, name, status: 'ok', message, hint: null };
+    }
+    const message = `removed ${removed.length}/${dupes.length} duplicate(s) — could not update every config`;
+    return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar };
+  }
+  const message = `duplicate 'sidecar' entry in ${dupes.map(e => e.target).join(', ')} — doubles the MCP tool list`;
+  return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar };
+}
+
+module.exports = { evaluateMcpRegistration, evaluateLegacyMcpEntry };

package/src/utils/input-validators.js

@@ -124,4 +124,55 @@ function validateStartInputs(input) {
   return { valid: true, resolvedModel: resolved };
 }
 
-module.exports = { validateStartInputs, findSimilar };
+/**
+ * Levenshtein edit distance between two strings (insertions, deletions,
+ * substitutions, each cost 1). Hand-rolled — no runtime dependency added,
+ * since fast-levenshtein is only a dev-time transitive and runtime deps are
+ * locked for this project.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshteinDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) { return n; }
+  if (n === 0) { return m; }
+
+  // Single rolling row (O(min(m,n)) space) rather than a full m×n matrix —
+  // plenty for CLI command names, which are always short.
+  let prevRow = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const currRow = [i];
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      currRow[j] = Math.min(
+        prevRow[j] + 1,      // deletion
+        currRow[j - 1] + 1,  // insertion
+        prevRow[j - 1] + cost // substitution
+      );
+    }
+    prevRow = currRow;
+  }
+  return prevRow[n];
+}
+
+/**
+ * Suggest known commands close to an unrecognized one ("did you mean").
+ * @param {string} input - the unrecognized token the user typed
+ * @param {string[]} candidates - known command names
+ * @param {number} [maxDistance=2] - inclusive distance cap
+ * @param {number} [maxSuggestions=3]
+ * @returns {string[]} candidates within maxDistance, closest first, capped
+ */
+function suggestCommand(input, candidates, maxDistance = 2, maxSuggestions = 3) {
+  if (!input) { return []; }
+  return candidates
+    .map(c => ({ c, distance: levenshteinDistance(input.toLowerCase(), c.toLowerCase()) }))
+    .filter(({ distance }) => distance <= maxDistance)
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, maxSuggestions)
+    .map(({ c }) => c);
+}
+
+module.exports = { validateStartInputs, findSimilar, levenshteinDistance, suggestCommand };

package/src/utils/mcp-discovery.js

@@ -12,7 +12,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { logger } = require('./logger');
-const { stripSelfMcpEntries } = require('./mcp-self-identity');
+const { stripSelfMcpEntries, isAmicusMcpConfig } = require('./mcp-self-identity');
 
 /**
  * Normalize .mcp.json to a flat { name: config } map.
@@ -34,17 +34,16 @@ function normalizeMcpJson(raw) {
 }
 
 /**
- * Discover MCP servers from Claude Code's plugin chain AND ~/.claude.json.
- *
- * Discovery sources (merged, in priority order):
- * 1. ~/.claude.json → mcpServers  (servers added via `claude mcp add`)
- * 2. Enabled plugins → .mcp.json entries
+ * Read Claude Code's merged mcpServers map (~/.claude.json + plugin-chain
+ * .mcp.json files) WITHOUT the self-entry strip. Shared raw-read core for
+ * both discoverClaudeCodeMcps (strips) and hasAmicusRegistration (does not —
+ * it needs to SEE the amicus entry the strip would otherwise hide).
  *
  * @param {string} [claudeDir] - Path to ~/.claude directory (for testing)
  * @param {string} [claudeJsonPath] - Path to ~/.claude.json (for testing)
- * @returns {object|null} Merged MCP server configs, or null if none found
+ * @returns {object} Merged MCP server configs (never stripped); {} if none found
  */
-function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
+function readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath) {
   const baseDir = claudeDir || path.join(os.homedir(), '.claude');
   const jsonPath = claudeJsonPath || path.join(os.homedir(), '.claude.json');
 
@@ -71,14 +70,12 @@ 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 = stripSelfMcpEntries({ ...claudeJsonServers }, logger);
-      return Object.keys(merged).length > 0 ? merged : null;
+      return { ...claudeJsonServers };
     }
     const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
     const enabledPlugins = settings.enabledPlugins;
     if (!enabledPlugins || typeof enabledPlugins !== 'object') {
-      const merged = stripSelfMcpEntries({ ...claudeJsonServers }, logger);
-      return Object.keys(merged).length > 0 ? merged : null;
+      return { ...claudeJsonServers };
     }
 
     let installedPlugins = {};
@@ -133,12 +130,51 @@ function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
   }
 
   // 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 { ...pluginServers, ...claudeJsonServers };
+}
 
+/**
+ * Discover MCP servers from Claude Code's plugin chain AND ~/.claude.json.
+ *
+ * Discovery sources (merged, in priority order):
+ * 1. ~/.claude.json → mcpServers  (servers added via `claude mcp add`)
+ * 2. Enabled plugins → .mcp.json entries
+ *
+ * @param {string} [claudeDir] - Path to ~/.claude directory (for testing)
+ * @param {string} [claudeJsonPath] - Path to ~/.claude.json (for testing)
+ * @returns {object|null} Merged MCP server configs, or null if none found
+ */
+function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
+  // Recursive-spawn guard: drop every entry that resolves to amicus itself.
+  const merged = stripSelfMcpEntries(readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath), logger);
   return Object.keys(merged).length > 0 ? merged : null;
 }
 
+/**
+ * True when Claude Code already has a working amicus MCP registration —
+ * checked against the SAME raw sources discoverClaudeCodeMcps reads, but
+ * WITHOUT stripSelfMcpEntries. discoverClaudeCodeMcps strips every
+ * 'amicus'/'sidecar'-shaped entry as a recursive-spawn guard (src/utils/
+ * mcp-self-identity.js), so code.amicus is ALWAYS undefined downstream —
+ * that check is the wrong consumer to answer "is amicus registered?" (B14).
+ *
+ * True when any entry's key is literally 'amicus' (regardless of its value
+ * shape — an unrecognizable value under that key is still an amicus
+ * registration slot) OR its value passes isAmicusMcpConfig() (covers
+ * aliased keys, e.g. legacy 'sidecar' or a custom name, whose command/args
+ * resolve to an amicus MCP invocation).
+ *
+ * @param {string} [claudeDir] - Path to ~/.claude directory (for testing)
+ * @param {string} [claudeJsonPath] - Path to ~/.claude.json (for testing)
+ * @returns {boolean}
+ */
+function hasAmicusRegistration(claudeDir, claudeJsonPath) {
+  const servers = readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath) || {};
+  return Object.entries(servers).some(([name, config]) => (
+    name === 'amicus' || isAmicusMcpConfig(config)
+  ));
+}
+
 /**
  * Resolve Claude Desktop's per-platform config directory.
  * Mirrors the 3-way branch in src/environment.js getCoworkRoot (same
@@ -211,5 +247,6 @@ module.exports = {
   discoverParentMcps,
   discoverClaudeCodeMcps,
   discoverCoworkMcps,
+  hasAmicusRegistration,
   normalizeMcpJson
 };

package/src/utils/result-schema-version.js

@@ -0,0 +1,14 @@
+/**
+ * @module result-schema-version
+ * The single SCHEMA_VERSION constant shared by result-schema.js and
+ * abort-result.js (split out to avoid a circular require between them).
+ *
+ * Stability contract: fields on any doc built from this version are only
+ * ADDED within a SCHEMA_VERSION; any rename/removal bumps SCHEMA_VERSION.
+ */
+
+'use strict';
+
+const SCHEMA_VERSION = 2;
+
+module.exports = { SCHEMA_VERSION };

package/src/utils/result-schema.js

@@ -1,15 +1,13 @@
-// src/utils/result-schema.js
 'use strict';
 
 /**
  * @module result-schema
  * Versioned, machine-parseable result documents for `--json` output (F4).
- *
- * Stability contract: fields are only ADDED within a SCHEMA_VERSION;
- * any rename/removal bumps SCHEMA_VERSION.
+ * Stability contract: fields are only ADDED within a SCHEMA_VERSION; any
+ * rename/removal bumps SCHEMA_VERSION (defined in ./result-schema-version.js,
+ * split out so ./abort-result.js can depend on it without a circular require).
  */
-
-const SCHEMA_VERSION = 2;
+const { SCHEMA_VERSION } = require('./result-schema-version');
 
 /** Leg/run statuses that count as terminal for wave aggregation. */
 const TERMINAL_STATUSES = ['complete', 'error', 'timeout', 'aborted', 'crashed', 'idle-timeout'];
@@ -159,8 +157,7 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
  * @param {string} project - Project dir
  * @param {string} taskId
  * @returns {object} run document
- * @throws {Error} if the session does not exist
- * @throws {Error} if metadata.json is missing or corrupt
+ * @throws {Error} if the session does not exist or metadata.json is missing/corrupt
  */
 function buildRunResultFromSession(project, taskId) {
   const fs = require('fs');
@@ -189,8 +186,7 @@ function buildRunResultFromSession(project, taskId) {
  * @param {string} project
  * @param {string} waveId
  * @returns {object} wave document
- * @throws {Error} if the wave session does not exist
- * @throws {Error} if metadata.json is missing or corrupt
+ * @throws {Error} if the wave session does not exist or metadata.json is missing/corrupt
  */
 function buildWaveResultFromSession(project, waveId) {
   const fs = require('fs');
@@ -283,6 +279,9 @@ function buildDoctorDoc({ version, timestamp, checks }) {
   };
 }
 
+// buildAbortResult lives in ./abort-result.js (size-gate split); re-exported below.
+const { buildAbortResult } = require('./abort-result');
+
 module.exports = {
   SCHEMA_VERSION,
   TERMINAL_STATUSES,
@@ -297,4 +296,5 @@ module.exports = {
   buildCatalogDoc,
   buildAuditDoc,
   buildDoctorDoc,
+  buildAbortResult,
 };