How it works
Reversibility is engineered, not hoped for. You get it by controlling how an agent's actions reach the world and by keeping enough state to walk them back. The usual mechanisms:
- Capture before mutate. Snapshot or checkpoint the affected state before the agent writes, so there is a known-good point to return to.
- Stage, then commit. Route changes through a reversible medium first — a branch, a draft, a transaction, a shadow copy — so nothing is live until it is approved.
- Record an inverse. For each action, keep the information needed to undo it: the prior value, a compensating action, or a diff you can revert.
- Bound the blast radius. Scope permissions and side effects so a single step can only touch what a single step should touch.
Under the hood, most reversible harnesses are just this loop: checkpoint, act inside a container, surface the diff, and only then promote it. The undo path is a first-class feature, exercised on every run, not a disaster-recovery script no one has tested. If the undo path only exists on paper, the system is not reversible — it is optimistic.
Why it matters in an agent harness
Agents are non-deterministic. The same prompt and state can produce different trajectories, and some fraction of those trajectories are wrong in ways you did not anticipate. Reversibility is how you make that acceptable. It converts an irreversible mistake into a cheap, observable one.
Concretely, it buys you four things. Control: you can let the agent act without pre-approving every step, because a bad step is recoverable rather than terminal. Observability with teeth: a diff you can revert is a diff you actually read, since the review has a consequence attached. Failure containment: when a run goes sideways, you roll back to a checkpoint instead of forensically reconstructing what changed. Higher autonomy at constant risk: reversibility is the property that lets you widen the agent's authority without widening the downside.
The deeper point: reversibility is what keeps autonomous work legible over time. Without it, every agent action is a small permanent commitment, and the system drifts into a state no one chose and no one can explain. With it, the operator's judgment stays in the loop even when the operator is not.
Reversibility vs idempotency
Engineers conflate these constantly, and it causes real bugs. They are different guarantees, and a harness usually needs both.
| Reversibility | Idempotency | |
|---|---|---|
| Question it answers | Can I undo this? | Is it safe to run again? |
| Direction | Backward — return to a prior state | Forward — repeat without extra effect |
| Failure it addresses | The action was wrong | The action was retried or duplicated |
| Typical mechanism | Checkpoint, inverse, revert | Dedup key, upsert, stable identifier |
An idempotent write is safe to retry but may be impossible to take back. A reversible write can be undone but might double-apply if you retry it naively. Design each action knowing which property you are relying on.
The Rifty take
We treat reversibility as the load-bearing property of a harness, ahead of speed and ahead of raw autonomy. The tradeoff we accept is deliberate friction: staging, snapshots, and diffs cost latency and storage, and we pay it on every run rather than only when something breaks. The boundary we enforce is simple — an action the operator cannot inspect and undo does not get to run unattended. Autonomy is something you earn by making the downside recoverable, not something you assert.
Common failure modes
- Undo that was never exercised. A rollback path that only runs in emergencies is untested code; run it on the happy path too.
- Reversible core, irreversible edges. The database rolls back, but the emails, payments, and webhooks it triggered do not. Track external side effects explicitly.
- Checkpoints without retention. You can revert, but the snapshot you need was already garbage-collected.
- Confusing retry-safe with undo-safe. Idempotency is not reversibility; know which one each action actually has.
- Silent partial rollback. An undo that half-completes leaves state more corrupt than the failure did. Make rollback atomic or make its partial states safe.
- Reversibility that no human ever sees. If the diff is never surfaced for review, you have the mechanism but not the control it was meant to provide.
Frequently asked questions
What is reversibility in an agent harness?
Reversibility is the harness property that lets an operator inspect and cleanly undo an agent's action. You engineer it with checkpoints, staged changes, and recorded inverses, so a wrong autonomous step becomes a cheap, recoverable event instead of a permanent commitment to unwind by hand.
How is reversibility different from idempotency?
Reversibility answers whether you can undo an action; idempotency answers whether it is safe to run again. Reversibility moves state backward to a prior point, while idempotency lets a forward action repeat without extra effect. A harness usually needs both, chosen per action.
Does reversibility limit how autonomous an agent can be?
It does the opposite. Reversibility is what lets you widen an agent's authority without widening the downside, because a bad step rolls back instead of sticking. You earn autonomy by making actions recoverable, so the operator can stop pre-approving every step.
What makes an action effectively irreversible?
Side effects that leave the harness: sent emails, charged payments, fired webhooks, or third-party writes with no compensating action. Also expired checkpoints, non-atomic rollbacks, and untested undo paths. If an action touches the outside world without a recorded inverse, treat it as irreversible and gate it.
How do you actually implement reversibility?
Snapshot state before mutating, route changes through a reversible medium like a branch or draft, record the inverse or diff for each action, and bound the blast radius with scoped permissions. Then exercise the undo path on every run, not only during incidents, so it stays real.