Description

The root cause of worktree disappearance, failed git operations, and terminal crashes appears to be git corruption from concurrent access patterns in local-only multi-agent workflows.

Root Cause Analysis

Concurrent Access Patterns

1. Multiple agents committing simultaneously - Race conditions in object database
2. Rebase while other worktrees active - Ref updates conflict with checked out branches
3. Shared git objects - All worktrees share .git/objects leading to write conflicts
4. Index operations - Concurrent index updates can corrupt state
5. Garbage collection - GC running during active operations causes issues

Related Known Issues

• git rebase --update-refs doesn't work with checked out worktrees (https://www.brandonpugh.com/til/git/update-refs-working-directory/)
• Unity engine corruption from branch switching (https://discussions.unity.com/t/huge-issue-switching-git-branches-corrupting-assets-have-to-reimport-all-tofix/799368)
• Stack Overflow worktree cleanup issues (https://stackoverflow.com/questions/44109234/how-to-delete-a-git-working-tree-branch-when-its-working-directory-has-been-remo)

Current Symptoms

1. Worktree directories disappear entirely
2. Git operations fail in seemingly valid worktrees
3. Terminal crashes without warning
4. Stale lock files persist
5. Corrupted refs or index

Proposed Solutions

Detection

• Monitor for concurrent git operations
• Detect stale lock files
• Validate worktree integrity periodically
• Log git operation sequences for debugging
• Alert on suspicious patterns (multiple rebases, concurrent writes)

Prevention

• Serialize critical operations (rebase, gc, ref updates)
• Implement application-level locking
• Queue operations instead of concurrent execution
• Disable automatic gc during agent operations
• Coordinate between worktrees before ref updates

Recovery

• Automatic lock file cleanup
• Worktree repair command
• Backup/restore mechanism for refs
• Clear recovery documentation
• Rollback capabilities for failed operations

Technical Details

Files/Areas Affected

• .git/objects/ - Shared object database
• .git/refs/ - Branch references
• .git/index - Worktree-specific but conflicts possible
• .git/worktrees/ - Worktree metadata
• .git/*.lock - Lock files for various operations

Concurrent Operations to Handle

• Commit + Commit
• Rebase + Commit
• Rebase + Rebase
• GC + Any operation
• Worktree add/remove + Other operations

Testing Needed

• Stress test with multiple concurrent agents
• Simulate race conditions
• Test rebase with active worktrees
• Validate lock file handling
• Test recovery mechanisms

Related Context

• Git worktrees + Claude Code guide: https://alirezarezvani.medium.com/git-worktrees-claude-code-parallel-ai-development-guide-dd90a2a1107f
• Parallel workflows blog: https://blog.itdepends.be/parallel-workflows-git-worktrees-agents/
• Hacker News discussion: https://news.ycombinator.com/item?id=46192929