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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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

[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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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

[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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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

[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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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

[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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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

[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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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

[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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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

[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

Medium Risk
Large changes to Git mutation, durable thread bindings, and concurrency guards in MCP worktree paths; incorrect rollback or binding logic could leave Git and recorded thread state diverged, though scope is limited to worktree MCP tooling rather than core auth or data stores.

Overview
Adds t3_thread_checkout so MCP agents can move a thread between the project root, an existing listed worktree, a branch switch/create (including remote refs), or a new worktree—mutating Git first, then updating durable thread metadata only after ref/commit verification. Workspace moves can queue a continuation before the provider session detaches.

Handoff is aligned with the same model: attached threads can hand off to another worktree, transitions are serialized per thread and per physical checkout, cross-project ownership is checked via canonical Git identity, and failures can return partial_failure with rollback hints instead of always tearing down created worktrees/branches.

Orchestrator thread.metadata.update now supports compare-and-set via expectedBranch and expectedArchived (alongside existing worktree expectations). GitWorkflowService.resolveCommit is exposed for HEAD/ref verification during these flows.

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

Note

Add t3_thread_checkout MCP tool to let agents switch thread workspaces

• Introduces WorktreeMcpService.checkout and the t3_thread_checkout MCP tool, enabling agents to move a thread to an existing branch, return to the project root, reuse or create a worktree, and create-and-switch new branches
• Adds compare-and-swap guards (expectedBranch, expectedArchived) to the thread.metadata.update command in Orchestrator.ts; the dispatch fails with OrchestratorDispatchError when expectations don't match current thread state
• Replaces per-thread handoff guards with per-physical-workspace serialization (workspaceTransitionsInFlight) in WorktreeMcpService.ts to prevent concurrent mutations to the same checkout
• Hardens gitWorkflow.createRef in GitVcsDriverCore.ts to validate branch names via git check-ref-format and use git branch -- <name> so option-like names are rejected
• Risk: transitionIds key format changes (binding/continuation suffixes replace worktree-handoff values), affecting commandId/messageId identifiers emitted during metadata updates and continuations; status handler now treats a non-repo path with an existing workspace inventory as an error rather than benign

^{Macroscope summarized 0e3839f.}

[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 0e3839f.

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 substantial destructive MCP workflow that can switch branches, create or reuse worktrees, update durable thread bindings, and detach or restart provider sessions. Its cross-component concurrency, rollback, and lifecycle behavior is too broad for automatic approval despite extensive test coverage.

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