Documentation
Recovery semantics
What a restart does, what on-chain recovery does, and what neither can do.
Runtime resume
On start, restoreOrInitialize verifies the newest checkpoint on the canonical lineage:
- Locator, manifest and artifact digests match the on-chain commitments.
- The manifest belongs to this agent and its parent matches the chain.
- The artifact decrypts under the expected binding, and state and context hashes match.
- Every action in the manifest and the journal is reconciled: confirmed, definitively failed, or compensated.
Only then does it restore the state. An interrupted execution resumes; a completed one starts a new execution. Confirmed actions return their recorded results instead of running again.
Outcomes
| Status | Meaning |
|---|---|
RESTORED | State restored and every action resolved |
HALTED_FOR_REVIEW | An action's outcome is unknown; a person must look before anything else runs |
FAILED | The checkpoint did not verify (integrity, availability, lineage, identity or schema); nothing resumes |
With the recoveryLogFile option, each recovery is appended to a log with its ID, target and result.
Partial execution
When a run failed after some external effects completed, partialEffects decides: keep (default; the resumed workflow reuses their results), compensate (your handlers run, and the compensation is recorded), or halt for review.
On-chain recovery
Separately, the owner and guardians can propose a recovery that moves the workflow's head back to an ancestor checkpoint and rotates executor keys, after the approvals, timelock and windows of the workflow's policy. See the specification.
Limits
- A finalized transaction cannot be reversed. Recovery restores the agent's state and reconciles or compensates its effects.
- Replaying a prompt does not reproduce model output; recovery resumes from recorded results.
- The recovery lock is per process; two processes for the same agent are not coordinated yet.