Plan–Execute Runner — Checkpointing & Resume Guide

This guide shows how to run plan_execute_from_yaml.py, what files it creates, and how to resume from exactly the point you want — in both single and hierarchical planning modes.

Example config to try:
examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml

---

Quickstart

# Fresh run (prompts auto-default after the countdown)
python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml

Resume from a specific checkpoint: This example assumes the randomly generated workspace name is FOOBAR. Change it to the one generated when you ran it yourself. It also assumes a checkpoint number you want to resume.

It's important to understand that what this does is look in workspace for a checkpoint to resume from. You can set that workspace yourself by name or use the name generated by URSA if you didn't choose one yourself.

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml \
  --workspace pi_multiple_ways_FOOBAR \
  --resume-from executor_checkpoint_5.db

Headless / HPC-friendly (no waiting at prompts):

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml \
  --workspace pi_multiple_ways_batchrun \
  --interactive-timeout 0

---

What the script does

• Plans steps from your YAML “problem.”
• Executes those steps while checkpointing to SQLite.
• Lets you pause/resume from either:
• the live checkpoint (executor_checkpoint.db), or
• any snapshot (executor_checkpoint_*.db) created after each step/sub-step.

All interactive prompts include a countdown and then pick a safe default. Use --interactive-timeout 0 to default immediately (great for clusters).

---

CLI Options

Flag	What it does	When to use it
--config PATH	Path to your YAML problem config.	Required. Try the example pi_multiple_ways.yaml.
--workspace NAME	Directory for checkpoints & outputs. If omitted, a new name is generated and printed.	Use a stable name to resume later.
--planning-mode {single,hierarchical}	Force planning mode. If omitted, you’ll be prompted. First run locks the workspace to that mode.	single = plan once, run top-level steps. hierarchical = plan top-level, then re-plan sub-steps per main step.
--stepwise-exit	Demo mode: exits after each plan/step checkpoint.	Good for demonstrating checkpointing; not needed normally.
--resume-from FILE	Restore executor state from a checkpoint file (e.g., executor_checkpoint_5.db or executor_checkpoint_3_2.db).	Jump back to an earlier step or to a precise sub-step.
--interactive-timeout SECONDS	How long prompts (model/mode/checkpoint) wait before defaulting. 0 = default immediately.	Set to 0 for HPC/headless. Otherwise default is 60.

---

Files you’ll see in a workspace

<workspace>/
├── executor_checkpoint.db          # live executor DB (current run)
├── executor_checkpoint_1.db        # snapshot after step 1 (single mode)
├── executor_checkpoint_2.db        # snapshot after step 2
├── executor_checkpoint_3_2.db      # snapshot after MAIN=3, SUB=2 (hierarchical)
├── executor_progress.json          # single-mode progress (next_index, plan_hash, last_summary)
├── hier_progress.json              # hierarchical progress (main index + per-step sub-progress)
├── planner_checkpoint.db           # planner’s DB
├── run_meta.json                   # metadata (planning_mode lock, plan hash, model, etc.)
└── ...                             # artifacts produced by steps (csv, plots, code, html, etc.)

Snapshot naming: - Single mode: executor_checkpoint_<STEP>.db
Example for 6 steps: executor_checkpoint_1.db . . . executor_checkpoint_6.db. - Hierarchical mode: executor_checkpoint_<MAIN>_<SUB>.db
<MAIN> is the 1-based top-level step; <SUB> is the 1-based sub-step just finished.

You can resume from any of these snapshot files.

---

Single vs. Hierarchical

Single mode

• Planner creates one list of top-level steps.
• Execution proceeds linearly.
• After each top-level step completes, a snapshot is saved:
• executor_checkpoint_1.db, executor_checkpoint_2.db, . . .

Resuming (single): - --resume-from executor_checkpoint_5.db sets executor_progress.json so the next step to run is step 6. - Without --resume-from, you’ll get an interactive chooser (with countdown). Default is executor_checkpoint.db (live).

Example tree (6 steps planned):

workspace/
├── executor_checkpoint.db
├── executor_checkpoint_1.db
├── executor_checkpoint_2.db
├── executor_checkpoint_3.db
├── executor_checkpoint_4.db
├── executor_checkpoint_5.db
├── executor_checkpoint_6.db
└── executor_progress.json

To redo from step 3, run with: --resume-from executor_checkpoint_2.db.

---

Hierarchical mode

• Planner creates top-level steps.
• For each main step, it re-plans concrete sub-steps.
• A snapshot is saved after each sub-step:
• executor_checkpoint_3_2.db = finished main step 3, sub-step 2.

Resuming (hierarchical): - --resume-from executor_checkpoint_3_2.db resumes within main step 3 at sub-step 3 (if it exists). - executor_checkpoint_4_1.db would continue with main 4, sub-step 2, etc.

---

Typical flows

Fresh run, default everything

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml

- Prompts choose defaults after the countdown. - A new workspace is created if --workspace isn’t supplied.

Resume from the latest run (no prompts)

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml \
  --workspace pi_multiple_ways_myws \
  --interactive-timeout 0

- Uses the default executor_checkpoint.db.
- If no checkpoints exist yet, it starts fresh.

Jump back to an earlier point

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml \
  --workspace pi_multiple_ways_myws \
  --resume-from executor_checkpoint_5.db

- Great for re-running from step 6 in single mode, or for precise sub-step resumes in hierarchical mode using <MAIN>_<SUB>.

---

Planning-mode lock per workspace

On the first run in a workspace, the chosen planning mode is locked in run_meta.json.
If you later pass a different --planning-mode for the same workspace, the script warns and keeps the original mode.
Use a new --workspace to switch modes for a project.

---

When the plan changes

The runner hashes your plan (plan_sig). If the plan changes:

• Single mode: executor_progress.json resets to step 0 for the new plan.
• Hierarchical mode: top-level or sub-plan changes reset the affected progress segments.

If you want a clean re-run, either: - remove executor_progress.json (single), and/or
- remove hier_progress.json (hierarchical), or
- choose a new workspace.

---

Example: run the provided YAML

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml \
  --planning-mode single

You’ll see messages like:

[checkpoint] saved step snapshot: executor_checkpoint_1.db
[checkpoint] saved step snapshot: executor_checkpoint_2.db
...

Now resume from after step 4:

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml \
  --workspace pi_multiple_ways_<your-workspace> \
  --resume-from executor_checkpoint_4.db

Or try hierarchical mode:

python examples/two_agent_examples/plan_execute/plan_execute_from_yaml.py \
  --config examples/two_agent_examples/plan_execute/pi_multiple_ways.yaml \
  --planning-mode hierarchical

You’ll see sub-step snapshots like executor_checkpoint_3_2.db.

---

Tips for clusters / headless

• Use --interactive-timeout 0 so prompts immediately pick defaults.
• Always pass --workspace so outputs land where you expect.
• Use --resume-from to pin the exact snapshot to restore (no prompt).

---

Troubleshooting

• “All steps already executed” (single):
  You’re at the end per executor_progress.json. To re-run, delete it or resume from an earlier snapshot (e.g., --resume-from executor_checkpoint_2.db).

• “Top-level plan changed — resetting . . .” (hierarchical):
  The plan hash changed; progress resets for safety.

• Mode mismatch warning:
  The workspace is locked to the first-run mode. Use a new --workspace to change modes.

---

Happy checkpointing & resuming!