fix(terminal): converge resize/fit feedback loop, add WebGL oscillation fallback

[tstapler]

Summary

Fixes an infinite fit() ↔ ResizeObserver feedback loop in the terminal UI that pegs CPU and freezes input. XtermTerminal.tsx's ResizeObserver gated fit() on a raw >1px pixel delta instead of whether FitAddon.proposeDimensions() actually proposes different integer cols/rows vs the terminal's live dimensions; useTerminalFlowControl.resize() only throttled by time, not value. A WebGL sub-pixel glyph-metric mismatch could keep both loops spinning indefinitely.

Closes backlog item fc63d55b-d6cf-4e11-af02-c76c86637c5e.

Note on base branch: this PR is opened against backup/pause-resume-fix-orig-base rather than main because this worktree's development lineage has diverged from main on this remote (a PR against main would show ~2,760 unrelated files). This is the closest live branch on origin sharing an exact, clean merge-base with this change (26 files / 4,578 insertions, matching the actual diff).

What Changed

• New pure module web-app/src/lib/terminal/resizeConvergence.ts: shouldFit, shouldSendResize, shouldAbandonWebgl + TerminalSize/ResizeEvent types.
• XtermTerminal.tsx: gates fit() on live terminal.cols/rows at both the ResizeObserver debounce path and the imperative fit() handle used by tab-visibility/viewport-change handlers (the latter closes the tab-background/resume repro path, caught during pre-mortem review). Adds an oscillation-burst detector hooked at terminal.onResize that falls back from WebGL to xterm's default DOM renderer after 3 recurrences within 2s, with an async-load race guard (cancelled flag) and a webglFallbackTrippedRef distinguishing "never loaded" from "already fell back."
• useTerminalFlowControl.ts: resize() gains value-dedup (lastSentSizeRef) independent of the existing 200ms time-throttle, plus a force bypass param for its 2 legitimate non-deduped callers (reconnect resync, manual debug resize).
• TerminalOutput.tsx / useTerminalStream.ts: thread the force param through both call sites and the intermediate hook signature.
• docs/adr/018-webgl-oscillation-fallback-to-default-renderer.md: documents the fallback decision and corrects the original ticket's "canvas renderer" wording — @xterm/addon-canvas is deprecated/incompatible with the pinned @xterm/xterm ^6.0.0; disposing WebGL falls back to xterm's default DOM renderer instead, which fully achieves the same functional goal.
• Full SDD process artifacts (requirements, research, plan, 2 review rounds, validation, pre-mortem, verification report) under project_plans/terminal-resize-fit-loop/.

Test plan

• cd web-app && npx jest --no-coverage --testPathPatterns="resizeConvergence|useTerminalFlowControl|XtermTerminalResize|TerminalOutputBug" → 65/65 passing across 4 suites, including a XtermTerminalResize.test.tsx component test exercising the real ResizeObserver/imperative-fit() wiring (not just the extracted pure functions), a StrictMode double-mount regression test, and 3 AC4 oscillation/backstop cases.
• Mutation-tested: temporarily reverted the AC2 gate, the cancelled guard, and the backstop branch logic in turn and confirmed each removal causes the corresponding test to fail.
• npx tsc --noEmit clean on all touched files; next lint shows no new warnings.
• sdd:6-verify (idiom + architecture + refactor review): 0 BLOCKER / 0 MUST FIX. Fixed 3 review-consensus items inline, including one genuine latent bug (webglFallbackTrippedRef not reset on cleanup) found only by the idiom reviewer, now regression-tested.
• Live browser verification: built and ran the real binary in an isolated instance, drove 3 real terminal sessions with headless Playwright. Observed bounded convergence (8 total resize-triggering log lines across 3 tabs in a 10s post-resize window, zero in the final 3s) and 0 console errors through a simulated tab-background/resume cycle — while this environment's software GPU reproduced a genuine live WebGL glyph-metric mismatch (8.59/8.41px, 8.27/8.00px, 8.59/8.41px), demonstrating the fix tolerates the mismatch rather than merely not encountering it. Full timeline in project_plans/terminal-resize-fit-loop/implementation/manual-verification-report.md.
• Still recommended before merge: a human pass with Chrome DevTools' Performance panel (real CPU%, real OS-level tab switch) on hardware closer to the original bug report — flagged explicitly as the fully authoritative check for this class of bug; the evidence above is strong supporting automation, not a full substitute.

🤖 Generated via the SDD pipeline (requirements → research → plan w/ 2 adversarial review rounds → validate/pre-mortem/triad review → implement → sdd:6-verify) in Claude Code.

[tstapler]

Update: addressed FAIL-verdict findings

The backlog system's automated review found 2 real issues after the initial commits, both now fixed and pushed:

1. False premise (AC1/AC6): research/features.md had incorrectly concluded no same-page tiled layout exists in this codebase. It does — PaneSplitRenderer.tsx → SessionDetail → SessionDetailView → dynamically-imported TerminalOutput → XtermTerminal, tiled as sibling flex panes. This is the actual original repro topology ("3 terminals open in a split/tiled layout... panes resize in lockstep"), not "3 separate browser tabs" as this pipeline had reframed it. Corrected requirements.md/research/features.md/plan.md with a visible ERRATA (not silently rewritten), and added a mutation-tested 5-case Jest test (XtermTerminalResize.test.tsx) proving sibling XtermTerminal instances converge independently in a tiled layout, including the discriminating case of simultaneous identical-dimension resizes.

Honest open gap: a live human/browser verification pass using the real split-pane UI (Chrome DevTools CPU trace, actual pane splits) was attempted twice by dispatched agents but did not land verifiable, substantiated results in this pipeline run. This remains the single most important follow-up before considering the fix fully verified end-to-end — see project_plans/terminal-resize-fit-loop/implementation/manual-verification-report.md's "CORRECTION" and "Updated Verdict" sections for the full honest account.

2. CRITICAL bug (found during this PR's own Gate 2 code review, not by the backlog reviewer): useTerminalFlowControl.resize()'s force=true only bypassed the value-dedup check, not the pre-existing 200ms time-throttle — so a forced resize landing within 200ms of a prior send was silently dropped, defeating the guarantee both real force callers need (reconnect-resync, manual force-resize). Fixed so force bypasses both gates; mutation-tested (regression test fails without the fix, passes with it).

Current state: 71/71 tests passing, tsc/lint clean, 0 BLOCKER/CRITICAL across 4 parallel code-review dimensions (testing, code quality, architecture, security — architecture's 1 CRITICAL finding above is now fixed). PR is MERGEABLE/CLEAN. No CI runs on this PR since all workflows in .github/workflows/ are scoped to branches: [main] and this PR targets backup/pause-resume-fix-orig-base (see PR description for why).

Recommend a human complete the live tiled-pane browser verification before merge.

[tstapler]

Update: live tiled-pane verification completed successfully

Correcting my own prior comment — the live human/browser verification I flagged as incomplete has now landed. A verification pass drove the app's real split-pane UI (each session row's "..." → "Open in new pane" action, which dispatches SPLIT_AND_ASSIGN_SESSION) to tile 3 real terminal sessions as sibling XtermTerminal panes on one page — confirmed via .xterm count = 3 and screenshots. This is the literal repro topology from the original ticket, not an approximation.

Key findings:

• Directly observed the "panes resize in lockstep" behavior the ticket describes — during pane tiling, two different panes logged Container resized at the identical millisecond, with paired Sending resize to server/Skipping fit() lines following. This same-timestamp cross-pane correlation is structurally only observable in this topology (not the separate-tabs approximation used in the first pass).
• Confirmed convergence despite it: after an explicit window resize, only 3 resize-triggering log lines fired (landing within 325ms), then complete silence for the remaining ~9.7s of the 10s observation window.
• New signal, only visible in this topology: 27 occurrences of Duplicate shortcut id churn, architecturally explained (sibling panes share one global ShortcutRegistry singleton, unlike isolated per-tab JS realms) — 0 console errors accompanied it, consistent with requirements.md's existing carve-out for this line.
• A genuine WebGL glyph-metric mismatch was reproduced live again (8.18–8.56px actual vs 8.00–8.40px expected), and convergence held despite it.

Full details in project_plans/terminal-resize-fit-loop/implementation/manual-verification-report.md's "Redone verification: same-page tiled panes" and "Overall Verdict" sections (both the tiled-panes primary topology and the separate-tabs secondary topology now show PASS).

Remaining gap, unchanged: no CPU%/DevTools-Performance-panel measurement was taken (headless environment, no DevTools UI to script against) — a human spot-check with that tooling on hardware closer to the original report remains the fully authoritative check, but is no longer blocking given the strength of the automated evidence now assembled (live tiled-pane pass + live tabs pass + mutation-tested component test, three independent lines of evidence all showing convergence).

[tstapler]

Closing — this bug is already fixed on main by #272 ("fix(web): dead-band terminal resize loop, RPC dedup, and WebGL fallback"), merged independently while this branch was in progress (its base branch turned out to be a stale snapshot of main from before that merge, which is why this PR's diff doesn't include it).

#272 covers the same ground this PR does — dead-band ResizeObserver, RPC value-dedup with force bypass + regression tests, and a WebGL mismatch tracker with renderer fallback — via an independently-derived approach (a two-consecutive-sample dead-band, its own ADR-002).

No further action needed here; the backlog item this branch addresses is resolved by #272.