A child that overspends its reservation is settled down after its artifact exists; the artifact is dropped

[drewstone]

Version checked

@tangle-network/agent-runtime 0.219.0 (605374f6), the version discovery-lab installs. Lines below are origin/main at that commit.

Defect

pool.reconcile (src/runtime/supervise/budget.ts:678) commits the child's actual spend to the pool and then throws when it exceeds the reservation. The child settle path calls it at src/runtime/supervise/scope.ts:2778 after the executor has returned its artifact, and rethrows at :2831 / :2842 before :2870 content-addresses and stores artifact.out. The child settles down, infra: true, with no outRef. The pool's totals were already correct before the throw, so the throw changes no accounting; it discards a finished, paid-for result and hands the director a dead child.

This is the executor-side twin of #1164 (driver side: charge a turn, then throw supervisor budget exhausted).

The runtime cannot enforce the cap in flight with this executor: the progress fold at scope.ts:2809 sees usage only when the provider reports it, and the Tangle sandbox executor reports zero until its terminal receipt (see the exhibit; filed separately at the provider).

Measured

Run mech-interp-foundations-astra-b-20260912a (discovery-lab), 2026-09-12, both children runtime: tangle-sandbox, GLM-5.3:

child	reservation	progress events	first non-zero usage	execution-result	settled
s0 (enumerate:mi-open-problems)	{ maxIterations: 16, maxTokens: 800000 }	159 over 15m05s, events 0–156 all { input: 0, output: 0 }	event 157 at 23:38:02.373Z: { input: 1871225, output: 46902 }	23:38:05.618Z	23:38:08.422Z down, infra: true, budget pool: ticket 0 spent 1918127 tokens > reserved 800000, outRef absent
s3 (Check sheaf-source scope and gauge assumptions)	{ maxIterations: 10, maxTokens: 70000 }	44 over 4m11s, events 0–41 zero	event 42 at 23:31:17.952Z: { input: 566461, output: 26159 }	23:31:20.640Z	23:31:23.588Z down, infra: true, budget pool: ticket 3 spent 592620 tokens > reserved 70000

Journal: pursuits/mech-interp-foundations-astra-b-20260912a/spawn-journal.jsonl in the Lab checkout (retained on request). Cost of the two children is unknown to the meter (usdKnown: false, router-served GLM); the tokens are 2.51M input.

What the settle should do

Keep the artifact. Settle done with the violation on the record (a budgetViolation field, and a journal event), so the director and the ledger see the overspend and the pool's free balance, which is already reduced by the true spend, refuses the next reservation on its own. down with infra: true for a child that completed is the wrong verdict twice: it was not infrastructure, and it did not fail.

When an executor does report usage in flight, the progress fold is the place to abort at the reservation; that is the cap the director asked for.

[drewstone]

Third exhibit, and the cost is a charter. In mech-interp-foundations-glm2-b-20260912b the literature graph reached its review stage for the first time in this Lab (enumerate 3/3, extract 17/24, 117 problems mined). The one review child that started ran a single iteration to 1,115,291 tokens against an 800,000 reservation and was settled down at reconcile with its output dropped; the graph then failed closed with no charter. Director's record: pages/glm2-b/literature/20260913b-graph-receipt-blocked.md in the mech-interp-foundations store.

[drewstone]

Fixed in #1218 (merged as 2feb583e) and released in @tangle-network/agent-runtime@0.223.0.

What changes for a consumer

• A child that returns a finished result after overspending its reservation settles done with its output stored and outRef set.
• The overspend is on the settlement as budgetViolation: { overspent: [{ channel, reserved, spent }] } (channel: tokens in charged tokens, iterations, usd, or resource:<name>).
  It appears on Settled, the settled/cancelled journal record, the agent.child hook payload, live and materialized NodeSnapshots, replay, retained recovery, the driver's await_event settlement and settled() ledger, and the driver roster and resume brief.
• Pool accounting is unchanged: the true spend is committed, the free balance goes negative, and the next reservation is refused on its own.
• BudgetPool.reconcile returns the BudgetViolation instead of throwing it.
  It still throws BudgetReconcileFault (and the child still settles down, infra: true) when spend cannot be verified: unknown dollar cost under a dollar cap, or unknown or overflowing enforced resource usage. That fault wins even when tokens also overspent, and the down record still carries the measured overspend.
• PursuitNodeProjection carries budgetViolation, so a pursuit ledger built from the observer journal sees it.
• Consequences: a keyed child that completed with an overspend resolves completed (key reuse returns the result instead of retrying), and the supervisor's down-rate breaker no longer counts it.
• A crashed or failed child stays down and carries the overspend beside its reason.

Checked on the #1206 shape: a streaming child reserved at 800,000 that reports zero usage and then 1,871,225 input + 46,902 output in its terminal receipt now settles done with its blob stored and budgetViolation tokens 1,918,127 > reserved 800,000; the pool reads 581,873 of 2,500,000 left and refuses the next 800,000 reservation (tests/kernel/overspend-settlement.test.ts; its first 9 tests failed 8 of 9 on unmodified main). Full local suite at the merged tree: 3,899 passed, 11 skipped, 0 failed.

Not changed: no in-flight abort at the reservation.
The progress fold cannot tell a report that crosses the reservation from the last report: executors report usage after the model call it measures, and the Tangle sandbox executor reports all of it in its terminal receipt (here, 3.2 s before execution-result).
Aborting there would drop the artifact at the moment it is returned while saving no spend.
A cap that prevents spend has to be enforced by the executor before it starts a call the remaining reservation cannot cover; ExecutorContext does not carry the reservation today, and the sandbox executor also needs in-flight usage (agent-sdk#324).