amicus 4.0.0 → 4.1.0

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) {
@@ -124,13 +123,28 @@ async function handleCouncilRunTool(input, project, helpers) {
   if (input.timeoutMinutes) { args.push('--timeout', String(input.timeoutMinutes)); }
   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) {
+  // v4.1 §4.5b/§4.5d. claudeReviewFile is resolved against `project` for the same
+  // reason outDir is — an MCP client may send a relative path, and the child's cwd
+  // is the run dir. Validation of the file itself stays in the spawned engine's
+  // pre-flight (run-assemble.preflightClaudeReview), so every entry point shares it.
+  if (input.debate) { args.push('--debate'); }
+  if (input.claudeReviewFile) { args.push('--claude-review', path.resolve(project, String(input.claudeReviewFile))); }
+  if (input.noCostGate) { args.push('--no-cost-gate'); }
+
+  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 +156,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,
 };

package/src/mcp-server.js

@@ -13,7 +13,7 @@ const { deriveStage, sanitizePreview } = require('./sidecar/progress-fields');
 const { SharedServerManager } = require('./utils/shared-server');
 const { durationBetween } = require('./utils/result-schema');
 const { canonicalProjectPath } = require('./utils/project-path');
-const { isAllowedProjectRoot } = require('./project-root-allowlist');
+const { isAllowedProjectRoot, isPathInside } = require('./project-root-allowlist');
 const { recordSession } = require('./utils/session-index');
 const { fileURLToPath } = require('url');
 const { RUNNING_VERSION, versionWarning } = require('./utils/version-info');
@@ -1141,10 +1141,35 @@ const handlers = {
     } catch (err) { return textResult(`council stats failed: ${err.message}`, true); }
   },
 
-  async amicus_verdict(input) {
+  async amicus_verdict(input, project) {
     try {
       const { buildVerdict } = require('./council/verdict');
-      return textResult(fenceSidecarOutput(JSON.stringify(buildVerdict(input.record, input.decisions || []))));
+      // The chair's synthesis lives only in the engine's verdict.json /
+      // chair-output.md, and this tool's output replaces verdict.json — so it
+      // must be carried through or it is destroyed. Unlike the CLI there is no
+      // run-folder path to anchor on (`record` arrives inline), so it is an
+      // explicit input; omitted → null, never fabricated.
+      const verdict = buildVerdict(input.record, input.decisions || [],
+        { overallVerdict: input.overallVerdict });
+      if (!input.render) {
+        return textResult(fenceSidecarOutput(JSON.stringify(verdict)));
+      }
+      // v4.1 §4.5c: return the markdown rendering (so Cowork can assemble report.md
+      // without Bash) and, when an outDir is given, refresh report.html on disk.
+      const { buildReport } = require('./council/report');
+      const md = buildReport({ verdict }, { format: 'md' });
+      if (input.outDir) {
+        // Containment parity with amicus_council_run (mcp-council-run.js): an
+        // MCP-supplied outDir must not write outside the project directory.
+        const cwd = project || getProjectDir(input.project);
+        const outDir = path.resolve(cwd, String(input.outDir));
+        if (!isPathInside(outDir, cwd)) {
+          return textResult(`outDir must resolve to a path inside the project directory (${cwd}).`, true);
+        }
+        fs.mkdirSync(outDir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(path.join(outDir, 'report.html'), buildReport({ verdict }, { format: 'html' }), { mode: 0o600 });
+      }
+      return textResult(fenceSidecarOutput(md));
     } catch (err) { return textResult(`verdict build failed: ${err.message}`, true); }
   },
 

package/src/mcp-tools.js

@@ -406,11 +406,12 @@ function getTools() {
   },
   {
     name: 'amicus_verdict',
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     description:
       "Merge a tally record with Claude's Stage-4 decisions into the verdict " +
       'object (final tiers after overrides, decisions, applied flags). Pure + ' +
-      'synchronous; returns the verdict — does NOT write it to disk.',
+      'synchronous; returns the verdict. Writes nothing unless render:true AND ' +
+      'outDir are given — then it also refreshes <outDir>/report.html.',
     inputSchema: {
       record: z.record(z.any()).describe('A tally() output record (from amicus_council_tally).'),
       decisions: z.array(z.object({
@@ -418,6 +419,13 @@ function getTools() {
         duplicateOf: z.string().nullable().optional(),
         tierOverride: z.object({ from: z.string(), to: z.string(), reason: z.string() }).nullable().optional(),
       })).optional().describe('Stage-4 per-finding decisions (default []).'),
+      overallVerdict: z.string().nullable().optional().describe(
+        "The chair's VERDICT line, read from the engine-written <runDir>/verdict.json " +
+        '(or the closing VERDICT: line of chair-output.md). Pass it through whenever you ' +
+        'overwrite verdict.json — it is the only copy, tally.json has none. Omit when the ' +
+        'chair was skipped; never author one yourself.'),
+      render: z.boolean().optional().describe('Also return the markdown rendering of the decided verdict (and refresh report.html when outDir is given).'),
+      outDir: z.string().optional().describe('Dir to write report.html into when render:true — resolved against the project dir and rejected if it escapes it. Omit to write nothing.'),
       project: z.string().optional().describe('Optional project directory path.'),
     },
   },
@@ -466,6 +474,18 @@ function getTools() {
       gateway: z.enum(GATEWAY_MODES).optional().describe(
         'Routing preference: auto (default), direct, or openrouter.'
       ),
+      debate: z.boolean().optional().describe(
+        'Add a Stage-2.5 rebuttal round: raisers defend Contested/Disputed findings and ' +
+        'disputing judges re-vote before the chair synthesizes.'
+      ),
+      claudeReviewFile: z.string().optional().describe(
+        "Path to Claude's own review file (prose + findings JSON) to include as a judged " +
+        'entry. Claude is reviewed and ranked like a seat, but never judges or chairs.'
+      ),
+      noCostGate: z.boolean().optional().describe(
+        'Disable the per-leg price gate for the WHOLE run (repairs and chair included). ' +
+        'Use for an intentional o3-class council. Independent of maxCost, which still caps the total.'
+      ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),

package/src/utils/error-doc.js

@@ -22,6 +22,8 @@ const ERROR_CODES = Object.freeze({
   INTERNAL: 'INTERNAL',             // unexpected pre-flight throw
   COUNCIL_QUORUM: 'COUNCIL_QUORUM', // council run: <2 surviving Stage-1 reviews (v4.0 §4)
   COST_EXCEEDED: 'COST_EXCEEDED',   // council run: whole-run --max-cost ceiling hit pre-tally (v4.0 §4)
+  // council run: --claude-review file unreadable/invalid, or --chair claude (v4.1 §4.4)
+  COUNCIL_CLAUDE_REVIEW_INVALID: 'COUNCIL_CLAUDE_REVIEW_INVALID',
 });
 
 /**