tomevault-io Troubleshooting The Fold
Quick Fixes
Check daemon status
./fold --status
Daemon won't start
./daemon.sh stop # Clear stale state
./daemon.sh cleanup # Kill orphan workers
./daemon.sh start # Or just run ./fold - it auto-starts
Session state corruption
rm -rf .fold-repl/ # Nuclear option - clears all session state
./fold "(help)" # Auto-starts fresh daemon
Tests hanging
Check fuel consumption. Infinite loops exhaust fuel and return out-of-fuel error.
;; In REPL, check fuel status
(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:
./fold -s mywork "(define x 10)" # Creates named session
./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:
(bbs-init!) ; Refresh from disk
Converted and distributed by TomeVault — claim your Tome and manage your conversions.