feat(mcp): expose thread workspace inventory

[juliusmarminge]

Problem

An agent can see only the branch and worktree path recorded on its own thread. That does not reveal whether Git still agrees, which physical worktrees are available, whether they are dirty, or which live threads are bound to them.

Change

• enrich t3_worktree_status with separate recorded and actual workspace state plus an agreement result
• add bounded, cursor-based t3_worktree_list results with bounded thread bindings and per-entry availability
• add a dedicated internal Git worktree inventory read that returns canonical common-directory and physical worktree-root identity
• include detached and missing/prunable registered entries without changing the existing paginated vcs.listRefs wire payload or cache shape
• resolve each distinct nested or symlinked recorded path through Git identity before attributing it to a physical checkout
• expose both read tools consistently, including Claude read-only permission handling, presentation labels, tests, and docs

Behavior

These tools are read-only and current-project scoped. Inventory pages are sliced before per-worktree status reads, one missing or unreadable checkout produces an explicit entry outcome instead of failing the entire page, and plain non-repository project roots return a truthful status. Nested independent repositories are not attributed to a containing checkout. The tools do not create, switch, remove, prune, revive, or repair worktrees.

Validation

• vp test run apps/server/src/mcp/WorktreeMcpService.test.ts (60 tests)
• vp test run apps/server/src/vcs/GitVcsDriverCore.test.ts (58 tests)
• focused contracts, client-runtime, Git workflow, MCP registration, and Claude adapter coverage from the stack
• old-shape vcs.listRefs decode/cache compatibility coverage
• real GitWorkflow non-repository status plus detached, symlink, nested-repository, archived-binding, missing-path, and stale-entry coverage
• targeted server TypeScript check and targeted lint

Dependency

Bottom of native stack #8711, rooted on agents/mcp-controls/base-490318a at 490318afa505d3d033295eca12d7e62b4b922725. The dependent checkout mutation is PR #8680. This is independent of lifecycle PR #5589.

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

---

Note

Medium Risk
WorktreeMcpStatusResult is an expanded MCP contract (new required fields), and list/status depend on new Git inventory reads with nuanced path/binding attribution logic.

Overview
Agents get read-only workspace discovery for the calling thread’s project: t3_worktree_list pages Git-registered checkouts (including detached entries) with dirty state, availability, and thread bindings, and t3_worktree_status now compares recorded thread metadata to on-disk Git state via an agreement field.

The server adds GitWorkflowService.listWorktrees / GitVcsDriver.listWorktrees, returning canonical repository identity (repositoryCommonDir, physical roots, real paths) and reusing shared porcelain parsing so stale or missing registrations still appear in inventory without changing the existing vcs.listRefs wire shape. List/status logic canonicalizes paths, resolves nested recorded cwd values through Git identity (excluding nested independent repos), bounds binding resolution and per-page status reads, and surfaces missing/unreadable checkouts per entry instead of failing the whole page.

Contracts, MCP registration, Claude read-only allowlists, presentation labels, docs, and broad tests cover pagination, archived bindings, and non-repository project roots.

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

Note

Add t3_worktree_list MCP tool and revamp t3_worktree_status inventory

• Adds the t3_worktree_list MCP tool to provide a paginated inventory of worktrees, thread bindings, and workspace statuses for the calling thread's project.
• Revamps the t3_worktree_status handler in WorktreeMcpService.ts to concurrently read workspace settings, Git inventories, and filesystem existence, computing agreement states like in_sync or branch_mismatch.
• Adds a listWorktrees operation to GitVcsDriver and GitWorkflowService to fetch repository worktree inventory, preserving detached and stale checkout records.
• Risk: t3_worktree_status now fails when the actual Git workspace status cannot be read instead of returning a settings-only result; parseWorktreeCheckouts now preserves detached and missing worktree entries, changing the data returned by readGitRefsSnapshot.

^{Macroscope summarized 07d53fd.}

[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: 71b8ce76-89e2-4f74-b444-f8a7e54f290f

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 07d53fd.

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 model-visible worktree inventory capability and substantially expands existing worktree status behavior across MCP, contracts, orchestration, and Git infrastructure. The cross-layer runtime impact and non-trivial inventory/path-resolution logic warrant human review.

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

[macroscopeapp]

Macroscope has since reviewed this pull request. An earlier review was skipped by a cost limit; a review has now completed, so that notice no longer applies.

[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 d1a6955. Configure here.}