resume

Resume Task Harness Session

Continues a cancelled, failed, or blocked task harness session from its last checkpoint.

Overview

The resume skill restores and continues a previously stopped task harness session by:

• Validating the session exists and is in a resumable state
• Finding the appropriate resume point (first incomplete task)
• Optionally allowing override to a specific task number
• Resetting session status to "running"
• Rebuilding the task prompt with context from completed tasks
• Restarting the ralph-loop execution

Prerequisites

• Existing session - A session file in .claude/task-harness/sessions/
• Resumable status - Session must be: cancelled, failed, or blocked
• ralph-loop plugin - For restarting iteration

Instructions

Step 1: Parse Arguments

Extract session ID and optional --from-task flag:

Arguments: <session-id> [--from-task N]

Examples:
  1234567890-12345
  1234567890-12345 --from-task 3

Step 2: Validate Session

Check the session exists and is resumable:

STATE_FILE=".claude/task-harness/sessions/${SESSION_ID}.json"
[[ -f "$STATE_FILE" ]] || echo "ERROR: Session not found"

STATUS=$(jq -r '.status' "$STATE_FILE")
if [[ "$STATUS" != "cancelled" && "$STATUS" != "failed" && "$STATUS" != "blocked" ]]; then
  echo "ERROR: Session status '$STATUS' is not resumable"
fi

Step 3: Find Resume Point

If --from-task N provided: Use task index N (0-based).

Otherwise: Find first task where status != "complete":

RESUME_INDEX=$(jq '[.tasks[] | .status] | to_entries | map(select(.value != "complete")) | .[0].key' "$STATE_FILE")

Step 4: Reset Session State

Update session for resumption:

jq ".status = \"running\" |
    .currentTaskIndex = $RESUME_INDEX |
    .tasks[$RESUME_INDEX].status = \"in_progress\" |
    del(.completedAt) |
    del(.finalMessage)" "$STATE_FILE" > tmp && mv tmp "$STATE_FILE"

Step 5: Build Task Prompt

Generate dynamic planning prompt including:

• Task objective and constraints
• Previous work context (completed tasks)
• Success criteria
• Completion instructions

Step 6: Restart Execution

Launch ralph-loop with the task prompt:

/ralph-loop "<task-prompt>" --completion-promise "<promise-text>"

Output

Upon successful resume:

Task Harness Resumed
====================
Session: 1234567890-12345
Harness: implement-auth-feature
Previous Status: cancelled
Resuming from: Task 3 - Implement Auth Routes
Progress: 2/5 tasks previously completed

Execution restarted...

Error Handling

Error	Cause	Resolution
Session not found	Invalid session ID	Use /task-harness:status to list valid IDs
Not resumable	Status is "running" or "completed"	Cancel first if running, or start new if completed
Invalid task index	--from-task exceeds task count	Check total tasks in session
State corruption	Malformed session JSON	Check logs, may need to restart from YAML

Examples

Example 1: Resume from Last Stop

User: /task-harness:resume 1234567890-12345

Skill: Finds first incomplete task (task 3), resumes execution

Result:
Task Harness Resumed
====================
Session: 1234567890-12345
Resuming from: Task 3 - Implement Auth Routes

Example 2: Resume from Specific Task

User: /task-harness:resume 1234567890-12345 --from-task 2

Skill: Overrides resume point to task 2 (re-runs completed task)

Result:
Task Harness Resumed
====================
Resuming from: Task 2 - Implement User Model (override)
Warning: Task 2 was previously completed, re-running

Example 3: Resume Failed Session

User: /task-harness:resume 1234567890-12345

Skill: Session was "failed" due to max retries, resumes with fresh retry count

Result:
Task Harness Resumed
====================
Previous Status: failed (max retries on task 4)
Resuming from: Task 4 - Write Tests
Retry count reset to 0

Resources

• {baseDir}/docs/yaml-schema.md - Session state structure
• {baseDir}/scripts/setup-task-harness.sh - Understanding session initialization