feat: Add session pause/resume for rate limit recovery

[rubenmarcus]

Summary

When ralph-starter hits rate limits or session usage limits, allow resuming from where it left off instead of starting over.

Problem

Currently when running auto mode or long tasks:

• Rate limit reached → must wait and restart from scratch
• Session usage at 100% → lose progress on incomplete tasks
• No way to continue partially completed batch

Solution

Add session persistence and resume capability.

Usage

# Normal run - automatically saves session state
ralph-starter auto --source github --label auto-ready

# If interrupted, resume later
ralph-starter resume

# Or with run command
ralph-starter run --continue

Implementation

Task 1: Session State Manager

• Create src/loop/session.ts
• Define SessionState interface (tasks, completed, current, branch)
• Save state to .ralph-session.json after each task
• Load state on resume

Task 2: CLI Commands

• Add ralph-starter resume command
• Add --continue flag to run command
• Add ralph-starter session status to show saved state
• Add ralph-starter session clear to reset

Task 3: Auto Mode Integration

• Save batch progress after each task completion
• Track which tasks completed vs pending
• Resume from correct git branch
• Skip already-completed tasks

Task 4: Rate Limit Recovery

• Detect rate limit errors
• Auto-save session before exiting
• Show "resume" command in rate limit message
• Estimate wait time if possible

Task 5: Documentation

• Add session/resume section to README.md
• Create docs/session-management.md for Docusaurus
• Document CLI commands and flags
• Add examples for rate limit recovery workflow

Session State Schema

interface SessionState {
  id: string;
  startedAt: string;
  lastUpdatedAt: string;
  cwd: string;
  mode: 'run' | 'auto';
  
  // For auto mode
  tasks?: BatchTask[];
  completedTaskIds?: string[];
  currentTaskIndex?: number;
  currentBranch?: string;
  
  // For run mode  
  task?: string;
  iterations?: number;
  
  // Results
  results?: TaskResult[];
}

Files to Create/Modify

• src/loop/session.ts (new)
• src/commands/resume.ts (new)
• src/commands/auto.ts (add session saving)
• src/commands/run.ts (add --continue flag)
• src/cli.ts (add resume command)
• README.md (add session management section)
• docs/session-management.md (new - Docusaurus)

Acceptance Criteria

• Session state persists across interruptions
• Resume picks up from last incomplete task
• Git branch state is restored correctly
• Rate limit message shows resume command
• Can clear session state manually
• Documentation in README.md and docs/

[rubenmarcus]

Automated PR created: multivmlabs/ralph-starter#122

Generated by ralph-starter auto mode