spec amend: make budget enforcement concurrency-safe and accounting deterministic

[santosomar]

Failure scenario

The current budget requirements describe a halt after cumulative spend exceeds a cap. In a concurrent fleet, multiple agents can observe remaining budget and start model calls before the governor's next poll. Their combined in-flight cost can overshoot an operator's supposed hard ceiling by several calls.

Accounting and yield behavior are also not deterministic enough for independent implementations to agree:

• “cumulative wall-clock runtime” does not say whether pauses are excluded or concurrent agent time is summed;
• retries, failed calls, cached/reasoning tokens, delayed provider cost, and pricing changes are not covered;
• the “fraction estimated” could mean fraction of calls or fraction of spend;
• the trailing window is denominated in spend while finding membership is timestamp-based, but the boundary algorithm is unspecified;
• stop and hot-reload transitions do not define whether new calls are admitted, how in-flight calls settle, or whether cumulative totals reset.

These gaps can produce cap overruns and make the dashboard, status command, and yield auto-stop disagree even when each implementation appears to satisfy the present text.

Constitutional alignment

• Principle V — The Provider Is The Rate Arbiter: budget admission is based only on an operator-authored spend cap. It is not a provider-rate or concurrency throttle, and it does not alter adaptive 429 handling.
• Principle VI — Coverage Before Yield: the four-part low-yield conjunction remains unchanged. The amendment only makes the spend-window calculation deterministic.
• Principle XI — Persist Atomically: reservations and settlements must be atomic/idempotent so concurrent callers cannot spend the same remaining budget.

The proposal does not match the prohibited “static internal cap below the provider quota” anti-pattern. A budget cap controls total authorized spend; a rate cap controls call throughput.

Amendment level

FR-level amendment to spec.md §9.3–§9.4 and FR-128, with corresponding operational guidance, reference index, success criterion, and changelog updates. This is a MINOR spec change because it adds testable requirements and narrows implementation ambiguity without removing or inverting an FR.

Proposed FR diff

• Clarify FR-112 so runtime means active evaluation wall time across runs, excluding operator-requested pauses and not multiplying concurrent agent time.
• Add FR-112a: before each spend-creating model call, atomically reserve its maximum estimated cost; deny admission if settled spend plus outstanding reservations would exceed the cap; settle the reservation exactly once against actual cost. State explicitly that this is budget admission, not provider pre-throttling.
• Expand FR-113 to require an idempotent per-call ledger with call identity, role, provider/model, timestamps, token categories when available, immutable rate-card version, reported/estimated status, retries/failures when billable, and dollar-weighted estimated fraction.
• Clarify FR-115 by defining a trailing spend window as the newest chronological suffix of settled accounting events whose total is at least W and would be below W if its oldest event were removed. Use the resulting time boundary for confirmed-finding membership.
• Add FR-116a: a stop decision atomically closes new spend admission, allows already-reserved calls to settle, permits bounded non-LLM cleanup, and persists the stop reason.
• Clarify FR-128 hot reload: lowering a cap below settled spend plus reservations triggers immediate stop; raising a cap can clear the FR-011 restart block; cumulative accounting never resets implicitly.

Acceptance checks

• Concurrent admission near a cap never reserves more than the remaining budget.
• Duplicate/retried delivery of one call's accounting event is counted once.
• Paused time and fleet width do not inflate evaluation runtime.
• The same ordered spend/finding event stream produces the same trailing yield.
• Cap lowering, cap raising, stop, and restart transitions preserve cumulative totals and expose one durable reason.

[faizjamal0111-svg]

@santosomar, "multiple agents can observe remaining budget and start model calls before the governor's next poll", this is the failure I think everyone rediscovers, and observing-then-starting is precisely the shape of it. The only fix I've found is that observing isn't enough: each agent has to take the headroom before the call, at the worst case that call could cost, then give back the difference when the response arrives. Two agents can read the same remaining budget; they can't both hold it.

On your other ambiguities, for whatever a second implementation is worth, I've had to decide each of these and would be glad to be told I'm wrong:

• cached/reasoning tokens: the class split is only known after the call, so reserve at the most expensive class that could apply. Over-reserves, never under.
• pricing changes: a dated table, and if a response reports a token class the table doesn't know, stop admitting calls rather than guess. A deliberate outage beats a ceiling you can no longer enforce.
• in-flight settle across a window boundary: charge the call to the window that admitted it, except any amount beyond what it reserved, which no window authorised and which has to land on the live one. Splitting those two cases wrong lets a real overspend vanish at the boundary. That one cost me a day.
• retries: each attempt reserves independently, or a retry storm is free.