Recover a failed agent task: what to keep and what to check
When an agent run fails, the runtime keeps its own session state and Paperclip keeps the task, the owner and the record. Here's what to check before anyone tries again.
The runtime keeps its session state; Paperclip keeps the task, the owner and the record, so a human can pick the work back up. When a run fails, work out which of those you still have before anyone presses Retry. Check four things in order: whether anything is still running, what the runtime saved, which outputs someone has actually opened, and what the next run will be given.
A failed run usually leaves a mix: some useful work, a half-written answer, maybe a command whose result nobody saw. Starting over throws away the useful part. Retrying blindly can repeat the part that already happened. The fix is to look at each kind of state on its own.
Four kinds of state, and where each one lives
Scroll horizontally to see all columns
| State | What it holds | Who keeps it | What to check after a failure |
|---|---|---|---|
| Model context | Instructions, sources and the question in front of the model | Put together fresh for each run | What the next run will actually be given |
| Runtime session | The conversation and any saved execution state | The runtime, such as Claude Code or Codex | Whether this runtime saved a session you can resume |
| Work products | Drafts, diffs, test output, documents | Wherever you saved them | Location, version and whether anyone has checked them |
| Task record | Goal, owner, status, comments and decisions | Paperclip | Who owns the recovery and what they’re allowed to do |
These link to each other. A task can point to a document, and a comment can name a run. A link doesn’t make one system responsible for keeping the others. Paperclip doesn’t hold your runtime’s checkpoints, and a runtime session doesn’t know who owns the task.
Model context: brief the next run, don’t replay the last one
Treat model context as the brief, not the record of what happened. A model may have been told an action was planned. That doesn’t mean the action ran.
Before the next attempt, write a short brief on the task:
- [goal]: what the task still needs to produce.
- [limits]: sources, access and approvals that still apply.
- [checked progress]: work someone has opened and confirmed, with links.
- [open questions]: what you still don’t know, including outcomes nobody has confirmed.
A fresh run starts from that brief and the task, not from the old conversation. Anything that lives only in the old transcript is gone for that run.
Runtime session: check what this runtime can resume
Each runtime saves its own session, and runtimes differ. Some can reopen the same conversation. Others start fresh when the session or working directory has changed. Check your adapter’s reference for the version you run. For Codex, the adapter reference covers how sessions work on each runner.
If the session can’t be resumed, plan the next run from the task record and the saved work. Say what has to be rebuilt. The task record gives the next run a starting point, but it doesn’t turn a lost session into a checkpoint.
Work products: open them before you reuse them
Save outputs where the next agent and the reviewer can reach them: the task’s documents, the branch, the shared folder. For a research task that might be a source list and a draft. For a code change, a diff and test output.
After a failure, open the work. Is it complete enough for the next step? Do its links and dependencies still resolve? Is it the version you think it is? A filename or a “done” comment isn’t the same as reading the contents.
Sort what you find into three piles:
- Usable: checked and good to build on.
- Partial: usable, with named gaps.
- Unknown: the agent asked for something outside Paperclip, and nobody has confirmed the result.
The third pile matters most. A timeout doesn’t prove nothing changed. Before repeating a push, a send or a deploy, look at the system it touches.
Task record: what Paperclip keeps, and what it does on its own
Paperclip keeps the task: its owner, status, comments, documents and linked subtasks. That record survives the run that failed, which is why recovery starts there.
Paperclip also steps in on a few documented cases:
- A run ends without a next step. Paperclip wakes the same agent once to set a status. If that doesn’t work, the task waits for a person.
- Assigned work has no live run. Paperclip records a recovery action on the task, keeps the original assignee and retries only when that’s safe.
- Retries run out. The task moves to
blockedwith a notice explaining why, often titled No live execution path. The recovery action belongs to the board, so a person decides what happens next.
None of that reassigns the work or decides whether the output is right. The stuck-heartbeat guide explains these notices and what to do with each one.
Work through one recovery
For example, let’s say you are a team lead trying to get a weekly research brief out, but the agent stopped partway and you can’t tell whether the draft is ready for review. Work through it in this order.
1. Make sure nothing is still running
Open the task and its latest run. Is the agent stopped, still working or waiting on a decision? An old timestamp alone isn’t proof the run is dead. Don’t start a second agent on the same work until you know.
2. List what you actually have
Fill in [session available: yes / no], [draft location and version] and [last checked step]. Open the draft and its sources. If you can’t confirm a step, write it down as unknown instead of counting it as done.
3. Assign the smallest next step
Give [next step] to [agent], with [review criteria] and [who approves]. If only the source check is left, assign the source check, not the whole brief again. Put the brief from the model-context section in the task so the agent starts from facts.
If the runtime has its own resume or release step, follow its documentation. Don’t clear the owner, delete saved state or repeat an outside action just to make a blocked badge go away.
4. Review before you call it recovered
Check the new output against [review criteria]. On the task, note what you reused, what was redone and what’s still open. If sending or publishing comes next, that needs its own approval and its own check of the result.
A good second run doesn’t explain why the first one failed. Keep the run link and the notice on the task, so whoever looks next can find the cause.
Common questions
Will retrying a failed run pick up where it stopped?
Only if the runtime saved a session it can resume and nothing it depends on has changed, such as the working directory. Otherwise the next run starts from the task and the brief you write for it.
Does Paperclip undo what a failed run did?
No. Paperclip keeps the task record and flags runs that stopped without a next step. It doesn’t roll back changes the agent made in other systems, so check those before you retry.
Set up the recovery packet before the next failure
Pick one task that would be expensive to redo. Before it runs again, make sure it has:
- A link to where its outputs are saved, and who can open them.
- A named owner for recovery decisions.
- A note on what its runtime can and can’t resume.
When something breaks, that packet turns a guessing game into a short checklist. The next agent knows what to reuse, the reviewer knows what to check, and the person accountable can decide how to continue. To set up the owner and the review step, see how to assign and review agent work. For how the runtime, framework and Paperclip split the job, see the layer guide. For patterns for planning the work before a run, see AI agent orchestration patterns.