Skip to content

perf(desktop): evict parked terminal runtimes past a configurable cap - #5751

Merged
Kitenite merged 8 commits into
mainfrom
superset-memory-worker-op
Jul 17, 2026
Merged

Kitenite merged 8 commits into
mainfrom
superset-memory-worker-op

Conversation

@Kitenite

@Kitenite Kitenite commented Jul 17, 2026 •

Copy link
Copy Markdown
Member

Links

  • Part of SUPER-1545 (terminal half; parked-webview half deferred)
  • Findings doc: apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md (added in this PR)

Summary

  • Parked (hidden) terminals were never disposed — every one kept its 5,000-line buffer, WebGL context, and WebSocket alive with no cap, which is the largest renderer memory leak-by-retention we have (CDP-measured: 18 terminals → 1.59 GB renderer RSS).
  • The registry now LRU-evicts parked runtimes past a cap: buffer serialized to localStorage first, PTY untouched, rebuilt from the persisted buffer on next mount.
  • The cap is user-configurable (Settings → Terminal → "Background terminal memory", 2–64, default 12) and applies live — lowering it sweeps immediately.

Why / Context

Full investigation + measurements in apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md. Controlled A/Bs (identical scripted CDP protocol, fresh launch per build, measured at cap 5):

18 terminals, 5k lines each Before After
Live runtimes / WebGL contexts 17 6
JS heap 658 MB 381 MB
Renderer RSS 1,655 MB 1,139 MB
Tab-switch p50 59 ms 76 ms
24 terminals with live streaming processes Before After
Live runtimes 23 6
JS heap (steady state) 836→846 MB climbing 373→376 MB flat
Renderer RSS 1,741 MB 1,165 MB
Renderer CPU (30 s cputime delta) 30 % 21 %

The CPU gap is structural: eviction closes released terminals' WebSockets, so their streams are neither delivered nor parsed. Savings scale with how far usage exceeds the cap; at the shipped default of 12, users under a dozen background terminals never see eviction.

How It Works

  • RegistryEntry.lastUsedAt (monotonic counter) is bumped on mount/detach; a deferred (one-tick) sweep after each detach releases the least-recently-used parked runtimes past the cap. The deferral matters: a workspace switch detaches outgoing panes before mounting incoming ones, so an immediate sweep could evict a terminal about to be re-adopted.
  • Eviction is disposeEntry({clearPersistedState:false}) — same as release(): serialize 1,000 lines to localStorage, close the socket, dispose xterm/WebGL. The PTY and host-side replay buffer are untouched; re-opening the tab rebuilds from localStorage and reconnects (the existing cold-restore path, incl. the "Session Contents Restored" divider).
  • Attached (visible) terminals are never candidates; runtime-less entries (transport-only) are skipped.
  • Cap plumbing: terminal_parked_runtime_cap on the local-db settings row (migration 0042, generated with drizzle-kit), zod-clamped get/set procedures, seeded into the registry by the authenticated layout at boot, and applied optimistically (with rollback) by the settings UI.

Manual QA Checklist

All exercised live over CDP against the dev app (see doc for full protocol):

  • Cap enforced: cycling 18 tabs leaves cap+1 live runtimes; zero WebGL context loss
  • Evicted terminal re-open: runtime rebuilt, 1,000-line scrollback restored (verified against content written in a previous app session), WS reconnects to the live PTY
  • Streaming processes in evicted terminals keep running host-side and resume display on re-open
  • Default 12 seeds from settings at boot; changing the setting applies immediately (12→6 swept live) and persists across restart
  • Input validation: out-of-range values (999) rejected server-side and revert on blur client-side; unchanged values don't mutate
  • Settings UI renders in Settings → Terminal; discoverable via settings search ("memory", "ram", "parked")
  • Migration 0042 applied cleanly on the existing dev DB

Testing

  • bun run lint, bun run typecheck — clean
  • Two controlled CDP A/B stress runs (18-terminal fill; 24-terminal live-stream) — tables above

Design Decisions

  • Parked-count cap, not total-live cap: visible terminals can never be evicted, so capping parked instances is the only enforceable invariant (a 6-way split stays fully live).
  • Number input over dropdown: matches FontSettingSection blur-commit pattern and exposes the full validated range; backend validation (2–64) is intentionally wider than any UI presets so the control can change without schema churn.
  • Deferred sweep over immediate: see How It Works — avoids evict/rebuild churn during workspace switches.

Known Limitations

  • Evicted terminals lose scrollback beyond 1,000 lines (serialize window). Deliberate trade-off; the cap default (12) keeps most users out of eviction entirely.
  • In-place TUIs (vim, htop, agent TUIs) restore as a static snapshot — same behavior as today's app-restart cold restore, but eviction can trigger it mid-session for users past the cap.
  • Restore replays localStorage + the host's 64 KB ring; the overlapping tail matches existing cold-restore behavior.
  • terminal_warm_attached/terminal_cold_restored telemetry will shift slightly (evictions produce cold-restore-shaped attaches).

Follow-ups

  • Parked-<webview> eviction (second half of SUPER-1545)
  • Alt-screen exemption (skip evicting terminals with an active TUI; host ModeTracker knows)
  • Persist-failure guard: skip eviction if the localStorage write fails (quota)

Open in Stage

Summary by cubic

Evicts least‑recently‑used parked terminal runtimes past a configurable cap to cut renderer memory and GPU context usage, delivering ~30–40% lower renderer RSS in stress tests (terminal half of SUPER‑1545). Also adds a live-applied setting (default 12) and fixes formatting in ai-workspace-names.ts to satisfy Biome.

  • New Features

    • LRU-evict parked terminal runtimes past a cap; on eviction we persist 1,000 lines to localStorage, close the socket, and dispose xterm/WebGL; the PTY keeps running and the runtime rebuilds on reopen.
    • New setting: Settings → Terminal → “Background terminal memory” (2–64, default 12); applies instantly; attached terminals are never evicted; sweeps are deferred one tick to avoid workspace-switch churn.
    • Settings search entry added; findings doc at apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md. Extracted a pure eviction-selection policy for isolated unit tests.
  • Migration

    • Adds terminal_parked_runtime_cap to the local DB (migration 0042); clamped to 2–64 and seeded into the registry at boot.

Written for commit 68887e4. Summary will update on new commits.

Review in cubic

Summary by CodeRabbit

  • New Features
    • Added a Terminal Settings option to cap retained inactive (“parked”) background terminals.
    • The setting is persisted, loaded into the terminal runtime registry, and applied to evict excess parked terminals using an LRU-style policy while preserving saved scrollback.
  • Documentation
    • Added “Memory Profile & Worker Offload Review,” including measured behavior and recommendations for terminal and worker/memory usage.
  • Tests
    • Added unit tests covering parked-terminal eviction selection and parked-cap normalization/validation.

Kitenite added 3 commits July 17, 2026 16:00
Parked xterm instances were kept alive forever (5,000-line buffer + WebGL
context each, no cap). Track recency on mount/detach and release the
least-recently-used parked runtimes past the cap: buffer serialized to
localStorage first, PTY untouched, rebuilt on next mount. Eviction is
deferred one tick so workspace switches re-adopt before the sweep counts.
Settings > Terminal > "Background terminal memory": number input (2-64,
default 12, blur-commit like FontSettingSection). Stored on the local-db
settings row (migration 0042), seeded into the registry at boot, applied
live on change so lowering the cap reclaims memory immediately.
CDP-verified findings across renderer/main/host-service/pty-daemon,
controlled A/Bs for the parked-terminal eviction, and the ranked
recommendation backlog (SUPER-1544..1550).
@ghost

ghost commented Jul 17, 2026 •

Copy link
Copy Markdown

Ready to review this PR? Stage has broken it down into 7 individual chapters for you:

Title
1 Document memory investigation and findings
2 Define terminal eviction constants and schema
3 Implement LRU eviction logic and tests
4 Integrate eviction into terminal registry
5 Expose terminal cap via tRPC settings
6 Wire settings to UI and boot
7 Miscellaneous cleanup
Open in Stage

Chapters generated by Stage for commit 68887e4 on Jul 17, 2026 11:50pm UTC.

@coderabbitai

coderabbitai Bot commented Jul 17, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The PR adds a persisted terminal parked-runtime cap with validated settings APIs, renderer-side LRU eviction, runtime initialization, and a terminal settings control. It also adds a memory and worker audit and simplifies host-service command construction.

Changes

Memory and worker audit

Layer / File(s) Summary
Measured memory and architecture findings
apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md
Documents memory measurements, parked-terminal retention, renderer worker scope, Electron main behavior, and host-service bottlenecks.
Offload and telemetry recommendations
apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md
Defines recommendations for terminal eviction, worker offload, collection growth control, process probes, search, telemetry, and excluded worker candidates.

Parked terminal runtime cap

Layer / File(s) Summary
Persisted cap contract
apps/desktop/src/shared/constants.ts, packages/local-db/src/schema/schema.ts, packages/local-db/drizzle/0042_overconfident_cloak.sql, packages/local-db/drizzle/meta/*
Adds default and boundary constants and persists terminalParkedRuntimeCap in the settings schema and migration metadata.
Settings API and runtime eviction
apps/desktop/src/lib/trpc/routers/settings/index.ts, apps/desktop/src/renderer/lib/terminal/terminal-runtime-eviction.ts, apps/desktop/src/renderer/lib/terminal/terminal-runtime-registry.ts, apps/desktop/src/renderer/routes/_authenticated/layout.tsx
Adds validated get/set procedures, initializes the registry cap, tracks runtime use order, and evicts least-recently-used parked runtimes while preserving persisted state.
Terminal settings control
apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/*, apps/desktop/src/renderer/routes/_authenticated/settings/utils/settings-search/settings-search.ts
Adds the v2 background-terminal setting entry and a numeric editor with validation, optimistic updates, rollback, and query invalidation.
Eviction behavior validation
apps/desktop/src/renderer/lib/terminal/terminal-runtime-eviction.test.ts
Tests cap normalization and selection of the oldest eligible parked runtimes.

Command construction cleanup

Layer / File(s) Summary
Non-interactive command assembly
packages/host-service/src/trpc/router/workspace-creation/utils/ai-workspace-names.ts
Rewrites command-string construction as a single expression while preserving the assembled command contents.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant BackgroundTerminalsSetting
  participant SettingsTRPC
  participant SettingsDatabase
  participant terminalRuntimeRegistry
  BackgroundTerminalsSetting->>SettingsTRPC: Get or set parked runtime cap
  SettingsTRPC->>SettingsDatabase: Read or upsert persisted cap
  SettingsTRPC-->>BackgroundTerminalsSetting: Return cap
  BackgroundTerminalsSetting->>terminalRuntimeRegistry: Apply cap
  terminalRuntimeRegistry->>terminalRuntimeRegistry: Evict excess parked runtimes by LRU order
Loading
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% 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 clearly summarizes the main change: configurable eviction of parked terminal runtimes.
Description check ✅ Passed The description is detailed and covers the change, rationale, testing, checklist, and follow-ups, though it doesn't use the template headings exactly.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch superset-memory-worker-op

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: 4

🤖 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/docs/MEMORY_AND_WORKERS_REVIEW.md`:
- Line 97: Update the “Effect” statement to match the supplied 18-terminal
measurements, reporting renderer RSS reduction from 1,655 MB to 1,139 MB. Remove
the unsupported extrapolation that a 20-terminal session reaches roughly 500–600
MB, unless a separately documented 20-terminal run and its conditions are added.
- Line 72: Clarify the collection-count statement in
MEMORY_AND_WORKERS_REVIEW.md: explicitly identify that the 30 total includes the
shared organizations collection, and state that preloadCollections preloads only
the remaining 29 org-scoped collections while excluding organizations.
- Line 54: Correct the throughput description in the live-stream workload
paragraph: replace the inaccurate per-process and aggregate rates with
approximately 1.5 KB/s per PTY process and 35 KB/s across 24 processes, while
preserving the command, throttling context, and CPU measurement details.

In
`@apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx`:
- Line 12: Move the BackgroundTerminalsSetting component into a dedicated
BackgroundTerminalsSetting directory, retaining the component implementation in
BackgroundTerminalsSetting.tsx and adding an index.ts barrel export. Update
imports and exports that reference BackgroundTerminalsSetting to use the new
barrel path.
🪄 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

Run ID: 21d7d319-5d51-47ac-97b3-31304ac12cf8

📥 Commits

Reviewing files that changed from the base of the PR and between 7a4e275 and b978576.

📒 Files selected for processing (12)
  • apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md
  • apps/desktop/src/lib/trpc/routers/settings/index.ts
  • apps/desktop/src/renderer/lib/terminal/terminal-runtime-registry.ts
  • apps/desktop/src/renderer/routes/_authenticated/layout.tsx
  • apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/TerminalSettings.tsx
  • apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx
  • apps/desktop/src/renderer/routes/_authenticated/settings/utils/settings-search/settings-search.ts
  • apps/desktop/src/shared/constants.ts
  • packages/local-db/drizzle/0042_overconfident_cloak.sql
  • packages/local-db/drizzle/meta/0042_snapshot.json
  • packages/local-db/drizzle/meta/_journal.json
  • packages/local-db/src/schema/schema.ts


### Heavy A/B — 24 terminals with live streaming processes

Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY process streaming continuously (`while true; do seq 1 100; sleep 0.2; done`, ~40 KB/s each; throttled deliberately — a full-rate flood kills the shared daemon socket per the SUPER-1544 plan's finding, which would invalidate the comparison). CPU is a 30 s `cputime` delta during steady state.

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 | 🟠 Major | ⚡ Quick win

Correct the live-stream throughput claim.

seq 1 100; sleep 0.2 produces roughly 292 bytes every 200 ms, or about 1.5 KB/s per process and 35 KB/s across 24 processes, not 40 KB/s per process. This materially changes the described load profile.

Suggested wording
-(`while true; do seq 1 100; sleep 0.2; done`, ~40 KB/s each;
+(`while true; do seq 1 100; sleep 0.2; done`, ~1.5 KB/s each;
📝 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
Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY process streaming continuously (`while true; do seq 1 100; sleep 0.2; done`, ~40 KB/s each; throttled deliberately — a full-rate flood kills the shared daemon socket per the SUPER-1544 plan's finding, which would invalidate the comparison). CPU is a 30 s `cputime` delta during steady state.
Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY process streaming continuously (`while true; do seq 1 100; sleep 0.2; done`, ~1.5 KB/s each; throttled deliberately — a full-rate flood kills the shared daemon socket per the SUPER-1544 plan's finding, which would invalidate the comparison). CPU is a 30 s `cputime` delta during steady state.
🤖 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/docs/MEMORY_AND_WORKERS_REVIEW.md` at line 54, Correct the
throughput description in the live-stream workload paragraph: replace the
inaccurate per-process and aggregate rates with approximately 1.5 KB/s per PTY
process and 35 KB/s across 24 processes, while preserving the command,
throttling context, and CPU measurement details.

- **Parked terminals are never disposed** (CDP). On workspace/tab switch the xterm wrapper reparents into a `position:fixed; left:-9999px` container under `<body>`; buffer (5,048 lines retained), addons, WebSocket, and **live WebGL context** all survive. `terminal-runtime-registry.ts`, `terminal-parking.ts`, detach-only unmount in `TerminalPane.tsx:162`.
- **No instance cap** (CDP): 18 terminals → 18 registry entries, 18 live WebGL contexts, zero evictions, zero GPU context losses (Electron/ANGLE tolerated 18; the classic ~16 cap did not trigger).
- **Scrollback 5000** (CDP: `term.options.scrollback === 5000`; buffer plateaued at 5,000 + viewport rows). `shared/constants.ts:42`. Park/persist serializes 1,000 lines to `localStorage` `terminal-buffer:<id>` (~69 KB observed) — `terminal-runtime.ts:25`.
- **Electric collections: 30 per org (29 org-scoped + shared organizations), fully preloaded at boot, never evicted** (CDP + code). All reached `ready` on reload with entire tables in heap — dev org alone: 3,501 `githubPullRequests`, 1,719 `tasks`, 613 `automationRuns`, 263 `chatSessions` (~50 MB heap). `collectionsCache` (`collections.ts:208`) has `.set/.get/.has` and **no `.delete` anywhere**; `getCollections` returns a fresh spread wrapper per call but underlying Collection instances are cached (verified identical across calls). `preloadCollections` (`collections.ts:905`) preloads everything except `organizations`.

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

Clarify the collection count and preload scope.

The sentence says there are 30 collections per org and that everything is preloaded, but it later says preloadCollections excludes organizations. State explicitly whether the 30-count includes the shared organizations collection and which 29 collections are actually preloaded.

🤖 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/docs/MEMORY_AND_WORKERS_REVIEW.md` at line 72, Clarify the
collection-count statement in MEMORY_AND_WORKERS_REVIEW.md: explicitly identify
that the 30 total includes the shared organizations collection, and state that
preloadCollections preloads only the remaining 29 org-scoped collections while
excluding organizations.


**Change:** cap live xterm instances (e.g. 4–6 most-recently-visible). On eviction, serialize 1,000 lines to localStorage (already implemented, ~69 KB) and `release()` the renderer state (already implemented — PTY stays alive host-side, host keeps its own 64 KB replay buffer). Re-attach restores the serialized buffer into a fresh instance. Same policy for parked `<webview>` guests (each is a whole Chromium process).

**Effect:** measured cost is ~20 MB JS heap + ~55–70 MB renderer RSS *per live terminal* (150→570 MB heap, renderer RSS 1.59 GB at 18 terminals). A 20-terminal session drops from ~1.6 GB to roughly 500–600 MB renderer RSS — **~1 GB reclaimed**, and GPU contexts drop from N to the cap. This is the direct fix for renderer OOM white-screens and GPU pressure on 8/16 GB machines, and it removes the per-parked-terminal WebSocket + reconnect traffic.

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.

🚀 Performance & Scalability | 🟠 Major | ⚡ Quick win

Align the RSS projection with the measured results.

The measured 18-terminal A/B reports renderer RSS falling from 1,655 MB to 1,139 MB, so the claim that a 20-terminal session reaches roughly 500–600 MB is not supported by the supplied measurements. Remove the extrapolation or add a separate 20-terminal run and its conditions.

🤖 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/docs/MEMORY_AND_WORKERS_REVIEW.md` at line 97, Update the
“Effect” statement to match the supplied 18-terminal measurements, reporting
renderer RSS reduction from 1,655 MB to 1,139 MB. Remove the unsupported
extrapolation that a 20-terminal session reaches roughly 500–600 MB, unless a
separately documented 20-terminal run and its conditions are added.

MIN_TERMINAL_PARKED_RUNTIME_CAP,
} from "shared/constants";

export function BackgroundTerminalsSetting() {

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.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Use a dedicated folder for this component.

As per coding guidelines, you must use one folder per component containing ComponentName/ComponentName.tsx and an index.ts barrel export. Please move this file into a BackgroundTerminalsSetting/ directory alongside an index.ts barrel file.

🤖 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/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx`
at line 12, Move the BackgroundTerminalsSetting component into a dedicated
BackgroundTerminalsSetting directory, retaining the component implementation in
BackgroundTerminalsSetting.tsx and adding an index.ts barrel export. Update
imports and exports that reference BackgroundTerminalsSetting to use the new
barrel path.

Source: Coding guidelines

@github-actions

github-actions Bot commented Jul 17, 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! 🎉

@greptile-apps

greptile-apps Bot commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR implements LRU eviction for parked (hidden) terminal runtimes, capping the number of live xterm instances to a user-configurable limit (default 12, range 2–64). Previously every hidden terminal retained its full scrollback buffer, WebGL context, and WebSocket indefinitely; the new registry evicts the least-recently-used parked runtimes past the cap by serializing 1,000 lines to localStorage and disposing the renderer state (PTY stays alive host-side). A deferred sweep guards against evicting terminals that are mid-workspace-switch.

  • Registry core (terminal-runtime-registry.ts): adds lastUsedAt LRU counter, setParkedRuntimeCap, and a setTimeout(0) deferred evictExcessParkedRuntimes sweep triggered on every detach.
  • Settings plumbing: terminal_parked_runtime_cap column (migration 0042), tRPC get/set procedures with Zod range validation, and an optimistic-update UI component in Terminal Settings.
  • Boot seeding: the authenticated layout reads the persisted cap on mount and seeds the singleton registry, with live updates when the setting changes.

Confidence Score: 4/5

Safe to merge. The eviction logic is correct, the deferred sweep handles workspace-switch batching, the migration is additive and non-breaking, and the optimistic-update UI follows the established blur-commit pattern.

The core eviction algorithm is well-reasoned: LRU ordering via a monotonic counter, a deferred sweep that avoids evicting terminals mid-workspace-switch, and correct isolation of attached vs. parked terminals via the container === null check. Two minor discrepancies stand out: the client-side setParkedRuntimeCap guard accepts values as low as 1 while the intended minimum is 2, and the onError rollback in BackgroundTerminalsSetting skips registry restoration when context.previous is undefined, leaving the registry temporarily at the failed cap until the invalidated query refetches. Neither affects the CDP-verified happy path.

terminal-runtime-registry.ts (guard discrepancy) and BackgroundTerminalsSetting.tsx (error-path registry restoration).

Important Files Changed

Filename Overview
apps/desktop/src/renderer/lib/terminal/terminal-runtime-registry.ts Core LRU eviction logic added: lastUsedAt counter, setParkedRuntimeCap, scheduleParkedEviction (deferred 0ms), and evictExcessParkedRuntimes. Client-side minimum guard in setParkedRuntimeCap accepts cap≥1 while the backend enforces ≥2.
apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx New settings UI component with blur-commit input, optimistic updates, and rollback on error. Rollback silently skips registry restoration when context.previous is undefined (first-load race).
apps/desktop/src/lib/trpc/routers/settings/index.ts Adds getTerminalParkedRuntimeCap and setTerminalParkedRuntimeCap tRPC procedures with correct Zod int/min/max validation and upsert-on-conflict DB writes.
apps/desktop/src/renderer/routes/_authenticated/layout.tsx Seeds the parked-runtime cap into the registry singleton on mount via useQuery+useEffect; cap updates live when the query value changes.
packages/local-db/drizzle/0042_overconfident_cloak.sql Additive ALTER TABLE adds nullable terminal_parked_runtime_cap integer column; safe migration with no data loss.
packages/local-db/src/schema/schema.ts Adds terminalParkedRuntimeCap nullable integer field to the settings table schema, matching the SQL migration.
apps/desktop/src/shared/constants.ts Exports DEFAULT (12), MIN (2), and MAX (64) constants for the parked runtime cap; straightforward addition.
apps/desktop/src/renderer/routes/_authenticated/settings/utils/settings-search/settings-search.ts Registers TERMINAL_BACKGROUND_LIMIT setting item with search keywords (memory, ram, parked, etc.) and marks it as v2-only.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant R as React (TerminalPane)
    participant Reg as TerminalRuntimeRegistry
    participant Timer as setTimeout(0)
    participant LS as localStorage
    participant WS as WebSocket

    R->>Reg: detach(terminalId)
    Reg->>Reg: "entry.lastUsedAt = ++useSeq"
    Reg->>Reg: detachFromContainer(runtime)
    Reg->>Timer: scheduleParkedEviction() [if no pending]

    Note over Timer: next event-loop tick

    Timer->>Reg: evictExcessParkedRuntimes()
    Reg->>Reg: "filter parked entries (runtime!=null, container=null)"
    Reg->>Reg: sort ascending by lastUsedAt
    Reg->>Reg: "excess = parked.length - parkedRuntimeCap"

    loop for each excess entry (LRU first)
        Reg->>LS: disposeRuntime serialize 1000 lines
        Reg->>WS: disposeTransport close WebSocket
        Reg->>Reg: deleteEntry(entry)
    end

    Note over R,Reg: On re-open
    R->>Reg: mount(terminalId, container, appearance)
    Reg->>LS: serializeExistingRuntime read 1000-line buffer
    Reg->>Reg: createRuntime with initialBuffer
    Reg->>WS: connect() reconnect to live PTY
Loading
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant R as React (TerminalPane)
    participant Reg as TerminalRuntimeRegistry
    participant Timer as setTimeout(0)
    participant LS as localStorage
    participant WS as WebSocket

    R->>Reg: detach(terminalId)
    Reg->>Reg: "entry.lastUsedAt = ++useSeq"
    Reg->>Reg: detachFromContainer(runtime)
    Reg->>Timer: scheduleParkedEviction() [if no pending]

    Note over Timer: next event-loop tick

    Timer->>Reg: evictExcessParkedRuntimes()
    Reg->>Reg: "filter parked entries (runtime!=null, container=null)"
    Reg->>Reg: sort ascending by lastUsedAt
    Reg->>Reg: "excess = parked.length - parkedRuntimeCap"

    loop for each excess entry (LRU first)
        Reg->>LS: disposeRuntime serialize 1000 lines
        Reg->>WS: disposeTransport close WebSocket
        Reg->>Reg: deleteEntry(entry)
    end

    Note over R,Reg: On re-open
    R->>Reg: mount(terminalId, container, appearance)
    Reg->>LS: serializeExistingRuntime read 1000-line buffer
    Reg->>Reg: createRuntime with initialBuffer
    Reg->>WS: connect() reconnect to live PTY
Loading
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
apps/desktop/src/renderer/lib/terminal/terminal-runtime-registry.ts:59-61
The lower guard here accepts any value ≥ 1, but `MIN_TERMINAL_PARKED_RUNTIME_CAP` is 2 — the same minimum enforced by the backend Zod schema. If a future caller passes 1 directly (e.g., via a test or a new code path), the registry silently accepts it and would aggressively evict down to a single parked terminal. Tying the guard to the shared constant keeps the invariant in one place.

```suggestion
	setParkedRuntimeCap(cap: number) {
		if (!Number.isFinite(cap) || cap < MIN_TERMINAL_PARKED_RUNTIME_CAP) return;
		this.parkedRuntimeCap = Math.floor(cap);
```

### Issue 2 of 2
apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx:26-34
**Registry cap not restored on error when query is uninitialized**

If `getData()` returns `undefined` (the query hasn't resolved yet — unlikely given `disabled={isLoading}`, but possible on a very fast double-submit before the first result arrives), `context.previous` is `undefined`, so the `if` guard skips the `setParkedRuntimeCap` call. The optimistically applied `nextCap` is left in the registry until `onSettled` → `invalidate()` → refetch → layout `useEffect` corrects it. During that async window, the eviction sweep runs with the wrong cap. The `onSettled` path does eventually correct this, but explicitly falling back to `DEFAULT_TERMINAL_PARKED_RUNTIME_CAP` here would make the recovery immediate and self-documenting.

Reviews (1): Last reviewed commit: "docs(desktop): memory profile & worker o..." | Re-trigger Greptile

Comment on lines +59 to +61
setParkedRuntimeCap(cap: number) {
if (!Number.isFinite(cap) || cap < 1) return;
this.parkedRuntimeCap = Math.floor(cap);

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.

P2 The lower guard here accepts any value ≥ 1, but MIN_TERMINAL_PARKED_RUNTIME_CAP is 2 — the same minimum enforced by the backend Zod schema. If a future caller passes 1 directly (e.g., via a test or a new code path), the registry silently accepts it and would aggressively evict down to a single parked terminal. Tying the guard to the shared constant keeps the invariant in one place.

Suggested change
setParkedRuntimeCap(cap: number) {
if (!Number.isFinite(cap) || cap < 1) return;
this.parkedRuntimeCap = Math.floor(cap);
setParkedRuntimeCap(cap: number) {
if (!Number.isFinite(cap) || cap < MIN_TERMINAL_PARKED_RUNTIME_CAP) return;
this.parkedRuntimeCap = Math.floor(cap);
Prompt To Fix With AI
This is a comment left during a code review.
Path: apps/desktop/src/renderer/lib/terminal/terminal-runtime-registry.ts
Line: 59-61

Comment:
The lower guard here accepts any value ≥ 1, but `MIN_TERMINAL_PARKED_RUNTIME_CAP` is 2 — the same minimum enforced by the backend Zod schema. If a future caller passes 1 directly (e.g., via a test or a new code path), the registry silently accepts it and would aggressively evict down to a single parked terminal. Tying the guard to the shared constant keeps the invariant in one place.

```suggestion
	setParkedRuntimeCap(cap: number) {
		if (!Number.isFinite(cap) || cap < MIN_TERMINAL_PARKED_RUNTIME_CAP) return;
		this.parkedRuntimeCap = Math.floor(cap);
```

How can I resolve this? If you propose a fix, please make it concise.

Comment on lines +26 to +34
onError: (_err, _vars, context) => {
if (context?.previous !== undefined) {
utils.settings.getTerminalParkedRuntimeCap.setData(
undefined,
context.previous,
);
terminalRuntimeRegistry.setParkedRuntimeCap(context.previous);
}
},

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.

P2 Registry cap not restored on error when query is uninitialized

If getData() returns undefined (the query hasn't resolved yet — unlikely given disabled={isLoading}, but possible on a very fast double-submit before the first result arrives), context.previous is undefined, so the if guard skips the setParkedRuntimeCap call. The optimistically applied nextCap is left in the registry until onSettled → invalidate() → refetch → layout useEffect corrects it. During that async window, the eviction sweep runs with the wrong cap. The onSettled path does eventually correct this, but explicitly falling back to DEFAULT_TERMINAL_PARKED_RUNTIME_CAP here would make the recovery immediate and self-documenting.

Prompt To Fix With AI
This is a comment left during a code review.
Path: apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx
Line: 26-34

Comment:
**Registry cap not restored on error when query is uninitialized**

If `getData()` returns `undefined` (the query hasn't resolved yet — unlikely given `disabled={isLoading}`, but possible on a very fast double-submit before the first result arrives), `context.previous` is `undefined`, so the `if` guard skips the `setParkedRuntimeCap` call. The optimistically applied `nextCap` is left in the registry until `onSettled` → `invalidate()` → refetch → layout `useEffect` corrects it. During that async window, the eviction sweep runs with the wrong cap. The `onSettled` path does eventually correct this, but explicitly falling back to `DEFAULT_TERMINAL_PARKED_RUNTIME_CAP` here would make the recovery immediate and self-documenting.

How can I resolve this? If you propose a fix, please make it concise.

@cubic-dev-ai cubic-dev-ai 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.

4 issues found across 12 files

You’re at about 94% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx">

<violation number="1" location="apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx:48">
P2: Fractional or exponent-form input can silently apply a different cap: `2.5` and `2e1` become `2` via `parseInt`. Parse the complete value and require an integer so invalid values revert rather than unexpectedly changing eviction behavior.</violation>
</file>

<file name="apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md">

<violation number="1" location="apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md:54">
P2: The throughput annotation for `while true; do seq 1 100; sleep 0.2; done` is overstated. This command is about ~1.5 KB/s per process (roughly ~35 KB/s total across 24 streams), not ~40 KB/s per process.</violation>

<violation number="2" location="apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md:72">
P3: This finding is ambiguous about preload scope: it says the 30-collection set is fully preloaded at boot, but later says `preloadCollections` excludes `organizations`. Consider explicitly stating whether `organizations` is counted in the 30 and which collections are actually eagerly loaded.</violation>

<violation number="3" location="apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md:97">
P2: The RSS projection here isn’t aligned with the measurements shown above. The documented eviction run reports renderer RSS at 1,139 MB (18 terminals), so the 20-terminal `~500–600 MB` claim reads as unsupported extrapolation unless a separate run is included.</violation>
</file>
Architecture diagram
sequenceDiagram
    participant User as User
    participant SettingsUI as BackgroundTerminalsSetting
    participant TRPC as tRPC Router
    participant LocalDB as SQLite (local-db)
    participant Layout as _authenticated Layout
    participant Registry as TerminalRuntimeRegistry
    participant Xterm as xterm.js + WebGL
    participant WS as WebSocket
    participant PTY as Host PTY + Replay Buffer

    Note over User,PTY: Boot: Cap seeded from settings

    Layout->>TRPC: getTerminalParkedRuntimeCap()
    TRPC->>LocalDB: SELECT terminal_parked_runtime_cap
    LocalDB-->>TRPC: 12 (or persisted value)
    TRPC-->>Layout: cap value
    Layout->>Registry: setParkedRuntimeCap(12)
    Registry->>Registry: parkedRuntimeCap = 12

    Note over User,PTY: Terminal lifecycle with LRU eviction

    User->>Xterm: Opens terminal 1
    Xterm->>Registry: mount(terminalId)
    Registry->>Registry: bump lastUsedAt
    Registry->>WS: create socket to host
    WS->>PTY: attach to running process

    User->>Xterm: Switch away from terminal (detach)
    Xterm->>Registry: detachFromContainer(terminalId)
    Registry->>Registry: bump lastUsedAt
    Registry->>Registry: scheduleParkedEviction() — deferred
    Note over Registry: Deferred 1 tick

    User->>Xterm: Opens terminals 2..18
    alt Parked count exceeds cap
        Note over Registry: 17 parked > cap 12
        Registry->>Registry: evictExcessParkedRuntimes()
        Registry->>Registry: sort parked entries by lastUsedAt (asc)
        Registry->>Registry: dispose 5 least-recently-used entries
        Registry->>Registry: serialize 1000 lines to localStorage
        Registry->>WS: close socket
        Registry->>Xterm: dispose xterm instance
        Xterm-->>Xterm: WebGL context freed
        Note over PTY: PTY process continues running
        PTY-->>PTY: host replay buffer preserved (64KB)
    else Parked count within cap
        Note over Registry: 10 parked ≤ cap 12 — no action
    end

    User->>Xterm: Reopen evicted terminal
    Xterm->>Registry: mount(terminalId)
    Registry->>Registry: bump lastUsedAt
    Registry->>Registry: restore from localStorage (1000 lines)
    Registry->>WS: create new socket
    WS->>PTY: reattach to live process
    WS-->>Xterm: stream new output appended to restored buffer

    Note over User,PTY: User changes cap in settings

    User->>SettingsUI: Set "Background terminal memory" to 6
    SettingsUI->>TRPC: setTerminalParkedRuntimeCap({ cap: 6 })
    alt Optimistic update
        SettingsUI->>Registry: setParkedRuntimeCap(6)
        Registry->>Registry: scheduleParkedEviction()
        TRPC->>LocalDB: UPSERT terminal_parked_runtime_cap = 6
        LocalDB-->>TRPC: ok
        TRPC-->>SettingsUI: success
    else Rollback on error
        SettingsUI->>Registry: setParkedRuntimeCap(previousCap)
        SettingsUI-->>User: revert input to prior value
    end

    alt Cap lowered 12→6
        Registry->>Registry: evictExcessParkedRuntimes()
        Registry->>Registry: 6 parked > new cap — evicts 6 more
        Note over PTY: same eviction flow: persist, close WS, dispose
    end

    Note over User,PTY: Input validation — server rejects out-of-range

    User->>SettingsUI: Enter 999 as cap
    SettingsUI->>TRPC: setTerminalParkedRuntimeCap({ cap: 999 })
    TRPC->>TRPC: zod validation fails (max 64)
    TRPC-->>SettingsUI: error
    SettingsUI->>SettingsUI: onError — rollback registry
    Registry->>Registry: setParkedRuntimeCap(previousCap)
    SettingsUI-->>User: input reverts to last valid value
Loading

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

}, [cap]);

const commitDraft = (raw: string) => {
const value = Number.parseInt(raw, 10);

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.

P2: Fractional or exponent-form input can silently apply a different cap: 2.5 and 2e1 become 2 via parseInt. Parse the complete value and require an integer so invalid values revert rather than unexpectedly changing eviction behavior.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/desktop/src/renderer/routes/_authenticated/settings/terminal/components/TerminalSettings/components/BackgroundTerminalsSetting.tsx, line 48:

<comment>Fractional or exponent-form input can silently apply a different cap: `2.5` and `2e1` become `2` via `parseInt`. Parse the complete value and require an integer so invalid values revert rather than unexpectedly changing eviction behavior.</comment>

<file context>
@@ -0,0 +1,92 @@
+	}, [cap]);
+
+	const commitDraft = (raw: string) => {
+		const value = Number.parseInt(raw, 10);
+		if (
+			!Number.isNaN(value) &&
</file context>


### Heavy A/B — 24 terminals with live streaming processes

Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY process streaming continuously (`while true; do seq 1 100; sleep 0.2; done`, ~40 KB/s each; throttled deliberately — a full-rate flood kills the shared daemon socket per the SUPER-1544 plan's finding, which would invalidate the comparison). CPU is a 30 s `cputime` delta during steady state.

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.

P2: The throughput annotation for while true; do seq 1 100; sleep 0.2; done is overstated. This command is about ~1.5 KB/s per process (roughly ~35 KB/s total across 24 streams), not ~40 KB/s per process.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md, line 54:

<comment>The throughput annotation for `while true; do seq 1 100; sleep 0.2; done` is overstated. This command is about ~1.5 KB/s per process (roughly ~35 KB/s total across 24 streams), not ~40 KB/s per process.</comment>

<file context>
@@ -0,0 +1,141 @@
+
+### Heavy A/B — 24 terminals with live streaming processes
+
+Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY process streaming continuously (`while true; do seq 1 100; sleep 0.2; done`, ~40 KB/s each; throttled deliberately — a full-rate flood kills the shared daemon socket per the SUPER-1544 plan's finding, which would invalidate the comparison). CPU is a 30 s `cputime` delta during steady state.
+
+| Metric (24 streams live) | Before (HEAD) | After (eviction) |
</file context>
Suggested change
Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY process streaming continuously (`while true; do seq 1 100; sleep 0.2; done`, ~40 KB/s each; throttled deliberately — a full-rate flood kills the shared daemon socket per the SUPER-1544 plan's finding, which would invalidate the comparison). CPU is a 30 s `cputime` delta during steady state.
Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY process streaming continuously (`while true; do seq 1 100; sleep 0.2; done`, ~1.5 KB/s each; throttled deliberately — a full-rate flood kills the shared daemon socket per the SUPER-1544 plan's finding, which would invalidate the comparison). CPU is a 30 s `cputime` delta during steady state.


**Change:** cap live xterm instances (e.g. 4–6 most-recently-visible). On eviction, serialize 1,000 lines to localStorage (already implemented, ~69 KB) and `release()` the renderer state (already implemented — PTY stays alive host-side, host keeps its own 64 KB replay buffer). Re-attach restores the serialized buffer into a fresh instance. Same policy for parked `<webview>` guests (each is a whole Chromium process).

**Effect:** measured cost is ~20 MB JS heap + ~55–70 MB renderer RSS *per live terminal* (150→570 MB heap, renderer RSS 1.59 GB at 18 terminals). A 20-terminal session drops from ~1.6 GB to roughly 500–600 MB renderer RSS — **~1 GB reclaimed**, and GPU contexts drop from N to the cap. This is the direct fix for renderer OOM white-screens and GPU pressure on 8/16 GB machines, and it removes the per-parked-terminal WebSocket + reconnect traffic.

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.

P2: The RSS projection here isn’t aligned with the measurements shown above. The documented eviction run reports renderer RSS at 1,139 MB (18 terminals), so the 20-terminal ~500–600 MB claim reads as unsupported extrapolation unless a separate run is included.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md, line 97:

<comment>The RSS projection here isn’t aligned with the measurements shown above. The documented eviction run reports renderer RSS at 1,139 MB (18 terminals), so the 20-terminal `~500–600 MB` claim reads as unsupported extrapolation unless a separate run is included.</comment>

<file context>
@@ -0,0 +1,141 @@
+
+**Change:** cap live xterm instances (e.g. 4–6 most-recently-visible). On eviction, serialize 1,000 lines to localStorage (already implemented, ~69 KB) and `release()` the renderer state (already implemented — PTY stays alive host-side, host keeps its own 64 KB replay buffer). Re-attach restores the serialized buffer into a fresh instance. Same policy for parked `<webview>` guests (each is a whole Chromium process).
+
+**Effect:** measured cost is ~20 MB JS heap + ~55–70 MB renderer RSS *per live terminal* (150→570 MB heap, renderer RSS 1.59 GB at 18 terminals). A 20-terminal session drops from ~1.6 GB to roughly 500–600 MB renderer RSS — **~1 GB reclaimed**, and GPU contexts drop from N to the cap. This is the direct fix for renderer OOM white-screens and GPU pressure on 8/16 GB machines, and it removes the per-parked-terminal WebSocket + reconnect traffic.
+
+**Cost/risk:** evicted terminals lose scrollback beyond 1,000 lines (visible only if the user scrolls back that far); re-attach pays one xterm construction + 69 KB replay (tens of ms, imperceptible next to pane-switch). No behavior change for the PTY itself.
</file context>

- **Parked terminals are never disposed** (CDP). On workspace/tab switch the xterm wrapper reparents into a `position:fixed; left:-9999px` container under `<body>`; buffer (5,048 lines retained), addons, WebSocket, and **live WebGL context** all survive. `terminal-runtime-registry.ts`, `terminal-parking.ts`, detach-only unmount in `TerminalPane.tsx:162`.
- **No instance cap** (CDP): 18 terminals → 18 registry entries, 18 live WebGL contexts, zero evictions, zero GPU context losses (Electron/ANGLE tolerated 18; the classic ~16 cap did not trigger).
- **Scrollback 5000** (CDP: `term.options.scrollback === 5000`; buffer plateaued at 5,000 + viewport rows). `shared/constants.ts:42`. Park/persist serializes 1,000 lines to `localStorage` `terminal-buffer:<id>` (~69 KB observed) — `terminal-runtime.ts:25`.
- **Electric collections: 30 per org (29 org-scoped + shared organizations), fully preloaded at boot, never evicted** (CDP + code). All reached `ready` on reload with entire tables in heap — dev org alone: 3,501 `githubPullRequests`, 1,719 `tasks`, 613 `automationRuns`, 263 `chatSessions` (~50 MB heap). `collectionsCache` (`collections.ts:208`) has `.set/.get/.has` and **no `.delete` anywhere**; `getCollections` returns a fresh spread wrapper per call but underlying Collection instances are cached (verified identical across calls). `preloadCollections` (`collections.ts:905`) preloads everything except `organizations`.

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.

P3: This finding is ambiguous about preload scope: it says the 30-collection set is fully preloaded at boot, but later says preloadCollections excludes organizations. Consider explicitly stating whether organizations is counted in the 30 and which collections are actually eagerly loaded.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md, line 72:

<comment>This finding is ambiguous about preload scope: it says the 30-collection set is fully preloaded at boot, but later says `preloadCollections` excludes `organizations`. Consider explicitly stating whether `organizations` is counted in the 30 and which collections are actually eagerly loaded.</comment>

<file context>
@@ -0,0 +1,141 @@
+- **Parked terminals are never disposed** (CDP). On workspace/tab switch the xterm wrapper reparents into a `position:fixed; left:-9999px` container under `<body>`; buffer (5,048 lines retained), addons, WebSocket, and **live WebGL context** all survive. `terminal-runtime-registry.ts`, `terminal-parking.ts`, detach-only unmount in `TerminalPane.tsx:162`.
+- **No instance cap** (CDP): 18 terminals → 18 registry entries, 18 live WebGL contexts, zero evictions, zero GPU context losses (Electron/ANGLE tolerated 18; the classic ~16 cap did not trigger).
+- **Scrollback 5000** (CDP: `term.options.scrollback === 5000`; buffer plateaued at 5,000 + viewport rows). `shared/constants.ts:42`. Park/persist serializes 1,000 lines to `localStorage` `terminal-buffer:<id>` (~69 KB observed) — `terminal-runtime.ts:25`.
+- **Electric collections: 30 per org (29 org-scoped + shared organizations), fully preloaded at boot, never evicted** (CDP + code). All reached `ready` on reload with entire tables in heap — dev org alone: 3,501 `githubPullRequests`, 1,719 `tasks`, 613 `automationRuns`, 263 `chatSessions` (~50 MB heap). `collectionsCache` (`collections.ts:208`) has `.set/.get/.has` and **no `.delete` anywhere**; `getCollections` returns a fresh spread wrapper per call but underlying Collection instances are cached (verified identical across calls). `preloadCollections` (`collections.ts:905`) preloads everything except `organizations`.
+- **Pierre worker pool is real and is the only renderer worker system** (CDP: exactly 8 `worker` CDP targets). `layout.tsx:217` (`poolSize: 8`, shiki-wasm). No SharedWorker/OffscreenCanvas/comlink anywhere.
+- **Chat code blocks highlight on the main thread, twice per block** (code): `codeToHast` with `one-light` then `one-dark-pro`, re-run on every `code` change — `packages/ui/src/components/ai-elements/code-block.tsx:84-159`. Not routed through the pierre pool.
</file context>
Suggested change
- **Electric collections: 30 per org (29 org-scoped + shared organizations), fully preloaded at boot, never evicted** (CDP + code). All reached `ready` on reload with entire tables in heap — dev org alone: 3,501 `githubPullRequests`, 1,719 `tasks`, 613 `automationRuns`, 263 `chatSessions` (~50 MB heap). `collectionsCache` (`collections.ts:208`) has `.set/.get/.has` and **no `.delete` anywhere**; `getCollections` returns a fresh spread wrapper per call but underlying Collection instances are cached (verified identical across calls). `preloadCollections` (`collections.ts:905`) preloads everything except `organizations`.
- **Electric collections: 30 per org context (29 org-scoped + shared `organizations`), never evicted** (CDP + code). The org-scoped preload path eagerly loads the 29 org collections; `organizations` is shared and loaded separately.

Covers recency ordering (not insertion order), attached-runtime
protection, deferred-sweep rescue on remount, live cap lowering,
invalid cap rejection, buffer persistence on evict, and runtime-less
entries. Each assertion verified to fail under a targeted impl
mutation (sort removed, attached included, sweep made synchronous,
setter sweep dropped, persist flag flipped).
…le mocks

The first test cut used bun mock.module, which is process-wide and
replaced the real terminal-ws-transport for its own suite (15 downstream
failures in CI). Restructure along a real seam instead: the LRU
selection + cap clamp move to dependency-free terminal-runtime-eviction.ts,
unit-tested without mocks (mutation-verified: sort removal, attached
inclusion, bare-entry counting, clamp boundary all caught; one equivalent
mutant on the <=cap guard documented). Timer deferral and dispose wiring
remain covered by the CDP verification in the PR.
Kitenite added 2 commits July 17, 2026 16:49
origin/main tip fails biome 2.4.2 on this block, which fails lint on
every PR's merge ref; carrying the fix here.

@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.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
packages/host-service/src/trpc/router/workspace-creation/utils/ai-workspace-names.ts (2)

262-275: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Prevent dangling timer in Promise.race.

When agent.generate resolves before the timeout, the setTimeout remains active in the event loop. This causes a memory and handle leak until the timer eventually expires. Store the timer ID and clear it when the race finishes.

💡 Proposed fix
 	try {
+		let timer: NodeJS.Timeout;
 		const { object } = await Promise.race([
 			agent.generate(prompt, {
 				structuredOutput: {
 					schema: workspaceNamesOutputSchema,
 				},
-			}),
+			}).finally(() => clearTimeout(timer)),
 			new Promise<never>((_, reject) =>
-				setTimeout(
+				timer = setTimeout(
 					() => reject(new Error(`timed out after ${GENERATE_TIMEOUT_MS}ms`)),
 					GENERATE_TIMEOUT_MS,
 				),
 			),
 		]);
🤖 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
`@packages/host-service/src/trpc/router/workspace-creation/utils/ai-workspace-names.ts`
around lines 262 - 275, The Promise.race timeout in the workspace-name
generation flow leaves its timer active after agent.generate completes. Update
the surrounding try flow to retain the setTimeout handle and clear it in a
finally block, ensuring cleanup occurs whether the race resolves, rejects, or
times out while preserving the existing timeout behavior.

144-169: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Robustly extract JSON to support braces inside string values.

The current regex /\{[^{}]*\}/g fails to extract the JSON if any of the generated strings contain a { or } (e.g., {"title": "add {user} field"}). Replacing the regex with a reverse-search loop guarantees robust extraction even if the model outputs inner braces or trailing garbage containing braces.

💡 Proposed fix
 function extractNamesJson(
 	output: string,
 ): { title: string; branchName: string } | null {
-	// Agent CLIs may prepend banners (skill/hook load lines) or wrap the
-	// object in fences; take the last flat JSON object with both fields.
-	const candidates = output.match(/\{[^{}]*\}/g);
-	if (!candidates) return null;
-	for (const candidate of candidates.reverse()) {
-		try {
-			const parsed: unknown = JSON.parse(candidate);
-			if (
-				typeof parsed === "object" &&
-				parsed !== null &&
-				"title" in parsed &&
-				"branchName" in parsed &&
-				typeof parsed.title === "string" &&
-				typeof parsed.branchName === "string"
-			) {
-				return { title: parsed.title, branchName: parsed.branchName };
-			}
-		} catch {
-			// not JSON — keep scanning earlier candidates
-		}
-	}
+	let startIdx = output.lastIndexOf("{");
+	while (startIdx !== -1) {
+		let endIdx = output.lastIndexOf("}");
+		while (endIdx > startIdx) {
+			try {
+				const parsed: unknown = JSON.parse(
+					output.substring(startIdx, endIdx + 1),
+				);
+				if (
+					typeof parsed === "object" &&
+					parsed !== null &&
+					"title" in parsed &&
+					"branchName" in parsed &&
+					typeof parsed.title === "string" &&
+					typeof parsed.branchName === "string"
+				) {
+					return { title: parsed.title, branchName: parsed.branchName };
+				}
+			} catch {
+				// keep trying shorter substrings
+			}
+			endIdx = output.lastIndexOf("}", endIdx - 1);
+		}
+		startIdx = output.lastIndexOf("{", startIdx - 1);
+	}
 	return null;
 }
🤖 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
`@packages/host-service/src/trpc/router/workspace-creation/utils/ai-workspace-names.ts`
around lines 144 - 169, Update extractNamesJson to replace the flat-brace regex
with a reverse scan that identifies balanced JSON object boundaries while
respecting braces inside quoted string values and escaped quotes. Parse each
candidate from the end, retain the existing title and branchName validation, and
continue past invalid or trailing-brace content until a valid object is found.
🤖 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.

Outside diff comments:
In
`@packages/host-service/src/trpc/router/workspace-creation/utils/ai-workspace-names.ts`:
- Around line 262-275: The Promise.race timeout in the workspace-name generation
flow leaves its timer active after agent.generate completes. Update the
surrounding try flow to retain the setTimeout handle and clear it in a finally
block, ensuring cleanup occurs whether the race resolves, rejects, or times out
while preserving the existing timeout behavior.
- Around line 144-169: Update extractNamesJson to replace the flat-brace regex
with a reverse scan that identifies balanced JSON object boundaries while
respecting braces inside quoted string values and escaped quotes. Parse each
candidate from the end, retain the existing title and branchName validation, and
continue past invalid or trailing-brace content until a valid object is found.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 36145d75-065b-473c-be64-4c3dfd2be67f

📥 Commits

Reviewing files that changed from the base of the PR and between 2a1aa7f and 68887e4.

📒 Files selected for processing (2)
  • apps/desktop/src/renderer/routes/_authenticated/layout.tsx
  • packages/host-service/src/trpc/router/workspace-creation/utils/ai-workspace-names.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • apps/desktop/src/renderer/routes/_authenticated/layout.tsx

This branch was previously deployed

1 inactive deployment
preview — 68887e4d Deployed Jul 17, 2026 by Kitenite via Deploy Web #6621
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