Skip to content

fix(desktop): garbage-collect persisted terminal scrollback in localStorage - #6036

Merged
Kitenite merged 2 commits into
mainfrom
fix-issue
Jul 29, 2026
Merged

Kitenite merged 2 commits into
mainfrom
fix-issue

Conversation

@Kitenite

@Kitenite Kitenite commented Jul 29, 2026 •

Copy link
Copy Markdown
Member

Problem

Terminal scrollback is persisted to renderer localStorage (terminal-buffer:<id> + terminal-dims:<id>) so panes can restore across remounts and relaunches. Those entries were only deleted on an explicit terminal kill (terminalRuntimeRegistry.dispose()). Terminals that disappear any other way — PTY exit, workspace deleted, host reset, crash, org switch — leaked their snapshot forever.

Measured on a real install after ~2 months: 945 orphaned buffers / 23.7 MB, enough that Chromium's synchronous localStorage load wedged the renderer (652% CPU, 6.31 GB RSS, unresponsive AX queries).

Fix (two layers)

1. Destroyed PTY ⇒ scrollback deleted, immediately.

  • host-service tags attach errors for permanently-destroyed sessions (not found / disposed / exited) with code: "session-gone" on the existing error message (additive, version-skew safe).
  • The renderer transport tracks that signal plus live exit messages as sessionEnded, distinct from _terminated (which also covers access denials where the PTY may still be alive). The signal clears the persisted snapshot on the spot, and every persistence path — detach, release, parked eviction — clears instead of re-persisting a dead session's buffer. A successful re-attach resets the flag (session re-created under the same id).

2. Boot-time GC bounds the store no matter how a terminal dies.

  • Every persist/restore stamps the terminal in a single terminal-buffer-persisted-at index.
  • At renderer boot, before any terminal mounts, pruneExpiredTerminalState() removes: unstamped entries (all pre-existing bloat, cleaned on first launch after this ships — a one-time scrollback-restore loss), entries older than a 14-day TTL (covers deaths the renderer never observes, e.g. workspace deleted while the app is closed), and oldest entries beyond a 2M-char (~4 MB) total budget.

Pruning deliberately does not cross-reference pane layouts: v2WorkspaceLocalState is org-scoped and cache-first, so reading it for GC could delete valid buffers for evicted orgs / not-ready collections.

Relationship to #5965

Complementary, not overlapping fixes: #5965 guards the TanStack-DB localStorage collections write path against the QuotaExceededError rollback→retry loop once the store is already full, and reclaims orphaned snapshots only reactively on that quota path. This PR stops the terminal-snapshot store from growing unbounded in the first place and ties snapshot lifetime to PTY lifetime. Both touch terminal-runtime(-registry).ts, so whichever lands second needs a small rebase.

Testing

  • terminal-buffer-gc.test.ts: legacy pruning, TTL, size-budget eviction order, index hygiene, dims-only orphans, corrupt-index recovery. Core tests verified to fail when their behavior is mutated out.
  • terminal-ws-transport.test.ts: exit ⇒ sessionEnded + callback fired once; session-gone attach error ⇒ same; plain error ⇒ untouched; re-attach resets.
  • terminal-runtime-registry.test.ts: release of an ended session disposes with clear and never serializes.
  • Full terminal lib suite: 304 pass. bun run typecheck --filter=desktop --filter=@superset/host-service and bun run lint clean.

Summary by CodeRabbit

  • New Features
    • Added automatic garbage collection for persisted terminal scrollback and dimensions at desktop startup, including TTL-based pruning and a size cap.
    • Introduced persisted-state tracking so terminal history retention is updated as terminals are persisted, restored, or cleared.
  • Bug Fixes
    • Improved session-ended handling to reliably clear persisted terminal state and avoid retaining snapshots after terminal termination.
    • Enhanced persistence cleanup to remove stale entries and keep the persisted-at index consistent.
    • Improved robustness when persisted GC index data is missing or corrupted.

…torage

Persisted terminal-buffer:* entries were only deleted on an explicit
terminal kill, so terminals that disappeared any other way (workspace
deleted, host reset, crash) leaked their snapshot forever - measured at
945 entries / 23.7 MB after two months, enough to wedge the renderer on
the synchronous localStorage load.

Stamp each buffer with a last persist/restore time and prune at renderer
boot: unstamped (legacy) entries immediately, stamped entries after a
14-day TTL, and oldest-first once total buffer size exceeds a 2M-char
budget.
@ghost

ghost commented Jul 29, 2026 •

Copy link
Copy Markdown

@coderabbitai

coderabbitai Bot commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Adds renderer-side garbage collection for persisted terminal state and tracks terminal session termination across the host service, WebSocket transport, and runtime registry. Persisted snapshots receive timestamps, startup pruning removes stale or oversized entries, and ended sessions clear saved state.

Changes

Terminal state garbage collection

Layer / File(s) Summary
GC index and pruning behavior
apps/desktop/src/renderer/lib/terminal/terminal-buffer-gc.ts, apps/desktop/src/renderer/lib/terminal/terminal-buffer-gc.test.ts
Adds persisted-at indexing, expiration and capacity pruning, orphan cleanup, fail-silent storage handling, and tests for these behaviors.
Runtime persistence tracking
apps/desktop/src/renderer/lib/terminal/terminal-runtime.ts
Shares storage key constants, records persistence and restoration timestamps, and removes tracking when persisted state is cleared.
Ended-session state clearing
packages/host-service/src/terminal/terminal.ts, apps/desktop/src/renderer/lib/terminal/terminal-ws-transport.ts, apps/desktop/src/renderer/lib/terminal/terminal-runtime-registry.ts, apps/desktop/src/renderer/lib/terminal/*test.ts
Propagates session-gone and exit signals, tracks session-ended state, clears snapshots during lifecycle disposal, and validates the behavior with transport and registry tests.
Startup cleanup wiring
apps/desktop/src/renderer/index.tsx
Runs terminal state pruning before router rendering and terminal mounts.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant HostService
  participant WebSocketTransport
  participant RuntimeRegistry
  participant TerminalRuntime
  participant LocalStorage
  HostService->>WebSocketTransport: send session-gone error
  WebSocketTransport->>RuntimeRegistry: invoke onSessionEnded
  RuntimeRegistry->>TerminalRuntime: clear persisted runtime state
  TerminalRuntime->>LocalStorage: remove terminal buffer, dims, and persisted-at entry
Loading

Possibly related PRs

Suggested reviewers: saddlepaddle

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title is conventional, concise, and accurately summarizes the main change: pruning persisted terminal scrollback in localStorage.
Description check ✅ Passed The description is detailed and covers the problem, fix, related work, and testing, though it doesn't follow the template headings exactly.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix-issue

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/desktop/src/renderer/lib/terminal/terminal-buffer-gc.test.ts`:
- Around line 98-107: Update the “drops index rows whose storage keys are gone”
test to delete the ghost terminal’s dimensions key from the fake storage before
calling pruneExpiredTerminalState, while preserving the existing removal of its
buffer key and the expected index assertion.

In `@apps/desktop/src/renderer/lib/terminal/terminal-runtime.ts`:
- Around line 115-119: Update the persisted-buffer check in the terminal
restoration flow to test explicitly for null rather than truthiness, so an
existing empty string is restored and touchTerminalStatePersistedAt is called.
Preserve the current behavior for a missing localStorage entry.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fb8fa01f-93bd-438c-962c-31a7545d360b

📥 Commits

Reviewing files that changed from the base of the PR and between 044b8ab and 1707f3f.

📒 Files selected for processing (4)
  • apps/desktop/src/renderer/index.tsx
  • apps/desktop/src/renderer/lib/terminal/terminal-buffer-gc.test.ts
  • apps/desktop/src/renderer/lib/terminal/terminal-buffer-gc.ts
  • apps/desktop/src/renderer/lib/terminal/terminal-runtime.ts

Comment on lines +98 to +107
test("drops index rows whose storage keys are gone", () => {
const { values, storage } = createFakeStorage();
seedTerminal(values, "live");
touchTerminalStatePersistedAt("live", storage, NOW);
touchTerminalStatePersistedAt("ghost", storage, NOW);
values.delete(`${TERMINAL_BUFFER_KEY_PREFIX}ghost`);

pruneExpiredTerminalState(storage, NOW);

expect(Object.keys(readIndex(values))).toEqual(["live"]);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Delete the remaining dimensions key before asserting index cleanup.

Line 103 leaves terminal-dims:ghost present, so GC correctly retains the fresh ghost index row and the assertion at Line 107 fails.

Proposed fix
 		touchTerminalStatePersistedAt("live", storage, NOW);
 		touchTerminalStatePersistedAt("ghost", storage, NOW);
 		values.delete(`${TERMINAL_BUFFER_KEY_PREFIX}ghost`);
+		values.delete(`${TERMINAL_DIMS_KEY_PREFIX}ghost`);
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
test("drops index rows whose storage keys are gone", () => {
const { values, storage } = createFakeStorage();
seedTerminal(values, "live");
touchTerminalStatePersistedAt("live", storage, NOW);
touchTerminalStatePersistedAt("ghost", storage, NOW);
values.delete(`${TERMINAL_BUFFER_KEY_PREFIX}ghost`);
pruneExpiredTerminalState(storage, NOW);
expect(Object.keys(readIndex(values))).toEqual(["live"]);
test("drops index rows whose storage keys are gone", () => {
const { values, storage } = createFakeStorage();
seedTerminal(values, "live");
touchTerminalStatePersistedAt("live", storage, NOW);
touchTerminalStatePersistedAt("ghost", storage, NOW);
values.delete(`${TERMINAL_BUFFER_KEY_PREFIX}ghost`);
values.delete(`${TERMINAL_DIMS_KEY_PREFIX}ghost`);
pruneExpiredTerminalState(storage, NOW);
expect(Object.keys(readIndex(values))).toEqual(["live"]);
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/desktop/src/renderer/lib/terminal/terminal-buffer-gc.test.ts` around
lines 98 - 107, Update the “drops index rows whose storage keys are gone” test
to delete the ghost terminal’s dimensions key from the fake storage before
calling pruneExpiredTerminalState, while preserving the existing removal of its
buffer key and the expected index assertion.

Comment on lines +115 to +119
if (data) {
terminal.write(data);
// Restored-but-never-detached terminals must stay fresh for boot GC.
touchTerminalStatePersistedAt(terminalId);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Treat an empty persisted buffer as present.

localStorage.getItem() returns "" for an existing empty snapshot. The truthiness check skips restoration/timestamp refresh, so that active state can expire after 14 days. Check explicitly for null.

Proposed fix
-		if (data) {
+		if (data !== null) {
 			terminal.write(data);
 			// Restored-but-never-detached terminals must stay fresh for boot GC.
 			touchTerminalStatePersistedAt(terminalId);
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
if (data) {
terminal.write(data);
// Restored-but-never-detached terminals must stay fresh for boot GC.
touchTerminalStatePersistedAt(terminalId);
}
if (data !== null) {
terminal.write(data);
// Restored-but-never-detached terminals must stay fresh for boot GC.
touchTerminalStatePersistedAt(terminalId);
}
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/desktop/src/renderer/lib/terminal/terminal-runtime.ts` around lines 115
- 119, Update the persisted-buffer check in the terminal restoration flow to
test explicitly for null rather than truthiness, so an existing empty string is
restored and touchTerminalStatePersistedAt is called. Preserve the current
behavior for a missing localStorage entry.

The server now tags attach errors for permanently-destroyed sessions
(not found / disposed / exited) with code: "session-gone". The renderer
transport tracks that signal plus live exit messages as sessionEnded,
clears the persisted snapshot immediately, and every persistence path
(detach, release, parked eviction) clears instead of re-persisting a
dead session's buffer.
@github-actions

github-actions Bot commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

  • ✅ Neon database branch

Thank you for your contribution! 🎉

@Kitenite

Copy link
Copy Markdown
Member Author

CDP before/after verification (dev app, this worktree)

Drove the real dev instance (fix-issue worktree Electron, Vite :8025, CDP :9557, owner pid verified) with real host-service PTY sessions. Renderer-only A/B via git checkout 044b8ab07 -- <renderer files> ↔ checkout HEAD -- + reload, same script both sides.

Check Before (base 044b8ab07) After (this PR)
Reload with 200 orphaned terminal-buffer:* keys seeded (19.1 MB, mirroring the real 945/23.7 MB report) all 200 survive reload, 19.1 MB retained, GC module never loaded 0 remain, 0.0 MB after one reload
Real shell: echo marker → exit → pane detach dead session's buffer + dims persisted (orphan created) nothing persisted; dead session's state also swept at next boot
Negative control: live shell, output, detach without exit, then reload n/a buffer persisted, stamped, survived boot GC with marker content intact

Method notes: terminals were driven through the real registry/transport (mount → connect (real WS to host-service) → writeInput → detach) into an offscreen container — the exact calls the pane lifecycle makes — rather than via UI clicks; orphan bloat was seeded as raw keys (identical to what real orphans are). Assertions are localStorage-state measurements over CDP Runtime.evaluate, not screenshots, since the fix is storage-lifecycle, not visual. Test sessions killed and all seeded state removed afterwards.

This branch was previously deployed

1 inactive deployment
preview — 67df6f63 Deployed Jul 29, 2026 by Kitenite via Deploy Web #6923
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant