feat(timing): book each turn's head and tail as their own buckets

[uipreliga]

#164 has merged; base is now main and this PR carries 27 commits in three waves: the head/tail buckets it opened with, then message_id (CE060), then a timing-architecture pass (CE061, close_window, TurnClock).

What and why

A turn's wall clock was only partly explained. Generation windows and tool execution were measured; the turn's head (turn start → first generation window opens) and tail (last window closes → turn end) were not, so they surfaced as Unaccounted in the evalboard. On OpenCode that was ~2.5 s per turn of CLI boot reported as unexplained time.

Both are now booked as optional TurnRecord fields, computed once at the EventCollector seam.

The head's composition genuinely differs per harness and is deliberately not decomposed. On an in-process SDK the first window already covers dispatch and TTFT, so it reads 0.0; on a subprocess harness it fuses CLI boot, provider resolution, dispatch and TTFT with no marker between them (measured on OpenCode: the process spawns in ~3 ms, its first event lands at ~3.9 s). The fields are named for the interval they measure, never for what they contain — docs/agents/HARNESS_PARITY.md records the per-harness composition.

The invariant

None means never measured; 0.0 means measured and instant. These stay distinguishable end to end, Python model → task.json → TypeScript → rendered cell (— vs 0ms). CE058 is widened to cover both new names and the TurnRecord constructor.

The identity, and the three defects that closed it

Σ generation + ∪ tool + head + tail ≈ duration_seconds. Each of these was found by measurement, not by reading:

1. The tool term must be the union, not the sum. One Pi turn overlapped a Write and a Bash by 18.4 ms and produced exactly an 18.3 ms residual.
2. The four buckets were not disjoint. Generation windows are tool-subtracted; the head and tail were not. A tool escaping every window — Antigravity force-closes an orphan at finalization, inside the tail — was counted twice. On the committed antigravity_d_orphaned_tool fixture that is −86% of wall clock, with all 72 golden tests passing.
3. claude-code did not subtract tool time from its generation windows at all. It was exempt on the premise that a tool's execution falls between two windows — but a tool's timer starts at the emission carrying its tool_use block, and one assistant turn spans several emissions, so a later emission's window runs concurrently with a tool already timing. Measured at 482 ms and 340 ms of double-count on two ~18–25 s turns. It cannot subtract while flushing (a tool from an earlier emission is still running when the next window closes), so _subtract_tool_time_from_windows runs once at finalization.

Also fixed: placeholder now() stamps (rollout rebuild, sub-agent recovery, synthesized terminal — all of which declare generation_duration_ms=None) were read as window bounds, so a Codex turn rebuilt from its rollout booked the entire turn as startup; bounds depended on list append order; a collector outliving a turn could pair this attempt's start with the last attempt's end; and the head/tail bracket is taken on main-thread messages only, since a sub-agent's generations bubble into the same stream and the spawning Agent call's own interval already spans them.

Wave 2 — message_id, and CE060

Antigravity omitted the message_id kwarg, so the field defaulted to None on every message it ever recorded. The evalboard groups assistant emissions by message_id and falls back to a wall-clock gap when either side lacks one — and that fallback cannot split a harness whose windows are contiguous, so a whole turn's generations collapsed into one timeline row. Nothing failed: the consumer sums a group, so the totals stayed right, and the golden snapshots had ratified the null on the day they were written.

The damage was not only granularity. A grouped emission is one API call to the evalboard's thinking-cost simulator, whose prompt-cache cascade is quadratic in that count, so a single-shot Antigravity run had every cascade coefficient pinned at zero.

CE060 now requires the kwarg, and derives its constructor set from each module's own coder_eval.models imports rather than a hardcoded name list — which is what catches AssistantMessage as AssistantMessageTelemetry in claude_code_agent.py, a spelling CE058 guards only by coincidence.

Wave 3 — one window helper, one clock basis

Four reducers had copy-pasted the same window arithmetic, and Pi had shipped a variant of it that measured from its own turn_start while its siblings tiled from a mark — so every inter-turn gap fell into no bucket. Nothing caught it, because the identity above is asserted on one side only.

• scripts/timing/decompose_run.py gains a two-sided gate (--max-residual-pct, --min-turn-ms, --include-crashed). It filters on the turn's own crashed flag and head/tail pair, never the record's final_status: the orchestrator preserves a crashed partial across a retry, and an execute corpus finalizes every row as NOT_GRADED, which says nothing about timing. An empty gateable set exits non-zero when a threshold was requested — a gate that passes because it measured nothing is the failure it exists to remove. Report-only on landing; nothing runs it on a schedule.
• timing.py::close_window() is now the single window implementation; codex, opencode, pi and antigravity all call it. mark is keyword-only with no default, so no reducer can open a window without stating what it tiles from. claude-code is the documented exception (it subtracts once at finalization) and carries the only # noqa: CE061.
• A reproduced 100% overstatement. Both pi and opencode cleared their tool-span list at turn/step start — after the window it feeds had already opened at the mark — so a call closing in the gap lost its span and the window published that call's execution as model time while the call's own duration_ms counted it again. Driving the real state objects: window 2 published 1000.0 ms where 500.0 is correct. It needs the non-terminal tool path, which is why the CLI's usual one-shot completed event hides it. Pi was protected from it only by not tiling, so its gen_mark and the reset move had to land in one commit, reset first.
• TurnClock gives antigravity and pi one (wall, monotonic) pair per turn. Antigravity's span was monotonic while its tool intervals were wall — the only reason its window could go negative, behind a clamp indistinguishable from a real instant generation. That branch, its debug line and _gen_mark_monotonic are deleted, not left unreachable. Pi's stamps were naive-local, so a DST transition or NTP step inside a turn landed directly in a generation window. Codex and OpenCode are deliberately not converted: their tool spans are the CLI's own epoch stamps, so converting only the bounds would put two bases inside one busy_ms subtraction. The hazard is narrowed from five harnesses to two, and the parity doc says so rather than implying it is solved.
• The clock is injected, not read from a module global. That is the phase's real blast radius: a derived stamp does not read datetime.now(), so the four existing monkeypatches would have stopped reaching the reducer and those tests would have quietly measured the real clock and passed. Verified by hand on both harnesses that deleting the injected fake now fails.
• CE061 requires any module in agents/ publishing a measured generation_duration_ms to import close_window. Its own docstring states its blind spot: it proves the helper is imported, never that a given call used it. The alias resolution CE060 already owned moved into a shared tests/lint/rules/_model_ctor.py that both rules consume.

Found in review of that wave and fixed here: a duplicate turn_end / step_finish with no intervening start republished the previous window in full — the spent start stamp sat before the mark, so close_window's backwards-clock min() reopened the next window at the previous turn's start. Reproduced at 3000 ms of generation for a 2000 ms turn. The stamp is now cleared at the flush alongside the mark and the span list.

Live verification

The first pass used tasks/hello_date, which has no concurrent tools and no sub-agents — so it never exercised the code the fixes touch, and defect 3 survived it. A second pass added a task issuing five parallel writes, five reads and two concurrent Bash calls, plus a sub-agent delegation. Five harnesses, 13 turns of which 9 carried overlapping tool calls:

harness	worst |residual|	% of wall
antigravity	0.047 ms	0.000%
claude-code	1.351 ms	0.007%
codex	0.376 ms	0.002%
opencode	0.326 ms	0.002%
pi	1.718 ms	0.012%

claude-code went from 481 ms / 2.691% → 1.4 ms / 0.007% on the same task.

Re-measured after wave 3, same task, one turn per harness, through the new gate:

harness	wall	residual	% of wall
antigravity	11.2 s	−0.025 ms	0.000%
pi	18.6 s	−0.115 ms	0.001%
opencode	22.3 s	−0.145 ms	0.001%
codex	20.0 s	−0.127 ms	0.001%
claude-code	23.6 s	+0.766 ms	0.003%

The gate exits 0 at --max-residual-pct 5 and 0.01, and 1 at 0.0001, naming each offending file and turn index — so it is armed rather than vacuously green. A separate sub-agent run reconciles to 1.833 ms on 12.6 s (0.015%) with the sub-agent's 4425.7 ms of nested generation correctly excluded; including it would drive the residual to about −35%.

Guard added

The golden corpus could catch an absence but not a double-count. The fixture clocks are now unified — codex stamped its items at a fixed 2027 epoch and opencode a month in the past, while both agents stamp now(), so a codex replay recorded a harness_startup_ms of ~126 days — and assert_timing_captured asserts the identity. The threshold is relative with an absolute floor, which is what makes it work: defect 2 read +55% of wall but only +0.175 ms.

Mutation-verified: reintroducing defect 2 fails test_antigravity_golden[d_orphaned_tool]; restoring either span reset to turn/step start turns five wave-3 tests red. 20 of 27 scenarios are identity-checked; 7 inject SDK stamps in integer milliseconds (17–900 ms of declared item time against a sub-millisecond replay), so no rebasing makes them commensurable — exempt via FICTIONAL_DURATIONS, each named with its reason.

Two of those exemptions were added here, and the trade is stated where the set is defined: codex_c_reasoning_placeholder and codex_h_no_turn_completed_crash injected no item stamps at all, so _flush_message took _ms_to_dt(None) for both window bounds — two adjacent datetime.now() reads that collide at microsecond resolution often enough to fail completed_at > started_at roughly one run in twenty under parallel load, naming a different scenario each time. Their identity check was near-vacuous anyway (a zero-width window reconciles trivially), so real bounds buy a stable bounds-span assertion.

Known and documented, not fixed

• The golden corpus pins that a timing value exists, never what it is. _scrub.py's SCRUB_KEYS masks generation_duration_ms and both bounds to a placeholder, and the one assertion that reads magnitudes is an upper bound. So the committed suite cannot see a per-harness generation number move in either direction — a whole phase of wave 3 was planned expecting the golden master to go red, and it never did. The two-sided check exists but runs by hand against live task.json. Interim cover is an ms-exact generation + ∪ tool == span test on pi and opencode. Deferred to .claude/harness-candidates.md with what closing it would take.
• claude-code's and antigravity's 0.0 head is a clamped negative, not a measured interval — their first window opens before the AgentStartEvent stamp. Measured at 0.03 ms (0.10 ms with four plugin roots), so it is the sub-millisecond skew the clamp exists for. TestClaudeHeadIsStructurallyZero pins the build cost so the reasoning can't rot silently.
• "A tool outside every generation window" has no live coverage — defect 2's fix rests on unit tests and the antigravity_d_orphaned_tool fixture.
• A genuinely backwards clock on codex or opencode can still overlap two windows. TurnClock removes it for antigravity and pi; those two keep the CLI's epoch stamps, which cannot be re-derived host-side.
• Time to first token is not measured and cannot be derived from what is recorded. The parity doc now carries the design — including the naming rule (first_delta_latency_ms, never ttft_ms, because four harnesses' windows tile so the interval fuses queueing and tool time) and that it is never a fifth bucket. No field, reducer or model change ships for it here.
• Other guards deferred to .claude/harness-candidates.md: no TypeScript counterpart to CE058, the naive/aware datetime assumption, and widening CE058/CE059 to resolve aliases the way CE060 and CE061 do.

Test plan

• make verify — 5340 passed, 2 skipped, 92.72% coverage
• make lint — 593, including the new CE060 and CE061
• make evalboard-verify — 742 tests, tsc, build (wave 1; waves 2–3 touch no evalboard/ file)
• Live: 30 hello_date runs for head/tail magnitudes, 26 runs on a concurrent-tool + sub-agent task across all five harnesses, plus a post-wave-3 re-measurement of all five through the new gate

🤖 Generated with Claude Code

[github-actions]

Claude finished @uipreliga's task in 1m 37s —— View job

---

Code Review in Progress

Todo List:

• Read .github/code_review.md for review standards
• Read CLAUDE.md for project conventions
• Review the diff (git diff origin/fix/timing-capture-and-reporting...HEAD)
• Examine changed files for cross-file consistency
• Check timing identity invariant implementation
• Verify test coverage for the new timing fields
• Complete review and provide feedback