fix(server): persist automatic thread settlement

[t3dotgg]

Thread settlement was partly inferred in each client from local clocks and row-level PR state. That let web and mobile disagree, and pinned threads could appear settled for inactivity or a closed PR.

This moves automatic settlement into a server reactor that persists the existing thread settlement event. Pinned threads now ignore inactivity and closed PRs; a merged PR is their only automatic settlement path. Clients render the projected settled timestamp directly, and the inactivity setting is server-owned.

Tested with 203 focused tests plus targeted lint and typechecks across server, contracts, client runtime, web, mobile, and desktop.

Made with GPT-5.6 Sol in T3 Code via the Codex harness.

---

Note

High Risk
Changes core thread lifecycle and cross-client consistency via a new background reactor, PR/VCS polling, and a settings migration that drops prior client preferences.

Overview
Automatic settlement is now server-owned. A new ThreadSettlementReactor periodically reconciles threads and dispatches thread.settle for inactivity or merged PRs, using threadSettlement.ts policy (pinned threads skip inactivity; merge settlement respects threadAutoSettleOnMerge; closed PRs no longer auto-settle). VcsStatusBroadcaster adds cache-only peekStatus and bounded pollStatus for PR verification without thrashing forge caches.

Clients stop inferring settled state. Web, mobile, and desktop drop effectiveSettled, per-row PR state maps, and client settings sidebarAutoSettleAfterDays / sidebarAutoSettleOnMerge. Lists and banners treat a thread as settled when settledAt is set; settled-tail ordering uses that timestamp. Auto-settle toggles live in server settings (threadAutoSettleAfterDays, threadAutoSettleOnMerge); mobile writes them across environments via updateServerSettings. Old client-only auto-settle keys are stripped on decode and are not migrated.

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

Note

Persist automatic thread settlement on the server instead of computing it client-side

• Introduces ThreadSettlementReactor on the server, which periodically reconciles all threads and dispatches thread.settle commands when inactivity or PR-merged conditions are met, using server settings threadAutoSettleAfterDays and threadAutoSettleOnMerge.
• Moves auto-settle configuration (threadAutoSettleAfterDays, threadAutoSettleOnMerge) from ClientSettings to ServerSettings; client-side sidebar-prefixed settings are removed.
• All client surfaces (web sidebar, chat view, mobile home screen, action menus) now classify threads as settled solely based on the server-projected settledAt timestamp; client-side effectiveSettled, changeRequestAutoSettles, and threadLastActivityAt utilities are removed.
• Adds peekStatus and pollStatus to VcsStatusBroadcaster for cache reads without I/O and partial PR-cache-preserving refreshes; all refresh paths are serialized per working directory.
• Risk: existing users with sidebarAutoSettleAfterDays/sidebarAutoSettleOnMerge client settings will lose those values; settlement behavior is now controlled server-side with defaults of 3 days and merge-settle enabled.

^{Macroscope summarized 1eb582b.}

[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: 2caf5a34-1658-470f-9c34-af674f3a5e30

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: the new ThreadSettlementReactor service is introduced with a standalone ...Shape interface, split across Services/ and Layers/, and non-canonical make/layer export names. Inline comments describe the expected shape (canonical single module, inline interface, make/layer, Foo["Service"]), which is the pattern used elsewhere in this repo (for example apps/server/src/workspace/WorkspacePaths.ts, apps/server/src/serverSettings.ts). The settlement policy module, its tests, and the mechanical reactor/harness wiring look fine.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review: the new ThreadSettlementReactor service is introduced in the older split Services/ + Layers/ shape, rather than as one canonical module with an inline service interface and make/layer exports. Two inline comments below; the rest of the diff (pure threadSettlement.ts helpers, contracts/settings changes, client consumers, test/harness Layer.succeed seams) looks consistent with the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions — findings (inline comments could not be attached, posting here):

1. apps/server/src/orchestration/Services/ThreadSettlementReactor.ts + apps/server/src/orchestration/Layers/ThreadSettlementReactor.ts

The new service is split across a Services/ module (tag + standalone ThreadSettlementReactorShape) and a Layers/ module (construction + layer). Consider defining it in one canonical module, apps/server/src/orchestration/ThreadSettlementReactor.ts, ordered imports → Context.Service tag with the interface declared inline → make → layer, and dropping the ...Shape type so consumers refer to ThreadSettlementReactor["Service"]. Callers (Layers/OrchestrationReactor.ts, server.ts, the unit test and integration/OrchestrationEngineHarness.integration.ts) would then import that single path.

2. apps/server/src/orchestration/Layers/ThreadSettlementReactor.ts:49,240-243

This is the single implementation of the service and the module is named for it, so the canonical export names are plain make and layer:

export const layer = Layer.effect(ThreadSettlementReactor, make);

makeThreadSettlementReactor / ThreadSettlementReactorLive naming is reserved for abstract-port modules that hold one of several possible implementations. Likewise, the shape references at lines 219 and 237 should become ThreadSettlementReactor["Service"]["start"] and satisfies ThreadSettlementReactor["Service"] once the interface lives inline in the tag.

No other convention issues found: dependencies are acquired via yield* Foo in make, no ManagedRuntime/runPromise was introduced in service code, the Layer.succeed uses are test/harness seams, Effect.catch handles the whole error channel intentionally, and no new error classes were added.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR migrates thread auto-settlement from client-computed to server-persisted state, introducing a new ThreadSettlementReactor that periodically evaluates and dispatches settlement commands. The architectural change affects all surfaces and modifies how/when settlement occurs, warranting human review.

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

[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	11.3 KiB	11.4 KiB	+25 B (+0.2%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+5 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+20 B (+0.3%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.8 KiB	+44 B (+0.1%)	66.4 KiB	✅
Codex	Live turn messages	16	17	+1 (+6.3%)	21	✅
Claude	Total thread wire	11.3 KiB	11.3 KiB	+26 B (+0.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.8 KiB	5.9 KiB	+23 B (+0.4%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: db1507e · PR result: 1eb582b · 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: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

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

[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.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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