feat(server): account for token usage per dispatch (#346 DI-33)

[m2ux]

The engine half of DI-33 from #346.

The defect

next_activity recorded an activity_usage event keyed to the activity a transition exits. So a dispatch not followed by a transition never reached the ledger:

• a resume after a checkpoint yield
• a re-dispatch after a timeout
• an out-of-band dispatch
• an abandoned session
• the terminal activity, which nothing exits

The review run that surfaced this reported 2,751,188 tokens against an actual 4,130,657 across 33 dispatches — a third of the run missing, including the pass that produced both Critical findings its verdict rested on.

The change

Cost belongs to a dispatch, not to a graph edge.

record_usage { session_index, activity, usage } writes one event per dispatch, and next_activity no longer takes usage at all. One write path, so there is no double-count to guard against and no attribution question to answer.

That also retires usageWarning, which fired when usage rode an entry transition that exits nothing. The case only existed because an edge was being asked to carry a dispatch's cost — remove the premise and the warning has nothing to warn about.

The activity_usage event type is unchanged, so projectUsage and the inspect_session usage view needed no edit. That projection already documented one entry per pass and left summing to the caller, which is exactly the shape per-dispatch accounting wants — only the write side was missing.

Absence stays distinguishable from zero: omit the call when the harness surfaces nothing, since a worker cannot self-measure.

This is a breaking change to next_activity

An optional parameter is removed. Nothing in the repo passes it after this change, and the orchestrator contract that told callers to pass it is updated in #351. Pre-1.0, and pre-merge, is the moment to do this rather than carry two paths.

Worth flagging honestly: I first assessed the parameter as having no dependents. Three tests did — a dedicated next_activity usage accounting (#324 B1) suite, including a deliberately-designed test for the entry-transition warning. So this removes a considered, tested design, not an oversight. I still think it is right, because that warning is itself evidence the transition model was awkward, but it deserves a reviewer's eye rather than being presented as a tidy-up.

Tests

The #324 B1 suite encoded transition attribution, so it moves onto record_usage rather than living alongside it. Two cases added:

• a dispatch the graph never transitions away from — the case the old model structurally could not reach
• two dispatches of one activity stay separate rows — a merged total is precisely what hid the shortfall

The entry-transition warning test is dropped, because the case no longer exists.

Merge order

#354 → #351 → #352.

#351 updates dispatch-activity's account-every-dispatch rule to call record_usage, so this must land first or that rule names a tool the server does not have. (An earlier revision of this description said "merges in any order" — that was written before the definitions follow-up existed.)

Verification

17/17 guards, 745 tests. The site's tool-group drift guard caught record_usage being ungrouped — it sits under Trace, whose note now covers cost accounting, and site/api/tools.html is regenerated.

A closing sweep checked the changeover for residue: usageWarning is gone entirely, usageSchema has exactly its declaration and one use, and five pieces of prose that still described cost as belonging to a transition — or defined the new call by what the old one no longer does — were rewritten to state the new model directly.

Refs #346

🤖 Generated with Claude Code