session_state
Save, load, or list orchestrator session snapshots to resume workflows after crashes, restarts, or pauses without re-planning or re-running completed modules.
Instructions
Save, load, or list orchestrator session snapshots for resumability. Lets a /forge workflow survive a crash, conversation restart, or an intentional pause — the next invocation can pick up exactly where the previous one left off, without re-planning or re-running completed modules.
Behaviour:
MUTATION on
save, READ onloadandlist.State lives at
.forge/state/<runId>.json. Writes use atomic tmp + rename semantics so a crash mid-save can never leave a partial file on disk.runIdis guarded against path traversal via_RUN_ID_PATTERN(/^[\w.-]{1,128}$/).Every
savestamps the state with a freshlastUpdatedAtISO timestamp;listsorts most-recent first using this field.No authentication, no network, no rate limits.
Use when:
The orchestrator has just completed a phase transition (plan approved, first parallel batch finished, module escalated) and wants to persist progress in case the session drops.
A fresh Claude Code session wants to resume an abandoned run: call
session_state({ action: "list" }), find the most recent run withcompletedCount < totalCount, thensession_state({ action: "load", runId: "..." }).A user has invoked
/forge-statusand the orchestrator is computing the summary.
Do NOT use for:
Per-module retry state — that's
iteration_state.Cross-run learned patterns — that's
memory_save.Ephemeral progress for the statusline — the server writes
/tmp/forge-status.jsonautomatically on every tool call; don't duplicate it here.
Returns:
save: { saved: true, runId, lastUpdatedAt }
load: { found: true, ...state } when the file exists,
{ found: false, runId } when it does not.
list: { sessions: [{ runId, lastUpdatedAt, currentPhase,
completedCount, totalCount }, ...] } sorted by
lastUpdatedAt descending.
Example: session_state({ action: "save", runId: "2026-04-15-1", state: { currentPhase: "execute", moduleStatuses: { m1: "done", m2: "running", m3: "pending" }, completedModules: ["m1"], startedAt: "2026-04-15T10:00:00Z" } }) → { "saved": true, "runId": "2026-04-15-1", "lastUpdatedAt": "..." }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | save = persist state, load = restore state, list = show all sessions | |
| runId | No | Run ID (required for save/load, ignored for list) | |
| state | No | Orchestrator state to persist (for save). Expected shape: {runId, planPath, currentPhase, moduleStatuses: {[moduleId]: status}, retryCounts: {[moduleId]: number}, completedModules: [string], startedAt, lastUpdatedAt} |