amicus 4.3.0 → 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-launch.js

@@ -18,11 +18,27 @@ 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,
@@ -37,7 +53,21 @@ function createLaunchers(deps = {}) {
    */
   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 },
@@ -73,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

@@ -119,13 +119,25 @@ 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,
@@ -133,7 +145,9 @@ async function runStage1(ctx) {
       });
       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'; }
@@ -225,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,7 +31,7 @@ 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');
 
@@ -52,20 +52,20 @@ async function runCouncil(options, deps = {}) {
   const o = { critic: null, lenses: null, maxCost: null, debate: false, claudeReviewFile: null,
     noCostGate: false, councilName: null, ...options };
   o.follow = o.follow ? require('../observe/follow').createFollowPrinter({ json: o.json }) : null; // Task 13: stderr mirror
-  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;
+  // 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: [],
@@ -89,15 +89,15 @@ async function runCouncil(options, deps = {}) {
     },
   });
 
-  const degraded = { value: false };
   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);
@@ -144,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',