beads/FIX_SUMMARY.md

# Fix Summary: GH#1224 - Stack Overflow in bd on WSL2 with SQLite WAL Locking Error

## Issue Description
The `bd` CLI tool crashed with a stack overflow error when running on WSL2 with a repository located on a Docker Desktop bind mount (`/mnt/wsl/docker-desktop-bind-mounts/...`). The crash occurred due to:

1. **SQLite WAL Mode Incompatibility**: WAL mode fails with "sqlite3: locking protocol" error on network filesystems like Docker Desktop bind mounts
2. **Infinite Recursion**: When WAL mode failed, the daemon's `acquireStartLock` function could theoretically enter infinite recursion

## Root Cause Analysis

### Primary Issue: WAL Mode on Network Filesystems
SQLite's Write-Ahead Logging (WAL) mode requires specific filesystem semantics (especially shared memory locking) that are not available on network filesystems. The existing code detected WSL2 Windows paths (`/mnt/[a-zA-Z]/`) but did not detect Docker Desktop bind mounts (`/mnt/wsl/*`), which are also network filesystems with the same limitations.

### Secondary Issue: Bounded Recursion
The current code in `acquireStartLock` (line 267 of daemon_autostart.go) already has proper bounds checking with `maxRetries = 3`, preventing infinite recursion. This fix was already in place.

## Solution

### 1. Enhanced Path Detection (internal/storage/sqlite/store.go)
- Added `wslNetworkPathPattern` regex to detect `/mnt/wsl/*` paths (Docker Desktop bind mounts)
- Expanded `isWSL2WindowsPath()` function to check for both:
  - Windows filesystem mounts: `/mnt/[a-zA-Z]/` 
  - Network filesystem mounts: `/mnt/wsl/*`
- Optimized logic to check WSL2 environment once (cheaper /proc/version check) before path matching

### 2. Added Comprehensive Tests
Created `internal/storage/sqlite/store_wsl_test.go` with tests for:
- Windows filesystem detection (`/mnt/c/`, `/mnt/d/`, etc.)
- Docker Desktop bind mount detection (`/mnt/wsl/docker-desktop-bind-mounts/`)
- Native WSL2 filesystem paths (allow WAL mode)
- Edge cases and path pattern matching
- Journal mode selection logic

### 3. Integration Test
Created `test_issue_gh1224.sh` to verify:
- Database creation on native WSL2 filesystem
- Proper handling of Windows paths (when available)
- Proper handling of Docker bind mount paths (when available)

## Changes Made

### Modified Files
1. **internal/storage/sqlite/store.go**
   - Added `wslNetworkPathPattern` regex variable
   - Updated `isWSL2WindowsPath()` function
   - Updated documentation with GH#1224 reference

### New Files
1. **internal/storage/sqlite/store_wsl_test.go**
   - Unit tests for WSL2 path detection
   - Tests for journal mode selection
   - Edge case tests

2. **test_issue_gh1224.sh**
   - Integration test script for manual verification

3. **test_wsl2_wal.sh**
   - Diagnostic script for WAL mode testing (requires sqlite3 CLI)

## Verification

### Test Results
- All existing tests pass (13.2s runtime for cmd/bd tests)
- New WSL2 detection tests pass (3/3)
- Docker bind mount detection tests pass
- Journal mode selection tests pass
- Daemon autostart tests confirm bounded recursion (maxRetries=3)

### Build Status
- Successfully builds: `go build ./cmd/bd`
- No syntax errors or regressions

## How the Fix Works

### Before
```
User on WSL2 with Docker bind mount (/mnt/wsl/docker-desktop-bind-mounts/...)
  ↓
bd init / bd ready / bd sync
  ↓
Database initialization (sqlite/store.go:NewWithTimeout)
  ↓
isWSL2WindowsPath() → false (only checked /mnt/[a-zA-Z]/)
  ↓
WAL mode enabled (PRAGMA journal_mode=WAL)
  ↓
Database connection fails: "sqlite3: locking protocol"
  ↓
Daemon retry loop (eventually bounded by maxRetries)
  ↓
Stack overflow / Timeout (user sees warning)
```

### After
```
User on WSL2 with Docker bind mount (/mnt/wsl/docker-desktop-bind-mounts/...)
  ↓
bd init / bd ready / bd sync
  ↓
Database initialization (sqlite/store.go:NewWithTimeout)
  ↓
isWSL2WindowsPath() → true (detects /mnt/wsl/ pattern)
  ↓
WAL mode disabled (PRAGMA journal_mode=DELETE)
  ↓
Database connection succeeds
  ↓
Command executes normally
```

## References
- GH#1224: Stack Overflow in bd on WSL2 with SQLite WAL Locking Error
- GH#920: SQLite WAL mode on Windows filesystem mounts in WSL2
- SQLite WAL Limitations: https://www.sqlite.org/wal.html#nfs

## Testing Recommendations for Review
1. Run tests locally in WSL2: `go test -v ./internal/storage/sqlite -run TestIsWSL2WindowsPath`
2. Test database creation in different paths:
   - Native WSL2: `/home/user/project/.beads/`
   - Windows: `/mnt/c/Users/.beads/` (if available)
   - Docker bind mount: `/mnt/wsl/docker-desktop-bind-mounts/.../` (if available)
3. Verify daemon starts without stack overflow or excessive retries