Fix standalone localStorage WAL bloat: Rust per-window session store

[nedtwigg]

Problem

The standalone (Tauri/WKWebView) app persisted its session blob (dormouse.session, multi-MB scrollback) into WebKit localStorage, rewritten on every save (a 500 ms-debounced save plus an unconditional 30 s heartbeat). WebKit stores localStorage as SQLite in WAL mode and pins its own WAL with a long-lived reader that never advances during a running session, so the WAL is never checkpointed and grows unbounded — observed ~1 GB after a few hours (~8 GB/day), and an external checkpoint is blocked by the same reader. Over a multi-day run this is pathological.

Diagnosis detail: PRAGMA wal_checkpoint(PASSIVE) against the live DB moved 0 of ~249k frames (a reader pins frame 0); it only truncates once WebKit closes the store (app quit). So the fix cannot be an external checkpoint — the blob has to leave WebKit localStorage.

Fix — a common seam, two host-native backings

Persistence already flows through the PlatformAdapter.saveState/getState seam. This keeps that seam and re-backs standalone below it:

• VS Code already persists host-natively (extension host workspaceState / per-panel vscode.setState()) — the host owns which window is which. Unchanged; it's the reference.
• Standalone now persists via Rust: save_session / load_session write one atomic file per window (<app_data_dir>/sessions/<label>.json, temp-then-rename). Window identity is implicit — Rust keys by the invoking tauri::Window label, so the frontend stays window-agnostic and the store is multi-window-ready even though one window ships today. No WAL, no checkpoint, no unbounded growth.

New SessionKeyValueStore seam in window-persistence.ts: the browser-dev sidecar keeps localStorage (plain Chromium, no WAL issue); the real app supplies TauriSessionStore, an in-memory write-through cache seeded once at boot so getState() stays synchronous (cold-start restore reads it before React mounts), with writes forwarded async and coalesced to one in-flight save_session.

Migration: first boot after this change adopts any legacy localStorage blob into the Rust store and clears the key, so WebKit stops rewriting it and the bloated WAL collapses on the next quit.

Scope note

This is part 1 of 2. It removes the unbounded-growth pathology. Reducing write throughput (skip unchanged saves, drop the unconditional 30 s heartbeat, cap persisted scrollback) is a follow-up — now a pure IO-efficiency task, no longer a bloat fix.

Tests

• Rust: file round-trip, per-window isolation, atomic overwrite, path-escape sanitization.
• TS: sync cache read, burst coalescing (first + latest wins), recovery after a rejected write.
• tsc (lib + standalone), pnpm lint:specs, full standalone + lib persistence suites green.

Specs updated: standalone.md §Persistence (rewrite), transport.md (seam), command list + Files table.

Not yet done: an end-to-end run in a real rebuilt app (file creation, restore across quit, WAL no longer growing) — the reviewer/author can dogfood via dev:standalone.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	5a0e876
Status:	✅  Deploy successful!
Preview URL:	https://2d7bc54d.mouseterm.pages.dev
Branch Preview URL:	https://fix-standalone-bloat.mouseterm.pages.dev

View logs

[dormouse-bot]

The atomic Rust file store is a clean fix for the WAL bloat, and the boot-seeded write-through cache correctly preserves the synchronous getState() contract. The coalescing state machine and its tests read well. One design consideration worth an explicit decision before this lands:

Standalone loses the last save on quit — a durability property localStorage used to provide. The old TauriAdapter.saveState went through localStorage.setItem, which is synchronous and durable on return (that durable-per-write behavior is exactly what grew the WAL). The new saveState updates the in-memory cache and fires save_session asynchronously, returning before the Rust write lands. Nothing on the shutdown path waits for that write:

• onRequestSessionFlush / notifySessionFlushComplete are no-ops in tauri-adapter.ts (that flush-and-wait handshake is only wired for VS Code panel disposal).
• TauriSessionStore has no drain/await; TauriAdapter.shutdown() doesn't call one.
• RunEvent::Exit in lib.rs only shuts down the sidecar.

So the pagehide handler and the unmount-time persistSessionNow() in use-session-persistence.ts resolve as soon as the synchronous saveState returns — the fired save_session invoke can be dropped when the webview tears down. Net effect: on a clean quit, the delta since the last completed async write (up to one debounce/heartbeat cycle) is lost, where before it was always durable.

This may well be an acceptable trade for part 1 — scrollback restore is best-effort and saves are frequent — but it's a real behavioral change from the localStorage baseline with no drain-on-quit to replace it, so it seems worth a conscious call rather than a silent side effect. (I haven't run a rebuilt app to confirm the invoke is actually dropped at quit — the PR notes e2e testing is still pending — but the synchronous-durability guarantee is gone at the code level regardless.)

Same shape, smaller: the migration at tauri-adapter.ts:190-193 clears the legacy localStorage key immediately after firing save_session without awaiting it. This is mostly self-healing because the cache is seeded with the same blob (hydrate(seed)), so the next normal save re-persists it — the only true loss is migration-invoke-dropped and quit before any subsequent save. Routing the migration write through the store (or draining the store on quit) would cover both cases at once.

Not blocking — flagging for your judgment on whether the last-save-on-quit window is acceptable for this stage.

[nedtwigg]

Good catch, and the diagnosis is accurate — the synchronous-durability guarantee is gone at the code level. saveState fires save_session and returns; the flush handshake is a no-op on Tauri, shutdown() has no caller, and onCloseRequested only prevents default for a pending update, so a clean quit can drop the pagehide save.

Conscious call: accept the bounded window for this PR, land the proper drain in part 2. The lost delta is state changed in the final debounce/heartbeat window (≤500 ms for anything that triggers a layout save; up to the heartbeat for pure-scrollback drift), affecting only cold restore on next launch — best-effort by design. The reliable fix can't live in pagehide (browsers won't await async there); it has to intercept onCloseRequested → preventDefault → final flushSessionSave() → await store.drain() → close, bridging the React save hook, the store, and the updater-owned close path with its Windows ordering. That's the same path part 2's save-path rework (write-on-change + heartbeat removal) reshapes, so it belongs there.

Done now in 5a0e876:

• Routed the one-time migration write through the store's setItem (one write path; it'll participate in the future drain) — covers your smaller point.
• Documented the trade in standalone.md §Persistence as a current limitation, and added ## Future "Drain-on-quit for the session store" with the exact plan above.

Thanks for the review.