Worktree lifecycle audit
PR #15080 rebased onto main c77a7b7eeb. Final reviewed revision: 6cf10f7db6.
PR updated and pushed at the reviewed revision. GitHub reports no merge conflicts; CI and review bots are running. Fresh Codex review approves. Claude found no data-loss, lease, readiness or contract defects, but objects to CLI-only removal for submodule checkouts. The lead retains that documented restriction to protect submodule work.
Fixes and simplifications
| Area | Result |
|---|
| Removal ownership | Settings, thread deletion, automatic cleanup, MCP and legacy RPC removal use WorktreeService. Main's cleanup policies, eligibility checks and report details are preserved. |
| Setup recovery | Required setup failure or cancellation remains pending across server restarts. Atomic project-and-checkout markers distinguish recreated checkouts and stop stale completions from clearing newer readiness. Projects sharing a Git repository retain their own setup, including projects rooted in different subdirectories. Replacement checkout generations use separate setup shells so a deleted working directory cannot be reused. |
| Checkout identity | Removal refuses linked threads whose recorded branch differs from the checkout. Revival honors environment and project submodule settings, plus current and previous managed roots. |
| Startup coordination | Removal, revival and terminal startup share checkout leases. Raw terminals in subdirectories or nested repositories lease enclosing Git roots. Provider startup permits main's background branch rename while checking the checkout path. |
| Cleanup behavior | Tracked edits are always protected. Other local files follow the configured automatic cleanup policy; manual removal requires ignored-file confirmation. Main's five-minute git clean timeout is restored. |
| Submodule preservation | Checked-out submodules and retained submodule repositories explicitly block removal. Git refuses unforced removal, and forcing it could delete commits kept only in submodule metadata. The inventory explains why manual handling is required. |
| Smaller model | Removed the unused generic listWorkspaces API and its schema. Kept the Git inventory implementation and a small internal type. Avoided a second cleanup queue or a new abstraction around context-specific path errors. |
Review decisions
Immediate manual removal after deleting a thread can return an in-use skip while provider or terminal teardown finishes. This is the conditional removal contract. Forcing deletion would undermine its safeguard; configured automatic cleanup retries after deletion effects settle.
Claude requested an in-app submodule removal override. The lead declines it in this change: outer Git status does not expose unpublished submodule branches or stashes retained in metadata. The real-Git test preserves such a branch in an otherwise clean checkout. A confirmation alone would weaken the removal promise; safe automated submodule removal needs separate ref-preservation work. After preserving submodule commits, stashes and local files, a maintainer can remove the checkout with git worktree remove --force <path>.
The optional shared repository-key helper is deferred. Both small probes use the same Git identity and canonicalization; their error handling and service context differ. Behavioral tests cover nested roots and aliases.
A missing checkout outside managed roots requires manual restoration. The error and user guidance now say so.
Verification
Final focused removal, setup, Storage cleanup and contract/client tests: 89 passed. The deinitialization case was extended and rerun separately. Earlier configured-root, lifecycle, provider startup and provisioning checks also passed. Terminal service suite: 90 passed, including gated startup/removal concurrency cases. Scoped Git suite: 260 passed, one known baseline test skipped. Contract, destination-permission, MCP, RPC and shared-client checks also passed.
Server, web, mobile and client-runtime package typechecks passed. Changed-file lint, formatting and diff checks passed. No repository-wide checks were run.
The skipped Git diff-preview test, preserves renames, unusual paths, modes, and binary statistics, also fails on clean main with a previousPath TypeError. It is unrelated to this PR. GitHub CI remains the full-suite gate.
Submodule inspection uses bounded directory metadata reads. Oversized or unreadable output keeps the checkout. The real setup-shell test runs on POSIX and skips Windows. A leftover failed-setup marker can cause an extra setup if an external tool later reuses that exact project and path; retaining readiness favors running required setup.
Surface coverage and limits
Web and mobile inventory use shared client commands and contracts. Desktop uses the web surface. Destination permissions are checked at execution. Provider-independent startup handles recovery before adapters run and preserves shared provider sessions. Local, remote and tunnel clients reach the same environment-owned services; MCP uses the same removal owner.
No new visual design was introduced. The original PR's web and iOS media are retained and labeled as original verification. Browser, native mobile and packaged Electron verification were not repeated for this revision.