Prove visible terminal size convergence

[brennanb2025]

Summary

• Adds a deterministic renderer-unit oracle for terminal-geometry.visible-convergence at the post-spawn PTY size reconcile layer.
• Covers first 0x0 visible measurement, delayed hidden-to-visible layout settle, and requested-size versus provider-applied-size drift when a resize application is dropped.
• Updates the reliability gate manifest with the focused command, test files, perf note, and explicit live-shell/provider-contract gaps.

ELI5

A terminal needs to agree on its size in several places: what the UI thinks, what the terminal renderer thinks, what the PTY thinks, and what the shell sees. When those disagree, users get blank panes, wrapped text, or broken splits. This PR adds a deterministic test for the size-recovery logic so visible terminals keep trying in bounded steps until the important sizes line up.

Why We Need This

This covers the visible terminal-size convergence class. Blank panes, broken wrapping, and split-layout failures can happen when xterm, fit/proposed size, provider-applied PTY size, and the visible layout disagree, especially after 0x0 measurements or hidden-to-visible transitions.

Product Code vs Gate Coverage

This PR is gate coverage, not terminal sizing restructuring. It adds deterministic renderer-unit tests for the existing post-spawn PTY size reconciliation layer and records the remaining live-shell/provider-contract gaps in the manifest. The gate proves convergence attempts are bounded and do not rely on blind sleeps.

Merge Order

Requires #7001 first because this PR updates the reliability gate manifest introduced there.

After #7001 lands, this PR can merge independently of #7004, #7005, #7007, and #7008. No other child PR must merge before this one. Later child PRs may need a normal manifest rebase if this one lands first.

Why These Tests Stay Useful

• Invariant protected: visible terminal size must converge across xterm size, fit/proposed size, requested PTY size, and provider-applied size, or stop in a bounded degraded state instead of looping forever.
• Right layer: the first gate targets the post-spawn size-reconcile decision layer, where the 0x0, hidden-to-visible, and dropped-applied-size cases can be made deterministic. A real shell stty/echo-wrap test remains a follow-up provider-contract or Electron gate.
• Stable oracle: the test uses controlled measurements, controlled provider applied-size state, and a controlled frame scheduler. It waits on explicit reconcile steps rather than wall-clock sleeps or browser rendering luck.
• How we know it works: removing the bounded retry/convergence behavior, trusting the first 0x0 measurement, or ignoring provider-applied-size drift makes the focused tests fail. With the gate intact, convergence happens within the asserted frame/call budget.
• Why it stays useful: the test encodes the durable contract reviewers care about: visible terminals cannot blindly trust stale or zero geometry, and recovery work must remain bounded. The manifest keeps live-shell, remote-runtime, and provider readback gaps explicit.
• Anti-flake policy: the oracle counts resize/reconcile work and final state under a deterministic scheduler. The gate remains experimental until soak history, runtime evidence, and provider/Electron follow-up coverage justify promotion.

Validation

• pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/terminal-pane/terminal-geometry-visible-convergence.test.ts src/renderer/src/components/terminal-pane/pty-size-reconcile.test.ts src/renderer/src/components/terminal-pane/split-right-white-screen.test.ts
• pnpm run check:reliability-gates
• Pre-commit oxlint, oxlint react-doctor config, and oxfmt on staged TypeScript

Residual risks

• This first harness is renderer-unit coverage; it does not execute a real shell, so stty size and echo-wrap behavior remain follow-up provider-contract/Electron coverage.
• Providers without applied-size readback, including the remote-runtime seam, are documented as unconfirmed at this layer.
• Manifest maturity remains experimental until soak/red-green evidence exists.

Performance note

• The oracle uses a controlled frame scheduler with no sleeps, asserts convergence stops before the hard frame cap, and keeps resize calls bounded so hidden/parked paths do not add redundant SIGWINCH or frame loops.

Made with Orca 🐋

---

Post-PR Stabilization

• CI checks pass after the post-PR wait.
• PR comments and review-comment surfaces were checked; no actionable automated review comments remain.

[stage-review]

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

	Title
1	Implement deterministic renderer-unit convergence oracle
2	Update reliability gate manifest for terminal convergence

_{Chapters generated by Stage for commit 9344a04 on Jul 1, 2026 8:23am UTC.}