amicus 2.0.0 → 2.2.0

package/src/cli-handlers-abort.js

@@ -0,0 +1,244 @@
+/**
+ * CLI Abort Handler (B21-rest extraction)
+ *
+ * Split out of src/cli-handlers.js — that file was already near the 300-line
+ * size gate and had no headroom for the --json branch added here. Re-exported
+ * from src/cli-handlers.js so existing callers/tests are unaffected.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { validateTaskId, safeSessionDir } = require('./utils/validators');
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
+const { buildAbortResult } = require('./utils/result-schema');
+
+/**
+ * Handle 'amicus abort --all --json': mark every running session aborted.
+ * @returns {number} exit code (always 0 — even a no-op --all is a success)
+ */
+function handleAbortAllJson(project) {
+  const { enumerateSessions } = require('./sidecar/read');
+  const { markAborted } = require('./utils/session-abort');
+  const { resolveExistingSessionDir } = require('./session-manager');
+  const running = enumerateSessions(project, { status: 'running' });
+  const aborted = [];
+  for (const s of running) {
+    if (markAborted(resolveExistingSessionDir(project, s.id), 'abort --all')) { aborted.push(s.id); }
+  }
+  console.log(JSON.stringify(buildAbortResult({ scope: 'all', taskId: null, aborted }), null, 2));
+  return 0;
+}
+
+/**
+ * Handle 'amicus abort <taskId> --json' for a single session or a wave.
+ * Mirrors the human-mode logic in handleAbort below but emits ONE doc on
+ * stdout instead of the multi-line console.log prose; the same waitThenKill
+ * fallback still runs, its narration routed to stderr instead of stdout.
+ * @returns {Promise<number>} exit code (always 0 for a resolved abort doc/error
+ *   doc — both are "the command ran"; ok:false is signaled inside the doc)
+ */
+async function handleAbortTaskJson(args, taskId) {
+  const project = args.cwd || process.cwd();
+  const sessionDir = safeSessionDir(project, taskId);
+  const metaPath = path.join(sessionDir, 'metadata.json');
+
+  if (!fs.existsSync(metaPath)) {
+    process.exit(failJson(true, { code: ERROR_CODES.BAD_SESSION, message: `Session ${taskId} not found` }));
+  }
+
+  let meta;
+  try {
+    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } catch (_err) {
+    process.exit(failJson(true, { code: ERROR_CODES.BAD_SESSION, message: `Session ${taskId} has malformed metadata` }));
+  }
+
+  if (meta.status !== 'running') {
+    // Not a hard error — the task exists — but nothing was aborted by this call.
+    // Scope must reflect the task's own type (wave vs session), not assume
+    // 'session' — a terminal wave still has meta.type === 'wave'.
+    const scope = meta.type === 'wave' ? 'wave' : 'session';
+    console.log(JSON.stringify(buildAbortResult({ scope, taskId, aborted: [] }), null, 2));
+    return 0;
+  }
+
+  const { markAborted } = require('./utils/session-abort');
+
+  if (meta.type === 'wave') {
+    const { resolveExistingSessionDir } = require('./session-manager');
+    const aborted = [];
+    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'));
+        if (legMeta.status === 'running') {
+          if (markAborted(legDir, 'wave abort')) { aborted.push(legId); }
+        }
+      } catch { /* skip unreadable leg */ }
+    }
+    // Only report the wave itself as aborted if its own markAborted write
+    // succeeded — mirrors the leg gating above and the --all/single-session
+    // gating (aborted[] must list ids ACTUALLY marked aborted per
+    // buildAbortResult's doc-comment).
+    if (markAborted(sessionDir, 'manual abort')) { aborted.unshift(taskId); }
+    console.log(JSON.stringify(buildAbortResult({ scope: 'wave', taskId, aborted }), null, 2));
+    return 0;
+  }
+
+  const wasMarked = markAborted(sessionDir, 'manual abort');
+
+  // Same fallback direct-kill as human mode (see the comment on the
+  // equivalent block in handleAbort below) — json mode still needs the
+  // process actually signalled, it just can't narrate it on stdout (stdout
+  // must carry ONLY the doc). Route the same chatter to stderr instead.
+  if (meta.pid) {
+    const { waitThenKill, abortGraceMs } = require('./utils/abort-coordinator');
+    const graceSec = Math.ceil(abortGraceMs() / 1000);
+    process.stderr.write(`Waiting up to ${graceSec}s for the session process (pid ${meta.pid}) to exit gracefully...\n`);
+    const { killed, exited } = await waitThenKill(meta.pid);
+    if (killed.length > 0) {
+      process.stderr.write(`Process ${meta.pid} did not exit in time — sent SIGTERM (a hard kill on Windows).\n`);
+    } else if (exited.length > 0) {
+      process.stderr.write('Process exited cleanly.\n');
+    } else {
+      process.stderr.write(`Process ${meta.pid} is still running — could not signal it (insufficient permission). It may require manual termination.\n`);
+    }
+  }
+
+  // aborted[] must list ids ACTUALLY marked aborted (buildAbortResult's doc
+  // comment) — gate on markAborted's own return, matching --all/wave-leg gating.
+  console.log(JSON.stringify(buildAbortResult({ scope: 'session', taskId, aborted: wasMarked ? [taskId] : [] }), null, 2));
+  return 0;
+}
+
+/**
+ * Handle 'sidecar abort' command
+ * Marks a running session as aborted
+ * @returns {Promise<number|undefined>} exit code (json mode only; human mode
+ *   uses process.exit internally on failure paths and implicitly returns 0)
+ */
+async function handleAbort(args) {
+  const useJson = !!args.json;
+
+  if (args.all) {
+    const project = args.cwd || process.cwd();
+    if (useJson) { return handleAbortAllJson(project); }
+
+    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 0;
+    }
+    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 0;
+  }
+
+  const taskId = args._[1];
+
+  if (!taskId) {
+    if (useJson) { process.exit(failJson(true, { code: ERROR_CODES.BAD_SESSION, message: 'Error: task_id is required for abort' })); }
+    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) {
+    if (useJson) { process.exit(failJson(true, { code: ERROR_CODES.BAD_SESSION, message: taskIdCheck.error })); }
+    console.error(taskIdCheck.error);
+    process.exit(1);
+  }
+
+  if (useJson) { return await handleAbortTaskJson(args, taskId); }
+
+  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 0;
+  }
+
+  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 0;
+  }
+
+  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.`);
+    }
+  }
+  return 0;
+}
+
+module.exports = { handleAbort };

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