feat(settings): add worktree storage management

[amanthanvi]

What Changed

Adds a Worktree Storage settings surface across web/desktop and mobile. It reports known worktree checkout bytes per connected system, ranks projects by their worktree footprint, shows bounded worktree details and protection reasons, and keeps offline, unsupported, failed, and partial systems explicit.

Adds path-free, environment-local report and prune RPCs plus per-system automatic policies for off, when threads settle, or after 1–365 inactive days. Clients can confirm pruning on one system or fan the same request out across the connected systems captured by the confirmation.

The destructive path is deliberately conservative: the server discovers candidates itself, protects unassigned worktrees, performs canonical containment and Git/liveness checks, treats ignored files and incomplete Git output as unsafe, reserves associated thread paths with verified compare-and-swap events, restores reservations on failure or interruption, and performs a final dirty/untracked/ignored check immediately before non-force git worktree remove.

Why

Connected T3 Code environments can accumulate large worktree checkouts without one place to understand their cost. This adds an honest cross-system view while preserving environment ownership: every server reports and mutates only its own filesystem, and older or unavailable servers remain unknown instead of being counted as zero.

UI Changes

Live visual QA passed on web at 1440×1100 and 1024×768 and on an iOS development client at 368×800. The fixture showed 66 MB across one connected system, Atlas Console ranked first at 48 MB and eligible, and Beacon API ranked second at 18 MB and protected. Local and across-system confirmation scopes rendered correctly. Applying “After 45 inactive days” removed only the stale fixture and preserved the protected fixture.

Before

The base branch has no Worktree Storage settings entry or storage-management surface.

After — web and desktop

After — mobile

Validation

• Final review-fix pass: 8 focused test files / 58 tests passed across server traversal and pruning, contracts, shared client logic, web, and mobile.
• Server, contracts, client-runtime, web, and mobile typechecks passed.
• Targeted lint with warnings denied, formatting, and whitespace checks passed.
• Production web build passed; only existing dynamic-import and large-chunk warnings remain.
• Live web and iOS client verification passed. The iOS pass found and fixed a Hermes incompatibility before this update.

Safety model and residual boundaries

• Automatic pruning defaults off; unowned worktrees, local or ignored files, ahead/unpushed commits, main/detached/locked worktrees, active sessions, live providers/terminals, pending interaction, incomplete Git output, and inspection uncertainty all protect a candidate.
• A physical checkout contributes bytes once. Shared multi-project associations use the same deterministic project attribution for both the aggregate and its visible detail.
• Directory traversal revalidates the directory device and inode after each read and rejects identity or symlink changes before queuing entries.
• In-process typed failures, defects, cancellation, Git failures, and final-state rejections trigger uninterruptible restoration attempts. A hard process stop or a restoration defect can still strand a thread association as cleared; the physical checkout is then rediscovered as unassigned and protected. Eliminating that metadata-recovery case requires a durable reservation journal and startup reconciliation.
• Final live-state and filesystem checks plus non-force Git removal narrow process races, but separate server processes and other same-user writers are not admission-locked, and Git status plus recursive removal is not one atomic filesystem operation. This does not claim safety against a hostile same-user writer racing those checks.
• Timed-out Node filesystem promises cannot be cancelled by the APIs used here; scans return a partial time-budget result and ignore late results for deletion decisions.
• The traversal entry cap is applied after each readdir; Node still materializes one directory's names first, so a pathologically wide directory can use more transient memory than the entry cap suggests. Incremental directory handles are the follow-up if this becomes operationally significant.

Simplification review

• Web and mobile now share frozen-confirmation reconciliation, per-environment pending-state helpers, and prune outcome formatting.
• The permissive test-only Git porcelain parser was removed; tests exercise the strict production decoder.
• The two no-follow traversal paths share one identity-validating directory-read primitive.
• A cross-process lock, durable reservation journal, and a generic web/mobile status-view abstraction were deliberately not added here: each would add machinery beyond the current trust model or cost more indirection than the duplication it removes.

Checklist

• This PR is small and focused — it is one product concern, but necessarily crosses contracts, server, shared runtime, web, and mobile.
• I explained what changed and why.
• I included before/after screenshots for UI changes.
• No animation or motion change requires a video.

Implemented with GPT-5.6 Sol (xhigh) in the Codex harness.

Note

Add worktree storage management with reporting, pruning, and settings UI

• Introduces a full worktree storage feature spanning contracts, server service, client-runtime state atoms, and web/mobile settings screens. Clients can query per-environment storage reports and issue prune-stale commands via new worktreeStorage.getReport and worktreeStorage.pruneStale RPCs.
• Adds WorktreeStorage.ts on the server, which scans managed worktree directories, interprets git porcelain output, computes protection reasons, selects prune candidates, and assembles bounded reports. Backed by a new no-follow directory traversal adapter in directorySize.ts that enforces entry/time/failure budgets and rejects symlink traversal.
• Adds worktreeAutoPrunePolicy to ServerSettings (defaults to { mode: 'off' }) and advertises worktreeStorage: true in server environment capabilities. Per-environment auto-prune policy controls are exposed in both web and mobile settings UI.
• Adds domain primitives in worktreeStorageDomain.ts (ranking, coverage, prune planning, byte formatting) consumed by both platforms.
• Behavioral Change: thread.meta.update now applies worktreePath using compare-and-set semantics when expectedWorktreePath is provided, and does not advance updatedAt for worktreePath-only CAS bookkeeping updates in decider.ts.

^{Macroscope summarized c07aa35.}

---

Note

High Risk
Adds server-side filesystem discovery and git worktree removal plus orchestration CAS on thread worktree paths. Destructive prune and auto-sweep run on the host with reservation/restore races that can strand metadata.

Overview
Adds a Worktree Storage settings surface on web/desktop and mobile so users can see known checkout size per connected system, set per-system auto-prune policy, and prune stale worktrees on one host or across currently connected capable hosts.

The server discovers and sizes managed worktrees itself (no client paths). Reports and prunes stay environment-local. Candidates are protected for dirty/ignored/unpushed Git state, live sessions/terminals, unassigned or shared checkouts, incomplete inspection, and similar fail-closed reasons. Prune reserves thread worktreePath with compare-and-set metadata, restores on failure or interrupt, then uses non-force git worktree remove. Auto-prune defaults off (on-settle or after 1–365 inactive days). Path-only CAS updates no longer bump thread updatedAt.

RPCs worktreeStorage.getReport / worktreeStorage.pruneStale use orchestration read vs operate scopes. Offline, unsupported, and partial systems stay unknown rather than counting as zero.

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

[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: 9065cbcd-8165-41cc-9ba5-241f010ce585

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]

One finding on the new Worktree Storage settings page: the partial-scan callout hardcodes a warning tint instead of the semantic warning surface token. Everything else (SettingsSection/SettingsRow composition, Button/Badge/Select/Input/AlertDialog primitives, search catalog and sidebar icon registration) follows the existing settings conventions.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

Effect service conventions review for the new worktree storage service. Four findings, all in newly added code; details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Follow-up on the earlier review: the Context.Reference wiring, the optional listSummaries on TerminalManager, and the hard-coded operation: "report" in loadScanContext are all resolved. One convention item remains in the new service module.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Reviewed the new Effect service (apps/server/src/worktree/WorktreeStorage.ts) and its consumers against the service conventions. Dependency acquisition (yield* Foo.Foo for every dependency), module namespace imports, make/layer export shape, and the WorktreeStorage["Service"] usage in server.test.ts all look right. One structural item below.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

UI consistency review of the new web Worktree Storage settings surface. One responsive finding on the destructive action labels; the rest of the page composes the shared settings primitives (SettingsPageContainer/SettingsSection/SettingsRow, Button, Badge, Select, Input, AlertDialog, toastManager) consistently, and the partial-scan callout now uses the --color-warning-surface token.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

Reviewed the web settings surface added by this PR (WorktreeStorageSettings.tsx, settingsSearch.ts, SettingsSidebarNav.tsx, state/worktree-storage.ts, worktreeStorage.logic.ts, route file). Two consistency findings, both in WorktreeStorageSettings.tsx. The earlier bg-warning/8 callout now uses the --color-warning-surface token, so that is resolved.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One minor consistency finding on the new Worktree Storage settings page; everything else (destructive button wrapping, warning surface token, header refresh affordance) now matches the shared settings patterns.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One consistency finding on the new Worktree Storage settings page: the Apply button in the per-system automatic-pruning cluster is a size smaller than the select and number input it sits next to, so the three controls in that row don't line up. Everything else (warning surface token, section header icons/refresh affordance, wrapping destructive labels) now matches the settings design system.

^{Posted via Macroscope — UI Consistency}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[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 e6d1ff3. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a substantial Worktree Storage feature spanning server filesystem/Git mutation, automatic pruning, orchestration CAS behavior, new RPC contracts, and web/mobile settings flows. The destructive host-side behavior and cross-cutting runtime changes warrant human review.

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

[macroscopeapp]

One finding on the new Worktree Storage settings page: its relative-time labels are rendered without the settings-layout tick, so they freeze. Everything else (primitive usage, sizes, warning surface token, wrapping destructive buttons, header refresh affordance) matches the shared settings conventions.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One consistency finding on the new Worktree Storage settings page. Everything else (primitive usage, control sizes, warning surface token, relative-time tick, wrapping destructive buttons) now matches the existing settings patterns.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One convention finding in the new Effect service code: WorktreeStorageError carries a redundant single-value reason literal alongside its multi-value operation discriminator. Everything else in the changed service scope matches the conventions (inline Context.Service interface with satisfies WorktreeStorage["Service"], namespace subpath imports, environment-acquired dependencies in make, canonical make/layer exports, required TerminalManager.listSummaries, and operation-aware error mapping in loadScanContext).

^{Posted via Macroscope — Effect Service Conventions}