feat(worktrees): manage lifecycle on orchestrator v2

[StiensWout]

Important

Stacked pull request. This targets t3code/codex-turn-mapping from #2829. After #2829 merges, rebase this branch and retarget the PR to main.

Problem

Thread worktrees accumulate without a server-owned way to inspect or clean them. The previous cleanup prompt only worked in the desktop client, and a removed worktree could strand the next provider turn.

Solution

• Derive a per-environment inventory from Git and V2 thread projections.
• Protect worktrees with active threads, local changes, unpushed commits, or unavailable status. Revalidate immediately before non-forced removal.
• Apply configurable retention and optional immediate cleanup after the last linked thread is deleted.
• Recreate a missing worktree from its retained branch before provider startup, then restart the shared provider session when its working directory changes.
• Add a project-grouped Worktrees inventory to Settings → Source Control for every compatible connected environment: one line per worktree (branch, linked thread, last use, sync state, and either Remove or the blockers), two plain settings rows for the cleanup policy, and rows that disappear as soon as removal is confirmed.
• Treat a detached worktree like a branch without an upstream: safe once its commit is on the default branch, otherwise blocked as unmerged. Previously it was marked status-unavailable forever.
• Read the inventory with one git status per worktree, concurrently with the ahead-of-default count, and fetch the per-repository listing, branch sync, and default ref together. On a 2-vCPU environment with 8 worktrees the inventory went from 5.0 s to 0.6 s. Mounting the section no longer issues a duplicate read.
• Keep local branches and checkpoint refs so cleanup remains reversible through automatic revival.

The refresh also removes the unused public revive RPC, fixes provider-start supersession after a mandatory session reopen, parses git worktree list --porcelain -z everywhere (main already requires -z in listRefs), keeps the reaper behind the activation boundary, lets interrupts stop sweeps and status reads, and skips projects outside a Git repository instead of failing the inventory.

Safety

• All worktree mutations share one server-side permit.
• Inventory combines projects that share a Git common directory, including nested project roots.
• Paths are canonicalized, and revival rejects symlink-ancestor escapes outside the managed worktree root.
• Automatic and manual cleanup never force-removes a worktree or deletes its branch.

Screenshots

Light	Dark

Verification

• Targeted typechecks pass for server, contracts, client runtime, and web.
• Targeted lint, formatting, and diff checks pass.
• The isolated worktree dev environment starts and serves the app successfully.
• Added tests were reduced by 669 lines, keeping focused Git, lifecycle, cleanup, revival, and destructive-safety coverage. Later rounds add coverage for detached worktrees, mixed repository and plain-directory projects, and NUL-terminated worktree listings.

Initial implementation and the refresh were produced with GPT-5.6 Sol via Codex in T3 Code. The one-line settings layout, detached-HEAD handling, inventory speed-up, and review follow-ups were done by Claude Fable 5 via Claude Code in T3 Code.

Note

Add server-side worktree lifecycle management to orchestrator v2

• Introduces WorktreeService, WorktreeRevivalService, WorktreeLifecycle, WorktreeReaper, and WorktreeDeletionCleanup services that handle listing, pruning, reviving, and reaping worktrees on the server
• ProviderTurnStartService now revives the thread's worktree before starting a provider turn, serializes session starts per ProviderSessionId, and closes/reopens the provider session when the worktree was revived or its generation/path changed
• Adds three WebSocket RPCs (vcs.listWorktrees, vcs.subscribeWorktreeInventory, vcs.pruneWorktrees) with auth scopes, and a worktreeManagement capability flag so clients gate features on server support
• Adds client UI in Source Control settings for viewing worktree inventory, configuring retention (autoPruneAfterDays default 14, deleteOrphanedImmediately default false), and pruning; useThreadActions skips legacy client-side orphan cleanup when the capability is present
• GitWorkflowService methods (preparePullRequestThread, createWorktree, removeWorktree) now run under a WorktreeLifecycle mutation permit and signal inventory changes
• Risk: ProviderTurnStartService no longer emits provider-session.updated and provider-thread.updated events during the initial running transition; consumers relying on those events in that phase will need to use run.updated, run-attempt.updated, or node.updated instead

^{Macroscope summarized bdc613b.}

---

Note

High Risk
Touches provider turn startup, shared session close/reopen, and automatic worktree deletion; race-sensitive paths are tested but mistakes could strand runs or remove worktrees incorrectly.

Overview
Adds server-owned Git worktree lifecycle for orchestration v2: inventory from git worktree list, safe pruning rules, automatic retention/orphan cleanup, and revival of missing thread worktrees before provider turns run.

Git & workflow: New listWorkspaces / shared porcelain parsing (GitWorktree.ts), with output-size limits. GitWorkflowService routes create/remove/prepare-PR-thread work through WorktreeLifecycle (serialized mutations + inventory revision stream).

Orchestration: ProviderTurnStartService calls WorktreeRevivalService.reviveForThread, then serializes startup per ProviderSessionId via KeyedSerialExecutor. If a worktree was revived or its generation/path changed, it closes and reopens the shared provider session so cwd stays correct, with careful handling when runs are superseded mid-restart.

Background jobs: WorktreeDeletionCleanup reacts to thread.deleted events; WorktreeReaper periodically prunes inactive safe worktrees per settings. Both delegate to WorktreeService for last-moment safety checks.

Product surface: Enables worktreeManagement server capability and RPC auth for vcsListWorktrees, subscribeWorktreeInventory, and vcsPruneWorktrees. Layers wired in server.ts / startup after the effect worker starts.

^{Reviewed by Cursor Bugbot for commit bdc613b. 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: 241aad84-47f4-4428-b412-3c651f409505

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

---

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

[macroscopeapp]

Reviewed the new worktree services against the Effect service conventions. Four convention issues found: two standalone *Shape service interfaces, a redundant singleton operation discriminator plus free-form message on the new worktree error classes, and a hidden optional service dependency in ProviderTurnStartService.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review of the worktree management services. Prior findings on WorktreeLifecycle/WorktreeRevivalService shape interfaces, the unstructured worktree error payloads, and the Effect.serviceOption acquisition of WorktreeRevivalService all look addressed. A few smaller convention issues remain.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding: raw git stderr is copied into a new error attribute. Everything flagged in earlier runs (service-shape interfaces, make/layer naming, the single-use mutationError helper, the parseWorktreeBranchPaths shim, structural stages on the new worktree errors, and the hidden WorktreeRevivalService requirement) is resolved in this revision.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Reviewed the Effect service conventions in this update. Previously flagged items (inline service interfaces, plain make/layer names, structural error stages with derived messages, required WorktreeRevivalService acquisition in ProviderTurnStartService, shared worktree porcelain parser, bounded git worktree list error context) all look resolved. One remaining error-modeling nit below.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This change adds a substantial server-owned worktree lifecycle with automatic filesystem cleanup, worktree recreation, provider-session restarts, new authorized RPCs, and a production settings surface. Its broad cross-cutting behavior and destructive side effects exceed the scope of a low-risk additive change.

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

[macroscopeapp]

One finding on the new GitVcsDriver.listWorkspaces truncation error: its context fields are hardcoded/fabricated rather than derived from the actual command and output.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding on the worktree refresh header action; the rest of the changed web UI looks consistent with the shared primitives.

^{Posted via Macroscope — UI Consistency}

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

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