feat(desktop): finish SUPER-1545 — alt-screen exemption, persist guard, hidden-webview LRU

Merged
KI
4mo ago
+460-22

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 optional isExempt predicate: 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 passes buffer.active.type === "alternate"; the browser registry reuses the same function through a small candidate adapter (visible → container).
  • tryPersistRuntimeState (new export from terminal-runtime.ts) reports persist success; the sweep only disposes runtimes whose buffers are safely on disk.
  • browserRuntimeRegistry mirrors the terminal design: lastUsedAt bumped on attach/detach, deferred one-tick sweep (so pane switches re-adopt before counting), eviction via the existing destroy() (which also unregisters main-process handlers), restore via the existing attach(initialUrl) path.

Manual QA Checklist

Exercised live over CDP (dev app):

  • Alt-screen exemption: less running in tab 0 (buffer type alternate confirmed), 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 — clean
  • bun 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 (slice already clamps; dropped a redundant Math.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 (onPersist is 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.


Open in Stage

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 selectRuntimesToEvict in browserRuntimeRegistry.
  • 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 onPersist after 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.