test(budget): pin the usage-attribution invariant — child cost bills, child context never leaks (#418)

[justrach]

Closes #418. Audit outcome: no bug. The invariant already holds, and it holds structurally rather than by a discipline someone could forget. The test is the deliverable.

The question, answered

Does a child's usage ever reach the parent's context estimate, as opposed to only its billing totals?

No. The two accounts are separate by construction:

• Bill is process-wide. Agent.recordCost writes pricing.g_cost, a global tally. A child bills the run automatically — that is why the [usage] footer includes the fleet.
• Meter is per-Agent. last_context_tokens / context_local_tokens are fields on the Agent that made the request. runSub gives the child a fresh Agent with both at their 0 defaults, and ToolCtx carries no pointer back to the parent Agent — so a child has nothing to write to even if it tried.
• Compaction inputs are parent-local. inputOverCompactThreshold → effectiveContextTokens → contextEstimate reads only self.messages, self.systemPrompt(), self.toolsJson() and the two self anchors, and both gate call sites pass root.
• run_budget.zig / phase_budget.zig have no token field at all — they ledger model calls, depth and concurrency. There is nothing there to conflate.

All 7 runSub call sites were checked, across both spawn paths: foreground execSubagent keeps run.output and drops run.usage; background agentJobPump stores job.usage and agent_output renders it as text; the workflow/retry/judge/pipeline sites all return run.output. No asymmetry between them, which is where a bug of this shape would most likely hide.

Worth noting the layers that do reuse the root Agent already implement exactly the capture-and-pin-back the issue describes: review.Context.begin/restore and compact().

The tests

parent context is identical with and without an attributed child; only the bill differs — two identically seeded roots, one of which runs eight workers each ending at 164k context, deliberately past the parent's 80k compactAt() so a single leaked token would trip the gate. Asserts last_context_tokens, context_local_tokens, effectiveContextTokens() and inputOverCompactThreshold() all equal the control field-for-field, and that g_cost moved by exactly 8× the children's in/cache/out tokens and USD.

a child's context total reaches the parent as report bytes, never as context — a child reporting 480k has its status line appended as a tool result; the parent grows by under 200 tokens rather than 480k, and stays under threshold.

One latent trap found, documented rather than changed

behavior_upload.zig sums context_tokens across parent and subagent API calls, so a fleet turn's TurnMetrics.context_tokens is a sum-of-agents, not an occupancy. It is write-only telemetry that no harness decision reads back, so it is not a bug today — but it is exactly the field someone would later mistake for a context reading, so it now says so in place.

Verification

zig build test → 1118/1118, +2 from the 1116 baseline. scripts/eval-tier1.sh green (reachability confirms 1079 declared tests compiled in).

Not traced: whether the GUI/--json frontend aggregates the agent_usage event's context_tokens for display. That is a wire event to a separate process and cannot feed the Zig meter, so it is outside this invariant, but the GUI side was not read.