fix(server): bound thread catch-up replay and stop full-DB snapshot hydration

[t3dotgg]

Reconnecting to a large database can OOM-kill the backend. Two unbounded reads are responsible:

• subscribeThread's stale-cursor catch-up read the entire global event log (readEvents(afterSequence, Number.MAX_SAFE_INTEGER)) and filtered per-thread in JS afterwards. A cached cursor a few hundred thousand events behind forces the server to page and JSON-decode every intervening event's tool payloads — for every thread — only to discard almost all of them. Field traces in App Crash on heavy thread #996 measured cursors 271k–591k events behind producing 15k+ SQL pages per reconnect, multiplied by the sidebar's concurrent thread subscriptions, ending in FATAL ERROR: JavaScript heap out of memory crash-loops.
• GET /api/orchestration/snapshot (and the offline t3 project CLI path) hydrated every message and activity payload in the database via getSnapshot(). App Crash on heavy thread #996 has a reproduction where a single authenticated request to this route deterministically OOMs the backend on a 1.5 GB database.

Fixes:

• subscribeThread now bounds catch-up replay to the projection head with the same gap cap subscribeShell has used since perf(orchestration): speed up new-chat propagation and offline catch-up #4177 (THREAD_RESUME_MAX_GAP = 1000). Past the cap (or with a cursor ahead of the head) it falls through to the existing fresh-snapshot path instead of an unbounded replay. No client change needed: clients already consume snapshot frames on resume and dedupe overlapping events by sequence, so the only observable difference is that a long-stale reconnect gets a fresh snapshot instead of a multi-minute replay (or a dead server).
• The snapshot HTTP route and the offline CLI now use the existing getCommandReadModel() — same OrchestrationReadModel wire shape, thread bodies empty. The route's only consumer in the monorepo is the project CLI, which reads projects alone; web/desktop/mobile load the shell + per-thread snapshots instead.

This is the short-term containment for the OOM class in #996 / #1686 / #4597 / #2761 on the current orchestration layer, shaped to be trivially portable to V2 (#2829). Longer term, moving tool payloads out of the hot paths entirely is the real fix.

Verification:

• 3 new tests: large-gap fallback, ahead-of-head cursor reset, replay bounded to captured head
• full server suite: 1828 passed
• server typecheck, lint, format clean

Built by Claude Fable 5 in Claude Code.

🤖 Generated with Claude Code

---

Note

High Risk
Changes hot-path orchestration reads and WebSocket resume semantics on large event logs; incorrect bounds could drop events or change reconnect behavior, though clients already handle snapshot resume and sequence dedupe.

Overview
Addresses backend OOM on large databases by bounding unbounded orchestration reads in two places.

Snapshot hydration: GET /api/orchestration/snapshot and the offline t3 project CLI now call getCommandReadModel() instead of getSnapshot() — same wire shape but without hydrating every message/activity body. That route is only used for project-list reads; UIs already use shell and per-thread snapshots.

Thread WebSocket resume: subscribeThread catch-up no longer uses readEvents(..., Number.MAX_SAFE_INTEGER) on the global log (which decoded all threads’ payloads then filtered in JS). It mirrors subscribeShell: THREAD_RESUME_MAX_GAP = 1000, replay limited to the captured latestSequence, and when the gap is too large or the cursor is ahead of the head it falls through to a fresh thread detail snapshot instead of replaying.

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

Note

Bound subscribeThread catch-up replay and replace full-DB snapshot hydration with lightweight command read model

• subscribeThread in ws.ts now caps catch-up replay to THREAD_RESUME_MAX_GAP (1,000 events) using the authoritative head at the time of the request, replacing the previous unbounded Number.MAX_SAFE_INTEGER replay.
• If the gap exceeds the limit or the client cursor is ahead of the server head, a fresh thread snapshot is sent via getThreadDetailSnapshot() instead of replaying.
• The orchestration snapshot route and offline snapshot generator in http.ts and project.ts now call getCommandReadModel() instead of getSnapshot(), avoiding full-DB hydration.
• Three new tests in server.test.ts cover the large-gap snapshot fallback, ahead-of-head cursor handling, and bounded replay limit.
• Behavioral Change: clients with a replay gap >1,000 events now receive a snapshot instead of a full replay, and snapshot endpoints return a lighter model.

^{Macroscope summarized 191a386.}

[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: 88a4f945-ab89-4218-99dc-3c188c42b84a

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]

Approvability

Verdict: Approved 191a386

Defensive bug fix that bounds thread catch-up replay and avoids full-database hydration to prevent OOM server crashes. Follows an existing pattern (SHELL_RESUME_MAX_GAP) with comprehensive test coverage.

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