fix(server): bound getThreadProjection history with explicit paging

[saphid]

Summary

orchestration.getThreadProjection materialized an entire long-lived thread — every
turn item, payload, and checkpoint — into one response. Simply capping the reply is
not acceptable: a response silently cut to N rows leaves clients with no path to
older history. This PR bounds snapshot rows, encoded bytes, and decode work while
keeping the complete raw history in storage and adding cursor-based paging to reach
it, with an explicit opt-in so legacy clients are never silently truncated.

Behavior

• getThreadProjection stays opt-in: only requests with
  acceptBoundedSnapshot: true receive the bounded recent-turn window plus paging
  metadata (snapshotSequence, historyCursor, hasMoreHistory,
  latestLocalTurnOrdinal, payloadBudgetExceeded). Pre-PR clients never send the
  flag and keep the full projection — complete history and out-of-window checkpoint
  rewind included.
• Bounded reads bound work inside the query: bounded_json write-time previews
  (migration 054 backfills them) mean oversized raw payloads never cross
  SQLite→JS; the window enforces row and byte budgets, keeps the newest rows,
  drops a partial oldest turn at its exact (ordinal, turn_item_id) boundary, and
  shares the budget across fork ancestry. Rows bigger than any budget stay
  reachable through at-least-one-row semantics.
• Older history pages through orchestration.getThreadHistoryPage (WS) or the
  existing HTTP history endpoint with the same opaque cursor. Cursor v2 anchors on
  (thread digest, ordinal, item digest) — fixed size regardless of id length and
  stable across driver id mangling; v1 cursors still decode. A deleted or
  superseded anchor returns typed invalid_history_cursor; the client reseeds
  progressive history from a fresh bounded snapshot (guarded by applyLock and
  the snapshot sequence so it cannot clobber in-flight socket events), and a
  structured not-found marks the thread deleted.
• orchestration.getThreadCheckpointContext returns whole-history checkpoint
  metadata (run/scope/checkpoint ids, ordinals, status, refs — no payloads) so
  bounded clients resolve rewind ordinals without the full projection. The
  threadCheckpointContext capability advertises it; revertThreadCheckpoint
  prefers it and falls back to an unbounded projection read on older servers.
  stopThreadSession also reads the unbounded projection so ready provider
  sessions outside the retained cohort are still detached.
• Migration 055 adds item_id_digest (+ index) so v2 anchor resolution is an
  indexed lookup, not a per-page payload decode of every equal-ordinal sibling.
• Both new RPCs require the existing orchestration.read scope.

Limitations

• Interactive arrays (approval_request.options, todo_list.steps,
  user_input_request.questions/options) preserve all members in previews —
  dropping them would silently change what the user is asked — so a preview can
  exceed the per-row byte cap; emitted items are still billed at their true size,
  so window budgets hold.
• Bounded snapshots retain only the timeline cohort's dependent collections; live
  control state outside the cohort is reachable via getThreadCheckpointContext
  or an unbounded read, not via visibleTurnItems.
• Memory reduction is established by row/byte-budget tests, not a measured
  heap-profile run.

Test plan

• 183 focused tests green on the head: ProjectionStore.test.ts,
  threadHistoryPaging.test.ts, ws.test.ts, commands.test.ts,
  threads-sync.test.ts, 054/055 migration tests — huge histories, oversized single
  rows, pagination to the true beginning (v1+v2 cursors, equal-ordinal siblings,
  lone-surrogate ids, fork markers), reconnect/reseed, legacy decode, and
  authorization.
• Regressions mutation-verified (wrapper-vs-item billing, ordinal-only
  alignment, exempt-all collision groups all detected).
• Per-package typecheck clean; fmt clean.

Supersedes the approach explored in #10512 — credited for the earlier proposal.

---

Built with SWE-2 Max via Devin/T3 Code.
Coordination: T3 thread c1c50bb3-6c48-44ec-a174-25715c55a302; campaign issue
saphid/t3code-personal#298.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR substantially changes production history retrieval, persistence schemas, RPC contracts, authorization, and client defaults while introducing new paging and recovery capabilities. Its cross-cutting behavior and an unresolved high-severity missing-thread error-classification concern require human review.

Not approved because:

• Per-PR cost limit exceeded (workspace setting). Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings, or comment @macroscope-app review this PR to bypass the limit and review now. You can add or adjust custom eligibility rules. Learn more.}

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[macroscopeapp]

Macroscope skipped reviewing this pull request. Per-PR cost limit exceeded (workspace setting).

Reviews on this PR have cost $49.04 so far. This review would add an estimated $13.60, bringing the total to $62.63 — above your per-PR limit of $50.00.

Tip

To get this pull request reviewed, you can:

1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
2. Exclude large or generated files from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
3. Raise your cost limit in your workspace billing settings.

^{Turn off this reminder going forward}

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[macroscopeapp]

🟠 High orchestration-v2/ProjectionStore.ts:6428

Missing threads from getThreadSnapshot are reclassified as ProjectionStoreReadError, so callers and the HTTP isThreadNotFound mapper receive an internal read error instead of thread_not_found. Preserve ProjectionStoreThreadNotFoundError before wrapping other failures, matching the SQL implementation.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/orchestration-v2/ProjectionStore.ts around line 6428:

Missing threads from `getThreadSnapshot` are reclassified as `ProjectionStoreReadError`, so callers and the HTTP `isThreadNotFound` mapper receive an internal read error instead of `thread_not_found`. Preserve `ProjectionStoreThreadNotFoundError` before wrapping other failures, matching the SQL implementation.

[saphid]

False positive — the mapError at :6428 is scoped inside the flatMap callback and wraps only the decode/bounding gen. service.getThreadSnapshot(threadId) is the pipe source: its ProjectionStoreThreadNotFoundError (from getThreadProjection at :5889) propagates past flatMap unwrapped, so callers see the bare error — error.cause._tag === "ProjectionStoreThreadNotFoundError" still matches isThreadNotFound → thread_not_found, identical to the SQL impl. Pinned by regression tests on both drivers in fc07d990b: "surfaces missing threads as not-found, not read errors" (SQL) and "memory snapshot windows surface missing threads as not-found, not read errors" (memory).

[macroscopeapp]

Sorry, I'm unable to act on this request because you do not have permissions within this repository.

[juliusmarminge]

Closing as superseded. v2 landed its own bounded-projection model on Sep 11 (12fb985, e2c5227, 6076240, c3e2920):

• getThreadProjection is served from getThreadSnapshotWindow through buildBoundedThreadProjection and is bounded unconditionally, so stale clients cannot materialize a full transcript.
• subscribeThread accepts acceptBoundedSnapshot and returns historyCursor / hasMoreHistory; older history pages through the HTTP endpoint in orchestration-v2/http.ts, and client-runtime already opts in.
• Control-plane arrays (checkpoints, runs, provider sessions) stay whole; only messages / turnItems are windowed, which removes the need for a separate checkpoint-context RPC.

That solves the unbounded read with a much smaller surface than this branch (three migrations, write-time previews, a new cursor format), so I don't want to carry both models. If there is a measured hot spot that the current paging does not cover, for example oversized single-row payloads, a small PR with the measurement attached would be welcome.

Thanks for the effort on this.