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 pile up and there is no way to see them or remove one from the app. Settings → Storage (#11598) can remove them automatically, but only by rule, and you can't see what it kept or why. The base also recreates a missing worktree before a turn, but it skips the project's setup script, and when recreation fails it starts the provider in a directory that doesn't exist.

Solution

• Build a per-environment inventory from Git and the V2 thread projections, and show it in Settings → Source Control → Worktrees for every connected environment that supports it. Each row shows the branch, a linked thread, last use, and sync state, then either Remove or what blocks removal. A removed row disappears as soon as the server confirms.
• Allow removal only when a worktree has no active thread, no local changes, and no unpushed commits. The server recomputes all of that right before removing, and removal is never forced. The branch and checkpoint refs stay.
• A detached worktree is treated like a branch without an upstream. It becomes removable once its commit is on the default branch; until then it shows as unmerged.
• Before a provider turn, recreate a missing worktree from its retained branch and run the project's setup script there again, waiting for scripts marked to finish first. If recreation or a required script fails, the run fails and shows the reason. An existing worktree is never touched. A per-thread provider session restarts when its directory was recreated, while sessions shared across threads (Codex) stay open. This replaces the base's inline repair.
• Removals and revival share one server-side permit, and Storage cleanup's removals now take it too. Every change, Storage cleanup included, bumps an inventory revision that open settings pages subscribe to. Creating a worktree skips the permit, so parallel launches keep checking out side by side.
• The inventory runs one git status per worktree, concurrently with the ahead-of-default count. On a 2-vCPU machine with 8 worktrees it went from 5.0 s to 0.6 s.

Automatic cleanup is not part of this PR anymore. Earlier revisions had their own reaper, a "remove with last thread" option, and a 14-day retention setting. Storage cleanup covers all of that now, off by default and per project, so I dropped them along with the change that hid the desktop "delete the worktree too?" prompt.

Other details: git worktree list --porcelain -z is parsed everywhere, projects outside a Git repository are skipped instead of failing the inventory, registrations whose directory is gone are left out, paths are canonicalized, and revival rejects symlinked ancestors that escape the managed worktree root.

Screenshots

These predate the removal of the two cleanup policy rows above the list. The list itself is unchanged.

Light	Dark

Verification

• Typechecks pass for server, contracts, client runtime, and web.
• Focused tests pass: worktree inventory and removal, revival, lifecycle, Git worktree parsing, Git workflow, turn start (including the memory test), delegated completion, the runtime layer, the project settings upgrade, RPC authorization, contracts, and settings search.
• Targeted lint and format checks pass. Lint reports warnings only.

Initial implementation and the first 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. The rebases through 2026-09-16 were done by Claude Fable 5.1 via Claude Code in T3 Code. The rebases on 2026-09-26 and 2026-09-30, the fixes for Macroscope's review, and dropping automatic cleanup in favor of Storage cleanup were done by Claude Opus 5.5 via Claude Code in T3 Code.

🤖 Generated with Claude 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 67217c7. 34 files reviewed, 8 issues evaluated, 5 issues filtered, 3 comments posted

🗂️ Filtered Issues

apps/server/src/git/GitWorkflowService.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 380: removeWorktree now tries to acquire WorktreeLifecycle's non-reentrant single-permit semaphore even when invoked by WorktreeService.removeIfStillSafe, which already holds that permit. The nested acquisition waits forever, so every automatic/manual safe cleanup path that reaches this call hangs instead of removing the worktree. [ Out of scope (triage) ]

apps/server/src/vcs/WorktreeLifecycle.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 28: changes emits the current SubscriptionRef revision as a subscriber's first item, but the inventory RPC has no matching revision/snapshot handshake. A mutation can complete after a client starts vcsListWorktrees and before it subscribes: the list response is then stale while the first stream item is the already-incremented revision. The client treats that first revision as its baseline and does not refresh, so the settings inventory remains stale until another mutation or manual refresh. [ Previously rejected ]

apps/server/src/vcs/WorktreeReaper.ts — 1 comment posted, 2 evaluated, 1 filtered

• line 65: The automatic call to pruneWorktrees can remove a worktree after its last thread has become active. pruneWorktrees's final thread snapshot is not synchronized with thread lifecycle updates (its implementation explicitly notes links/status can change without the mutation permit), so an unsettle or new turn can land after that snapshot but before Git removal. The reaper makes this race recurring; the active thread is left pointing at a removed working directory until a later revival path repairs it. [ Previously rejected ]

apps/server/src/vcs/WorktreeService.ts — 1 comment posted, 2 evaluated, 1 filtered

• line 647: The thread snapshot is only a point-in-time check: a thread can be linked to this path after the loop at lines 618-624 (the comment explicitly says linking does not take the mutation permit) and before removeWorktree runs. In that interleaving the new active thread is absent from references, while the clean worktree is removed successfully, leaving its newly linked thread with a missing working directory. [ Previously rejected ]

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

• line 1050: The first inventory revision is always ignored, even though the inventory RPC and the revision subscription are independent requests. If a worktree mutation completes after list has already read its Git worktree list but before the subscription is established, the subscription's initial value contains the new revision and is discarded here; the older list response is then rendered and no later refresh occurs. The Worktrees settings can therefore keep showing a removed or newly-created worktree until the user manually refreshes. [ Already posted ]

---

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 bdc613b9f3f9fecc9d611b94a2fa014b393a27ab. 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 PR introduces a large, user-facing worktree lifecycle feature that changes provider startup and cleanup behavior, performs Git/filesystem mutations, and adds authenticated RPCs and default capability exposure. Its cross-cutting runtime impact and auth-package change require human review.

^{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}

[juliusmarminge]

Note

This comment is posted by Julius' dot

Closing for incomplete UI verification. Both attached images show the added list in light and dark mode, including cleanup controls that have since been removed. Neither shows the before state or the Remove interaction.

Please attach current before/after views and a short recording of confirming a safe removal and seeing its row disappear, then request reconsideration.