feat: paginate thread loading with user-anchored turn windows

[t3dotgg]

Problem

Long threads are heavy to open, especially on mobile. The heaviest observed thread (161 turns, 23k activities) ships 8.4MB of JSON on every open, all of which must be parsed, held in client state, and persisted to the mobile cache. On many-turn threads, the most recent 10 turns are only 2-6% of the bytes.

Solution

Opt-in pagination of the thread detail snapshot, cut on user-anchored turn boundaries:

• Server: GET /api/orchestration/threads/:id accepts turnLimit + beforeCursor. The window is everything from the Nth-last turn-with-a-user-pending-message onward, so subagent/fan-out turns ride along and the first page always contains the last N user prompts (verified against real data: fan-out bursts run 35+ consecutive subagent turns). Responses carry page: { beforeCursor, hasMore, snapshotSequence } with an opaque exclusive cursor returning disjoint older slices. A 150-raw-turn ceiling bounds pathological fan-out. The WS fallback snapshot honors the same opt-in via the subscription input.
• Compatibility: pagination is strictly opt-in and capability-gated (threadSnapshotPagination in server config). Old client + new server and new client + old server both keep full-snapshot behavior.
• Shared client state: initial loads request the last 10 user turns; loadOlderTurns fetches 20 more per call. Consistency rules: a fresh snapshot replaces all loaded history (no stale-revert resurrection), in-flight pages are discarded when a revert/snapshot/deletion rewrites history or when the page was read from a projection behind the loaded state, and merged pages never advance the live-event dedupe sequence. All covered by state-machine tests.
• UI: a plain "Load earlier turns" header row on web and mobile; LegendList's maintainVisibleContentPosition anchors scroll on prepend.

No schema migration: the migration-029 indexes cover the bounded queries (verified with EXPLAIN QUERY PLAN against a 45k-activity fixture; worst-case bounded reads run in single-digit ms).

Measured on the heaviest real thread: initial fetch drops from 8.4MB to 1.0MB wire (~1/8th), and a full page-by-page walk reproduces the exact row set of an unwindowed fetch with zero overlap between pages.

Testing

• 7 new server tests for window resolution, cursor semantics (foreign/malformed cursor degradation, disjointness/coverage walk), and the turnless-thread edge case
• 7 new client state-machine tests for the race rules
• Full server (1880) and client-runtime (615) suites green; typecheck and lint clean across the workspace
• Live smoke against the seeded worktree db: windowed first page returns exactly the last 10 user messages with hasMore, older pages are disjoint, full walk covers all 815 messages

---

Implemented by Claude Fable 5 via Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches core thread sync, projection queries, and cache semantics; mistakes could drop history, duplicate streaming text, or serve wrong pages, but behavior is opt-in, capability-gated, and heavily tested.

Overview
Adds opt-in, capability-gated thread detail pagination so long threads open with a small recent window instead of the full history.

Server exposes turnLimit and beforeCursor on HTTP thread snapshots and WS subscribe fallbacks. Windowing walks back user-anchored turns (subagent turns ride along), returns page metadata with an opaque keyset cursor, and uses a new projection_turns keyset index. Malformed or foreign cursors degrade to the first page.

Client-runtime loads the last 10 user turns initially and fetches 20 more per “load earlier” via requestOlderThreadTurns, with epoch/lock/watermark rules so reverts, fresh snapshots, and stale pages cannot corrupt merged history. Thread cache schema bumps to v3 so old clients cannot treat a partial window as complete.

Web and mobile show a Load earlier turns control in the thread feed when hasMore is set.

^{Reviewed by Cursor Bugbot for commit 95cd34a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Paginate thread loading with user-anchored turn windows on client and server

• Adds windowed thread snapshot loading to the server (ProjectionSnapshotQuery, HTTP and WS handlers), returning only the last 10 user-anchored turns initially and supporting cursor-based older-page fetches of 20 turns at a time.
• Extends EnvironmentThreadState with pagination state (page, loadingOlder, hasMore, cursor) and adds requestOlderThreadTurns / threadHasOlderTurns helpers in the client-runtime state machine.
• Introduces a semaphore (applyLock) and epoch/watermark guards in the thread state machine to prevent stale or interleaved older-page merges from corrupting live history.
• Surfaces a "Load earlier turns" header control in both the web (MessagesTimeline) and mobile (ThreadFeed) UIs, wired to requestOlderThreadTurns and reflecting loading state.
• Adds a new DB migration (037_ProjectionTurnsKeysetIndex.ts) creating a composite keyset index on projection_turns(thread_id, requested_at, turn_id) to support efficient paginated queries.
• Bumps the thread snapshot cache schema version from 2 to 3; existing v1/v2 cached entries will fail to decode and trigger a full reload.
• Risk: clients connected to servers that do not advertise threadSnapshotPagination in ServerConfig will have any windowed cache discarded and reload the full thread history.

^{Macroscope summarized 95cd34a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7ec277cf-6f61-408f-a3c7-14e9c2edeaaa

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[macroscopeapp]

Effect service conventions review of the changed TypeScript. One finding: the new UI-to-state-machine channel in packages/client-runtime/src/state/threads.ts routes through mutable module-global state instead of the Effect environment. Server-side additions (threadDetailCursor.ts, windowed ProjectionSnapshotQuery queries, contract/schema additions) follow the import, error, and dependency-acquisition conventions; test harnesses pass service instances explicitly, which is an allowed test seam.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a substantial new pagination feature for thread loading with complex state management, new API parameters, and multi-platform UI changes. Additionally, there is an open bug report about the loading state getting stuck on disconnect. Human review is appropriate for this scope.

No code changes detected at 95cd34a. Prior analysis still applies.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Parked page sticks loading offline

Medium Severity

The pendingOlderPage state, which holds a parked page and keeps loadingOlder true, isn't cleared when the connection disconnects or encounters a stream error. This leaves the UI stuck on "Loading earlier turns..." and prevents subsequent attempts to fetch older history.

Additional Locations (1)

• packages/client-runtime/src/state/threads.ts#L520-L527

 

^{Reviewed by Cursor Bugbot for commit 9bc5966. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 95cd34a. Configure here.}

[cursor]

Pre-turn rows dropped from pages

Medium Severity

Windowed reads only open the lower bound for turnless rows when the thread has no turns at all. If any turns exist, minAnchorAt stays at the oldest returned turn’s requested_at even when hasMore is false, so messages and activities with turn_id null and created_at before that first turn never appear on any page. That breaks the claimed full page-walk parity with an unwindowed fetch for pre-turn content such as early context-window.updated activities.

Additional Locations (2)

• apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts#L1210-L1215
• apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts#L1257-L1262

 

^{Reviewed by Cursor Bugbot for commit 95cd34a. Configure here.}