Cost cap

One ledger scalar per agent, cost_cap_usd. It is unset on every agent unless you set it, and unset means no check ever runs. There is no fleet-wide default and no implied ceiling.

agentctl agents set noor cost_cap_usd 500     # live immediately — no apply, no restart
agentctl agents set noor cost_cap_usd 1000    # raise it: the next turn/subsession/tick goes through
agentctl agents set noor cost_cap_usd ""      # clear it: back to no cap at all

The three choke points

When the cap is set and the agent's persisted spend has reached or passed it, three independent choke points refuse new model work. Each carries its own check.

choke point	code	how it refuses
an inbound turn (a channel message or agentctl inject)	runtime/channel/shim/server.ts → cost-cap.ts	answers the owner on their channel and injects nothing; the shim keeps running
subsession start / subsession resume	internal/cli/subsession.go → costcap.go	stderr and exit 1, before the drop-in is written and before systemctl start
a cron tick	packaging/payload/cron/cron-run.sh	logs it and exits 0 rather than failing the unit

All three notify the owner directly. Nothing is stopped or disabled: the agent's unit keeps running and every other verb keeps working, so lifting the cap takes effect on the next check.

Behaviour

property	detail
daily	resets at local midnight; a prior day's spend never counts against today
source	today's days[] entry in ~<agent>/workspace/.cache/fleet-usage-rollup.json
up to an hour stale	the rollup runs roughly hourly, so an agent can cross its cap and keep working
fails open	no cap, an unparseable cap, a missing or corrupt rollup — all proceed
not a containment boundary	two of the three checks run as the agent's own user, against agent-readable state

fleet-usage-rollup.py remains the only thing that prices tokens; no cost is re-derived. agents set rejects a value that would not parse.

Where the cockpit shows it

Read-only, in the Fleet app, in two places. Setting a cap stays a CLI action.

surface	what it shows
Agents table, cap column	blank when uncapped, $50 when capped, bad in the warn tone when unparseable
Usage tab, cost caps section	$34.20 spent / $50.00 cap per capped agent, closest-to-the-cap first

The section turns red and flags ≥ cap once spend reaches the ceiling, and lists cap not enforced for a capped agent whose rollup is missing. It sums today's spend only and ignores the tab's 7d/30d/90d picker, which is what the three checks compare against.