feat(llm-reach): the checkpoint summaries publish the stage-local running usage — per attempted batch, exception-safe, the delta semantics (#603)

[gadievron]

Fixes #603.

What was wrong

The LLM-reachability checkpoint summaries omitted usage and received no batch-progress refresh — two writes per pass, at start and end, both passing usage=None (a silent omission). The tracker was already wired into the stage (the omission was caller-side). The stage-local running cost was invisible to any summary-reading consumer mid-stage: in the referenced run, the llr stage spent ~$8 over 41 minutes while any summary-derived cost sum held the app-context step's $0.03. The terminal step report retained the tracked cost — the loss was live visibility, not terminal accounting.

The fix

Publication at three points: the pass start (the prior-usage injection now precedes the write, so the first snapshot is internally consistent with completed=len(adopted) and carries the adopted spend), after every attempted batch — including the failed/dropped/unrecovered-split paths that continue past the record persistence (the billed-but-empty cases whose spend the live summary exists to show), and at termination. Publication failures (OSError) never mask the pass.

The delta semantics (the hunt's correction): the global tracker is cumulative — prior phases' spend included — so a naive totals read would double-count with the step report and the earlier phases' summaries. The published figure is current minus baseline (a get_totals() snapshot at function entry) — the step-context semantics. The terminal summary equals the step report's delta while the windows between the two snapshots (step_context's start vs this entry) stay spend-free — co-located snapshots, not one shared boundary (a future LLM call between them would need a pin; none exists today). The #216 markers (cost_incomplete/unpriced_models) and the #605 accounting-error counter survive the publication (run-cumulative, the accepted trade in step_report.py).

The count policy, stated truthfully: the per-batch refreshes are deliberately uncounted on failure — the #599 counters cover the pass-start/final writes (the persistent-failure case); a per-batch counter would fire N times for one disk-full episode and drown the loud signal.

Evidence

• RED (pristine master, this file copied in): 2 failed + 2 passed (the 4-item set — the usage-shape and the publication-count rows; the pass-completes and no-tracker rows are green-at-base controls).
• GREEN: 6/6 on the file (pytest -q tests/test_issue603_llr_summary_usage.py → 6 passed) — the exact delta pin [0, 10, 10] (the baseline's 110/55 excluded; the FakeAdapter's 10/10 response — a regression to naive cumulative totals [110, 120, 120] fails); the 4-write count for 2 batches; the site-build(deps): bump minimatch from 10.2.2 to 10.2.4 in /libs/openant-core/parsers/javascript #3 receipt — a dropped batch's PRE-CONTINUE publication pinned (3 writes; the write carries the 10/10 spend; a bare-continue regression yields 2); the injection-ordering receipt — a two-pass drive (the first pass seeds the record; the second's pass-start snapshot carries the adopted spend — a write-then-inject regression reads 0); the poisoned-publication pass-completes; the no-get_totals shape. The full suite locally: pytest -q → 2 failed, 4208 passed, 34 skipped — the 2 are test_llm_sdk_contract_floor SDK-pin host drift, identical on master; CI is the authoritative suite. Ruff clean; Semgrep 0 findings.
• The LLM-reach checkpoint summary-write failures are invisible in the scan path — and the in-progress summary write is silent even with an on_error callback #599 contract preserved: the write sequence is [pass-start, per-batch × N, final]; the failure tests key on phase == "done" (call-count drift cannot retarget the injection); the both-fail counter still counts 2 from the loud sites.

The de-balancing check (the intent trace)

serves: I-llr, I-out; de-balances-checked: the #599 counters increment at exactly the same two sites as before (the pass-start/final writes); the resume machinery's reads are per-unit records, never the summary; the phase state machine unchanged (the per-batch writes only refresh completed/incomplete mid-loop — the Go resume prompt now shows accurate progress instead of the pass-start count).

Notes for the reviewer

• The usage key is write-only inside the product (the Go Summary struct has no field; the Python resume reads per-unit records) — the audience is an operator tailing the file or external tooling, the same family parity as the analyzer/verifier/enhancer summaries.
• A consumer keying stages off the checkpoint directory name must map llm_reach_checkpoints → the completed llm-reachability step or it will double-count on resume (the issue's own caveat, carried).