AgentSkillsCN

troubleshooting

The Fold 故障排除指南——涵盖守护进程问题、会话损坏、文件路径以及常见故障。当 ./fold 无法正常运行、守护进程无法启动，或您需要查找系统文件时，可参考本指南。

SKILL.md
--- frontmatter
name: troubleshooting
description: Troubleshooting guide for The Fold - daemon issues, session corruption, file locations, and common problems. Use when ./fold isn't working, the daemon won't start, or you need to find system files.
allowed-tools: Bash, Read, Grep, Glob

Troubleshooting The Fold

Quick Fixes

Check daemon status

bash
./fold --status

Daemon won't start

bash
./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

bash
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.

scheme
;; In REPL, check fuel status
(fuel)

File Locations

REPL Infrastructure

PathPurpose
.fold-repl/readyDaemon ready file (presence indicates daemon is running)
.fold-repl/requests/<session>.ssSession request queue
.fold-repl/responses/<session>.txtSession response output
.fold-repl/daemon.logDaemon log (check for errors)
.fold-repl/discord-outbox/Discord bot message outbox

Persistent State

PathPurpose
.fold-sessions/Persistent session state (survives daemon restart)
.fold-users/User profile data

Content-Addressed Store

PathPurpose
.store/Content-addressed store root
.store/objects/CAS objects (blocks)
.store/heads/bbs/fold-*.headBBS issue heads (current hash per issue)
.store/heads/bbs/post-*.headBBS post heads (current hash per post)

BBS Runtime

PathPurpose
.bbs/BBS runtime data
.bbs/counterNext issue ID
.bbs/deps/Dependency tracking
.bbs/index/Search index cache

Project Files

PathPurpose
TAXONOMY.sexpMachine-readable project taxonomy
CLAUDE.mdAgent instructions (this file)
docs/agent-operating-manual.mdAgent procedures

Common Issues

"Daemon not responding"

  1. •Check if daemon is running: ./fold --status
  2. •Check daemon log: cat .fold-repl/daemon.log
  3. •Kill and restart: ./daemon.sh stop && ./fold --status

"Session not found"

Sessions are ephemeral unless named with -s:

bash
./fold -s mywork "(define x 10)"  # Creates named session
./fold -s mywork "x"              # Uses same session

"Module not found" during require

  1. •Check you're in project root (where core/, lattice/, boundary/ live)
  2. •Verify module exists: ls lattice/<module>/
  3. •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:

  1. •Check .store/ permissions
  2. •Run integrity check: ./fold "(cas-verify)"
  3. •Rebuild from git: rm -rf .store && ./fold "(cas-rebuild)"

BBS shows stale data

After reloading modules, refresh BBS state:

scheme
(bbs-init!)  ; Refresh from disk