Implement exclusive lock protocol for daemon/external tool coexistence

- Add ExclusiveLock struct with JSON marshaling and validation
- Implement IsProcessAlive() with EPERM fail-safe behavior
- Add ShouldSkipDatabase() with stale lock cleanup
- Integrate lock checking into daemon sync cycle
- Return holder name on stale removal for better logging
- Case-insensitive hostname comparison
- Comprehensive unit tests (89.3% coverage)
- Documentation updates (ADVANCED.md, AGENTS.md)
- Add .beads/.exclusive-lock to .gitignore

Closes bd-115, bd-116, bd-117, bd-118, bd-119, bd-120, bd-121, bd-122

Amp-Thread-ID: https://ampcode.com/threads/T-0b835739-0d79-4ef9-aa62-8446a368c42d
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-10-25 23:32:02 -07:00
parent e42868c8e5
commit 3a42ca252d
10 changed files with 620 additions and 0 deletions

View File

@@ -474,6 +474,35 @@ We're working toward 1.0. Key blockers tracked in bd. Run:
bd dep tree bd-8 # Show 1.0 epic dependencies
```
## Exclusive Lock Protocol (Advanced)
**For external tools that need full database control** (e.g., CI/CD, deterministic execution systems):
The bd daemon respects exclusive locks via `.beads/.exclusive-lock` file. When this lock exists:
- Daemon skips all operations for the locked database
- External tool has complete control over git sync and database operations
- Stale locks (dead process) are automatically cleaned up
**Use case:** Tools like VibeCoder that need deterministic execution without daemon interference.
See [EXCLUSIVE_LOCK.md](EXCLUSIVE_LOCK.md) for:
- Lock file format (JSON schema)
- Creating and releasing locks (Go/shell examples)
- Stale lock detection behavior
- Integration testing guidance
**Quick example:**
```bash
# Create lock
echo '{"holder":"my-tool","pid":'$$',"hostname":"'$(hostname)'","started_at":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","version":"1.0.0"}' > .beads/.exclusive-lock
# Do work...
bd create "My issue" -p 1
# Release lock
rm .beads/.exclusive-lock
```
## Common Tasks
### Adding a New Command