fix(term): writeInFlight RAF guard + scroll flash retro (v0.32.88)

[AgentA-asaf]

Summary

Consolidates the full Win10 scroll flash investigation into one clean PR on current main (v0.32.88).

Closes: #210, #215, #227 (all superseded by this)

What's in this PR

1. writeInFlight fix (termwrap.ts) — prevents concurrent RAF writes at high scrollback fill

The original Tier 3 fix (PR #208) had a race: rafPending was cleared before doTerminalWrite resolved. When terminal.write() takes >16ms (common at 1000+ buffer lines), new data arriving during that window could schedule a second RAF and fire a concurrent write — producing the same flash the Tier 3 fix was meant to prevent.

Fix: writeInFlight flag + armRaf() helper. A new RAF only fires when both rafPending and writeInFlight are false. After each write resolves, armRaf() drains any buffered data.

2. RAF timing logs (termwrap.ts) — surface regressions without grepping

Every RAF flush logs: chunks, bytes, elapsed, bufLines. Writes >8ms emit at WARN:

[fe] [raf-write] SLOW chunks=3 bytes=4200 elapsed=14.2ms bufLines=1847

Tail with: tail -f ~/.agentmux/logs/agentmux-host-v*.log | grep raf-write

3. Retro doc (docs/retros/retro-scroll-flash-win10.md) — full investigation history

Covers all three root causes, what's merged, what was tried and closed, monitoring instructions, and current status (no flash observed in v0.32.88 sessions).

Closed PRs

• fix(term): RAF write timing logs + frontend log docs (v0.32.74) #210 — logging only, superseded
• fix(term): raise default scrollback 2k→10k to eliminate Win10 scroll flash (v0.32.74) #215 — stale (diverged at v0.32.74), 40ms RAF window approach documented in retro but not carried forward
• fix: prevent concurrent RAF writes causing scroll flash at high bufLines (v0.32.84) #227 — same fix on an older base, replaced by this

No merge needed yet

Flash has not been observed in recent sessions. This PR should sit open for monitoring before merging — the retro doc documents what to watch for.

Test plan

• Run a long Claude Code session (1hr+) — confirm no flash
• Check host log for [raf-write] SLOW lines at high bufLines
• If SLOW appears at bufLines > 1500 with elapsed > 16ms — writeInFlight fix is actively needed
• If no SLOW and no flash after extended testing — safe to merge

🤖 Generated with Claude Code

[reagentx-workflow]

ReAgent Diagnostics

Field	Value
ReAgent Version	5.12.4
Project Context	CLAUDE.md loaded
Model	claude-opus-4-6
Effort	high
Ref Repos	Disabled
Merge Analysis	Clean
Review Time	25.4s
Timestamp	2026-03-26T01:43:11Z
Repository	agentmuxai/agentmux
PR	#234

---

Issues:

• package.json:3 - Missing version bump for code changes (no diff found for "version" field)
• frontend/app/view/term/termwrap.ts:337 - No .catch() on doTerminalWrite promise — if it ever rejects, writeInFlight stays true permanently and the terminal stops rendering

[reagentx-workflow]

ReAgent Diagnostics

Field	Value
ReAgent Version	5.12.4
Project Context	CLAUDE.md loaded
Model	claude-opus-4-6
Effort	high
Ref Repos	Disabled
Merge Analysis	1 regression(s) detected
Review Time	65.6s
Timestamp	2026-03-27T19:34:22Z
Repository	agentmuxai/agentmux
PR	#234

---

LGTM