server: the live stream's cursor describes what it read, not the file

[Shashankss1205]

The build_snapshot read-then-stat race from the 2026-08 sweep. It was recorded as suspected and never demonstrated — so the first thing here is the demonstration.

The cursor

frames() polls the trace file's size, rebuilds a snapshot when it changes, and stores the snapshot's own size as "everything up to here has been sent":

last_size = snapshot.size if snapshot.size else size

build_snapshot took that number from path.stat() after reading the events. Those disagree in the direction that matters, two ways:

1. TailRecorder cuts at the last newline, so a half-written final line is excluded from the events but counted by st_size.
2. The run is appending while the snapshot is built — that is the premise of a live view — so bytes can land between the read and the stat.

Only (2) loses whole events, since the bytes (1) omits cannot parse into one yet.

Why that wedges rather than lagging

A cursor past what was read means the next poll sees an unchanged file size and rebuilds nothing. If the writer has stopped, the file never changes size again, so the stream never rebuilds and never learns the run ended.

Reproduced against the old code with a single append landing in the window:

  cursor stored : 375
  final size    : 375
  done          : False
  WEDGED (cursor == final and not done): True

That pair is the bug: frames() has no reason to rebuild and nothing left to learn from. The page shows a finished run as running for as long as it stays open.

The fix

TailRecorder.read_tail() returns the events and the byte count they came from. read_events() keeps its old signature over it, since that is what every other caller uses. build_snapshot uses the count for size and reads only the mtime from the file's current state — which is safe to be too new: it makes a run look more recently active, delaying an idle verdict by one poll rather than stopping the stream.

Because the cursor now falls short of the file, the next poll rebuilds and the missed event arrives. That is the difference between a one-poll delay and a stream that never recovers.

Tests

Nine, including the two that guard against over-correcting:

• test_a_quiet_complete_trace_reports_the_whole_file — the ordinary case, where the cursor is the file size and the stream must still settle.
• test_an_empty_or_missing_trace_is_still_a_waiting_snapshot — the URL is posted before the run starts writing.
• test_a_finished_run_stops_reporting_itself_as_running — the end-to-end symptom, asserting the wedged pair cannot occur and that the follow-up build reports done.

One correction worth recording: my first version of that last test asserted done on a bare stop phase, which is not what compose_snapshot reads — it needs a termination_reason in the state delta. The test now appends a genuine terminal event.

Verification

194 tests across the live, server, trace and replay files pass; ruff check clean; figure refreshed to 2,189 with GRAPHARC_UPDATE_FIGURES (#119's first real use). The full matrix is left to CI.

🤖 Generated with Claude Code