Troubleshooting The Fold
Quick Fixes
Check daemon status
bash1./fold --status
Daemon won't start
bash1./daemon.sh stop # Clear stale state 2./daemon.sh cleanup # Kill orphan workers 3./daemon.sh start # Or just run ./fold - it auto-starts
Session state corruption
bash1rm -rf .fold-repl/ # Nuclear option - clears all session state 2./fold "(help)" # Auto-starts fresh daemon
Tests hanging
Check fuel consumption. Infinite loops exhaust fuel and return out-of-fuel error.
scheme1;; In REPL, check fuel status 2(fuel)
File Locations
REPL Infrastructure
| Path | Purpose |
|---|---|
.fold-repl/ready | Daemon ready file (presence indicates daemon is running) |
.fold-repl/requests/<session>.ss | Session request queue |
.fold-repl/responses/<session>.txt | Session response output |
.fold-repl/daemon.log | Daemon log (check for errors) |
Persistent State
| Path | Purpose |
|---|---|
.fold-sessions/ | Persistent session state (survives daemon restart) |
.fold-users/ | User profile data |
Content-Addressed Store
| Path | Purpose |
|---|---|
.store/ | Content-addressed store root |
.store/objects/ | CAS objects (blocks) |
.store/heads/bbs/fold-*.head | BBS issue heads (current hash per issue) |
.store/heads/bbs/post-*.head | BBS post heads (current hash per post) |
BBS Runtime
| Path | Purpose |
|---|---|
.bbs/ | BBS runtime data |
.bbs/counter | Next issue ID |
.bbs/deps/ | Dependency tracking |
.bbs/index/ | Search index cache |
Project Files
| Path | Purpose |
|---|---|
TAXONOMY.sexp | Machine-readable project taxonomy |
CLAUDE.md | Agent instructions (this file) |
docs/agent-operating-manual.md | Agent procedures |
Common Issues
"Daemon not responding"
- Check if daemon is running:
./fold --status - Check daemon log:
cat .fold-repl/daemon.log - Kill and restart:
./daemon.sh stop && ./fold --status
"Session not found"
Sessions are ephemeral unless named with -s:
bash1./fold -s mywork "(define x 10)" # Creates named session 2./fold -s mywork "x" # Uses same session
"Module not found" during require
- Check you're in project root (where
core/,lattice/,boundary/live) - Verify module exists:
ls lattice/<module>/ - Check for typos in module name
"Out of fuel" error
The expression exceeded its fuel budget. Options:
- Simplify the expression
- Check for infinite recursion
- Increase fuel budget (if safe)
"Hash mismatch" or CAS errors
The CAS store may be corrupted. Options:
- Check
.store/permissions - Run integrity check:
./fold "(cas-verify)" - Rebuild from git:
rm -rf .store && ./fold "(cas-rebuild)"
BBS shows stale data
After reloading modules, refresh BBS state:
scheme1(bbs-init!) ; Refresh from disk
