pal-e-docs

Review: Bug: 31 stale agent worktrees accumulating across repos

review-637-2026-03-28 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Checked against template-issue-bug:
  • [x] Type — Bug
  • [x] Lineage — board, story, arch, discovery session documented
  • [x] Repo — present ("Multiple repos affected. Primary cleanup target: pal-e-platform")
  • [x] What Broke — detailed symptom with table of affected repos and counts
  • [x] Repro Steps — 3 concrete steps, all verified accurate
  • [x] Expected Behavior — references cleanup hooks by name
  • [x] Environment — archbox, worktree paths, related merged PRs
  • [x] File Targets — 3 targets listed (extra section for bug template, helpful)
  • [x] Acceptance Criteria — 3 criteria
  • [x] Constraints — 3 safety constraints (extra section, helpful)
  • [x] Related — 3 claude-custom PRs cited

Traceability

  • [x] story:superuser-deploy — present on board item
  • [x] arch:worktree — present on board item
  • [x] Forgejo issue — forgejo_admin/pal-e-platform#243, open

File Targets

  • [x] hooks/cleanup-worktrees.sh — verified exists at ~/claude-custom/hooks/cleanup-worktrees.sh. Registered as SessionStart hook in ~/.claude/settings.json. Contains 7-day age threshold, scans 22 repos.
  • [x] Post-merge hook worktree cleanup logic — verified in ~/claude-custom/hooks/forgejo-helper.sh (function remove_worktree_for_branch) and ~/claude-custom/hooks/post-mcp-merge-rebase.sh.
  • [ ] "Claude Code's built-in worktree management (.claude/worktrees/)" — ISSUE: this is not a fixable file target. Claude Code creates these directories internally. The fix is in the cleanup script's scanning logic, not in Claude Code itself. This target should be rewritten as the filesystem scan pattern.

Repo Placement

MISMATCH. Issue is filed on forgejo_admin/pal-e-platform but all fixable code lives in forgejo_admin/claude-custom (hooks/cleanup-worktrees.sh, hooks/forgejo-helper.sh). The pal-e-platform repo contains no worktree management code. The fix PR must target claude-custom. The pal-e-platform issue should either be moved to the claude-custom repo or a new issue created there with a cross-reference.

Dependencies

  • [x] claude-custom#194 (post-merge worktree cleanup) — merged, satisfied
  • [x] claude-custom#195 (cleanup-worktrees.sh repo list) — merged, satisfied
  • [x] claude-custom#184 (worktree isolation enforcement) — merged, satisfied
No unresolved dependencies. No blocking items on the board — #637 is the only worktree-related item.

Acceptance Criteria

  • AC1: "All 31 stale worktrees cleaned up" — Count is wrong. Verified state: 64 directories on disk in pal-e-platform (37 orphans + 27 git-tracked), plus 2 orphans in basketball-api, 1 in pal-e-docs, 1 in pal-e-app. Total ~70 stale dirs, ~1.8GB disk. Should read "All stale worktree directories cleaned up across all repos."
  • AC2: "Root cause identified" — Testable. Root cause found during this review: cleanup-worktrees.sh only iterates git worktree list --porcelain entries. When git loses worktree registration (but the directory remains), the script is blind to those orphans. 37 of 64 pal-e-platform directories are invisible to the current approach.
  • AC3: "Fix applied so future agent worktrees are cleaned up" — Testable but underspecified. The fix must add a filesystem scan of .claude/worktrees/agent-* and /tmp/{repo}-* patterns in addition to the git-tracked worktree scan.

Blast Radius

  • pal-e-platform: 64 dirs on disk (27 git-tracked, 37 orphans). 1.2GB wasted.
  • basketball-api: 5 dirs in /tmp (3 git-tracked, 2 orphans). ~201MB wasted.
  • pal-e-docs: 1 orphan (/tmp/pal-e-api-199). 175MB wasted.
  • pal-e-app: 1 orphan (/tmp/pal-e-docs-app-94). 224MB wasted.
  • Other repos (claude-custom, westside-app, pal-e-services, etc.): clean.
  • Total: ~1.8GB disk waste. No risk of data loss — all worktree branches for merged PRs are safe to remove. Rollback is trivial (worktrees can be recreated).

Decomposition Assessment

Apply the three-thing limit and five-minute rule:
  • 2 file targets in 1 repo (claude-custom): hooks/cleanup-worktrees.sh and possibly hooks/forgejo-helper.sh
  • 3 acceptance criteria — within limit
  • Estimated agent time: under 5 minutes
  • No independent subtasks that need parallelization
No decomposition needed. The immediate cleanup (AC1) is a one-time manual operation; the script fix (AC2+AC3) is a single focused change.

Recommendation

  • [BODY] Fix repo placement: change "Primary cleanup target: forgejo_admin/pal-e-platform" to "Fix target: forgejo_admin/claude-custom (hooks/cleanup-worktrees.sh). pal-e-platform is the worst-affected repo but contains no fixable code."
  • [BODY] Fix worktree count: "31 stale worktrees" is outdated. Actual: 64 dirs in pal-e-platform alone (37 orphans + 27 git-tracked), ~70 total across repos, ~1.8GB disk waste.
  • [BODY] Add root cause to What Broke: cleanup-worktrees.sh only iterates git worktree list --porcelain. Orphaned directories (git lost registration, directory remains) are invisible. Script needs filesystem scan of .claude/worktrees/agent-* and /tmp/{repo}-* patterns.
  • [BODY] Fix AC1: "All 31 stale worktrees cleaned up" should be "All stale worktree directories cleaned up across all repos."
  • [BODY] Clarify file target: replace "Claude Code's built-in worktree management" with hooks/forgejo-helper.sh (remove_worktree_for_branch function).