@event4u/agent-config 14.2.0 → 14.5.0

package/src/scripts/ai_council/py_parity.ts

@@ -0,0 +1,139 @@
+/**
+ * py_parity — the small Python-stdlib parity helpers the council modules share.
+ *
+ * Relocated out of `orchestrator.ts` UNCHANGED. That file sits ~870 lines over
+ * the source ceiling and this repository answers growth with extraction rather
+ * than a raised baseline (`gate-violation-baselines.json`
+ * § check_source_size_budget: "extract, then measure"). A reviewer diffs a
+ * move: no body here is edited, only exported.
+ *
+ * They exist at all because this module family is a faithful port of a retired
+ * Python implementation whose formatting and slicing semantics are asserted
+ * byte-for-byte by golden tests — JS `Math.trunc`, `String.slice` and
+ * `str.length` disagree with their Python counterparts on truncation sign,
+ * code points and surrogate pairs respectively.
+ */
+
+// ── small stdlib parity helpers ───────────────────────────────────────
+
+/** Mirror Python `int(x)` truncation-toward-zero on a float total. */
+export function _pyInt(x: number): number {
+    return Math.trunc(x);
+}
+
+/** Mirror Python `repr(int)` for the error message in estimate_debate_cost. */
+export function _pyReprInt(x: number): string {
+    return String(x);
+}
+
+/** Mirror `type(exc).__name__ + ": " + str(exc)`. */
+export function _excTag(exc: unknown): string {
+    if (exc instanceof Error) {
+        return `${exc.name}: ${exc.message}`;
+    }
+    return `Error: ${String(exc)}`;
+}
+
+/** dict.setdefault(key, value) — only set when key absent. */
+export function _setdefault(
+    obj: Record<string, unknown>,
+    key: string,
+    value: unknown,
+): void {
+    if (!(key in obj)) {
+        obj[key] = value;
+    }
+}
+
+/** dict.get(key, default). */
+export function _metaGet(
+    obj: Record<string, unknown>,
+    key: string,
+    fallback: unknown,
+): unknown {
+    return key in obj ? obj[key] : fallback;
+}
+
+/** Python `str.lstrip()` (no-arg) — strip leading whitespace. */
+export function _pyLStrip(s: string): string {
+    return s.replace(/^\s+/, '');
+}
+
+/** Python `str.rstrip()` (no-arg) — strip trailing whitespace. */
+export function _pyRStrip(s: string): string {
+    return s.replace(/\s+$/, '');
+}
+
+/** Python `len(str)` — code-point count, not UTF-16 unit count. */
+export function _pyLen(s: string): number {
+    let n = 0;
+    for (const _ of s) {
+        n += 1;
+    }
+    return n;
+}
+
+/** Python `s[start:end]` — code-point slicing. */
+export function _pySlice(s: string, start: number, end: number): string {
+    return [...s].slice(start, end).join('');
+}
+
+// ── Python-format / stdlib parity helpers ────────────────────────────────
+//
+// The orchestrator formats USD / scores / strengths via Python f-string
+// specs (`:.4f`, `:.2f`, `:.1f`) which round half-to-even on the decimal
+// representation. JS `toFixed` rounds half away from zero, so the spec
+// formatting is reimplemented to stay byte-exact with the retired Python implementation.
+
+/**
+ * Format `x` to `ndigits` decimals using round-half-to-even, matching
+ * CPython's `format(x, ".<ndigits>f")`.
+ */
+export function _pyFixed(x: number, ndigits: number): string {
+    if (!Number.isFinite(x)) {
+        return String(x);
+    }
+    const neg = x < 0 || Object.is(x, -0);
+    const abs = Math.abs(x);
+    const factor = Math.pow(10, ndigits);
+    const scaled = abs * factor;
+    const floor = Math.floor(scaled);
+    const frac = scaled - floor;
+    const tol = Math.max(Math.abs(scaled), 1) * 2 ** -40;
+    let rounded: number;
+    if (Math.abs(frac - 0.5) <= tol) {
+        rounded = floor % 2 === 0 ? floor : floor + 1;
+    } else {
+        rounded = Math.round(scaled);
+    }
+    let intStr = String(rounded);
+    let result: string;
+    if (ndigits === 0) {
+        result = intStr;
+    } else {
+        if (intStr.length <= ndigits) {
+            intStr = '0'.repeat(ndigits - intStr.length + 1) + intStr;
+        }
+        const whole = intStr.slice(0, intStr.length - ndigits);
+        const dec = intStr.slice(intStr.length - ndigits);
+        result = `${whole}.${dec}`;
+    }
+    return neg ? `-${result}` : result;
+}
+
+/** Mirror Python `str.strip()` (no-arg). Sibling-twin convention uses trim(). */
+export function _pyStrip(s: string): string {
+    return s.trim();
+}
+
+/**
+ * Mirror Python `str.split()` (no separator) — split on runs of whitespace,
+ * dropping leading / trailing whitespace (no empty tokens).
+ */
+export function _pySplitWhitespace(s: string): string[] {
+    const trimmed = s.trim();
+    if (trimmed === '') {
+        return [];
+    }
+    return trimmed.split(/\s+/);
+}

package/src/scripts/ai_council/response_render.ts

@@ -0,0 +1,99 @@
+/**
+ * response_render — the per-member meta line, and the one-call helper.
+ *
+ * Both are plumbing the orchestrator uses rather than orchestration, and both
+ * were extracted when the mid-flight fallback grew them: `orchestrator.ts` is
+ * ~1,000 lines over the source ceiling, and the documented response to growing
+ * an over-ceiling file is extraction, never a raised baseline
+ * (`gate-violation-baselines.json` § check_source_size_budget).
+ */
+
+import { CouncilResponse, type ExternalAIClient } from './clients.js';
+import { _metaGet } from './py_parity.js';
+
+/**
+ * The shape `callMember` reads off a question. Structural rather than an
+ * import of `CouncilQuestion`: that class lives in `orchestrator.ts`, and
+ * importing it back would make this extraction a cycle.
+ */
+interface QuestionShape {
+    readonly user_prompt: string;
+    readonly max_tokens: number;
+}
+
+/** Round half-to-even to `n` decimals, matching CPython's `format(x, ".nf")`. */
+type FixedFn = (x: number, n: number) => string;
+
+export interface MetaRenderDeps {
+    readonly pyFixed: FixedFn;
+}
+
+export function renderResponseMeta(r: CouncilResponse, deps: MetaRenderDeps): string {
+    const meta_dict: Record<string, unknown> = r.metadata ?? {};
+    const billable = Boolean(_metaGet(meta_dict, 'billable', true));
+    const estimated = Boolean(_metaGet(meta_dict, 'tokens_estimated', false));
+    const parts: string[] = [];
+    if (!billable) {
+        const label = (_metaGet(meta_dict, 'subscription_label', null) ||
+            'flat-rate') as string;
+        parts.push(`cost: subscription (${label})`);
+    } else {
+        const cost_usd = _metaGet(meta_dict, 'cost_usd', undefined);
+        if (typeof cost_usd === 'number' && !(typeof cost_usd === 'boolean')) {
+            parts.push(`cost: $${deps.pyFixed(cost_usd, 4)}`);
+        }
+        const prefix = estimated ? '~' : '';
+        parts.push(
+            `tokens: ${prefix}${r.input_tokens} in / ${prefix}${r.output_tokens} out`,
+        );
+    }
+    parts.push(`${r.latency_ms} ms`);
+    // A seat that answered over api because its cli transport died says so
+    // in the ARTEFACT, not only in metadata: otherwise the only visible
+    // difference from "was api all along" is a cost line nobody planned.
+    const fallback_from = _metaGet(meta_dict, 'fallback_from', null);
+    if (typeof fallback_from === 'string' && fallback_from !== '') {
+        const reason = _metaGet(meta_dict, 'fallback_reason', null);
+        const sticky = _metaGet(meta_dict, 'fallback_sticky', false) === true;
+        const why = typeof reason === 'string' && reason !== '' ? `: ${reason}` : '';
+        parts.push(
+            sticky
+                ? `transport: api (${fallback_from} lost earlier this pass${why})`
+                : `transport: api (fell back from ${fallback_from}${why})`,
+        );
+    }
+    return `*${parts.join(' · ')}*`;
+}
+
+
+/** Error-tagged member call — the split/ask branch is one shape, not three. */
+/**
+ * One member call, error-tagged rather than throwing — the split/ask branch
+ * appeared three times before this and is one shape, not three.
+ */
+export function callMember(
+    client: ExternalAIClient,
+    question: QuestionShape,
+    opts: { split?: { stable: string; suffix: string } | null },
+    systemFor: (m: ExternalAIClient) => string,
+    excTag: (e: unknown) => string,
+): CouncilResponse {
+    try {
+        return opts.split
+            ? client.ask_split(
+                  systemFor(client),
+                  opts.split.stable,
+                  opts.split.suffix,
+                  question.max_tokens,
+              )
+            : client.ask(systemFor(client), question.user_prompt, question.max_tokens);
+    } catch (exc) {
+        return new CouncilResponse({
+            provider: client.name,
+            model: client.model,
+            text: '',
+            error: excTag(exc),
+        });
+    }
+}
+

package/src/scripts/ai_council/spend_gate.ts

@@ -0,0 +1,123 @@
+/**
+ * spend_gate — the ceilings, the breach decision, and the event a breach raises.
+ *
+ * Extracted from `orchestrator.ts` unchanged, and the ordering is the point
+ * (`gate-violation-baselines.json` § check_source_size_budget: "extract, then
+ * measure"): the orchestrator sits far over the 1,500-line source ceiling, so
+ * a change that grows it has to hand a cohesive unit out rather than pin a
+ * higher number — the gate's own text calls raising the baseline a defect.
+ *
+ * The unit is cohesive on its own terms, not merely convenient: `CostBudget`
+ * states the ceilings, `_breach` decides whether one is crossed, `OverrunEvent`
+ * is what a crossing hands to the operator, and `_total_usd` is the arithmetic
+ * all three share. Nothing here calls a provider or knows what a round is.
+ *
+ * Re-exported from `orchestrator.ts`, so no caller changes.
+ */
+
+import type { CostEstimate } from './pricing.js';
+import type { ExternalAIClient } from './clients.js';
+import { would_exceed as _would_exceed_daily } from './budget_guard.js';
+
+export class CostBudget {
+    max_input_tokens: number;
+    max_output_tokens: number;
+    max_calls: number;
+    max_total_usd: number; // 0 = USD ceiling disabled (token caps still apply)
+    daily_limit_usd: number; // 0 = rolling 24h cap disabled (D3)
+
+    constructor(
+        args: {
+            max_input_tokens?: number;
+            max_output_tokens?: number;
+            max_calls?: number;
+            max_total_usd?: number;
+            daily_limit_usd?: number;
+        } = {},
+    ) {
+        this.max_input_tokens = args.max_input_tokens ?? 50_000;
+        this.max_output_tokens = args.max_output_tokens ?? 20_000;
+        this.max_calls = args.max_calls ?? 10;
+        this.max_total_usd = args.max_total_usd ?? 0.0;
+        this.daily_limit_usd = args.daily_limit_usd ?? 0.0;
+    }
+}
+
+
+/** Passed to `on_overrun` when projected spend exceeds the budget. */
+export class OverrunEvent {
+    member_index: number;
+    member: ExternalAIClient;
+    next_estimate: CostEstimate; // this member's projected cost
+    spent_input_tokens: number; // already-billed totals BEFORE this member
+    spent_output_tokens: number;
+    spent_usd: number;
+    projected_total_usd: number; // spent_usd + next_estimate.total_usd
+    daily_spent_usd: number; // rolling 24h spend BEFORE this member (D3)
+    daily_limit_usd: number; // the configured daily cap (0 = disabled)
+    breach_kind: string; // "session" | "daily" | "tokens"
+
+    constructor(args: {
+        member_index: number;
+        member: ExternalAIClient;
+        next_estimate: CostEstimate;
+        spent_input_tokens: number;
+        spent_output_tokens: number;
+        spent_usd: number;
+        projected_total_usd: number;
+        daily_spent_usd?: number;
+        daily_limit_usd?: number;
+        breach_kind?: string;
+    }) {
+        this.member_index = args.member_index;
+        this.member = args.member;
+        this.next_estimate = args.next_estimate;
+        this.spent_input_tokens = args.spent_input_tokens;
+        this.spent_output_tokens = args.spent_output_tokens;
+        this.spent_usd = args.spent_usd;
+        this.projected_total_usd = args.projected_total_usd;
+        this.daily_spent_usd = args.daily_spent_usd ?? 0.0;
+        this.daily_limit_usd = args.daily_limit_usd ?? 0.0;
+        this.breach_kind = args.breach_kind ?? 'session';
+    }
+}
+
+
+/** Mirror the Python `CostEstimate.total_usd` property. */
+export function _total_usd(e: CostEstimate): number {
+    return e.input_usd + e.output_usd;
+}
+
+export type BreachKind = 'tokens' | 'daily' | 'session' | null;
+
+/**
+ * The projected-spend verdict. One implementation because the round head and
+ * the fallback's metered retry must gate on the SAME rules — two copies of
+ * four comparisons is how they drift.
+ */
+export function _breach(
+    est: CostEstimate | null,
+    spent: Spent,
+    budget: CostBudget,
+): BreachKind {
+    const usd = est ? _total_usd(est) : 0.0;
+    if (
+        spent.input + (est ? est.input_tokens : 0) > budget.max_input_tokens ||
+        spent.output + (est ? est.output_tokens : 0) > budget.max_output_tokens
+    ) {
+        return 'tokens';
+    }
+    if (budget.daily_limit_usd > 0 && _would_exceed_daily(budget.daily_limit_usd, usd)) {
+        return 'daily';
+    }
+    if (budget.max_total_usd > 0 && spent.usd + usd > budget.max_total_usd) return 'session';
+    return null;
+}
+
+
+export interface Spent {
+    input: number;
+    output: number;
+    usd: number;
+}
+

package/src/scripts/ai_council/transport_resolver.ts

@@ -381,18 +381,35 @@ const FALLBACK_ELIGIBLE: ReadonlySet<CliFailureClass> = new Set([
     // of its shapes: the pre-spend gate refuses before any subprocess exists,
     // and the call-time shape is a provider 400 — rejected at the request
     // boundary, no generation performed.
-    //
-    // HONEST SCOPE: this set is not consumed by any shipped path today.
-    // `isFallbackEligible` and `MidFlightFallback` have zero call sites outside
-    // this module and its tests, so membership here is a stated property of the
-    // class, NOT a behaviour a caller performs. Said plainly because the
-    // opposite reading is the attractive one — the constraint really is the
-    // subscription transport's rather than the model's, so the api rung really
-    // would serve the same id, and it would be easy to write that as if it
-    // happened. It does not happen yet.
     'model_unservable',
 ]);
 
+/**
+ * Caller-supplied policy that widens the base eligibility set.
+ *
+ * `apiOnQuota` covers BOTH quota shapes, and both satisfy the same
+ * no-double-charge property the base set is built on:
+ *
+ * - the LOCAL `cli_call_budget` refusal happens before any subprocess exists
+ *   ("nothing sent, nothing booked" — `clients.ts` returns the response
+ *   without spawning);
+ * - the provider-side plan-quota rejection is refused at the request
+ *   boundary, no generation performed.
+ *
+ * They stay behind an opt-in for a different reason than double-spend: the
+ * fallback flips the billing class. A vendor CLI under a subscription login
+ * is unmetered; its api twin is metered USD. Silently converting exhausted
+ * plan quota into API spend is a decision the operator must state, not one
+ * `auto` may infer — the USD spend itself remains guarded by the ordinary
+ * `cost_budget` gates the orchestrator runs on the retry.
+ */
+export interface FallbackPolicy {
+    readonly apiOnQuota: boolean;
+}
+
+/** The base policy: exactly the three-plus-one no-double-charge classes. */
+export const DEFAULT_FALLBACK_POLICY: FallbackPolicy = { apiOnQuota: false };
+
 /** Normalise a raw client error / skip reason into a `CliFailureClass`. */
 export function classifyCliFailure(raw: string): CliFailureClass {
     const s = raw.trim().toLowerCase();
@@ -409,7 +426,19 @@ export function classifyCliFailure(raw: string): CliFailureClass {
     // Also matched on the provider's own wording, so a model refused at call
     // time (one the deny-list has never seen) classifies the same as one the
     // pre-spend gate caught.
-    if (s.startsWith('model_unservable') || s.includes('is not supported when using codex')) {
+    if (
+        s.startsWith('model_unservable') ||
+        // The token the PRODUCERS actually write. R2 round 6, finding 4:
+        // `clients.ts` emits `model_unsupported_on_transport` at both sites
+        // (the pre-spend gate at :1857 and the turn-failed path at :2002) and
+        // puts the vendor sentence in `metadata.detail`, never in `error` — so
+        // the class matched nothing a caller could produce and the contract's
+        // fourth eligible class was dead. The token is matched here rather
+        // than renamed at the producers because `code:` values reach the
+        // events log and a rename would break every reader of the history.
+        s.startsWith('model_unsupported_on_transport') ||
+        s.includes('is not supported when using codex')
+    ) {
         return 'model_unservable';
     }
     if (s === 'timeout') return 'timeout';
@@ -420,7 +449,22 @@ export function classifyCliFailure(raw: string): CliFailureClass {
 
 /** True when `failure` is eligible to fall through to the `api` rung. */
 export function isFallbackEligible(failure: CliFailureClass): boolean {
-    return FALLBACK_ELIGIBLE.has(failure);
+    return isFallbackEligibleUnder(failure, DEFAULT_FALLBACK_POLICY);
+}
+
+/**
+ * Policy-aware variant: the base set, plus `quota_exhausted` when the
+ * caller's policy opted in (`ai_council.fallback.api_on_quota`).
+ * `timeout` / `server_error` are ineligible under EVERY policy — a
+ * half-completed call must never be paid for twice, and no opt-in key
+ * exists (or may be added) to override that.
+ */
+export function isFallbackEligibleUnder(
+    failure: CliFailureClass,
+    policy: FallbackPolicy,
+): boolean {
+    if (FALLBACK_ELIGIBLE.has(failure)) return true;
+    return policy.apiOnQuota && failure === 'quota_exhausted';
 }
 
 /**
@@ -467,13 +511,37 @@ export class MidFlightFallback {
     private readonly used = new Set<string>();
 
     /** `'api'` to retry on the api rung, `'stop'` to surface the failure. */
-    attempt(provider: string, failure: CliFailureClass): 'api' | 'stop' {
-        if (!isFallbackEligible(failure)) return 'stop';
+    attempt(
+        provider: string,
+        failure: CliFailureClass,
+        policy: FallbackPolicy = DEFAULT_FALLBACK_POLICY,
+    ): 'api' | 'stop' {
+        if (!isFallbackEligibleUnder(failure, policy)) return 'stop';
         if (this.used.has(provider)) return 'stop';
         this.used.add(provider);
         return 'api';
     }
 
+    /**
+     * Give a provider its one fallback back, because the twin never ran.
+     *
+     * R2 round 2, finding 8. `attempt` claims the slot at DECISION time, which
+     * is correct — the claim is what stops a dead binary being retried once per
+     * round. But a claim that is never CONSUMED must not stay spent: when the
+     * projected-spend gate refuses the escalation, no api call happens, and
+     * leaving the provider marked means the seat can never re-decide. Every
+     * later round then re-spawns the dead cli binary and gets `'stop'`, which
+     * is the exact per-round-ledger behaviour the invocation-scoped ledger was
+     * chosen to avoid.
+     *
+     * Called ONLY on a path where the twin was built and then not called.
+     * A provider that actually retried keeps its claim spent — that is the cap
+     * working.
+     */
+    release(provider: string): void {
+        this.used.delete(provider);
+    }
+
     /** Providers that have already spent their one fallback. */
     spent(): readonly string[] {
         return [...this.used].sort();

package/src/scripts/bench_hook_injection.ts

@@ -17,10 +17,27 @@
  *     the fix is a registered decision, not a silent default bump
  *   - per-slot SUM over all bound concerns > the slot cap → RED
  *
+ * NOT FULLY DETERMINISTIC — this paragraph replaces a claim that said it was.
+ * The fixture path was described as "deterministic, CI-reproducible". For most
+ * concerns it is; they read only the committed envelope. But `end-review-nudge`
+ * decides whether to fire from the LIVE working-tree diff plus a once-per-session
+ * latch, so one commit reads 1,140 B with uncommitted changes present and 922 B
+ * without them. Two values, observed three times in one session as the tree went
+ * dirty, clean and dirty again — the earlier wording here said "three different
+ * values", which counted the readings and not the values, and an R2 review was
+ * right to call that an unbacked number inside the paragraph that exists to
+ * replace an unbacked claim.
+ * Two consequences. A single run is a reading of THIS checkout right now, so its
+ * number must never be pinned as acceptance evidence (a roadmap note tried, and
+ * had to be corrected). And the BREACH verdict is unaffected regardless, because
+ * a state-dependent concern can only push the sum UP: a green run is still a
+ * green run. Documented rather than fixed, because making this hermetic means
+ * changing what the concern reads — a change to the concern, not to its bench.
+ *
  * HONEST SCOPE, stated up front: concerns are conditional-silence by design —
  * a generic fixture triggers few of them, so most measure 0 bytes here. The
  * gate therefore enforces the cap on whatever DOES fire under the committed
- * fixtures (deterministic, CI-reproducible), while the census mode
+ * fixtures, while the census mode
  * (`--record`) measures REAL sessions: it appends counts-only lines
  * ({ts, slot, concern, bytes}) to agents/runtime/state/injection-census.jsonl
  * — the repeat-injection-census blocker's instrument. Claiming the fixture
@@ -62,10 +79,74 @@ export interface Measurement {
     breach: boolean;
 }
 
+interface PerTurnAggregate {
+    tool_calls: number;
+    slots_counted: string[];
+    ceiling_bytes: number;
+    gate_on_ceiling: boolean;
+}
+
 interface Budget {
     default_cap_bytes: number;
     per_concern_caps_bytes: Record<string, number | string>;
     per_slot_sum_caps_bytes: Record<string, number | string>;
+    per_turn_aggregate_bytes?: PerTurnAggregate;
+}
+
+/** The per-turn aggregate reading, or the reason there isn't one. */
+export interface TurnAggregate {
+    /** Bytes a representative turn injects, or `null` when it is not derivable. */
+    bytes: number | null;
+    ceiling: number;
+    gated: boolean;
+    breach: boolean;
+    /** Present only when `bytes` is null — names the slot that was missing. */
+    unresolved?: string;
+}
+
+/**
+ * Derive the per-turn aggregate from the same per-slot sums the rows above
+ * report, per `per_turn_aggregate_bytes.definition`.
+ *
+ * Returns `null` bytes rather than a number when a counted slot produced no
+ * reading. This is the latency twin's rule, adopted deliberately: a composite
+ * over a subset reads LOW, and low is the direction that makes a ceiling look
+ * met. A missing slot is an unresolved measurement, never a small one.
+ */
+export function perTurnAggregate(
+    slotSums: Record<string, { bytes: number; unresolved?: boolean }>,
+    cfg: PerTurnAggregate | undefined,
+): TurnAggregate | null {
+    if (cfg === undefined) return null;
+    const perCallSlots = new Set(['pre_tool_use', 'post_tool_use']);
+    let bytes = 0;
+    for (const slot of cfg.slots_counted) {
+        const reading = slotSums[slot];
+        if (reading === undefined || reading.unresolved === true) {
+            return {
+                bytes: null,
+                ceiling: cfg.ceiling_bytes,
+                gated: cfg.gate_on_ceiling,
+                // AN UNRESOLVED COMPOSITE BREACHES WHEN THE ROW IS ARMED. It used
+                // to return `false` here, which meant the protection this
+                // function's docstring calls load-bearing was a printed word and
+                // not a gate: once `gate_on_ceiling` is armed, a composite over a
+                // subset of its slots reads low, and low is the direction that
+                // makes a ceiling look met — so the run would have exited green
+                // over a measurement that does not exist. Found by the R2
+                // completion review, 2026-08-19.
+                breach: cfg.gate_on_ceiling,
+                unresolved: slot,
+            };
+        }
+        bytes += perCallSlots.has(slot) ? reading.bytes * cfg.tool_calls : reading.bytes;
+    }
+    return {
+        bytes,
+        ceiling: cfg.ceiling_bytes,
+        gated: cfg.gate_on_ceiling,
+        breach: cfg.gate_on_ceiling && bytes > cfg.ceiling_bytes,
+    };
 }
 
 function capFor(budget: Budget, concern: string): number {
@@ -129,12 +210,12 @@ export function runConcernOnce(
     }
 }
 
-export function bench(opts: { platform?: string; budgetPath?: string } = {}): { measurements: Measurement[]; slotSums: Record<string, { bytes: number; cap: number; breach: boolean }>; errors: string[] } {
+export function bench(opts: { platform?: string; budgetPath?: string } = {}): { measurements: Measurement[]; slotSums: Record<string, { bytes: number; cap: number; breach: boolean }>; errors: string[]; turnAggregate: TurnAggregate | null } {
     const platform = opts.platform ?? 'claude';
     const manifest = _load_yaml(MANIFEST);
     const budget = JSON.parse(fs.readFileSync(opts.budgetPath ?? BUDGET, 'utf8')) as Budget;
     const measurements: Measurement[] = [];
-    const slotSums: Record<string, { bytes: number; cap: number; breach: boolean }> = {};
+    const slotSums: Record<string, { bytes: number; cap: number; breach: boolean; unresolved?: boolean }> = {};
     const errors: string[] = [];
 
     for (const event of EVENT_VOCABULARY) {
@@ -143,10 +224,19 @@ export function bench(opts: { platform?: string; budgetPath?: string } = {}): {
         const envelope = JSON.parse(fs.readFileSync(fixtureFile, 'utf8')) as JsonObject;
         const concerns = _resolve_concerns(manifest, platform, event);
         let sum = 0;
+        // A concern the registry cannot resolve contributes NOTHING to `sum`, so
+        // the slot total is short by an unknown amount. It used to be reported as
+        // a resolved low number, which is the one direction that makes a ceiling
+        // look met — `perTurnAggregate`'s own docstring refuses exactly that for a
+        // missing fixture, and a missing concern is the same defect one level
+        // down. Marked unresolved so the composite refuses to derive from it.
+        // (R2 review, 2026-08-19.)
+        let slotUnresolved = false;
         for (const concern of concerns) {
             const bytes = runConcernOnce(String(concern['script']), Array.isArray(concern['args']) ? concern['args'].map(String) : [], envelope);
             if (bytes < 0) {
                 errors.push(`${event}/${String(concern['name'])}: not in CONCERN_REGISTRY`);
+                slotUnresolved = true;
                 continue;
             }
             const cap = capFor(budget, String(concern['name']));
@@ -156,9 +246,9 @@ export function bench(opts: { platform?: string; budgetPath?: string } = {}): {
         }
         const slotCapRaw = budget.per_slot_sum_caps_bytes[event];
         const slotCap = typeof slotCapRaw === 'number' ? slotCapRaw : Number.MAX_SAFE_INTEGER;
-        slotSums[event] = { bytes: sum, cap: slotCap, breach: sum > slotCap };
+        slotSums[event] = { bytes: sum, cap: slotCap, breach: sum > slotCap, ...(slotUnresolved ? { unresolved: true } : {}) };
     }
-    return { measurements, slotSums, errors };
+    return { measurements, slotSums, errors, turnAggregate: perTurnAggregate(slotSums, budget.per_turn_aggregate_bytes) };
 }
 
 export function main(argv: readonly string[]): number {
@@ -211,10 +301,31 @@ export function main(argv: readonly string[]): number {
         for (const [slot, s] of Object.entries(result.slotSums)) {
             if (s.bytes > 0) process.stdout.write(`  slot-sum ${slot.padEnd(20)} ${String(s.bytes).padStart(6)} B (cap ${s.cap === Number.MAX_SAFE_INTEGER ? '—' : s.cap})${s.breach ? '  ❌ BREACH' : ''}\n`);
         }
+        const agg = result.turnAggregate;
+        if (agg !== null) {
+            const reading =
+                agg.bytes === null
+                    ? `UNRESOLVED (slot '${String(agg.unresolved)}' produced no reading)`
+                    : `${String(agg.bytes)} B`;
+            const arm = agg.gated ? 'gated' : 'reported, not gated';
+            process.stdout.write(
+                `  per-turn aggregate      ${reading} (ceiling ${String(agg.ceiling)} B, ${arm})${agg.breach ? '  ❌ BREACH' : ''}\n`,
+            );
+        }
         for (const e of result.errors) process.stdout.write(`  warn: ${e}\n`);
     }
-    if (breaches.length > 0 || slotBreaches.length > 0) {
-        process.stderr.write(`bench_hook_injection: ${breaches.length} concern breach(es), ${slotBreaches.length} slot-sum breach(es) — the budget row is the decision surface (src/config/hook-token-budget.json)\n`);
+    const aggBreach = result.turnAggregate?.breach === true;
+    if (breaches.length > 0 || slotBreaches.length > 0 || aggBreach) {
+        // The aggregate is named in the failure line. It used to be absent, so an
+        // aggregate-only red read "0 concern breach(es), 0 slot-sum breach(es)"
+        // and exited 1 — a CI failure that named no cause. (R2 review, 2026-08-19.)
+        const agg = result.turnAggregate;
+        const aggPart = !aggBreach
+            ? ''
+            : agg?.bytes === null
+              ? `, per-turn aggregate UNRESOLVED (slot '${String(agg.unresolved)}' produced no reading) while the ceiling is armed`
+              : `, per-turn aggregate ${String(agg?.bytes)} B over its ${String(agg?.ceiling)} B ceiling`;
+        process.stderr.write(`bench_hook_injection: ${breaches.length} concern breach(es), ${slotBreaches.length} slot-sum breach(es)${aggPart} — the budget row is the decision surface (src/config/hook-token-budget.json)\n`);
         return 1;
     }
     return 0;