fable-agent/PHASES/phase-01-session-engine.md

Phase 1: Session Engine

Purpose: Days-long autonomous session management with checkpoint/resume. TS Module: src/tier1-foundation/session-engine.ts

What It Does

Manages the session lifecycle: idle → running → checkpointing → resumed → completed → archived Saves checkpoints at every iteration. Resumes from latest checkpoint on restart.

Checkpoint/Resume

# CLI
npx tsx src/index.ts session start "Your goal here"
npx tsx src/index.ts session resume <session-id>
npx tsx src/index.ts session list
npx tsx src/index.ts session inspect <session-id>

Signals

• Heartbeat: written every 30s. If no heartbeat for >60s, session is stalled.
• Checkpoint: saved after each loop iteration. Latest and numbered copies.
• Stall detection: session inspect shows stall warning if heartbeat expired.

Key Rules

• Start a session before running any task
• Checkpoint before dreaming
• Resume from checkpoint if interrupted
• Complete sessions explicitly (avoids dangling state)