amicus 1.9.1 → 2.1.0

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:
 
@@ -165,16 +166,16 @@ equivalent.
 
 Instruct models to emit the structured JSON verbatim after the prose, without preamble, so it parses cleanly.
 
-**After the wave returns, validate each leg's findings block** using `validateFindings` (Unit A — `src/council/findings.js`). If a leg's JSON fails validation:
+Save each leg's full output (prose + findings block) to the run folder as `review-<model>.md`
+(one file per reviewer) before moving on.
+
+**After the wave returns, validate each leg's findings block** by running `amicus council validate <leg-file> --json` (a thin CLI wrapper over `validateFindings`, Unit A — `src/council/findings.js`). It reads the leg's saved `review-<model>.md` and prints `{ok, findings, errors}`. Exit codes are a **tri-state** contract: `0` when `ok:true` (well-formed, proceed), `2` when `ok:false` (validation failed — a distinct, scriptable outcome, not a crash), `1` (`BAD_ARGS`) for a missing/unreadable file. If a leg's JSON fails validation (`ok:false` / exit 2):
 1. Issue a **solo `start --json`** re-prompt to that one model: "re-emit only the findings JSON, fixing: \<errors\>." Keep the first-pass prose. (Solo `start` passes through the **same budget gate** as `fanout`. If launching the wave required `--max-cost <$>` or `--no-cost-gate`, pass the **same flag on every repair re-prompt and on the chair call** — otherwise the gate can refuse a repair or the chair mid-council.)
 2. If still malformed, retry **once more** (cap = **2** re-prompts total).
 3. If still malformed after 2 retries, mark the review `unstructured` and hand-parse its prose into the schema. The review proceeds — never dropped for a formatting miss.
 
 Record per-model **conformance** (`clean` | `repaired` | `unstructured`) for inclusion in the tally input's `runStats` and the Stage-6 MODEL-NOTES note.
 
-Save each leg's full output (prose + findings block) to the run folder as `review-<model>.md`
-(one file per reviewer) before moving on.
-
 **"Claude in the council" (when toggled on):** Claude also produces a **fresh** Stage-1 review on the artifact in the identical findings format — a new structured pass on the artifact, not a formalization of anything said upstream. This review is added to the bundle as one more anonymous entry. Claude does not rank or adjudicate in Stage 2 (it holds the label map), and does not chair in Stage 3. Save it as `review-claude.md`.
 
 **Wave-degrade rules (Stage 1).** Read failures from the wave document — never silently ignore
@@ -210,7 +211,7 @@ amicus fanout --models "<m1,m2,m3>" --prompt-file <run-folder>/_tmp-bundle-stage
 (Background, same JSON handling as Stage 1.) Each judge's leg `summary` is its ranking +
 adjudication response. **Stage-2 degrade:** a judge leg dies → tally over the surviving judges
 (≥ 1) and disclose the reduced bench in `crossreview-matrix.md`; tier definitions are unchanged
-(they already count "judges engaged"). Each judge is asked to do two things on the bundle:
+(they already count "judges engaged").
 
 **Judge-briefing hardening (required).** Open `_tmp-bundle-stage2.md` with this preamble, verbatim, as its first line:
 
@@ -218,6 +219,8 @@ adjudication response. **Stage-2 degrade:** a judge leg dies → tally over the
 
 Plan-agent judges have wandered to tools mid-adjudication (reading files instead of judging and returning only narration), and a tool-capable judge can read the de-anonymized `review-<model>.md` files in the run folder — an anonymization leak. The preamble closes both. **Scratch-cwd (optional second layer):** launch the Stage-2 wave (and the Stage-3 chair call) with `--cwd <run-folder>/_scratch/` — create the empty directory first — so even a wandering agent finds nothing to read. Caveat: those legs' session records then live under `_scratch/.claude/amicus_sessions/`, so any later `amicus read <taskId>` for them needs the same `--cwd`.
 
+Each judge is asked to do two things on the bundle:
+
 **Task A — Rank.** Order the reviews from most to least accurate and insightful. End the response with a parseable block in exactly this format (no other text on those lines):
 
 ```
@@ -242,12 +245,14 @@ As each judge's ranking + adjudication response returns, collect it (the raw per
 
 **Five-keys checklist — verify `tally-input.json` has ALL of:** `meta` (with `meta.models`), `findings`, `adjudications`, `rankings`, `runStats` (`runStats` may be `[]`; the other four are required). Do not call `tally` until all five are present.
 
-Then call:
+Then call, saving the printed `record` to `<run-folder>/tally.json` (Stage 5's `amicus council verdict` reads it back from disk):
 
 ```
-amicus council tally <run-folder>/tally-input.json --json
+amicus council tally <run-folder>/tally-input.json --json > <run-folder>/tally.json
 ```
 
+**Windows PowerShell 5.1 caveat:** that `>` redirect writes UTF-16 under legacy Windows PowerShell 5.1 (fine on pwsh 7+ or bash), which corrupts `tally.json` for Stage 5's `amicus council verdict` and surfaces as a confusing `BAD_ARGS` there instead of here — on 5.1 pipe through `| Out-File -Encoding utf8` (or run under pwsh 7+) instead of a bare `>`.
+
 The output `record` carries the deterministic tiers (Disputed / Confirmed / Contested / Singleton), `confidence` (`solid` | `thin`), both street-cred numbers (`withSelf` and `peersOnly`), the validated `runStats`, and `tierCounts`. **Claude may override a `thin`-confidence tier at the margins** before Stage 4 — record the override in `tierOverride: {from, to, reason}`; the matrix and `verdict.json` surface it. De-anonymize and write the tally results to `crossreview-matrix.md` — the adjudication grid plus the street-cred table. This data feeds Stage 3 (chair briefing) and is never re-anonymized or forwarded to any council model.
 
 ---
@@ -334,7 +339,7 @@ Do not advance to Stage 5 until every finding in both tiers has a recorded decis
 - `review-<model>.md` × N (already saved in Stage 1)
 - `crossreview-matrix.md` — the de-anonymized adjudication grid and street-cred table
 - `verdict.md` (already saved in Stage 3)
-- `verdict.json` — write via `buildVerdict(record, decisions)` (`src/council/verdict.js`): pass the tally `record` from Stage 2 and the Stage-4 decision map (accepted / denied / modified / deferred per finding, plus any `duplicateOf` links Claude identified). This is the schema-stamped machine-readable record of the full run. Write it with an atomic tmp+rename to the run folder.
+- `verdict.json` — write by running `amicus council verdict <run-folder>/tally.json --decisions <run-folder>/decisions.json -o <run-folder>/verdict.json` (a thin CLI wrapper over `buildVerdict(record, decisions)` + `writeVerdictAtomic`, `src/council/verdict.js`). `<run-folder>/tally.json` is the `record` saved from the Stage-2 `amicus council tally` call. `<run-folder>/decisions.json` is a **JSON array**, one object per finding: `{id, decision, applied?, duplicateOf?, tierOverride?}` — `id` is the run-global label id (e.g. `A1`); `decision` is the Stage-4 outcome (accepted / denied / modified / deferred); `applied` (optional bool) marks whether the accepted change was actually applied to the artifact in Stage 5; `duplicateOf` (optional) links to another finding's id when Claude identified a duplicate; `tierOverride` (optional) carries any `{from, to, reason}` override recorded in Stage 2. Save this array to `<run-folder>/decisions.json` first, then run the command — it parses the tally record and the decisions file, calls `buildVerdict`, and writes the schema-stamped machine-readable record to the run folder via the same atomic tmp+rename convention the function always used.
 - `report.md` — the chair's synthesis + the full Stage-4 decision log + a summary of what was
   applied (+ the "How Claude's review fared" readout when "Claude in the council" is on) + a
   **run-stats table**: one row per model call — **stage** (which stage you launched the call for)
@@ -343,15 +348,17 @@ Do not advance to Stage 5 until every finding in both tiers has a recorded decis
   — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
   invent a figure. Add a wave **total cost** row from the wave document's
   `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`; never invent a value.
-  - **Renderer:** once `verdict.json` is written, generate BOTH renderings:
-    `amicus council report <run-folder>/verdict.json --md > <run-folder>/report.md` and
-    `amicus council report <run-folder>/verdict.json --html > <run-folder>/report.html`.
-    **`report.html` is the default final artifact to hand the user** — a self-contained,
-    shareable page. This emits the
+  - **Renderer:** once `verdict.json` is written, run
+    `amicus council report <run-folder>/verdict.json --html > <run-folder>/report.html` — a
+    **separate, deterministic** artifact, not report.md itself. **`report.html` is the default
+    final artifact to hand the user** — a self-contained, shareable page. This emits the
     adjudication matrix (finding × judge), the peers-only street-cred table, the
     findings-by-tier groupings (Disputed-first), and the per-model + wave cost —
-    deterministic data only. Prefer it over hand-assembling the matrix; reserve
-    prose for the chair's synthesis and the decision log.
+    deterministic data only. To assemble report.md, also run
+    `amicus council report <run-folder>/verdict.json --md` (no redirect — read its stdout) and
+    paste that Markdown into report.md as one section; reserve the rest of report.md's prose for
+    the chair's synthesis and the decision log. Prefer the renderer's Markdown over
+    hand-assembling the matrix by hand.
 
 Tell the user exactly which files were written and where, leading with `report.html`, **and present the verdict inline in chat** — the chair's overall assessment (verbatim or lightly trimmed) plus the tier counts (Confirmed/Disputed/Contested/Singleton) and what was applied. Never hand over only file paths.
 
@@ -465,14 +472,9 @@ Always **rank recommendations by fit**, state the trade-off for each option, and
   - `review-<model>.md` ×N — raw Stage 1 reviews (plus `review-claude.md` when "Claude in the council" is on)
   - `crossreview-matrix.md` — adjudication grid + de-anonymized street-cred table
   - `verdict.md` — the chair's synthesis (prose)
-  - `verdict.json` — schema-stamped machine-readable record: tally output + Stage-4 decisions, written via `buildVerdict(record, decisions)` at Stage 5
-  - `report.md` — synthesis + decision log + what was applied (+ the "How Claude's review fared" readout when the toggle is on) + a
-    **run-stats table**: one row per model call — **stage** (which stage you launched the call for) plus **model, status, durationMs, and cost** read from the wave/run JSON `usage`
-    block. Cost is `usage.cost.amount` (USD); mark it with its `usage.cost.source`
-    — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
-    invent a figure. Add a wave **total cost** row from the wave document's
-    `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`.
-  - `report.html` — the same report rendered as a self-contained page (`amicus council report <verdict.json> --html`); the default artifact to share.
+  - `verdict.json` — schema-stamped machine-readable record: tally output + Stage-4 decisions, written via `amicus council verdict` at Stage 5
+  - `report.md` — Claude-authored; full contract defined once in *Stage 5 → Run-folder artifacts* above (chair's synthesis + Stage-4 decision log + run-stats table).
+  - `report.html` — a **separate, deterministic** artifact generated by the `amicus council report <verdict.json> --html` renderer directly from `verdict.json` (no chair prose, no decision-log narrative — see Stage 5's *Renderer* note); the default artifact to share.
 - Reviewed copy: `<stem>-reviewed.<ext>`, next to the source.
 - Temp working files (`_tmp-*.md`: extracts, stage briefings, red-team brief, bundle, chair packet, proposed
   MODEL-NOTES diff) live in the run folder and are cleaned up at the end of the run — the proposed-diff file

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
 ```
@@ -747,13 +750,13 @@ The summary includes:
 
 ### Handling Config Update Notices
 
-When amicus emits `[AMICUS_CONFIG_UPDATE]` on stderr (or the legacy `[SIDECAR_CONFIG_UPDATE]` from older installs — accept either), the user's model aliases have changed (via `amicus setup`). The message contains a hash comment and a markdown alias table.
+When amicus emits `[AMICUS_CONFIG_UPDATE]` on stderr, the user's model aliases have changed (via `amicus setup`). The message contains a hash comment and a markdown alias table.
 
 **Action required:**
 1. Find the "Model Aliases" section in the project's CLAUDE.md
 2. Replace that section's content with the block provided in the message
 3. If no "Model Aliases" section exists, add one after the title line
-4. Do **not** remove the `<!-- amicus-config-hash: ... -->` comment (legacy files may use `<!-- sidecar-config-hash: ... -->` — do not remove whichever is present) — it tracks config changes and prevents duplicate notifications
+4. Do **not** remove the `<!-- amicus-config-hash: ... -->` comment — it tracks config changes and prevents duplicate notifications
 
 The update is purely informational (alias mappings) and safe to apply without user confirmation.
 
@@ -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)" \
@@ -846,7 +849,7 @@ The mutex approach looks correct. Add tests."
 
 ### "Missing Authentication header" in Claude Code or CI
 
-API keys in `~/.zshrc` are not available in non-interactive shells. Resolution order: `process.env` > `~/.config/amicus/.env` (legacy `~/.config/sidecar/.env` still read) > `~/.local/share/opencode/auth.json` (first wins). Fix:
+API keys in `~/.zshrc` are not available in non-interactive shells. Resolution order: `process.env` > `~/.config/amicus/.env` (the legacy `~/.config/sidecar/.env` fallback was removed in v2.0.0 — see `docs/SHIMS.md`) > `~/.local/share/opencode/auth.json` (first wins). Fix:
 1. Run `amicus setup` (stores keys in `~/.config/amicus/.env`)
 2. Or move exports to `~/.zshenv`
 3. Or add credentials to `~/.local/share/opencode/auth.json`

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-council.js

@@ -6,6 +6,13 @@ const { deriveReliability, appendRun } = require('./council/ledger');
 const { sumWaveUsage, formatCost } = require('./utils/pricing');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { buildReport } = require('./council/report');
+const { validateFindings } = require('./council/findings');
+const { buildVerdict, writeVerdictAtomic } = require('./council/verdict');
+const {
+  runSave: runCouncilSave,
+  runList: runCouncilList,
+  runShow: runCouncilShow,
+} = require('./council/presets-cli');
 
 function runTally(inputPath, useJson, opts = {}) {
   if (!inputPath) {
@@ -87,6 +94,93 @@ function runReport(args, useJson) {
   return 0;
 }
 
+/**
+ * `amicus council validate <file>` — thin wrapper over `validateFindings`
+ * (src/council/findings.js). Tri-state outcome, distinct from the usual
+ * two-state (0/1) CLI convention:
+ *   exit 0  ok:true              — findings block is well-formed
+ *   exit 2  ok:false             — findings block parsed as a *result*, but
+ *                                  validation failed (a distinct, scriptable
+ *                                  outcome — mirrors the repo's exit-2
+ *                                  "completed-with-failure" convention)
+ *   exit 1  BAD_ARGS envelope    — missing/unreadable input file
+ */
+function runValidate(filePath, useJson) {
+  if (!filePath) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council validate needs a <file> path',
+      hint: 'amicus council validate <file> [--json]' });
+  }
+  let text;
+  try { text = fs.readFileSync(filePath, 'utf-8'); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read ${filePath}: ${e.message}`,
+      hint: 'pass a Stage-1 reviewer output file (prose + trailing ```json findings block)' });
+  }
+  const result = validateFindings(text);
+  process.stdout.write(useJson ? JSON.stringify(result, null, 2) + '\n' : renderValidate(result));
+  return result.ok ? 0 : 2;
+}
+
+function renderValidate(result) {
+  if (result.ok) {
+    const hist = {};
+    for (const f of result.findings) { hist[f.severity] = (hist[f.severity] || 0) + 1; }
+    const parts = Object.keys(hist).map(sev => `${sev} ${hist[sev]}`).join(', ');
+    const n = result.findings.length;
+    return `OK — ${n} finding${n === 1 ? '' : 's'}${parts ? ` (${parts})` : ''}\n`;
+  }
+  return 'INVALID\n' + result.errors.map(e => `  ${e.code}: ${e.detail}`).join('\n') + '\n';
+}
+
+/**
+ * `amicus council verdict <tally.json> --decisions <decisions.json> [-o|--out <out.json>]`
+ * Thin wrapper over `buildVerdict` + `writeVerdictAtomic` (src/council/verdict.js).
+ * `--decisions` is optional (buildVerdict defaults decisions to []). Writes to
+ * `-o`/`--out` (default `./verdict.json`) via the atomic tmp+rename convention.
+ */
+function runVerdict(args, useJson) {
+  const tallyPath = args._[2];
+  if (!tallyPath) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council verdict needs a <tally.json> path',
+      hint: 'amicus council verdict <tally.json> [--decisions <decisions.json>] [-o|--out <out.json>]' });
+  }
+  let record;
+  try { record = JSON.parse(fs.readFileSync(tallyPath, 'utf-8')); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read ${tallyPath}: ${e.message}`,
+      hint: 'pass a valid tally.json (from `amicus council tally` / amicus_council_tally)' });
+  }
+  let decisions = [];
+  const decisionsPath = args.decisions;
+  if (decisionsPath) {
+    try { decisions = JSON.parse(fs.readFileSync(decisionsPath, 'utf-8')); }
+    catch (e) {
+      return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read --decisions ${decisionsPath}: ${e.message}`,
+        hint: 'pass a valid decisions.json array or omit --decisions' });
+    }
+  }
+  const outPath = args.out || './verdict.json';
+  let verdict;
+  try { verdict = buildVerdict(record, decisions); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot build verdict: ${e.message}`,
+      hint: 'either tally.json needs meta, findings[], streetCred[], runStats, tierCounts, or decisions.json must be a JSON array of {id, decision, …} objects' });
+  }
+  writeVerdictAtomic(outPath, verdict);
+  process.stdout.write(useJson ? JSON.stringify(verdict, null, 2) + '\n' : renderVerdict(verdict, outPath));
+  return 0;
+}
+
+function renderVerdict(v, outPath) {
+  const counts = {};
+  for (const f of v.findings) {
+    const key = f.decision || 'undecided';
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  const parts = Object.keys(counts).map(k => `${k} ${counts[k]}`).join('  ');
+  return `Verdict (schema v${v.schemaVersion}, ${v.runId}) → ${outPath}\n  ${parts}\n`;
+}
+
 /** @param {{_:string[], json?:boolean}} args @returns {Promise<number>} */
 async function handleCouncil(args) {
   const sub = args._[1];
@@ -94,8 +188,14 @@ async function handleCouncil(args) {
   if (sub === 'tally') { return runTally(args._[2], useJson, { append: !args['no-ledger'] }); }
   if (sub === 'stats') { return runStats(useJson); }
   if (sub === 'report') { return runReport(args, useJson); }
+  if (sub === 'validate') { return runValidate(args._[2], useJson); }
+  if (sub === 'verdict') { return runVerdict(args, useJson); }
+  if (sub === 'save') { return runCouncilSave(args._[2], args.models, useJson); }
+  if (sub === 'list') { return runCouncilList(useJson); }
+  if (sub === 'show') { return runCouncilShow(args._[2], useJson); }
   return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
-    message: `unknown council subcommand '${sub || ''}'`, hint: 'amicus council tally|stats|report' });
+    message: `unknown council subcommand '${sub || ''}'`,
+    hint: 'amicus council tally|stats|report|validate|verdict|save|list|show' });
 }
 
 module.exports = { handleCouncil };