perf(mobile): thread list resumes from the saved cache, and large gaps reload over gzip HTTP#32287

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Shell cache records now include origin metadata. The client uses this metadata to decide whether to resume a cached snapshot. When a resume requires a snapshot, the server can signal the client to load one over HTTP and resubscribe.

Changes: Shell resume and snapshot fallback

Layer / File(s)	Summary
Resume contracts and cache metadata packages/contracts/src/orchestrationV2.ts, packages/client-runtime/src/platform/orchestrationCache.ts, packages/client-runtime/src/platform/persistence.ts, apps/mobile/src/connection/environment-cache-store.ts, apps/mobile/src/connection/environment-cache-store.test.ts, apps/web/src/connection/storage.ts	The shell stream contract adds snapshot-required and the optional httpSnapshotFallback input. Cache types and mobile and web stores support optional origin metadata. The mobile test checks that the metadata survives a save and load.
Server snapshot fallback apps/server/src/ws.ts, apps/server/src/ws.test.ts	When a shell resume requests HTTP snapshot fallback, the server emits snapshot-required instead of loading and streaming a shell snapshot. Tests cover both fallback and the existing snapshot behavior.
Client cache validation and reload packages/client-runtime/src/state/shell.ts, packages/client-runtime/src/state/shellReducer.ts, packages/client-runtime/src/state/shell-sync.test.ts	The client resumes cached rows only when origin identity matches and the snapshot is less than 12 hours old. It handles snapshot-required by reloading over HTTP, updates cache origin metadata, and filters stream items by active subscription. Tests cover eligible and ineligible cached origins and cold and warm fallback paths.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

mermaid

1	sequenceDiagram
2	participant ShellSync
3	participant subscribeOrchestrationV2Shell
4	participant HTTPSnapshotLoader
5	participant EnvironmentCacheStore
6	ShellSync->>subscribeOrchestrationV2Shell: Subscribe with cursor and HTTP fallback
7	subscribeOrchestrationV2Shell-->>ShellSync: Emit snapshot-required
8	ShellSync->>HTTPSnapshotLoader: Load authoritative snapshot
9	HTTPSnapshotLoader-->>ShellSync: Return snapshot
10	ShellSync->>EnvironmentCacheStore: Save snapshot with origin
11	ShellSync->>subscribeOrchestrationV2Shell: Resubscribe from snapshot sequence

Possibly related PRs

• pingdotgg/t3code#30732: Implements an earlier cursor-resume design with cache metadata and a 12-hour age check.
• pingdotgg/t3code#24704: Implements a parallel cursor-resume design with a different cache basis and age limit.
• pingdotgg/t3code#26556: Adds server-version validation for cached shell resume.

Suggested reviewers: bil0000, saphid, t3dotgg

The change lets cold starts resume from the saved cache and falls back to the gzip HTTP snapshot when replay is not possible. No concrete merge-blocking defect was established.

^Failed Failed checks: 1 inconclusive

Check name	Status	Explanation	Resolution
Description check	Inconclusive	The description follows the repository template closely. It covers the problem (cold-start full thread-list downloads and uncompressed over-cap socket snapshots), the change (cache origin, afterSequen…	Add a link to the triaged issue or to the discussion that records explicit maintainer approval of the direction and scope, including the approval comment. The author states the work was done at the maintainers' direction, but the template r…

^Passed Passed checks: 3 passed

Check name	Status	Explanation
Title check	Passed	The title names the two main changes: the thread list resumes from the saved cache on cold start, and large replay gaps reload over gzip HTTP. The raw summary confirms both: cache origin with afterSeq…
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.

Full details: Title check

Explanation

The title names the two main changes: the thread list resumes from the saved cache on cold start, and large replay gaps reload over gzip HTTP. The raw summary confirms both: cache origin with afterSequence resume, and the snapshot-required fallback that loads an HTTP snapshot. The title follows the conventional commit format and is specific to the changeset.

Full details: Description check

Explanation

The description follows the repository template closely. It covers the problem (cold-start full thread-list downloads and uncompressed over-cap socket snapshots), the change (cache origin, afterSequence resume, httpSnapshotFallback and snapshot-required, loop guard, generation bump and buffered-item drop), and scope with a link to the superseded PR and a statement that the change is maintainer-authored. Verification is detailed: named test files and cases, a mutation-style check (reverting the loop guard fails 6 cases), web manual traces against a copy of a real database, and a screenshot. Measurements are reported with medians and methods. Gaps: the Scope and approval section does not link a triaged issue or a discussion with explicit maintainer approval comment. It states the work is maintainer-authored and was done at the maintainers' direction, but no approval comment is linked. The template requires that link or the explanation that the change qualifies as a small obvious fix, and this change is a broad performance and protocol change, so the approval evidence matters. The template also asks for the model and harness used, and the description ends with a 'Built by' line that names models and Claude Code, which satisfies that request. The screenshot is hosted on a file-drop URL, not GitHub, and the template says to upload evidence to GitHub. The UI change here is minor, since the PR is primarily protocol and sync behavior, so the screenshot is supplementary.

Resolution

Add a link to the triaged issue or to the discussion that records explicit maintainer approval of the direction and scope, including the approval comment. The author states the work was done at the maintainers' direction, but the template requires the approval evidence itself. Alternatively, explain why this change qualifies without prior approval. Because this PR changes the stream protocol (a new httpSnapshotFallback flag and a snapshot-required item), it is not a small obvious fix. Also move the screenshot from the file-drop host to GitHub, or confirm that the screenshot is evidence the template accepts. Keep the existing verification, measurements, and model/harness attribution.

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.