Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions apps/desktop/docs/MEMORY_AND_WORKERS_REVIEW.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Memory Profile & Worker Offload Review

2026-07-17. Code sweep across renderer / Electron main / host-service / pty-daemon, then every load-bearing claim verified against the live dev app over CDP (18-terminal stress, heap + RSS sampling, process-table spawn sampling). Claims marked **CDP** were observed at runtime; **code** means verified at the cited line but not behaviorally driven.
2026-07-18. Code sweep across renderer / Electron main / host-service / pty-daemon, then every load-bearing claim verified against the live dev app over CDP (18-terminal stress, heap + RSS sampling, process-table spawn sampling). Claims marked **CDP** were observed at runtime; **code** means verified at the cited line but not behaviorally driven.

## Progress

| Item | Ticket | Status |
|---|---|---|
| Parked-terminal LRU eviction (terminal half) | SUPER-1545 | **Implemented**, uncommitted. Cap defaults to 12 parked, user-configurable (Settings → Terminal → "Background terminal memory"; local-db `terminal_parked_runtime_cap`, migration 0042, zod-clamped 2–64, live-applied via `terminalRuntimeRegistry.setParkedRuntimeCap`). CDP-verified: default seeds at boot, 16-tab cycle parks exactly 12, lowering to 6 sweeps immediately, persists, out-of-range rejected. Two controlled A/Bs below (18-terminal fill, 24-terminal live-stream; both measured at cap 5 — savings scale down as the cap rises) |
| Parked-webview eviction (second half) | SUPER-1545 | Not started |
| Parked-terminal LRU eviction (terminal half) | SUPER-1545 | **Shipped** in PR #5751. Cap defaults to 12 parked, user-configurable (Settings → Terminal → "Background terminal memory"; local-db `terminal_parked_runtime_cap`, migration 0042, zod-clamped 2–64, live-applied via `terminalRuntimeRegistry.setParkedRuntimeCap`). CDP-verified: default seeds at boot, 16-tab cycle parks exactly 12, lowering to 6 sweeps immediately, persists, out-of-range rejected. Two controlled A/Bs below (18-terminal fill, 24-terminal live-stream; both measured at cap 5 — savings scale down as the cap rises) |
| Parked-webview eviction + alt-screen exemption + quota guard | SUPER-1545 | **Implemented** (hidden-webview LRU cap 3 in `browserRuntimeRegistry`; alternate-screen TUIs exempt from terminal eviction; eviction skipped when the buffer cannot persist). CDP-verified 2026-07-18 |
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
| Chat shiki off main thread | SUPER-1546 | Not started |
| Collections preload/window/evict | SUPER-1547 | Not started |
| Async process-tree probes | SUPER-1548 | Not started |
Expand Down Expand Up @@ -62,7 +62,7 @@ Same A/B discipline, harder load: 24 terminal tabs, each running a real PTY proc
| Host-service / daemon / GPU CPU | 2% / 1% / 5% | 2% / 1% / 4% |
| Tab-switch p50 / p95 under load | 52 / 95 ms | 68 / 114 ms |

The CPU gap is structural: eviction closes the WebSocket of released terminals, so their streams are neither delivered nor parsed — the before build parses all 24 streams into 23 live xterms forever. Heap is also flat under load in the eviction build vs climbing in the before build.
Under this real-PTY streaming workload, eviction closes the WebSocket of released terminals, so their streams are neither delivered nor parsed — the before build parses all 24 streams into 23 live xterms forever. Heap is also flat under load in the eviction build vs climbing in the before build. A later 18-terminal synthetic-output rerun confirmed the memory result (−46% JS heap, −30% renderer RSS) but did not reproduce a CPU reduction (`TaskDuration` 1.41 s before vs 1.80 s after), so treat the 30% → 21% CPU sample as workload-specific rather than a general CPU claim.

## Verified findings — renderer

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,26 @@ describe("selectRuntimesToEvict", () => {
expect(selectRuntimesToEvict(entries, 2)).toEqual([]);
expect(ids(selectRuntimesToEvict(entries, 1))).toEqual(["a"]);
});

it("never selects exempt entries, even when they are the oldest", () => {
const entries = [parked("tui", 1), parked("a", 2), parked("b", 3)];
const isExempt = (e: { id: string }) => e.id === "tui";
expect(ids(selectRuntimesToEvict(entries, 2, isExempt))).toEqual(["a"]);
});

it("stops early when only exempt entries remain over the cap", () => {
const entries = [parked("tui1", 1), parked("tui2", 2), parked("a", 3)];
const isExempt = (e: { id: string }) => e.id.startsWith("tui");
// excess is 2 but only one evictable entry exists
expect(ids(selectRuntimesToEvict(entries, 1, isExempt))).toEqual(["a"]);
});

it("exempt entries still occupy the parked count", () => {
const entries = [parked("tui", 1), parked("a", 2)];
const isExempt = (e: { id: string }) => e.id === "tui";
// cap 1: tui fills the single slot, so "a" must go despite being newer
expect(ids(selectRuntimesToEvict(entries, 1, isExempt))).toEqual(["a"]);
});
});

describe("normalizeParkedRuntimeCap", () => {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
/**
* Pure selection policy for parked-runtime LRU eviction (SUPER-1545).
* Kept dependency-free so it can be unit-tested without pulling the
* xterm/transport import graph into the test process.
* xterm/transport import graph into the test process. Also reused by the
* browser pane registry for hidden-webview eviction.
*/

interface EvictionCandidate {
Expand All @@ -18,16 +19,21 @@ export function normalizeParkedRuntimeCap(cap: number): number | null {
/**
* Pick the parked (live runtime, no container) entries to release, oldest
* `lastUsedAt` first, so at most `cap` parked runtimes remain. Attached
* runtimes and runtime-less entries are never candidates.
* runtimes and runtime-less entries are never candidates. Exempt entries
* (e.g. an active alternate-screen TUI) still occupy the parked count but
* are never selected — eviction stops early when only exempt entries remain.
*/
export function selectRuntimesToEvict<T extends EvictionCandidate>(
entries: Iterable<T>,
cap: number,
isExempt: (entry: T) => boolean = () => false,
): T[] {
const parked = Array.from(entries).filter(
(entry) => entry.runtime !== null && entry.runtime.container === null,
);
if (parked.length <= cap) return [];
parked.sort((a, b) => a.lastUsedAt - b.lastUsedAt);
return parked.slice(0, parked.length - cap);
const excess = parked.length - cap;
if (excess <= 0) return [];
const evictable = parked.filter((entry) => !isExempt(entry));
evictable.sort((a, b) => a.lastUsedAt - b.lastUsedAt);
return evictable.slice(0, excess);
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";

mock.module("renderer/lib/trpc-client", () => ({
electronTrpcClient: {
keyboardLayout: {
changes: { subscribe: () => {} },
},
},
}));

const { terminalRuntimeRegistry } = await import("./terminal-runtime-registry");
const { tryPersistRuntimeState } = await import("./terminal-runtime");

interface FakeStorageState {
values: Map<string, string>;
storage: Storage;
}

function createFakeStorage(): FakeStorageState {
const values = new Map<string, string>();
const storage = {
get length() {
return values.size;
},
clear: () => values.clear(),
getItem: (key: string) => values.get(key) ?? null,
key: (index: number) => Array.from(values.keys())[index] ?? null,
removeItem: (key: string) => values.delete(key),
setItem: (key: string, value: string) => values.set(key, value),
} as Storage;
return { values, storage };
}

const originalLocalStorage = globalThis.localStorage;
let fakeStorage: FakeStorageState;

beforeEach(() => {
fakeStorage = createFakeStorage();
Object.defineProperty(globalThis, "localStorage", {
configurable: true,
value: fakeStorage.storage,
});
});

afterEach(() => {
Object.defineProperty(globalThis, "localStorage", {
configurable: true,
value: originalLocalStorage,
});
});

describe("terminalRuntimeRegistry eviction cleanup", () => {
test("keeps a runtime when dimensions fail to persist", () => {
const terminalId = "dimensions-write-failure";
const setItem = fakeStorage.storage.setItem.bind(fakeStorage.storage);
fakeStorage.storage.setItem = (key: string, value: string) => {
if (key === `terminal-dims:${terminalId}`) {
throw new Error("dimensions write failed");
}
setItem(key, value);
};
const runtime = {
terminalId,
serializeAddon: { serialize: () => "serialized scrollback" },
lastCols: 120,
lastRows: 32,
};

expect(
tryPersistRuntimeState(
runtime as Parameters<typeof tryPersistRuntimeState>[0],
),
).toBe(false);
expect(fakeStorage.values.get(`terminal-buffer:${terminalId}`)).toBe(
"serialized scrollback",
);
expect(fakeStorage.values.has(`terminal-dims:${terminalId}`)).toBe(false);
});

test("dispose clears persisted state even when eviction already removed the entry", () => {
const terminalId = "evicted-terminal";
fakeStorage.values.set(`terminal-buffer:${terminalId}`, "scrollback");
fakeStorage.values.set(
`terminal-dims:${terminalId}`,
JSON.stringify({ cols: 120, rows: 32 }),
);

expect(terminalRuntimeRegistry.has(terminalId)).toBe(false);
terminalRuntimeRegistry.dispose(terminalId);

expect(fakeStorage.values.has(`terminal-buffer:${terminalId}`)).toBe(false);
expect(fakeStorage.values.has(`terminal-dims:${terminalId}`)).toBe(false);
});

test("reschedules eviction when a parked terminal changes buffers", () => {
let emitBufferChange: () => void = () => {
throw new Error("buffer listener was not installed");
};
let listenerDisposed = false;
const runtime = {
container: {} as HTMLDivElement | null,
terminal: {
buffer: {
onBufferChange: (listener: () => void) => {
emitBufferChange = listener;
return { dispose: () => (listenerDisposed = true) };
},
},
},
};
const entry = {
runtime,
disposeBufferChangeListener: null as (() => void) | null,
};
const registryInternals = terminalRuntimeRegistry as unknown as {
observeBufferChanges: (observedEntry: typeof entry) => void;
pendingEviction: ReturnType<typeof setTimeout> | null;
};

if (registryInternals.pendingEviction !== null) {
clearTimeout(registryInternals.pendingEviction);
registryInternals.pendingEviction = null;
}
registryInternals.observeBufferChanges(entry);
emitBufferChange();
expect(registryInternals.pendingEviction).toBeNull();

runtime.container = null;
emitBufferChange();
expect(registryInternals.pendingEviction).not.toBeNull();

if (registryInternals.pendingEviction !== null) {
clearTimeout(registryInternals.pendingEviction);
registryInternals.pendingEviction = null;
}
entry.disposeBufferChangeListener?.();
expect(listenerDisposed).toBe(true);
});

test("defers eviction while flushed output is still being parsed", () => {
const terminalId = "parser-busy-terminal";
let flushed = false;
const gate = { pending: 1, queued: null as (() => void) | null };
const entry = {
terminalId,
instanceId: terminalId,
runtime: {
container: null,
gate,
terminal: { buffer: { active: { type: "normal" } } },
},
transport: {
_writeCoalescer: {
flushSync: () => {
flushed = true;
},
},
},
linkManager: null,
pendingLinkHandlers: null,
lastUsedAt: 1,
};
const registryInternals = terminalRuntimeRegistry as unknown as {
entries: Map<string, typeof entry>;
evictExcessParkedRuntimes: () => void;
};
const entryKey = `${terminalId}\u0000${terminalId}`;
registryInternals.entries.set(entryKey, entry);

try {
registryInternals.evictExcessParkedRuntimes();

expect(flushed).toBe(true);
expect(gate.queued).not.toBeNull();
expect(registryInternals.entries.has(entryKey)).toBe(true);
} finally {
registryInternals.entries.delete(entryKey);
}
});
});
Loading
Loading