perf(mobile): omit duplicated turn items from bounded thread snapshots

[juliusmarminge]

Stacked on #15248.

Problem

A bounded thread snapshot sends each local visible row's item twice: once in visibleTurnItems and again in projection.turnItems. That duplication makes up roughly 30–45% of the raw JSON a phone downloads, parses, and decodes when it opens a thread.

Fix

Clients can now opt in to a compact snapshot: compactTurnItems=1 on GET /api/orchestration/threads/:id/bounded, or acceptCompactTurnItems on the thread subscription. The server then drops the leading turnItems entries that repeat local visible rows and marks the snapshot turnItemsOmitLocalVisible. The client rebuilds them with boundedSnapshotProjection right after decode, so reducers, the cache, and live events still see the full list.

• The server compacts only when the leading turnItems are exactly the local visible rows' items (same object). Otherwise it sends the unchanged snapshot with no marker.
• Compatibility holds across versions. Older clients never opt in. Older servers ignore the query or flag and send no marker, and the client restores only when the marker is present.
• The byte budget still charges the omitted items, so the history window is the same with or without the opt-in.
• The cache format is unchanged: snapshots are restored before they reach the cache.

Measurements

Synthetic fixtures seeded through the real EventSink into a scratch DB, run against this branch on nucbox-1 (Node 24, x86_64), medians of 25 iterations. "Before" is the opted-out response, which is byte-identical to the base branch. "After" is the opted-in response. Node parse+decode is JSON.parse plus schema decode. Restore adds boundedSnapshotProjection. Every fixture round-trips to the identical projection after restore.

Fixture	Raw before → after	gzip before → after	br before → after	Node parse+decode before → after (ms)	after + restore (ms)
plain (20 rows)	72.0 → 49.7 KB (−31%)	5.9 → 5.5 KB (−6%)	5.8 → 5.7 KB (−2%)	0.50 → 0.35	0.36
tool-small (130)	250.8 → 149.3 KB (−40%)	29.9 → 18.7 KB (−38%)	16.4 → 14.7 KB (−10%)	2.08 → 1.30	1.22
tool-large (140)	746.3 → 405.1 KB (−46%)	120.8 → 65.7 KB (−46%)	38.1 → 34.7 KB (−9%)	2.52 → 1.40	1.41
many-tools (830)	964.6 → 549.7 KB (−43%)	68.4 → 39.8 KB (−42%)	32.6 → 21.9 KB (−33%)	11.62 → 6.15	6.30
fork-child (131)	172.2 → 131.9 KB (−23%)	19.9 → 16.1 KB (−19%)	13.8 → 13.4 KB (−3%)	1.50 → 1.16	1.13
interrupts (138)	261.4 → 156.5 KB (−40%)	31.4 → 19.7 KB (−37%)	17.6 → 15.2 KB (−14%)	2.34 → 1.32	1.35
agent-turns (780)	1495.1 → 885.7 KB (−41%)	166.8 → 100.2 KB (−40%)	54.3 → 57.5 KB (+6%)	12.71 → 7.05	7.14
turnless (75)	80.7 → 45.6 KB (−44%)	6.4 → 4.0 KB (−39%)	4.1 → 3.1 KB (−23%)	0.96 → 0.53	0.53

Limits:

• Brotli already removes much of the duplication, so savings over br are small. On agent-turns, br output is 6% larger.
• The timings come from Node on a desktop CPU, not a phone. Tap-to-content on a real device has not been measured yet.
• This PR makes no battery claim.

Evidence (synthetic data only): script, results and log (tgz) · README with reproduction steps · results.json

Verification

Focused tests and typechecks passed for the touched packages: shared (6), client-runtime (49), contracts (34), server (44), projection (5). They cover the omit/restore round-trip, the identity guard, the HTTP and WS opt-in in both directions across versions, and client restore before reducers and the cache.

Implemented by Claude Opus 5.5 in Claude Code (T3 Code).

🤖 Generated with Claude Code

Native runtime follow-up

Alternating compact off/on in the iOS 27 simulator, using the matching native build and a Hermes debug bundle against the isolated nucbox fixture server over Tailscale. Three samples per mode per fixture, JS reload each time and synthetic-thread cache bypassed.

Fixture	Tap to populated feed commit, median	HTTP request + decode, median
Large tool results	474 → 429 ms	242 → 188 ms
Many tool items	541 → 470 ms	301 → 233 ms

The endpoint is the populated React feed's layout-effect commit, not a confirmed displayed frame. Small sample sizes and overlapping results make these preliminary; they are not physical-device, release-build, 1.4 comparison, or battery measurements. Separate Hermes captures show substantial React opening work but only 17 ms sampled non-idle JS over 15 seconds on a settled thread with one connected environment.

Native measurements, diagnostic patch, automation, and method. Temporary instrumentation was removed after measurement.

---

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	4.9 KiB	5.0 KiB	+23 B (+0.5%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	+23 B (+1.9%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.8 KiB	20.9 KiB	+41 B (+0.2%)	29.3 KiB	✅
Codex	Live turn messages	1	2	+1 (+100.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	1	1	0 (0.0%)	8	✅

Baseline: 6053a78 · PR result: 38b945b · Source CI: success

Scenario and decoded snapshot size

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

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Approved at 38b945b

Macroscope's review found this PR approvable — This is a focused, backward-compatible snapshot transport optimization: opted-in clients receive a smaller payload and restore the unchanged projection before application state uses it. Legacy clients and servers retain the existing representation, with coverage for HTTP, WebSocket, forked histories, and cache/reducer restoration.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Team
• Run ID: 96ab785c-0e8b-4e02-b4e5-59b3553361b3

📥 Commits

Reviewing files that changed from the base of the PR and between 918cf5f and 96698d5.

📒 Files selected for processing (4)

• apps/server/src/ws.ts
• packages/contracts/src/orchestrationV2.test.ts
• packages/contracts/src/orchestrationV2.ts
• packages/shared/package.json

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds compact bounded snapshots that omit eligible local visible turn items and mark the omission. HTTP and WebSocket paths support opt-in negotiation. Client code restores omitted items before using the projection.

Changes

Compact bounded snapshots

Layer / File(s)	Summary
Snapshot contract and restoration packages/contracts/src/orchestrationV2.ts, packages/contracts/src/environmentHttp.ts, packages/shared/src/orchestrationV2BoundedSnapshot.ts, packages/shared/src/orchestrationV2BoundedSnapshot.test.ts, packages/contracts/src/orchestrationV2.test.ts, packages/shared/package.json	The contracts define compact-snapshot negotiation and an optional omission marker. Shared helpers omit eligible local visible turn items and restore them when the marker is present. Tests cover ordering, identity, JSON round-trips, and compatibility cases.
Server compact snapshot responses apps/server/src/orchestration-v2/ThreadStream.ts, apps/server/src/orchestration-v2/http.ts, apps/server/src/ws.ts, apps/server/src/orchestration-v2/ThreadStream.test.ts, apps/server/src/orchestration-v2/boundedSnapshotTransport.test.ts	The HTTP and WebSocket paths pass compact-snapshot opt-ins to the shared response builder. Tests compare compact and legacy responses, including forked threads and retained interrupt requests.
Client snapshot restoration packages/client-runtime/src/state/boundedThreadSnapshotHttp.ts, packages/client-runtime/src/state/boundedThreadSnapshotHttp.test.ts, packages/client-runtime/src/state/threads.ts, packages/client-runtime/src/state/threads-sync.test.ts	The HTTP loader requests compact items and restores marked responses. Socket snapshot installation restores omitted items before reduction and persistence, and subscriptions request compact snapshots.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Suggested reviewers: yash-singh1

Sequence Diagram(s)

sequenceDiagram
  participant Client as fetchEnvironmentBoundedThreadSnapshot
  participant Endpoint as threadBoundedSnapshot
  participant Builder as boundedSnapshotResponseFields
  participant Restorer as boundedSnapshotProjection
  Client->>Endpoint: Request compactTurnItems=1
  Endpoint->>Builder: Build compact bounded response
  Builder-->>Endpoint: Projection and omission marker
  Endpoint-->>Client: Bounded snapshot response
  Client->>Restorer: Restore marked projection
  Restorer-->>Client: Projection with local visible items

Loading

Merge Risk: ⚪ Minimal · up to 96698

The compact snapshot path is connected end to end, with no identified issue requiring a fix before merge.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the problem, change, compatibility behavior, measurements, and verification. It does not include the required Scope and approval information, such as a triaged issue or mainta…	Add a Scope and approval section. Link the triaged issue or maintainer discussion with explicit approval, or explain why this focused change qualifies for an exception under the template.
Docstring Coverage	⚠️ Warning	Docstring coverage is 47.06% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 14 files. (1 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: omitting duplicated turn items from bounded thread snapshots.
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: Description check

Explanation

The description explains the problem, change, compatibility behavior, measurements, and verification. It does not include the required Scope and approval information, such as a triaged issue or maintainer approval, or an explanation of why the change qualifies for an exception.

Full details: Docstring Coverage

Explanation

Docstring coverage is 47.06% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 14 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}