fix(review): TUI sink must never backpressure the orchestrator

[peyton-alt]

https://entire.io/gh/entireio/cli/trails/797

During a live full-crew dogfood run (2026-07-07), the parent entire review process wedged mid-run: the TUI stopped rendering (elapsed frozen at 11m58s, spinner ticks dead), an armed --timeout 20m never surfaced, no judge ran, and the process had to be killed externally 15 minutes later.

Mechanism (proven)

Program.Send is an unbuffered blocking send, and TUISink called it directly from the orchestrator's serial dispatch goroutine. Any stall in the Bubble Tea Update/render pipeline therefore freezes, in order: sink dispatch → the bounded fanIn drain loop → the per-agent forwarding goroutines → the stdout parsers → reviewer-timeout event handling. Ticks are self-re-arming and commands run in independent goroutines, so a frozen elapsed counter is itself proof the Update loop was blocked. (The stall's own trigger was not reproduced across three targeted shim experiments — single-agent linger, multi-agent linger + burst, pre-fix tailer backlog — all of which enforced timeouts exactly; this PR closes the amplification path that turns any display stall into a full orchestrator freeze.)

Change

• TUISink gains a bounded internal queue (4096) drained by a pump goroutine — the only goroutine allowed to block on Send.
• AgentEvent never blocks: overflow is dropped and counted (droppedCount), zero drops in any healthy run.
• Control messages (RunFinished, FinalPhase*, PostRunComplete) use a bounded wait; PostRunComplete keeps its existing Kill fallback. A wedged TUI now degrades to lost frames and a stale footer instead of a hung run with an unenforced timeout.
• FIFO order preserved through the single queue; teaRunner interface extracted so tests can inject a deterministically wedged program.

Verification

• New tests: AgentEvent completes 3× the queue cap against a wedged program without blocking; control messages return within their bounded wait; a recording runner pins FIFO delivery. All -race clean.
• Full unit suite green (7,693), lint clean.

Investigation record and incident evidence: session notes from the #1666 live dogfood runs.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes the interactive review TUI event path and drops display events under extreme backlog; orchestration and timeouts should keep working but the UI may lag or miss frames when wedged.

Overview
Prevents a stalled Bubble Tea TUI from freezing the entire review run by stopping direct blocking Program.Send calls from the orchestrator's serial dispatch path.

TUISink now enqueues tea.Msg on a 4096-cap channel drained by a dedicated pump goroutine (the only place that may block on Send). AgentEvent uses a non-blocking enqueue and drops + counts overflow via droppedCount instead of backpressuring fan-in, parsers, or timeout handling. Control messages (RunFinished, final-phase updates, PostRunComplete) go through enqueueControl with a bounded wait; PostRunComplete keeps its Kill fallback without the extra goroutine around Send.

A teaRunner interface and newTUISinkWithProgram enable tests with wedged/recording fakes. New tests assert non-blocking AgentEvent under a wedged loop, FIFO delivery when healthy, and bounded RunFinished when the queue is jammed.

^{Reviewed by Cursor Bugbot for commit a91d234. Configure here.}

[Copilot]

Pull request overview

This PR hardens entire review’s interactive Bubble Tea TUI sink so UI stalls cannot backpressure (and thereby wedge) the orchestrator event pipeline, preserving timeout/judge execution even if the TUI freezes.

Changes:

• Introduces a bounded internal message queue in TUISink, with a dedicated pump goroutine as the only caller allowed to block on tea.Program.Send.
• Makes AgentEvent non-blocking by dropping overflow events and tracking a dropped-message count.
• Adds tests covering non-blocking behavior against a deterministically wedged program, FIFO delivery for a healthy program, and bounded behavior for control messages.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
cmd/entire/cli/review/tui_sink.go	Adds bounded queue + pump goroutine to prevent TUI backpressure from freezing orchestration; introduces control-message enqueue with bounded wait.
cmd/entire/cli/review/tui_sink_test.go	Adds wedge-hardening tests using injected fake teaRunner implementations (wedged + recording).

Comments suppressed due to low confidence (1)

cmd/entire/cli/review/tui_sink.go:269

• The PostRunComplete doc comment says it "waits for the Bubble Tea program to finish", but the implementation is a bounded best-effort wait: after two grace windows it returns even if s.done is still not closed. This mismatch can confuse callers/reviewers about the shutdown guarantees.

Consider updating the comment to reflect the bounded wait + Kill fallback behavior.

// PostRunComplete exits the TUI and waits for the Bubble Tea program to finish.
// Call after post-run sinks have produced any buffered output.
func (s *TUISink) PostRunComplete() {