Fix TUI agent-pane live-stream TOCTOU race (BUG-075)

[anutron]

Summary

Follow-up in the same investigation as #912 (BUG-073) and #913 (BUG-074). After both shipped, garbling frequency dropped from constant to rare — but one report didn't fit the "known deferred row-margin gap" explanation I initially reached for: a duplicated recent sentence + a few dropped characters + an old stale label, appearing in a coordinator pane that was actively being watched and streaming, with no pane switch, no resize, and no bind event involved at all. The coordinator pushed back on my first (too-quick) explanation and asked me to actually re-investigate rather than stretch the deferred-gap story to cover it. That re-investigation found a genuinely distinct, previously-unidentified bug.

Root cause

TerminalPane.renderLive's incremental-feed path read totalWritten via sess.TotalWritten() at the top of the function, then later read raw via a separate sess.RecentOutput() call, several lines down. readLoop is a live, independent goroutine — for an actively streaming session, new bytes can land in the ring in the gap between those two unsynchronized calls, so raw (sampled later) can be longer than the earlier totalWritten accounts for.

The feed line, raw[len(raw)-int(newBytes):], slices against that stale newBytes — which now misaligns with what raw actually contains. The result: it silently skips the true next bytes (a few dropped characters — e.g. "Independent" renders as "Indepe dent") and instead feeds bytes from further ahead, while emuFedTotal gets recorded short of what was actually fed. The very next frame then re-feeds that same already-fed tail — a duplicated recent phrase. Both artifacts land together, which is exactly the reported signature, and required no bind/resize event at all — a plain TOCTOU race in the steady-state live-feed path, not a reconstruction-from-history problem like BUG-068/073/074.

Notably, agent.Session.RecentOutputTailWithTotal's own doc comment already named this exact hazard — it was built for the /output HTTP endpoint's cursor for precisely this reason. renderLive's live-feed path just hadn't been updated to use it.

Fix

Fetch (raw, totalWritten) together via one sess.RecentOutputTailWithTotal(256*1024) call and recompute newBytes from that same snapshot — but only when !emuMissing. The emuMissing (fresh-attach) branch is unconditionally a full replay regardless of raw/newBytes (short-circuited by the ||) and calls readLiveRebuildHistory, which does its own independent ring read — fetching here too would just be a wasted extra 256KB copy on every fresh attach.

Test plan

• TestRenderLive_LiveFeedUsesAtomicSnapshotNotStaleTotal — new raceAdapter mock whose TotalWritten() always reports an earlier snapshot than RecentOutputTailWithTotal(), simulating readLoop advancing in between. Verified it fails on the pre-fix code with exactly the predicted garble ("HELLOLD " instead of "HELLOWORLD" — the wrong 2-byte tail fed, "WOR" dropped) before restoring the fix.
• Updated countingAdapter/TestTerminalPane_RenderLiveSkipsCopyWhenIdle/TestTerminalPane_PaintCacheReplay to instrument RecentOutputTailWithTotal (the method the live-feed path now actually calls) instead of RecentOutput — confirms the "skip the expensive copy when nothing changed" invariant still holds, and that the fix doesn't introduce a redundant copy on fresh attach.
• go test ./internal/tui/... -race -count=1 green.
• make pre-pr — build/vet/fmt-check/lint-pr/test-cover-gate clean. vuln fails only on pre-existing stdlib CVEs (CI continue-on-error). 2 pre-existing internal/agent profile-env tests fail only due to this hera-worker sandbox's own ARGUS_* env leaking into the test subprocess — unrelated to this diff.
• context/knowledge/gotchas/pty-terminal.md updated (BUG-075).

🤖 Generated with Claude Code

Co-authored-by: Claude noreply@anthropic.com

[github-actions]

Merging this branch will not change overall coverage

Impacted Packages	Coverage Δ	🤖
github.com/drn/argus/internal/tui/terminal	95.88% (+0.00%)	👍

---

Coverage by file

Changed files (no unit tests)

Changed File	Coverage Δ	Total	Covered	Missed	🤖
github.com/drn/argus/internal/tui/terminal/terminalpane.go	96.05% (+0.00%)	811 (+1)	779 (+1)	32	👍

Please note that the "Total", "Covered", and "Missed" counts above refer to code statements instead of lines of code. The value in brackets refers to the test coverage of that file in the old version of the code.

Changed unit test files

• github.com/drn/argus/internal/tui/terminal/terminalpane_test.go