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
fable-agent session start "Your goal here"
fable-agent session resume <session-id>
fable-agent session list
fable-agent 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)