amicus 4.0.1 → 4.1.0

package/src/council/run-assemble.js

@@ -3,13 +3,17 @@
 
 /**
  * @module council/run-assemble
- * Pure assembly + artifact emission for the headless council engine (spec §5):
- * the five-keys tally input (meta pins: claudeInCouncil false, models = bench
- * seats exactly — critic included, chair excluded — runType 'headless'),
- * runStats rows copied verbatim from leg docs, and the run-dir artifact set
- * (tally-input.json, tally.json, verdict.json with overallVerdict, report.html,
- * chair-output.md). Raiser self-votes are INCLUDED in adjudications — exclusion
- * is tally's job (tally.js:95); judged is tally's job (tally.js:110).
+ * Assembly + artifact emission for the headless council engine (spec §5), plus
+ * the `--claude-review` pre-flight it now also owns: the five-keys tally input
+ * (meta pins: claudeInCouncil false, models = bench seats exactly — critic
+ * included, chair excluded — runType 'headless'), runStats rows copied
+ * verbatim from leg docs, the run-dir artifact set (tally-input.json,
+ * tally.json, verdict.json with overallVerdict, report.html, chair-output.md),
+ * v4.1 §4.4 pre-flight validation of the file-sourced Claude review
+ * (preflightClaudeReview — the reserved-seat/chair/critic guards), its review-N+1
+ * labelling (labelClaudeReview), and its synthesized null-usage runStats row
+ * (claudeRunStatsRow). Raiser self-votes are INCLUDED in adjudications —
+ * exclusion is tally's job (tally.js:95); judged is tally's job (tally.js:110).
  */
 
 const fs = require('fs');
@@ -17,9 +21,15 @@ const path = require('path');
 const { writeFileAtomic } = require('../utils/atomic-write');
 const { buildVerdict, writeVerdictAtomic } = require('./verdict');
 const { buildReport } = require('./report');
+const { validateFindings } = require('./findings');
+const { toGlobalFindings } = require('./anonymize');
 
 const CONFORMANCE_RANK = { clean: 0, repaired: 1, unstructured: 2 };
 
+/** v4.1 §4.4: the reserved seat name for the file-sourced Claude review. */
+const CLAUDE_SEAT = 'claude';
+const CLAUDE_REVIEW_ERROR = 'COUNCIL_CLAUDE_REVIEW_INVALID';
+
 /** Worst-wins merge of Stage-1 findings conformance and Stage-2 judge conformance. */
 function worseConformance(a, b) {
   return (CONFORMANCE_RANK[a] || 0) >= (CONFORMANCE_RANK[b] || 0) ? a : b;
@@ -43,14 +53,79 @@ function buildRunStatsEntry({ leg, model, role, wasChair, conformance }) {
   };
 }
 
+/**
+ * Pre-flight for `--claude-review <path>` (v4.1 §4.4). Runs AFTER initRun (so the
+ * error doc lands in a run dir that exists) and BEFORE any launch, so an invalid
+ * file costs zero spend. The orchestrator authored the file, so there is no repair
+ * loop — fix and relaunch is free.
+ * @param {{claudeReviewFile: ?string, chair: ?string, critic: ?string, models: ?Array<string>}} o run options
+ * @returns {{claudeReview: object|null, error: ?{code: string, message: string}}}
+ */
+function preflightClaudeReview(o) {
+  if (!o.claudeReviewFile) { return { claudeReview: null, error: null }; }
+  const bad = (detail) => ({ claudeReview: null,
+    error: { code: CLAUDE_REVIEW_ERROR, message: `council_claude_review_invalid: ${detail}` } });
+  if (o.chair === CLAUDE_SEAT) {
+    return bad('claude may not chair (it is judged, never votes or chairs)');
+  }
+  if (o.critic === CLAUDE_SEAT) {
+    return bad("'claude' is a reserved seat name and cannot be the critic");
+  }
+  if (Array.isArray(o.models) && o.models.includes(CLAUDE_SEAT)) {
+    // 'claude' is a reserved seat name for the file-sourced review N+1 (it
+    // joins meta.models synthetically — see buildTallyInput). A real bench
+    // leg ALSO named 'claude' would collide on that same key: labelMap gets
+    // two 'claude' entries, and ledger.js's Map join lets the synthesized
+    // claude row overwrite the real leg's role/conformance/wasChair and
+    // double-count findingsRaised — permanently, since the ledger is
+    // append-only. Reject it here so every entry point (CLI, MCP, GitHub
+    // Action, direct require('./council/run')) is covered, not just the
+    // CLI's option whitelist.
+    return bad("'claude' is a reserved seat name and cannot also appear in --models");
+  }
+  let text = '';
+  try { text = fs.readFileSync(o.claudeReviewFile, 'utf-8'); }
+  catch (e) { return bad(`cannot read ${o.claudeReviewFile}: ${e.message}`); }
+  const v = validateFindings(text);
+  if (!v.ok) { return bad(v.errors.map(e => `${e.code}: ${e.detail}`).join('; ')); }
+  return { claudeReview: { model: CLAUDE_SEAT, text, findings: v.findings }, error: null };
+}
+
+/**
+ * Stamp the file-sourced Claude review with its label (always the LAST entry —
+ * review N+1) and its run-global finding ids. Mutates + returns the new ids so
+ * run.js can concat them onto the bench's globalFindings in one expression.
+ * @returns {Array<object>} claude's run-global findings
+ */
+function labelClaudeReview(claudeReview, labels) {
+  const e = labels.entries[labels.entries.length - 1];
+  claudeReview.label = e.label;
+  claudeReview.globalFindings = toGlobalFindings(e.letter, CLAUDE_SEAT, claudeReview.findings);
+  return claudeReview.globalFindings;
+}
+
+/**
+ * The synthesized runStats row for a review that never ran a leg (v4.1 §4.4).
+ * durationMs/usage are null per the never-invent rule — nothing was launched.
+ */
+function claudeRunStatsRow() {
+  return { model: CLAUDE_SEAT, role: CLAUDE_SEAT, wasChair: false, conformance: 'clean',
+    status: 'complete', durationMs: null, usage: null };
+}
+
 /**
  * Assemble the five-keys tally input (spec §5 / SKILL.md Stage-2 recipe).
  * @param {{runId: string, date: string, bench: string[], chair: string,
  *   reviews: Array<{model, role, conformance, leg, globalFindings}>,
  *   judgeResults: Array<{judge, ok, order, adjudications}>,
- *   chairStats: object|null}} args
+ *   chairStats: object|null, claudeReview?: object|null}} args
+ *   `claudeReview` (v4.1 §4.4) amends the v4.0 meta pin: present ⇒ claudeInCouncil
+ *   true, 'claude' joins meta.models (the street-cred universe), its findings join
+ *   the pool and it gets the synthesized null-usage runStats row. Absent ⇒ v4.0
+ *   output byte-for-byte.
  */
-function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, chairStats }) {
+function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, chairStats,
+  claudeReview }) {
   const meta = {
     runId, date, runType: 'headless',
     models: bench.slice(),          // bench seats exactly: critic included, chair excluded
@@ -65,6 +140,12 @@ function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, cha
   const runStats = reviews.map(r => buildRunStatsEntry({
     leg: r.leg, model: r.model, role: r.role, wasChair: false, conformance: r.conformance,
   }));
+  if (claudeReview) {
+    meta.models.push(CLAUDE_SEAT);      // last, mirroring its review-N+1 label
+    meta.claudeInCouncil = true;
+    findings.push(...claudeReview.globalFindings);
+    runStats.push(claudeRunStatsRow());
+  }
   if (chairStats) { runStats.push(chairStats); }
   return { meta, findings, adjudications, rankings, runStats };
 }
@@ -97,4 +178,5 @@ function writeVerdictFiles({ runDir, record, overallVerdict, chairText }) {
 
 module.exports = {
   buildRunStatsEntry, worseConformance, buildTallyInput, writeTallyFiles, writeVerdictFiles,
+  preflightClaudeReview, labelClaudeReview, claudeRunStatsRow, CLAUDE_SEAT,
 };

package/src/council/run-chair.js

@@ -0,0 +1,145 @@
+// src/council/run-chair.js
+'use strict';
+
+/**
+ * @module council/run-chair
+ * Chair synthesis + VERDICT-line repair for the headless council driver,
+ * lifted VERBATIM out of run.js for the 300-line gate (v4.1 Task 0.5). Pure
+ * refactor: same launches, same waveIds, same run.json checkpoints, same
+ * degradation rules. Launchers come in through `ctx` exactly as run-stages.js
+ * takes them; run.js keeps the chair-packet build, the tally sequencing, the
+ * signal bookkeeping and finalize().
+ *
+ * `isSignalled` is a GETTER, not a snapshot: run.js's signal handler mutates
+ * its `signalled` local between awaits and the v4.0 code re-read it after every
+ * chair launch. Passing the value instead would silently drop those aborts.
+ */
+
+const stage2 = require('./briefings-stage2');
+const { parseChairVerdict } = require('./parse-stage2');
+const runState = require('./run-state');
+const { isAbortExit } = require('./run-stages');
+
+/**
+ * Chair fallback promotion (spec §4): the highest peers-only street-cred
+ * model from `council stats` that is not a bench seat and not the failed
+ * chair. "Highest street-cred" = BEST = numerically LOWEST mean rank
+ * (deriveReliability's avgStreetCredPeersOnly; lower is better).
+ *
+ * The reserved seat name 'claude' is never eligible (v4.1 §4.4 "never chairs"):
+ * a --claude-review run puts a real 'claude' row in the ledger, so without this
+ * filter a LATER run could promote it and walk straight past the pre-flight
+ * --chair claude guard — with no Claude leg to launch.
+ * @returns {string|null}
+ */
+function pickFallbackChair(statsRows, bench, failedChair) {
+  const benchSet = new Set(bench);
+  const candidates = (statsRows || [])
+    .filter(r => r.model !== 'claude' && !benchSet.has(r.model) && r.model !== failedChair
+      && typeof r.avgStreetCredPeersOnly === 'number')
+    .sort((a, b) => a.avgStreetCredPeersOnly - b.avgStreetCredPeersOnly);
+  return candidates.length ? candidates[0].model : null;
+}
+
+/**
+ * Chair chain (attempt → retry → ledger-promoted fallback → give up) plus the
+ * single VERDICT-line repair re-prompt.
+ * @param {object} ctx run.js's {o, launchers, addWave, overBudget, scratchDir}
+ * @param {{packet: string, degraded: {value: boolean}, statsFn: Function,
+ *   isSignalled: function(): (number|null)}} args
+ * @returns {Promise<{aborted: number|null, chairLeg: object|null,
+ *   actualChair: string|null, chairText: string|null,
+ *   chairConformance: string, overallVerdict: string|null}>}
+ */
+async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
+  const { o, launchers, addWave, overBudget } = ctx;
+  const now = () => new Date().toISOString();
+  const bail = (code) => ({
+    aborted: code, chairLeg: null, actualChair: null, chairText: null,
+    chairConformance: 'clean', overallVerdict: null,
+  });
+
+  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,
+      // v4.1 §4.5d: the chair chain (ch1/ch2/ch3) and the ch4 VERDICT repair
+      // below are the launches a re-armed price gate would refuse LAST, after
+      // the whole bench has already been paid for.
+      noCostGate: o.noCostGate,
+    });
+    addWave(solo.wave);
+    const ok = solo.leg && solo.leg.status === 'complete'
+      && solo.leg.summary && solo.leg.summary.trim();
+    return { leg: ok ? solo.leg : null, exitCode: solo.exitCode };
+  };
+
+  let chairLeg = null;
+  let actualChair = null;
+  if (overBudget()) {
+    // Ceiling hit after the tally is computable: skip the chair, write the
+    // verdict with overallVerdict null, exit 2 (spec §4 degradation table).
+    // Never abort in-flight legs for cost — this only stops NEW launches.
+    degraded.value = true;
+    runState.updateStage(o.runDir, 'chair', { status: 'skipped', completedAt: now() });
+  } else {
+    runState.updateStage(o.runDir, 'chair', { status: 'running', startedAt: now(), project: o.runDir });
+    // Fallback chain (spec §4): retry same chair once → promote best
+    // non-bench model from the ledger → give up (no Claude fallback headless).
+    let attempt = await attemptChair(o.chair, `${o.runId}-ch1`);
+    if (isAbortExit(attempt.exitCode) || isSignalled()) { return bail(attempt.exitCode || isSignalled()); }
+    if (!attempt.leg && !overBudget()) {
+      attempt = await attemptChair(o.chair, `${o.runId}-ch2`);
+      if (isAbortExit(attempt.exitCode) || isSignalled()) { return bail(attempt.exitCode || isSignalled()); }
+    }
+    if (attempt.leg) { actualChair = o.chair; }
+    else if (!overBudget()) {
+      let statsRows = [];
+      try { statsRows = statsFn(); } catch { /* no ledger yet */ }
+      const fallback = pickFallbackChair(statsRows, o.models, o.chair);
+      if (fallback) {
+        attempt = await attemptChair(fallback, `${o.runId}-ch3`);
+        if (isAbortExit(attempt.exitCode) || isSignalled()) { return bail(attempt.exitCode || isSignalled()); }
+        if (attempt.leg) { actualChair = fallback; }
+      }
+    }
+    chairLeg = attempt.leg;
+    runState.updateStage(o.runDir, 'chair',
+      { status: chairLeg ? 'complete' : 'error', completedAt: now() });
+    // The chair chain may have promoted a fallback (or given up) — checkpoint
+    // the ACTUAL chair into run.json now so status/`--json`/the human summary
+    // never report the originally-requested chair after a promotion. Mirrors
+    // mkInput's actualChair || o.chair (a give-up with no actual chair keeps
+    // the requested chair).
+    runState.checkpoint(o.runDir, { chair: actualChair || o.chair });
+  }
+  const chairText = chairLeg ? chairLeg.summary : null;
+  let chairConformance = 'clean';
+
+  // ---- 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`,
+      timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
+      noCostGate: o.noCostGate,
+    });
+    addWave(repair.wave);
+    if (isAbortExit(repair.exitCode) || isSignalled()) { return bail(repair.exitCode || isSignalled()); }
+    overallVerdict = parseChairVerdict((repair.leg && repair.leg.summary) || '');
+    chairConformance = overallVerdict ? 'repaired' : 'unstructured';
+  }
+  // A completed chair whose verdict never parsed is 'unstructured' even when
+  // the repair was skipped (e.g. the chair leg itself tripped --max-cost).
+  if (chairText && !overallVerdict) { chairConformance = 'unstructured'; }
+  if (!chairLeg || !overallVerdict) { degraded.value = true; } // spec table: exit 2 rows
+
+  return {
+    aborted: null, chairLeg, actualChair, chairText, chairConformance, overallVerdict,
+  };
+}
+
+module.exports = { runChair, pickFallbackChair };

package/src/council/run-debate.js

@@ -0,0 +1,289 @@
+// src/council/run-debate.js
+'use strict';
+
+/**
+ * @module council/run-debate
+ * Impure Stage-2.5 orchestration for headless debate mode (spec §5.1). Launches the
+ * defense mini-wave (one solo per raiser) and the re-vote mini-wave (one fanout to
+ * disputing judges), parses each with one bounded repair, then hands off to the pure
+ * reassembly in ./debate.js. Launchers are injected via ctx (repo DI pattern).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const dbrief = require('./briefings-debate');
+const { parseDebateDefense, parseRevote } = require('./parse-stage2');
+const { applyDebate, debateRunStatsRows, PAST_TENSE } = require('./debate');
+const { materializeDebate } = require('./run-launch');
+const { tally } = require('./tally');
+const { isAbortExit } = require('./run-stages');
+const runState = require('./run-state');
+
+/** Spec §5.7 fallback: a dead/unparseable defense means every bundled id's original stands. */
+function allNoResponse(ids) {
+  const byId = {};
+  for (const id of ids) { byId[id] = { action: 'no-response' }; }
+  return byId;
+}
+
+/** True when there is nothing to challenge (spec §5.1). */
+function nothingToDebate(provisionalRecord) {
+  if (!provisionalRecord || provisionalRecord.judged === false) { return true; }
+  const n = provisionalRecord.findings.filter(f => f.tier === 'Contested' || f.tier === 'Disputed').length;
+  return n === 0;
+}
+
+/** Judges whose provisional adjudications dispute at least one bundled id. */
+function disputingJudges(provisionalRecord, bundledIds) {
+  const ids = new Set(bundledIds);
+  const judges = new Set();
+  for (const f of provisionalRecord.findings) {
+    if (!ids.has(f.id)) { continue; }
+    for (const adj of f.adjudications || []) {
+      if (adj.verdict === 'dispute') { judges.add(adj.judge); }
+    }
+  }
+  return [...judges];
+}
+
+/** Group Contested+Disputed findings by raiser (defense targets). */
+function debateTargets(provisionalRecord, tallyInput) {
+  const claimById = new Map(tallyInput.findings.map(f => [f.id, f]));
+  const byRaiser = {};
+  const previousTier = {};
+  for (const f of provisionalRecord.findings) {
+    if (f.tier !== 'Contested' && f.tier !== 'Disputed') { continue; }
+    previousTier[f.id] = f.tier;
+    const src = claimById.get(f.id) || {};
+    const peerVerdicts = (f.adjudications || []).filter(a => a.judge !== f.raiser).map(a => a.verdict);
+    (byRaiser[f.raiser] = byRaiser[f.raiser] || []).push({ id: f.id, claim: src.claim,
+      severity: f.severity, location: src.location, peerVerdicts, disputeReasons: [] });
+  }
+  return { byRaiser, previousTier };
+}
+
+/** Common launch options for every debate leg (judge-isolated `_scratch` cwd). */
+function legOpts(ctx, waveId) {
+  return { project: ctx.scratchDir, waveId, timeout: ctx.o.timeout, gateway: ctx.o.gateway,
+    noValidateModel: ctx.o.noValidateModel, noCostGate: ctx.o.noCostGate };
+}
+
+async function runDefenseSolo(ctx, raiser, findings, idx) {
+  const brief = dbrief.buildDefenseBrief({ findings, date: ctx.o.date });
+  const waveId = `${ctx.o.runId}-d${idx + 1}`;
+  const expectedIds = findings.map(f => f.id);
+  // Record the sub-wave BEFORE launching: `amicus abort` cascades over stages[].waveIds
+  // (run-stages.js's record(), run-chair.js's chair chain), so an id written after the
+  // launch leaves an in-flight leg reachable only by the pid kill. The v4.0.1
+  // abort-cascade fix must hold for debate stages too.
+  runState.appendStageWave(ctx.o.runDir, 'debate-defense', waveId);
+  const res = await ctx.launchers.launchSolo({ ...legOpts(ctx, waveId), model: raiser, prompt: brief });
+  ctx.addWave(res.wave);
+  if (isAbortExit(res.exitCode)) { return { raiser, aborted: res.exitCode }; }
+  let leg = res.leg && res.leg.status === 'complete' ? res.leg : null;
+  // A dead leg gets the SAME spec §5.7 fallback the parser applies to a block-level
+  // failure — every expected id 'no-response', never an empty map, so the
+  // originals-stand outcome still reaches debate.json and the record decoration.
+  let parsed = leg ? parseDebateDefense(leg.summary, expectedIds)
+    : { ok: false, byId: allNoResponse(expectedIds), errors: [{ code: 'DEAD_LEG', detail: 'no summary' }] };
+  let conformance = leg ? 'clean' : 'unstructured';
+  if (leg && !parsed.ok) {
+    const repairId = `${waveId}r`;
+    runState.appendStageWave(ctx.o.runDir, 'debate-defense', repairId);
+    const res2 = await ctx.launchers.launchSolo({
+      ...legOpts(ctx, repairId), model: raiser,
+      prompt: dbrief.buildDefenseRepairPrompt({ errors: parsed.errors }),
+    });
+    ctx.addWave(res2.wave);
+    if (isAbortExit(res2.exitCode)) { return { raiser, aborted: res2.exitCode }; }
+    const leg2 = res2.leg && res2.leg.status === 'complete' ? res2.leg : null;
+    parsed = leg2 ? parseDebateDefense(leg2.summary, expectedIds) : parsed;
+    conformance = parsed.ok ? 'repaired' : 'unstructured';
+    if (leg2) { leg = leg2; }
+  }
+  // A dead leg (no complete summary) OR an 'unstructured' conformance after the one
+  // repair is a debate degradation (spec §5.7) — surfaced via the returned leg.
+  const stub = { model: raiser, status: 'error', durationMs: null, usage: null, conformance: 'unstructured', summary: '' };
+  return { raiser, byId: parsed.byId,
+    leg: leg ? { model: raiser, status: leg.status, durationMs: leg.durationMs, usage: leg.usage, conformance, summary: leg.summary } : stub };
+}
+
+async function runRevoteWave(ctx, judges, bundleFindings) {
+  const bundle = dbrief.buildRevoteBundle({ findings: bundleFindings, date: ctx.o.date });
+  // spec §5.1 names `revote-bundle.md` a run-dir artifact: the shared re-vote prompt goes to
+  // disk exactly like Stage 2's bundle-stage2.md, so the round's model-facing input is
+  // auditable alongside briefing-stage1.md and chair-packet.md.
+  fs.writeFileSync(path.join(ctx.o.runDir, 'revote-bundle.md'), bundle, { mode: 0o600 });
+  const waveId = `${ctx.o.runId}-rv`;
+  const expectedIds = bundleFindings.map(f => f.id);
+  // run-debate — not run.js — owns this stage's `running` checkpoint AND its abort-cascade
+  // id: only this function knows whether the wave actually launched (it is skipped when
+  // nothing was defended/amended, or the cost ceiling hit).
+  runState.updateStage(ctx.o.runDir, 'debate-revote',
+    { status: 'running', startedAt: new Date().toISOString(), project: ctx.scratchDir, waveId });
+  runState.appendStageWave(ctx.o.runDir, 'debate-revote', waveId);
+  const res = await ctx.launchers.launchWave({ ...legOpts(ctx, waveId), models: judges, prompt: bundle });
+  ctx.addWave(res.wave);
+  if (isAbortExit(res.exitCode)) { return { aborted: res.exitCode }; }
+  const byJudge = {}, legs = [];
+  for (const leg of ((res.wave && res.wave.legs) || [])) {
+    // The council ALIAS, not the resolved executable id — runStats rows join
+    // meta.models by exact string (run-assemble.js's buildRunStatsEntry).
+    const judge = leg.modelInput || leg.model;
+    const alive = leg.status === 'complete' && leg.summary;
+    let outLeg = leg;               // the leg actually recorded (post-repair when there is one)
+    let parsed = alive ? parseRevote(leg.summary, expectedIds)
+      : { ok: false, byId: {}, errors: [{ code: 'DEAD_LEG', detail: 'no summary' }] };
+    let conformance = alive ? 'clean' : 'unstructured';
+    if (alive && !parsed.ok) {
+      // One repair, solo, to that judge.
+      const repairId = `${waveId}-${judge}r`;
+      runState.appendStageWave(ctx.o.runDir, 'debate-revote', repairId);
+      const r2 = await ctx.launchers.launchSolo({ ...legOpts(ctx, repairId), model: judge,
+        prompt: dbrief.buildRevoteRepairPrompt({ errors: parsed.errors }) });
+      ctx.addWave(r2.wave);
+      if (isAbortExit(r2.exitCode)) { return { aborted: r2.exitCode }; }
+      const leg2 = r2.leg && r2.leg.status === 'complete' ? r2.leg : null;
+      parsed = leg2 ? parseRevote(leg2.summary, expectedIds) : parsed;
+      conformance = parsed.ok ? 'repaired' : 'unstructured';
+      // Symmetric with runDefenseSolo's `if (leg2) { leg = leg2; }` — otherwise
+      // revote-<model>.md and the runStats row keep the PRE-repair output.
+      if (leg2) { outLeg = leg2; }
+    }
+    byJudge[judge] = parsed.byId;
+    legs.push({ model: judge, status: outLeg.status, durationMs: outLeg.durationMs, usage: outLeg.usage, conformance, summary: outLeg.summary || '' });
+  }
+  return { byJudge, legs };
+}
+
+/** The re-vote bundle: defended-or-amended findings ONLY (spec §5.1 — withdrawn never appear). */
+function bundleFor(defenseResults, tallyInput) {
+  const out = [];
+  for (const dr of defenseResults) {
+    for (const [id, resp] of Object.entries(dr.byId)) {
+      if (resp.action !== 'defend' && resp.action !== 'amend') { continue; }
+      const src = tallyInput.findings.find(f => f.id === id) || {};
+      out.push({ id, severity: src.severity, amended: resp.action === 'amend',
+        claim: resp.action === 'amend' ? resp.claim : src.claim,
+        argument: resp.argument || 'defended without extra argument' });
+    }
+  }
+  return out;
+}
+
+/**
+ * Full Stage-2.5 sequence (spec §5.1). Returns everything run.js needs. Cost gate: run.js
+ * checks overBudget before invoking; this checks again before the re-vote wave (spec §5.7).
+ * @param {object} ctx run.js's {o, launchers, addWave, overBudget, scratchDir}
+ * @param {{provisionalRecord: object, tallyInput: object}} args
+ */
+async function runDebate(ctx, { provisionalRecord, tallyInput }) {
+  const { byRaiser, previousTier } = debateTargets(provisionalRecord, tallyInput);
+  const contested = provisionalRecord.findings.filter(f => f.tier === 'Contested').length;
+  const disputed = provisionalRecord.findings.filter(f => f.tier === 'Disputed').length;
+
+  // ---- Defense mini-wave: ONE CONCURRENT solo per raiser (spec §5.1) ----
+  // Concurrent, not sequential: every raiser gets its OWN briefing, so this is N independent
+  // solos rather than one fanout wave. No per-leg budget check interleaves between them — the
+  // cost ceiling is a WHOLE-ROUND gate run.js applies BEFORE calling runDebate
+  // ('skipped-cost-ceiling' is a round-level outcome in spec §5.1's enum, not a per-leg one).
+  // `appendStageWave` is sync fs and each solo registers its waveId before its first await,
+  // so concurrency cannot interleave a read-modify-write of run.json.
+  // v4.1 §4.4: the reserved seat 'claude' is a FILE-sourced review with no leg to
+  // launch, so it is never asked to defend — its contested findings simply stand
+  // (the same "originals stand" outcome as a no-response).
+  const raisers = Object.keys(byRaiser).filter(m => m !== 'claude');
+  const defenseResults = await Promise.all(
+    raisers.map((raiser, i) => runDefenseSolo(ctx, raiser, byRaiser[raiser], i)));
+  // A signal during the defense wave aborts the whole finalization (spec §5.7):
+  // return the abort code so run.js finalizes 'aborted' with NO tally-final / NO ledger.
+  const abortedDefense = defenseResults.find(d => d.aborted);
+  if (abortedDefense) { return { aborted: abortedDefense.aborted, contested, disputed }; }
+  materializeDebate(ctx.o.runDir, defenseResults.map(d => ({ model: d.raiser, summary: d.leg.summary })), 'rebuttal');
+
+  const defenseByRaiser = {};
+  for (const dr of defenseResults) { defenseByRaiser[dr.raiser] = { ...dr.byId }; }
+  // v4.1 §4.4: claude never gets a defense leg (raisers filter above), but its
+  // contested/disputed findings still need an audit trail — the SAME spec §5.7
+  // "originals stand" fallback a dead/unrepaired defense leg gets. Seeded into
+  // defenseByRaiser ONLY (never defenseResults, which feeds the `bad(l)`
+  // degraded check below — a claude entry there would wrongly flip a clean run
+  // to degraded/exit 2).
+  if (byRaiser.claude) { defenseByRaiser.claude = allNoResponse(byRaiser.claude.map(f => f.id)); }
+  // Stamp previousTier onto the tally input: applyDebate reads it off tallyInput.findings[]
+  // (it ignores the provisional record), so without this every row's previousTier is null.
+  const stampedInput = { ...tallyInput, findings: tallyInput.findings.map(f => ({ ...f, previousTier: previousTier[f.id] })) };
+
+  // ---- Re-vote mini-wave (disputing judges only) ----
+  let revoteByJudge = {}, revoteLegs = [];
+  const defendedOrAmended = bundleFor(defenseResults, tallyInput);
+  const judges = disputingJudges(provisionalRecord, defendedOrAmended.map(f => f.id));
+  // A re-vote is warranted only when something was defended/amended AND ≥1 judge disputed it.
+  // Skipping THAT case because the whole-run budget is spent is the 'skipped-cost-ceiling'
+  // degradation branch (spec §5.7); skipping because there is simply nothing to re-vote is NOT.
+  const wouldRevote = defendedOrAmended.length > 0 && judges.length > 0;
+  const costCeiling = ctx.overBudget() && wouldRevote;
+  if (wouldRevote && !costCeiling) {
+    const rv = await runRevoteWave(ctx, judges, defendedOrAmended);
+    if (rv.aborted) { return { aborted: rv.aborted, contested, disputed }; }
+    revoteByJudge = rv.byJudge;
+    revoteLegs = rv.legs;
+    // revote-<model>.md per surviving judge leg, mirroring rebuttal-<model>.md
+    // (spec §5.1 'raw outputs revote-<model>.md').
+    materializeDebate(ctx.o.runDir, revoteLegs, 'revote');
+  }
+
+  // ---- Pure reassembly ----
+  const { input: debatedInput, debateFindings } = applyDebate({
+    tallyInput: stampedInput, provisionalRecord, defenseByRaiser, revoteByJudge });
+  debatedInput.runStats = [...(debatedInput.runStats || []),
+    ...debateRunStatsRows({ defenseLegs: defenseResults.map(d => d.leg), revoteLegs })];
+
+  // verdictChanges: findings whose tier moved from provisional to debated.
+  const provTierById = new Map(provisionalRecord.findings.map(f => [f.id, f.tier]));
+  const debatedRec = tally(debatedInput);
+  let verdictChanges = 0;
+  for (const f of debatedRec.findings) { if (provTierById.get(f.id) !== f.tier) { verdictChanges += 1; } }
+
+  // ---- Artifacts + summary ----
+  const revotesJson = [];
+  for (const [judge, perId] of Object.entries(revoteByJudge)) {
+    for (const [id, rv] of Object.entries(perId)) { revotesJson.push({ judge, id, verdict: rv.verdict, reason: rv.reason || null, applied: true }); }
+  }
+  fs.writeFileSync(path.join(ctx.o.runDir, 'debate.json'),
+    JSON.stringify({ findings: debateFindings, revotes: revotesJson }, null, 2), { mode: 0o600 });
+
+  const counts = { defended: 0, amended: 0, withdrawn: 0, noResponse: 0 };
+  const COUNT_KEY = { defend: 'defended', amend: 'amended', withdraw: 'withdrawn' };
+  for (const df of debateFindings) { counts[COUNT_KEY[df.action] || 'noResponse'] += 1; }
+  const debateSummary = {
+    enabled: true, outcome: costCeiling ? 'skipped-cost-ceiling' : 'ran',
+    contested, disputed, ...counts,
+    revoteJudges: revoteLegs.length, revoteApplied: revotesJson.length, verdictChanges,
+  };
+
+  // ---- Degradation (spec §5.7) → run.js maps this to exit code 2 ----
+  // A dead/unstructured-after-repair defense solo, a partial or fully-dead re-vote wave, or a
+  // cost-ceiling skip of a warranted re-vote each degrade the run. (Abort short-circuits above;
+  // nothing-to-debate and a clean run are NOT degradations.)
+  const bad = (l) => l.status !== 'complete' || l.conformance === 'unstructured';
+  const degraded = defenseResults.some(d => bad(d.leg)) || revoteLegs.some(bad) || costCeiling;
+
+  // Chair-addendum outcomes (spec §5.3c). `action` is the PAST_TENSE form
+  // buildDebateAddendum renders verbatim — only the four valid values ever reach it.
+  const priorById = new Map(provisionalRecord.findings.map(
+    f => [f.id, Object.fromEntries((f.adjudications || []).map(a => [a.judge, a.verdict]))]));
+  const addendumOutcomes = debateFindings.map(df => ({
+    id: df.id, originalClaim: (tallyInput.findings.find(f => f.id === df.id) || {}).claim,
+    action: PAST_TENSE[df.action] || PAST_TENSE['no-response'],
+    amendedClaim: df.action === 'amend' ? df.claim : null,
+    priorVerdicts: priorById.get(df.id) || {},
+    revotes: Object.fromEntries(revotesJson.filter(r => r.id === df.id).map(r => [r.judge, r.verdict])),
+  }));
+
+  return { debatedInput, debateFindings, debateSummary, addendumOutcomes,
+    defenseLegs: defenseResults.map(d => d.leg), revoteLegs, verdictChanges,
+    degraded, aborted: null };
+}
+
+module.exports = { runDebate, nothingToDebate, disputingJudges, debateTargets };

package/src/council/run-launch.js

@@ -43,6 +43,13 @@ function createLaunchers(deps = {}) {
       includeContext: false,
       gatewayMode: opts.gateway,
       noValidateModel: opts.noValidateModel,
+      // v4.1 §4.5d: `--no-cost-gate` is a WHOLE-RUN opt-out (an intentional
+      // o3-class council), so it has to ride every council launch — otherwise
+      // fanout's per-$/Mtok gate refuses the first repair or the chair
+      // mid-council. Transport key is literally `noCostGate` (fanout.js
+      // guards with `if (!options.noCostGate)`); the CALLERS assemble these
+      // option objects, so run-stages/run-chair/run-debate each set it.
+      noCostGate: !!opts.noCostGate,
       json: false,
       quiet: true,
       // Spec §6 judge isolation: pin every leg's OpenCode tool-exec cwd to its
@@ -96,4 +103,23 @@ function materializeReviews(runDir, legs) {
   return out;
 }
 
-module.exports = { createLaunchers, materializeReviews, sanitizeName };
+/**
+ * Write per-leg debate artifacts: `<prefix>-<sanitizeName(model)>.md` for each
+ * leg with a non-empty summary. Mirrors materializeReviews.
+ * @param {string} runDir
+ * @param {Array<{model: string, summary: string}>} legs
+ * @param {string} prefix 'rebuttal' | 'revote'
+ * @returns {Array<{model: string, file: string}>}
+ */
+function materializeDebate(runDir, legs, prefix) {
+  const out = [];
+  for (const leg of legs) {
+    if (!leg || !leg.summary || !leg.summary.trim()) { continue; }
+    const file = path.join(runDir, `${prefix}-${sanitizeName(leg.model)}.md`);
+    fs.writeFileSync(file, leg.summary, { mode: 0o600 });
+    out.push({ model: leg.model, file });
+  }
+  return out;
+}
+
+module.exports = { createLaunchers, materializeReviews, materializeDebate, sanitizeName };