feat(mcp): let agents change thread workspaces

[juliusmarminge]

Problem

Existing threads cannot safely move between their project root, branches, and worktrees through MCP. Updating only the recorded branch can leave durable thread state out of sync with Git, and a workspace change can detach the caller before follow-up work is queued.

Change

• add typed t3_thread_checkout targets for branch switch/create, canonical inventory worktree reuse, project-root return, and new-worktree creation
• resolve symlinked and nested paths to canonical repository and physical-worktree identity before ownership checks
• serialize each physical checkout across callers and re-read bindings across projects after acquiring the guard, failing closed when a possible same-repository owner cannot be resolved
• invoke Git's real remote/tracking resolution, including a verified detached remote result, and verify post-switch ref and commit identity before durable binding
• recheck caller lifecycle, checkout state, and physical owners immediately before mutation, then enforce the archive constraint inside the serialized V2 metadata decision
• use one conservative rollback rule that rechecks ref, dirty state, HEAD commit, physical owners, and caller lifecycle; retain created branches when safe cleanup cannot be proven
• preserve the committed handoff result and queued continuation across caller detachment or later fallible work
• recover stale thread bindings by selecting a healthy listed checkout or creating from the project root without touching the missing checkout

Behavior

Workspace path changes queue an optional continuation after the binding commits and before the calling provider session detaches. Same-workspace retries are idempotent. Failures report whether Git changed, whether the binding committed, and whether rollback completed, failed, or was unsafe. Unknown, unattested, or concurrently changed Git state is preserved. The workflow never stashes or drops files, removes existing worktrees, or implements retention, pruning, or revival.

Validation

• vp test run apps/server/src/mcp/WorktreeMcpService.test.ts (107 tests)
• vp test run apps/server/src/vcs/GitVcsDriverCore.test.ts (59 tests)
• focused Git workflow, V2 runtime/continuation, MCP registration, contracts, client-runtime, and provider adapter tests
• real Git explicit-remote/detached, nested-repository identity, and conservative rollback coverage
• real V2 archive constraint plus persisted detach receipt, queued continuation, and fake-provider cwd coverage
• targeted server TypeScript check and targeted lint

Dependency

Upper member of native stack #8711. Depends on workspace inventory PR #8685 and remains independent of lifecycle PR #5589.

Implemented by GPT-5.6-Sol via Codex in T3 Code.

---

Note

High Risk
Large changes to Git orchestration, durable thread bindings, and handoff failure/cleanup semantics; incorrect partial-failure or rollback logic could leave Git and thread metadata diverged or retain unintended worktrees.

Overview
Adds t3_thread_checkout so agents can move a thread between branches, the project root, listed worktrees, or a new worktree (via the existing handoff path). Git mutations run first; durable thread.metadata.update bindings commit only after ref/commit verification, with optional continuation queued when the workspace path changes.

Handoff no longer rejects threads already on a worktree—it can create a new checkout from the current binding. Failed or racy bindings surface partial_failure with rollback metadata instead of always deleting the new worktree/branch; cleanup runs only when exclusive ownership and unchanged HEAD/dirty state can be proven. Per-thread serialization expands to physical-checkout guards and cross-project owner scans so concurrent checkout/handoff on the same path fails closed.

Orchestrator now honors expectedBranch and expectedArchived on metadata updates (alongside existing worktree CAS). GitWorkflowService.resolveCommit supports commit identity checks. Status/list behavior gains edge-case coverage; tool copy drops the “already in worktree” handoff restriction.

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

Note

Add checkout operation to WorktreeMcpService for thread workspace changes

• Adds a new checkout MCP operation with four target types: branch, existing worktree, project root, and new worktree. Agents can switch branches, move to unclaimed worktrees, return to project root, or create new worktrees.
• Reworks performHandoff to validate physical source and created worktrees before binding, detect concurrent thread changes, and return partial-failure details with rollback metadata when a created worktree cannot be safely removed or its binding outcome cannot be verified.
• Adds expectedBranch and expectedArchived compare-and-set fields to thread.metadata.update in orchestrationV2.ts; Orchestrator.dispatch rejects stale updates that do not match current thread state.
• Extracts shared loadRefs, loadActiveWorkspaceBindings, queueContinuation, and readWorkspaceBranchOrNull helpers; transitions now share a single in-flight registry for both per-thread admission locks and physical-workspace reservations.
• Behavioral Change: WorktreeMcpFailure gains checkout_in_progress, scope_mismatch, dirty_workspace, workspace_in_use, workspace_shared, and partial_failure error codes with an optional WorktreeMcpPartialFailure payload. status no longer classifies a path as absent when an inventory record exists. Dispatch failures are treated as committed when a follow-up read confirms the binding, otherwise cleanup removes the created worktree only when exclusive ownership and creation identity are proven.

^{Macroscope summarized 4838416.}

[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: a2fe674c-aa02-4f15-950f-20e9f297b529

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

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

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

[github-actions]

Thread transfer impact

⚠️ The latest CI run did not produce a thread transfer result for 4838416.

This comment will update automatically after the next completed run.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds an agent-facing checkout workflow and changes existing handoff behavior across Git mutation, durable thread bindings, ownership arbitration, rollback, and provider-session detachment. The breadth and side effects of these production changes warrant human review.

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

[macroscopeapp]

Effect service conventions review of the new WorktreeMcpService.checkout path: service tag, inline interface, make/layer, subpath namespace imports, dependency acquisition (yield* Foo.Foo), and error construction all follow the conventions. One test-organization issue noted inline.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

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

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

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