amicus 1.7.7 → 1.8.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.7",
+  "version": "1.8.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,44 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-07-02
+
+### Added
+- **`amicus_wait` MCP tool: blocking wait for a session or fan-out wave.** Blocks inside one tool call until the
+  target reaches a terminal state or the wait window closes, replacing the sleep+`amicus_status` polling loop with
+  a single call. Returns the same JSON shape as `amicus_status` plus `waitedMs` and `{timedOut: true}` (with a
+  `hint`) on expiry — re-call it while it keeps returning `timedOut: true`. Works for sessions or waves started by
+  other processes, not just the caller. Torn-read tolerant: a transient read of `metadata.json` mid-write is
+  treated as a missed poll tick, not a hard failure. Legacy alias `sidecar_wait` is available under
+  `AMICUS_LEGACY_ALIASES=1`.
+- **Agent-visible progress.** A new `amicus status <task_id>` (or `--wave <id>`) one-shot CLI command delegates
+  directly to the MCP status handler — same crash detection and wave-leg rollup, zero duplicated logic.
+  `amicus_status` and `amicus_list` are enriched with agent-facing `mode`, `phase`, `messageCount`,
+  `lastActivityAt`, and `latestPreview` (the pinned raw `stage` field is unchanged for back-compat; wave legs
+  additionally surface the raw `stage` alongside the coarse `phase`). Interactive (Electron GUI) runs now write
+  the same lifecycle progress stages headless runs always have (`initializing`, `server_ready`, `session_created`,
+  `prompt_sent`), and long-thinking turns emit periodic thinking-delta progress ticks instead of at most one ever
+  — so a live GUI run no longer reads "Starting up... | 0 messages" forever.
+- **`amicus doctor` duplicate-registration check.** A new `mcp-legacy` check flags plugin-channel installs
+  (`AMICUS_SKIP_POSTINSTALL=1`) that never ran the postinstall migration and still carry a duplicate legacy
+  `sidecar` MCP registration; `doctor --fix` cleans it up.
+
+### Fixed
+- **`amicus abort` now actually stops interactive sessions and wave legs.** Marker-first, honest output — reports
+  what really happened including the unkillable-pid case — and no-ops cleanly with a clear message when the
+  target isn't running.
+- **Legacy-MCP remediation's `claude mcp add-json` (CLI) path no longer drops a user's custom `env`** on
+  re-registration — it now merges the previous registration's `env` the same way the file-fallback path already did.
+
+### Changed
+- **Legacy `sidecar_*` MCP tool aliases are now opt-in** via `AMICUS_LEGACY_ALIASES=1` (breaking-adjacent —
+  carrying release must be a MINOR, v1.8.0). The default client-visible surface is the `amicus_*` toolset (14
+  tools as of this release); saved allowlists that still reference `mcp__amicus__sidecar_*` stop resolving unless
+  you opt back in.
+- **Postinstall no longer registers a separate `sidecar` MCP server** and auto-removes a verified-identical
+  duplicate left over from pre-1.8 installs. A customized `sidecar` entry or a sole `sidecar` registration (no
+  `amicus` twin) is never touched.
+
 ## [1.7.7] - 2026-07-01
 
 Correctness patch from the 2026-07-01 full product review (multi-agent review, every finding adversarially

package/README.md

@@ -259,6 +259,7 @@ amicus update
 | `amicus resume` | Reopen a previous session with full history. |
 | `amicus continue` | Start a new session building on a previous one. |
 | `amicus read` | Output a session's summary / conversation / metadata. |
+| `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
 | `amicus abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
@@ -329,6 +330,10 @@ amicus read <id> --conversation      # full conversation
 amicus read <id> --metadata          # session metadata
 amicus read <id> --json              # stable JSON (run or wave document)
 
+amicus status <id>                   # one-shot status for a session or wave
+amicus status --wave <id>            # alternative spelling for a wave ID
+amicus status <id> --json            # machine-readable output
+
 amicus resume <id>                   # reopen with full history
 amicus continue <id> --prompt "..."  # new session, previous one as read-only context
 
@@ -371,12 +376,13 @@ amicus models --check         # audit your aliases against the catalog
 
 ## MCP integration
 
-The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes ten tools:
+The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes fourteen tools:
 
 | Tool | What it does |
 |------|--------------|
 | `amicus_start` | Spawn a session; returns a task ID immediately. |
 | `amicus_status` | Poll a task (or a fanout wave) for completion. |
+| `amicus_wait` | Block inside one tool call until a session/wave finishes or the wait window closes. |
 | `amicus_read` | Read results: summary, conversation, metadata, or JSON. |
 | `amicus_list` | List past sessions. |
 | `amicus_resume` | Reopen a session. |
@@ -385,8 +391,11 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `amicus_setup` | Open the setup wizard. |
 | `amicus_guide` | Return usage guidance (model choice, briefings, polling). |
 | `amicus_fanout` | Launch a same-prompt wave; returns `{ waveId, taskIds[] }`. |
+| `amicus_council_tally` | Aggregate a council wave's reviews into a scored tally. |
+| `amicus_council_stats` | Reviewer-reliability stats from past council runs. |
+| `amicus_verdict` | Build the final council verdict from a tally + decisions. |
 
-The async pattern is **start → status → read**: `amicus_start` (or `amicus_fanout`) returns immediately, you poll `amicus_status`, then `amicus_read` once it's done — so the calling agent never blocks.
+The async pattern is **start → status → read**: `amicus_start` (or `amicus_fanout`) returns immediately, you poll `amicus_status`, then `amicus_read` once it's done — so the calling agent never blocks. Prefer `amicus_wait` over manual sleep+status polling for headless runs: it collapses the poll loop into a single blocking call that returns as soon as the run finishes (or the wait window closes).
 
 To register manually (user scope):
 
@@ -394,7 +403,7 @@ To register manually (user scope):
 claude mcp add-json amicus '{"command":"npx","args":["-y","amicus@latest","mcp"]}' --scope user
 ```
 
-> Legacy `sidecar_*` tool names are still registered as aliases of each `amicus_*` tool for backward compatibility.
+> Legacy `sidecar_*` tool names are no longer registered by default (v1.8.0). To restore them, add `"env": {"AMICUS_LEGACY_ALIASES": "1"}` to the server entry. They will be removed entirely in the next major.
 
 ---
 

package/bin/amicus.js

@@ -94,6 +94,11 @@ async function main() {
       case 'list':
         await handleList(args);
         break;
+      case 'status': {
+        const { handleStatus } = require('../src/cli-handlers-status');
+        exitCode = await handleStatus(args);
+        break;
+      }
       case 'resume':
         exitCode = await handleResume(args);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.7",
+  "version": "1.8.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.",
   "keywords": [
     "claude",

package/scripts/postinstall.js

@@ -15,6 +15,7 @@ const { execFileSync } = require('child_process');
 
 const { repairElectron } = require('../src/sidecar/electron-install');
 const HINTS = require('../src/utils/remediation-hints');
+const { isAmicusMcpConfig } = require('../src/utils/mcp-self-identity');
 
 const SETUP_HOOKS_SCRIPT = path.join(__dirname, 'setup-hooks.js');
 
@@ -41,7 +42,18 @@ const MCP_CONFIG = { command: 'npx', args: ['-y', 'amicus@latest', 'mcp'] };
 
 /**
  * Add or update an MCP server in a JSON config file.
- * Always overwrites the entry to ensure upgrades apply the latest config.
+ *
+ * Refreshes command/args on every install/upgrade. If the EXISTING entry at
+ * this key is already amicus-shaped (per isAmicusMcpConfig — Phase 1's single
+ * source of truth for "this is amicus"), we MERGE instead of overwrite: the
+ * user's `env` (and any other extra keys, e.g. a future `cwd`) survive the
+ * refresh. Without this, `npm i -g amicus` silently wiped
+ * "env": {"AMICUS_LEGACY_ALIASES":"1"} — the exact opt-in escape hatch Phase 4
+ * tells users to add — on every upgrade.
+ *
+ * A NON-amicus-shaped entry at this key is overwritten as before: 'amicus' is
+ * a reserved registration name, so a foreign entry there is reclaimed rather
+ * than merged with.
  *
  * @param {string} configPath - Path to the JSON config file
  * @param {string} name - MCP server name
@@ -59,9 +71,10 @@ function addMcpToConfigFile(configPath, name, config) {
   if (!existing.mcpServers) { existing.mcpServers = {}; }
 
   const prev = existing.mcpServers[name];
-  const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(config) ? 'updated' : 'unchanged';
+  const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...config } : config;
+  const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(nextConfig) ? 'updated' : 'unchanged';
 
-  existing.mcpServers[name] = config;
+  existing.mcpServers[name] = nextConfig;
   if (status !== 'unchanged') {
     const dir = path.dirname(configPath);
     if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); }
@@ -111,28 +124,42 @@ function installCouncilSkill(sourceDir = COUNCIL_SOURCE_DIR) {
   }
 }
 
+/**
+ * Read the previous 'amicus' entry from ~/.claude.json, if any — used by the
+ * CLI add-json path to merge env the same way the file-fallback path does.
+ * Never throws: a missing/unreadable file just means "no previous entry".
+ * @returns {object|undefined}
+ */
+function readPrevClaudeCodeAmicusEntry() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf-8'));
+    return parsed && parsed.mcpServers ? parsed.mcpServers.amicus : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Register MCP server in Claude Code config */
 function registerClaudeCode() {
   // Try the CLI first
   try {
-    const mcpJson = JSON.stringify(MCP_CONFIG);
+    // Merge the PREVIOUS registration's env into the add-json payload — same
+    // merge semantics as addMcpToConfigFile's file-fallback path (`{ ...prev,
+    // ...config }`: prev env keys survive, canonical MCP_CONFIG keys win on
+    // collision). Without this, a user's custom env (API key, AMICUS_* tuning
+    // knobs) on the old registration was silently dropped whenever the
+    // `claude` CLI was present, because the CLI path built its JSON payload
+    // from the bare MCP_CONFIG and delegated overwrite semantics to the
+    // claude binary — which has no idea about the user's previous entry.
+    const prev = readPrevClaudeCodeAmicusEntry();
+    const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...MCP_CONFIG } : MCP_CONFIG;
+    const mcpJson = JSON.stringify(nextConfig);
     execFileSync('claude', ['mcp', 'add-json', 'amicus', mcpJson, '--scope', 'user'], {
       stdio: 'pipe',
       timeout: 10000,
     });
     console.log('[amicus] MCP registered in Claude Code (via CLI).');
 
-    // DEPRECATED(amicus-shim): also register 'sidecar' so existing clients that
-    // reference the old server name keep resolving. Remove in next major.
-    try {
-      execFileSync('claude', ['mcp', 'add-json', 'sidecar', mcpJson, '--scope', 'user'], {
-        stdio: 'pipe',
-        timeout: 10000,
-      });
-    } catch {
-      // Best-effort; ignore failures for the shim registration
-    }
-
     return;
   } catch {
     // CLI not available or failed — fall back to file edit
@@ -148,10 +175,6 @@ function registerClaudeCode() {
   } else {
     console.log('[amicus] MCP already registered in Claude Code.');
   }
-
-  // DEPRECATED(amicus-shim): also register 'sidecar' entry so existing clients
-  // that reference the old server name keep resolving. Remove in next major.
-  addMcpToConfigFile(claudeConfigPath, 'sidecar', MCP_CONFIG);
 }
 
 /** Register MCP server in Claude Desktop / Cowork config */
@@ -174,10 +197,33 @@ function registerClaudeDesktop() {
   } else {
     console.log('[amicus] MCP already registered in Claude Desktop.');
   }
+}
 
-  // DEPRECATED(amicus-shim): also register 'sidecar' entry so existing clients
-  // that reference the old server name keep resolving. Remove in next major.
-  addMcpToConfigFile(configPath, 'sidecar', MCP_CONFIG);
+/**
+ * One-shot migration: drop the duplicate legacy 'sidecar' MCP entry that
+ * pre-1.8 postinstalls registered alongside 'amicus' (same server twice —
+ * doubled the client-visible tool list). Only removes an entry whose command
+ * is an amicus MCP invocation; a customized 'sidecar' entry is left alone.
+ * Covers both files the three legacy registration paths wrote to:
+ * ~/.claude.json (CLI + file fallback) and claude_desktop_config.json.
+ * Never throws (postinstall must always exit 0).
+ */
+function migrateLegacyMcp(deps = {}) {
+  try {
+    const impl = deps.migrateLegacySidecar
+      || require('../src/utils/legacy-mcp-migration').migrateLegacySidecar;
+    for (const r of impl()) {
+      if (r.result === 'removed') {
+        console.log(`[amicus] Removed duplicate legacy 'sidecar' MCP entry from ${r.target} (same server — kept as 'amicus').`);
+      } else if (r.result === 'customized') {
+        console.log(`[amicus] Kept custom 'sidecar' MCP entry in ${r.target} (does not point at amicus).`);
+      } else if (r.result === 'write-failed') {
+        console.warn(`[amicus] Warning: could not remove the legacy 'sidecar' MCP entry from ${r.target} — run: amicus doctor --fix`);
+      }
+    }
+  } catch (err) {
+    console.warn(`[amicus] Warning: legacy MCP cleanup skipped: ${err && err.message}`);
+  }
 }
 
 /**
@@ -291,6 +337,7 @@ async function main(deps = {}) {
   const _installCouncilSkill = deps.installCouncilSkill || installCouncilSkill;
   const _registerClaudeCode = deps.registerClaudeCode || registerClaudeCode;
   const _registerClaudeDesktop = deps.registerClaudeDesktop || registerClaudeDesktop;
+  const _migrateLegacyMcp = deps.migrateLegacyMcp || migrateLegacyMcp;
   const _setupHooks = deps.setupHooks || setupHooks;
   const _provisionElectron = deps.provisionElectron || provisionElectron;
 
@@ -302,6 +349,7 @@ async function main(deps = {}) {
   _installCouncilSkill();
   _registerClaudeCode();
   _registerClaudeDesktop();
+  _migrateLegacyMcp(deps);
 
   // Non-fatal, cache-only: heal the optional Electron binary from local cache
   // or emit a deferred notice (GUI provisions on first use). Never throws.
@@ -336,4 +384,5 @@ if (require.main === module) {
   runCli();
 }
 
-module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill, setupHooks, provisionElectron, COUNCIL_FILES };
+module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill,
+  setupHooks, provisionElectron, registerClaudeCode, registerClaudeDesktop, migrateLegacyMcp, COUNCIL_FILES };

package/src/cli-handlers-doctor.js

@@ -41,6 +41,8 @@ function realDeps() {
     fix: false,
     discoverClaudeCodeMcps: () => require('./utils/mcp-discovery').discoverClaudeCodeMcps(),
     discoverCoworkMcps: () => require('./utils/mcp-discovery').discoverCoworkMcps(),
+    inspectLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').inspectAllLegacySidecarEntries(),
+    migrateLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').migrateLegacySidecar(),
     skillInstalled: () => {
       const dir = path.join(os.homedir(), '.claude', 'skills');
       return fs.existsSync(path.join(dir, 'sidecar', 'SKILL.md'))
@@ -181,6 +183,47 @@ async function runDoctorChecks(depsOverride = {}) {
     return { id: 'mcp', name: 'MCP registration', status: 'ok', message: `registered: Claude Code${extra}`, hint: null };
   }));
 
+  // Duplicate legacy 'sidecar' MCP registration (same server twice — doubles
+  // the client-visible tool list). Detection reads the raw config files via
+  // legacy-mcp-migration: mcp-discovery can't see it (it strips 'sidecar' as
+  // its own recursion guard). --fix removes only identical-in-effect twins.
+  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 };
+  }));
+
   // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no key.
   checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit', async () => {
     const values = d.readApiKeyValues() || {};

package/src/cli-handlers-status.js

@@ -0,0 +1,76 @@
+/**
+ * `amicus status <task_id>` — one-shot human/JSON status for a session or wave.
+ * Reads the SAME sources as the MCP amicus_status handler by calling it
+ * directly (requiring mcp-server does NOT start the server; the MCP SDK is
+ * only loaded inside startMcpServer()). Zero duplicated status logic — this
+ * inherits crash detection, wave leg rollup, and P6-3 enrichment for free.
+ */
+
+'use strict';
+
+const { validateTaskId } = require('./utils/validators');
+
+/** Render a key-value block for a single-session status payload. */
+function formatRunHuman(d) {
+  const lines = [
+    `Task:     ${d.taskId}`,
+    `Status:   ${d.status}${d.phase ? ` (${d.phase})` : ''}`,
+    `Elapsed:  ${d.elapsed}`,
+  ];
+  if (d.model) { lines.push(`Model:    ${d.model}`); }
+  if (d.mode) { lines.push(`Mode:     ${d.mode}`); }
+  if (d.messageCount !== undefined) { lines.push(`Messages: ${d.messageCount}`); }
+  if (d.lastActivity) { lines.push(`Activity: ${d.lastActivity}`); }
+  if (d.latestPreview) { lines.push(`Latest:   ${d.latestPreview}`); }
+  else if (d.latest) { lines.push(`Latest:   ${d.latest}`); }
+  if (d.stalled) { lines.push(`STALLED:  no activity for ${d.stalledForSeconds}s (see --json for recovery)`); }
+  if (d.reason) { lines.push(`Reason:   ${d.reason}`); }
+  return lines.join('\n');
+}
+
+/** Render a wave payload: header + one line per leg. */
+function formatWaveHumanStatus(d) {
+  const head = `Wave ${d.taskId}: ${d.status} — ${d.legsComplete}/${d.legsTotal} legs done (${d.elapsed})`;
+  const legLines = (d.legs || []).map((l) => {
+    const label = String(l.model || l.taskId || '').padEnd(28);
+    const st = String(l.status || 'unknown').padEnd(10);
+    const msgs = l.messages !== undefined ? `${l.messages} msg` : '';
+    const latest = l.latestPreview || l.latestActivity || '';
+    const flag = l.stalled ? ' ⏳stalled' : '';
+    return `  ${label} ${st} ${msgs} | ${latest}${flag}`;
+  });
+  return [head, ...legLines].join('\n');
+}
+
+/**
+ * Handle 'amicus status'. Exit code 0 = status retrieved (any run state, even
+ * a failed/crashed run — the QUERY succeeded); 1 = missing/invalid/unknown id.
+ * @param {object} args parsed CLI args
+ * @returns {Promise<number>}
+ */
+async function handleStatus(args) {
+  const taskId = args.wave || args._[1];
+  if (!taskId || taskId === true) {
+    process.stderr.write('Error: task_id is required for status\n');
+    process.stderr.write('Usage: amicus status <task_id> [--json]   (or: amicus status --wave <wave_id>)\n');
+    return 1;
+  }
+  const check = validateTaskId(String(taskId));
+  if (!check.valid) { process.stderr.write(`${check.error}\n`); return 1; }
+
+  const project = args.cwd || process.cwd();
+  const { handlers } = require('./mcp-server');
+  const result = await handlers.amicus_status({ taskId: String(taskId) }, project);
+  const text = result.content[0].text;
+  if (result.isError) { process.stderr.write(`${text}\n`); return 1; }
+
+  let data;
+  try { data = JSON.parse(text); } catch { process.stdout.write(`${text}\n`); return 0; }
+  delete data.next_poll; // MCP-agent polling guidance, not CLI output
+
+  if (args.json) { process.stdout.write(`${JSON.stringify(data, null, 2)}\n`); return 0; }
+  process.stdout.write(`${data.type === 'wave' ? formatWaveHumanStatus(data) : formatRunHuman(data)}\n`);
+  return 0;
+}
+
+module.exports = { handleStatus, formatRunHuman, formatWaveHumanStatus };

package/src/cli-handlers.js

@@ -123,6 +123,16 @@ async function handleAbort(args) {
     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.
@@ -147,6 +157,28 @@ async function handleAbort(args) {
 
   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.`);
+    }
+  }
 }
 
 /**

package/src/cli.js

@@ -330,6 +330,7 @@ Commands:
   start       Launch a new amicus session
   fanout      Run N models on the same prompt in parallel (headless)
   list        Show previous sessions
+  status      One-shot status for a session or wave (--json)
   resume      Reopen a previous session
   continue    New session building on previous
   read        Output session summary/conversation
@@ -416,6 +417,13 @@ Options for 'list':
   --status <filter>            Filter by status (running, complete)
   --all                        Show all projects
   --json                       Output as JSON
+`,
+  status: `
+Options for 'status':
+  <task_id>                    Required. Session or wave ID (positional)
+  --wave <wave_id>             Alternative to the positional ID for waves
+  --json                       Machine-readable output
+  --cwd <path>                 Project directory (default: cwd)
 `,
   abort: `
 Options for 'abort':