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: deliberately model-invocable — scanning is read-only. Every cleanup action is gated on explicit user approval.

Configuration

This skill operates on git worktrees and branches only; it reads no state files, so workspace.yaml's state paths do not apply. The one setting it depends on is the default branch, which it detects (step 0) rather than hardcoding. Full reference: docs/state-model.md.

When to Use

• After a system crash or forced session termination
• When parallel-session hooks warn about stale processes
• When you find 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.