feat: pre-flight spend gate (--max-spend-usd, exit 4) — DSE-1514 round 4 of 4

[ernestprovo23]

Summary

Closes DSE-1514 — Round 4 of 4: the pre-flight spend gate. Before the first provider call, the full worst-case call plan for the selected mode is reserved at ceiling rates; over the cap, or unboundable, the run is refused with exit code 4.

• max_output_tokens — config, Council(...), --max-output-tokens; threaded to every call (members, adjudication ladder, verdict extraction incl. the repair retry, streaming); recorded in generation_settings only when set. An output cap is a prerequisite for a ceiling: nothing is inferred.
• Council.plan_calls(mode, …) — worst-case call plan derived from modes.py: raw N · vote N · synthesize N + C + 2CV · debate N·R + C · adversarial N + C · elite 3N + C + 2CV (C = keyed chain candidates, V = verdict extraction). Input bound = UTF-8 bytes of the known prompt + template + framing allowances + Σ(upstream output caps) × bytes-per-token for calls that embed prior outputs.
• --max-spend-usd (Decimal, never float) → reserve via reserve_cost → refuse before any provider call:
  • over cap → SpendCapExceeded — reserved total, cap, call count → exit 4
  • no output cap → cannot bound spend: no output cap (set --max-output-tokens or config max_output_tokens) → exit 4
  • planned model absent from the snapshot → cannot bound spend: no priced rate for <model_id> in snapshot <digest> (<date>) → exit 4
• Without either flag, behaviour is byte-identical to before.

Changed (deliberate)

• CACHE_FORMAT_VERSION 4 → 5 (Round 3); the output cap is part of cache identity.
• Nine test doubles widened to accept **kwargs (call sites now always pass max_output_tokens=); one pre-existing test uses two members instead of one so the verdict-extraction calls it asserts on are actually made (the N<2 gate).

Verification

• Builder: 977 passed; CI green. Round 5 QA re-check closed C1/C2/I1/M1–M5 and found one defect introduced by the C2 fix — I2: debate per-round receipts and the debate manifest omitted max_output_tokens from generation_settings while the calls were made with the cap; fixed in 8e83cf6 via the shared _generation_settings() path, pinned by a per-mode regression test. Round 5 QA fixes: usage-less receipts are priced from the phase-aware pre-flight bound (the plan-table row for the receipt's phase) when an output cap is set, otherwise unpriced — never the old flat constants (which under-bounded upstream-embedding phases 3–9×); a parametrized test asserts every phase's reservation ≥ the honest ceiling for its real worst-case bytes; the fourth refusal message documented; the gate's scope for library callers documented; evals.pricing one-shot-iterable robustness restored. Round 5 CSO findings (cap validation: NaN/Infinity/non-positive rejected; pretty_exceptions_show_locals=False; streaming cache-hit re-priced; snapshot loader never raises) fixed in 7663eea; the judge phase added to the byte-lower-bound suite.
• Plan: docs/plans/2026-09-03-bounded-cost-receipts.md Tasks 9–14. Round 5 QA adversarial + CSO read-only review summaries in the PR comments.

🤖 Generated with Claude Code

https://claude.ai/code/session_01K1dHPjZ1bZcE2GnX3KMMSH

[ernestprovo23]

Round 5 — CSO read-only review (whole DSE-1514 branch at 470265e) → YELLOW, all findings fixed in 7663eea

• Control-change determination: no existing security control changed — redact, scan_for_secret_material, verified_secret_safety, _receipt_error_category, _resolve_key, key_present untouched; registry.py / transport.py zero diff; adapter request bodies unchanged when the cap is None. The security-specific classification is the classifier's vocabulary rule.
• F1 (medium, fixed): non-finite spend caps — NaN crashed at the <= 0 comparison; Infinity was accepted and silently disabled the gate. Now: strict format check + is_finite() + > 0 in both the CLI (exit 2) and Council.__init__ (ValueError); underscored literals like 0_5 (which Decimal reads as 5) rejected.
• F2 (low-medium, fixed): --max-output-tokens 0/negative bypassed validation → min=1 on the option + a constructor check.
• F5 (low-medium, fixed): pretty_exceptions_show_locals=False pinned on the Typer app — with the allowed typer>=0.12.0 floor, an unhandled exception would otherwise print the user's prompt (a local) to stderr.
• F3 (low, fixed): ask_stream's cache-hit path now re-prices the hit before replay, so priced_as_of / staleness are not replayed from store time.
• F4 (informational, fixed): load_default_price_snapshot honours its never-raises contract for scalar payloads.
• Also closed from the Round 4 re-review: the judge phase added to the byte-lower-bound regression suite (it had 38 bytes of margin and no test).

959 tests on the builder; security suites unchanged and green.

🤖 Generated with Claude Code

[ernestprovo23]

Round 5 — QA adversarial re-verification (Opus, read-only, verified by execution)

Scope: stack sanity (main.. = 19 commits; r2 2b558a4 untouched; r3 d4b43e3; top 4420274), full suite + ruff on both heads, and a field-by-field regression matrix {synthesize, debate, adversarial, elite, stream} × {ok, 503} against base 7edb3a1.

Closed by execution

• C1 usage-less receipts: r3 → unpriced, run ceiling None (flat-constant branch gone). Top → phase-aware reservation from the plan table; recorded reservation ≥ honest ceiling (real wire bytes × input rate + cap × output rate) for every phase, including synthesis with 3×16 KB upstream (1.70× over) and elite revision ×3 (1.82–1.93× over) — the two that were previously 3.2× and 9.5× under.
• C2 debate receipts: N=3,R=2 → 7 receipts (3×round-1, 3×round-2, debate_final); N=3,R=3 → 10; drop-out case → 3+2+1+final. Ceiling moves with R. Base-vs-head delta is exactly the documented one; total_usage = per-receipt sum.
• I1 OpenAI-compat "usage": {} → not reported → unpriced (or reservation when capped). No receipt prices $0.000000 on reported_usage anywhere in the matrix.
• M1–M5 refusal messages ↔ README/PDD; gated entry points refuse with 0 provider calls while the 8 documented ungated primitives run; evals.pricing generator input; README snapshot date; secret-safety vocabulary guard mutation-tested.
• Regressions: every base→head delta is an additive pricing field or a debate per-round receipt; CACHE_FORMAT_VERSION 4→5; no loosened assertion in the key-leak or secret-safety suites; secret_safety re-stamps after pricing and flips to unverified when a round-1 receipt is poisoned; CLI --help gains only the two documented flags; a no-flags run is byte-identical on stdout.

New finding, fixed here

• I2 (Important): _build_debate_manifest (the C2 fix) built per-round receipts and the debate manifest's generation_settings without max_output_tokens, so a capped debate run attested to un-capped calls while fan_out had applied the cap. Fixed in 8e83cf6 by routing both through the shared _generation_settings() / receipt_from_answer(max_output_tokens=) path; a per-mode regression test (test_every_mode_records_the_output_cap_on_manifest_and_receipts) fails on debate only without the change. Builder: 977 passed, ruff clean.

Verdict after the fix: no open findings.