fix: solve #2968 — skip writes to backpressured terminal sockets

[github-actions]

Summary

• Root cause: broadcastEvent in the terminal host session continued calling socket.write() on client sockets that were already backpressured (i.e., socket.write() had previously returned false). This grew Node's internal write buffer without bound. When the socket finally drained, the massive accumulated buffer flushed to the client all at once, causing the visible freeze/catch-up stall reported in the issue — especially for high-repaint TUIs like Droid.
• Fix: Skip socket.write() for sockets already in the clientSocketsWaitingForDrain set. The terminal emulator still processes all data (preserving snapshot state), so the next TUI repaint naturally resyncs the display. When the socket drains and subprocess stdout resumes, new data flows normally without a flood of stale buffered data.
• Tests: Added two tests covering the backpressure behavior: one verifying writes are skipped during backpressure, and one verifying writes resume after drain.

Test plan

• bun test apps/desktop/src/main/terminal-host/session.test.ts — all 6 tests pass
• Manual: open Droid TUI in Superset terminal, switch tabs/workspaces, switch back — terminal should recover immediately without freeze

Closes #2968

---

Summary by cubic

Skip writes to backpressured terminal sockets to prevent buffer growth and UI freezes in high-repaint TUIs. Addresses #2968 by letting the terminal recover immediately after drain.

• Bug Fixes
  • In broadcastEvent, skip socket.write() for sockets in clientSocketsWaitingForDrain.
  • Prevents unbounded Node write buffer and catch-up stalls; emulator still processes data and next repaint resyncs.
  • Added tests for skipping during backpressure and resuming after drain.

^{Written for commit 5c7a881. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/desktop/src/main/terminal-host/session.ts">

<violation number="1" location="apps/desktop/src/main/terminal-host/session.ts:1074">
P1: The backpressure skip check drops `exit`/`error` events as well as `data`. Restrict skipping to `data` events so clients still receive terminal lifecycle/error notifications.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: The backpressure skip check drops exit/error events as well as data. Restrict skipping to data events so clients still receive terminal lifecycle/error notifications.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/desktop/src/main/terminal-host/session.ts, line 1074:

<comment>The backpressure skip check drops `exit`/`error` events as well as `data`. Restrict skipping to `data` events so clients still receive terminal lifecycle/error notifications.</comment>

<file context>
@@ -1065,10 +1065,18 @@ export class Session {
+				// buffer flush causes a visible freeze / catch-up stall (#2968).
+				// The data is still processed by the emulator, so snapshot state
+				// stays consistent and the next TUI repaint naturally resyncs.
+				if (this.clientSocketsWaitingForDrain.has(socket)) {
+					continue;
+				}
</file context>

Suggested change

	if (this.clientSocketsWaitingForDrain.has(socket)) {
	continue;
	}
	if (
	eventType === "data" &&
	this.clientSocketsWaitingForDrain.has(socket)
	) {
	continue;
	}