feat(worktrees): server-managed worktree lifecycle on orchestrator v2

[StiensWout]

Important

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

This supersedes #4742. The earlier PR was built on the legacy orchestration paths; this version ports the feature to V2 and incorporates its outstanding review feedback.

Problem

Thread worktrees pile up with no way to see or clean them. Web and remote users had nothing at all, and the only cleanup path was a desktop-native prompt on thread deletion.

Solution

The server now owns the worktree lifecycle: it derives an inventory from Git plus the V2 projections, protects anything with active threads, local changes, or unpushed commits, and cleans up the rest by retention policy (or immediately when a worktree loses its last thread, if enabled). Missing worktrees are revived before a provider turn starts. Every connected client gets the same management surface.

Settings → Source Control gains a Worktrees section: one ledger per connected environment that advertises the new worktreeManagement capability, with per-environment cleanup policy and safe manual removal — so remote environments' worktrees are manageable from any client. Older servers are excluded per the usual version-skew contract.

Light	Dark

Safety notes

• Pruning is non-forced and revalidates current state on the server; all worktree mutations are serialized.
• Safety joins all projects that share one Git common directory, including nested project roots.
• Paths are canonicalized, and revival rejects symlink-ancestor escapes outside the managed worktree root.
• Local branches and checkpoint refs are retained for revival.

Verification

• Server vcs suite (14 files / 113 tests), web settings + worktree suites (18 files / 117 tests), contracts (275 tests) pass; server, contracts, client-runtime, and web typechecks clean.
• Integrated browser passes on the live dev environment: inventory streaming without reloads, prune with confirmation, revival, and the environment-scoped section after the multi-environment rework.

Initial V2 port implemented with GPT-5.6 Sol via Codex in T3 Code. Worktree settings redesign, review fixes, and multi-environment management by Claude Fable 5 via Claude Code in T3 Code.

Note

Add server-managed worktree lifecycle with listing, pruning, revival, and background cleanup on orchestrator v2

• Introduces WorktreeLifecycle, WorktreeService, WorktreeReaper, WorktreeDeletionCleanup, and WorktreeRevivalService to manage the full lifecycle of Git worktrees on the server, including serialized mutations, inventory change streaming, scheduled pruning, and post-deletion cleanup.
• Adds four new WebSocket RPCs (vcs.listWorktrees, subscribeWorktreeInventory, vcs.pruneWorktrees, vcs.reviveWorktree) with authorization scopes and corresponding client-runtime atoms for the web app.
• ProviderTurnStartService now revives and validates the worktree for a thread before provider session operations, restarts the session when the worktree generation or path changes, and serializes startup per ProviderSessionId.
• GitWorkflowService methods preparePullRequestThread, createWorktree, and removeWorktree now acquire a mutation permit and emit an inventory change notification after completion.
• Adds a Worktree Management section to Source Control settings, with retention controls, rich per-worktree metadata, and an in-app confirmation dialog for project removal.
• Removes the client-side prompt to delete orphaned worktrees when deleting a thread; orphan cleanup is now handled server-side via WorktreeDeletionCleanup.
• Risk: Worktree creation and removal commands are now serialized per environment (not per environment+cwd), which changes concurrency behavior for clients issuing concurrent worktree commands.

^{Macroscope summarized 0eec832.}

---

Note

High Risk
Changes provider turn startup, shared Git worktree state, and automated deletion/pruning paths where incorrect safety checks could remove data or strand sessions.

Overview
Introduces server-managed worktree lifecycle so clients can list, subscribe to, prune, and revive worktrees uniformly, gated by a new worktreeManagement environment capability.

Inventory and mutations: WorktreeService builds inventory from git worktree list plus V2 thread shells, applies prune blockers (active threads, dirty state, unpushed commits), and revalidates immediately before removal. WorktreeLifecycle serializes mutations and publishes inventory revision streams. WorktreeRevivalService recreates missing paths under the managed root (with symlink/path checks) and runs project setup scripts; WorktreeReaper and WorktreeDeletionCleanup handle retention sweeps and thread.deleted orphan cleanup per server settings.

Git layer: Adds listWorkspaces and shared porcelain parsing for newline git worktree list output (replacing -z-only parsing for older Git). GitWorkflowService acquires mutation permits and bumps inventory on PR worktree prep, create, and remove.

Orchestration: ProviderTurnStartService calls reviveForThread before opening a provider session, closes/reopens the session when the worktree was revived or its generation changed, and serializes startup per ProviderSessionId. Projection rechecks for “still starting” no longer swallow read failures.

Wire-up: New WS methods with auth scopes, server layer composition, and startup hooks for deletion cleanup and the reaper after the effect worker starts.

^{Reviewed by Cursor Bugbot for commit 0eec832. 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: b1a1bf39-e72a-4ff4-bbab-b9ad5f9a2ea0

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]

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

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. 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}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

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

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

[cursor]

Cancelled restart still loads thread

Medium Severity

After closedForRestart, open and the generation update correctly continue even when the attempt left "starting", but there is no matching gate before ensureThread / resumeThread / handoff writes. A superseded attempt can still mutate the shared provider session and emit handoff events before the later "starting" check returns.

 

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

[cursor]

listRefs still requests -z

Medium Severity

This change drops -z from listWorkspaces and documents that the codebase no longer requests it for Git 2.34 compatibility, but listRefs still runs git worktree list --porcelain -z. On Ubuntu 22.04 Git that call fails soft and clears worktree path associations on refs.

Additional Locations (1)

• apps/server/src/vcs/GitWorktree.ts#L2-L8

 

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