{
  "id": "page:docs-user-guide-features-run-resumption",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/features/run-resumption.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/features/run-resumption.md",
    "sourceKind": "repo-docs",
    "title": "Run Resumption: Pause and Continue Workflows",
    "displayName": "Run Resumption: Pause and Continue Workflows",
    "slug": "docs/user-guide/features/run-resumption",
    "articlePath": "wiki/docs/user-guide/features/run-resumption.md",
    "article": "\n[Docs](../index.md) › [Features](./index.md) › Run Resumption\n\n# Run Resumption: Pause and Continue Workflows\n\n**Version:** 1.1\n**Last Updated:** 2026-01-26\n**Category:** Feature Guide\n\n---\n\n## In Plain English\n\n**You can stop and come back later. Nothing is lost.**\n\nClose your laptop, end your session, or even have your computer crash - when you come back, just say \"resume\" and Babysitter picks up exactly where it left off.\n\n**Common scenarios:**\n- 🔋 Your laptop battery dies → resume later\n- ⏸️ Waiting for someone to approve → resume when they approve\n- 🌙 End of workday → resume tomorrow morning\n\n**How to resume:** Just tell Babysitter to continue your previous work, or use the CLI command shown below.\n\n> **Note (v6):** The in-session command shown in the examples below (`/babysitter:call resume ...`) is the **Claude Code** form. The exact in-session token that triggers a resume **varies by harness** — see the [Slash Commands reference](../reference/slash-commands.md) for the per-harness surface. The CLI commands (`babysitter run:iterate`, `run:status`) are harness-agnostic and work everywhere.\n\n---\n\n## On this page\n\n- [Overview](#overview)\n- [Use Cases and Scenarios](#use-cases-and-scenarios)\n- [Step-by-Step Instructions](#step-by-step-instructions)\n- [Configuration Options](#configuration-options)\n- [Code Examples and Best Practices](#code-examples-and-best-practices)\n- [Common Pitfalls and Troubleshooting](#common-pitfalls-and-troubleshooting)\n- [How Resumption Works](#how-resumption-works)\n\n---\n\n## Overview\n\nRun resumption enables pausing and continuing Babysitter workflows at any point. Whether a session times out, a [breakpoint](../reference/glossary.md) awaits approval, or you simply need to continue later, Babysitter's event-sourced architecture ensures no work is lost. Workflows automatically resume from exactly where they left off.\n\n### Why Use Run Resumption\n\n- **Session Independence**: Continue workflows across multiple Claude Code sessions\n- **Breakpoint Handling**: Pause for human review and resume after approval\n- **Failure Recovery**: Recover from crashes or network issues without losing progress\n- **Flexible Scheduling**: Start work now, continue later when convenient\n- **Team Handoffs**: One person can start a workflow, another can continue it\n\n---\n\n## Use Cases and Scenarios\n\n### Scenario 1: Resume After Session Timeout\n\nA workflow is interrupted when a Claude Code session ends unexpectedly.\n\n```bash\n# Session 1: Start a workflow\nclaude \"/babysitter:call implement user authentication with TDD\"\n\n# ... session times out mid-execution ...\n\n# Session 2: Resume the workflow\nclaude \"/babysitter:call resume --run-id 01KFFTSF8TK8C9GT3YM9QYQ6WG\"\n```\n\n### Scenario 2: Continue After Breakpoint Approval\n\nA workflow pauses at a breakpoint while you review and approve changes.\n\n```bash\n# Workflow reaches breakpoint and pauses\n# \"Waiting for approval at breakpoint: Plan Review\"\n\nclaude \"/babysitter:call resume the babysitter run for the auth feature\"\n```\n\n### Scenario 3: Team Handoff\n\nOne team member starts work during the day, another continues overnight.\n\n```bash\n# Developer A (morning): Creates and starts run\nbabysitter run:create \\\n  --process-id feature/auth \\\n  --entry ./code/main.js#process \\\n  --inputs ./inputs.json \\\n  --prompt \"Implement auth feature for the platform\"\n\n# Developer B (evening): Continues the run\nclaude \"/babysitter:call resume --run-id feature-auth-20260125\"\n```\n\n### Scenario 4: Retry After Failure\n\nA task fails due to a transient error. Fix the issue and resume.\n\n```bash\n# Run fails with error\n# \"Error: API rate limit exceeded\"\n\n# After waiting for rate limit to reset:\nclaude \"/babysitter:call resume --run-id 01KFFTSF8TK8C9GT3YM9QYQ6WG\"\n```\n\n---\n\n## Step-by-Step Instructions\n\n### Step 1: Find the Run ID\n\nList available runs or check the output from when you started the workflow.\n\n**From initial output:**\n```\nRun ID: 01KFFTSF8TK8C9GT3YM9QYQ6WG\nRun Directory: .a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/\n```\n\n**List recent runs:**\n```bash\nls -lt .a5c/runs/ | head -10\n```\n\n**Check run status:**\n```bash\nbabysitter run:status 01KFFTSF8TK8C9GT3YM9QYQ6WG --json\n```\n\n### Step 2: Check Run Status\n\nVerify the run's current state before resuming.\n\n```bash\nbabysitter run:status 01KFFTSF8TK8C9GT3YM9QYQ6WG --json\n```\n\n**Example output:**\n```json\n{\n  \"runId\": \"01KFFTSF8TK8C9GT3YM9QYQ6WG\",\n  \"state\": \"waiting\",\n  \"metadata\": {\n    \"processId\": \"feature/auth\",\n    \"stateVersion\": 42,\n    \"pendingEffectsByKind\": {\n      \"breakpoint\": 1\n    }\n  }\n}\n```\n\n**State values:**\n- `running` - Active execution (may be from another session)\n- `waiting` - Paused at breakpoint or sleep\n- `completed` - Finished successfully\n- `failed` - Terminated with error\n\n### Step 3: Resume the Run\n\nUse the babysitter skill or CLI to resume execution.\n\n**Via skill (natural language):**\n```\nResume the babysitter run for the auth feature\n```\n\n**Via slash command:**\n```bash\n/babysitter:call resume --run-id 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\n**Via CLI (for scripting):**\n```bash\nbabysitter run:iterate 01KFFTSF8TK8C9GT3YM9QYQ6WG --json\n```\n\n### Step 4: Handle Pending Actions\n\nIf the run is waiting, resolve any pending actions before resuming.\n\n**Pending breakpoint:**\n1. Open http://localhost:3184\n2. Review and approve the breakpoint\n3. Resume the run\n\n**Pending sleep:**\n- Wait until the sleep deadline passes\n- Or manually advance time in testing scenarios\n\n### Step 5: Monitor Progress\n\nWatch the resumed workflow's progress.\n\n```bash\n# View recent events\nbabysitter run:events 01KFFTSF8TK8C9GT3YM9QYQ6WG --limit 10 --reverse\n\n# Check for new pending tasks\nbabysitter task:list 01KFFTSF8TK8C9GT3YM9QYQ6WG --pending --json\n```\n\n---\n\n## Configuration Options\n\n### Run Status States\n\n| State | Description | Can Resume? |\n|-------|-------------|-------------|\n| `running` | Currently executing | Check if session is active |\n| `waiting` | Paused at breakpoint/sleep | Yes |\n| `completed` | Finished successfully | No (already done) |\n| `failed` | Terminated with error | Depends on error type |\n\n### Session Resolution (v6)\n\nTo resume the right run, Babysitter must work out which harness session you are in. This changed in v6:\n\n- **The session ID env var is now `AGENT_SESSION_ID`** (harness-agnostic). The old `BABYSITTER_SESSION_ID` is **DEPRECATED** and superseded by `AGENT_SESSION_ID`.\n- **Resolution is now PID-scoped, not env-first.** Earlier versions trusted the session env var first; v6 resolves the active session from **PID-scoped markers** so concurrent sessions don't collide. The previous env-first behavior is **deprecated**.\n- **Escape hatch:** If you need the legacy env-first behavior (for example, an automation that injects the session ID), set `BABYSITTER_TRUST_ENV_SESSION=1` to make the runtime trust the session env var again.\n\n| Key | Status | Notes |\n|-----|--------|-------|\n| `AGENT_SESSION_ID` | Current | Harness-agnostic session ID |\n| `BABYSITTER_SESSION_ID` | **Deprecated** | Superseded by `AGENT_SESSION_ID` |\n| `BABYSITTER_TRUST_ENV_SESSION=1` | Escape hatch | Restores legacy env-first session resolution |\n\nSee [Configuration](../reference/configuration.md) for the full key reference and [Troubleshooting](../reference/troubleshooting.md) if a resume targets the wrong run.\n\n### Resume Command Options\n\n```bash\n/babysitter:call resume --run-id <id> [--max-iterations <n>]\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--run-id` | string | Required | The run ID to resume |\n| `--max-iterations` | number | Unlimited | Maximum iterations for this session |\n\n### CLI Resume Commands\n\n**Single iteration:**\n```bash\nbabysitter run:iterate <runId> --json\n```\n\n**Check status:**\n```bash\nbabysitter run:status <runId> --json\n```\n\n---\n\n## Code Examples and Best Practices\n\n### Example 1: Resume via Skill (Recommended)\n\nThe simplest way to resume a run is through natural language:\n\n```\nClaude, resume the babysitter run 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\nOr:\n\n```\nContinue the babysitter run for the authentication feature\n```\n\n### Example 2: Resume via CLI Script\n\nFor automated scenarios, use the CLI in a loop:\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nRUN_ID=\"01KFFTSF8TK8C9GT3YM9QYQ6WG\"\nCLI=\"npx -y @a5c-ai/babysitter@latest\"\n\n# Check current status\nSTATUS=$($CLI run:status \"$RUN_ID\" --json | jq -r '.state')\n\nif [ \"$STATUS\" = \"completed\" ]; then\n  echo \"Run already completed\"\n  exit 0\nelif [ \"$STATUS\" = \"failed\" ]; then\n  echo \"Run previously failed, cannot resume\"\n  exit 1\nfi\n\n# Resume loop\nwhile true; do\n  RESULT=$($CLI run:iterate \"$RUN_ID\" --json)\n  ITER_STATUS=$(echo \"$RESULT\" | jq -r '.status')\n\n  echo \"Iteration status: $ITER_STATUS\"\n\n  case \"$ITER_STATUS\" in\n    \"completed\")\n      echo \"Run completed successfully\"\n      exit 0\n      ;;\n    \"failed\")\n      echo \"Run failed\"\n      exit 1\n      ;;\n    \"waiting\")\n      echo \"Run waiting (breakpoint or sleep)\"\n      exit 0\n      ;;\n    *)\n      # executed or none - continue\n      ;;\n  esac\ndone\n```\n\n### Example 3: Inspect Run Before Resuming\n\nCheck what happened and what's pending:\n\n```bash\n# Get run metadata\ncat .a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/run.json | jq .\n\n# View recent journal events\nbabysitter run:events 01KFFTSF8TK8C9GT3YM9QYQ6WG --limit 20 --reverse --json | jq '.events[] | {type, recordedAt}'\n\n# Check pending tasks\nbabysitter task:list 01KFFTSF8TK8C9GT3YM9QYQ6WG --pending --json | jq '.tasks[] | {effectId, kind, status}'\n```\n\n### Example 4: Resume After Fixing an Issue\n\nWhen a task fails due to a fixable issue:\n\n```bash\n# 1. Check what failed\nbabysitter run:events \"$RUN_ID\" --filter-type RUN_FAILED --json | jq '.events[].data.error'\n\n# 2. Fix the underlying issue (e.g., install missing dependency)\nnpm install missing-package\n\n# 3. Resume the run\nclaude \"/babysitter:call resume --run-id $RUN_ID\"\n```\n\n### Example 5: Resumable Process Design\n\nDesign processes that are resumption-friendly:\n\n```javascript\nexport async function process(inputs, ctx) {\n  // Each phase is a separate task - resumption continues from last completed task\n\n  // Phase 1: Research (if not done, this executes; if done, returns cached result)\n  const research = await ctx.task(researchTask, { feature: inputs.feature });\n\n  // Phase 2: Planning\n  const plan = await ctx.task(planningTask, { research });\n\n  // Breakpoint allows natural pause/resume point\n  await ctx.breakpoint({\n    question: 'Review plan before implementation?',\n    title: 'Plan Approval'\n  });\n\n  // Phase 3: Implementation\n  const impl = await ctx.task(implementTask, { plan });\n\n  // Phase 4: Verification\n  const verification = await ctx.task(verifyTask, { impl });\n\n  return { success: verification.passed };\n}\n```\n\n### Best Practices\n\n1. **Use Descriptive Run IDs**: Include project name and date for easy identification\n2. **Add Breakpoints at Natural Pause Points**: Design workflows with clear approval gates\n3. **Check Status Before Resuming**: Verify the run is in a resumable state\n4. **Handle Pending Actions**: Resolve breakpoints before attempting resume\n5. **Monitor Journal Events**: Review what happened during previous execution\n6. **Design Idempotent Tasks**: Tasks should handle being re-executed gracefully\n\n---\n\n## Common Pitfalls and Troubleshooting\n\n### Pitfall 1: Attempting to Resume a Completed Run\n\n**Symptom:** Resume has no effect.\n\n**Cause:** The run already finished successfully.\n\n**Solution:**\n```bash\n# Check if completed\nbabysitter run:status \"$RUN_ID\" --json | jq '.state'\n# If \"completed\", the run is done - create a new run instead\n```\n\n### Pitfall 2: Breakpoint Not Resolved\n\n**Symptom:** Resume says \"waiting\" but nothing happens.\n\n**Cause:** Breakpoint awaiting approval.\n\n**Solution:**\n1. Check pending breakpoints:\n   ```bash\n   babysitter task:list \"$RUN_ID\" --pending --json | jq '.tasks[] | select(.kind == \"breakpoint\")'\n   ```\n2. Open http://localhost:3184 and approve/reject the breakpoint\n3. Resume the run\n\n### Pitfall 3: State Corruption After Manual Edits\n\n**Symptom:** Run behaves unexpectedly after resume.\n\n**Cause:** Manual edits to journal or state files.\n\n**Solution:**\n- Never manually edit `journal/` or `state/` files\n- If state is corrupted, delete `state/state.json` and let CLI rebuild it:\n  ```bash\n  rm .a5c/runs/\"$RUN_ID\"/state/state.json\n  babysitter run:status \"$RUN_ID\"  # Rebuilds state from journal\n  ```\n\n### Pitfall 4: Different Process Code After Resume\n\n**Symptom:** Resume produces unexpected behavior.\n\n**Cause:** Process code modified between sessions.\n\n**Solution:**\n- Avoid modifying process code for in-progress runs\n- If changes are necessary, consider starting a new run\n- The SDK stores `processRevision` to detect changes\n\n### Pitfall 5: Session Conflict\n\n**Symptom:** \"Run is already being executed\" error.\n\n**Cause:** Another session is actively running the same run.\n\n**Solution:**\n- Wait for the other session to complete or pause\n- Check if you have another Claude Code window running the same workflow\n- If the previous session crashed, wait a moment and retry\n\n### Pitfall 6: Missing Run Directory\n\n**Symptom:** \"Run not found\" error.\n\n**Cause:** Run directory doesn't exist or was cleaned up.\n\n**Solution:**\n```bash\n# Check if directory exists\nls -la .a5c/runs/ | grep \"$RUN_ID\"\n\n# If missing, the run may have been deleted or never created\n# Create a new run instead\n```\n\n---\n\n## How Resumption Works\n\n### Event-Sourced State Reconstruction\n\nWhen you resume a run, Babysitter:\n\n1. **Loads the Journal**: Reads all events from `journal/` directory\n2. **Reconstructs State**: Replays events to rebuild current state\n3. **Identifies Position**: Determines what tasks have completed vs. pending\n4. **Continues Execution**: Resumes process from the last completed point\n\n```\nJournal Events:\n├── 000001.json  RUN_CREATED\n├── 000002.json  EFFECT_REQUESTED (task-1)\n├── 000003.json  EFFECT_RESOLVED (task-1) ✓\n├── 000004.json  EFFECT_REQUESTED (task-2)\n├── 000005.json  EFFECT_RESOLVED (task-2) ✓\n├── 000006.json  EFFECT_REQUESTED (breakpoint-1)  ← Waiting here\n└── (resume continues from breakpoint-1)\n```\n\n### Deterministic Replay\n\nThe process function re-executes from the beginning on resume:\n\n```javascript\nexport async function process(inputs, ctx) {\n  // On resume, ctx.task returns cached result immediately\n  const task1Result = await ctx.task(task1, {});  // Returns cached result\n  const task2Result = await ctx.task(task2, {});  // Returns cached result\n\n  // Resume point - this is where we actually pause\n  await ctx.breakpoint({ question: 'Continue?' });  // Waiting here\n\n  // After breakpoint approval, execution continues\n  const task3Result = await ctx.task(task3, {});\n}\n```\n\n---\n\n## Related Documentation\n\n- [Breakpoints](./breakpoints.md) - Understand approval gates that cause pauses\n- [Journal System](./journal-system.md) - Learn how state is persisted\n- [Process Definitions](./process-definitions.md) - Design resumable workflows\n- [Configuration](../reference/configuration.md) - Session env vars (`AGENT_SESSION_ID`) and `BABYSITTER_TRUST_ENV_SESSION`\n- [Troubleshooting](../reference/troubleshooting.md) - Diagnosing session-resolution and resume issues\n- [Slash Commands](../reference/slash-commands.md) - Per-harness in-session resume tokens\n\n---\n\n## Summary\n\nRun resumption is a fundamental Babysitter capability that ensures workflow progress is never lost. The event-sourced journal captures every state change, enabling workflows to resume from exactly where they paused. Use breakpoints for natural pause points, check run status before resuming, and design processes with resumption in mind.\n\n---\n\n## Next steps\n\n- **Next:** [Journal System](./journal-system.md)\n- **Related:** [Breakpoints](./breakpoints.md), [CLI Reference](../reference/cli-reference.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-features",
      "to": "page:docs-user-guide-features-run-resumption",
      "kind": "contains_page"
    }
  ]
}