feat: Complete GH #353 follow-up phases (bd-9nw, bd-u3t, bd-e0o)
Implements all three follow-up phases for sandbox environment support: **Phase 1 (bd-9nw): Documentation** ✅ - Comprehensive sandbox troubleshooting section in TROUBLESHOOTING.md - Detailed symptoms, root causes, and escape hatches - Step-by-step troubleshooting workflow - Comparison table for --sandbox, --force, and --allow-stale flags - Global flags section added to CLI_REFERENCE.md - Documents --sandbox, --allow-stale, and --force flags - Usage examples and when to use each flag - GitHub issue #353 comment with immediate workarounds **Phase 2 (bd-u3t): Sandbox Auto-Detection** ✅ - Automatic sandbox detection using syscall.Kill permission checks - cmd/bd/sandbox_unix.go: Unix/Linux/macOS implementation - cmd/bd/sandbox_windows.go: Windows stub (conservative approach) - cmd/bd/sandbox_test.go: Comprehensive test coverage - Auto-enables sandbox mode when detected - Shows: "ℹ️ Sandbox detected, using direct mode" - Respects explicit --sandbox or --no-daemon flags - Updated documentation to reflect auto-detection (v0.21.1+) **Phase 3 (bd-e0o): Enhanced Daemon Robustness** ✅ - Permission-aware process checks in cmd/bd/daemon_unix.go - Correctly handles EPERM (operation not permitted) from syscall.Kill - Treats EPERM as "process exists but not signable" = running - Prevents false negatives in sandboxed environments - Metadata health check in cmd/bd/daemon_event_loop.go - Periodic verification that metadata is accessible - Helps detect external import operations (bd import --force) - Non-fatal logging for diagnostics - Comprehensive test suite in cmd/bd/daemon_unix_test.go - Self-check, init process, nonexistent process, parent process tests **Impact:** - Codex users: No manual intervention needed, auto-detected - Stuck states: Three escape hatches (--sandbox, --force, --allow-stale) - Daemon robustness: Handles permission-restricted environments gracefully - All three follow-up issues (bd-9nw, bd-u3t, bd-e0o) closed **Files changed:** - cmd/bd/main.go: Auto-detection logic in PersistentPreRun - cmd/bd/sandbox_unix.go: Unix sandbox detection (new) - cmd/bd/sandbox_windows.go: Windows sandbox detection stub (new) - cmd/bd/sandbox_test.go: Sandbox detection tests (new) - cmd/bd/daemon_unix.go: Permission-aware isProcessRunning() - cmd/bd/daemon_unix_test.go: Process check tests (new) - cmd/bd/daemon_event_loop.go: Metadata health check - docs/TROUBLESHOOTING.md: Comprehensive sandbox section - docs/CLI_REFERENCE.md: Global flags documentation Closes bd-9nw, bd-u3t, bd-e0o Related: GH #353 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -203,6 +203,83 @@ bd list --priority-min 2 --json # P2 and below
|
||||
bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
|
||||
```
|
||||
|
||||
## Global Flags
|
||||
|
||||
Global flags work with any bd command and must appear **before** the subcommand.
|
||||
|
||||
### Sandbox Mode
|
||||
|
||||
**Auto-detection (v0.21.1+):** bd automatically detects sandboxed environments and enables sandbox mode.
|
||||
|
||||
When detected, you'll see: `ℹ️ Sandbox detected, using direct mode`
|
||||
|
||||
**Manual override:**
|
||||
|
||||
```bash
|
||||
# Explicitly enable sandbox mode
|
||||
bd --sandbox <command>
|
||||
|
||||
# Equivalent to combining these flags:
|
||||
bd --no-daemon --no-auto-flush --no-auto-import <command>
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Disables daemon (uses direct SQLite mode)
|
||||
- Disables auto-export to JSONL
|
||||
- Disables auto-import from JSONL
|
||||
|
||||
**When to use:** Sandboxed environments where daemon can't be controlled (permission restrictions), or when auto-detection doesn't trigger.
|
||||
|
||||
### Staleness Control
|
||||
|
||||
```bash
|
||||
# Skip staleness check (emergency escape hatch)
|
||||
bd --allow-stale <command>
|
||||
|
||||
# Example: access database even if out of sync with JSONL
|
||||
bd --allow-stale ready --json
|
||||
bd --allow-stale list --status open --json
|
||||
```
|
||||
|
||||
**Shows:** `⚠️ Staleness check skipped (--allow-stale), data may be out of sync`
|
||||
|
||||
**⚠️ Caution:** May show stale or incomplete data. Use only when stuck and other options fail.
|
||||
|
||||
### Force Import
|
||||
|
||||
```bash
|
||||
# Force metadata update even when DB appears synced
|
||||
bd import --force -i .beads/beads.jsonl
|
||||
```
|
||||
|
||||
**When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.
|
||||
|
||||
**Shows:** `Metadata updated (database already in sync with JSONL)`
|
||||
|
||||
### Other Global Flags
|
||||
|
||||
```bash
|
||||
# JSON output for programmatic use
|
||||
bd --json <command>
|
||||
|
||||
# Force direct mode (bypass daemon)
|
||||
bd --no-daemon <command>
|
||||
|
||||
# Disable auto-sync
|
||||
bd --no-auto-flush <command> # Disable auto-export to JSONL
|
||||
bd --no-auto-import <command> # Disable auto-import from JSONL
|
||||
|
||||
# Custom database path
|
||||
bd --db /path/to/.beads/beads.db <command>
|
||||
|
||||
# Custom actor for audit trail
|
||||
bd --actor alice <command>
|
||||
```
|
||||
|
||||
**See also:**
|
||||
- [TROUBLESHOOTING.md - Sandboxed environments](TROUBLESHOOTING.md#sandboxed-environments-codex-claude-code-etc) for detailed sandbox troubleshooting
|
||||
- [DAEMON.md](DAEMON.md) for daemon mode details
|
||||
|
||||
## Advanced Operations
|
||||
|
||||
### Cleanup
|
||||
|
||||
Reference in New Issue
Block a user