amicus 4.2.1 → 4.4.0

package/src/council/run-budget.js

@@ -0,0 +1,224 @@
+// src/council/run-budget.js
+'use strict';
+
+/**
+ * @module council/run-budget
+ * The council driver's budget position (v4.4). Split out of src/council/run.js
+ * to stay under the 300-line size gate; it is pure except for the one stderr
+ * notice, and every member is injectable/observable so run.js's behaviour is
+ * unchanged by the move.
+ *
+ * WHY THIS EXISTS AS ITS OWN CONCEPT. Before v4.4 the driver had a single
+ * `spent()` that mapped a null cost amount to `0` and discarded
+ * `sumWaveUsage`'s `unpricedLegs`/`source` entirely. Unknown spend was
+ * therefore invisible to `--max-cost` AND to every reader of run.json:
+ * `council-wsgate02` really spent $0.9859 against a $0.75 ceiling — a 131%
+ * overrun — while `spent()` believed $0.3720 and never emitted COST_EXCEEDED
+ * (.superpowers/sdd/v44/zero-usage-diagnosis.md §0/§9).
+ *
+ * OWNER'S RULING (Christian, v4.4): fail LOUD, not fail CLOSED —
+ * "I don't want hitting a ceiling to stop us from solving real problems."
+ * So an unknown-cost leg must NOT halt a run and must NOT by itself trip the
+ * ceiling; the ceiling trips on KNOWN spend only. The uncertainty is instead
+ * made impossible to miss. The failure mode being eliminated is SILENT
+ * UNDER-REPORTING, not "continuing in the presence of uncertainty" — and
+ * nothing here converts uncertainty into a fabricated number in either
+ * direction (no rounding unknown up to a guess, no rounding it down to zero).
+ */
+
+const { sumWaveUsage } = require('../utils/pricing');
+
+/**
+ * @param {object} opts
+ * @param {Array<object>} [opts.allLegs] live array the driver pushes every wave's legs into
+ * @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 {(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}}
+ */
+function createBudget({ allLegs, maxCost, runDir, degraded, write }) {
+  const legs = allLegs || [];
+  const emit = write || ((s) => process.stderr.write(s));
+  const hasCeiling = maxCost !== null && maxCost !== undefined;
+
+  /**
+   * The run's position, split into what we KNOW was spent and how many legs we
+   * cannot price at all. `known` is the sum of resolved amounts only — a leg
+   * whose cost is `unknown` contributes nothing, because inventing a number for
+   * it would be a fabrication. `unknownLegs` is what makes that omission
+   * visible instead of silent: it is the count the run summary, the envelope,
+   * `amicus spend` and the GUI all read to say "this total is a floor".
+   */
+  const spendState = () => {
+    const c = sumWaveUsage(legs).cost;
+    return {
+      known: typeof c.amount === 'number' ? c.amount : 0,
+      unknownLegs: c.unpricedLegs || 0,
+      subtreeUnknownLegs: c.subtreeUnknownLegs || 0,
+      cost: c,
+    };
+  };
+
+  const spent = () => spendState().known;
+
+  /** Trips on KNOWN spend only — see the ruling in the module docblock. */
+  const overBudget = () => hasCeiling && spent() >= maxCost;
+
+  // ---- Concurrency-safe reservations (v4.4 cost-council finding 1) ----------
+  /**
+   * THE DEFECT. `launchStage1()` builds the seat wave and the critic wave
+   * concurrently under one `Promise.all`, and each launcher called
+   * `remainingBudget()` BEFORE either wave's legs had been appended to `legs`.
+   * Both therefore observed the full, unreduced allowance, and both could pass
+   * a soft gate that — taken together — exceeded `--max-cost`. Only run.js's
+   * post-Stage-1 `overBudget()` noticed, by which point the money was committed.
+   * A read is not a claim.
+   *
+   * THE FIX. `reserveBudget` is a SYNCHRONOUS read-and-claim. Synchronicity is
+   * the entire guarantee: the JS event loop cannot interleave two callers inside
+   * a synchronous function, so a second concurrent wave necessarily observes the
+   * first wave's claim. No mutex, no async barrier, nothing to deadlock.
+   *
+   * WHY NOT SPLIT THE QUOTA. Handing each concurrent wave a fixed share is also
+   * safe but is strictly MORE refusing than the ceiling requires: three cheap
+   * seats plus one expensive critic can fit a ceiling that no proportional split
+   * admits. The owner's standing ruling is fail LOUD, not fail CLOSED — so the
+   * gate must refuse only what genuinely does not fit. First claim wins; a wave
+   * refused here does not stop the run (see noteBudgetRefusal).
+   */
+  const reservations = new Map(); // waveId -> pre-flight estimate ($)
+  const reserved = () => { let t = 0; for (const v of reservations.values()) { t += v; } return t; };
+
+  /** Ceiling minus known spend MINUS outstanding reservations, floored at 0;
+   *  null when no ceiling is set. Threaded into each wave's fanout pre-flight
+   *  estimate as its starting allowance (run-launch.js). */
+  const remainingBudget = () => (hasCeiling ? Math.max(maxCost - spent() - reserved(), 0) : null);
+
+  /**
+   * Atomically claim `estimate` against the allowance no sibling wave has taken.
+   * @returns {boolean} false ONLY when the estimate genuinely does not fit.
+   *   A $0 / unpriced / non-numeric estimate always fits: unknown cost must
+   *   never halt a run (the same ruling that keeps it out of `overBudget`).
+   */
+  const reserveBudget = (waveId, estimate) => {
+    if (!hasCeiling) { return true; }
+    const est = (typeof estimate === 'number' && Number.isFinite(estimate) && estimate > 0) ? estimate : 0;
+    if (est > remainingBudget()) { return false; }
+    reservations.set(waveId, (reservations.get(waveId) || 0) + est);
+    return true;
+  };
+
+  /** Drop a wave's outstanding claim (its real spend now speaks for it). */
+  const releaseBudget = (waveId) => { reservations.delete(waveId); };
+
+  /**
+   * Record a finished wave: its ESTIMATE stops counting and its MEASURED legs
+   * start counting, in one synchronous step so no concurrent launcher can ever
+   * observe a moment where the wave counts twice or not at all.
+   */
+  const addWave = (wave) => {
+    if (!wave) { return; }
+    if (wave.waveId) { releaseBudget(wave.waveId); }
+    if (Array.isArray(wave.legs)) { legs.push(...wave.legs); }
+  };
+
+  /**
+   * A wave the ceiling refused. POLICY (the owner's ruling applied to
+   * concurrency): the run CONTINUES with a partial bench — it never rolls back
+   * waves already launched (that would destroy paid work) and never aborts
+   * (that is fail-closed). What it must never do is lose the seat SILENTLY, so
+   * every refusal is announced on stderr, kept on run.json, and degrades the
+   * run's exit code. Stage 1's existing quorum gate still refuses to call a
+   * bench of fewer than two reviews a council.
+   */
+  const refusals = [];
+  const noteBudgetRefusal = (info) => {
+    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');
+    if (runDir) {
+      // Never let bookkeeping sink a run that is otherwise fine.
+      try { require('./run-state').checkpoint(runDir, { budgetRefusals: refusals.slice() }); }
+      catch (e) { emit(`Notice: could not record the budget refusal in run.json: ${e.message}\n`); }
+    }
+  };
+  const budgetRefusals = () => refusals.slice();
+
+  let noticed = false;
+  /**
+   * One prominent, un-missable notice per run when the total is incomplete — for
+   * EITHER reason, which are different statements and are worded differently:
+   *   - `unknownLegs`        — the leg reported no usage at all.
+   *   - `subtreeUnknownLegs` — the leg's own cost is known, but it spawned a
+   *     subagent whose CHILD session is billed separately and whose spend the
+   *     walk could NOT account for. This is the one that made
+   *     `council-wsgate01` report `costExact: true` while $0.0215 short — 100%
+   *     of that gap was one `explore` child session.
+   *
+   * v4.4.1 CA-1: child sessions are now enumerated and their measured spend IS
+   * attributed (`cost.subtreeCost`), so this second bucket has narrowed to the
+   * subtrees the walk genuinely could not price. It is deliberately still a
+   * separate statement from an unpriced leg: "we could not see this leg at all"
+   * and "we saw this leg but not what it spawned" are different facts.
+   */
+  const noticeUnknownSpend = () => {
+    const s = spendState();
+    if ((s.unknownLegs === 0 && s.subtreeUnknownLegs === 0) || noticed) { return; }
+    noticed = true;
+    const ceiling = hasCeiling ? ` or the $${maxCost} --max-cost ceiling` : '';
+    const parts = [];
+    if (s.unknownLegs > 0) {
+      parts.push(`${s.unknownLegs} council leg(s) reported NO usage — their cost is UNKNOWN`);
+    }
+    if (s.subtreeUnknownLegs > 0) {
+      parts.push(`${s.subtreeUnknownLegs} council leg(s) spawned a subagent whose CHILD session spend `
+        + 'is billed separately and could NOT be determined');
+    }
+    emit(`Notice: ${parts.join('; and ')} and is NOT included in the $${s.known.toFixed(4)} `
+      + `total${ceiling}. Real spend is HIGHER than reported — this total is at least, not exactly, `
+      + 'what was spent. See run.json usage (unknownLegs / subtreeUnknownLegs), or '
+      + '`amicus spend --json` (sourceMix.unknown).\n');
+  };
+
+  /**
+   * The run summary's `usage` block. `costExact`/`unknownLegs` sit at the TOP of
+   * it on purpose: `cost.unpricedLegs` always carried the count, but every reader
+   * of `usage` looked one level up and saw only a number that read as
+   * authoritative — the silent under-report the diagnosis measured at 62.3% on
+   * council-wsgate02. Consumers: src/workspace/run-detail.js costPanel (the GUI
+   * gauge + total), src/cli-handlers-council-run.js renderRunHuman, and the
+   * `--json` manifest, which emits run.json verbatim.
+   */
+  const usageBlock = () => {
+    const s = spendState();
+    return {
+      cost: s.cost,
+      unknownLegs: s.unknownLegs,
+      subtreeUnknownLegs: s.subtreeUnknownLegs,
+      // v4.4 Task 2: `costExact` used to be `unknownLegs === 0`, which asks "did
+      // every leg report tokens" — a statement about observation coverage of each
+      // leg's OWN session, NOT about whether the total is complete. That is how
+      // `council-wsgate01` asserted exactness while $0.0215 short: all 7 legs were
+      // `source: 'reported'`, and 100% of the gap was one unattributed `explore`
+      // child session. costExact must mean "this is the whole bill", so it now
+      // requires BOTH: every leg observed, AND no leg with an unattributed subtree.
+      costExact: s.unknownLegs === 0 && s.subtreeUnknownLegs === 0,
+    };
+  };
+
+  return { spendState, spent, overBudget, remainingBudget, noticeUnknownSpend, usageBlock,
+    addWave, reserveBudget, releaseBudget, noteBudgetRefusal, budgetRefusals };
+}
+
+module.exports = { createBudget };

package/src/council/run-chair.js

@@ -19,6 +19,7 @@ const stage2 = require('./briefings-stage2');
 const { parseChairVerdict } = require('./parse-stage2');
 const runState = require('./run-state');
 const { isAbortExit } = require('./run-stages');
+const { emitStageStarted, emitStageTerminal } = require('../observe/events');
 
 /**
  * Chair fallback promotion (spec §4): the highest peers-only street-cred
@@ -68,6 +69,9 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
       // below are the launches a re-armed price gate would refuse LAST, after
       // the whole bench has already been paid for.
       noCostGate: o.noCostGate,
+      // v4.3 Task 3 (spec §7.2 named defect): without this, chair spend is
+      // ledgered with councilRunId:null and is unattributable.
+      councilRunId: o.runId, councilName: o.councilName,
     });
     addWave(solo.wave);
     const ok = solo.leg && solo.leg.status === 'complete'
@@ -83,8 +87,10 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
     // Never abort in-flight legs for cost — this only stops NEW launches.
     degraded.value = true;
     runState.updateStage(o.runDir, 'chair', { status: 'skipped', completedAt: now() });
+    emitStageTerminal(o.runDir, o.runId, 'chair', 'skipped', null, o.follow);
   } else {
     runState.updateStage(o.runDir, 'chair', { status: 'running', startedAt: now(), project: o.runDir });
+    emitStageStarted(o.runDir, o.runId, 'chair', null, o.follow);
     // 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`);
@@ -105,8 +111,9 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
       }
     }
     chairLeg = attempt.leg;
-    runState.updateStage(o.runDir, 'chair',
-      { status: chairLeg ? 'complete' : 'error', completedAt: now() });
+    const chairStatus = chairLeg ? 'complete' : 'error';
+    runState.updateStage(o.runDir, 'chair', { status: chairStatus, completedAt: now() });
+    emitStageTerminal(o.runDir, o.runId, 'chair', chairStatus, null, o.follow);
     // 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
@@ -126,6 +133,7 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
       project: o.runDir, waveId: `${o.runId}-ch4`,
       timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
       noCostGate: o.noCostGate,
+      councilRunId: o.runId, councilName: o.councilName,
     });
     addWave(repair.wave);
     if (isAbortExit(repair.exitCode) || isSignalled()) { return bail(repair.exitCode || isSignalled()); }

package/src/council/run-debate.js

@@ -18,6 +18,7 @@ const { materializeDebate } = require('./run-launch');
 const { tally } = require('./tally');
 const { isAbortExit } = require('./run-stages');
 const runState = require('./run-state');
+const { emitStageStarted } = require('../observe/events');
 
 /** Spec §5.7 fallback: a dead/unparseable defense means every bundled id's original stands. */
 function allNoResponse(ids) {
@@ -65,7 +66,9 @@ function debateTargets(provisionalRecord, tallyInput) {
 /** 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 };
+    noValidateModel: ctx.o.noValidateModel, noCostGate: ctx.o.noCostGate,
+    // v4.3 Task 3 (spec §7.2): attribution ids for every defense/re-vote leg.
+    councilRunId: ctx.o.runId, councilName: ctx.o.councilName };
 }
 
 async function runDefenseSolo(ctx, raiser, findings, idx) {
@@ -121,6 +124,7 @@ async function runRevoteWave(ctx, judges, bundleFindings) {
   // 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 });
+  emitStageStarted(ctx.o.runDir, ctx.o.runId, 'debate-revote', waveId, ctx.o.follow);
   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);

package/src/council/run-launch.js

@@ -18,20 +18,56 @@ const fs = require('fs');
 const path = require('path');
 
 /**
- * @param {{fanoutFn?: Function}} [deps] test seam; default = real runFanout
+ * @param {{fanoutFn?: Function, remainingBudget?: () => number|null,
+ *   reserveBudget?: (waveId: string, estimate: number) => boolean,
+ *   onBudgetRefusal?: (info: {waveId, models, message}) => void}} [deps]
+ *   fanoutFn: test seam; default = real runFanout.
+ *   remainingBudget (v4.4): supplies the council's REMAINING `--max-cost`
+ *   allowance (ceiling − known spend − outstanding reservations) at launch time,
+ *   threaded into the fanout pre-flight estimate gate. Omitted (or returning
+ *   null) leaves `maxCost` off the transport call entirely, exactly as before.
+ *   reserveBudget (v4.4 cost-council finding 1): the ATOMIC claim. Reading the
+ *   remaining allowance is not enough when two waves launch concurrently — both
+ *   read the same unreduced number and both pass. The transport calls this once,
+ *   synchronously, with the estimate it just computed; see run-budget.js.
+ *   onBudgetRefusal: notified when the ceiling refuses a wave, so a seat that
+ *   never launched can never vanish silently.
  * @returns {{launchWave: Function, launchSolo: Function}}
  */
 function createLaunchers(deps = {}) {
   const fanoutFn = deps.fanoutFn || require('../sidecar/fanout').runFanout;
+  const remainingBudget = deps.remainingBudget || null;
+  const reserveBudget = deps.reserveBudget || null;
+  const onBudgetRefusal = deps.onBudgetRefusal || null;
 
   /**
    * @param {{models: string[], prompt: string, project: string, waveId: string,
-   *   timeout?: number, gateway?: string, noValidateModel?: boolean, agent?: string}} opts
+   *   timeout?: number, gateway?: string, noValidateModel?: boolean, agent?: string,
+   *   councilRunId?: string, councilName?: string, fallback?: object, catalog?: Array}} opts
+   *   councilRunId/councilName (v4.3 Task 3, spec §7.2) are additive attribution
+   *   ids forwarded verbatim into the runFanout call so it can stamp them onto
+   *   every leg. fallback/catalog (v4.3 Task 18, spec §6.2) are likewise
+   *   additive/opt-in — omitted by callers that must never substitute (the
+   *   chair, debate legs); run-stages.js's Stage-1/Stage-2 launches pass them.
    * @returns {Promise<{wave: object|null, exitCode: number}>}
    */
   async function launchWave(opts) {
     fs.mkdirSync(opts.project, { recursive: true });
-    const { wave, exitCode } = await fanoutFn({
+    // v4.4: arm fanout's SOFT total-$ ceiling with the council's remaining
+    // allowance. Previously omitted, so fanout fell back to `cfg.maxCost` (a key
+    // src/utils/config.js never defines) and the pre-flight estimate gate was
+    // inert for every council run — run.js's post-hoc check was the only ceiling,
+    // and it can only refuse after the money is gone. Left OFF when there is no
+    // provider or no ceiling, so the transport call is byte-identical for
+    // non-council callers and for `--max-cost`-less runs.
+    const remaining = remainingBudget ? remainingBudget() : null;
+    const { wave, exitCode, errorDoc } = await fanoutFn({
+      ...(typeof remaining === 'number' ? { maxCost: remaining } : {}),
+      // v4.4 cost-council finding 1: `maxCost` above is a READ taken before the
+      // transport resolved routing; a concurrently launching sibling can claim
+      // part of that allowance in the meantime. This is the CLAIM that settles
+      // it — synchronous by contract, so two callers can never interleave.
+      ...(reserveBudget ? { reserveBudget: (est) => reserveBudget(opts.waveId, est) } : {}),
       models: opts.models.join(','),
       prompt: opts.prompt,
       promptMeta: { source: 'council-engine', file: null, chars: opts.prompt.length },
@@ -43,6 +79,13 @@ function createLaunchers(deps = {}) {
       includeContext: false,
       gatewayMode: opts.gateway,
       noValidateModel: opts.noValidateModel,
+      councilRunId: opts.councilRunId,
+      councilName: opts.councilName,
+      // v4.3 Task 18 (spec §6.2): additive/opt-in. Callers that must never
+      // substitute (run-chair.js, run-debate.js) simply omit these — runLeg's
+      // fallback path only activates when `fallback.enabled` is true.
+      fallback: opts.fallback,
+      catalog: opts.catalog,
       // 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
@@ -60,17 +103,25 @@ function createLaunchers(deps = {}) {
       directory: opts.project,
       noMcp: true,
     });
-    return { wave, exitCode };
+    // A ceiling refusal returns `wave: null`, which the council driver's
+    // addWave() treats as a no-op — so before v4.4 the seats simply vanished
+    // from the bench with nothing on stdout, stderr or run.json to say so. A
+    // partial bench is an acceptable outcome; an UNANNOUNCED one is not.
+    if (onBudgetRefusal && errorDoc && errorDoc.code === 'BUDGET_EXCEEDED') {
+      onBudgetRefusal({ waveId: opts.waveId, models: opts.models.slice(), message: errorDoc.message });
+    }
+    return { wave, exitCode, errorDoc: errorDoc || null };
   }
 
   /**
    * One-model launch (critic/lens legs, repairs, the chair) as a 1-leg wave.
-   * @returns {Promise<{wave: object|null, exitCode: number, leg: object|null}>}
+   * @returns {Promise<{wave: object|null, exitCode: number, leg: object|null,
+   *   errorDoc: object|null}>}
    */
   async function launchSolo(opts) {
-    const { wave, exitCode } = await launchWave({ ...opts, models: [opts.model] });
+    const { wave, exitCode, errorDoc } = await launchWave({ ...opts, models: [opts.model] });
     const leg = (wave && Array.isArray(wave.legs) && wave.legs[0]) || null;
-    return { wave, exitCode, leg };
+    return { wave, exitCode, leg, errorDoc };
   }
 
   return { launchWave, launchSolo };

package/src/council/run-stages.js

@@ -41,6 +41,13 @@ async function launchStage1(ctx) {
   const common = {
     project: o.runDir, timeout: o.timeout, gateway: o.gateway,
     noValidateModel: o.noValidateModel, noCostGate: o.noCostGate,
+    // v4.3 Task 3 (spec §7.2): attribution ids, forwarded verbatim to runFanout
+    // via run-launch.js so every Stage-1 leg's ledger row carries them.
+    councilRunId: o.runId, councilName: o.councilName,
+    // v4.3 Task 18 (spec §6.2): fallback chains apply to STAGE legs only —
+    // the chair (run-chair.js) and debate legs (run-debate.js) never receive
+    // this, so they never substitute via chains.
+    fallback: o.fallback, catalog: o.catalog,
   };
   const launches = [];
   // Record every sub-wave BEFORE it launches: `amicus abort` cascades over
@@ -112,19 +119,35 @@ async function runStage1(ctx) {
     let conformance = 'clean';
     let res = validateFindings(m.text);
     let attempts = 0;
+    // ⚠️ LC-6: the text the repair prompt must carry. A repair solo is a FRESH
+    // session — it has no memory of the review turn — so shipping only
+    // res.errors asked the model to correct something it had never seen. Two
+    // paid models refused ("I don't have a previous review to correct") and one
+    // fabricated a finding, which reached tally.json and the chair's verdict.
+    // Tracked rather than pinned to m.text so `repairing` and `res.errors`
+    // always describe the SAME artifact: on attempt 2 the errors came from
+    // validating attempt 1's output, so attempt 1's output is what is being
+    // repaired. An empty/dead repair leg leaves it on the last real text
+    // (there is no newer artifact to name).
+    let repairing = m.text;
     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 }),
+        model: m.modelInput,
+        prompt: briefings.buildFindingsRepairPrompt({ errors: res.errors, review: repairing }),
         project: o.runDir, waveId, timeout: o.timeout,
         gateway: o.gateway, noValidateModel: o.noValidateModel, noCostGate: o.noCostGate,
+        councilRunId: o.runId, councilName: o.councilName,
+        fallback: o.fallback, catalog: o.catalog,
       });
       ctx.addWave(solo.wave);
       if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, reviews, deadLegs }; }
-      res = validateFindings((solo.leg && solo.leg.summary) || '');
+      const repaired = (solo.leg && solo.leg.summary) || '';
+      if (repaired.trim()) { repairing = repaired; }
+      res = validateFindings(repaired);
       if (res.ok) { conformance = 'repaired'; }
     }
     if (!res.ok) { conformance = 'unstructured'; }
@@ -170,6 +193,8 @@ async function runStage2(ctx, { reviews, labels, globalFindings, extraLabeled =
     models: judges, prompt: bundle, project: ctx.scratchDir, waveId: `${o.runId}-s2`,
     timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
     noCostGate: o.noCostGate,
+    councilRunId: o.runId, councilName: o.councilName,
+    fallback: o.fallback, catalog: o.catalog,
   });
   ctx.addWave(wave);
   if (isAbortExit(exitCode)) { return { aborted: exitCode, judgeResults: [] }; }
@@ -195,6 +220,8 @@ async function runStage2(ctx, { reviews, labels, globalFindings, extraLabeled =
         model: judge, prompt: stage2.buildJudgeRepairPrompt({ errors: parsed.errors }),
         project: ctx.scratchDir, waveId, timeout: o.timeout,
         gateway: o.gateway, noValidateModel: o.noValidateModel, noCostGate: o.noCostGate,
+        councilRunId: o.runId, councilName: o.councilName,
+        fallback: o.fallback, catalog: o.catalog,
       });
       ctx.addWave(solo.wave);
       if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, judgeResults }; }
@@ -212,4 +239,4 @@ async function runStage2(ctx, { reviews, labels, globalFindings, extraLabeled =
   return { aborted: null, judgeResults };
 }
 
-module.exports = { runStage1, runStage2, isAbortExit, slug };
+module.exports = { runStage1, runStage2, isAbortExit, slug, roleFor };

package/src/council/run.js

@@ -31,33 +31,41 @@ const runDebateMod = require('./run-debate');
 const { buildDebateAddendum } = require('./briefings-debate');
 const { decorateRecord } = require('./debate');
 const asm = require('./run-assemble');
-const { sumWaveUsage } = require('../utils/pricing');
+const { createBudget } = require('./run-budget');
+const { emitRunStarted, emitRunTerminal, emitStageStarted, emitStageTerminal } = require('../observe/events');
+const { fireCouncilOnComplete } = require('../observe/on-complete');
 
 const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143, SIGBREAK: 143 };
 
 /**
  * @param {object} options {briefing, models, chair, critic?, lenses?, project, runId,
- *   runDir, timeout?, maxCost?, gateway?, noValidateModel?, date, debate?, noCostGate?}
+ *   runDir, timeout?, maxCost?, gateway?, noValidateModel?, date, debate?, noCostGate?,
+ *   councilName?, fallback?, catalog?} councilName (v4.3 Task 3) = preset name when
+ *   launched via `--council <preset>`, else null — threaded via ctx.o into every
+ *   launchWave/launchSolo for leg ledger attribution. fallback/catalog (v4.3 Task 18
+ *   §6.2): ctx.o carries both, but only run-stages.js's stage launches read them —
+ *   the chair/debate legs never substitute via chains.
  * @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, debate: false, claudeReviewFile: null,
-    noCostGate: false, ...options };
-  const launchers = deps.launchers || createLaunchers();
+    noCostGate: false, councilName: null, ...options };
+  o.follow = o.follow ? require('../observe/follow').createFollowPrinter({ json: o.json }) : null; // Task 13: stderr mirror
   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;
+  // v4.4: the whole budget position lives in ./run-budget — its docblock carries the "fail LOUD,
+  // not CLOSED" ruling, why reserveBudget (not merely remainingBudget) is what holds the ceiling
+  // across Stage-1's CONCURRENT launches, why addWave must release-and-account atomically, and
+  // why a refused wave sets `degraded` (a shrunken bench never exits 0) rather than aborting.
+  const degraded = { value: false };
+  const { addWave, overBudget, remainingBudget, noticeUnknownSpend, usageBlock, reserveBudget,
+    noteBudgetRefusal } = createBudget({ maxCost: o.maxCost, runDir: o.runDir, degraded });
+  const launchers = deps.launchers || createLaunchers({ remainingBudget, reserveBudget, onBudgetRefusal: noteBudgetRefusal });
 
   runState.initRun(o.runDir, {
     schemaVersion: 2, type: 'council-run', runId: o.runId, status: 'running', stages: [],
@@ -71,6 +79,7 @@ async function runCouncil(options, deps = {}) {
     usage: null, pid: process.pid, createdAt: now(),
   });
   runState.writePointer(o.project, o.runId, o.runDir);
+  emitRunStarted(o.runDir, o.runId, { bench: o.models, chair: o.chair }, o.follow);
 
   let signalled = null;
   const uninstall = installSignals({
@@ -80,17 +89,19 @@ async function runCouncil(options, deps = {}) {
     },
   });
 
-  const degraded = { value: false };
-  const finalize = (exitCode, error) => {
+  const finalize = async (exitCode, error) => {
     uninstall();
     const code = signalled || exitCode;
     const status = (code === 130 || code === 143) ? 'aborted'
       : code === 0 ? 'complete' : code === 1 ? 'error' : 'partial';
+    noticeUnknownSpend(); // v4.4: never finish a run silently short (run-budget.js)
     const run = runState.checkpoint(o.runDir, {
       status, exitCode: code, error: error || null,
-      usage: { cost: sumWaveUsage(allLegs).cost },
+      usage: usageBlock(),
       completedAt: now(),
     });
+    emitRunTerminal(o.runDir, o.runId, status, code, o.follow);
+    await fireCouncilOnComplete(o.onComplete, run, { runId: o.runId, runDir: o.runDir, exitCode: code, project: o.project }, o.onCompleteDeps);
     return { exitCode: code, run };
   };
 
@@ -116,11 +127,13 @@ async function runCouncil(options, deps = {}) {
       status: 'running', startedAt: now(), project: o.runDir,
       ...(o.lenses ? {} : { waveId: `${o.runId}-s1` }),
     });
+    emitStageStarted(o.runDir, o.runId, 'stage1', o.lenses ? null : `${o.runId}-s1`, o.follow);
     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),
     });
+    emitStageTerminal(o.runDir, o.runId, 'stage1', 'complete', o.lenses ? null : `${o.runId}-s1`, o.follow);
     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) {
@@ -131,6 +144,7 @@ async function runCouncil(options, deps = {}) {
     }
 
     // ---- Cost gate: Stage 2 is a paid launch; no tally exists yet (spec §4) ----
+    noticeUnknownSpend(); // v4.4: warn EARLY on a long run, not only at finalize
     if (overBudget()) {
       return finalize(1, {
         code: 'COST_EXCEEDED',
@@ -151,9 +165,11 @@ async function runCouncil(options, deps = {}) {
       .concat(claudeReview ? asm.labelClaudeReview(claudeReview, labels) : []);
     runState.updateStage(o.runDir, 'stage2',
       { status: 'running', startedAt: now(), waveId: `${o.runId}-s2`, project: ctx.scratchDir });
+    emitStageStarted(o.runDir, o.runId, 'stage2', `${o.runId}-s2`, o.follow);
     const s2 = await runStage2(ctx, { reviews: s1.reviews, labels, globalFindings,
       extraLabeled: claudeReview ? [{ label: claudeReview.label, text: claudeReview.text }] : [] });
     runState.updateStage(o.runDir, 'stage2', { status: 'complete', completedAt: now() });
+    emitStageTerminal(o.runDir, o.runId, 'stage2', 'complete', `${o.runId}-s2`, o.follow);
     if (signalled || s2.aborted) { return finalize(s2.aborted || signalled); }
     if (s2.judgeResults.filter(j => j.ok).length < 2) { degraded.value = true; } // thin cross-review
 
@@ -183,9 +199,12 @@ async function runCouncil(options, deps = {}) {
       // 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.
@@ -195,6 +214,7 @@ async function runCouncil(options, deps = {}) {
           return finalize(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.
@@ -203,6 +223,10 @@ async function runCouncil(options, deps = {}) {
         // 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
@@ -258,9 +282,14 @@ async function runCouncil(options, deps = {}) {
       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, o.debate ? 'tally-final' : 'tally', { status: 'complete', completedAt: now() });
+    const tallyStage = o.debate ? 'tally-final' : 'tally';
+    runState.updateStage(o.runDir, tallyStage, { status: 'complete', completedAt: now() });
+    emitStageStarted(o.runDir, o.runId, tallyStage, null, o.follow);
+    emitStageTerminal(o.runDir, o.runId, tallyStage, 'complete', null, o.follow);
     asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText });
     runState.updateStage(o.runDir, 'verdict', { status: 'complete', completedAt: now() });
+    emitStageStarted(o.runDir, o.runId, 'verdict', null, o.follow);
+    emitStageTerminal(o.runDir, o.runId, 'verdict', 'complete', null, o.follow);
 
     return finalize(degraded.value ? 2 : 0);
   } catch (err) {