Summary

This PR implements comprehensive stale Git lock file detection and handling to address Issue #175, which describes how Claude Code's background Git operations can leave stale lock files that interfere with auto-worktree operations.

Changes

New Files

• internal/git/lockfile.go - Lock file detection, process verification, and management utilities
• internal/git/lockfile_test.go - Comprehensive test suite (8 test suites, all passing)

Modified Files

• internal/git/executor.go - Added retry logic with lock file detection for all Git operations
• internal/cmd/commands.go - New RunDoctor command and startup lock detection
• cmd/auto-worktree/main.go - CLI integration for doctor command
• README.md - Added troubleshooting section with lock file documentation

Features

1. Lock File Detection

• Process-based stale detection (checks if owning process exists via PID)
• Handles both main repo and worktree-specific lock files
• Supports .git files (worktree pointers) and directories

2. Automatic Retry Logic

• Git operations retry up to 3 times when encountering lock file errors
• 1-second delay between retries
• Displays warnings with detailed lock file information
• Non-lock errors fail immediately without retries

3. Doctor Command

auto-worktree doctor --check-locks                    # Detect and report
auto-worktree doctor --check-locks --remove-locks     # Detect and remove

• Distinguishes between active and stale locks
• Safe removal (refuses to remove locks from running processes)
• Clear, actionable output

4. Startup Integration

• Detects stale locks during initialization
• Warns users before attempting operations
• Non-blocking (doesn't prevent operations from continuing)

Implementation Details

Conservative Approach

• Warn-only by default: Never auto-removes locks without explicit user action
• Process verification: Only considers locks stale if owning process doesn't exist
• Safe operations: Refuses to remove active locks

Error Detection Pattern

Identifies lock file errors by checking for:

• "index.lock" in error message
• ".lock" extension
• "unable to create" messages
• "file exists" in .git directory

Test Coverage

• ✅ Lock file error detection
• ✅ Stale lock identification
• ✅ Safe lock removal
• ✅ Process verification
• ✅ Warning message formatting
• ✅ Edge cases (non-existent files, invalid repos, etc.)

Testing

All validation passed:

✅ All Go tests passing (100% success rate)
✅ Build successful
✅ go vet clean
✅ gofmt compliant

Documentation

Added comprehensive troubleshooting section to README.md covering:

• Symptoms of lock file issues
• Solutions (doctor command, automatic detection, manual cleanup)
• Prevention and best practices
• Integration with AI agents

Usage Examples

Check for stale locks:

$ auto-worktree doctor --check-locks
Running repository diagnostics...

🔍 Checking for Git lock files...

⚠️  Found 1 stale lock file(s):
  • /path/.git/index.lock (age: 5m, pid: 12345, stale)

These lock files may be preventing Git operations.
To remove them, run: auto-worktree doctor --check-locks --remove-locks

✓ Diagnostics complete

Remove stale locks:

$ auto-worktree doctor --check-locks --remove-locks
Running repository diagnostics...

🔍 Checking for Git lock files...

⚠️  Found 1 stale lock file(s):
  • /path/.git/index.lock (age: 5m, pid: 12345, stale)

Removing stale lock files...
  ✓ Removed /path/.git/index.lock

✓ Removed 1 stale lock file(s)

✓ Diagnostics complete

Related Issues

• Closes Bug: Claude Code stale lock files interfere with auto-worktree operations #175
• Related to Claude Code issue [BUG] Stale .git/index.lock files created by CC's background git operations block user git commands anthropics/claude-code#11005

Test Plan

• Unit tests for all lock file functionality
• Integration with existing Git operations
• Manual testing with simulated stale locks
• Verification of process-based detection
• Doctor command with both flags
• Startup warning display

🤖 Generated with Claude Code