amicus 4.0.0 → 4.0.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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,49 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [4.0.1] - 2026-07-20
+
+Follow-up fixes to the v4.0.0 council engine: `amicus abort` and `amicus status` now see every
+sub-wave a stage launched, a council run that dies before its first checkpoint is recoverable
+instead of stranded, and neither command can be thrown by a malformed wave record.
+
+### Fixed
+
+- **`amicus abort` now cascades to every in-flight council leg, not just the primary wave of
+  each stage.** A stage can own several sub-waves — the chair's `ch1..ch4` retry/fallback/repair
+  chain, one solo per lens, a critic solo beside the seat wave, and the bounded Stage-1/Stage-2
+  repair re-prompts — but only a single `waveId` was recorded per stage (and the chair stage
+  recorded none at all), so the targeted cascade skipped those legs and left them to the
+  `waitThenKill` process-tree fallback. They were still killed, so this was never a leak or a
+  hang; what was lost were the per-leg `aborted` markers, an accurate `legsAborted` count, and a
+  faithful per-stage audit trail in `run.json`. Stage entries now carry a `waveIds` array
+  recording every sub-wave at launch time (documented in `schemas/council-run.schema.json`), and
+  the cascade targets the union of `waveId` + `waveIds`. In lens mode `stage1` previously
+  advertised only a phantom `-s1` wave that never launches, so *no* Stage-1 leg was reachable;
+  lens runs no longer record that `waveId` at all.
+- **`amicus status` now rolls up council legs across every sub-wave of the active stage.** It
+  counted only the stage's primary `waveId`, so a lens run — which has no seat wave — always
+  reported `legsTotal: null`, and a run with a critic omitted the critic's leg from the count
+  (e.g. `2` instead of `3` for two seats plus a critic). Note that `legsTotal` can now rise
+  mid-stage when a bounded repair re-prompt launches, which is a real additional model call.
+- **A council run spawned through `amicus_council_run` that died before its first checkpoint no
+  longer strands an unrecoverable record.** The MCP handler wrote `run.json` with
+  `status: "running"` and no `pid`, leaving the spawned CLI child to record its own pid at
+  startup; a child that died inside that window left a pid-less `running` run that `amicus
+  status` skipped entirely (its crash detection is guarded on `run.pid`) and that `amicus abort`
+  could not fall back to killing, so the run was recoverable only by hand. The handler now
+  captures the pid from the spawned child and checkpoints it immediately — the same value the
+  engine writes itself, recorded a beat earlier. The pid is written to its own
+  `spawn.pid` file rather than patched into `run.json`: the spawning process and the engine
+  child both write `run.json`, and `checkpoint` is a read-merge-write with no cross-process
+  lock, so a pid patch could clobber (or be clobbered by) the child's first checkpoint. Readers
+  prefer `run.json`'s own pid and fall back to `spawn.pid`.
+- **A malformed wave `metadata.json` no longer throws out of `amicus status` or `amicus abort`.**
+  `countWaveLegs` and `cascadeWave` both assumed the `legs` field was an array if it was present
+  at all, so a half-written or hand-edited record raised a `TypeError` past its caller. Both now
+  treat a non-array `legs` as no legs. `cascadeWave`'s wave-level abort mark is also guarded, so
+  a failure there can no longer discard the count of legs it had already marked.
+
 ## [4.0.0] - 2026-07-20
 
 The **headless council engine** release. `amicus council run` (CLI) and `amicus_council_run`

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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/schemas/council-run.schema.json

@@ -21,6 +21,7 @@
           "startedAt": { "type": ["string", "null"] },
           "completedAt": { "type": ["string", "null"] },
           "waveId": { "type": "string" },
+          "waveIds": { "type": "array", "items": { "type": "string" } },
           "taskIds": { "type": "array", "items": { "type": "string" } }
         }
       }

package/src/council/run-stages.js

@@ -25,6 +25,7 @@ const briefings = require('./briefings');
 const stage2 = require('./briefings-stage2');
 const { parseJudgeOutput } = require('./parse-stage2');
 const { materializeReviews, sanitizeName } = require('./run-launch');
+const runState = require('./run-state');
 
 function isAbortExit(code) { return code === 130 || code === 143; }
 
@@ -40,20 +41,30 @@ async function launchStage1(ctx) {
     noValidateModel: o.noValidateModel,
   };
   const launches = [];
+  // Record every sub-wave BEFORE it launches: `amicus abort` cascades over
+  // stages[].waveIds, so an id written after the launch leaves that leg
+  // reachable only by the pid kill (no per-leg abort marker).
+  const record = (waveId) => runState.appendStageWave(o.runDir, 'stage1', waveId);
   if (o.lenses) {
-    o.models.forEach((m, i) => launches.push(launchers.launchSolo({
-      ...common, model: m, waveId: `${o.runId}-l${i + 1}`,
-      prompt: briefings.buildLensBriefing({ lens: o.lenses[i], briefing: o.briefing, date: o.date }),
-    })));
+    o.models.forEach((m, i) => {
+      const waveId = `${o.runId}-l${i + 1}`;
+      record(waveId);
+      launches.push(launchers.launchSolo({
+        ...common, model: m, waveId,
+        prompt: briefings.buildLensBriefing({ lens: o.lenses[i], briefing: o.briefing, date: o.date }),
+      }));
+    });
   } else {
     const seats = o.models.filter(m => m !== o.critic);
     if (seats.length > 0) {
+      record(`${o.runId}-s1`);
       launches.push(launchers.launchWave({
         ...common, models: seats, waveId: `${o.runId}-s1`,
         prompt: briefings.buildSeatBriefing({ briefing: o.briefing, date: o.date }),
       }));
     }
     if (o.critic) {
+      record(`${o.runId}-c1`);
       launches.push(launchers.launchSolo({
         ...common, model: o.critic, waveId: `${o.runId}-c1`,
         prompt: briefings.buildCriticBriefing({ briefing: o.briefing, date: o.date }),
@@ -102,9 +113,11 @@ async function runStage1(ctx) {
     while (!res.ok && attempts < 2 && !ctx.overBudget()) {
       attempts += 1;
       repairSeq += 1;
+      const waveId = `${o.runId}-p${repairSeq}`;
+      runState.appendStageWave(o.runDir, 'stage1', waveId);
       const solo = await ctx.launchers.launchSolo({
         model: m.modelInput, prompt: briefings.buildFindingsRepairPrompt({ errors: res.errors }),
-        project: o.runDir, waveId: `${o.runId}-p${repairSeq}`, timeout: o.timeout,
+        project: o.runDir, waveId, timeout: o.timeout,
         gateway: o.gateway, noValidateModel: o.noValidateModel,
       });
       ctx.addWave(solo.wave);
@@ -141,6 +154,7 @@ async function runStage2(ctx, { reviews, labels, globalFindings }) {
     labels: labels.entries.map(e => e.label),
     findingIds: globalFindings.map(f => f.id),
   };
+  runState.appendStageWave(o.runDir, 'stage2', `${o.runId}-s2`);
   const { wave, exitCode } = await ctx.launchers.launchWave({
     models: judges, prompt: bundle, project: ctx.scratchDir, waveId: `${o.runId}-s2`,
     timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
@@ -163,9 +177,11 @@ async function runStage2(ctx, { reviews, labels, globalFindings }) {
     while (!parsed.ok && leg.status === 'complete' && leg.summary && attempts < 2 && !ctx.overBudget()) {
       attempts += 1;
       repairSeq += 1;
+      const waveId = `${o.runId}-q${repairSeq}`;
+      runState.appendStageWave(o.runDir, 'stage2', waveId);
       const solo = await ctx.launchers.launchSolo({
         model: judge, prompt: stage2.buildJudgeRepairPrompt({ errors: parsed.errors }),
-        project: ctx.scratchDir, waveId: `${o.runId}-q${repairSeq}`, timeout: o.timeout,
+        project: ctx.scratchDir, waveId, timeout: o.timeout,
         gateway: o.gateway, noValidateModel: o.noValidateModel,
       });
       ctx.addWave(solo.wave);

package/src/council/run-state.js

@@ -20,8 +20,31 @@ const { writeFileAtomic } = require('../utils/atomic-write');
 const { SESSIONS_DIR } = require('../session-manager');
 
 const RUN_FILE = 'run.json';
+const SPAWN_PID_FILE = 'spawn.pid';
 
 function runPath(runDir) { return path.join(runDir, RUN_FILE); }
+function spawnPidPath(runDir) { return path.join(runDir, SPAWN_PID_FILE); }
+
+/**
+ * Record the engine child's pid in its own file rather than patching run.json.
+ * The spawning process (the MCP handler) and the engine child both write
+ * run.json, and `checkpoint` is a read-merge-write with no cross-process lock —
+ * so a pid patch from the parent can clobber, or be clobbered by, whatever the
+ * child wrote in the same window. A standalone single-write file has no read
+ * side, so there is no race to lose. Readers fall back to it whenever run.json
+ * carries no pid (see readSpawnPid).
+ */
+function writeSpawnPid(runDir, pid) {
+  writeFileAtomic(spawnPidPath(runDir), String(pid), { mode: 0o600 });
+}
+
+/** @returns {number|null} the recorded spawn pid, or null when absent/corrupt */
+function readSpawnPid(runDir) {
+  try {
+    const pid = Number.parseInt(fs.readFileSync(spawnPidPath(runDir), 'utf-8').trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch { return null; }
+}
 
 /** @returns {object|null} parsed run.json, or null when missing/corrupt */
 function readRun(runDir) {
@@ -78,6 +101,21 @@ function updateStage(runDir, name, patch) {
   return checkpoint(runDir, { stages });
 }
 
+/**
+ * Append a sub-wave id to one stage's `waveIds` (dedup, launch order preserved).
+ * A stage can have several sub-waves in flight at once (lens solos, a critic
+ * solo alongside the seat wave) or in sequence (the chair's ch1..ch4 chain), so
+ * the single `waveId` field cannot describe them. `amicus abort` cascades over
+ * this list to mark every in-flight leg instead of relying on the pid kill.
+ */
+function appendStageWave(runDir, name, waveId) {
+  const existing = readRun(runDir) || {};
+  const stage = (existing.stages || []).find(s => s && s.name === name) || {};
+  const waveIds = Array.isArray(stage.waveIds) ? stage.waveIds : [];
+  if (waveIds.includes(waveId)) { return existing; }
+  return updateStage(runDir, name, { waveIds: [...waveIds, waveId] });
+}
+
 function stripPrefix(runId) { return String(runId).replace(/^council-/, ''); }
 
 /** `<project>/.claude/amicus_sessions/council-<runId>.json` */
@@ -117,6 +155,7 @@ function listPointers(project) {
 }
 
 module.exports = {
-  RUN_FILE, readRun, initRun, checkpoint, updateStage,
+  RUN_FILE, readRun, initRun, checkpoint, updateStage, appendStageWave,
+  writeSpawnPid, readSpawnPid,
   pointerPath, writePointer, readPointer, listPointers,
 };

package/src/council/run.js

@@ -110,8 +110,14 @@ async function runCouncil(options, deps = {}) {
       briefings.buildSeatBriefing({ briefing: o.briefing, date: o.date }), { mode: 0o600 });
 
     // ---- Stage 1: independent reviews ----
-    runState.updateStage(o.runDir, 'stage1',
-      { status: 'running', startedAt: now(), waveId: `${o.runId}-s1`, project: o.runDir });
+    // Lens mode launches one solo per seat instead of a `-s1` seat wave, so it
+    // has no primary wave to name — run-stages records each real sub-wave into
+    // waveIds at launch. Advertising a `-s1` that never exists made both the
+    // abort cascade and the status leg rollup chase a phantom.
+    runState.updateStage(o.runDir, 'stage1', {
+      status: 'running', startedAt: now(), project: o.runDir,
+      ...(o.lenses ? {} : { waveId: `${o.runId}-s1` }),
+    });
     const s1 = await runStage1(ctx);
     runState.updateStage(o.runDir, 'stage1', {
       status: 'complete', completedAt: now(),
@@ -173,6 +179,7 @@ async function runCouncil(options, deps = {}) {
     });
     fs.writeFileSync(path.join(o.runDir, 'chair-packet.md'), packet, { mode: 0o600 });
     const attemptChair = async (model, waveId) => {
+      runState.appendStageWave(o.runDir, 'chair', waveId);
       const solo = await launchers.launchSolo({
         model, prompt: packet, project: o.runDir, waveId,
         timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
@@ -228,6 +235,7 @@ async function runCouncil(options, deps = {}) {
     // ---- Chair VERDICT line (one repair re-prompt, spec §5) ----
     let overallVerdict = chairText ? parseChairVerdict(chairText) : null;
     if (chairText && !overallVerdict && !overBudget()) {
+      runState.appendStageWave(o.runDir, 'chair', `${o.runId}-ch4`);
       const repair = await launchers.launchSolo({
         model: actualChair, prompt: stage2.buildChairRepairPrompt(),
         project: o.runDir, waveId: `${o.runId}-ch4`,

package/src/mcp-council-awareness.js

@@ -0,0 +1,187 @@
+// src/mcp-council-awareness.js
+'use strict';
+
+/**
+ * @module mcp-council-awareness
+ * The council-awareness helpers behind amicus_status / amicus_list /
+ * amicus_abort: they resolve a council runId through the sessions-dir pointer
+ * file and read the run directory directly, so the generic session handlers do
+ * not need to know anything about council run layout.
+ *
+ * Split out of mcp-council-run.js, which owns the amicus_council_run handler;
+ * that file re-exports these so existing require paths keep working.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const runState = require('./council/run-state');
+const { RUNNING_VERSION } = require('./utils/version-info');
+
+/**
+ * Every wave a stage launched: the primary `waveId` plus the recorded
+ * `waveIds` sub-waves (chair ch1..ch4, lens solos, critic solo, repairs).
+ */
+function subWaveIds(stage) {
+  return [...new Set(
+    [stage.waveId, ...(Array.isArray(stage.waveIds) ? stage.waveIds : [])].filter(Boolean))];
+}
+
+/**
+ * The pid to probe for liveness. run.json's own pid is authoritative once the
+ * engine has checkpointed it; before that, the spawning process's record is all
+ * there is (see run-state.writeSpawnPid).
+ */
+function enginePid(run, runDir) {
+  return run.pid || runState.readSpawnPid(runDir);
+}
+
+/** @returns {{total: number, complete: number}|null} null when not on disk yet */
+function countWaveLegs(project, waveId) {
+  const { getSessionDir } = require('./session-manager');
+  const { TERMINAL_STATUSES } = require('./utils/result-schema');
+  let legs;
+  try {
+    legs = JSON.parse(fs.readFileSync(
+      path.join(getSessionDir(project, waveId), 'metadata.json'), 'utf-8')).legs;
+  } catch { return null; }
+  // A hand-edited or half-written metadata.json can carry a non-array `legs`;
+  // treat anything that is not an array as no legs rather than throwing out of
+  // a status read.
+  if (!Array.isArray(legs)) { return { total: 0, complete: 0 }; }
+  const complete = legs.filter((id) => {
+    try {
+      const m = JSON.parse(fs.readFileSync(
+        path.join(getSessionDir(project, id), 'metadata.json'), 'utf-8'));
+      return TERMINAL_STATUSES.includes(m.status);
+    } catch { return false; }
+  }).length;
+  return { total: legs.length, complete };
+}
+
+function elapsedOf(run) {
+  const end = run.completedAt || new Date().toISOString();
+  const ms = Math.max(0, new Date(end).getTime() - new Date(run.createdAt || end).getTime());
+  return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`;
+}
+
+/** Status payload for a council runId, or null when the id is not a council run. */
+function buildCouncilStatusPayload(project, taskId) {
+  const ptr = runState.readPointer(project, taskId);
+  if (!ptr) { return null; }
+  const run = runState.readRun(ptr.runDir);
+  if (!run) { return null; }
+
+  // Crash detection: a running run.json whose engine pid is gone is 'error'.
+  const pid = run.status === 'running' ? enginePid(run, ptr.runDir) : null;
+  if (pid) {
+    try { process.kill(pid, 0); } catch (err) {
+      if (err.code !== 'EPERM') {
+        runState.checkpoint(ptr.runDir, {
+          status: 'error', completedAt: new Date().toISOString(),
+          error: { code: 'INTERNAL', message: 'Council engine process exited unexpectedly' },
+        });
+        run.status = 'error';
+        run.error = { code: 'INTERNAL', message: 'Council engine process exited unexpectedly' };
+      }
+    }
+  }
+
+  const stages = (run.stages || []).map(s => ({
+    name: s.name, status: s.status, waveId: s.waveId || null,
+  }));
+  const active = (run.stages || []).find(s => s.status === 'running') || null;
+  let legsTotal = null; let legsComplete = null;
+  // Sum across every sub-wave the active stage launched: a lens stage1 has no
+  // seat wave at all, and a critic solo runs beside one. Stays null until at
+  // least one sub-wave record exists on disk.
+  for (const waveId of active && active.project ? subWaveIds(active) : []) {
+    const c = countWaveLegs(active.project, waveId);
+    if (!c) { continue; }
+    legsTotal = (legsTotal || 0) + c.total;
+    legsComplete = (legsComplete || 0) + c.complete;
+  }
+  const payload = {
+    taskId: run.runId, type: 'council-run', runId: run.runId, runDir: ptr.runDir,
+    status: run.status, currentStage: active ? active.name : null, stages,
+    legsTotal, legsComplete, elapsed: elapsedOf(run),
+    exitCode: run.exitCode !== undefined ? run.exitCode : null,
+    version: RUNNING_VERSION,
+  };
+  if (run.error) { payload.reason = `${run.error.code}: ${run.error.message}`; }
+  return payload;
+}
+
+/** amicus_list entries for every council pointer in the project. */
+function listCouncilRuns(project) {
+  const { sanitizePreview } = require('./sidecar/progress-fields');
+  const out = [];
+  for (const ptr of runState.listPointers(project)) {
+    const run = runState.readRun(ptr.runDir);
+    if (!run) { continue; }
+    let briefing = '';
+    try { briefing = fs.readFileSync(path.join(ptr.runDir, 'briefing.md'), 'utf-8'); }
+    catch { /* optional */ }
+    const active = (run.stages || []).find(s => s.status === 'running');
+    out.push({
+      id: run.runId, type: 'council-run', status: run.status, mode: 'headless',
+      model: null, agent: 'Plan', createdAt: run.createdAt,
+      briefing: sanitizePreview(briefing, 80),
+      stage: active ? active.name : null,
+    });
+  }
+  return out;
+}
+
+/** Mark one sub-wave and its legs aborted. @returns {number} legs newly marked */
+function cascadeWave(project, waveId) {
+  const { markAborted } = require('./utils/session-abort');
+  const { getSessionDir } = require('./session-manager');
+  const waveDir = getSessionDir(project, waveId);
+  let meta = {};
+  try { meta = JSON.parse(fs.readFileSync(path.join(waveDir, 'metadata.json'), 'utf-8')); }
+  catch { /* wave record may not exist yet */ }
+  let n = 0;
+  // Non-array `legs` (hand-edited or half-written) would throw out of the
+  // for..of and lose the wave-level mark below.
+  for (const legId of Array.isArray(meta.legs) ? meta.legs : []) {
+    try { if (markAborted(getSessionDir(project, legId), 'council abort')) { n++; } }
+    catch { /* skip leg */ }
+  }
+  // Guarded so a failure here cannot discard the legs already marked: the
+  // caller only learns the count through the return value.
+  try { markAborted(waveDir, 'council abort'); } catch { /* best-effort */ }
+  return n;
+}
+
+/**
+ * Abort a council run via its pointer: checkpoint run.json aborted (abort-wins)
+ * and cascade to every in-flight sub-wave + its legs so they settle.
+ * @returns {null|{notFound?: true}|{alreadyTerminal: true, status}|{aborted: true, cascaded: number}}
+ */
+function abortCouncilRun(project, taskId) {
+  const ptr = runState.readPointer(project, taskId);
+  if (!ptr) { return null; }
+  const run = runState.readRun(ptr.runDir);
+  if (!run) { return null; }
+  if (run.status !== 'running') { return { alreadyTerminal: true, status: run.status }; }
+
+  let cascaded = 0;
+  for (const s of run.stages || []) {
+    if (s.status !== 'running' || !s.project) { continue; }
+    for (const waveId of subWaveIds(s)) {
+      try { cascaded += cascadeWave(s.project, waveId); } catch { /* skip sub-wave */ }
+    }
+  }
+  runState.checkpoint(ptr.runDir, { status: 'aborted', completedAt: new Date().toISOString() });
+  const pid = enginePid(run, ptr.runDir);
+  if (pid) {
+    try { require('./utils/abort-coordinator').waitThenKill(pid).catch(() => {}); }
+    catch { /* best-effort */ }
+  }
+  return { aborted: true, cascaded };
+}
+
+module.exports = {
+  subWaveIds, countWaveLegs, elapsedOf, enginePid,
+  buildCouncilStatusPayload, listCouncilRuns, cascadeWave, abortCouncilRun,
+};

package/src/mcp-council-run.js

@@ -4,18 +4,17 @@
 /**
  * @module mcp-council-run
  * MCP surface for headless council runs (spec §8): the amicus_council_run
- * handler (15th tool, born-fenced) plus the council-awareness helpers that
- * amicus_status / amicus_list / amicus_abort call through the sessions-dir
- * pointer file. Lives outside mcp-server.js (grandfathered-oversized); the
- * spawn helper is INJECTED by mcp-server at call time to avoid a require
- * cycle.
+ * handler (15th tool, born-fenced). Lives outside mcp-server.js
+ * (grandfathered-oversized); the spawn helper is INJECTED by mcp-server at call
+ * time to avoid a require cycle. The council-awareness helpers that
+ * amicus_status / amicus_list / amicus_abort call now live in
+ * mcp-council-awareness.js and are re-exported from here.
  */
 
 const fs = require('fs');
 const path = require('path');
 const runState = require('./council/run-state');
 const { fenceSidecarOutput } = require('./utils/untrusted-fence');
-const { RUNNING_VERSION } = require('./utils/version-info');
 const { isPathInside } = require('./project-root-allowlist');
 
 function textResult(text, isError) {
@@ -125,12 +124,20 @@ async function handleCouncilRunTool(input, project, helpers) {
   if (typeof input.maxCost === 'number') { args.push('--max-cost', String(input.maxCost)); }
   if (input.gateway) { args.push('--gateway', input.gateway); }
 
-  try { helpers.spawnFn(args, runDir); } catch (err) {
+  let child;
+  try { child = helpers.spawnFn(args, runDir); } catch (err) {
     try {
       runState.checkpoint(runDir, { status: 'error', error: { code: 'INTERNAL', message: err.message }, completedAt: new Date().toISOString() });
     } catch { /* best-effort */ }
     return textResult(`Failed to start council run: ${err.message}`, true);
   }
+  // Record the child's pid NOW: the engine writes its own pid at startup, but a
+  // child that dies before that leaves a pid-less status:'running' run.json that
+  // crash detection skips and abort cannot signal. Written to its own file, not
+  // patched into run.json — the child owns run.json and a cross-process
+  // read-merge-write has no lock (see run-state.writeSpawnPid).
+  try { if (typeof child?.pid === 'number') { runState.writeSpawnPid(runDir, child.pid); } }
+  catch { /* best-effort */ }
 
   const body = JSON.stringify({
     schemaVersion: 2, type: 'council-run', runId, runDir, status: 'running',
@@ -142,126 +149,13 @@ async function handleCouncilRunTool(input, project, helpers) {
   return textResult(fenceSidecarOutput(body));
 }
 
-/** ---- council-awareness helpers (consumed by mcp-server status/list/abort) ---- */
-
-function elapsedOf(run) {
-  const end = run.completedAt || new Date().toISOString();
-  const ms = Math.max(0, new Date(end).getTime() - new Date(run.createdAt || end).getTime());
-  return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`;
-}
-
-/** Status payload for a council runId, or null when the id is not a council run. */
-function buildCouncilStatusPayload(project, taskId) {
-  const ptr = runState.readPointer(project, taskId);
-  if (!ptr) { return null; }
-  const run = runState.readRun(ptr.runDir);
-  if (!run) { return null; }
-
-  // Crash detection: a running run.json whose engine pid is gone is 'error'.
-  if (run.status === 'running' && run.pid) {
-    try { process.kill(run.pid, 0); } catch (err) {
-      if (err.code !== 'EPERM') {
-        runState.checkpoint(ptr.runDir, {
-          status: 'error', completedAt: new Date().toISOString(),
-          error: { code: 'INTERNAL', message: 'Council engine process exited unexpectedly' },
-        });
-        run.status = 'error';
-        run.error = { code: 'INTERNAL', message: 'Council engine process exited unexpectedly' };
-      }
-    }
-  }
-
-  const stages = (run.stages || []).map(s => ({
-    name: s.name, status: s.status, waveId: s.waveId || null,
-  }));
-  const active = (run.stages || []).find(s => s.status === 'running') || null;
-  let legsTotal = null; let legsComplete = null;
-  if (active && active.waveId && active.project) {
-    try {
-      const { getSessionDir } = require('./session-manager');
-      const { TERMINAL_STATUSES } = require('./utils/result-schema');
-      const meta = JSON.parse(fs.readFileSync(
-        path.join(getSessionDir(active.project, active.waveId), 'metadata.json'), 'utf-8'));
-      const legs = meta.legs || [];
-      legsTotal = legs.length;
-      legsComplete = legs.filter((id) => {
-        try {
-          const m = JSON.parse(fs.readFileSync(
-            path.join(getSessionDir(active.project, id), 'metadata.json'), 'utf-8'));
-          return TERMINAL_STATUSES.includes(m.status);
-        } catch { return false; }
-      }).length;
-    } catch { /* stage wave not on disk yet */ }
-  }
-  const payload = {
-    taskId: run.runId, type: 'council-run', runId: run.runId, runDir: ptr.runDir,
-    status: run.status, currentStage: active ? active.name : null, stages,
-    legsTotal, legsComplete, elapsed: elapsedOf(run),
-    exitCode: run.exitCode !== undefined ? run.exitCode : null,
-    version: RUNNING_VERSION,
-  };
-  if (run.error) { payload.reason = `${run.error.code}: ${run.error.message}`; }
-  return payload;
-}
-
-/** amicus_list entries for every council pointer in the project. */
-function listCouncilRuns(project) {
-  const { sanitizePreview } = require('./sidecar/progress-fields');
-  const out = [];
-  for (const ptr of runState.listPointers(project)) {
-    const run = runState.readRun(ptr.runDir);
-    if (!run) { continue; }
-    let briefing = '';
-    try { briefing = fs.readFileSync(path.join(ptr.runDir, 'briefing.md'), 'utf-8'); }
-    catch { /* optional */ }
-    const active = (run.stages || []).find(s => s.status === 'running');
-    out.push({
-      id: run.runId, type: 'council-run', status: run.status, mode: 'headless',
-      model: null, agent: 'Plan', createdAt: run.createdAt,
-      briefing: sanitizePreview(briefing, 80),
-      stage: active ? active.name : null,
-    });
-  }
-  return out;
-}
-
-/**
- * Abort a council run via its pointer: checkpoint run.json aborted (abort-wins)
- * and cascade to the active stage's wave + legs so in-flight legs settle.
- * @returns {null|{notFound?: true}|{alreadyTerminal: true, status}|{aborted: true, cascaded: number}}
- */
-function abortCouncilRun(project, taskId) {
-  const ptr = runState.readPointer(project, taskId);
-  if (!ptr) { return null; }
-  const run = runState.readRun(ptr.runDir);
-  if (!run) { return null; }
-  if (run.status !== 'running') { return { alreadyTerminal: true, status: run.status }; }
-
-  const { markAborted } = require('./utils/session-abort');
-  const { getSessionDir } = require('./session-manager');
-  let cascaded = 0;
-  for (const s of run.stages || []) {
-    if (s.status !== 'running' || !s.waveId || !s.project) { continue; }
-    try {
-      const waveDir = getSessionDir(s.project, s.waveId);
-      let meta = {};
-      try { meta = JSON.parse(fs.readFileSync(path.join(waveDir, 'metadata.json'), 'utf-8')); }
-      catch { /* wave record may not exist yet */ }
-      for (const legId of meta.legs || []) {
-        try { if (markAborted(getSessionDir(s.project, legId), 'council abort')) { cascaded++; } }
-        catch { /* skip leg */ }
-      }
-      markAborted(waveDir, 'council abort');
-    } catch { /* skip stage */ }
-  }
-  runState.checkpoint(ptr.runDir, { status: 'aborted', completedAt: new Date().toISOString() });
-  if (run.pid) {
-    try { require('./utils/abort-coordinator').waitThenKill(run.pid).catch(() => {}); }
-    catch { /* best-effort */ }
-  }
-  return { aborted: true, cascaded };
-}
+// The council-awareness helpers live in their own module; re-exported here so
+// mcp-server and cli-handlers-abort keep requiring one council MCP entry point.
+const awareness = require('./mcp-council-awareness');
 
 module.exports = {
-  handleCouncilRunTool, buildCouncilStatusPayload, listCouncilRuns, abortCouncilRun,
+  handleCouncilRunTool,
+  buildCouncilStatusPayload: awareness.buildCouncilStatusPayload,
+  listCouncilRuns: awareness.listCouncilRuns,
+  abortCouncilRun: awareness.abortCouncilRun,
 };