recover

/recover — Worktree & Branch Cleanup

Scan for orphaned worktrees, stale branches, and partial work left behind by crashed or abandoned agent sessions. Read-only by default — reports findings and waits for approval before any cleanup.

Invocation: explicitly user-invoked. Scanning is read-only, but the workflow can lead to destructive cleanup; every cleanup action remains separately gated on explicit user approval.

Configuration

This core operates on git worktrees and branches only; it reads no state files, so tracked workspace path configuration does not apply. The one setting it depends on is the default branch, which it detects (step 0) rather than hardcoding.

When to Use

• After a system crash or forced session termination
• When parallel-session hooks warn about stale processes
• When /reconcile finds commits on unknown branches
• Periodic hygiene (monthly, or after heavy parallel work)

Instructions

0. Detect the default branch

Don't assume main. Resolve it once and use it everywhere below:

git rev-parse --git-dir >/dev/null 2>&1 || { echo "not a git repository — nothing to recover"; exit 0; }
DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
DEFAULT=${DEFAULT:-$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p')}
DEFAULT=${DEFAULT:-main}   # no remote at all — fall back and note it in the report

1. List all worktrees

git worktree list --porcelain

Identify:

• Recently touched worktrees: files or .git metadata modified in the last hours — treat as possibly live. git worktree list cannot tell whether a session is actually running; without a lock/heartbeat file or process evidence, classify as unknown activity and never as orphaned.
• Candidate-orphaned worktrees: no recent modification and no activity signal — proceed to inspection, still gated on user approval before any cleanup.
• Stale entries: git tracks a worktree but the directory is gone.