Add worktree handoff and status tools to the t3-code MCP server

[nsxdavid]

What Changed

Closes #3753.

Adds two tools to the t3-code MCP server:

• worktree_handoff creates a worktree and re-points the calling thread at it. branch is the only required argument; the rest are optional:

  • baseRef defaults to the branch checked out in the project workspace
  • startFromOrigin defaults to the existing "new worktrees start from origin" server setting
  • path defaults to the managed worktrees directory
  • runSetupScript defaults to true

• worktree_status reports the thread's current binding (attached or not, worktree path, branch, workspace root) so an agent can check before trying.

No new machinery. The handler runs the same sequence as the thread-bootstrap path in ws.ts: GitWorkflowService.createWorktree, a thread.meta.update dispatch, a status refresh, and the project setup script runner. The session restart with resume on cwd change picks the rest up on the next turn, and worktree cleanup on thread delete works unchanged since it keys off worktreePath. A worktree capability is added alongside preview in the MCP credential.

Deliberately not included: a detach/undo tool. The UI has no equivalent (worktree removal only happens on thread delete), and detaching raises lifecycle questions that seem worth their own discussion.

Why

See #3753: an agent can create a worktree from its shell, but the thread binding lives in T3 Code's orchestration state and nothing agent-reachable can update it, so agent-driven worktree setup dead-ends. The MCP server is the only channel T3 Code exposes to the agent, so this is the only place the capability can live.

Tested with unit tests over the handlers, an HTTP-level test that drives the production MCP layer end to end (auth, initialize, tools/list), and manually in a packaged Windows build: status, handoff from origin, session resume inside the worktree with conversation intact, and cleanup on thread delete.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Handoff mutates thread metadata, runs git operations, and can queue agent messages; rollback and guards reduce orphan worktrees, but incorrect use still affects orchestration and disk state.

Overview
Adds t3_worktree_handoff and t3_worktree_status to the T3 Code MCP server so agents can bind orchestration state to a git worktree, not only create one from the shell.

t3_worktree_handoff creates a worktree (optional origin fetch, custom absolute path, setup script), dispatches thread.metadata.update to point the calling thread at it, optionally queues continuationPrompt before slower follow-up work, and rolls back the worktree if metadata update fails. t3_worktree_status reports attachment, paths, and server defaults. New worktree MCP capability is included on issued credentials; handoffs are serialized per thread.

Contracts in worktreeMcp.ts define inputs, results, and WorktreeMcpFailure codes. The worktree toolkit registers on the HTTP MCP layer next to preview and orchestrator tools, with broad unit coverage and an HTTP tools/list test.

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

Note

Add worktree handoff and status tools to the t3-code MCP server

• Adds two new MCP tools: t3_worktree_handoff creates a git worktree and re-points the thread to it (optionally queuing a continuation prompt and running a setup script), and t3_worktree_status reports the current thread's worktree attachment and defaults.
• Defines contracts in worktreeMcp.ts including validated input/result schemas and a WorktreeMcpFailure tagged error with codes like capability_denied, already_in_worktree, handoff_in_progress, and operation_failed.
• Adds a per-thread in-flight guard in WorktreeMcpService to serialize concurrent handoffs and avoid races on thread attachment.
• Fixes a bug in ProviderSessionManager.ts where detaching a superseded live session could revoke MCP credentials issued by the replacement session; revocation is now scoped to the credential ID of the session being detached.
• The worktree capability is added to ALL_MCP_CAPABILITIES and included in all newly issued MCP credentials.

📊 Macroscope summarized cd1905b. 9 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[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

Run ID: 258caf3d-c0ff-43f5-9581-55a58a16a501

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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]

One convention issue: WorktreeOperationError copies the underlying cause.message into a detail field and builds its message from it, instead of preserving the real failure as cause and deriving the message from structural attributes. The sibling previewAutomation.ts errors already follow the expected pattern (cause: Schema.Defect() plus bounded diagnostics). See inline comment.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a7bf0f58f3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

1 blocking correctness issue found. This PR introduces new MCP tools for worktree management with ~1500 lines of new logic. Multiple unresolved review comments identify medium-to-high severity bugs including race conditions and missing cleanup paths that warrant human review before merging.

^{You can customize Macroscope's approvability policy. Learn more.}

[macroscopeapp]

One finding on the new worktree handlers: WorktreeOperationError requires a cause, but the project-not-found path has no underlying failure and fabricates an Error only to satisfy that field.

^{Posted via Macroscope — Effect Service Conventions}

[juliusmarminge]

please target against #2829 which introduces and reworks the MCP services a bit

[macroscopeapp]

One Effect service-convention violation: the new WorktreeMcpService retains a standalone WorktreeMcpServiceShape interface instead of defining the service interface inline in the Context.Service declaration. See details inline.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

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

There are 3 total unresolved issues (including 2 from previous reviews).

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

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

[macroscopeapp]

🟡 Medium mcp/WorktreeMcpService.ts:241

The re-check in recheckAndBind reads the projection and only then calls thread.metadata.update, but the dispatch unconditionally overwrites worktreePath. A concurrent UI binding that commits between the recheck read and the dispatch gets silently overwritten, leaving the UI-created worktree untracked on disk. The handoffThreadsInFlight set only serializes MCP calls, so it does not prevent this race. The dispatched thread.metadata.update command needs an atomic conditional update (e.g., compare-and-set on the current worktreePath) so the binding only applies when the thread is still unbound at commit time.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/mcp/WorktreeMcpService.ts around line 241:

The re-check in `recheckAndBind` reads the projection and only then calls `thread.metadata.update`, but the dispatch unconditionally overwrites `worktreePath`. A concurrent UI binding that commits between the recheck read and the dispatch gets silently overwritten, leaving the UI-created worktree untracked on disk. The `handoffThreadsInFlight` set only serializes MCP calls, so it does not prevent this race. The dispatched `thread.metadata.update` command needs an atomic conditional update (e.g., compare-and-set on the current `worktreePath`) so the binding only applies when the thread is still unbound at commit time.