v-resume

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 is Engine-A-owned: it does not rely on Workflows (whose resume is same-session-only and fails the crash case). The reconcile + re-dispatch logic below is the authoritative procedure defined in skills/compound-v/state-machine.md.

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). 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). 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) — via Engine A (compound-v:parallel-dispatcher / the backend-launcher), 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.

   • A Codex worktree job's resume-vs-recreate decision is governed by the resume-eligibility rule below — reproduced verbatim so it agrees word-for-word with parallel-dispatcher.md and kills the old contradiction (this step once said "may use codex exec resume" unconditionally, while the dispatcher's invariant recreates the worktree fresh at HEAD). Either way — resumed session or fresh recreate — the scope gate re-runs on return.
   • Update each job's status and write state.json after every transition.

Both inputs the rule needs live in state.json jobs[<id>] — session_id (the captured UUID) and failure_class — written there by the dispatcher on the job's return (Step 2 already reads state.json; you do not need to open results/<id>.json for this). A job with an empty session_id has no session to resume ⇒ recreate fresh regardless.