perf(remote): bound live transcript retention for unviewed sessions

[Juliusolsson05]

Confirmed with synthetic live feed events at 5d641845 (Node v24.14.1, macOS arm64). Priority: medium for Remote users with long-lived/multiple agents. No private transcript or live app was used.

Expected and actual behavior

The phone should retain a bounded live transcript window, and should not accumulate full transcripts for every session the user has never opened. Older content should remain available through durable pagination.

TranscriptStore constructor ingests all sessions' live entries independently of view subscriptions. ingestRawEntries retains every UUID in seen, inserts tool objects into unbounded indexes, and copies/appends the entire entries array for every burst. There is no live entry count/byte window here. Session-list removal, transcript roll, and store disposal clear state, but simply not viewing a still-live session does not.

The desktop already has liveEntryWindow (2,000-entry and 32 MiB triggers with ownership constraints). The phone reuses several desktop reducers but does not apply that retention discipline.

Reproduction and measurements

Instantiate the actual TranscriptStore with a fake feed that captures the registered event callbacks, lists one synthetic Claude session, and has zero view subscriptions. Use the real Claude transcript mapper and real indexEntryIntoMaps/empty state helpers. Deliver 4,096 unique newline-equivalent assistant entries through onSessionJsonlEntries, each containing one unique Read tool call and an 8,192-character ASCII text block. Use a stable synthetic transcript filename.

The harness transpiled the store source in memory, substituted only the renderer capability registry with the actual Claude mapper factory, and left unused semantic-event modules inert. No semantic events were exercised.

Delivered entries	Retained entries	Retained text bytes	Tool-use index	Seen UUIDs	View subscribers
1,024	1,024	8,388,608	1,024	1,024	0
2,048	2,048	16,777,216	2,048	2,048	0
4,096	4,096	33,554,432	4,096	4,096	0

These are retained logical payload sizes and collection cardinalities, not browser heap measurements. Tool input bodies, object/index overhead and semantic state are additional, unmeasured costs. The test stops after 4,096 entries; there is no eviction branch in this append path.

User impact and next steps

Memory grows with all received conversation/tool output while sessions remain live, even on the list screen. Phone tab reloads/termination under memory pressure and increasing append/render cost are plausible consequences; no actual mobile crash or FPS regression was measured.

• Introduce byte- and count-bounded live retention with a smaller budget for unviewed sessions, or negotiate server interest and backfill on selection.
• Keep entry, seen-id, tool-use/result indexes, pagination marker/offset, and semantic ownership state consistent when trimming. Never merely slice entries while leaving indexes holding the same bodies.
• Share the desktop retention policy where practical, but explicitly adapt its ghost/history/live-turn invariants to the remote store rather than importing the entire desktop workspace.
• Preserve paginated history and retry/reconnect semantics. Trimming must not cause duplicate rows or tool results to lose their owners.
• Add a regression covering sustained large entries on several unviewed sessions, bounded cardinalities/bytes, later selection/backfill, and session removal.

Tradeoff: smaller retained windows increase backfill requests and may affect scroll position; no estimated percentage improvement is claimed. This is independent of the main-process socket queue bound and of B7's #795 external operator implementation.

Refs #103, #375, #475.

Related transport backlog issue: #804. A bounded send queue does not limit what a healthy receiving phone retains.

[Juliusolsson05]

Implementation: #814, based on #813.

The phone previously accumulated every live transcript even on the session list. Transcript ownership now follows actual view subscriptions: unviewed JSONL/semantic bodies are not mapped or retained, and leaving the last view releases entries, tool indexes, mapper/fold state and identity sets. Selecting the session again backfills durable history and rejects stale pending responses.

Fixes #805
Refs #813

Dependency: incremental PR against fix/remote-output-backpressure (#813). Merge #813 first, then retarget this PR to main and rerun checks. No merge is currently authorized. No protocol migration, desktop/worktree edits or toolkit changes.

Acceptance criteria

• Several unviewed sessions retain zero transcript entries, tool indexes, seen UUIDs and semantic bodies; metadata remains available.
• Last-unsubscribe, reselect, rolled file identity, stale requests and session removal have behavioral coverage. Partial semantic suffixes wait for a fresh turn; committed content remains authoritative.
• Viewed live windows reuse the desktop pure count/estimated-byte trim planner (2,000 entries / 32 MiB triggers; 1,500 / 24 MiB targets), preserving semantic owners and tool pairs. Remote bookkeeping does not use desktop global registries.
• Indexes rebuild from retained entries in chronological order. Trimmed identities suppress old live replays but allow older pages to reload them in order.
• Exact history offsets survive trimming and all-duplicate pages; raw-record fan-out is not split. Paging/grace protects recently requested older content. Total entry count remains independent of the retained window.

Validation and reproducible evidence

• 137 local tests / 14 files pass: all remote transport/store tests plus shared entry/trim tests. Ten new retention regressions exercise real Claude, Codex and OpenCode mappers and semantic folds.
• The unviewed regression fails on parent fix(remote): bound outgoing queues and recover after overflow #813 with 4,096 retained entries. Fixed: three synthetic sessions each receiving 4,096 entries / 32 MiB logical ASCII text retain zero entries, indexes and UUIDs. These are collection/payload measurements, not production heap savings.
• A 2,100-entry live burst retains 1,500 entries with matching indexes; 300 entries of 128 KiB each trigger byte trimming below the count threshold. Tests verify replay suppression, chronological reload, tool pairs, semantic owners and exact cursor offsets.
• Typecheck, test contract, client production build and diff check pass. Full applicable repository checks pass in CI. Existing bundle size/mixed import warnings remain.

Limits and tradeoffs

Safety constraints (active/history semantic ownership, tool pairs, missing stable identity/anchor and whole raw records) can pin a viewed window above its nominal target. Older-history reading has a 30-second trim grace. Small UUID-only tombstone sets grow during a continuously viewed session to preserve exact replay deduplication; all are released when that view ends. Live wire entries lack byte offsets and retain provider-marker fallback; history pages use exact offsets when supplied. Re-selection costs a backfill and an interrupted live turn may wait for durable completion. Mobile heap/FPS gains remain unmeasured.

Plan committed before code: docs/superpowers/plans/2026-09-05-remote-transcript-retention.md.

Current validation: rebased onto main f7507980 (toolkit #812 and MCP repair #818), head 6230658d. Source changes from the earlier implementation are preserved; both required CI gates pass on this head (CI run). No merge is authorized. The initial CI packaging failure reproduced with an unbuilt parser checkout and is fixed by resolving agent-transcript-parser/ghost to pinned source in the remote Vite config. The same unbuilt checkout now passes the full local package gate; no shared parser build or pane layout was changed.

2026-09-07 merge status: PR #814 now targets main after its parent merged; unchanged patches were rebased to c4f175f0 and fresh CI is running. Merge is authorized once green.

Merged with explicit user authorization on 2026-09-07 as 13258ffa after both current-head CI gates passed. No outstanding review feedback. The resolving issue is closed.