amicus 3.2.3 → 4.0.1

package/src/council/run-stages.js

@@ -0,0 +1,203 @@
+// src/council/run-stages.js
+'use strict';
+
+/**
+ * @module council/run-stages
+ * Stage-1 (independent reviews) and Stage-2 (anonymized cross-review) loops
+ * for the headless council engine — launch, materialize, validate, bounded
+ * repair. Split from run.js for the 300-line gate. All model calls go through
+ * ctx.launchers (DI); the whole-run cost ceiling is consulted via
+ * ctx.overBudget() before every paid repair launch (spec §4).
+ *
+ * Headless adaptations (vs SKILL.md):
+ *  - A review still malformed after 2 repair re-prompts is KEPT with
+ *    conformance 'unstructured' and zero findings entries (the skill's Claude
+ *    hand-parse fallback has no headless equivalent; the review still gets
+ *    ranked in Stage 2).
+ *  - A judge still malformed after 2 repairs is dropped from rankings and
+ *    adjudications (ok:false) and recorded conformance 'unstructured' (spec §5).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { validateFindings } = require('./findings');
+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; }
+
+function slug(text) {
+  return String(text).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/** Launch all Stage-1 legs (wave + critic/lens solos), collect run docs. */
+async function launchStage1(ctx) {
+  const { o, launchers } = ctx;
+  const common = {
+    project: o.runDir, timeout: o.timeout, gateway: o.gateway,
+    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) => {
+      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 }),
+      }));
+    }
+  }
+  const results = await Promise.all(launches);
+  let aborted = null;
+  const legs = [];
+  for (const r of results) {
+    ctx.addWave(r.wave);
+    if (isAbortExit(r.exitCode)) { aborted = r.exitCode; }
+    if (r.wave && Array.isArray(r.wave.legs)) { legs.push(...r.wave.legs); }
+  }
+  return { aborted, legs };
+}
+
+/** Role of a seat by its input alias. */
+function roleFor(o, alias) {
+  if (o.lenses) {
+    const i = o.models.indexOf(alias);
+    return i === -1 ? 'seat' : `lens:${slug(o.lenses[i])}`;
+  }
+  return alias === o.critic ? 'critic' : 'seat';
+}
+
+/**
+ * Stage 1: independent reviews + findings validation + bounded repair.
+ * @returns {Promise<{aborted: number|null, reviews: Array, deadLegs: Array}>}
+ */
+async function runStage1(ctx) {
+  const { o } = ctx;
+  const { aborted, legs } = await launchStage1(ctx);
+  if (aborted) { return { aborted, reviews: [], deadLegs: [] }; }
+
+  const materialized = materializeReviews(o.runDir, legs);
+  const alive = new Set(materialized.map(m => m.leg));
+  const deadLegs = legs.filter(l => !alive.has(l));
+
+  const reviews = [];
+  let repairSeq = 0;
+  for (const m of materialized) {
+    let conformance = 'clean';
+    let res = validateFindings(m.text);
+    let attempts = 0;
+    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, timeout: o.timeout,
+        gateway: o.gateway, noValidateModel: o.noValidateModel,
+      });
+      ctx.addWave(solo.wave);
+      if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, reviews, deadLegs }; }
+      res = validateFindings((solo.leg && solo.leg.summary) || '');
+      if (res.ok) { conformance = 'repaired'; }
+    }
+    if (!res.ok) { conformance = 'unstructured'; }
+    reviews.push({
+      model: m.modelInput, modelInput: m.modelInput, role: roleFor(o, m.modelInput),
+      text: m.text, findings: res.ok ? res.findings : [], conformance, leg: m.leg,
+    });
+  }
+  return { aborted: null, reviews, deadLegs };
+}
+
+/**
+ * Stage 2: shared anonymized bundle → judge wave in _scratch → parse + repair.
+ * @param {object} ctx
+ * @param {{reviews: Array, labels: {entries, labelMap}, globalFindings: Array}} args
+ * @returns {Promise<{aborted: number|null, judgeResults: Array}>}
+ */
+async function runStage2(ctx, { reviews, labels, globalFindings }) {
+  const { o } = ctx;
+  const { rankingToOrder } = require('./anonymize');
+  fs.mkdirSync(ctx.scratchDir, { recursive: true, mode: 0o700 });
+
+  const labeled = labels.entries.map((e, i) => ({ label: e.label, text: reviews[i].text }));
+  const bundle = stage2.buildJudgeBundle({ reviews: labeled, findings: globalFindings });
+  fs.writeFileSync(path.join(o.runDir, 'bundle-stage2.md'), bundle, { mode: 0o600 });
+
+  const judges = reviews.map(r => r.modelInput);
+  const parseCtx = {
+    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,
+  });
+  ctx.addWave(wave);
+  if (isAbortExit(exitCode)) { return { aborted: exitCode, judgeResults: [] }; }
+
+  const judgeResults = [];
+  let repairSeq = 0;
+  for (const leg of (wave && wave.legs) || []) {
+    const judge = leg.modelInput || leg.model;
+    if (leg.status === 'complete' && leg.summary) {
+      fs.writeFileSync(path.join(o.runDir, `judge-${sanitizeName(judge)}.md`), leg.summary, { mode: 0o600 });
+    }
+    let conformance = 'clean';
+    let parsed = (leg.status === 'complete' && leg.summary)
+      ? parseJudgeOutput(leg.summary, parseCtx)
+      : { ok: false, errors: [{ code: 'DEAD_LEG', detail: leg.error || leg.status }] };
+    let attempts = 0;
+    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, timeout: o.timeout,
+        gateway: o.gateway, noValidateModel: o.noValidateModel,
+      });
+      ctx.addWave(solo.wave);
+      if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, judgeResults }; }
+      parsed = parseJudgeOutput((solo.leg && solo.leg.summary) || '', parseCtx);
+      if (parsed.ok) { conformance = 'repaired'; }
+    }
+    if (!parsed.ok) {
+      judgeResults.push({ judge, ok: false, order: null, adjudications: null,
+        conformance: leg.status === 'complete' ? 'unstructured' : 'clean' });
+      continue;
+    }
+    const { order } = rankingToOrder(parsed.ranking, labels.labelMap);
+    judgeResults.push({ judge, ok: true, order, adjudications: parsed.adjudications, conformance });
+  }
+  return { aborted: null, judgeResults };
+}
+
+module.exports = { runStage1, runStage2, isAbortExit, slug };

package/src/council/run-state.js

@@ -0,0 +1,161 @@
+// src/council/run-state.js
+'use strict';
+
+/**
+ * @module council/run-state
+ * Durable state for one headless council run (spec §4/§5): atomic run.json
+ * read/write with checkpoint semantics, plus the sessions-dir pointer file
+ * (`council-<runId>.json` → {runId, runDir}) that lets status/wait/list/abort
+ * resolve council runIds without knowing --out-dir.
+ *
+ * Abort-wins: once run.json's status is 'aborted', no later checkpoint can
+ * demote it (same precedence rule as fanout's writeWaveMetadata — an external
+ * `amicus abort` must never lose a write race against the engine's own
+ * finalize).
+ */
+
+const fs = require('fs');
+const path = require('path');
+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) {
+  try { return JSON.parse(fs.readFileSync(runPath(runDir), 'utf-8')); }
+  catch { return null; }
+}
+
+/** Abort-wins merge: once status is 'aborted', it cannot change to anything else. */
+function mergeRun(existing, patch) {
+  const merged = { ...existing, ...patch };
+  // If the prior run was aborted, preserve that status regardless of patch content
+  // (prevents falsy status values, null, '', or omitted status from overwriting)
+  if (existing.status === 'aborted' || patch.status === 'aborted') {
+    merged.status = 'aborted';
+    // An aborted run is terminal: never let a later (racing) finalize report a
+    // clean/degraded exitCode. Prefer a recorded abort code, then a patch abort
+    // code, else default SIGTERM's 143.
+    const prior = [130, 143].includes(existing.exitCode) ? existing.exitCode : null;
+    const fromPatch = [130, 143].includes(patch.exitCode) ? patch.exitCode : null;
+    merged.exitCode = prior || fromPatch || 143;
+  }
+  return merged;
+}
+
+function writeRun(runDir, run) {
+  writeFileAtomic(runPath(runDir), JSON.stringify(run, null, 2), { mode: 0o600 });
+  return run;
+}
+
+/** Create (or merge into) run.json; preserves an existing createdAt. */
+function initRun(runDir, seed) {
+  fs.mkdirSync(runDir, { recursive: true, mode: 0o700 });
+  const existing = readRun(runDir) || {};
+  const run = mergeRun(existing, {
+    ...seed,
+    createdAt: existing.createdAt || seed.createdAt,
+  });
+  return writeRun(runDir, run);
+}
+
+/** Read-merge-write checkpoint (atomic; abort-wins on status). */
+function checkpoint(runDir, patch) {
+  const existing = readRun(runDir) || {};
+  return writeRun(runDir, mergeRun(existing, patch));
+}
+
+/** Upsert one stages[] entry by name; other stages and order preserved. */
+function updateStage(runDir, name, patch) {
+  const existing = readRun(runDir) || {};
+  const stages = Array.isArray(existing.stages) ? existing.stages.slice() : [];
+  const i = stages.findIndex(s => s && s.name === name);
+  if (i === -1) { stages.push({ name, ...patch }); }
+  else { stages[i] = { ...stages[i], ...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` */
+function pointerPath(project, runId) {
+  return path.join(project, '.claude', SESSIONS_DIR, `council-${stripPrefix(runId)}.json`);
+}
+
+function writePointer(project, runId, runDir) {
+  const p = pointerPath(project, runId);
+  fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+  writeFileAtomic(p, JSON.stringify({ runId: stripPrefix(runId), runDir }, null, 2), { mode: 0o600 });
+  return p;
+}
+
+/** @returns {{runId: string, runDir: string}|null} */
+function readPointer(project, runId) {
+  try {
+    const ptr = JSON.parse(fs.readFileSync(pointerPath(project, runId), 'utf-8'));
+    return (ptr && ptr.runId && ptr.runDir) ? ptr : null;
+  } catch { return null; }
+}
+
+/** All council pointers in the project sessions dir. */
+function listPointers(project) {
+  const root = path.join(project, '.claude', SESSIONS_DIR);
+  let names = [];
+  try { names = fs.readdirSync(root); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    if (!/^council-[a-zA-Z0-9_-]{1,64}\.json$/.test(n)) { continue; }
+    try {
+      const ptr = JSON.parse(fs.readFileSync(path.join(root, n), 'utf-8'));
+      if (ptr && ptr.runId && ptr.runDir) { out.push(ptr); }
+    } catch { /* skip corrupt pointer */ }
+  }
+  return out;
+}
+
+module.exports = {
+  RUN_FILE, readRun, initRun, checkpoint, updateStage, appendStageWave,
+  writeSpawnPid, readSpawnPid,
+  pointerPath, writePointer, readPointer, listPointers,
+};

package/src/council/run.js

@@ -0,0 +1,277 @@
+// src/council/run.js
+'use strict';
+
+/**
+ * @module council/run
+ * Headless council driver (spec §5): stage state machine over the DI launch
+ * wrappers — Stage-1 reviews → anonymized Stage-2 cross-review → tally →
+ * chair synthesis → verdict/report — checkpointing run.json after every
+ * stage (run-state) and consuming the existing pure primitives unchanged
+ * (tally, buildVerdict via run-assemble, report renderers, ledger).
+ *
+ * Tally sequencing: an in-memory provisional tally feeds the chair packet;
+ * the on-disk tally-input.json/tally.json are FINAL (chair runStats row
+ * included, actual chair in meta) and only the final record is ledgered —
+ * the skill's debate-mode provisional/final precedent.
+ *
+ * Never rejects for run errors: always resolves {exitCode, run}.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { tally } = require('./tally');
+const { assignLabels, toGlobalFindings } = require('./anonymize');
+const briefings = require('./briefings');
+const stage2 = require('./briefings-stage2');
+const { parseChairVerdict } = require('./parse-stage2');
+const runState = require('./run-state');
+const { createLaunchers } = require('./run-launch');
+const { runStage1, runStage2, isAbortExit } = require('./run-stages');
+const asm = require('./run-assemble');
+const { sumWaveUsage } = require('../utils/pricing');
+
+const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143, SIGBREAK: 143 };
+
+/**
+ * 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).
+ * @returns {string|null}
+ */
+function pickFallbackChair(statsRows, bench, failedChair) {
+  const benchSet = new Set(bench);
+  const candidates = (statsRows || [])
+    .filter(r => !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;
+}
+
+/**
+ * @param {object} options {briefing, models, chair, critic?, lenses?, project,
+ *   runId, runDir, timeout?, maxCost?, gateway?, noValidateModel?, date}
+ * @param {object} [deps] {launchers?, appendRunFn?, statsFn?, installSignalAbortFn?}
+ * @returns {Promise<{exitCode: number, run: object}>}
+ */
+async function runCouncil(options, deps = {}) {
+  const o = { critic: null, lenses: null, maxCost: null, ...options };
+  const launchers = deps.launchers || createLaunchers();
+  const appendRunFn = deps.appendRunFn || require('./ledger').appendRun;
+  const statsFn = deps.statsFn || require('./ledger').deriveReliability;
+  const installSignals = deps.installSignalAbortFn
+    || require('../utils/session-abort').installSignalAbort;
+  const now = () => new Date().toISOString();
+
+  const allLegs = [];
+  const addWave = (wave) => { if (wave && Array.isArray(wave.legs)) { allLegs.push(...wave.legs); } };
+  const spent = () => {
+    const c = sumWaveUsage(allLegs).cost;
+    return typeof c.amount === 'number' ? c.amount : 0;
+  };
+  const overBudget = () => o.maxCost !== null && o.maxCost !== undefined && spent() >= o.maxCost;
+
+  runState.initRun(o.runDir, {
+    schemaVersion: 2, type: 'council-run', runId: o.runId, status: 'running', stages: [],
+    bench: o.models.slice(), chair: o.chair, critic: o.critic, lenses: o.lenses,
+    labelMap: null,
+    options: { timeout: o.timeout || null, maxCost: o.maxCost, gateway: o.gateway || 'auto', outDir: o.runDir },
+    usage: null, pid: process.pid, createdAt: now(),
+  });
+  runState.writePointer(o.project, o.runId, o.runDir);
+
+  let signalled = null;
+  const uninstall = installSignals({
+    onAbort: (signal) => {
+      signalled = SIGNAL_EXIT[signal] || 143;
+      runState.checkpoint(o.runDir, { status: 'aborted', exitCode: signalled, completedAt: now() });
+    },
+  });
+
+  const degraded = { value: false };
+  const finalize = (exitCode, error) => {
+    uninstall();
+    const code = signalled || exitCode;
+    const status = (code === 130 || code === 143) ? 'aborted'
+      : code === 0 ? 'complete' : code === 1 ? 'error' : 'partial';
+    const run = runState.checkpoint(o.runDir, {
+      status, exitCode: code, error: error || null,
+      usage: { cost: sumWaveUsage(allLegs).cost },
+      completedAt: now(),
+    });
+    return { exitCode: code, run };
+  };
+
+  const ctx = { o, launchers, addWave, overBudget, scratchDir: path.join(o.runDir, '_scratch') };
+
+  try {
+    // Composed Stage-1 seat briefing persisted for auditability (spec §4 layout).
+    fs.writeFileSync(path.join(o.runDir, 'briefing-stage1.md'),
+      briefings.buildSeatBriefing({ briefing: o.briefing, date: o.date }), { mode: 0o600 });
+
+    // ---- Stage 1: independent reviews ----
+    // 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(),
+      taskIds: s1.reviews.map(r => (r.leg && r.leg.taskId)).filter(Boolean),
+    });
+    if (signalled || s1.aborted) { return finalize(s1.aborted || signalled); }
+    if (s1.deadLegs.length > 0) { degraded.value = true; } // bench shrank → never a "full run"
+    if (s1.reviews.length < 2) {
+      return finalize(1, {
+        code: 'COUNCIL_QUORUM',
+        message: `Only ${s1.reviews.length} Stage-1 review(s) survived; a council needs at least 2`,
+      });
+    }
+
+    // ---- Cost gate: Stage 2 is a paid launch; no tally exists yet (spec §4) ----
+    if (overBudget()) {
+      return finalize(1, {
+        code: 'COST_EXCEEDED',
+        message: `Cost ceiling $${o.maxCost} reached before cross-review; no tally exists`,
+      });
+    }
+
+    // ---- Stage 2: anonymized cross-review ----
+    const labels = assignLabels(s1.reviews.map(r => r.model));
+    runState.checkpoint(o.runDir, { labelMap: labels.labelMap });
+    // Attach each review's run-global findings (buildTallyInput reads
+    // r.globalFindings per review, not a bare parallel array).
+    s1.reviews.forEach((r, i) => {
+      r.globalFindings = toGlobalFindings(labels.entries[i].letter, r.model, r.findings);
+    });
+    const globalFindings = s1.reviews.flatMap(r => r.globalFindings);
+    runState.updateStage(o.runDir, 'stage2',
+      { status: 'running', startedAt: now(), waveId: `${o.runId}-s2`, project: ctx.scratchDir });
+    const s2 = await runStage2(ctx, { reviews: s1.reviews, labels, globalFindings });
+    runState.updateStage(o.runDir, 'stage2', { status: 'complete', completedAt: now() });
+    if (signalled || s2.aborted) { return finalize(s2.aborted || signalled); }
+    if (s2.judgeResults.filter(j => j.ok).length < 2) { degraded.value = true; } // thin cross-review
+
+    // Merge Stage-2 judging conformance into each seat's row (worst wins).
+    const byJudge = new Map(s2.judgeResults.map(j => [j.judge, j]));
+    for (const r of s1.reviews) {
+      const j = byJudge.get(r.model);
+      if (j) { r.conformance = asm.worseConformance(r.conformance, j.conformance); }
+    }
+
+    // ---- Chair synthesis (provisional tally feeds the packet) ----
+    const mkInput = (chairStats, chairModel) => asm.buildTallyInput({
+      runId: o.runId, date: o.date, bench: o.models.slice(), chair: chairModel,
+      reviews: s1.reviews, judgeResults: s2.judgeResults, chairStats,
+    });
+    const provisionalInput = mkInput(null, o.chair);
+    const provisional = tally(provisionalInput);
+
+    const packet = stage2.buildChairPacket({
+      reviews: s1.reviews.map(r => ({ model: r.model, text: r.text })),
+      rankings: provisionalInput.rankings,
+      adjudications: provisionalInput.adjudications,
+      tierCounts: provisional.tierCounts,
+    });
+    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,
+      });
+      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) || signalled) { return finalize(attempt.exitCode || signalled); }
+      if (!attempt.leg && !overBudget()) {
+        attempt = await attemptChair(o.chair, `${o.runId}-ch2`);
+        if (isAbortExit(attempt.exitCode) || signalled) { return finalize(attempt.exitCode || signalled); }
+      }
+      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) || signalled) { return finalize(attempt.exitCode || signalled); }
+          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,
+      });
+      addWave(repair.wave);
+      if (isAbortExit(repair.exitCode) || signalled) { return finalize(repair.exitCode || signalled); }
+      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
+
+    // ---- Final tally (chair row included) + ledger + artifacts ----
+    const chairStats = chairLeg ? asm.buildRunStatsEntry({
+      leg: chairLeg, model: actualChair, role: 'chair', wasChair: true,
+      conformance: chairConformance,
+    }) : null;
+    const finalInput = mkInput(chairStats, actualChair || o.chair);
+    const record = tally(finalInput);
+    if (!o.lenses) {
+      // Lens runs never feed cross-run reliability stats (spec §4 / skill rule).
+      try { appendRunFn(record); }
+      catch (e) { process.stderr.write(`Notice: council ledger append failed: ${e.message}\n`); }
+    }
+    asm.writeTallyFiles({ runDir: o.runDir, tallyInput: finalInput, record });
+    runState.updateStage(o.runDir, 'tally', { status: 'complete', completedAt: now() });
+    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText });
+    runState.updateStage(o.runDir, 'verdict', { status: 'complete', completedAt: now() });
+
+    return finalize(degraded.value ? 2 : 0);
+  } catch (err) {
+    return finalize(1, { code: 'INTERNAL', message: err.message });
+  }
+}
+
+module.exports = { runCouncil, pickFallbackChair, SIGNAL_EXIT };

package/src/council/tally.js

@@ -66,7 +66,8 @@ function computeStreetCred(rankings, models) {
   });
 }
 
-const COUNCIL_SCHEMA_VERSION = 1;
+// v4.0 §7: council family v2 — every council doc carries {schemaVersion, type}.
+const COUNCIL_SCHEMA_VERSION = 2;
 const VERDICTS = { agree: 'a', dispute: 'd', neutral: 'n' };
 
 function countTiers(findings) {
@@ -106,6 +107,7 @@ function tally(input) {
   });
   return {
     schemaVersion: COUNCIL_SCHEMA_VERSION,
+    type: 'council-tally',
     meta,
     judged: Array.isArray(rankings) && rankings.length >= 2,
     streetCred: computeStreetCred(rankings || [], meta.models),