feat(mcp): expose thread workspace inventory#8685

🟡 Medium src/git.ts:272

Existing persisted VCS-ref caches without worktrees fail VcsListRefsResult decoding after upgrade, so the loader returns ConnectionPersistenceError and users lose the cached/offline branch list until refresh. Because this field is required, make it backward-compatible with a default empty array or migrate the cache schema.

Fixed in c49a0611921ca9671aae4b590b0339a0001a6dd3 by removing the worktrees field from VcsListRefsResult entirely. Worktree enumeration now uses a dedicated internal Git workflow read, so existing RPC responses and persisted branch caches keep their original shape. Added old-shape contract decode and client-runtime persisted-cache coverage.

🟡 Medium mcp/WorktreeMcpService.ts:637

A deleted Git worktree is returned with availability: "available" and no statusError, so agents can treat a stale checkout as usable. readWorkspaceStatus succeeds with isRepo: false for a missing cwd; check filesystem existence in the success branch before setting availability.

✅ Resolved in 0130019314ce24de5c9733dad2286cec6c23160a

Fixed in 0130019314ce24de5c9733dad2286cec6c23160a. A successful status read with isRepo: false now checks filesystem existence and reports availability: "missing" for a deleted checkout or "unreadable" for an existing non-worktree path, with a matching statusError. Added coverage for the stale registered path case.

🟠 High orchestration-v2/orchestrator-mcp-server.md:309

t3_worktree_status returns operation_failed instead of a not_repository result when the saved worktree path is missing or outside a Git repository. The implementation starts loadWorktrees(workspacePath) before constructing the agreement, and GitVcsDriver.listWorktrees fails for that path, so the documented workspace_missing/not_repository state is never reported. Handle this discovery error when building the agreement so the status result remains visible.

Fixed in 0130019314ce24de5c9733dad2286cec6c23160a. t3_worktree_status now treats worktree inventory discovery as optional for the saved path, separately checks path availability, and still returns a typed workspace_missing or not_repository agreement instead of failing the whole status read. Added a missing saved-worktree regression where inventory discovery fails.

Inventory failure marked not a repository

Medium Severity

t3_worktree_status sets agreement to not_repository whenever worktree inventory for the thread path fails, even if actualWorkspace.isRepo is already true. A timeout or git worktree list error then contradicts the status payload and can send the agent down the wrong repair path.

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

Fixed in b3658e777174937b83647d9199388c7b6d8849ba. Inventory failure no longer forces not_repository: that result is based only on actual.isRepo === false; when status proves a repository but physical inventory identity cannot be established, the tool reports workspace_missing instead. The focused status suite covers the distinct missing, non-repository, and inventory-unavailable outcomes.

Status dies if project inventory fails

Medium Severity

t3_worktree_status requires loadWorktrees on the project root to succeed. If that inventory read fails, the whole tool errors even after the thread's own git status has already been read, so an attached worktree cannot report recorded vs actual state.

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

Fixed in b3658e777174937b83647d9199388c7b6d8849ba. Project-root inventory is now optional during status reconciliation, just like saved-workspace inventory. A real GitWorkflowService non-repository test uses an existing plain directory and verifies the tool returns not_repository with its recorded and actual state instead of failing the read.

🟡 Medium mcp/WorktreeMcpService.ts:609

listWorktrees omits thread bindings when a thread's recorded worktreePath is a nested directory such as /repo/packages/server: threadWorkspacePath returns that directory, while inventory keys the checkout by /repo, so the comparison at line 619 yields no match and reports an incorrect bindings and bindingCount. Resolve each recorded path to its Git worktree root before comparing it with inventory paths.

✅ Resolved in 3beb4dc0f7d7c8da625bccca93d2d8f7d77d54b1

Fixed in 3beb4dc0f7d7c8da625bccca93d2d8f7d77d54b1. Recorded paths are now realpath-canonicalized and mapped to the longest canonical physical worktree root from the existing inventory before bindings are counted. The focused regression uses a nested recorded cwd, verifies it binds to the root entry, and asserts that pagination still performs only one inventory read and one status read for the returned page.

🟠 High mcp/WorktreeMcpService.ts:626

listWorktrees performs a Git inventory lookup for every unresolved recorded thread path before returning any page, so limit: 1 still scans all stale archived/deleted bindings and can leave the MCP request hung on thousands of slow operations. Bound this resolution by the requested page (or otherwise avoid resolving unlisted bindings) so pagination also bounds the work performed.

✅ Resolved in d1a69553ec81ba2d68399b392dd2b7ef993becc9

Fixed in d1a69553ec81ba2d68399b392dd2b7ef993becc9. Resolution work is page-local and capped. Candidate paths first pass a non-authorizing nearest-root filter, then Git common-dir/current-root identity proves attribution so nested independent repositories are not counted. Ordinary inventory failures mark ; defects and interruption still propagate. The focused limit=1 and failed-candidate tests pass.

Unused worktrees field persisted in cached snapshot

Low Severity

The new worktrees field on GitRefsSnapshot is populated inside readGitRefsSnapshot and stored in the TTL-governed snapshot cache, but no consumer of the snapshot ever reads snapshot.worktrees. The listRefs function only accesses localBranches, remoteBranches, and hasPrimaryRemote. The worktree data IS used internally within readGitRefsSnapshot to build existingWorktrees and worktreeMap, but it doesn't need to be part of the returned/cached struct. Keeping it there adds dead data to every cached entry without any reader.

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

Confirmed. GitRefsSnapshot.worktrees was dead cached payload: readGitRefsSnapshot still keeps its local worktrees value to map checked-out paths onto branch refs, while listWorktrees remains the dedicated inventory API. Removed only the snapshot interface member and returned property in 602bf694f3a73d5f8029d961d9e2df9cddb8d449. Both Git driver suites pass (65 tests), and the canonical server typecheck completes without errors.

mcp/WorktreeMcpService.ts:689

readWorkspaceStatus fails only with the tagged WorktreeMcpFailure, so this could catch that tag directly instead of inspecting an Exit/Cause. Two consequences of the current form: defects and interruption are also folded into an availability: "missing"/"unreadable" entry rather than propagating, and statusError is re-derived from a squashed cause instead of the error's own structured message.

Consider replacing the exit inspection with Effect.catchTags({ WorktreeMcpFailure: ... }) (or Effect.catch, since the whole error channel is handled) and using error.message for detail; the later statusExit.value read would become the success value of that pipeline.

No longer relevant as of 07d53fd07b5fd71d4c3a71ed0c37ca24bed2931c

Fixed in 07d53fd07b5fd71d4c3a71ed0c37ca24bed2931c. The listing now matches only the typed WorktreeMcpFailure channel; defects and interruption propagate. Focused coverage asserts the ordinary unreadable result, Cause.hasDies for a defect, and Cause.hasInterruptsOnly for interruption (64/64 lower tests; the 115/115 upstack suite also passes).

Verified: typed failures are handled while defects and interruption propagate. Thanks.