Stop hidden terminal panes from exhausting renderer memory (hidden-view parking, byte mode, default off)

Extracts the self-contained "hidden-view parking" slice from PR #7214
(orca-performance) as a standalone fix for the Windows renderer OOM/hang
under multi-agent load (#7175 / STA-476): long-hidden terminal panes
unmount after a 30s hysteresis while a pane-less byte watcher keeps
bell/title/agent-completion side effects alive; reveal rides the existing
tab-move reattach path.

Byte mode only: no main-process side-effect emitter ships here, so
constants.ts pins terminalMainSideEffectAuthority / terminalHiddenDeliveryGate /
terminalModelQueryAuthority to false (the single intentional divergence from
#7214, reconciled by taking #7214's values when its emitter lands). The
parking kill switch terminalHiddenViewParking also ships default-OFF
(opt-in) until the memory win is confirmed in a soak.

Co-authored-by: Jinwoo-H <jinwoo0825@gmail.com>
Co-authored-by: Orca <help@stably.ai>

docs/reference/terminal-hidden-view-parking.md

@@ -0,0 +1,118 @@
+# Terminal Hidden View Parking
+
+Status: Shipped standalone (byte mode only, extracted from PR #7214), kill
+switch `terminalHiddenViewParking` **default off** — opt-in until the memory
+win is confirmed in a soak, then a follow-up flips it on. The companion doc
+`terminal-model-view-contract.md` (invariants this design extends and the full
+phase list) ships with PR #7214 together with the fact-mode main emitter; in
+this build `terminalMainSideEffectAuthority` must stay `false` (see
+`src/shared/constants.ts`).
+
+## Problem
+
+Hidden terminal panes keep a full renderer xterm instance alive (buffer,
+scrollback, DOM, addons). At many-worktree scale this is the dominant renderer
+memory cost, and it forces every hidden byte through renderer-side write/skip
+decisions. The main-process model (daemon + runtime headless emulators) already
+ingests every byte and can serve restorable snapshots, so the renderer view for
+a long-hidden pane is redundant state.
+
+A previous attempt shipped and was reverted the same day. The post-mortem
+finding: parking unmounted the pane component, which also tore down the
+renderer's PTY byte parsers — and those parsers are the only source of bell
+notifications, title-transition agent-complete notifications, and tab titles.
+A parked worktree whose agent finished would never notify. This design keeps
+those side effects alive while parked.
+
+## Design
+
+### Park policy (renderer)
+
+A pure policy module decides which hidden terminal tabs may park:
+
+- Cold-park hysteresis: a tab must be hidden for 30s before parking.
+- Hot-retain working set: recently visible worktrees/tabs are retained
+  (5 minutes, bounded count) so quick tab switches never pay a re-hydrate.
+- Eligibility excludes: visible panes, hidden-measuring startup probes,
+  activity-portal panes, tabs with pending startup commands or pending
+  activation spawns, floating-panel tabs, and any tab whose PTY is not
+  snapshot-backed (remote-runtime `remote:` PTYs and SSH PTYs are excluded).
+- Kill switch: `settings.terminalHiddenViewParking === false` disables parking
+  entirely.
+
+### Park mechanics
+
+Parking a tab unmounts its `TerminalPane` React subtree (the overlay layer
+renders null for parked tabs). This is the same teardown that tab-group moves
+already exercise: transports detach but the PTY session, daemon model, and tab
+state all survive. The xterm instance, its buffers, DOM, and WebGL/addon
+resources are released.
+
+### Parked watcher (the piece the reverted attempt lacked)
+
+While a tab is parked, a pane-less watcher
+(`parked-terminal-byte-watcher.ts`) keeps the pane's side effects alive. Its
+consumption mode is decided once at watcher start:
+
+- **Main side-effect authority on (default):** the watcher is purely
+  fact-driven — it registers exactly one `pty:sideEffect` fact consumer and
+  parses no bytes. Titles, agent working/idle/exited transitions, BEL
+  attention, and PR links arrive as main-tracker facts and drive the same
+  policy callbacks a mounted pane uses. With the hidden-delivery gate also on,
+  the watcher marks the PTY hidden so main stops renderer byte delivery
+  entirely; the DECSET 2031 color-scheme subscribe arrives as main's
+  `2031-subscribe` fact and the watcher replies out-of-band via
+  `transport.sendInput`.
+- **Kill switch off:** the watcher subscribes to raw bytes through the
+  dispatcher sidecar mechanism (the same mechanism background agent launches
+  use) and runs the transport-level byte parsers with no xterm — OSC 0/1/2
+  titles (all-titles ordering, live-path normalization), the title-transition
+  agent tracker (completion notification, prompt-cache timer), the OSC-aware
+  stateful BEL detector, the GitHub PR link scan, and a dedicated DECSET 2031
+  byte responder (`parked-terminal-mode2031-responder.ts`, whose
+  `subscribeToPtyData` registration doubles as the delivery-interest signal).
+
+The two modes drive one shared policy-callback block, so flipping the kill
+switch never changes notification semantics. Main's synthetic
+agent-title/permission frames feed the main tracker directly and arrive as
+facts; the legacy synthetic `pty:data` copy exists only in kill-switch-off
+mode.
+
+Out of scope while parked: OSC 52 clipboard writes. Terminal queries inside
+hidden-dropped chunks are answered by main's model responder
+(`terminal-query-authority.md`, ships with PR #7214); in kill-switch-off byte
+mode only the 2031 reply is answered and Command Code output is not scraped,
+matching the pre-gate status quo.
+
+### Reveal
+
+Revealing a parked tab remounts the pane subtree and rides the existing
+reattach path: fresh xterm via `openTerminal` (unicode provider activation
+before any write), daemon model snapshot > relay replay > cold restore
+precedence, replay-guarded so snapshot-embedded queries never answer, then
+`POST_REPLAY_REATTACH_RESET` hygiene, fit, and PTY resize. The watcher is
+disposed before the pane handlers re-register.
+
+## Invariants
+
+1. PTY reads never stop; parking only changes renderer-side view lifetime.
+2. Bell, agent-completion, title, and PR-link side effects keep working while
+   parked (watcher parity tests).
+3. Reveal shows model-correct output (visual gates: hidden TUI restore, long
+   table, rendering golden) and accepts input immediately.
+4. Sleep/wake, pane close, and PTY restart while parked must not leak watchers
+   or strand parked state.
+5. Memory: parked tabs hold no xterm buffers; renderer memory scales with
+   visible panes.
+
+## Relation to later phases (all shipped)
+
+Side-effect authority in main (Phase 3) replaced the watcher's byte parsing
+with the `pty:sideEffect` fact consumer; the hidden-delivery gate (Phase 4)
+stops hidden byte delivery in main, moving the parked 2031 reply from the
+byte sidecar to the `2031-subscribe` fact; the model query responder
+(Phase 5) answers queries in hidden-dropped chunks. The watcher's byte-parser
+mode survives only behind the kill switches. Parking still excludes
+remote-runtime and SSH PTYs (no local snapshot to restore from); the watcher
+would return as a byte parser only if remote-runtime tabs — whose bytes never
+transit local main — ever became parkable.