cleanup stale work trees

[mickume]

During a coding session, there might be multiple active worktrees. If the user interrupts the session (Ctrl-C), these work trees become stale and must be cleaned up manually.

Think of a way to clean them up on interrupt, regardless if they contain uncommitted or unmerged changes. The user decided to interrupt, ie it is OK to loose these changes.

[mickume]

Analysis

Auto-generated by af-fix. Reviewing issue context and codebase.

Diagnosis

Classification: enhancement

Root Cause / Problem:
When the user interrupts a running session (Ctrl-C, SIGKILL, etc.), worktree directories under .agent-fox/worktrees/ may persist on disk. The per-session cleanup in session_lifecycle.py uses asyncio.shield() to protect destroy_worktree(), but a double-SIGINT (SystemExit(1)) or process kill can bypass this cleanup entirely.

The existing run_preflight_workspace_check() in workspace/health.py runs git worktree prune at startup, but this only cleans git's internal worktree registry entries for directories that no longer exist — it does NOT remove actual stale worktree directories still on disk.

Planned Fix

Approach:
Add a cleanup_stale_worktrees() function to workspace/health.py that:

1. Parses git worktree list --porcelain to identify worktrees under .agent-fox/worktrees/
2. Removes each via git worktree remove --force (falling back to shutil.rmtree)
3. Removes any remaining orphan directories under .agent-fox/worktrees/
4. Runs git worktree prune to clean the registry

This function is called from run_preflight_workspace_check() at orchestrator startup, before any sessions are dispatched. At startup there are no active sessions, so ALL worktrees under .agent-fox/worktrees/ are stale from a prior interrupted run and can be safely removed.

Files to modify:

• packages/agentfox/agentfox/workspace/health.py — Add cleanup_stale_worktrees() and wire into preflight
• packages/agentfox/tests/unit/workspace/test_run_preflight.py — Add tests for stale worktree cleanup

---

Analysis by af-fix. Implementation follows.

[mickume]

Fix Implemented

Auto-generated by af-fix.

Summary

Added cleanup_stale_worktrees() to workspace/health.py that removes all worktree directories under .agent-fox/worktrees/ at orchestrator startup. Since no sessions are active at startup, all directories under the worktrees root are stale from a prior interrupted run. The function uses git worktree remove --force with shutil.rmtree fallback, cleans up empty parent directories, and prunes the git registry. It's wired into run_preflight_workspace_check() so it runs automatically before every orchestrator run.

Changes

File	Change
packages/agentfox/agentfox/workspace/health.py	Added cleanup_stale_worktrees() function, _walk_leaf_dirs() helper, stale_worktrees_removed field on WorkspacePreflightResult, wired into preflight
packages/agentfox/agentfox/engine/engine.py	Added stale_worktrees_removed to preflight audit event payload
packages/agentfox/tests/unit/workspace/test_run_preflight.py	Added 8 tests covering no-op, removal, fallback, empty dir cleanup, error resilience, 4-level paths, and preflight integration

Tests

• test_run_preflight.py::TestCleanupStaleWorktrees: 8 tests covering all paths
• All 283 workspace/preflight tests pass

Verification

• All existing tests pass: ✅
• New tests pass: ✅
• Linter / formatter: ✅
• No regressions: ✅

Branch

feature/issue-629-cleanup-stale-worktrees — ready to merge into main.

---

Fix by af-fix. Ready for review.