amicus 4.5.4 → 4.6.0

package/src/council/report-html.js

@@ -11,6 +11,7 @@ const { formatCost } = require('../utils/pricing');
 const { formatDuration } = require('../utils/format-duration');
 const { TIER_ORDER, SYMBOL } = require('./report');
 const { tokenCss } = require('../design/tokens');
+const { formatDegrade } = require('../utils/degrade');
 
 const TIER_VAR = {
   Disputed: 'var(--tier-disputed)',
@@ -52,9 +53,23 @@ function renderHtml(m) {
   const costRows = m.cost.rows.map(r =>
     `<tr><td>${esc(r.model)}</td><td>${esc(r.status)}</td><td>${dur(r.durationMs)}</td>` +
     `<td>${esc(formatCost(r.cost))}</td></tr>`).join('');
+  // v4.6 Plan 2: 'What was lost' rows — m.degrades is absent on hand-built
+  // models (same tolerance as m.debate below); ONE voice (Plan 1's
+  // formatDegrade) rendered into the row, not a second HTML dialect.
+  const lostRows = (m.degrades || []).map(d =>
+    `<tr><td>${esc(d.channel)}</td><td>${esc(formatDegrade(d).trimEnd())}</td></tr>`).join('');
   const meta = [h.date, h.chair ? `chair: ${h.chair}` : null, `council: ${h.council.join(', ')}`,
     h.claudeInCouncil ? 'Claude in council' : null].filter(Boolean).map(esc).join(' · ');
 
+  // Heading-over-nothing, same guard idiom as debateSection below: absent or
+  // empty degrades ⇒ no section at all, so a clean verdict's HTML stays
+  // byte-identical to before this section existed. Losses are headline news,
+  // so the section sits directly after the Verdict-summary table (report.js's
+  // renderMd mirrors this placement immediately after the tier loop).
+  const lostSection = lostRows
+    ? `<h2>What was lost</h2><table><tr><th>Channel</th><th>Notice</th></tr>${lostRows}</table>`
+    : '';
+
   // m.debate is absent on hand-built models (tests/council/report.test.js calls
   // renderHtml directly with no debate key) — the guard must tolerate that, and
   // absent/empty ⇒ no section at all so a no-debate report stays byte-identical
@@ -113,7 +128,7 @@ td.c { text-align: center; }
 <h1>Council Report — ${esc(h.runType)} (${esc(h.runId)})</h1>
 <p class="meta">${meta}</p>
 <h2>Verdict summary</h2>
-<table><tr><th>Tier</th><th>Count</th></tr>${tierRows}</table>
+<table><tr><th>Tier</th><th>Count</th></tr>${tierRows}</table>${lostSection}
 <h2>Adjudication matrix</h2>
 <table><tr><th>Finding</th><th>Sev</th><th>Raiser</th>${judgeHead}<th>Tier</th><th>Decision</th></tr>${matrixRows}</table>
 <p class="legend">✓ agree · ✗ dispute · – neutral · <sup>*</sup> raiser's own vote</p>

package/src/council/report.js

@@ -11,6 +11,7 @@
 
 const { formatCost, sumWaveUsage } = require('../utils/pricing');
 const { formatDuration } = require('../utils/format-duration');
+const { formatDegrade } = require('../utils/degrade');
 
 const TIER_ORDER = ['Disputed', 'Contested', 'Confirmed', 'Singleton'];
 const SYMBOL = { agree: '✓', dispute: '✗', neutral: '–' };
@@ -65,8 +66,14 @@ function toModel(verdict, wave) {
       .map(f => ({ id: f.id, previousTier: f.debate.previousTier, tier: f.tier })),
   };
   const runStats = verdict.runStats || [];
+  // Cost-row role tag (Plan 2 final review F1): #83 gave judges their own
+  // runStats row, so a bench model can now appear twice (seat + judge),
+  // indistinguishable by `model` alone. Tag ONLY judge rows — old verdicts have
+  // no judge rows at all, so chair/critic/lens/seat rows stay byte-identical to
+  // their historical rendering.
   const costRows = runStats.map(r => ({
-    model: r.model, status: r.status, durationMs: r.durationMs,
+    model: r.role === 'judge' ? `${r.model} (judge)` : r.model,
+    status: r.status, durationMs: r.durationMs,
     cost: r.usage && r.usage.cost ? r.usage.cost : null,
   }));
   const total = (wave && wave.usage && wave.usage.cost) ? wave.usage.cost : sumWaveUsage(runStats).cost;
@@ -78,6 +85,13 @@ function toModel(verdict, wave) {
     tierCounts: verdict.tierCounts || { Confirmed: 0, Contested: 0, Singleton: 0, Disputed: 0 },
     judges, findings, debate,
     streetCred: verdict.streetCred || [],
+    // v4.6 Plan 2: additive and OPTIONAL on the verdict (verdict.js only sets
+    // it when the run actually degraded), so a clean verdict's model — and
+    // therefore its rendered report — is byte-for-byte unchanged.
+    // Plan 2 final review F2: LOSSES ONLY — a heal is announced on stderr/run.json but
+    // is not a loss (spec D4, §8), so it must never render under "What was
+    // lost". deriveSeatLoss (verdict.js) applies the same kind !== 'heal' filter.
+    degrades: (verdict.degrades || []).filter(d => d.kind !== 'heal'),
     cost: { rows: costRows, total },
   };
 }
@@ -97,6 +111,16 @@ function renderMd(m) {
   out.push('| Tier | Count |\n|---|---|');
   for (const t of TIER_ORDER) { out.push(`| ${t} | ${m.tierCounts[t]} |`); }
 
+  // Heading-over-nothing: emitted ONLY when the run actually degraded, so a
+  // clean verdict's report stays byte-identical to before this section
+  // existed. Losses are headline news, so they sit directly under the
+  // summary, before the reader reaches the adjudication detail.
+  if (m.degrades.length) {
+    out.push('\n## What was lost\n');
+    // ONE voice (Plan 1's formatDegrade) — the report must not grow a dialect.
+    for (const d of m.degrades) { out.push(`- ${formatDegrade(d).trimEnd()}`); }
+  }
+
   out.push('\n## Adjudication matrix\n');
   out.push(`| Finding | Sev | Raiser | ${m.judges.join(' | ')} | Tier | Decision |`);
   out.push(`|---|---|---|${m.judges.map(() => '---').join('|')}|---|---|`);

package/src/council/run-assemble.js

@@ -19,7 +19,7 @@
 const fs = require('fs');
 const path = require('path');
 const { writeFileAtomic } = require('../utils/atomic-write');
-const { buildVerdict, summarizeSeatLoss, writeVerdictAtomic } = require('./verdict');
+const { buildVerdict, summarizeSeatLoss, deriveSeatLoss, writeVerdictAtomic } = require('./verdict');
 const { buildReport } = require('./report');
 const { validateFindings } = require('./findings');
 const { toGlobalFindings } = require('./anonymize');
@@ -160,6 +160,16 @@ function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, cha
     findings.push(...claudeReview.globalFindings);
     runStats.push(claudeRunStatsRow());
   }
+  // #83 (v4.6 Plan 2): Stage-2 judge legs are ~38% of a run's cost and had no
+  // runStats row at all — per-leg cost was unattributable from the artifact.
+  // One row per judge, attributing the judge's ORIGINAL Stage-2 wave leg (never
+  // a repair solo's — run-stage2.js mirrors Stage-1's convention there); a judge
+  // whose wave leg died still gets an honest error row.
+  for (const j of (judgeResults || [])) {
+    runStats.push(buildRunStatsEntry({
+      leg: j.leg, model: j.judge, role: 'judge', conformance: j.conformance,
+    }));
+  }
   if (chairStats) { runStats.push(chairStats); }
   return { meta, findings, adjudications, rankings, runStats };
 }
@@ -176,14 +186,22 @@ function writeTallyFiles({ runDir, tallyInput, record }) {
  * Undecided verdict + deterministic report. Sets the nullable overallVerdict
  * (council family v2, Plan A) on buildVerdict's output — independent of
  * buildVerdict's own signature.
+ * @param {{runDir: string, record: object, overallVerdict?: (string|null),
+ *   chairText?: string, critic?: string, deadWaves?: Array<object>,
+ *   degrades?: Array<object>}} o `degrades` (v4.6 Plan 2), when present, is
+ *   both carried onto the verdict and used to DERIVE `seatLoss` (deriveSeatLoss)
+ *   in preference to summarizing it from `deadWaves` (summarizeSeatLoss).
  * @returns {object} the verdict written to disk
  */
-function writeVerdictFiles({ runDir, record, overallVerdict, chairText, critic, deadWaves }) {
-  // v4.5.2 — computed here rather than in run.js so verdict assembly stays in
-  // one place; see summarizeSeatLoss in ./verdict for why a lost critic has to
-  // reach the verdict at all.
-  const seatLoss = summarizeSeatLoss({ runId: record.meta.runId, critic, deadWaves });
-  const verdict = buildVerdict(record, [], { seatLoss });
+function writeVerdictFiles({ runDir, record, overallVerdict, chairText, critic, deadWaves, degrades }) {
+  // v4.6 Plan 2 (spec D3): when the sink's records are available they are the
+  // single source of truth — seatLoss derives from them so it can never
+  // disagree with degrades[]. deadWaves remains the fallback for direct
+  // callers that predate the sink (their tests pass unedited).
+  const seatLoss = degrades
+    ? deriveSeatLoss({ runId: record.meta.runId, critic, degrades })
+    : summarizeSeatLoss({ runId: record.meta.runId, critic, deadWaves });
+  const verdict = buildVerdict(record, [], { seatLoss, degrades });
   verdict.overallVerdict = (overallVerdict === undefined) ? null : overallVerdict;
   writeVerdictAtomic(path.join(runDir, 'verdict.json'), verdict);
   const html = buildReport({ verdict }, { format: 'html' });

package/src/council/run-budget.js

@@ -38,15 +38,17 @@ const { sumWaveUsage } = require('../utils/pricing');
  * @param {number|null|undefined} opts.maxCost the `--max-cost` ceiling, if any
  * @param {string} [opts.runDir] run directory; when given, budget refusals are
  *   checkpointed into run.json so the record outlives the stderr notice
- * @param {{value: boolean}} [opts.degraded] the driver's degrade flag; a budget
- *   refusal sets it so the run can never exit 0 with a silently shrunken bench
+ * @param {{note: Function}} opts.degrade the council degrade sink; a budget
+ *   refusal announces through it so the run can never exit 0 with a silently
+ *   shrunken bench. Required, not optional — noteBudgetRefusal dereferences it
+ *   unconditionally.
  * @param {(s:string)=>void} [opts.write] stderr writer seam (defaults to process.stderr)
  * @returns {{spendState:Function, spent:Function, overBudget:Function,
  *   remainingBudget:Function, noticeUnknownSpend:Function, usageBlock:Function,
  *   addWave:Function, reserveBudget:Function, releaseBudget:Function,
  *   noteBudgetRefusal:Function, budgetRefusals:Function, inexactUnderCeiling:Function}}
  */
-function createBudget({ allLegs, maxCost, runDir, degraded, write }) {
+function createBudget({ allLegs, maxCost, runDir, degrade, write }) {
   const legs = allLegs || [];
   const emit = write || ((s) => process.stderr.write(s));
   const hasCeiling = maxCost !== null && maxCost !== undefined;
@@ -146,11 +148,15 @@ function createBudget({ allLegs, maxCost, runDir, degraded, write }) {
     const rec = { waveId: (info && info.waveId) || null, models: (info && info.models) || [],
       reason: 'max-cost', at: new Date().toISOString() };
     refusals.push(rec);
-    if (degraded) { degraded.value = true; }
-    emit(`Notice: the $${maxCost} --max-cost ceiling refused wave ${rec.waveId} `
-      + `(${rec.models.join(', ') || 'no models'}) — those seats DID NOT LAUNCH and are missing from `
-      + 'this council. The run continues with the bench that did launch and will exit degraded (2). '
-      + 'Raise --max-cost, or pass --no-cost-gate, to seat them.\n');
+    const message = info && info.message;
+    degrade.note({
+      channel: 'budget-refusal',
+      what: `wave ${rec.waveId} (${rec.models.join(', ') || 'no models'}) — those seats DID NOT `
+        + 'LAUNCH and are missing from this council',
+      why: `the $${maxCost} --max-cost ceiling refused it${message ? `: ${message}` : ''}`,
+      effect: 'The run continues with the bench that did launch and will exit degraded (2)',
+      remedy: 'Raise --max-cost, or pass --no-cost-gate, to seat them',
+    });
     if (runDir) {
       // Never let bookkeeping sink a run that is otherwise fine.
       try { require('./run-state').checkpoint(runDir, { budgetRefusals: refusals.slice() }); }

package/src/council/run-chair.js

@@ -46,13 +46,13 @@ function pickFallbackChair(statsRows, bench, failedChair) {
  * 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,
+ * @param {{packet: string, degrade: {note: Function}, 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 }) {
+async function runChair(ctx, { packet, degrade, statsFn, isSignalled }) {
   const { o, launchers, addWave, overBudget } = ctx;
   const now = () => new Date().toISOString();
   const bail = (code) => ({
@@ -81,11 +81,19 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
 
   let chairLeg = null;
   let actualChair = null;
+  let skippedForCost = false;
   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;
+    skippedForCost = true;
+    degrade.note({
+      channel: 'chair-skipped-cost-ceiling',
+      what: 'the chair did not run',
+      why: 'the --max-cost ceiling was reached before the chair could launch',
+      effect: 'the verdict is written with no chair synthesis and overallVerdict null; will exit degraded (2)',
+      remedy: 'raise --max-cost, or re-run the chair alone against the existing tally',
+    });
     runState.updateStage(o.runDir, 'chair', { status: 'skipped', completedAt: now() });
     emitStageTerminal(o.runDir, o.runId, 'chair', 'skipped', null, o.follow);
   } else {
@@ -146,7 +154,16 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
   // 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
+  if (!skippedForCost && (!chairLeg || !overallVerdict)) {
+    degrade.note({
+      channel: 'chair-failed',
+      what: 'the council has no chair synthesis',
+      why: chairLeg
+        ? 'the chair ran but its output carried no parseable VERDICT: line'
+        : 'no chair leg completed, including after the fallback chain',
+      effect: 'the verdict is written with overallVerdict null; will exit degraded (2)',
+    });
+  }
 
   return {
     aborted: null, chairLeg, actualChair, chairText, chairConformance, overallVerdict,

package/src/council/run-debate-stage.js

@@ -0,0 +1,115 @@
+// src/council/run-debate-stage.js
+'use strict';
+
+/**
+ * @module council/run-debate-stage
+ * Debate orchestration, extracted from run.js (v4.6 Plan 1 Task 1) so that file
+ * could come off the 300-line size-gate cliff. Logic moved verbatim; the only
+ * change is the explicit parameter object replacing closure access — PLUS one
+ * necessary deviation the plan's block-boundary audit missed: the original
+ * line here was `return finalize(dbg.aborted);` (spec §5.7, a signal arriving
+ * mid-debate). `finalize` is a run.js-local closure bound to session/server
+ * teardown state (uninstall, the shared OpenCode server) that cannot be
+ * reconstructed in a separate module without duplicating that single-close-site
+ * guarantee. Mirroring the SAME convention run.js already uses for Stage 1/2
+ * (`runStage1`/`runStage2` return an `aborted` field; run.js itself decides to
+ * call `finalize`), this module returns `{ ...the five bindings, aborted:
+ * dbg.aborted }` on that one path instead, and run.js's call site now carries
+ * a `if (debateAborted) { return finalize(debateAborted); }` guard, exactly
+ * paralleling its existing `if (signalled || s1.aborted) { ... }` /
+ * `if (signalled || s2.aborted) { ... }` lines. Verified against
+ * tests/council/run-debate.test.js's "abort mid-debate (defense wave
+ * signalled) → finalize aborted, NO tally-final, NO ledger" end-to-end case,
+ * which exercises exactly this path through runCouncil and continues to pass
+ * unedited.
+ */
+const fs = require('fs');
+const path = require('path');
+const runState = require('./run-state');
+const runDebateMod = require('./run-debate');
+const { tally } = require('./tally');
+const { emitStageStarted, emitStageTerminal } = require('../observe/events');
+
+const now = () => new Date().toISOString();
+
+async function runDebateStage(ctx, { provisional, provisionalInput, overBudget }) {
+  const { o } = ctx;
+  let debatedInput = provisionalInput, debatedRecord = provisional;
+  let debateOutcomes = null, debateFindings = null;
+  let debateSummary = o.debate ? { enabled: true, outcome: 'nothing-to-debate',
+    contested: 0, disputed: 0, defended: 0, amended: 0, withdrawn: 0, noResponse: 0,
+    revoteJudges: 0, revoteApplied: 0, verdictChanges: 0 } : null;
+  if (o.debate) {
+    // spec §5.1: the provisional tally is ALSO an audit artifact, not just a stage
+    // checkpoint — no ledger append, written before any debate leg launches.
+    fs.writeFileSync(path.join(o.runDir, 'tally-provisional.json'), JSON.stringify(provisional, null, 2), { mode: 0o600 });
+    runState.updateStage(o.runDir, 'tally-provisional', { status: 'complete', startedAt: now(), completedAt: now() });
+    emitStageStarted(o.runDir, o.runId, 'tally-provisional', null, o.follow);
+    emitStageTerminal(o.runDir, o.runId, 'tally-provisional', 'complete', null, o.follow);
+    const worthDebating = !runDebateMod.nothingToDebate(provisional);
+    if (worthDebating && !overBudget()) {
+      runState.updateStage(o.runDir, 'debate-defense', { status: 'running', startedAt: now(), project: ctx.scratchDir });
+      emitStageStarted(o.runDir, o.runId, 'debate-defense', null, o.follow);
+      const dbg = await runDebateMod.runDebate(ctx, { provisionalRecord: provisional, tallyInput: provisionalInput });
+      // A signal mid-debate aborts finalization: no tally-final, no ledger (spec §5.7). Close
+      // the summary FIRST — the writer contract requires a valid `outcome` whenever the key exists.
+      if (dbg.aborted) {
+        runState.checkpoint(o.runDir, { debate: { ...debateSummary, outcome: 'ran',
+          contested: dbg.contested, disputed: dbg.disputed } });
+        // See module docblock: `finalize` lives in run.js, not here. Return the
+        // signal (mirroring runStage1/runStage2's `aborted` field) instead of
+        // calling it directly — run.js's call site finalizes on our behalf.
+        return { debatedInput, debatedRecord, debateOutcomes, debateFindings, debateSummary, aborted: dbg.aborted };
+      }
+      runState.updateStage(o.runDir, 'debate-defense', { status: 'complete', completedAt: now() });
+      emitStageTerminal(o.runDir, o.runId, 'debate-defense', 'complete', null, o.follow);
+      // run-debate owns debate-revote's running/waveId/waveIds checkpoint — only it
+      // knows whether the wave launched. Never advertise a `-rv` id here: a skipped
+      // re-vote would leave the abort cascade chasing the v4.0 lens `-s1` phantom.
+      // Mirror run-chair.js's 'skipped' convention (no startedAt) when nothing was
+      // defended/amended or the cost ceiling skipped it — 'complete' would report
+      // work that never happened.
+      runState.updateStage(o.runDir, 'debate-revote', dbg.revoteLaunched
+        ? { status: 'complete', completedAt: now() } : { status: 'skipped', completedAt: now() });
+      // debate-revote-TERMINAL only — run-debate.js owns the START (spec §4.2 /
+      // v4.3 Task 7 B3 note): only it knows the `-rv` waveId when launched.
+      emitStageTerminal(o.runDir, o.runId, 'debate-revote',
+        dbg.revoteLaunched ? 'complete' : 'skipped', dbg.revoteLaunched ? `${o.runId}-rv` : null, o.follow);
+      ({ debatedInput, debateFindings, debateSummary } = dbg);
+      debatedRecord = tally(debatedInput);
+      // Defensive truthiness guard: `[]` is truthy in JS, so an empty outcomes
+      // list must be normalized to null here — otherwise the packet-assembly
+      // ternary below still calls buildDebateAddendum({outcomes: []}), which
+      // emits a bare "--- Debate round outcomes ---" heading with nothing
+      // under it (same defect class ee447b6 fixed on the report renderer).
+      debateOutcomes = (dbg.addendumOutcomes && dbg.addendumOutcomes.length > 0)
+        ? dbg.addendumOutcomes : null;
+      // Dead/unstructured defense, partial/fully-dead re-vote or a cost-ceiling re-vote skip
+      // each degrade the run → exit 2 (spec §5.7), same channel as a dead Stage-1 leg.
+      if (dbg.degraded) {
+        ctx.degrade.note({
+          channel: 'debate-degraded',
+          what: 'the debate round did not complete cleanly',
+          why: 'one or more defense or re-vote legs died or returned unstructured output',
+          effect: 'affected findings keep their provisional tier; will exit degraded (2)',
+        });
+      }
+    } else if (worthDebating) {
+      // Budget gone before the defense wave launched, but there WAS something to debate — the
+      // other cost-ceiling branch (spec §5.7). Over budget AND nothing to debate stays the latter.
+      debateSummary.outcome = 'skipped-cost-ceiling';
+      ctx.degrade.note({
+        channel: 'debate-degraded',
+        what: 'the debate round did not run',
+        why: 'the --max-cost ceiling was reached before the defense wave could launch',
+        effect: 'contested findings were not debated and keep their provisional tier; will exit degraded (2)',
+        remedy: 'raise --max-cost to let the debate round run',
+      });
+    }
+    runState.checkpoint(o.runDir, { debate: debateSummary });
+  }
+
+  return { debatedInput, debatedRecord, debateOutcomes, debateFindings, debateSummary };
+}
+
+module.exports = { runDebateStage };

package/src/council/run-degrade.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * @module council/run-degrade
+ * THE CHOKE POINT. The only place in the council runtime permitted to set
+ * `degraded.value`. Announcing is a side effect of degrading, which is what
+ * makes "every degrade is announced" true by construction rather than by
+ * discipline — see tests/council/degrade-invariant.test.js, which fails if
+ * anyone writes `degraded.value = true` anywhere else.
+ */
+const { makeDegrade, formatDegrade } = require('../utils/degrade');
+
+function createDegradeSink({ runDir, degraded, write }) {
+  const emit = write || ((s) => process.stderr.write(s));
+  const records = [];
+
+  // One level, no re-entry. Without this rule a disk-full condition becomes an
+  // unbounded loop of degrades about failing to record degrades (spec §7).
+  const safeEmit = (s) => { try { emit(s); } catch { /* EPIPE etc — never mask the run */ } };
+
+  function note(input) {
+    let record;
+    try {
+      record = makeDegrade(input);
+    } catch (err) {
+      record = makeDegrade({
+        channel: 'internal',
+        what: `a degrade on channel '${input && input.channel}' could not be recorded`,
+        why: (err && err.message) || 'unknown error',
+        effect: 'the run still degrades; the original detail is lost',
+      });
+    }
+    records.push(record);
+    safeEmit(formatDegrade(record));
+    try {
+      require('./run-state').checkpoint(runDir, { degrades: records.slice() });
+    } catch { /* precedent: run-budget.js:156 — a degrade that cannot be persisted is still announced */ }
+    if (record.kind === 'degrade' && degraded) { degraded.value = true; }
+  }
+
+  return { note, all: () => records.slice() };
+}
+
+module.exports = { createDegradeSink };

package/src/council/run-finalize.js

@@ -59,12 +59,27 @@ function statusForExit(code) {
  * a run that published a total it knows is a floor has not earned that.
  *
  * @param {{signalled: number|null, exitCode: number, degraded?: {value: boolean},
- *   inexactUnderCeiling?: () => boolean}} args
+ *   degrade?: {note: Function}, inexactUnderCeiling?: () => boolean}} args
  * @returns {number}
  */
-function resolveTerminalExit({ signalled, exitCode, degraded, inexactUnderCeiling }) {
+function resolveTerminalExit({ signalled, exitCode, degraded, degrade, inexactUnderCeiling }) {
   if (signalled) { return signalled; }
-  if (degraded && inexactUnderCeiling && inexactUnderCeiling()) { degraded.value = true; }
+  // Final-review F1: the inexactness itself is still announced on EVERY path by
+  // noticeUnknownSpend() at writeRunTerminal, below — that is unconditional and
+  // untouched. What is gated here is only the CLAIM this record's effect text
+  // makes, "the run exits degraded (2)", which is true on exactly the codes that
+  // end up 2 (a clean 0 about to flip, or an already-degraded 2). On exit 1
+  // (quorum/internal error) or an abort/signal code the run does NOT exit 2, so
+  // noting that sentence there would be false.
+  if (degrade && inexactUnderCeiling && inexactUnderCeiling() && (exitCode === 0 || exitCode === 2)) {
+    // Late channel (spec §6 rule 1): fires AFTER verdict assembly, so this record is run.json-only by design — it can never appear on verdict.degrades[].
+    degrade.note({
+      channel: 'inexact-under-ceiling',
+      what: 'the run total is a lower bound, not an exact figure',
+      why: 'one or more legs reported no usage, so their cost is unknown',
+      effect: '--max-cost bounded only KNOWN spend; the run exits degraded (2)',
+    });
+  }
   return (exitCode === 0 && degraded && degraded.value) ? 2 : exitCode;
 }
 

package/src/council/run-server.js

@@ -145,7 +145,12 @@ async function resolveRunServerModels(o, deps = {}) {
  * cannot clobber `budgetRefusals[]` or anything else already on the document.
  * Verified, not assumed — `tests/council/run-state.test.js` pins it.
  *
- * @param {object} o the council run's resolved options
+ * @param {object} o the council run's resolved options (carries `degrade`, the
+ *   council sink, for the `sharedServerUnavailable` announcement below). `o.degrade`
+ *   is expected to be set on that path — run.js threads it — but the call below is
+ *   still guarded rather than assumed: a throw from this module would escape
+ *   runCouncil past its "never rejects for run errors" contract (see this file's
+ *   own docblock), which is worse than a missed note.
  * @param {object} patch a single top-level run.json key
  * @param {string} what the field name, for the failure log
  */
@@ -155,6 +160,21 @@ function recordServerFate(o, patch, what) {
   catch (writeErr) {
     logger.warn(`Could not record ${what} on run.json`, { runId: o.runId, error: writeErr.message });
   }
+  if (what === 'sharedServerUnavailable') {
+    const unavailable = patch.sharedServerUnavailable;
+    const reason = typeof unavailable === 'string' ? unavailable
+      : (unavailable && unavailable.error) || 'unknown error';
+    if (o.degrade) {
+      o.degrade.note({
+        channel: 'shared-server-unavailable',
+        kind: 'degrade',
+        what: 'could not start a shared OpenCode server',
+        why: reason,
+        effect: 'each wave will start its own, which is the configuration that races; the run '
+          + 'will exit degraded (2)',
+      });
+    }
+  }
 }
 
 /**
@@ -222,14 +242,11 @@ async function acquireRunServer(o, deps = {}) {
     // DURABLE: it lands on the run's own record, next to `budgetRefusals[]`,
     // for the same reason — a silent partial is the failure mode this whole
     // release exists to remove.
-    const degrade = { error: err.message, at: new Date().toISOString() };
-    recordServerFate(o, { sharedServerUnavailable: degrade }, 'sharedServerUnavailable');
+    const serverFailure = { error: err.message, at: new Date().toISOString() };
+    recordServerFate(o, { sharedServerUnavailable: serverFailure }, 'sharedServerUnavailable');
     logger.warn('Shared OpenCode server unavailable — falling back to one server per wave', {
       runId: o.runId, error: err.message,
     });
-    process.stderr.write(
-      `Notice: could not start a shared OpenCode server (${err.message}); each wave will start `
-      + 'its own, which is the configuration that races. Expect degraded results.\n');
     return null;
   }
 }
@@ -245,4 +262,4 @@ async function releaseRunServer(shared) {
   try { await shared.server.close(); } catch { /* best-effort: the run is over */ }
 }
 
-module.exports = { acquireRunServer, releaseRunServer, resolveRunServerModels };
+module.exports = { acquireRunServer, releaseRunServer, resolveRunServerModels, recordServerFate };

package/src/council/run-stage2.js

@@ -106,11 +106,19 @@ async function runStage2(ctx, { reviews, labels, globalFindings, extraLabeled =
     }
     if (!parsed.ok) {
       judgeResults.push({ judge, ok: false, order: null, adjudications: null,
-        conformance: leg.status === 'complete' ? 'unstructured' : 'clean' });
+        conformance: leg.status === 'complete' ? 'unstructured' : 'clean',
+        // #83 (v4.6 Plan 2): the judge's ORIGINAL Stage-2 wave leg, mirroring
+        // Stage-1's convention (reviews carry the original wave leg even when a
+        // repair ran — repairs are separately recorded via appendStageWave).
+        // A repair solo's leg is NOT preferred here: attributing it instead
+        // would leave every non-repaired (the common case) judge with a false
+        // `status: 'error'` row — worse than the missing row #83 complained about.
+        leg: leg || null });
       continue;
     }
     const { order } = rankingToOrder(parsed.ranking, labels.labelMap);
-    judgeResults.push({ judge, ok: true, order, adjudications: parsed.adjudications, conformance });
+    judgeResults.push({ judge, ok: true, order, adjudications: parsed.adjudications, conformance,
+      leg: leg || null });
   }
   return { aborted: null, judgeResults };
 }

package/src/council/run-stages.js

@@ -107,25 +107,6 @@ async function launchStage1(ctx) {
   return { aborted, legs, deadWaves };
 }
 
-/**
- * Announce Stage-1 sub-waves that never produced a leg.
- *
- * POLICY (the standing "never fail closed on availability" ruling, applied the
- * same way run-budget.js applies it to cost): the run CONTINUES with the bench
- * that did launch. What it must never do is lose the seats SILENTLY — so every
- * dead wave is announced on stderr, kept on run.json's stage entry (run.js) and
- * degrades the run's exit code to 2.
- * @param {Array<{waveId: string, models: string[], reason: string}>} deadWaves
- * @param {(s: string) => void} [write] stderr seam
- */
-function reportDeadStage1Waves(deadWaves, write = (s) => process.stderr.write(s)) {
-  for (const d of deadWaves) {
-    write(`Notice: Stage-1 wave ${d.waveId} (${d.models.join(', ') || 'no models'}) produced NO legs `
-      + `— ${d.reason}. Those seats are NOT in this council. The run continues with the bench that `
-      + 'did launch and will exit degraded (2).\n');
-  }
-}
-
 /** Role of a seat by its input alias. */
 function roleFor(o, alias) {
   if (o.lenses) {
@@ -151,12 +132,33 @@ async function runStage1(ctx) {
   const { o } = ctx;
   const { aborted, legs, deadWaves } = await launchStage1(ctx);
   if (aborted) { return { aborted, reviews: [], deadLegs: [], deadWaves: [], degraded: false }; }
-  reportDeadStage1Waves(deadWaves);
+
+  for (const d of deadWaves) {
+    ctx.degrade.note({
+      channel: 'dead-wave',
+      what: `Stage-1 wave ${d.waveId} (${d.models.join(', ') || 'no models'}) produced NO legs`,
+      why: d.reason,
+      effect: 'Those seats are NOT in this council. The run continues with the bench that did '
+        + 'launch and will exit degraded (2)',
+      data: { waveId: d.waveId, models: d.models, reason: d.reason },
+    });
+  }
 
   const materialized = materializeReviews(o.runDir, legs);
   const alive = new Set(materialized.map(m => m.leg));
   const deadLegs = legs.filter(l => !alive.has(l));
 
+  for (const leg of deadLegs) {
+    ctx.degrade.note({
+      channel: 'dead-leg',
+      what: `seat ${leg.modelInput || leg.model} did not review`,
+      why: `the leg ended '${leg.status}'${leg.error ? `: ${leg.error}` : ''} with no usable output`,
+      effect: `${materialized.length} of ${legs.length} seats reviewed; `
+        + 'the run continues with the bench that did and will exit degraded (2)',
+      data: { seat: leg.modelInput || leg.model, status: leg.status, reason: leg.error || null },
+    });
+  }
+
   const reviews = [];
   let repairSeq = 0;
   for (const m of materialized) {
@@ -263,4 +265,4 @@ async function runStage1(ctx) {
 // module that produces the exit codes — so the child no longer imports from its
 // parent (v4.4.1 review F5). isAbortExit is still re-exported for run-chair.js
 // and run-debate.js, which have always taken it from here.
-module.exports = { runStage1, runStage2, isAbortExit, slug, roleFor, reportDeadStage1Waves };
+module.exports = { runStage1, runStage2, isAbortExit, slug, roleFor };