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

Terminal Hidden View Parking

Status: Shipped — Phase 1 of the terminal model/view architecture, kill switch terminalHiddenViewParking (default on). See terminal-model-view-contract.md for the invariants this design extends and the full phase list.

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); 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.