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 #8686. 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
Mutates Git checkouts and durable thread metadata with complex concurrency, rollback, and cross-project ownership checks; mis-handling could leave Git and recorded branch/worktree out of sync.

Overview
Adds t3_thread_checkout, an MCP path for an existing thread to switch branches (including create), return to the project root, reuse a listed worktree, or create a new worktree. Git runs before the durable thread.metadata.update, with dirty-tree and cross-thread workspace guards, commit/ref verification, and partial_failure when binding or rollback cannot be proven safe.

Handoff is aligned with the same model: threads already on a worktree can move to a new one, rollback drops only the new worktree (not the branch), and dispatch uses expectedBranch / expectedWorktreePath / expectedArchived compare-and-set in the orchestrator. Per-thread (and per-checkout) workspaceTransitionsInFlight serialization covers handoff and checkout. GitWorkflowService.resolveCommit supports verification; status/list behavior is tightened for missing or non-repo workspaces.

Contracts, toolkit registration, docs, and a large WorktreeMcpService test suite cover the flow; a V2 integration test asserts queued continuation after workspace binding detach.

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

Note

Add t3_thread_checkout tool for agents to switch thread workspaces

• Adds a new MCP checkout operation (WorktreeMcpService.checkout) that lets agents move their thread to an existing branch, return to the project root, reuse an unclaimed worktree, or create a new worktree. Git mutations run before durable binding updates, with rollback and conflict detection against other threads.
• Introduces optimistic concurrency on thread.metadata.update via new expectedBranch and expectedArchived fields in orchestrationV2.ts; the orchestrator now fails dispatch when these preconditions do not match current state.
• Reworks performHandoff in WorktreeMcpService.ts to use the same optimistic-concurrency binding updates, safer rollback (no branch deletion), and structured partial_failure diagnostics when cleanup cannot be guaranteed.
• Replaces handoffThreadsInFlight with workspaceTransitionsInFlight to serialize both handoffs and checkouts per thread and per workspace.
• Behavioral Change: WorktreeMcpFailure gains new error codes (checkout_in_progress, dirty_workspace, workspace_in_use, workspace_shared, partial_failure) and an optional partial payload; thread.metadata.update now rejects when expectedBranch or expectedArchived mismatch.

^{Macroscope summarized 03d0e2b.}

[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: d617704a-a4b3-42fb-9621-a0a4bf0602a3

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.}

[github-actions]

Thread transfer impact

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

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 a destructive MCP capability that can switch branches, create or reuse worktrees, update durable thread bindings, run setup scripts, and restart provider sessions. Its substantial cross-component concurrency and rollback behavior, along with changed handoff semantics, creates a broad runtime surface that requires human review.

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

[cursor]

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

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

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