amicus 2.0.0 → 2.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -5,6 +5,68 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-07-04
+
+### Added
+
+- `--json` on `resume`, `continue`, and `abort`. `amicus resume <id> --no-ui --json` and
+  `amicus continue <id> --prompt "..." --no-ui --json` emit the same versioned run document as
+  `start --json` (a `continue` run's document carries the new continuation task id, not the old
+  one). `amicus abort <id|--all> --json` emits a new `type: 'abort'` document
+  (`{ schemaVersion, type, ok, scope, taskId, aborted, count }`) covering single-session, wave, and
+  `--all` aborts, success and failure alike — stdout carries exactly one parseable document either
+  way, and non-`--json` human output is unchanged (byte-identical pinned messages still hold).
+- Did-you-mean suggestions for unknown CLI commands: a near-miss typo like `amicus contnue` now
+  prints `Unknown command: contnue` followed by `Did you mean: continue` on stderr (still exits 1).
+  Suggestions are capped at 3 and only shown within edit-distance 2 of a known command; unrelated
+  garbage input gets no suggestion.
+
+### Changed
+
+- Agent-facing polling guidance now recommends `amicus_wait` first across every headless-flow
+  reminder, tool description, and guide section (MCP system-reminders, `amicus_start`/`amicus_resume`/
+  `amicus_continue`/`amicus_fanout` descriptions, `amicus_guide`'s headless workflow, and the
+  `second-opinion`/`sidecar` skill docs) — one blocking call replaces the sleep+status poll loop.
+  `sleep 25` + `amicus_status` polling remains documented as the explicit fallback for clients
+  without the `amicus_wait` tool; it is never presented as the only mechanism.
+
+### Fixed
+
+- `amicus doctor`'s MCP registration check no longer false-negatives on a healthy Claude Code
+  registration. The check's only signal was `discoverClaudeCodeMcps()`, which always strips every
+  `amicus`/`sidecar`-shaped entry as its own recursive-spawn guard — so the check could never see
+  its own registration and warned "not registered in Claude Code" even when one existed. The check
+  now reads the same config sources directly (unstripped) to answer "is amicus registered?".
+
+### CI / Security
+
+- `council-review.yml`: both fanout legs (review wave and synthesis) now request
+  `--summary-length normal` instead of `verbose`. `--summary-length` only shapes the prompt (there is
+  no engine-side output-token cap), so `verbose` was asking every model in the wave — on a paid CI
+  key — for maximally long output on every PR.
+- `council-review.yml`: the model-to-model handoff from the review wave into the synthesis leg is
+  now neutralized. The synthesis briefing previously concatenated raw model review text
+  (`reviews.md`) straight into another model's prompt with no sanitization; it now runs the same
+  neutralization (byte-identical sed rules, duplicated into the synthesis step's own shell) used on
+  the human-facing PR comment, and wraps the reviews in an explicit untrusted-data block before
+  handing them to the synthesis model. The comment path itself is unchanged.
+- `ci.yml`: the `quality` job now runs [actionlint](https://github.com/rhysd/actionlint) (pinned to
+  v1.7.7) over `.github/workflows/`, which also shellchecks every `run:` block via ubuntu-latest's
+  preinstalled shellcheck. Verified locally with the actionlint + shellcheck Windows binaries before
+  landing; both are clean against all 5 workflows (0 findings), so no suppression config was needed.
+
+### Documentation
+
+- Corrected the `--agent` default docs in `skills/sidecar/SKILL.md`: the flag defaults to `Chat`
+  only in interactive mode — headless (`--no-ui`) runs default to `Build`, since `chat` stalls
+  without user interaction. The file previously claimed an unqualified "defaults to Chat" in
+  several spots while also correctly documenting the headless-`Build` default elsewhere,
+  contradicting itself; `docs/usage.md` was already correct and unchanged.
+- Corrected `commands/council.md`'s description of the council pipeline order: `amicus council
+  validate` runs per-leg during Stage 1 (independent reviews), and `amicus council tally` runs
+  after Stage 2 (cross-review) and before Stage 3 (chair synthesis) — not, as previously worded,
+  both after all three review waves.
+
 ## [2.0.0] - 2026-07-03
 
 Amicus's first major release: the **`sidecar*` shim removal** (#19). v1.x carried a full

package/README.md

@@ -311,7 +311,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -11,12 +11,12 @@
 const { loadCredentials } = require('../src/utils/env-loader');
 loadCredentials();
 
-const { parseArgs, getUsage } = require('../src/cli');
-const { validateTaskId } = require('../src/utils/validators');
-const { resolveModelFromArgs, validateFallbackModel } = require('../src/utils/start-helpers');
+const { parseArgs, getUsage, getCommandNames } = require('../src/cli');
 const { handleSetup, handleAbort, handleUpdate, handleMcp, handleKey } = require('../src/cli-handlers');
 const { handleStart, handleFanout, handleRead } = require('../src/cli-handlers-run');
+const { handleResume, handleContinue } = require('../src/cli-handlers-resume-continue');
 const { isOneShotCommand, armExitWatchdog } = require('../src/utils/lifecycle');
+const { suggestCommand } = require('../src/utils/input-validators');
 const { logger } = require('../src/utils/logger');
 
 const VERSION = require('../package.json').version;
@@ -124,7 +124,7 @@ async function main() {
         await handleKey(args);
         break;
       case 'abort':
-        await handleAbort(args);
+        exitCode = await handleAbort(args);
         break;
       case 'mcp':
         await handleMcp();
@@ -132,10 +132,16 @@ async function main() {
       case 'update':
         await handleUpdate();
         break;
-      default:
+      default: {
         console.error(`Unknown command: ${command}`);
+        // suggestCommand honors a cap-3 contract (up to 3 candidates, closest
+        // first) — print all of them, not just the closest, matching the
+        // join precedent in src/cli-handlers.js.
+        const candidates = suggestCommand(command, getCommandNames());
+        if (candidates.length > 0) { console.error(`Did you mean: ${candidates.join(', ')}`); }
         console.log(getUsage());
         process.exit(1);
+      }
     }
   } catch (err) {
     console.error(`Error: ${err.message}`);
@@ -166,94 +172,6 @@ async function handleList(args) {
   });
 }
 
-/**
- * Handle 'sidecar resume' command
- * Spec Reference: §4.3
- */
-async function handleResume(args) {
-  const taskId = args._[1];
-
-  if (!taskId) {
-    console.error('Error: task_id is required for resume');
-    console.error('Usage: amicus resume <task_id>');
-    process.exit(1);
-  }
-
-  const taskIdCheck = validateTaskId(taskId);
-  if (!taskIdCheck.valid) {
-    console.error(taskIdCheck.error);
-    process.exit(1);
-  }
-
-  const { resumeAmicus } = require('../src/index');
-
-  return await resumeAmicus({
-    taskId,
-    project: args.cwd,
-    headless: args['no-ui'],
-    timeout: args.timeout
-  });
-}
-
-/**
- * Handle 'sidecar continue' command
- * Spec Reference: §4.4
- */
-async function handleContinue(args) {
-  const taskId = args._[1];
-
-  if (!taskId) {
-    console.error('Error: task_id is required for continue');
-    console.error('Usage: amicus continue <task_id> --prompt "..."');
-    process.exit(1);
-  }
-
-  const taskIdCheck = validateTaskId(taskId);
-  if (!taskIdCheck.valid) {
-    console.error(taskIdCheck.error);
-    process.exit(1);
-  }
-
-  // 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('../src/utils/prompt-source');
-    const promptRes = resolvePromptSource(args);
-    if (promptRes.error) {
-      console.error(promptRes.error);
-      process.exit(1);
-    }
-    args.prompt = promptRes.prompt;
-    delete args['prompt-file'];
-  }
-
-  if (!args.prompt && !args.briefing) {
-    console.error('Error: --prompt is required for continue');
-    process.exit(1);
-  }
-
-  // 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('../src/index');
-
-  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
-  });
-}
-
 // Run main
 main().catch(err => {
   console.error(`Fatal error: ${err.message}`);

package/commands/council.md

@@ -17,8 +17,10 @@ the **analysis request**, and the **criteria**. If any of the three is missing o
 ambiguous, ask for it before launching any model (the skill's Stage 0 covers this —
 don't re-ask for what is already present).
 
-Then follow the second-opinion skill end to end: Stage 0 intake/prep and run-folder
-setup, council selection with a cost estimate and explicit user confirmation, the
-three review waves, `amicus council validate` on each leg's findings block,
-`amicus council tally`, the accept/deny decision pass, and `amicus council verdict`
-to write the final `verdict.json`.
+Then follow the second-opinion skill end to end, in pipeline order: Stage 0
+intake/prep and run-folder setup, then council selection with a cost estimate
+and explicit user confirmation; Stage 1 independent reviews, running
+`amicus council validate` on each leg's findings block as it lands; Stage 2
+cross-review, followed by `amicus council tally` once cross-review settles;
+Stage 3 council-chair synthesis; Stage 4 the accept/deny decision pass; and
+Stage 5, which runs `amicus council verdict` to write the final `verdict.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [

package/skills/second-opinion/SKILL.md

@@ -31,7 +31,7 @@ Operating lessons from each run fold back into `MODEL-NOTES.md` (with approval),
 
 **Before launching any model, READ `MODEL-NOTES.md`** (next to this file). It holds the operating rules and per-model quirks that decide whether a run succeeds or silently fails. These were learned the hard way; skipping them wastes runs and produces empty results that look like answers.
 
-**Transport rule — CLI not on PATH:** every command below assumes the `amicus` CLI. If `amicus` is not on PATH (typical for **plugin-only installs**), run the identical commands as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest fanout --models "m1,m2,m3" --prompt-file <path> --json`), or use the equivalent MCP tools (`amicus_fanout`, `amicus_start`, `amicus_status`, `amicus_read`, `amicus_council_tally`, `amicus_council_stats`, `amicus_verdict`) — council briefings are always self-contained (`--no-context`), so MCP transport is equivalent.
+**Transport rule — CLI not on PATH:** every command below assumes the `amicus` CLI. If `amicus` is not on PATH (typical for **plugin-only installs**), run the identical commands as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest fanout --models "m1,m2,m3" --prompt-file <path> --json`), or use the equivalent MCP tools (`amicus_fanout`, `amicus_start`, `amicus_wait`, `amicus_status`, `amicus_read`, `amicus_council_tally`, `amicus_council_stats`, `amicus_verdict`) — council briefings are always self-contained (`--no-context`), so MCP transport is equivalent.
 
 ## When to use
 
@@ -124,7 +124,7 @@ Always quote the `--models` list — unquoted, PowerShell splits on commas and t
 
 Run it in the background (`run_in_background: true`); you are notified on completion — do not
 poll. `fanout` is headless by definition. The command exits when every leg is terminal and prints
-ONE JSON wave document on stdout (`schemaVersion: 1`; the wave's id field is `waveId`, each leg's id is `taskId`): check `status` (`complete` | `partial` |
+ONE JSON wave document on stdout (`schemaVersion: 2`; the wave's id field is `waveId`, each leg's id is `taskId`): check `status` (`complete` | `partial` |
 `error`), `counts`, and each leg in `legs[]` — a leg's `summary` field IS that model's review;
 `model`/`modelInput` identify the reviewer (`model` is the resolved id, `modelInput` the alias you passed — use the alias for `review-<model>.md` filenames); `status`/`error` identify failures. Exit code 0 =
 all legs complete, 2 = partial (apply the wave-degrade rules below), 1 = error/aborted. (To re-fetch a single leg later: `amicus read <taskId> --json`.)
@@ -141,9 +141,10 @@ amicus start --model <redteam-model> --no-ui --json \
 Its stdout is a single run document; the `summary` field is the review.
 
 **Cowork / no-Bash environments:** use the MCP tools instead — `amicus_fanout` (briefing via
-file) returns `{waveId, taskIds[]}` immediately; poll `amicus_status`, then `amicus_read` each
-leg. The council's briefings are always self-contained (`--no-context`), so MCP transport is
-equivalent.
+file) returns `{waveId, taskIds[]}` immediately. Preferred: call `amicus_wait` with the waveId —
+one blocking call per wave; re-call it while it returns `timedOut: true`. Fallback: poll
+`amicus_status`. Either way, `amicus_read` each leg when done. The council's briefings are always
+self-contained (`--no-context`), so MCP transport is equivalent.
 
 **Required structured output from every model.** Instruct each council model to produce:
 

package/skills/sidecar/SKILL.md

@@ -45,7 +45,7 @@ These rules are mandatory for every amicus invocation in this skill:
 5. **When the user asks to query MULTIPLE LLMs simultaneously** (e.g., "ask Gemini AND ChatGPT", "compare Gemini vs GPT"), ALWAYS use `--no-ui` (headless) for all of them unless the user explicitly requests interactive. Opening multiple Electron windows at once is disruptive. Launch them all in parallel with `run_in_background: true`.
 6. **When the SAME prompt should go to N models, use `amicus fanout --models "a,b,c" --prompt-file <path> --json`** (one headless wave, one JSON result) instead of N separate start calls. Different prompts per model → separate parallel `amicus start --no-ui` calls.
 7. **For a SINGLE-model sidecar, DEFAULT to interactive** — omit `--no-ui` so the Electron UI opens and the user can watch, converse, and click Fold. Use `--no-ui` for a single model only when the user asks for headless/autonomous, or for unattended bulk automation. Interactive launches still use `run_in_background: true`.
-8. **If `amicus` is not on PATH** (typical for plugin-only installs), run every command in this skill as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest start --model gemini --prompt "..."`), or use the MCP tools (`amicus_start`, `amicus_status`, `amicus_read`, …) instead. Do not conclude the tool is broken because `amicus` is not found.
+8. **If `amicus` is not on PATH** (typical for plugin-only installs), run every command in this skill as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest start --model gemini --prompt "..."`), or use the MCP tools (`amicus_start`, `amicus_wait`, `amicus_status`, `amicus_read`, …) instead. Do not conclude the tool is broken because `amicus` is not found.
 
 ## Installation
 
@@ -65,7 +65,7 @@ amicus --version
 
 ### MCP Server (Auto-Registered)
 
-On install, an MCP server is auto-registered for Claude Cowork and Claude Desktop. If you're in an MCP-enabled environment, you can use `amicus_start`, `amicus_status`, `amicus_read`, and other MCP tools directly instead of CLI commands. Call `amicus_guide` for detailed usage instructions.
+On install, an MCP server is auto-registered for Claude Cowork and Claude Desktop. If you're in an MCP-enabled environment, you can use `amicus_start`, `amicus_wait`, `amicus_status`, `amicus_read`, and other MCP tools directly instead of CLI commands. Call `amicus_guide` for detailed usage instructions.
 
 ---
 
@@ -177,7 +177,7 @@ amicus start --model anthropic/<model-name> --prompt "..."
 
 ### Agent Selection Guidelines
 
-**Chat mode (default)** — no `--agent` flag needed. Reads are auto-approved, writes and bash commands require user permission in the Electron UI:
+**Chat mode (interactive default)** — no `--agent` flag needed. Reads are auto-approved, writes and bash commands require user permission in the Electron UI:
 ```bash
 # Default — good for questions, analysis, and guided work
 amicus start --model gemini --prompt "Analyze the auth flow and suggest improvements"
@@ -199,7 +199,7 @@ amicus start --model gemini --prompt "Implement the login feature" --agent Build
 
 | Mode | Use When |
 |------|----------|
-| **Chat** (default) | Questions, analysis, guided exploration — you control what gets written |
+| **Chat** (interactive default) | Questions, analysis, guided exploration — you control what gets written |
 | **Plan** | Comprehensive read-only analysis where no changes should happen |
 | **Build** | Offloading implementation tasks where full autonomy is desired |
 
@@ -250,14 +250,17 @@ amicus start \
 - `--prompt-file <path>`: Read the prompt/briefing from a UTF-8 file (mutually exclusive with
   `--prompt`). Use for long or multi-line briefings.
 - `--json`: With `--no-ui`, emit the run result as one stable JSON document on stdout
-  (`schemaVersion: 1`; the `summary` field is the model's output).
+  (`schemaVersion: 2`; the `summary` field is the model's output).
 - `--no-validate-model`: Skip the model-catalog pre-flight check (validation is on by default).
-- `--agent <agent>`: Agent mode (controls tool permissions). If omitted, defaults to **Chat**.
+- `--agent <agent>`: Agent mode (controls tool permissions). If omitted, defaults to
+  **Chat** in interactive mode and **Build** in headless (`--no-ui`) mode — `chat`
+  stalls without user interaction, so headless runs need an agent that doesn't wait
+  on write/bash approval.
 
   **Primary Agents (for `amicus start`):**
-  - `Chat` **(default)**: Reads auto-approved, writes/bash require user permission
+  - `Chat` **(interactive default)**: Reads auto-approved, writes/bash require user permission
   - `Plan`: Read-only mode - no file modifications possible
-  - `Build`: Full tool access - all operations auto-approved
+  - `Build` **(headless default)**: Full tool access - all operations auto-approved
 
   **Custom Agents:**
   Custom agents defined in `~/.config/opencode/agents/` or `.opencode/agents/` are passed through directly.
@@ -573,16 +576,16 @@ Amicus uses OpenCode's agent framework with three primary modes:
 
 | Agent | Reads | Writes/Edits | Bash | Default |
 |-------|-------|-------------|------|---------|
-| **Chat** | auto | asks permission | asks permission | Yes |
+| **Chat** | auto | asks permission | asks permission | Interactive |
 | **Plan** | auto | denied | denied | No |
-| **Build** | auto | auto | auto | No |
+| **Build** | auto | auto | auto | Headless |
 
-#### Chat Agent (Default)
+#### Chat Agent (Interactive Default)
 
-Conversational mode — reads are auto-approved, writes and bash commands prompt for user permission in the UI. This is the default when no `--agent` flag is provided.
+Conversational mode — reads are auto-approved, writes and bash commands prompt for user permission in the UI. This is the default when no `--agent` flag is provided **in interactive mode**; headless (`--no-ui`) runs default to Build instead (see the Headless section below).
 
 ```bash
-# These are equivalent — Chat is the default
+# These are equivalent — Chat is the interactive default
 amicus start --model gemini --prompt "Analyze the auth flow"
 amicus start --model gemini --prompt "Analyze the auth flow" --agent Chat
 ```
@@ -781,7 +784,7 @@ If a relevant sidecar exists:
 ### Example 1: Interactive Debugging (Chat Mode - Default)
 
 ```bash
-# Default Chat mode — can read freely, asks before writing
+# Chat mode (interactive default) — can read freely, asks before writing
 amicus start \
   --model gpt \
   --session-id "$(ls -t ~/.claude/projects/-Users-john-myproject/*.jsonl | head -1 | xargs basename .jsonl)" \

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