Data-Wise 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
| Event | Action |
|---|---|
| Agent starts | Update state, save |
| Agent completes | Update result, save |
| Agent fails | Log error, save |
| Decision made | Log decision, save |
User says save |
Force save |
| Compression | Save before compress |
| Session end | Archive |
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