feat(web): F4 dormant terminal panes — keep the socket open, buffer instead of re-streaming (WI-128)

[thedancingdeveloper]

Eighth PR of the terminal-attach-budget initiative (WI-121). Stacked on #673 (D6); all land on feat/terminal-attach-budget.

What this does (F4 / WI-128)

Switching away from a terminal parked its socket (closed it); returning reattached and re-streamed everything produced while away (bounded by F1, but still a re-stream — the switch-away flood). F4 keeps the socket open for inactive panes and stops writing to xterm — output buffers into the in-memory ring — so returning renders the buffered delta with no reattach and no re-stream.

• terminalDormancy.ts (pure, unit-tested) — a per-document budget of MAX_DORMANT_SOCKETS (4), most-recently-active kept, the rest evicted to parking; and planDormantResume() deciding delta-write vs reset+tail on return.
• Terminal.tsx state machine — active | dormant | parked. A dormant pane has an open socket, buffers, and shows no "Suspended" banner (e.g. the unfocused half of a split keeps its screen). suspend() goes dormant if the budget allows and the pane is past its snapshot, else parks. activate() resumes a live dormant socket in place with a synchronous catch-up (flip the flag before any write, so live frames queue in order — no gap), or reconnects if the socket died while dormant (a mobile OS reclaim). Preserves the no-second-socket invariant and the cache-load initial-connect path; releases the slot on park and unmount.
• Docs — USER_GUIDE (dormant vs Suspended) and ENGINE.md (client note: dormant panes are extra broadcast subscribers, bounded).

Tests

• terminalDormancy.test.ts — budget, MRU eviction, release, and the resume plan. The shared registry is reset between tests in setup.ts.

Verification & the one gap

• pnpm typecheck clean; pnpm vitest — 947 passed (9 new); pnpm build bundles.
• ⚠️ Live acceptance still owed. The core socket-lifecycle change is unit-tested and typechecks, but the switch-away-under-load behavior (symptom 1: no reset, replay ≤ budget on return) is H3's live spec (WI-124) against a real stack — which an agent session cannot reach. Please review this against the live spec / a dev stack before merging. The plan sequences F4's acceptance on H3-live for exactly this reason.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UtEFLJAhLiq4NfZCN2vuBb

[thedancingdeveloper]

Cleanup: superseded by the single promotion PR #676. All of this work is already integrated into feat/terminal-attach-budget and is reviewable there per-commit (each commit is one initiative item with a full message). Closing to keep the initiative to one PR; the commit is preserved.