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

[uipreliga]

Stacked on #164 — base is fix/timing-capture-and-reporting, whose tiling fixes are prerequisites. GitHub will retarget this to main automatically when #164 merges. Review the 11 commits here, not the 21 against main.

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; and a collector outliving a turn could pair this attempt's start with the last attempt's end.

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.

Final, all 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. Head/tail magnitudes (means of six hello_date turns per harness) are in the parity doc; reproduce any of it with scripts/timing/decompose_run.py.

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]. 22 of 27 scenarios are checked; 5 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.

Known and documented, not fixed

• 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. Moving the emit earlier would not change the number and would cost the event its effective model; 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.
• Two guards deferred to .claude/harness-candidates.md: no TypeScript counterpart to CE058, and the naive/aware datetime assumption.

Test plan

• make verify — 5246 passed, 92.71% coverage
• make evalboard-verify — 742 tests, tsc, build
• make lint — 561
• Live: 30 hello_date runs for head/tail magnitudes, plus 26 runs on a concurrent-tool + sub-agent task across all five harnesses

🤖 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