/v-resume

description: Resume an interrupted Compound V orchestrator run by run-id. Reconciles state.json against git reality (git-wins tie-break) and re-dispatches only the incomplete jobs (pending/failed/blocked), then continues collect → integration gate → review → merge.

You are about to **resume** the Compound V orchestrator run `{{args}}` after an interruption or crash. Resume is **idempotent** — resuming a fully-`MERGED` run is a no-op.

Resume belongs to the **verification layer**, not to any engine. It deliberately does not rely on the native runtime's resume, which is **same-session-only** and, past a failure point, **re-runs completed agents** — a 16-job run whose job 3 failed would re-run jobs 4–16 that already succeeded, paying full cost twice. The reconcile + re-dispatch logic below is the authoritative procedure defined in [`skills/compound-v/state-machine.md`](../skills/compound-v/state-machine.md).

> **This contract must read a PRE-CUTOVER `state.json`, and that is a hard requirement, not a courtesy.** The 3.0 run that ships Engine C is itself dispatched on the pre-cutover path: its `state.json` carries `worktree: null`, no `baseline`, no `merged`, and its run dir has no `lane-map.json`, no `receipts/` and no `results/`. The session can die *after* the Engine C job merges while later waves still have to finish on the old engine. So every field Engine C adds is **OPTIONAL on read**: a job missing `baseline` reconciles the way it always did (git-wins against the recorded pre-dispatch commit, or the worktree HEAD with that weakness stated), a missing `lane-map.json` is not an error, and a missing receipt is **re-derived** by the integration gate rather than treated as a failure. Never refuse to resume a run because it predates a field.

Resolving the plugin root

The `scripts/` this command calls ship with the plugin — they are not files in your own repository. Resolve the plugin root once per session before calling any of them:

CV="${CLAUDE_PLUGIN_ROOT:-$(ls -d "$HOME"/.claude/plugins/cache/*/superpowers-v/*/ 2>/dev/null | sort -V | tail -1)}"
CV="${CV:-$PWD}"; CV="${CV%/}"

`CLAUDE_PLUGIN_ROOT` is set for hooks but is not set in this Bash environment, so treat it as a hint, never the whole answer — the fallback line covers an installed plugin cache or a checkout of this repo.

Steps

1. **Locate the run.** If `{{args}}` is empty, list the subdirectories of `docs/superpowers/execution/` and ask which run to resume. The run dir is `docs/superpowers/execution/<run-id>/`. If it does not exist, stop and say so.

2. **Read** `state.json` and `manifest.yaml` from the run dir. If `phase` is already `MERGED`, report nothing to do and stop.

3. **Reconcile against git reality (git-wins).** For each job, derive what actually landed using the same git signal the scope gate uses:

• `git -C <worktree-or-repo> diff --name-only HEAD` ∪ `git -C <worktree-or-repo> ls-files --others --exclude-standard`.
• When `state.json` and git disagree, **git wins**:
• `done` in `state.json` but the job's `write_allowed` files are **not** in git → reclassify as not-done, re-dispatch.
• `pending`/`running` in `state.json` but the files **are** fully present and within scope → reclassify as `done`, skip.

4. **Reconcile the circuit breaker (neither a silent retry nor a permanent lockout).** `circuit_open` is an **object per backend** — `{ "<backend>": { "open": bool, "reason": "out_of_credits|auth", "opened_at": "<iso-ts>", "cleared_by": null } }` (see [`state-machine.md`](../skills/compound-v/state-machine.md)). For each entry, decide whether to keep it open or clear it **before** any re-dispatch:

• **`reason == "out_of_credits"`** → keep the breaker **OPEN** unless the user confirms a credit top-up, **or** a cheap liveness probe — a tiny "reply ok" call to that backend — returns success. Only then set `cleared_by` (`"top_up"` or `"probe"`) and re-dispatch that backend's `failed` jobs. The run-level `total_retries` budget persists across the resume.
• **`reason == "auth"`** → keep the breaker **OPEN** until the user re-authenticates (point them at [`/v:init`](v-init.md)). Only after re-auth set `cleared_by: "reauth"` and re-dispatch its `failed` jobs.
• **Cooldown-only (no open breaker)** → a backend whose `cooldowns[backend]` timestamp has merely **expired** is **half-opened**: probe it **once** before full re-dispatch. A clean probe clears the cooldown; a repeat failure re-cools it via the policy.
• **Never silently re-dispatch to a still-open breaker.** If neither the top-up/probe (credits) nor the re-auth (auth) has happened, leave the breaker open, leave its jobs `failed`, and report exactly what the user must do to unblock — do not retry behind their back.
• Update `circuit_open[backend].cleared_by` and write `state.json` for every breaker transition.

5. **Re-dispatch only the incomplete jobs** — those that are `pending`, `failed`, or `blocked` after steps 3–4 (and **not** behind a still-open breaker) — honoring `depends_on`, `run`, and `max_parallel` exactly as the original dispatch. Each re-dispatch replays the captured prompt at `jobs/<id>.prompt.md` verbatim.

• **Re-dispatch on the engine the run can actually reach now, not the one it started on.** Probe as [`/v:dispatch`](v-dispatch.md) step 4 does. On a successful probe, **first run `python3 "$CV/scripts/compound-v-emit-workflow.py" resume-prepare --run-dir docs/superpowers/execution/<run-id>`** — it clears the crashed attempt's baseline pin for every job that has not integrated — except a codex job whose `failure_class` is environmental (`timeout`|`network`), whose `session_id` is recorded and whose worktree still exists: that one is left intact for `codex exec resume` per the eligibility rule below — (the relaunch branches a fresh worktree from the current HEAD, and a pin from the crashed attempt charges the job with every commit landed since — proven BLOCKED on 2026-09-03, finding 146),