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:
29
AGENTS.md
29
AGENTS.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user