How it works
A checkpoint records enough state to reconstruct a known-good moment before the agent changes anything irreversible. In a harness, the capture is not an afterthought — it is a step in the control loop that wraps every mutating action:
- Detect a mutation. The harness recognizes that the next tool call writes files, edits a database, or calls an external API with side effects.
- Capture state. It snapshots the relevant scope — a commit, a copy-on-write filesystem layer, a serialized task and memory state, or a transaction boundary — and records a reference to it.
- Execute the action. The agent performs the write.
- Verify. A check runs: tests, a diff review, a schema validation, or a human approval.
- Keep or restore. If the verification passes, the checkpoint becomes history. If it fails, the harness restores to the checkpoint and the mutation is undone.
The scope of a checkpoint matters more than its existence. A snapshot that captures the working tree but not an external side effect gives false confidence: you can restore the files but not the row you inserted or the message you sent. Good checkpoints are cheap enough to take often and scoped tightly enough that restoring one does not throw away unrelated good work.
Why it matters in an agent harness
Agents are stochastic and take long, branching trajectories. Without checkpoints, a single bad tool call can leave the system in a half-mutated state with no clean way back, and the only recovery is manual forensics. Checkpoints convert that open-ended risk into a bounded one.
Concretely, they buy you three things. First, reversibility: any mutating step becomes provisionally reversible, which is what lets you grant an agent write access without accepting write-and-pray. Second, blast-radius containment: when a step fails verification, damage is confined to the delta since the last checkpoint, not the whole run. Third, autonomy headroom: because a mistake is recoverable, the harness can let the agent proceed further without a human in the loop, then verify and restore in batches instead of gating every action.
Checkpoints are also the substrate for retries. A loop that can restore to a prior state can re-attempt a failed step from clean ground instead of compounding a broken one. Frequent, well-scoped checkpoints are the difference between an agent that degrades gracefully and one that corrupts itself.
Checkpoint vs rollback
The two are constantly conflated, but they are different objects, and the distinction changes how you design recovery.
| Checkpoint | Rollback | |
|---|---|---|
| What it is | A saved state (a noun) | An action that restores state (a verb) |
| When it happens | Before a mutation | After a failure is detected |
| Cost model | Paid on the happy path, every step | Paid only when something goes wrong |
| What it needs | A capturable, well-scoped state boundary | A valid checkpoint to return to |
A rollback is only ever as good as the checkpoint it targets. If you invest in rollback machinery but checkpoint rarely or too coarsely, you can restore — just not to a useful point. Design the capture first.
The Rifty take
We treat every mutating action as provisional until it is verified, and a checkpoint is the price of that stance. We accept the cost of capturing state on the happy path — most checkpoints are thrown away — because that cost is what makes autonomy safe to grant. The boundary we enforce is simple: no irreversible mutation without a restore point that actually covers its side effects. Cheap, frequent, tightly-scoped checkpoints beat clever recovery every time.
Common failure modes
- Scope gaps. The checkpoint covers files but not the external side effect (an email sent, a payment made), so a rollback restores an inconsistent world.
- Too coarse. One checkpoint per run means restoring discards hours of good work along with the bad step.
- Too expensive to take often. If capture is slow, the harness skips it under pressure — exactly when you need it.
- Unverified restore. Rolling back to a checkpoint that was itself corrupt just resets to a different broken state.
- No retention discipline. Checkpoints accumulate without pruning, or the one you need has already been garbage-collected.
- Silent capture failure. The harness believes a checkpoint exists; the write never landed, and the gap surfaces only during recovery.
Frequently asked questions
What is a checkpoint in an agent harness?
A checkpoint is a saved snapshot of an agent's state captured just before a mutating action, so the harness has a known-good point to restore to if the change fails verification. It turns an otherwise irreversible step into a provisionally reversible one and bounds the blast radius of mistakes.
How is a checkpoint different from a rollback?
A checkpoint is the saved state; a rollback is the action of restoring to it. Checkpoints are captured before a mutation, on the happy path; rollbacks run only after a failure. A rollback is only as useful as the checkpoint it targets, so design the capture scope first.
When should the harness take a checkpoint?
Take a checkpoint immediately before any action with irreversible side effects — file writes, database mutations, or external API calls that change state. Frequent, tightly-scoped checkpoints are better than rare coarse ones, because they let you restore a single bad step without discarding unrelated good work.
What state should a checkpoint capture?
Capture enough to reconstruct the moment before the mutation and to reverse its side effects — working tree or files, task and memory context, and any external effect that a filesystem snapshot alone won't undo. Scope gaps, where the snapshot misses a side effect, are the most common source of inconsistent recovery.
Do checkpoints let an agent run more autonomously?
Yes. Because a checkpoint makes a mutating step recoverable, the harness can let the agent proceed without a human gating every action, then verify and restore in batches. Reversibility is what makes it safe to grant write access, so checkpoints directly expand how much autonomy you can responsibly allow.