Live E2E stand: the handbook states the wait-then-refuse admission rule

docs/DEVELOPMENT.md still described the retired contract ("halts scheduling
at the first refusal"); it now states the per-attempt rule the runner
implements (wait while blocked only by reservations in flight, refuse only
what can never fit, manifest keys refusals/first_refused). The RunBudget
docstring names the non-FIFO fairness policy and the on_wait-under-lock
contract the reviewers asked to pin.

Co-authored-by: Ouroboros <311266734+ouroboros-agent@users.noreply.github.com>
This commit is contained in:
Ouroboros 2026-09-05 14:33:49 +00:00 • committed by Anton Razzhigaev
parent 88509e2cea
commit 2f6d6e59c2
2 changed files with 10 additions and 5 deletions

View file

@ -309,7 +309,10 @@ class RunBudget:
def admit(self, job: tuple, root_tasks: int, data_root: pathlib.Path, *,
on_wait: Callable[[str], None] | None = None) -> tuple[bool, dict]:
"""``(admitted, facts)`` — blocks while the attempt cannot fit YET (``on_wait`` is told
"""Admission is not FIFO: a waiting large reservation can be leapfrogged by smaller
attempts admitted from other lanes and may end refused after waiting (bounded: spend only
grows and the job list is finite; cap-safe at every admission). ``on_wait`` runs UNDER the
budget lock — it must not touch the budget itself. ``(admitted, facts)`` — blocks while the attempt cannot fit YET (``on_wait`` is told
once, with the numbers, when the wait begins); ``facts["waited_sec"]`` is how long."""
need, name, waited_from = self.reservation(root_tasks), f"{job[0]}_a{job[1]}", None
with self._lock:

View file

@ -1278,10 +1278,12 @@ grant); the preflight takes `min(key limit remaining, account credits)` and
refuses below `--min-credit-usd`. `--total-budget` (default 100) is the RUN-WIDE
cap: a ledger sums the lanes' durable `llm_usage` costs, reserves
`--per-task-usd × root tasks` per attempt (SM1 and SW1 one root — scouts spend
under their root's `OUROBOROS_PER_TASK_COST_USD` fence — SK1 two), schedules a
new attempt only while `spent + reserved + reservation ≤ cap`, halts scheduling at
the first refusal (later attempts are recorded `not_run` with
`reason_code=budget_cap`), and writes each lane's TOTAL_BUDGET as its OWN reservation — an
under their root's `OUROBOROS_PER_TASK_COST_USD` fence — SK1 two), admits an
attempt only while `spent + reserved(in flight) + reservation ≤ cap` — an attempt that
cannot fit YET (blocked only by reservations in flight) waits for a settle and asks again,
one that can NEVER fit (`spent + reservation > cap`) is refused and recorded `not_run` with
`reason_code=budget_cap` for that attempt alone (no run-wide halt: a later, smaller attempt
is asked on its own; the manifest carries `refusals` and `first_refused`), and writes each lane's TOTAL_BUDGET as its OWN reservation — an
immutable ceiling disjoint from every other lane's, so the settled spend plus the ceilings
in flight never exceed the cap; the manifest records the cap, the spend, the reservation rule
and the stop reason. `--per-task-usd` (default 8) is the runtime's per-root-task