Bug: 31 stale agent worktrees accumulating across repos

forgejo_admin commented

2026-03-28 23:18:22 +00:00

Contributor

Type

Bug

Lineage

Board: board-pal-e-platform
Story: story:superuser-deploy
Arch: arch:worktree
Discovered during session 2026-03-28

Repo

Fix target: forgejo_admin/claude-custom (hooks/cleanup-worktrees.sh). pal-e-platform is the worst-affected repo but contains no fixable code.

What Broke

Agent worktrees are not being cleaned up after agent completion. ~70 stale worktree directories found across 4 repos (~1.8GB disk waste):

Repo	Stale Dirs	Location	Breakdown
pal-e-platform	64	`~/.claude/worktrees/agent-*`	37 orphans + 27 git-tracked
basketball-api	2	`/tmp/basketball-api-*`	orphans
pal-e-docs (pal-e-api)	1	`/tmp/pal-e-api-199`	git-tracked
pal-e-app (pal-e-docs-app)	1	`/tmp/pal-e-docs-app-94`	git-tracked

Root cause: cleanup-worktrees.sh only iterates git worktree list --porcelain. Orphaned directories (git lost registration, directory remains on disk) are invisible to the script. 37 of 64 pal-e-platform directories are orphans — the cleanup script never sees them. Script needs filesystem scan of .claude/worktrees/agent-* and /tmp/{repo}-* patterns in addition to git-tracked worktrees.

Repro Steps

ls ~/.claude/worktrees/ | wc -l — shows 64+ directories
git -C ~/pal-e-platform worktree list | wc -l — shows only 27 (git-tracked)
Difference = 37 orphaned directories invisible to cleanup

Expected Behavior

Post-merge cleanup hook should remove both git-tracked worktrees AND orphaned directories for merged branches.

Environment

All repos on archbox
Worktree paths: ~/.claude/worktrees/agent-* (Claude Code managed) and /tmp/* (agent-created)
Related: PR #194 (post-merge worktree cleanup) and PR #195 (cleanup-worktrees.sh repo list) were merged but only scan git-tracked worktrees

File Targets

hooks/cleanup-worktrees.sh — add filesystem scan for orphaned directories alongside git worktree list
hooks/forgejo-helper.sh — remove_worktree_for_branch function (may need orphan-aware cleanup)

Acceptance Criteria

All stale worktree directories cleaned up across all repos
Root cause fixed (orphaned dirs detected and removed)
Fix applied so future agent worktrees are cleaned up on merge or session end

Constraints

Do NOT delete worktrees for branches with unmerged changes
Verify each branch is merged before removing its worktree
Orphaned dirs (no git tracking) need heuristic: check if branch exists, if merged, age of directory

Checklist

Add filesystem scan to cleanup-worktrees.sh
Handle orphaned directories (no git worktree registration)
Test with real orphaned dirs
Create PR on claude-custom

claude-custom#194 — post-merge worktree cleanup (merged but insufficient)
claude-custom#195 — cleanup-worktrees.sh repo list fix (merged)
claude-custom#184 — worktree isolation enforcement gaps (merged)

### Type Bug ### Lineage - Board: board-pal-e-platform - Story: story:superuser-deploy - Arch: arch:worktree - Discovered during session 2026-03-28 ### Repo Fix target: `forgejo_admin/claude-custom` (`hooks/cleanup-worktrees.sh`). pal-e-platform is the worst-affected repo but contains no fixable code. ### What Broke Agent worktrees are not being cleaned up after agent completion. ~70 stale worktree directories found across 4 repos (~1.8GB disk waste): | Repo | Stale Dirs | Location | Breakdown | |------|-----------|----------|-----------| | pal-e-platform | 64 | `~/.claude/worktrees/agent-*` | 37 orphans + 27 git-tracked | | basketball-api | 2 | `/tmp/basketball-api-*` | orphans | | pal-e-docs (pal-e-api) | 1 | `/tmp/pal-e-api-199` | git-tracked | | pal-e-app (pal-e-docs-app) | 1 | `/tmp/pal-e-docs-app-94` | git-tracked | **Root cause:** `cleanup-worktrees.sh` only iterates `git worktree list --porcelain`. Orphaned directories (git lost registration, directory remains on disk) are invisible to the script. 37 of 64 pal-e-platform directories are orphans — the cleanup script never sees them. Script needs filesystem scan of `.claude/worktrees/agent-*` and `/tmp/{repo}-*` patterns in addition to git-tracked worktrees. ### Repro Steps 1. `ls ~/.claude/worktrees/ | wc -l` — shows 64+ directories 2. `git -C ~/pal-e-platform worktree list | wc -l` — shows only 27 (git-tracked) 3. Difference = 37 orphaned directories invisible to cleanup ### Expected Behavior Post-merge cleanup hook should remove both git-tracked worktrees AND orphaned directories for merged branches. ### Environment - All repos on archbox - Worktree paths: `~/.claude/worktrees/agent-*` (Claude Code managed) and `/tmp/*` (agent-created) - Related: PR #194 (post-merge worktree cleanup) and PR #195 (cleanup-worktrees.sh repo list) were merged but only scan git-tracked worktrees ### File Targets - `hooks/cleanup-worktrees.sh` — add filesystem scan for orphaned directories alongside git worktree list - `hooks/forgejo-helper.sh` — `remove_worktree_for_branch` function (may need orphan-aware cleanup) ### Acceptance Criteria - [ ] All stale worktree directories cleaned up across all repos - [ ] Root cause fixed (orphaned dirs detected and removed) - [ ] Fix applied so future agent worktrees are cleaned up on merge or session end ### Constraints - Do NOT delete worktrees for branches with unmerged changes - Verify each branch is merged before removing its worktree - Orphaned dirs (no git tracking) need heuristic: check if branch exists, if merged, age of directory ### Checklist - [ ] Add filesystem scan to cleanup-worktrees.sh - [ ] Handle orphaned directories (no git worktree registration) - [ ] Test with real orphaned dirs - [ ] Create PR on claude-custom ### Related - claude-custom#194 — post-merge worktree cleanup (merged but insufficient) - claude-custom#195 — cleanup-worktrees.sh repo list fix (merged) - claude-custom#184 — worktree isolation enforcement gaps (merged)

forgejo_admin commented

2026-03-28 23:30:58 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-637-2026-03-28

Root cause identified during review: cleanup-worktrees.sh only iterates git worktree list --porcelain — orphaned directories (git lost registration, dir remains on disk) are invisible. 37 of 64 pal-e-platform worktree dirs are orphans.

Issues found:

Repo mismatch: Issue filed on pal-e-platform but all fixable code is in claude-custom (hooks/cleanup-worktrees.sh, hooks/forgejo-helper.sh)
Stale count: "31 worktrees" is outdated — actual: 64 dirs in pal-e-platform (37 orphans + 27 git-tracked), ~70 total across repos, ~1.8GB disk
AC1 underspecified: Should say "all stale worktree directories" not "31"
AC3 underspecified: Fix must add filesystem scan of .claude/worktrees/agent-* and /tmp/{repo}-* patterns
File target vague: "Claude Code's built-in worktree management" is not a fixable target — should be hooks/forgejo-helper.sh

## Scope Review: NEEDS_REFINEMENT Review note: `review-637-2026-03-28` Root cause identified during review: `cleanup-worktrees.sh` only iterates `git worktree list --porcelain` — orphaned directories (git lost registration, dir remains on disk) are invisible. 37 of 64 pal-e-platform worktree dirs are orphans. Issues found: - **Repo mismatch**: Issue filed on pal-e-platform but all fixable code is in `claude-custom` (`hooks/cleanup-worktrees.sh`, `hooks/forgejo-helper.sh`) - **Stale count**: "31 worktrees" is outdated — actual: 64 dirs in pal-e-platform (37 orphans + 27 git-tracked), ~70 total across repos, ~1.8GB disk - **AC1 underspecified**: Should say "all stale worktree directories" not "31" - **AC3 underspecified**: Fix must add filesystem scan of `.claude/worktrees/agent-*` and `/tmp/{repo}-*` patterns - **File target vague**: "Claude Code's built-in worktree management" is not a fixable target — should be `hooks/forgejo-helper.sh`

forgejo_admin commented

2026-03-28 23:31:44 +00:00

Author

Contributor

Scope Refinement Applied (review-637-2026-03-28)

5 body changes per review recommendations:

Repo placement: pal-e-platform → claude-custom (fix target is hooks/cleanup-worktrees.sh)
Count: 31 → ~70 dirs (~1.8GB), 37 orphans + 27 tracked in pal-e-platform alone
Root cause added: cleanup script only iterates git-tracked worktrees, orphans invisible
AC1 fixed: "All 31" → "All stale worktree directories across all repos"
File target clarified: Added forgejo-helper.sh remove_worktree_for_branch function

Re-running scope review.

## Scope Refinement Applied (review-637-2026-03-28) 5 body changes per review recommendations: 1. **Repo placement**: pal-e-platform → claude-custom (fix target is hooks/cleanup-worktrees.sh) 2. **Count**: 31 → ~70 dirs (~1.8GB), 37 orphans + 27 tracked in pal-e-platform alone 3. **Root cause added**: cleanup script only iterates git-tracked worktrees, orphans invisible 4. **AC1 fixed**: "All 31" → "All stale worktree directories across all repos" 5. **File target clarified**: Added forgejo-helper.sh remove_worktree_for_branch function Re-running scope review.

forgejo_admin commented

2026-03-29 03:17:48 +00:00

Author

Contributor

Scope Review: APPROVED

Review note: review-637-2026-03-28-v2
Re-review after refinement. All 5 BODY fixes from the previous review have been applied correctly. Template complete, traceability intact, file targets verified against codebase, acceptance criteria testable. Ready for dispatch.

## Scope Review: APPROVED Review note: `review-637-2026-03-28-v2` Re-review after refinement. All 5 BODY fixes from the previous review have been applied correctly. Template complete, traceability intact, file targets verified against codebase, acceptance criteria testable. Ready for dispatch.