Contain xterm addon failures to terminal panes

[brennanb2025]

Summary

• Added structured breadcrumbs for contained terminal search decoration failures and WebGL attach/context-loss fallback.
• Strengthened deterministic renderer-unit coverage so injected search/WebGL failures stay addon-scoped while focus and input/write surfaces remain callable.
• Registered the xterm-addon.boundary-containment manifest command and documented the live PTY echo gap.

ELI5

Terminal panes have extra pieces bolted on for things like search, links, and graphics acceleration. If one of those pieces breaks, the whole terminal should not disappear or stop accepting input. This PR proves those add-ons can fail in a contained way while the pane still stays alive enough to focus and write to.

Why We Need This

This covers the terminal-addon failure class from the recent reliability work. Terminal panes depend on optional xterm add-ons for search, link handling, and WebGL rendering. Those add-ons are useful, but they should be allowed to degrade without crashing the terminal pane, blanking the surface, or breaking focus/input.

Product Code vs Gate Coverage

This PR includes targeted product hardening plus regression coverage. The product change contains known xterm search decoration failures and WebGL attach/context-loss failures so the terminal can fall back instead of letting an add-on failure take down the pane. The tests prove that containment behavior at the renderer-unit layer; live PTY echo coverage remains a documented follow-up gap.

Merge Order

Requires #7001 first because this PR depends on the reliability gate manifest and validator added there.

After #7001 lands, this PR can merge independently of #7005, #7006, #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: xterm search, link, WebGL, decoration, or renderer failures must stay pane/addon scoped and must not unmount the terminal surface or break focus/input/write access.
• Right layer: the risky behavior is addon failure containment, so renderer-unit tests with injected throws prove the failure boundary more directly than a flaky UI flow. A live PTY echo test remains a documented follow-up for the user-visible end-to-end path.
• Stable oracle: failures are injected deterministically into search decoration and WebGL attach/context-loss paths. The tests assert contained fallback behavior, structured breadcrumbs, and callable focus/input/write surfaces, not timing-dependent pixels.
• How we know it works: the tests fail if contained addon errors are allowed to escape, if fallback state is not set, or if the pane loses its callable terminal surface after a known addon failure.
• Why it stays useful: the gate protects the class-level boundary that optional terminal addons may degrade but cannot take the terminal pane down. The manifest keeps the remaining local/daemon/SSH/remote PTY echo proof explicit rather than hiding it behind renderer-unit success.
• Anti-flake policy: no sleeps, external services, shared state, or real GPU dependence are required. The gate remains experimental until soak history and saved red/green evidence justify promotion.

Validation

• pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/terminal-search-safe-find.test.ts src/renderer/src/lib/pane-manager/pane-lifecycle.test.ts src/renderer/src/lib/pane-manager/terminal-link-provider-guard.test.ts
• pnpm run check:reliability-gates
• pnpm exec oxlint config/reliability-gates.jsonc src/renderer/src/components/terminal-search-safe-find.ts src/renderer/src/components/terminal-search-safe-find.test.ts src/renderer/src/lib/pane-manager/pane-webgl-renderer.ts src/renderer/src/lib/pane-manager/pane-lifecycle.test.ts

Residual Risks

• The new gate proves renderer-unit containment and callable focus/input/write surfaces only; it does not model a real local, daemon, SSH, or remote-runtime PTY echo loop yet.
• Manifest maturity remains experimental pending soak history and saved red/green evidence.

Performance

• Containment records a breadcrumb and returns/falls back once; no retries, polling, or fallback loops were added.

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 3 individual chapters for you:

	Title
1	Contain terminal search decoration failures
2	Harden WebGL renderer attachment and fallback
3	Update reliability gate manifest and commands

_{Chapters generated by Stage for commit baced3b on Jul 1, 2026 10:23pm UTC.}

[brennanb2025]

Hard-review follow-up: two independent reviewers found WebGL fallback lifecycle gaps. Pushed baced3b to dispose a constructed WebGL addon when loadAddon throws, and to make auto mode fall back to DOM for later panes after WebGL context loss. Validation: focused Vitest terminal-search-safe-find/pane-lifecycle/terminal-link-provider-guard passed (36 tests), reliability gate manifest check passed, touched-file oxlint passed, and git diff --check passed.