Detect and recover locked worktree entries with missing directories

[helizaga]

Summary

Fixes #180.

git worktree prune skips locked entries by design, so a locked worktree whose directory was deleted (e.g. a crashed agent session under .claude/worktrees/) lingers in the registry and keeps its branch checked out. git gtr clean --merged --yes --force skipped these silently, and a later git branch -D failed with "used by worktree at ...".

clean now detects entries that are locked but whose directory no longer exists:

• warns about each one, then offers to unlock + prune (--force or --yes auto-confirms, --dry-run previews)
• when declined or non-interactive, prints the manual recovery command instead: git worktree unlock <path> && git worktree prune

Auto-unlock stays behind confirmation on purpose: a locked entry with a missing directory can also just be a worktree on an unmounted network/removable volume, which is exactly what the lock protects.

Testing

• bats tests/ — 474 pass
• shellcheck clean
• manual repro of the issue scenario (locked worktree, directory deleted): clean --yes --force unlocks + prunes the entry and git branch -D works afterwards; without confirmation the entry is left alone and the recovery hint is printed

Summary by CodeRabbit

• Bug Fixes

  • Detects and recovers locked worktree registry entries with missing directories (e.g., after a crashed agent). Automatically unlocks and prunes these entries when --force or --yes flags are used.

• Documentation

  • Updated help text and README documentation to explain the new locked phantom worktree detection and automatic recovery behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 653b9fbc-1afa-42bf-805d-e084debc0007

📥 Commits

Reviewing files that changed from the base of the PR and between 828413f and 503b3b4.

📒 Files selected for processing (4)

• README.md
• lib/commands/clean.sh
• lib/commands/help.sh
• tests/cmd_clean.bats

---

Walkthrough

This PR adds automatic recovery for "locked phantom" worktrees—registry entries marked locked whose directories have been deleted. The git gtr clean command now detects these entries, optionally prompts for unlock (or auto-confirms with --force/--yes), and prunes them, preventing branches from remaining stuck in phantom worktrees.

Changes

Locked phantom worktree recovery

Layer / File(s)	Summary
Locked phantom detection and unlock logic lib/commands/clean.sh	New helper _clean_locked_phantoms scans the worktree registry, identifies entries with status=locked whose paths no longer exist, and unlocks them via prompting or automatic confirmation with --force/--yes; integration into cmd_clean calls this helper before other cleanup steps.
Help and README documentation lib/commands/help.sh, README.md	Help text and README updated to document that clean detects locked registry entries with missing directories and explains that --force or --yes automatically confirms unlock-and-prune.
Locked phantom test coverage tests/cmd_clean.bats	Test helper creates locked-but-missing worktree entries; tests verify behavior across flag combinations—default hints at recovery without unlocking, --force/--yes unlock and prune, --dry-run --force reports intent, and --merged integrates recovery before branch checks.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A phantom locked in registry deep,
Its worktree gone, its secrets to keep—
But clean swoops in with unlock and prune,
Freeing branches beneath the moon! 🌙

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main change: detecting and recovering locked worktree entries with missing directories.
Linked Issues check	✅ Passed	The implementation detects locked entries with missing directories, auto-unlocks with appropriate flags, prompts for confirmation otherwise, and provides manual recovery hints—directly addressing all stated requirements from issue #180.
Out of Scope Changes check	✅ Passed	All changes are focused on detecting and recovering locked-but-missing worktree entries; no extraneous modifications to unrelated functionality were introduced.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch clean-recover-locked-missing-worktrees

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}