Gate PTY delivery to hidden terminal views

[nwparker]

Summary

Phase 4 of the terminal model/view architecture: main stops sending PTY bytes to hidden terminal views entirely.

• hiddenRendererPtys gate in pty.ts: bytes for hidden views are dropped after model ingestion (never queued) — the headless model owns them and reveal reconciles via snapshot+seq; SSH relay parity in wireUpPtyEvents
• ref-counted delivery-interest registry: byte-needing sidecars (paste-draft readiness, background launches, automation observers) keep delivery automatically through their existing subscribeToPtyData registrations; the codex 10s startup query window stays exempt
• parked tabs and hidden mounted panes set/clear the hidden bit with strict ordering (unhide before restore); mode-2031 subscribes become a fact from main's tracker with the renderer replying — fixing today's post-latch subscribe drop — and ownership is structural (isHiddenDeliveryGateManagedPty: fact is the sole responder for gated panes)
• new out-of-band pty:modelRestoreNeeded IPC replaces any in-band signaling (an OSC-9999-only chunk can strip to empty — it must never masquerade as a restore marker)
• restore reconciliation hardened: main reports pendingDeliveryStartSeq with each snapshot so the renderer arms a duplicate-suppression baseline only for a real undelivered window; seq-continuity gap detection forces a fresh snapshot when the pending-cap trims behind a completed restore
• the previously-unbounded pendingData growth under ACK starvation is capped (2 MB oldest-drop + restore marker), gated on the same kill switches; switches-off is byte-identical to today
• dual kill switches: terminalMainSideEffectAuthority AND new terminalHiddenDeliveryGate (default on), read main-side

Review hardening (3-lens adversarial review + deterministic e2e regression fix, all red-verified)

• in-band marker/OSC-9999 collision eliminated (spurious visible repaints)
• post-restore backlog duplication and gap-blind drains fixed via the reported pending window + continuity detection; a follow-up e2e regression (baseline misreading foreign seq domains) was root-caused to the missing empty-backlog invariant and fixed by never arming a baseline without a real window
• 2031 fact registers the pane's mode-2031 subscription so theme flips push after reveal; reply ownership races eliminated structurally
• drop memory survives hidden remount/reload cycles (mark never clears; unmark is the sole consumer); renderer-scoped gate state resets on reload/crash

Validation

• typecheck clean; oxlint clean; 1,020+ unit tests green across the gate, connection, transport, watcher, runtime, and SSH suites (red-verified per fix)
• e2e on fresh builds: hidden TUI visual restore 4/4 (incl. the regression's solo repro), parking 3/3, parked memory 2/2, attention, sleep/wake, long-table — 12-17 per sweep; artificial-opencode hidden/cross-workspace/revisit pressure 6/6 under the new byte-free contract (hidden bytes die in main: mainHiddenDroppedChars carries the evidence, renderer queues ~0); golden 2/2
• perf annotations now expose mainHiddenGatedPtys/mainHiddenDroppedChars/mainPendingDroppedChars for the over-time report

Cut-off

Independently mergeable; completes the Phase 3–4 arc. Phase 5 (model query authority for hidden panes, design committed next) is the final behavioral phase before the skip-grammar deletion.

Made with Orca 🐋

[stage-review]

Ready to review this PR? Stage has broken it down into 16 individual chapters for you:

	Title
1	Define core types and constants for hidden delivery
2	Implement main-side hidden delivery gate logic
3	Wire hidden gate into PTY data ingestion
4	Expose gate controls and markers via IPC
5	Implement renderer-side delivery interest registry
6	Add out-of-band restore channel router
7	Surface DECSET 2031 subscriptions as facts
8	Handle 2031 facts in the renderer
9	Integrate hidden gate into parked tabs
10	Harden restore reconciliation in the connection
11	Update PTY transport and status carry handling
12	Report pending delivery window in snapshots
13	Add debug counters and reset logic
14	Update PTY tests for hidden delivery
15	Update E2E pressure and restore tests
16	Document Phase 5 query authority design

_{Chapters generated by Stage for commit f70350b on Jun 17, 2026 9:35am UTC.}

[nwparker]

Closing as superseded by merged PR #7214 (merge e84a8dd), which explicitly revived the complete term-speed-2 model/view chain into current main and then added newer scheduler, producer flow-control, snapshot, and reliability work. This old component/rollup branch no longer has an independent delta to rebase.