amicus 2.0.0 → 2.2.0

package/src/mcp-server.js

@@ -205,13 +205,13 @@ function appendVersionWarning(content) {
  */
 function computeNextPoll() {
   return {
-    hint: 'Run `sleep 25` in your shell before calling amicus_status again. This enforces the wait and prevents token-wasting rapid polls. Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true.',
+    hint: 'Preferred: call amicus_wait with this task ID — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): run `sleep 25` in your shell before calling amicus_status again. This enforces the wait and prevents token-wasting rapid polls.',
     wait_command: 'sleep 25',
   };
 }
 
-const HEADLESS_START_REMINDER = '<system-reminder>IMPORTANT: Before calling amicus_status, you MUST run `sleep 25` in your shell first. This enforces the polling interval and prevents token waste. Do other useful work while waiting, or run `sleep 25` to block until the next poll window. Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true.</system-reminder>';
-const HEADLESS_STATUS_REMINDER = '<system-reminder>IMPORTANT: This session is still running. Before calling amicus_status again, you MUST run `sleep 25` in your shell first. Each premature poll wastes context tokens for zero benefit. Run `sleep 25` now, then check again. Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true.</system-reminder>';
+const HEADLESS_START_REMINDER = '<system-reminder>Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): before calling amicus_status, you MUST run `sleep 25` in your shell first. This enforces the polling interval and prevents token waste. Do other useful work while waiting, or run `sleep 25` to block until the next poll window.</system-reminder>';
+const HEADLESS_STATUS_REMINDER = '<system-reminder>Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): this session is still running. Before calling amicus_status again, you MUST run `sleep 25` in your shell first. Each premature poll wastes context tokens for zero benefit. Run `sleep 25` now, then check again.</system-reminder>';
 
 /** Spawn an Amicus CLI process (fire-and-forget) */
 function spawnSidecarProcess(args, sessionDir) {
@@ -672,7 +672,8 @@ const handlers = {
       const legsTotal = (readMeta.legs || []).length;
       const stillRunning = !readMeta.status || readMeta.status === 'running';
       const msg = stillRunning
-        ? `Wave ${input.taskId} is still running (${legsTotal} legs). Poll amicus_status.`
+        ? `Wave ${input.taskId} is still running (${legsTotal} legs). Preferred: call amicus_wait ` +
+          'with this waveId — one blocking call replaces polling. Fallback: poll amicus_status.'
         : `Wave ${input.taskId} ended with status '${readMeta.status}' before writing wave.json ` +
           '(fan-out may have been killed). Read individual legs by taskId, or use mode \'metadata\'.';
       return textResult(msg);
@@ -976,7 +977,9 @@ const handlers = {
 
     const body = JSON.stringify({
       waveId, taskIds: legIds, status: 'running', mode: 'headless',
-      message: 'Fan-out started. Poll amicus_status with the waveId; amicus_read the waveId when complete.',
+      message: 'Fan-out started. Preferred: call amicus_wait with the waveId — one blocking call ' +
+        'replaces polling; re-call it while it returns timedOut: true. Fallback: poll amicus_status ' +
+        'with the waveId. Either way, amicus_read the waveId when complete.',
     });
     return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
   },

package/src/mcp-tools.js

@@ -44,8 +44,11 @@ function getTools() {
       'ALWAYS use HEADLESS (noUi: true) for all of them unless the user ' +
       'explicitly requests interactive. Opening multiple Electron windows ' +
       'at once is disruptive. ' +
-      'For headless mode, ALWAYS run `sleep 25` in your shell before each ' +
-      'amicus_status call to enforce the polling interval. ' +
+      'For headless mode, prefer calling amicus_wait with the task ID — one ' +
+      'blocking call replaces the sleep+status loop; re-call it while it returns ' +
+      'timedOut: true. Fallback (no amicus_wait tool available): ALWAYS run ' +
+      '`sleep 25` in your shell before each amicus_status call to enforce the ' +
+      'polling interval. ' +
       'For interactive mode, do not poll. Wait for the user to tell you ' +
       'they\'ve clicked Fold, then use amicus_read. ' +
       'Call amicus_guide first if you need help choosing a model or writing a good briefing.' +
@@ -61,9 +64,9 @@ function getTools() {
       ),
       agent: z.enum(['Chat', 'Plan', 'Build']).optional()
         .default('Chat').describe(
-          'Agent mode. Chat (default): reads auto, writes ask ' +
-          'permission. Plan: read-only analysis. Build: full auto ' +
-          '(all operations approved).'
+          'Agent mode. Chat (interactive default; headless runs auto-convert ' +
+          'to Build): reads auto, writes ask permission. Plan: read-only ' +
+          'analysis. Build: full auto (all operations approved).'
         ),
       noUi: z.boolean().optional().default(false).describe(
         'Run headless without GUI. Default false (opens Electron window).'
@@ -215,7 +218,8 @@ function getTools() {
     description:
       'Reopen a previous Amicus session with full conversation history ' +
       'preserved. The session continues in the same OpenCode session. ' +
-      'Returns a task ID immediately — use amicus_status to poll.',
+      'Returns a task ID immediately — use amicus_wait to block until done ' +
+      '(or poll amicus_status).',
     inputSchema: {
       taskId: safeTaskId.describe(
         'The task ID of the session to resume.'
@@ -238,7 +242,7 @@ function getTools() {
       'Start a new Amicus session that inherits a previous session\'s ' +
       'conversation as context. The previous session\'s messages become ' +
       'read-only background for the new task. Returns a task ID ' +
-      'immediately — use amicus_status to poll.',
+      'immediately — use amicus_wait to block until done (or poll amicus_status).',
     inputSchema: {
       taskId: safeTaskId.describe(
         'The task ID of the previous session to continue from.'
@@ -296,10 +300,12 @@ function getTools() {
     description:
       'Run N models on the SAME prompt in parallel (one shared engine) and ' +
       'aggregate the results. Headless only. Returns {waveId, taskIds[]} ' +
-      'immediately. Poll amicus_status with the waveId (run `sleep 25` between ' +
-      'polls); when done, amicus_read the waveId for the aggregated JSON wave ' +
-      'document (per-leg summaries inside). Each leg is also an ordinary ' +
-      'session readable by taskId.',
+      'immediately. Preferred: call amicus_wait with the waveId — one blocking ' +
+      'call replaces polling; re-call it while it returns timedOut: true. ' +
+      'Fallback (no amicus_wait tool available): poll amicus_status with the ' +
+      'waveId (run `sleep 25` between polls). Either way, amicus_read the waveId ' +
+      'when done for the aggregated JSON wave document (per-leg summaries ' +
+      'inside). Each leg is also an ordinary session readable by taskId.',
     inputSchema: {
       models: z.array(safeModel).min(1).max(10).optional().describe(
         `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
@@ -442,16 +448,18 @@ Amicus spawns parallel conversations with different LLMs and folds results back
 
 ### Headless Mode (noUi: true)
 1. amicus_start with model + prompt + noUi: true -> get task ID
-2. Run \`sleep 25\` in your shell (this enforces the polling interval)
-3. amicus_status to check progress
-4. If still running, run \`sleep 25\` again before each subsequent amicus_status call
-5. amicus_read to get the summary once complete
-6. Act on findings
+2. **Preferred:** call amicus_wait with the task ID — one blocking call (up to
+   ~50s) replaces the sleep+status loop; re-call it while it returns timedOut: true
+3. amicus_read to get the summary once complete
+4. Act on findings
 
-(Alternative to steps 2-4: call amicus_wait with the task ID — one call blocks
-up to ~50s and returns status; call it again while it returns timedOut: true.)
+**Fallback (only if amicus_wait is unavailable):**
+1. Run \`sleep 25\` in your shell (this enforces the polling interval)
+2. amicus_status to check progress
+3. If still running, run \`sleep 25\` again before each subsequent amicus_status call
+4. amicus_read to get the summary once complete
 
-**IMPORTANT:** Always run \`sleep 25\` before every amicus_status call. This is not optional. Each premature poll wastes context tokens for zero benefit. The sleep command enforces the wait mechanically.
+**IMPORTANT (fallback path only):** Always run \`sleep 25\` before every amicus_status call. This is not optional. Each premature poll wastes context tokens for zero benefit. The sleep command enforces the wait mechanically.
 
 ### Interactive Mode (noUi: false, default)
 1. amicus_start with model + prompt -> get task ID
@@ -463,17 +471,19 @@ up to ~50s and returns status; call it again while it returns timedOut: true.)
 ### Fan-Out (amicus_fanout)
 Run the SAME prompt across 1-10 models in parallel (one shared engine):
 1. amicus_fanout with models + prompt -> {waveId, taskIds[]}
-2. sleep 25, then amicus_status with the waveId (repeat until done), or call amicus_wait with the waveId
+2. **Preferred:** call amicus_wait with the waveId (re-call while timedOut: true). **Fallback:** sleep 25, then amicus_status with the waveId (repeat until done)
 3. amicus_read the waveId -> aggregated JSON wave document (per-leg summaries inside)
 Each leg is an ordinary session: read/resume/continue it by taskId.
 
 ## Agent Selection
 | Agent | Reads | Writes | Bash | Use When |
 |-------|-------|--------|------|----------|
-| Chat (default) | auto | asks | asks | Questions, analysis |
+| Chat (interactive default*) | auto | asks | asks | Questions, analysis |
 | Plan | auto | denied | denied | Read-only analysis |
 | Build | auto | auto | auto | Implementation tasks |
 
+* Headless (\`noUi\`) runs auto-convert Chat to Build — Chat would otherwise stall waiting on write/bash approval with no UI to approve it.
+
 ## Writing Good Briefings
 Include: Objective, Background, Files of interest, Success criteria, Constraints.
 

package/src/sidecar/continue.js

@@ -123,7 +123,7 @@ async function continueSidecar(options) {
     headless = false,
     timeout = 15,
     agent,
-    mcp, mcpConfig, client, noMcp, excludeMcp
+    mcp, mcpConfig, client, noMcp, excludeMcp, json = false
   } = options;
 
   // Load previous session data
@@ -185,10 +185,17 @@ async function continueSidecar(options) {
 
   try {
     if (headless) {
-      result = await runHeadless(
-        model, systemPrompt, userMessage, newTaskId, project,
-        timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers, nonce: foldNonce }
-      );
+      try {
+        result = await runHeadless(
+          model, systemPrompt, userMessage, newTaskId, 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: newTaskId };
+      }
       summary = result.summary ||
         '## Sidecar Results: No Output\n\nContinued session completed without summary.';
 
@@ -209,8 +216,8 @@ async function continueSidecar(options) {
     releaseLock(prevSessionDir);
   }
 
-  // Output summary
-  outputSummary(summary);
+  // Output summary (human mode only — json mode keeps stdout to the doc below)
+  if (!json) { outputSummary(summary); }
 
   // Load current metadata for finalization
   const metaPath = SessionPaths.metadataFile(sessionDir);
@@ -230,8 +237,16 @@ async function continueSidecar(options) {
     writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
     logger.error('Continuation completed with error', { taskId: newTaskId, error: meta.reason });
   } else {
-    finalizeSession(sessionDir, summary, project, meta, { status: terminal.status });
+    finalizeSession(sessionDir, summary, project, meta, { 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: newTaskId, metadata: finalMeta, result, summary, sessionDir });
+    console.log(JSON.stringify(doc, null, 2));
+  }
+
   return terminal.exitCode;
 }
 

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 };