fix: keep auto-settle policy consistent across clients

[PixPMusic]

What Changed

• moved the inactivity auto-settle threshold from device-local client settings into server settings owned by each environment
• made web, desktop, and mobile classify each thread with its owning environment's streamed policy
• kept inactivity classification derived: clients do not send thread.settle, and the server does not schedule settlement events
• added version-skew gating, multi-environment regression coverage, and user documentation

Why

Web/desktop read sidebarAutoSettleAfterDays from local client persistence, while mobile hard-coded the default of three days. A desktop configured for seven days and a mobile client connected to the same server could therefore put the same thread in different shelves.

The existing server-settings RPC is already remotely writable and streamed to connected clients, so the policy now lives there. Explicit settle/un-settle remains the durable server lifecycle; crossing the inactivity threshold only changes the derived list classification. This avoids clients racing automatic settle commands and lets a policy change reclassify threads immediately.

The default remains three days. The legacy client field and exported names remain decodable for downgrade/source compatibility, but local values no longer drive upgraded clients; automatically importing whichever client connects first would recreate the same ownership race. In multi-environment lists, each backend owns its own policy rather than one client silently mirroring writes to other environments.

This establishes the ownership boundary that overlaps with #5141. Its proposed additional auto-settle controls should extend the server-owned policy rather than introducing separate web and mobile preferences.

UI Changes

No layout or interaction changes. The existing General setting now updates the primary environment and is read-only against older servers that do not advertise policy updates, so screenshots/video are not applicable.

Verification

• vp test run packages/contracts/src/settings.test.ts apps/server/src/serverSettings.test.ts packages/client-runtime/src/state/threadSettled.test.ts apps/mobile/src/features/threads/threadListV2.test.ts — 269 passed
• targeted typechecks for contracts, client runtime, server, web, and mobile
• targeted lint and formatting checks for all changed source and documentation files
• git diff --check

Checklist

• This PR is small and focused
• I explained what changed and why
• Screenshots are not applicable because there is no visual layout change
• A video is not applicable because there is no animation or timing interaction change

Model: GPT-5.6-Sol | Harness: Codex in T3 Code

---

Note

Medium Risk
Changes how threads appear in sidebars across clients and introduces server-streamed policy with version-skew gating; behavior can shift when local client thresholds differed from the environment default.

Overview
Moves inactive thread auto-settle from per-device client settings (sidebarAutoSettleAfterDays) to per-environment server settings (threadSettlement.autoSettleAfterDays), streamed to connected clients so web, desktop, and mobile classify the same threads the same way.

Contracts & server: Adds ThreadSettlementSettings on ServerSettings, renames the day-threshold constants to THREAD_AUTO_SETTLE_*, keeps the old client field only for downgrade decoding, and advertises a new threadSettlementPolicy capability. The server persists policy patches and tests cover enable/disable.

Clients: Web sidebar, chat view, thread actions, and General settings now read/write the primary environment’s streamed policy (controls disabled when the server lacks threadSettlementPolicy). Mobile thread list v2 takes a per-environment map instead of a single hard-coded default; classification still treats inactivity as a derived settled view, not a server settle command.

Docs: New user doc on thread settlement and a README link.

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

Note

Move auto-settle policy from client preferences to per-environment server settings

• Adds a threadSettlement section to server settings with an autoSettleAfterDays field (default: 3 days, nullable to disable) and a threadSettlementPolicy capability flag so clients can detect support.
• Updates buildThreadListV2Items to accept a per-environment map (autoSettleAfterDaysByEnvironment) instead of a single global value; threads fall back to DEFAULT_THREAD_AUTO_SETTLE_AFTER_DAYS when no policy is set for their environment.
• Web sidebar, chat view, and thread action menu all now read auto-settle policy from serverConfig.settings.threadSettlement rather than a local client preference.
• The General settings panel binds auto-settle controls to the server-side policy and disables them when the connected server does not advertise threadSettlementPolicy support.
• Behavioral Change: sidebarAutoSettleAfterDays in client settings is deprecated but retained for downgrade compatibility; existing clients on servers without the capability will use the fixed 3-day default.

^{Macroscope summarized 08b6d70.}

[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: 26f17fa4-d86c-4525-adea-03ba92866013

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: Needs human review

This PR moves thread auto-settlement policy from client-side settings to server-side environment configuration - a cross-cutting architectural change affecting mobile, web, and server. The author labeled it 'Medium Risk' as it changes how threads appear across connected clients.

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