Client caches: skip unchanged writes, then store rows instead of whole values

[josephv123]

Note

Claude Opus 5.5 in Claude Code, writing on behalf of @josephv123. Following up on #21300, as suggested there.

Problem

The client saves each cache to IndexedDB as one whole value, at most every 10 s while changes arrive (packages/client-runtime/src/state/cachePersistence.ts). On @josephv123's Mac (T3 Code Nightly 0.1.1-nightly.20261018.3315, connected to its local server and two Linux servers), macOS filed five "disk writes" reports against the app's main process, which hosts IndexedDB, between Oct 11 and 17. Four were 2.1–8.6 GB over 2.3–5.4 h (187–441 KB/s). One was 2.1 GB in 69 s at startup, possibly a different cause.

Value sizes, decoded from the app's IndexedDB:

Cached value	JSON chars	Serialized	On disk per save
Open thread (693 items)	3,179,429	6.36 MB (UTF-16)	1.39 MB
acerlinux shell (459 threads)	969,246	1.94 MB (UTF-16)	237 KB
lenovolinux server config	285,251	570 KB (UTF-16)	175 KB
lenovolinux shell (23–25 threads)	56,279–65,020	56–65 KB (Latin-1), inline in LevelDB	113–130 KB with LevelDB's undo copy

Every shell, config and thread save captured in 43 minutes (16:15–16:58 EDT on Oct 18, with subagents running on lenovolinux):

Cache entry	Saves	Written to disk
Open thread	26	40.6 MB
lenovolinux shell	80	9.8 MB
acerlinux shell	8	1.9 MB
Mac-local shell	4	0.3 MB
Server configs (3)	17	2.5 MB
Total	135	55.0 MB

What #21300 established

• The triage confirmed three things: the shell is saved again when only snapshotSequence moves, the server config is saved without comparing it with the last save, and a saved thread stores each visible item twice.
• The triage was right that the open thread was not idle. Every one of its saves above carried real changes (subagent progress, updatedAt, lastVisitedAt).
• The 10 s throttle is the intended design. Nothing below changes it.

Checked on main: the saved cursor isn't used to resume

The triage noted that a sequence-only shell save matters because the stored sequence is the resume point. Checking that on main @ e2cc34f, the saved cursor doesn't seem to be read on resume:

• A new session, at startup or after a reconnect, first reloads the shell over HTTP and resumes from the reloaded snapshot's sequence. Without an HTTP snapshot, it subscribes with no afterSequence, and the server starts with a full snapshot (packages/client-runtime/src/state/shell.ts:334-375, since fix: prevent reconnect loops during server stalls #5561; apps/server/src/ws.ts:1102-1108).
• A resubscription on the same session resumes from the in-memory cursor, which keeps advancing whether or not the cache is saved.
• The only reader of the saved shell is the state's initial value, used for first paint (state/shell.ts:77).
• Tests: the existing "refreshes a warm shell cache from HTTP before resuming" resumes after 9 (the HTTP snapshot), not 5 (the cache). The prototype adds "does not resume a new session from the saved cursor": with no HTTP snapshot, the subscription carries no cursor. Forcing canResume = true makes that test fail with [5].

Where the unchanged saves come from

Matched against the app's client trace spans:

• Window becomes visible. Each visibilitychange (on mobile, returning to the foreground) resubscribes every environment's shell. The resume re-sends project metadata, and mergeShellSnapshotProjects builds a new snapshot with the same rows. The window became visible four times in five minutes, and the acerlinux and Mac-local shells were saved unchanged six times in that span.
• Reconnect. The HTTP reload brings the same rows, sometimes in another order (174 of 459 at 16:23:20).
• Config. Theme and usage-limit source pushes change only fields the cache drops, and reconnect snapshots equal the stored config. 7 of 17 config saves were byte-identical to the save before.
• No save in this window moved only the cursor, but that path exists (state/shellReducer.ts:166).

Options, smallest first

	Option	Effect	Cost
1	Skip a save whose stored value is unchanged	In the capture: 135 → 118 saves, 55.0 → 52.3 MB on disk (−5%), and 214 → 198 MB serialized	About 50 lines in client-runtime, no format change: prototype
2	Persist the resume sequence on its own	Needed only if the cache should become a resume point. A cursor move would then write a few bytes instead of the shell.	Small
3	One record per shell row and per thread item	A running thread writes its own row or item instead of a 56 KB to 6.4 MB value. Most of the bytes above are here.	Cache schema change and migration
4	Store each thread item once	turnItems and visibleTurnItems[].item hold 1.11 M and 1.26 M chars of the open thread's 3.18 M	Thread cache schema change
5	UTF-8 or compressed bytes	A few characters above U+00FF make V8 store the whole value as UTF-16, doubling its serialized size. The disk gain is smaller, because Chromium already compresses blobs.	Encoding change

The prototype compares the shell's rows by id, plus its projects and schema version, ignoring the cursor and row order. It compares the config with Equal.equals. Decoded settings hold Duration values, which identity and reuseUnchanged treat as changed after every reconnect. It adds seven tests, and all except the resume-point test fail on main. The first save after startup, the 10 s throttle, and the flushes on disconnect are unchanged.

Question

Which of these would you take as a PR? Is option 1 acceptable on its own, as in the prototype? Should options 3 and 4 be designed here first?