feat: sync thread unread state across clients

[t3dotgg]

Thread unread state lived in each web client, so viewing or marking a thread unread did not follow the user to another client.

This stores a server-owned viewed timestamp and sends view and mark-unread commands through the existing event stream. Existing threads are backfilled as viewed, older servers keep the local fallback, and mobile reports completed threads when opened.

Tests:

• Focused tests for contracts, server, web, and mobile
• Type checks for contracts, client runtime, server, web, and mobile
• Targeted lint and formatting checks

Created by GPT-5.6 Sol through the Codex harness in T3 Code.

---

Note

Medium Risk
Touches orchestration commands, projections, and multi-client optimistic concurrency for thread metadata; behavior is heavily tested but incorrect guards could leave threads stuck read/unread across devices.

Overview
Adds server-backed thread read state so clearing a Done badge or marking a thread unread can follow the user across web and mobile, with a local-only fallback when the environment does not advertise threadViewState.

The server introduces thread.view and thread.mark-unread orchestration commands (with optional expectedViewedAt / expectedCompletedAt guards), persists viewedAt via existing thread.meta-updated events and projection viewed_at, advertises the threadViewState capability, and runs migration 044 to backfill existing rows as read. Client runtime wires the new commands on a dedicated view-state scheduler so passive acknowledgements do not block turn actions.

Web replaces direct markThreadVisited / markThreadUnread store calls with useThreadViewState and resolveThreadViewedAt, including pending/local-only markers, visibility-gated completion acknowledgement in chat, and sidebar/status indicator updates. Mobile sends guarded view commands when a thread route is focused, the app is active, and the server is connected. Agent awareness ignores meta updates that only change view timestamps.

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

Note

Add server-backed thread view/unread state with thread.view and thread.mark-unread commands

• Introduces thread.view and thread.mark-unread orchestration commands validated in decider.decideOrchestrationCommand, emitting thread.meta-updated events with viewedAt; contracts, client runtime commands, and projector all updated to carry the new field
• Adds migration 044 to add viewed_at to projection_threads (backfilled from updated_at/created_at) and repairs missing unsettled_at
• Web gains a useThreadViewState hook and resolveThreadViewedAt util that coordinate local pending markers with server state; sidebar, chat view, and status indicators now display resolved visited timestamps
• Mobile ThreadRouteScreen derives guarded view commands via resolveThreadViewCommand and dispatches them on focus when the server advertises threadViewState capability
• AgentAwarenessRelay.shouldPublishAgentAwarenessEvent suppresses publication for meta updates that only change viewedAt/updatedAt
• Behavioral Change: OrchestrationThread, OrchestrationThreadShell, and ThreadMetaUpdatedPayload gain an optional viewedAt; old clients/servers still decode but ignore it. projection_threads.viewed_at is initialized to created_at for new threads. persistState/parsePersistedState now persist only valid local-only threadViewStatePendingById entries

📊 Macroscope summarized c55dd68. 30 files reviewed, 3 issues evaluated, 3 issues filtered, 0 comments posted

🗂️ Filtered Issues

apps/mobile/src/features/threads/threadViewState.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 46: resolveAppliedThreadViewBoundary only recognizes an applied view when the server timestamp exactly equals a requested boundary. If a completed timestamp is ahead of server time, the server caps the view to its current time; that valid response remains below completedAt but does not match the requested future boundary. The tracking effect then leaves retryBoundary unset, so its focus callback is not re-created and the mobile client never retries after the boundary becomes reachable, leaving the thread unread until an unrelated focus/dependency change. [ Already posted ]

apps/web/src/components/Sidebar.tsx — 0 comments posted, 1 evaluated, 1 filtered

• line 1844: acknowledgeWoke calls markViewed while an environment's server configuration can still be unavailable. In that state, useThreadViewState takes its local-only fallback when the shell has no viewedAt; this sidebar callback is only invoked by the one user click and is never retried when the threadViewState capability later loads. Thus dismissing a Woke notification during startup remains local and other clients continue to show the thread as unread/woken despite the server supporting synchronization. [ Already posted ]

apps/web/src/uiStateStore.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 241: persistState strips every in-flight view/unread operation because sanitizeLocalThreadViewState only retains entries whose localOnly is already true. If the tab is closed or reloaded after setThreadViewStatePending and the optimistic local timestamp update but before the asynchronous server command resolves, the unload flush saves no pending intent. On the next load resolveThreadViewedAt treats the old server timestamp as authoritative, so a view or mark-unread action that was not processed by the server is silently lost rather than retried or retained locally. [ Out of scope (triage) ]

[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: 3427fc18-ca12-43b4-b99c-1ee04b9e370b

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

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

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

[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	13.3 KiB	13.4 KiB	+169 B (+1.2%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	+17 B (+0.2%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.5 KiB	+152 B (+2.3%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	57.0 KiB	+1.4 KiB (+2.6%)	66.4 KiB	✅
Codex	Live turn messages	10	10	0 (0.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.3 KiB	−203 B (−1.5%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	+16 B (+0.2%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.6 KiB	6.3 KiB	−219 B (−3.3%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.8 KiB	56.3 KiB	−1.5 KiB (−2.6%)	66.4 KiB	✅
Claude	Live turn messages	10	8	−2 (−20.0%)	21	✅

Baseline: 0bfb6df · PR result: c55dd68 · 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: 109.5 KiB
• Claude decoded thread snapshot: 110.2 KiB

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

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces cross-client unread-state synchronization across web, mobile, orchestration, event relay, and persisted server projections, including a migration that changes the initial state of existing threads. Its broad production behavior and default enablement warrant human review despite strong backward-compatibility and test coverage.

No code changes detected at c55dd68. Prior analysis still applies.

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

[cursor]

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

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

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

[t3dotgg]

Note

🤖 Claude Fable 5.1 responding on behalf of Theo

Closing in favor of #9124, which keeps this branch's server model (viewedAt column, thread.view and thread.mark-unread, monotonic decider, capability gate) and drops the client-side pending, retry, and reconciliation state.

Every review round here added another layer of optimistic client machinery, and the diff grew past 950 non-test lines. Since #8600 moved settlement server-side with clients rendering server state directly, read state can use the same shape. #9124 is about 420 non-test lines with the same behavior and no dev-database migration repair.