feat(desktop): finish SUPER-1545 — alt-screen exemption, persist guard, hidden-webview LRU
Merged
KI
4mo ago+460+460+012345678901234567890123456789-22-22-01234567890123456789
Links
- Completes SUPER-1545 (terminal half shipped in #5751)
Summary
- Alt-screen exemption: terminal eviction never selects runtimes in the alternate screen — in-place TUIs (vim, less, agent TUIs) restore as garbled static snapshots, the worst failure mode of #5751. Exempt entries still occupy the parked count, so plain shells evict sooner in their place and the memory bound holds when possible.
- Persist guard: eviction now persists the buffer first and skips the eviction (runtime kept alive, one-shot console warning) if the write fails — previously a localStorage-quota failure would have silently destroyed scrollback.
- Hidden-webview LRU: v2 browser panes get the same policy — hidden webviews (each a full guest Chromium process) are destroyed past a cap of 3, oldest-first, and rebuilt from the pane's persisted URL on next attach.
How It Works
- The pure policy (
terminal-runtime-eviction.ts) gains an optionalisExemptpredicate: excess is computed over all parked entries, but only non-exempt ones are selectable, so eviction stops early when only exempt entries remain. The terminal registry passesbuffer.active.type === "alternate"; the browser registry reuses the same function through a small candidate adapter (visible→ container). tryPersistRuntimeState(new export fromterminal-runtime.ts) reports persist success; the sweep only disposes runtimes whose buffers are safely on disk.browserRuntimeRegistrymirrors the terminal design:lastUsedAtbumped on attach/detach, deferred one-tick sweep (so pane switches re-adopt before counting), eviction via the existingdestroy()(which also unregisters main-process handlers), restore via the existingattach(initialUrl)path.
Manual QA Checklist
Exercised live over CDP (dev app):
- Alt-screen exemption:
lessrunning in tab 0 (buffer typealternateconfirmed), cap lowered to 2, 6 other tabs cycled → TUI survives parked and occupies a cap slot; 1 recent shell kept; 5 plain shells evicted - Claude Code specifically (v2.1.214): confirmed it runs in the alternate buffer; parked under cap-2 pressure with 6 tabs cycled → survived eviction with its UI intact in the live buffer, and re-revealed pixel-perfect (screenshot-verified)
- Hidden-webview cap: 5 browser panes opened → registry holds exactly 1 visible + 3 hidden; oldest destroyed; DOM webview count matches
- Evicted browser tab re-open: new registry entry created, webview rebuilt from persisted URL, cap still held afterwards
- Persist guard: unit-covered (quota simulation isn't practical in CDP); failure path keeps the runtime alive and warns once
Testing
bun run lint,bun run typecheck— cleanbun test(full desktop suite) — 0 fail- Policy tests extended to 10 (exemption ordering, exempt-slot semantics, shortfall stop); each new behavior mutation-verified (exemption ignored, exempt-excluded-from-count, both caught). One equivalent mutant found and eliminated by simplifying the impl (
slicealready clamps; dropped a redundantMath.min).
Design Decisions
- Exempt entries occupy the parked count rather than being invisible to it: with N TUIs parked, plain shells evict more aggressively, keeping total parked ≤ cap whenever possible instead of letting TUIs raise the ceiling silently.
- Webview cap is a constant (3), not a setting: webviews are much heavier than terminals and rarer; a second knob isn't warranted until someone asks.
Known Limitations
- Navigations that happen while a webview is hidden aren't persisted (
onPersistis detached), so an evicted webview restores to its last visible URL. Same class as app-restart behavior. - Many parked alt-screen TUIs can exceed the cap (they're never evicted) — the memory bound is best-effort in that case, by design.
Infra note
This worktree's Neon dev branch had been deleted by the daily cleanup; re-provisioned (br-curly-scene-afdvq3jq) to run the CDP verification. No code impact.
Summary by cubic
Finishes SUPER-1545 by protecting TUIs and scrollback while keeping background memory bounded. Adds alt-screen exemption, a persist guard, and an LRU cap for hidden webviews, plus tighter eviction timing and cleanup.
-
New Features
- Alt-screen exemption: terminal eviction skips alternate-screen TUIs (e.g., vim, less). Exempt entries still count toward the cap so plain shells evict first.
- Persist guard: eviction now saves buffer and dims first; on persist failure the runtime is kept alive and a one-time warning is logged.
- Hidden-webview LRU: v2 browser panes keep up to 3 hidden webviews; oldest are destroyed and later rebuilt from the persisted URL, reusing
selectRuntimesToEvictinbrowserRuntimeRegistry.
-
Bug Fixes
- Eviction flushes pending output and waits for the parser to go idle before checking alt-screen state or persisting, preventing bad snapshots and wrong evictions.
- Parked TUIs that switch back to the normal buffer trigger a re-check, making them eligible for eviction again.
- Closing a terminal clears any orphaned persisted state left by earlier eviction.
- Browser panes retain
onPersistafter detach to capture late navigation completion; unregister errors are now logged; hidden-webview eviction is deferred one tick to avoid pane-switch races.
Summary by CodeRabbit
-
New Features
- Automatically limits inactive terminal and hidden browser webviews to improve resource usage.
- Preserves terminal scrollback and dimensions across eviction; re-attempts eviction when buffers change.
- Adds eviction exemptions so specific runtimes are not selected, while still counting toward capacity.
- Improves alternate-screen protection during eviction.
-
Bug Fixes
- If terminal-state persistence fails, the runtime is not released; warnings are shown only once.
- Cleans up persisted terminal state when a terminal is fully disposed.
-
Tests
- Expanded eviction and persistence coverage for terminal and browser registries.