session-resume

name	session-resume
description	Use when starting a new session and workflow-state.json exists in the working directory — recovers full context from checkpoint files before any new work

Session Resume

Overview

Every new session recovers state from files. No guessing. No assumptions.

Core principle: No new work until the resume protocol completes.

Violating the letter of this rule is violating the spirit of this rule.

The Iron Law

NO NEW WORK UNTIL RESUME PROTOCOL COMPLETES

The Resume Protocol

You MUST complete every step in order:

Step 1: Read workflow-state.json

Understand the workflow structure: how many stages, what status each is in, what the dependencies are.

Step 2: Read progress.log (tail)

Read the last 30-50 lines. Understand what happened in the last session: what was being worked on, where it stopped, any errors.

Step 3: Read git log (recent)

git log --oneline -10 — understand any file changes since last session.

Step 4: Run init.sh

Verify the environment is functional. If it fails → invoke superscientist:systematic-debugging.

Step 5: Check Running Processes

For each stage with status running or (preparing with running_process populated):

Condition	Action
tmux session alive (tmux has-session -t {session} 2>/dev/null)	Leave as running (or update preparing → running), log "Stage N still running (tmux: {session})"
tmux gone + DPDISP_DONE exists + exit code 0	Transition to post_processing, invoke superscientist:result-verification
tmux gone + DPDISP_DONE exists + exit code non-zero	Mark failed, set last_error from DPDispatcher logs
tmux gone + no DPDISP_DONE + recovery_attempted: false	Re-launch: tmux kill-session -t {session} 2>/dev/null && tmux new-session -d -s {session} "bash {wrapper_script}". Set recovery_attempted: true. Log "Recovering stage-N: re-launching DPDispatcher"
tmux gone + no DPDISP_DONE + recovery_attempted: true	Mark failed: "DPDispatcher monitoring process died twice. Check system stability and tmux."
No running_process data	Mark failed: "stale from previous session, no process info"

For stages with status preparing and no running_process → mark failed (subagent died mid-preparation).

Step 6: Identify Next Action

Find the next actionable item:

1. First ready stage (dependencies met)
2. Or a failed stage eligible for retry
3. Or a running stage to continue monitoring
4. Or all stages completed → invoke superscientist:workflow-completion

Step 7: Log and Resume

1. Read session_count from session_config in workflow-state.json. Increment by 1. Write back to workflow-state.json.
2. Append session start entry to progress.log using the incremented session_count as N:

echo "[$(date -Iseconds)] Session ${N} started. Reading workflow-state.json... [summary of state]" >> progress.log

N comes from session_count — not from counting log entries or inference.

3. Resume work via superscientist:executing-workflows.

If a running stage was identified in Step 5 with tmux still alive, re-establish background monitoring before dispatching any new stages:

# run_in_background: true, timeout: 600000
while [ ! -f "stage-N/DPDISP_DONE" ]; do sleep 30; done; cat stage-N/DPDISP_EXIT_CODE

The orchestrator will be auto-notified when the job completes, then resume via superscientist:executing-workflows Step 5 continuation.

Step 8: Reset Session Budget

Read session_config from workflow-state.json.

1. If exit_reason from the previous session is not null, log it:

   echo "[$(date -Iseconds)] Previous session ended: exit_reason=budget_exhausted, cost=5.5/6" >> progress.log
   

   (Use actual values from session_config.session_cost and session_config.session_budget.)
2. Set session_id to current ISO timestamp.
3. Set session_cost to 0.
4. Set exit_reason to null.
5. Write updated session_config to workflow-state.json.

This ensures every session starts with a fresh budget. The previous session's exit reason is logged before being cleared, preserving the audit trail in progress.log.

Failure Handling

Failure	Action
init.sh fails	Invoke superscientist:systematic-debugging
workflow-state.json missing or corrupted	Alert the user, do not proceed
progress.log missing	Create it with recovery note, proceed

Red Flags

Thought	Reality
"I remember what we were doing"	Read the files. Memory lies.
"Let me just continue from here"	Complete the full protocol first.
"init.sh passed last time, skip it"	Environment changes. Run it.
"That tmux session is probably still running"	Check with tmux has-session. Don't assume.
"The budget looks wrong, I'll skip the reset"	Reset is mandatory. The previous session's cost is stale.