Session State Manager

Handles persistent state for orchestrator sessions, enabling resume after disconnects.

Scope — Not to Be Confused With orchestrate:resume

"Resume" here means resuming orchestrator-v2 session state: reloading .claude/orchestrator-session.json so an in-progress multi-agent orchestration can continue where it left off (see Resume Flow below). This skill has no relationship to the orchestrate:resume slash command, which was a separate, fictional 523-line command removed in #239. If a request seems to want "bring back the old orchestrate:resume command," that is out of scope for this skill — this skill only manages the session-state JSON files described below.

State File Location

.claude/orchestrator-session.json     # Current session (project-local)
.claude/orchestrator-history/         # Session history (project-local)
  └── 2025-12-27-abc123.json         # Archived sessions

Session State Schema

{
  "schema_version": "1.0",
  "session_id": "2025-12-27-abc123",
  "created": "2025-12-27T10:30:00Z",
  "updated": "2025-12-27T11:45:00Z",
  "project": {
    "name": "my-project",
    "path": "/path/to/my-project",
    "git_branch": "dev"
  },
  "goal": "Add sensitivity analysis to RMediation::medci()",
  "mode": "default",
  "status": "in_progress",
  "agents": [
    {
      "id": "arch-1",
      "type": "arch",
      "task": "Design sensitivity API",
      "status": "complete",
      "started": "2025-12-27T10:30:00Z",
      "completed": "2025-12-27T10:32:00Z",
      "result_summary": "3 methods proposed: bootstrap, delta, MCMC",
      "context_tokens": 1500
    },
    {
      "id": "code-1",
      "type": "code",
      "task": "Implement primary method",
      "status": "in_progress",
      "started": "2025-12-27T10:32:00Z",
      "progress": 60,
      "context_tokens": 3200
    }
  ],
  "completed_work": [
    {
      "task": "Architecture design",
      "outcome": "3 methods proposed",
      "files": ["R/sensitivity.R"]
    }
  ],
  "pending_tasks": [
    "Complete code-1 implementation",
    "Add unit tests",
    "Update documentation"
  ],
  "decisions_made": [
    {
      "decision": "Use bootstrap for confidence intervals",
      "rationale": "Best balance of accuracy and performance",
      "timestamp": "2025-12-27T10:31:00Z"
    }
  ],
  "context_usage": {
    "estimated_tokens": 25000,
    "percentage": 20,
    "last_compression": null
  },
  "errors": []
}

Operations

Save Session

Called automatically on:

• Agent completion
• User says save
• Before compression
• On abort

def save_session(state: dict) -> Path:
    """Save current session state."""
    state["updated"] = datetime.now().isoformat()

    session_file = Path(".claude/orchestrator-session.json")
    session_file.parent.mkdir(exist_ok=True)
    session_file.write_text(json.dumps(state, indent=2))

    return session_file

Load Session

Called when user says continue:

def load_session() -> Optional[dict]:
    """Load existing session if available."""
    session_file = Path(".claude/orchestrator-session.json")

    if not session_file.exists():
        return None

    state = json.loads(session_file.read_text())

    # Validate schema version
    if state.get("schema_version") != "1.0":
        return None  # Incompatible version

    return state

Archive Session

Called on session completion or new session start:

def archive_session(state: dict) -> Path:
    """Move session to history."""
    history_dir = Path(".claude/orchestrator-history")
    history_dir.mkdir(exist_ok=True)

    archive_file = history_dir / f"{state['session_id']}.json"
    archive_file.write_text(json.dumps(state, indent=2))

    # Remove current session file
    Path(".claude/orchestrator-session.json").unlink(missing_ok=True)

    return archive_file

List History

def list_history(limit: int = 10) -> list[dict]:
    """List recent sessions."""
    history_dir = Path(".claude/orchestrator-history")

    if not history_dir.exists():
        return []

    sessions = []
    for f in sorted(history_dir.glob("*.json"), reverse=True)[:limit]:
        state = json.loads(f.read_text())
        sessions.append({
            "id": state["session_id"],
            "goal": state["goal"],
            "status": state["status"],
            "created": state["created"]
        })

    return sessions

Resume Flow

When user says continue:

## 🔄 RESUMING SESSION

**Session ID**: 2025-12-27-abc123
**Goal**: Add sensitivity analysis to RMediation::medci()
**Started**: 2 hours ago
**Progress**: 60% complete

### Completed Work
- ✅ Architecture design (3 methods proposed)
- ✅ Test stubs created

### In Progress
- 🔄 code-1: Implement primary method (60%)

### Pending
1. Complete code-1 implementation
2. Add unit tests
3. Update documentation

### Context Budget
- Tokens used: ~25,000 (20%)
- Last compression: Never

**Resuming from code-1...**

State Transitions

┌─────────────────────────────────────────────────────────┐
│                    Session Lifecycle                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  [new task] ──► CREATED ──► IN_PROGRESS ──► COMPLETE   │
│                    │              │             │       │
│                    │              │             ▼       │
│                    │              │         [archive]   │
│                    │              │                     │
│                    │              ▼                     │
│                    │          PAUSED ◄── [disconnect]  │
│                    │              │                     │
│                    │              ▼                     │
│                    │         [continue]                 │
│                    │              │                     │
│                    │              ▼                     │
│                    └────► IN_PROGRESS                   │
│                                                         │
│  [abort] ──► ABORTED ──► [archive]                     │
│                                                         │
└─────────────────────────────────────────────────────────┘

Auto-Save Triggers

Error Recovery

If session file is corrupted:

## ⚠️ SESSION RECOVERY

The previous session file appears corrupted.

**Options**:
1. **Start fresh**: Begin new session (old state lost)
2. **View history**: Check archived sessions
3. **Manual recovery**: I'll try to extract what I can

Which would you prefer?

Integration with Orchestrator

The orchestrator calls session state operations at key points:

# On startup
if args == "continue":
    state = load_session()
    if state:
        resume_from_state(state)
    else:
        print("No session to resume")

# On task analysis
state = create_new_session(goal, mode)
save_session(state)

# On agent completion
update_agent_status(state, agent_id, "complete", result)
save_session(state)

# On shutdown
if status == "complete":
    archive_session(state)
else:
    save_session(state)  # Keep for resume