| name | workflow-recovery |
| description | Recover a failed or interrupted workflow-mcp run so it resumes from its active repair rather than starting over. Use before calling workflow_run with action recover, whenever a run shows stage error or interrupted, or when deciding between recovering a run, launching a fresh one, and deferring it. Covers the evidence to gather first, the three permitted outcomes, the judgement cases, and the files that must never be edited. |
Recovering a workflow run
A recovery is not a relaunch, and the difference is expensive to get wrong. A
relaunch throws away the run's state and starts again; a recovery resumes the
existing run from its active repair, preserving the worktree and the work already
done. Choosing the wrong one either destroys progress or resumes a run that can
never succeed.
Recovery is also the explicit ownership-transfer path. A replacement Pi session
may recover a terminal failed run launched by an earlier session; the replay is
then stamped to the recovering session. This does not permit cross-session
control of running or completed work.
Read this before calling workflow_run with action recover.
1. Gather evidence first
Never act on the stage alone. Before touching a failed run, collect:
- Every log source, not just the first one that looks relevant.
- Process state — is anything still alive from the original run?
- The exact staged
run.json for the run.
- Only the repair referenced by
activeRepairId. Other repairs in the
directory belong to earlier cycles and are not yours to act on.
Use workflow_run with action recovery-evidence for the terminal run.json
and durable changelog.md, context.md, and progress evidence. This dedicated
action is terminal-only and read-only, including for failures from an earlier
session; it never scrapes that session's live launcher. Generic status and
tail remain limited to runs owned by this session.
2. Choose exactly one outcome
Every failed run resolves to one of three, and never two in the same pass:
| Outcome | When |
|---|
| Recover the existing run | The recorded target is still valid and the failure was transient or an interruption |
| Launch fresh | The run cannot resume, or the branch has diverged far enough that resuming is meaningless |
| Defer | A named prerequisite is materially unresolved |
Recovery and a fresh launch each consume one launch from the pass budget.
3. Judgement cases
interrupted with a valid failed job — the strong recovery case.failed with a valid failed job — recoverable when the failure was transient
and the recorded target remains valid.- Empty failed job — cannot be recovered. Launch fresh if the work is ready,
otherwise defer.
- Terminal repair-triage run — must never be recovered. Launch fresh once the
work is ready again.
- Stale branch — prefer a fresh launch once the branch has diverged enough
that resuming would rebase onto unrecognisable history.
- No job id — the run was launched by hand and is outside dispatch. Report
it; do not recover it.
- Blocked — never recover or launch a run whose job sits in a blocked column.
A human resolves the blocker first.
4. Hard constraints
- Never edit
issue.md or repair.json. They are the record of what went
wrong; editing them destroys the evidence and the repair chain.
- Never manufacture a recovery target. If the recorded target is invalid,
that is a fresh-launch case, not a reason to invent one.
- Prepare
run.json only when verified recovery state requires it.
- Preserve the active repair and the existing worktree identity.
- Treat an “already claimed” result as another recovery winning the race; do
not launch fresh or retry around the claim.
- Do not use
--dry-run for a real recovery.
5. Verify before reporting
Recover through the launcher recorded for the run. Then confirm real process
and registry progress. A workflow_run action recover call that returns is
not a recovery that succeeded. After ownership has transferred and the replacement run is visible to this
session, check workflow_run with action status before reporting an outcome.
Say what you recovered, what you skipped and why, and anything still blocked.
