Before a dollar is spent
Capacity checks, usage windows, the refusals that happen before a run spawns, and an honest statement of which ceiling is enforced by whom.
Two numbers ride on every dispatch: a prediction of what the work should cost, and a ceiling derived from it at twice that figure. What each of those is, who declares them, and what happens when a run reaches the ceiling is a topic of its own and is not repeated here.
This page is everything else that happens before the money moves — the capacity checks, the probes, and the refusals. They exist because the cheapest run is the one that never started, and the second cheapest is the one that was stopped a second before it did.
Which ceiling is actually enforced, and by whom
⚠ This is stated per backend, because it differs per backend, and a budget holder who assumes otherwise will be surprised exactly once.
| What holds the run | |
|---|---|
| A backend that accepts a spend limit of its own | The ceiling is composed onto the vendor's own budget option. A run that reaches it ends, under our own named status — distinct from a vendor error, and distinct from a provider limit. |
| A backend with no native spending limit | ⛔ There is no pre-enforcement. The ceiling is compared against the actual after the run, so it is a measurement rather than a brake. |
| Every backend, unconditionally | The wall clock. Every run carries a deadline and is killed at it. This is the engine's own backstop and it does not depend on any vendor's cooperation. |
The remediation when a ceiling is hit is the same in both cases — re-predict and re-run, or split the work, as a deliberate decision — but the moment you learn differs, and on a backend in the second row you learn afterwards.
Capacity is checked before commitment, as a report
Given a model and an expected cost, this probes every applicable place for room to run and reports what it found. It is a report and never a dispatch: there is no way to make it select a winner, and no way to chain it into a run. Two disciplines make the report worth reading:
- A place counts as free only on a positive assertion. A successful recorded probe with its own liveness marker present. ⛔ The absence of a failure is never read as a pass.
- "Could not measure" is a first-class answer, never collapsed into "not free". Those are opposite conclusions and they lead to opposite acts.
Subscription windows are measured, not assumed
A flat-rate plan is not unlimited — it is windowed, with capacity that refills on the plan's own cadence. This probes each seated account for its own usage reading and answers in three states: free, exhausted, or unknown, keeping the vendor's own reset wording verbatim rather than paraphrasing it into something that might be wrong.
Every reading is persisted, and an ordinary run that hits a provider limit extinguishes a stale "free" verdict at no extra cost — the fleet's own work keeps the report honest between probes.
⚠ A window nobody could put a number on is marked as unread on its own row, rather than left to read as a window with room. An absent percentage and a low percentage are opposite answers, and only the mark tells them apart.
It blocks nothing, deliberately. Nothing can positively clear an account again once it has been marked, so a refusal built on an absent number would idle capacity that no later measurement could release.
The pre-flight gate: what is wired, and what is not
A real dispatch can opt in to a pre-flight that runs the capacity probe and refuses the spawn when no probed place is free. The refusal enumerates every place it probed with that place's own reason, so the answer is actionable rather than a verdict. The pre-flight's own cost is stated on the option itself — nothing about capacity checking is silent, including its price.
Independently of that, a prediction at or above a configurable threshold — five dollars by default — flags the dispatch for visibility. A warning, never a block.
⚠ A seat's own usage reading is not part of that gate today. The gate checks capacity;
it does not check whether a flat-rate account still has window left. Reading a window before
committing work is saphan fleet usage, run deliberately. Wiring the one into the other is
a policy decision about how far capacity refusals are allowed to idle paid-for accounts, and
it has not been taken.
Two refusals that happen before the spawn
A dead session is refused before it burns capacity. Before casting work onto a seat, the cheapest legal probe of that seat's session runs — capped at two cents and cached briefly — and the spawn is refused if the session is already dead. A named refusal before the money moves, rather than a vendor error after it.
A step that asks for a model it does not need is refused outright. Work routed to the deterministic tier that requests a model-capable context is refused, with its own exit code, and the refusal is booked in the ledger at zero cost. Using a frontier model where ordinary code suffices is not discouraged here; it is refused, and the refusal leaves a row.
Declaring who pays for a seat
A seat is one identity on one machine slot, with its own profile and its own session — the unit by which several vendor accounts are driven in parallel from one machine. Each seat carries a billing class, set by an explicit act on the seat's own signed row:
| Class | Meaning |
|---|---|
subscription | Flat-rate capacity somebody already paid for; the marginal run inside the window is effectively pre-paid |
metered | Invoiced per token, from the first token |
local-energy | A model you host yourself: no vendor bills anything, and what is scarce is time and the host's capacity |
⚠ An untagged seat reads back as unknown, and anything that gates spend must treat
unknown exactly like metered. The conservative reading is the safe one: assuming a
seat is free is how an unbudgeted invoice arrives.
The economic consequence is the point of the feature. When most work runs on flat-rate accounts, metered APIs become a deliberate overflow rather than the default meter — and a model behind an endpoint you run yourself extends the ladder down to electricity, with ordinary deterministic tooling closing it at zero.
Declared zeros live in one place
A zero that means "this genuinely has no marginal cost" and a zero that means "nobody knows" must never look the same in a report. So the rate for a backend and model — or the declaration that there is no marginal rate at all — is written by a human into the pricing registry, and the engine only ever reads it.
- A declared zero books a real, countable zero, with the declaration named on the row.
- A model with no declaration books
unknown, and is named in every rollup until somebody declares it. - One structural exception exists so an unregistered local model cannot masquerade as vendor spend: a run against a loopback endpoint with no declaration is classed as electricity from the observed fact of the loopback itself.
What is not built
- ⚠ Ceilings are per run only. There is no envelope above the run — no stream-level or portfolio-level budget with its own threshold, and no monthly number burned down over time. Tracking a larger envelope is done by hand against the reads.
- ⚠ Nothing warns you mid-run. A run's spend crossing a fraction of its ceiling raises no notification; you read the number at close.
Next
- One yardstick across vendors — why running several backends is a cost instrument and not just a preference.
- What a ledger row knows — where all of this lands afterwards.
The dimensions of cost
The question of what agent development costs has no single answer — it has axes. Which axes the record can answer along, and which ones need an export.
One yardstick across many vendors
Running several backends is a cost instrument, not a preference — because the same order can be given to two actors and judged by the same tests.