feat(worktrees): reap worktrees whose work has already landed (PP-49x5)

[timothyfroehlich]

Why

Nothing in PinPoint ever removed an agent worktree that was still on disk. Measured on main today: 60 worktrees, 66 GB, 59 of 96 port slots consumed (61% of the address space). 43 were on branches whose PR already merged with a clean tree; 8 more were bridge worktrees carrying zero commits ahead of origin/main.

All three existing mechanisms miss this by construction:

Mechanism	Why it misses
WorktreeRemove hook → worktree_cleanup.py	Only fires when something else initiates removal. A background agent that commits, pushes and ends never initiates. ExitWorktree is scoped to EnterWorktree sessions and doesn't apply to Agent(isolation:"worktree").
worktree_orphan_sweep.py	Reconciles slot entries whose directory is gone. A worktree still on disk is "active" by its definition — invisible, and its Supabase volumes are deliberately protected.
stale-worktrees.sh	Hard-scoped to ../pinpoint-worktrees/*.

The predicate matters more than the plumbing

stale-worktrees.sh uses "no open PR + clean", which is indistinguishable from an agent working right now that hasn't opened its PR yet. At the moment of measurement zero worktrees had an open PR while at least two agents were live — that rule would have deleted live work.

So this reaps only on positive proof that the work is already on main:

• REAP/merged — merged PR and local HEAD is that PR's headRefOid and clean tree. The SHA equality is load-bearing: branches are squash-merged, so their commits are never ancestors of main and an is-ancestor test gives a false negative on every merged branch. HEAD past the merged SHA = post-merge work → REVIEW.
• REAP/empty — no merged or open PR, clean tree, zero commits ahead of origin/main.
• REVIEW — unmerged commits or a dirty tree (untracked files count). Reported every run, never touched.
• KEEP — open PR, or a live process whose cwd is inside the worktree.

Unknown is never mergedness. If gh can't be queried, those branches are UNKNOWN — not "no PR". They classify REVIEW, never REAP, and the run exits non-zero. Same discipline as the sweep's "unknown is never zero" (PP-5o7b) and worktree_cleanup.py's volume query (PP-3w4g). A total gh outage is a no-op, not a mass deletion.

What's here

• scripts/worktree_reap.py (new) — dry-run by default. Delegates removal to worktree_cleanup.py (Supabase stop, Docker volumes, slot dealloc already live there) and surfaces its exit codes with their meanings rather than flattening them to "failed" — flattening is the standing complaint in PP-r7tv. Never the main worktree, never one containing the invoking cwd, never a live process's cwd (Linux /proc, macOS lsof; unavailable → note and continue, since it's defence in depth, not the safety floor). --quiet skips du.
• scripts/workflow/merge-pr.sh — reaps the merged branch's worktree in a fail-open subshell mirroring the post-merge huddle notice exactly (set +e, || true). The merge already happened; no post-step may propagate an error. The reap re-derives the verdict itself — merge-pr.sh passes no opinion about safety.
• .claude/hooks/session-start-orphan-sweep.sh — second dry-run pass alongside the sweep, same 6h throttle, its own 10s budget.
• Docs — AGENTS.md §4, CLAUDE.md, and the orchestrator skill all asserted that agent worktrees "are handled by the WorktreeRemove hook". That premise is false and is why nobody noticed.

Tests

scripts/tests/test_worktree_reap.py (26 tests) — real throwaway git repos with real worktrees so the commit-graph questions get real answers; gh and worktree_cleanup.py stubbed, so nothing reaches GitHub and nothing is removed. Covers every classifier edge including test_squash_merged_branch_is_still_reaped, which an is-ancestor implementation fails, and test_untracked_file_alone_blocks_the_empty_reap.

test_merge_pr_automerge.py now shadows python3 for the same reason it shadows bd: unshadowed, a test merge would run worktree_reap.py --apply against this machine's real checkout. Plus a case pinning that a failing reap doesn't change merge-pr.sh's exit status.

Verification

pnpm run check green. Live dry-run against the host (62 worktrees): 52 REAP (44 merged, 8 empty), 6 REVIEW, 4 KEEP, 2.2s in --quiet (inside the hook's 10s ceiling), 7.9s with du. feature/pp-4zcj-oxlint and its untracked plan doc — the file that exists nowhere else on disk — survive twice over: dirty tree and a live process cwd.

--apply was deliberately not run. The tool ships; Tim runs the reclamation.

Out of scope

Branch reaping (PP-m22p, 183 leaked worktree-agent-* branches), folding in stale-worktrees.sh, and the REVIEW worktrees themselves — those need judgment, not a rule. worktree_cleanup.py's contract is unchanged; the WorktreeRemove hook still calls it.

Closes PP-49x5.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VypoeEVeXdF7Y3KfyWYeP8

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pin-point	Ready	Preview	Aug 1, 2026 8:10pm

[Copilot]

Pull request overview

Adds an explicit “reap finished worktrees” mechanism to prevent long-lived agent worktrees from accumulating on disk and consuming Supabase port slots, while keeping safety grounded in positive proof (merged-SHA equality or zero-commits-ahead) and preserving dry-run-by-default discipline.

Changes:

• Introduces scripts/worktree_reap.py to classify and (optionally) remove worktrees whose work has already landed, delegating deletion to worktree_cleanup.py and preserving meaningful exit codes.
• Hooks reaping into merge-pr.sh (fail-open) and the Claude SessionStart audit hook (dry-run only, time-capped).
• Adds a comprehensive pytest suite for the classifier and hardens the merge workflow test harness to stub python3 to prevent real reaps during tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/worktree_reap.py	New reaper script: PR-state lookup + git-state predicate + optional delegation to worktree_cleanup.py.
scripts/workflow/merge-pr.sh	Runs a fail-open reap pass for the merged branch’s worktree after a successful merge.
scripts/tests/test_worktree_reap.py	Adds end-to-end classifier tests using real throwaway repos/worktrees and stubbed gh/cleanup.
scripts/tests/test_merge_pr_automerge.py	Stubs python3 and asserts the new post-merge reap step doesn’t affect merge exit status.
CLAUDE.md	Updates documentation to distinguish cleanup-on-removal vs reaping-finished-worktrees.
AGENTS.md	Documents the new reaping tool and the SessionStart dual-audit behavior.
.claude/hooks/session-start-orphan-sweep.sh	Adds a second dry-run audit pass for reaping finished worktrees, each with its own 10s cap.
.agents/skills/pinpoint-orchestrator/SKILL.md	Updates worktree-health guidance and adds the new reap command.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

scripts/worktree_reap.py:81

• CLEANUP_EXIT_MEANINGS[1] is more specific than worktree_cleanup.py’s documented EXIT_FAILED meaning (which can also be a usage error). This could mislead someone interpreting a propagated exit code 1.

    1: "FAILED — worktree not removed; slot kept to avoid a port collision",

scripts/worktree_reap.py:69

• EXIT_GH_UNAVAILABLE is set to 1, but 1 is also a valid propagated exit code from worktree_cleanup.py (EXIT_FAILED). That makes a top-level exit status of 1 ambiguous ("gh unavailable" vs "cleanup failed"), which undermines the goal of preserving meaningful cleanup exit codes for callers.

This issue also appears on line 81 of the same file.

#: At least one branch's PR state could not be determined, so the report is
#: incomplete and nothing that depended on that state was reaped. Deliberately
#: the same value as `worktree_orphan_sweep.EXIT_DOCKER_UNKNOWN`: in both
#: scripts, 1 means "this run could not see everything".
EXIT_GH_UNAVAILABLE = 1

[timothyfroehlich]

Acted on both suppressed comments from the last review (953601d), because they land squarely on what this PR claims to do.

EXIT_GH_UNAVAILABLE = 1 colliding with cleanup's EXIT_FAILED — right, and I had talked myself into it during design by pointing at worktree_orphan_sweep.EXIT_DOCKER_UNKNOWN = 1. That precedent does not transfer: the sweep is free to use 1 because it propagates nobody else's codes. This script propagates worktree_cleanup.py's, so a top-level 1 was ambiguous between "gh was unreachable" and "a cleanup failed" — the same information loss as flattening, reached from the other direction. EXIT_GH_UNAVAILABLE is now 6, and 0-4 are reserved for cleanup exclusively.

Chasing that turned up a third instance you did not see: run_cleanup() also returned 1 when cleanup could not be launched. Nothing ran in that case, so there is no cleanup verdict to report — now EXIT_CLEANUP_UNRUNNABLE = 7.

CLEANUP_EXIT_MEANINGS[1] overclaiming — also right. worktree_cleanup.py documents 1 as "usage error, or the git worktree removal itself failed"; mine said only the second half. A narrower wording than the source is worse than none, since the whole point is that a caller can trust the code it was handed. Now matches.

test_this_scripts_own_exit_codes_never_collide_with_cleanups fails if any future status lands inside cleanup's range, so the invariant is now structural rather than remembered.

—Claude

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.