[coordination] Autonomous work budget — bound spend across every unattended entry point

[serge-ivo]

Design: docs/supervision.md. Companion to #183. Revised after critical review — the first draft was wrong in three ways, recorded below.

Why

Nothing in the platform enforces a spend cap. ai_usage (migration 0048) records cost_micros faithfully, but it is a ledger, not a control — it tells you what a runaway cost you, after it cost you. The only limits in the codebase are req/min rate limits, which bound request frequency, not spend.

Two levels of hierarchy in code are safe because a human wrote them. N levels by configuration are not. Fan-out 5 at 3 levels is 125 leaf runs from one delegation, each an LLM call.

Three corrections to the original draft

1. Depth bounds almost nothing. The first draft leaned on depth as a primary control. It is not: a supervisor at depth 1 can re-delegate sequentially a thousand times without ever increasing depth. Depth caps tree height; it does not cap work. Keep it as a cheap per-path guard, but cost is the real control, plus a separate delegation-count guard (a cheap model can spin thousands of iterations before a cost budget bites).

2. "Carries a budget, decremented at every hop" is wrong under fan-out. That describes a value copied down each path — so five siblings each receive the full allowance and the tree total becomes allowance × fanout^depth, i.e. unbounded in exactly the quantity we are trying to bound. It must be a shared pool scoped to the root delegation, drawn from atomically (UPDATE … SET remaining = remaining - ? WHERE remaining >= ?), not a per-path copy.

3. Check-then-go overshoots under concurrency. Cost is only known after a run. An optimistic "is there budget left?" check lets N concurrent branches all pass simultaneously and overshoot by N × run_cost. This is the classic overbooking problem. Correct pattern: reserve a bounded maximum before starting, settle the actual on completion, refund the remainder.

Scope correction: budget every autonomous entry point, not just delegation

Supervision makes this acute but did not create it. Today every unattended path starts work with no budget:

• cron triggers
• inbound webhook triggers
• connection deliveries (the pump)
• delegations ([coordination] Supervision graph as configured platform data — hierarchy belongs to the platform, not inside an agent #183)

Budgeting only delegation plugs one hole in a boat. This should be one primitive covering all four, with delegation as the first consumer.

Retries and replay must draw from the same pool. The 0058 outbox retries up to 5 times with backoff, and each retry re-runs the action — so a persistently failing consumer can cost 5× before dead-lettering. Manual replay is currently unlimited. Both must check and draw.

Two pools, different purposes

• BYOK spend (the user's own Anthropic key) — the platform is not financially exposed; the user is. So this is a user-safety feature: user-visible, user-configurable, sensible non-infinite defaults, and a hard stop rather than a soft warning.
• Platform Workers AI — genuine platform cost, and the operator's control (relates to [Admin][API] Runtime kill switch for platform-paid AI (platform_settings override) #46 runtime kill switch, [Admin][API] Cloudflare billing-actuals for authoritative platform AI spend #45 billing actuals).

Natural chokepoint for both: the BYOK/Workers-AI call path that already writes ai_usage.

Scope

• Root-scoped budget pool: remaining cost (micros) + remaining delegations + max depth.
• Atomic reserve-and-settle at the model-call chokepoint; refund unused reservation on completion.
• Admission check at every autonomous entry point (cron, webhook, delivery, delegation) and on retry/replay.
• Per-user/period backstop in addition to the per-tree pool — a tree budget alone does not stop a thousand small runaway trees.
• Exhaustion is a distinct, visible outcome recording where it stopped ("budget exhausted at depth 3"), and must preserve the partial work as resumable once the human raises the limit. Exhaustion must not destroy what was already paid for.

Acceptance

• Total spend across an entire delegation tree is bounded by the root pool, regardless of fan-out.
• Concurrent siblings cannot collectively overshoot the pool.
• A supervisor cannot raise its own budget by delegating (the pool only ever decreases).
• Sequential re-delegation at constant depth is bounded by the cost/count budget.
• Retries and replays draw from the pool.
• Exhaustion surfaces its own status and the work resumes after a raise.
• Tests: fan-out overshoot, concurrent draw, sequential re-delegation, retry drain, resume-after-raise.

Note

Build this with #183. Threading a budget through an existing handoff path is a retrofit touching every call site; adding it while the path is being defined is nearly free.

[serge-ivo]

UX continuity — hard acceptance criteria (added after review)

The question that decides whether this is a safety feature or an obstacle: does it preserve what Coder does today? Three conditions, all binding.

1. Attended work is not hard-capped

When a human clicks Loop and watches, the human is the circuit breaker. Hard stops belong on paths that run while you sleep — cron, webhook, connection delivery, unattended delegation. Applying a runaway-prevention cap to an interactive session degrades the product for no safety gain.

Interactive paths get visibility (live spend, projected cost), not enforcement. /explain and Chat — single cheap calls — are not gated at all; an admission check on every chat turn is a latency and failure regression.

Subtlety: the Pilot is durable, so "attended" is a property of the moment, not the path. A session you started and walked away from stays bounded — but at a level tuned to real sessions, not to runaways.

2. Exhaustion is a pause with a one-click raise, never a failure

"Preserve partial work as resumable" (original wording) is too weak. If Loop stops at iteration 30 and the session is gone, that is strictly worse than today, where nothing stops it.

Required: pause, keep the session + timeline intact, surface "continue (+$5)", and resume without redoing completed work.

3. Defaults derived from the ledger, not guessed

ai_usage already separates kind (coding / copilot / overseer / chat) with cost_micros per row. Compute the real distribution of session cost and set defaults above the 95th percentile.

Acceptance test writes itself: what fraction of historical sessions would this default have interrupted? Target ~0. Shipping a guessed number is exactly how this breaks the UX.

One conflict to design away

The Loop UI already has max iterations — Coder therefore already exposes a budget, and this primitive generalizes a concept users have been taught, rather than imposing a new one. But a count budget and a cost budget can disagree (you set 50, cost cuts at 30). Both should enforce, the UI must say which one stopped it, and iterations must appear as one dimension in the same budget panel. Two invisible, disagreeing limits are worse than either alone.

Dependency

#158 is a precondition. You cannot budget a loop you do not own — today the Loop is driven from the browser (InstanceDetail.tsx polling /loop-decide), so the platform cannot stop it, count it reliably, or reserve against a pool. Every enforcement point here sits on the server side of a loop the server does not currently drive.

Design goal, stated plainly: invisible in normal use, decisive in a runaway.

[serge-ivo]

Substrate landed in 4ecb80e (migration 0061). Built to the revised design, not the original draft.

The atomic draw — one UPDATE whose WHERE carries the affordability test:

UPDATE delegation_budgets
   SET cost_micros_reserved = cost_micros_reserved + ?3,
       delegations_used     = delegations_used + 1
 WHERE id = ?1 AND user_id = ?2 AND status = 'open'
   AND ?4 <= max_depth
   AND delegations_used < delegations_limit
   AND (cost_micros_limit - cost_micros_reserved - cost_micros_spent) >= ?3

Whoever D1 applies second sees the first reservation already subtracted and matches zero rows. A read-then-write would race. Depth and the count are guarded in the same statement rather than in JS, so a concurrent sibling cannot slip past them. There is a test asserting exactly one statement is issued — i.e. that this did not regress into check-then-write.

On refusal it re-reads to report which limit stopped it. "Budget exhausted at depth 3" is actionable; a bare failure is not.

Other pieces worth noting:

• settle clamps the release with MAX(0, …) — without it a duplicate settle drives reserved negative, which the affordability test reads as free budget.
• An overspend is charged in full rather than capped at the reservation. The money is already gone; a pool that hides it lies.
• Exhaustion is a distinct status from failure, with reason + depth, so work survives and resumes via raiseBudget() — the one place a budget goes up, and human-only.
• sanitizeLimits clamps to the ceiling rather than merely defaulting, so an agent cannot raise its own budget by requesting more when opening a child tree.
• Defaults are finite for an unconfigured tree, because "we'll set a limit later" is how the first runaway happens.

40 tests.

Still open on this ticket: wiring reserve/settle into the model-call chokepoint (blocked on #158 — you cannot budget a loop you do not own); the per-user/period backstop, which a per-tree pool does not give you (it does not stop a thousand small runaway trees); and deriving the defaults from the ai_usage distribution per kind instead of the placeholder $5, per the UX conditions above.