beads/docs
Steve Yegge 58fe00057c 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>
2025-11-21 19:32:45 -05:00
..
adr feat(agent-mail): Add Python adapter library for Agent Mail integration 2025-11-08 00:15:07 -08:00
ADAPTIVE_IDS.md Implement adaptive ID length scaling (bd-ea2a13) 2025-10-30 21:40:52 -07:00
ADVANCED.md Fix #264 and #262: Remove stale --resolve-collisions references 2025-11-08 13:18:50 -08:00
AGENT_MAIL.md docs: Add comprehensive Agent Mail integration guide 2025-11-08 00:49:41 -08:00
AGENT_MAIL_DEPLOYMENT.md Add Agent Mail multi-workspace deployment guide and scripts 2025-11-08 04:16:44 -08:00
AGENT_MAIL_MULTI_WORKSPACE_SETUP.md Add Agent Mail multi-workspace deployment guide and scripts 2025-11-08 04:16:44 -08:00
AGENT_MAIL_QUICKSTART.md Complete Agent Mail documentation (bd-nl8z) 2025-11-08 02:36:27 -08:00
ARCHITECTURE.md Fix race condition in auto-flush mechanism (issue bd-52) 2025-11-20 21:24:31 -05:00
ATTRIBUTION.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
CLAUDE.md Fix #264 and #262: Remove stale --resolve-collisions references 2025-11-08 13:18:50 -08:00
CLI_REFERENCE.md feat: Complete GH #353 follow-up phases (bd-9nw, bd-u3t, bd-e0o) 2025-11-21 19:32:45 -05:00
COLLISION_MATH.md Remove obsolete collision remapping code and tests 2025-10-31 00:19:42 -07:00
CONFIG.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
DAEMON.md Refactor AGENTS.md: extract supplemental docs 2025-11-08 01:03:28 -08:00
EXCLUSIVE_LOCK.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
EXTENDING.md Fix SQLite driver name mismatch causing "unknown driver" errors (#252) 2025-11-07 14:19:14 -08:00
FAQ.md Fix #264 and #262: Remove stale --resolve-collisions references 2025-11-08 13:18:50 -08:00
GIT_INTEGRATION.md Document files created by bd init and clarify .gitattributes should be committed 2025-11-20 21:29:20 -05:00
INSTALLING.md Add uv prerequisite to Claude Code plugin documentation (#293) 2025-11-12 10:49:38 -08:00
LABELS.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
LINTING.md Document -short flag, update linting baseline, clarify bd edit MCP exclusion 2025-11-06 19:42:01 -08:00
MULTI_REPO_AGENTS.md Add multi-repo patterns documentation for AI agents (bd-4b6u) 2025-11-06 19:53:29 -08:00
MULTI_REPO_HYDRATION.md Extract SQLite migrations into separate files (bd-fb95094c.7) 2025-11-06 20:06:45 -08:00
MULTI_REPO_MIGRATION.md feat: Add bd init --contributor and --team wizards 2025-11-05 19:04:14 -08:00
PLUGIN.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
PROTECTED_BRANCHES.md Document which files to commit after bd init --branch 2025-11-20 21:47:50 -05:00
QUICKSTART.md Fix #349: Improve compact error messages, remove bogus merge suggestion, add daemon/maintenance docs 2025-11-20 20:58:57 -05:00
README_TESTING.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
RELEASING.md Fix RELEASING.md: Homebrew formula uses GoReleaser artifacts, not source tarball 2025-11-08 03:59:59 -08:00
ROUTING.md Add routing integration tests and documentation 2025-11-04 23:12:42 -08:00
TROUBLESHOOTING.md feat: Complete GH #353 follow-up phases (bd-9nw, bd-u3t, bd-e0o) 2025-11-21 19:32:45 -05:00