amicus 2.0.0 → 2.1.0

package/src/cli-handlers-doctor.js

@@ -2,6 +2,8 @@
 'use strict';
 
 const HINTS = require('./utils/remediation-hints');
+// B14/4.3: 'mcp' + 'mcp-legacy' check bodies (mirrors the B15 tmpSweep split — see file header).
+const mcpChecks = require('./utils/doctor-mcp-checks');
 
 const MAX_CATALOG_AGE_MS = 24 * 60 * 60 * 1000; // 24h (mirrors model-catalog DEFAULT_MAX_AGE_MS)
 
@@ -39,8 +41,13 @@ function realDeps() {
     // stays separate; repair only runs when fix is requested.
     repairElectron: (opts) => require('./sidecar/electron-install').repairElectron(opts),
     fix: false,
-    discoverClaudeCodeMcps: () => require('./utils/mcp-discovery').discoverClaudeCodeMcps(),
     discoverCoworkMcps: () => require('./utils/mcp-discovery').discoverCoworkMcps(),
+    // B14: raw (unstripped) read — the PRIMARY 'mcp' check signal.
+    // discoverClaudeCodeMcps() always strips 'amicus'/'sidecar'-shaped
+    // entries (recursive-spawn guard, src/utils/mcp-self-identity.js) and so
+    // can never be used to detect a healthy registration — see
+    // utils/doctor-mcp-checks.js for the full rationale.
+    hasAmicusRegistration: () => require('./utils/mcp-discovery').hasAmicusRegistration(),
     inspectLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').inspectAllLegacySidecarEntries(),
     migrateLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').migrateLegacySidecar(),
     skillInstalled: () => {
@@ -175,59 +182,12 @@ async function runDoctorChecks(depsOverride = {}) {
       : { id: 'skills', name: 'Skills installed', status: 'warn', message: 'one or both skills missing', hint: `${HINTS.reinstall}  (re-runs the skill install)` }
   )));
 
-  checks.push(guard('mcp', 'MCP registration', () => {
-    const code = d.discoverClaudeCodeMcps();
-    const cowork = d.discoverCoworkMcps();
-    const inCode = !!(code && code.amicus);
-    const inCowork = !!(cowork && cowork.amicus);
-    // Primary signal: Claude Code MCP registration. Cowork/Desktop is reported as bonus only.
-    if (!inCode) {
-      return { id: 'mcp', name: 'MCP registration', status: 'warn', message: 'not registered in Claude Code', hint: `${HINTS.reinstall}  (or install the amicus plugin)` };
-    }
-    const extra = inCowork ? ', Cowork/Desktop' : '';
-    return { id: 'mcp', name: 'MCP registration', status: 'ok', message: `registered: Claude Code${extra}`, hint: null };
-  }));
+  checks.push(guard('mcp', 'MCP registration', () => mcpChecks.evaluateMcpRegistration(d)));
 
-  // 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.
-  checks.push(guard('mcp-legacy', 'Legacy sidecar MCP entry', () => {
-    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 };
-  }));
+  // Duplicate legacy 'sidecar' MCP registration check — logic lives in
+  // utils/doctor-mcp-checks.js (mirrors the B15 tmpSweep split) to keep this
+  // file under the 300-line size gate.
+  checks.push(guard('mcp-legacy', 'Legacy sidecar MCP entry', () => mcpChecks.evaluateLegacyMcpEntry(d)));
 
   checks.push(guard('sessions-index-tmp', 'Session index tmp files', () => tmpSweep.evaluateSessionIndexTmpSweep(d)));
 

package/src/cli-handlers-resume-continue.js

@@ -0,0 +1,103 @@
+/**
+ * CLI Resume/Continue Handlers (B21-rest extraction)
+ *
+ * Split out of src/cli-handlers-run.js (which stayed over the 300-line size
+ * gate once --json plumbing landed here) — same extraction rationale as the
+ * original WS-2 split of bin/amicus.js.
+ *
+ * Contains: handleResume, handleContinue
+ */
+
+'use strict';
+
+const { resolveModelFromArgs, validateFallbackModel } = require('./utils/start-helpers');
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
+const { requireNoUiForJson, requireValidTaskId } = require('./utils/cli-preflight');
+
+/**
+ * Handle 'amicus resume' command
+ * Spec Reference: §4.3
+ */
+async function handleResume(args) {
+  const useJson = !!args.json;
+  const taskId = requireValidTaskId(args, useJson, 'resume', 'Usage: amicus resume <task_id>');
+  requireNoUiForJson(args, useJson);
+
+  const { resumeAmicus } = require('./index');
+
+  try {
+    return await resumeAmicus({
+      taskId,
+      project: args.cwd,
+      headless: args['no-ui'],
+      timeout: args.timeout,
+      json: useJson,
+    });
+  } catch (err) {
+    // resumeSidecar throws a plain Error before it has a chance to consult
+    // `json` (e.g. the session directory doesn't exist) — under --json that
+    // must still land as ONE parseable envelope on stdout, not an uncaught
+    // throw. Non-json mode is unaffected: re-throw so bin/amicus.js's
+    // existing top-level catch prints `Error: <message>` exactly as before.
+    if (!useJson) { throw err; }
+    process.exit(failJson(true, { code: ERROR_CODES.BAD_SESSION, message: err.message }));
+  }
+}
+
+/**
+ * Handle 'amicus continue' command
+ * Spec Reference: §4.4
+ */
+async function handleContinue(args) {
+  const useJson = !!args.json;
+  const taskId = requireValidTaskId(args, useJson, 'continue', 'Usage: amicus continue <task_id> --prompt "..."');
+
+  // BL-1: accept --prompt-file (XOR --prompt) so the MCP handler can pass a long
+  // follow-up prompt via file, dodging the ~32KB Windows command-line cap.
+  if (args['prompt-file'] !== undefined) {
+    const { resolvePromptSource } = require('./utils/prompt-source');
+    const promptRes = resolvePromptSource(args);
+    if (promptRes.error) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error }));
+    }
+    args.prompt = promptRes.prompt;
+    delete args['prompt-file'];
+  }
+
+  if (!args.prompt && !args.briefing) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: 'Error: --prompt is required for continue' }));
+  }
+
+  requireNoUiForJson(args, useJson);
+
+  // F5: an explicitly passed --model gets the same resolution+validation as start.
+  if (args.model !== undefined) {
+    const { model, alias } = resolveModelFromArgs(args);
+    args.model = model;
+    args.model = await validateFallbackModel(args, alias);
+  }
+
+  const { continueAmicus } = require('./index');
+
+  try {
+    return await continueAmicus({
+      taskId,
+      newTaskId: args['task-id'],
+      briefing: args.prompt || args.briefing,
+      model: args.model,
+      project: args.cwd,
+      contextTurns: args['context-turns'],
+      contextMaxTokens: args['context-max-tokens'],
+      headless: args['no-ui'],
+      timeout: args.timeout,
+      json: useJson,
+    });
+  } catch (err) {
+    // Same rationale as handleResume above: continueSidecar/loadPreviousSession
+    // throws before consulting `json` when the PREVIOUS session doesn't exist.
+    if (!useJson) { throw err; }
+    process.exit(failJson(true, { code: ERROR_CODES.BAD_SESSION, message: err.message }));
+  }
+}
+
+module.exports = { handleResume, handleContinue };

package/src/cli-handlers-run.js

@@ -5,7 +5,9 @@
  * size gate and to make handlers unit-testable without running main().
  *
  * Contains: handleStart, handleFanout, handleRead
- * Remaining inline in bin/amicus.js: handleList, handleResume, handleContinue
+ * See also: src/cli-handlers-resume-continue.js (handleResume, handleContinue —
+ * split out to stay under the size gate) and src/cli-handlers.js (handleList
+ * remains inline in bin/amicus.js).
  */
 
 'use strict';
@@ -14,6 +16,7 @@ const { validateStartArgs } = require('./cli');
 const { validateTaskId } = require('./utils/validators');
 const { resolveModelFromArgs, validateFallbackModel } = require('./utils/start-helpers');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
+const { requireNoUiForJson } = require('./utils/cli-preflight');
 
 /**
  * Handle 'sidecar start' command
@@ -33,9 +36,7 @@ async function handleStart(args) {
     // prompt-file set and trip its mutually-exclusive branch.
     delete args['prompt-file'];
   }
-  if (args.json && !args['no-ui']) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --json requires --no-ui' }));
-  }
+  requireNoUiForJson(args, useJson);
 
   const mc = args['max-cost'];
   if (mc !== undefined && (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0)) {

package/src/cli-handlers.js

@@ -5,9 +5,11 @@
  * under the 300-line limit.
  */
 
-const fs = require('fs');
-const path = require('path');
-const { validateTaskId, safeSessionDir } = require('./utils/validators');
+'use strict';
+
+// handleAbort moved to src/cli-handlers-abort.js (B21-rest: --json branch
+// needed headroom this file didn't have). Re-exported below for compatibility.
+const { handleAbort } = require('./cli-handlers-abort');
 
 /**
  * Handle 'amicus setup' command
@@ -64,123 +66,6 @@ async function handleSetup(args) {
   await runInteractiveSetup();
 }
 
-/**
- * Handle 'sidecar abort' command
- * Marks a running session as aborted
- */
-async function handleAbort(args) {
-  if (args.all) {
-    const project = args.cwd || process.cwd();
-    const { enumerateSessions } = require('./sidecar/read');
-    const { markAborted } = require('./utils/session-abort');
-    const { resolveExistingSessionDir } = require('./session-manager');
-    // A session may complete between enumeration and the write (TOCTOU); the
-    // window is tiny for a local CLI and markAborted is best-effort, so we count
-    // only sessions actually marked aborted.
-    const running = enumerateSessions(project, { status: 'running' });
-    if (running.length === 0) {
-      console.log('No running sessions to abort.');
-      return;
-    }
-    let aborted = 0;
-    for (const s of running) {
-      if (markAborted(resolveExistingSessionDir(project, s.id), 'abort --all')) {
-        aborted++;
-        console.log(`Aborted ${s.id}`);
-      }
-    }
-    console.log(`Aborted ${aborted} running session(s).`);
-    return;
-  }
-
-  const taskId = args._[1];
-
-  if (!taskId) {
-    console.error('Error: task_id is required for abort');
-    console.error('Usage: amicus abort <task_id>');
-    process.exit(1);
-  }
-
-  const taskIdCheck = validateTaskId(taskId);
-  if (!taskIdCheck.valid) {
-    console.error(taskIdCheck.error);
-    process.exit(1);
-  }
-
-  const project = args.cwd || process.cwd();
-  const sessionDir = safeSessionDir(project, taskId);
-  const metaPath = path.join(sessionDir, 'metadata.json');
-
-  if (!fs.existsSync(metaPath)) {
-    console.error(`Session ${taskId} not found`);
-    process.exit(1);
-  }
-
-  let meta;
-  try {
-    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-  } catch (_err) {
-    console.error(`Session ${taskId} has malformed metadata`);
-    process.exit(1);
-  }
-  // Guard against a completed/terminal session: without this, metadata.pid
-  // still holds a value forever and `amicus abort <completed-task>` would
-  // wait the grace window then TerminateProcess whatever unrelated process
-  // now owns that (possibly recycled) pid. Mirrors MCP's amicus_abort guard
-  // (src/mcp-server.js) — same wording, no re-mark, no kill.
-  if (meta.status !== 'running') {
-    console.log(`Session ${taskId} is not running (status: ${meta.status}).`);
-    return;
-  }
-
-  const { markAborted } = require('./utils/session-abort');
-
-  // F4: aborting a wave aborts every still-running leg too.
-  if (meta.type === 'wave') {
-    const { resolveExistingSessionDir } = require('./session-manager');
-    let aborted = 0;
-    for (const legId of meta.legs || []) {
-      const legDir = resolveExistingSessionDir(project, legId);
-      try {
-        const legMeta = JSON.parse(fs.readFileSync(path.join(legDir, 'metadata.json'), 'utf-8'));
-        // TOCTOU: a leg may complete between this read and markAborted —
-        // best-effort, same contract as abort --all above.
-        if (legMeta.status === 'running') {
-          if (markAborted(legDir, 'wave abort')) { aborted++; }
-        }
-      } catch { /* skip unreadable leg */ }
-    }
-    markAborted(sessionDir, 'manual abort');
-    console.log(`Wave ${taskId} marked as aborted (${aborted} running leg(s) aborted).`);
-    return;
-  }
-
-  markAborted(sessionDir, 'manual abort');
-  console.log(`Session ${taskId} marked as aborted.`);
-
-  // Phase 3: fallback direct-kill for a session that does not honor the
-  // marker. Headless loops poll the marker every ~2s and the interactive
-  // abort watch does too, so the normal outcome is a graceful exit during
-  // the grace window; only a wedged/legacy process gets SIGTERM. The wait is
-  // awaited on purpose — bin/amicus.js arms its force-exit watchdog only
-  // after this handler returns.
-  if (meta.pid) {
-    const { waitThenKill, abortGraceMs } = require('./utils/abort-coordinator');
-    const graceSec = Math.ceil(abortGraceMs() / 1000);
-    console.log(`Waiting up to ${graceSec}s for the session process (pid ${meta.pid}) to exit gracefully...`);
-    const { killed, exited } = await waitThenKill(meta.pid);
-    if (killed.length > 0) {
-      console.log(`Process ${meta.pid} did not exit in time — sent SIGTERM (a hard kill on Windows).`);
-    } else if (exited.length > 0) {
-      console.log('Process exited cleanly.');
-    } else {
-      // 3.1 contract: an EPERM-unkillable pid lands in NEITHER array —
-      // it is still alive and we could not signal it. Say so honestly.
-      console.log(`Process ${meta.pid} is still running — could not signal it (insufficient permission). It may require manual termination.`);
-    }
-  }
-}
-
 /**
  * Handle 'amicus update' command
  * Updates amicus to the latest version

package/src/cli.js

@@ -442,6 +442,7 @@ Options for 'status':
   abort: `
 Options for 'abort':
   --all                        Abort all running sessions in this project
+  --json                       Emit the abort result as stable JSON
 `,
   read: `
 Options for 'read':
@@ -457,6 +458,7 @@ Options for 'continue':
   --model <model>              Optional. Override the model (alias or provider/model)
   --cwd <path>                 Project directory (default: cwd)
   --no-ui                      Run without GUI (autonomous mode)
+  --json                       With --no-ui: emit the run result as stable JSON
   --timeout <minutes>          Headless timeout (default: 15)
   --context-turns <N>          Max conversation turns (default: 50)
   --context-max-tokens <N>     Max context tokens (default: 80000)
@@ -466,6 +468,7 @@ Options for 'resume':
   <task_id>                    Required. Session to reopen (positional)
   --cwd <path>                 Project directory (default: cwd)
   --no-ui                      Run without GUI (autonomous mode)
+  --json                       With --no-ui: emit the run result as stable JSON
   --timeout <minutes>          Headless timeout (default: 15)
 `,
   council: `
@@ -546,6 +549,22 @@ Examples:
   amicus read abc123 --conversation
 `;
 
+// Commands handled directly in bin/amicus.js's switch that have no dedicated
+// USAGE_COMMAND_BLOCKS entry (their usage is covered by USAGE_HEADER's command
+// list only). Kept minimal and explicit rather than parsing the switch itself.
+const SWITCH_ONLY_COMMANDS = ['update'];
+
+/**
+ * Canonical list of top-level command names, for did-you-mean suggestions and
+ * any other consumer that needs "every command amicus recognizes" without a
+ * second hand-maintained list. Derived from USAGE_COMMAND_BLOCKS (the existing
+ * per-command help source of truth) plus SWITCH_ONLY_COMMANDS.
+ * @returns {string[]}
+ */
+function getCommandNames() {
+  return [...Object.keys(USAGE_COMMAND_BLOCKS), ...SWITCH_ONLY_COMMANDS];
+}
+
 /**
  * Get usage text.
  *
@@ -570,5 +589,6 @@ module.exports = {
   parseArgs,
   validateStartArgs,
   getUsage,
+  getCommandNames,
   DEFAULTS
 };

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