b3e76ff1f6
Implements three quick fixes for users stuck in sandboxed environments (e.g., Codex) where daemon cannot be stopped: 1. **--force flag for bd import** - Forces metadata update even when DB is synced with JSONL - Fixes stuck state caused by stale daemon cache - Shows: "Metadata updated (database already in sync with JSONL)" 2. **--allow-stale global flag** - Emergency escape hatch to bypass staleness check - Shows warning: "⚠️ Staleness check skipped (--allow-stale)" - Allows operations on potentially stale data 3. **Improved error message** - Added sandbox-specific guidance to staleness error - Suggests --sandbox, --force, and --allow-stale flags - Provides clear fix steps for different scenarios Also fixed: - Removed unused import in cmd/bd/duplicates_test.go Follow-up work filed: - bd-u3t: Phase 2 - Sandbox auto-detection - bd-e0o: Phase 3 - Daemon robustness enhancements - bd-9nw: Documentation updates Fixes #353 (Phase 1) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
129 lines
4.3 KiB
Markdown
129 lines
4.3 KiB
Markdown
# Next Session Prompt: Implement GH #353 Fixes
|
|
|
|
## Context
|
|
We've investigated GH #353 (daemon locking issues in Codex sandbox). Full analysis in `docs/GH353_INVESTIGATION.md`.
|
|
|
|
**TL;DR:** Users in sandboxed environments (Codex) get stuck with "Database out of sync" errors because:
|
|
1. Running daemon has cached metadata
|
|
2. `bd import` updates database but daemon never sees it
|
|
3. Sandbox can't signal/kill the daemon
|
|
4. User is stuck in infinite loop
|
|
|
|
## Task: Implement Phase 1 Solutions
|
|
|
|
Implement three quick fixes that give users escape hatches:
|
|
|
|
### 1. Add `--force` flag to `bd import`
|
|
**File:** `cmd/bd/import.go`
|
|
|
|
**What to do:**
|
|
- Add `--force` flag to importCmd.Flags() (around line 692)
|
|
- When `--force` is true, ALWAYS update metadata (lines 310-346) even if `created == 0 && updated == 0`
|
|
- Print message: "Metadata updated (database already in sync with JSONL)"
|
|
- Ensure `TouchDatabaseFile()` is called to update mtime
|
|
|
|
**Why:** Allows users to manually force metadata sync when stuck
|
|
|
|
### 2. Add `--allow-stale` global flag
|
|
**File:** `cmd/bd/main.go`
|
|
|
|
**What to do:**
|
|
- Add global var: `allowStale bool`
|
|
- Add to rootCmd.PersistentFlags(): `--allow-stale` (around line 111)
|
|
- Description: "Allow operations on potentially stale data (skip staleness check)"
|
|
|
|
**File:** `cmd/bd/staleness.go`
|
|
|
|
**What to do:**
|
|
- At top of `ensureDatabaseFresh()` function (line 20), add:
|
|
```go
|
|
if allowStale {
|
|
fmt.Fprintf(os.Stderr, "⚠️ Staleness check skipped (--allow-stale), data may be out of sync\n")
|
|
return nil
|
|
}
|
|
```
|
|
|
|
**Why:** Emergency escape hatch when staleness check blocks operations
|
|
|
|
### 3. Improve error message in staleness.go
|
|
**File:** `cmd/bd/staleness.go`
|
|
|
|
**What to do:**
|
|
- Update the error message (lines 41-50) to add sandbox guidance:
|
|
```go
|
|
return fmt.Errorf(
|
|
"Database out of sync with JSONL. Run 'bd import' first.\n\n"+
|
|
"The JSONL file has been updated (e.g., after 'git pull') but the database\n"+
|
|
"hasn't been imported yet. This would cause you to see stale/incomplete data.\n\n"+
|
|
"To fix:\n"+
|
|
" bd import -i .beads/beads.jsonl # Import JSONL updates to database\n\n"+
|
|
"If in a sandboxed environment (e.g., Codex) where daemon can't be stopped:\n"+
|
|
" bd --sandbox ready # Use direct mode (no daemon)\n"+
|
|
" bd import --force # Force metadata update\n"+
|
|
" bd ready --allow-stale # Skip staleness check (use with caution)\n\n"+
|
|
"Or use daemon mode (auto-imports on every operation):\n"+
|
|
" bd daemon start\n"+
|
|
" bd <command> # Will auto-import before executing",
|
|
)
|
|
```
|
|
|
|
**Why:** Guides users to the right solution based on their environment
|
|
|
|
## Testing Checklist
|
|
|
|
After implementation:
|
|
|
|
- [ ] `bd import --force -i .beads/beads.jsonl` updates metadata even with 0 changes
|
|
- [ ] `bd import --force` without `-i` flag shows appropriate error (needs input file)
|
|
- [ ] `bd ready --allow-stale` bypasses staleness check and shows warning
|
|
- [ ] Error message displays correctly and includes sandbox guidance
|
|
- [ ] `--sandbox` mode still works as before
|
|
- [ ] Flags appear in `bd --help` and `bd import --help`
|
|
|
|
## Quick Start Commands
|
|
|
|
```bash
|
|
# 1. Review the investigation
|
|
cat docs/GH353_INVESTIGATION.md
|
|
|
|
# 2. Check current import.go implementation
|
|
grep -A 5 "func init()" cmd/bd/import.go
|
|
|
|
# 3. Check current staleness.go
|
|
head -60 cmd/bd/staleness.go
|
|
|
|
# 4. Run existing tests to establish baseline
|
|
go test ./cmd/bd/... -run TestImport
|
|
go test ./cmd/bd/... -run TestStaleness
|
|
|
|
# 5. Implement changes (see sections above)
|
|
|
|
# 6. Test manually
|
|
bd import --help | grep force
|
|
bd --help | grep allow-stale
|
|
```
|
|
|
|
## Expected Outcome
|
|
|
|
Users stuck in Codex sandbox can:
|
|
1. Run `bd import --force -i .beads/beads.jsonl` to fix metadata
|
|
2. Run `bd --sandbox ready` to use direct mode
|
|
3. Run `bd ready --allow-stale` as last resort
|
|
4. See helpful error message explaining their options
|
|
|
|
## References
|
|
|
|
- **Investigation:** `docs/GH353_INVESTIGATION.md`
|
|
- **Issue:** https://github.com/steveyegge/beads/issues/353
|
|
- **Key files:**
|
|
- `cmd/bd/import.go` (import command)
|
|
- `cmd/bd/staleness.go` (staleness check)
|
|
- `cmd/bd/main.go` (global flags)
|
|
|
|
## Estimated Time
|
|
~1-2 hours for implementation + testing
|
|
|
|
---
|
|
|
|
**Ready to implement?** Start with adding the flags, then update the error message, then test thoroughly.
|