Agent crash recovery starts before the crash. Put the work definition, discoveries, status, and dependencies outside the agent session; then a replacement agent can query the same graph and resume from recorded state.
Beads gives that state a durable home, so the job can outlive the worker. Hidden reasoning and code that never reached disk remain outside the recovery boundary.
10:02 — the agent claims the work
An agent begins bd-7f3a, “Add request signing to webhook delivery.” The bead already contains the acceptance criteria, relevant files, and a blocking relationship: end-to-end delivery tests cannot begin until signing is implemented.
The agent claims the bead. That single operation moves it to in_progress and prevents another agent from claiming the same work.
The claim also grants a five-minute node-local lease. A live worker refreshes it with bd heartbeat; a dead worker stops refreshing it.
At this point the durable record answers:
- who has the job;
- what “done” means;
- what the job blocks;
- which larger feature contains it.
The conversation contains far more detail, but these are the facts that keep coordination intact.
10:19 — implementation reveals another bug
While tracing webhook retries, the agent finds that a failed delivery can reuse an expired token. The signing work does not require a full retry redesign, so the agent creates a separate bug bead and connects it with discovered-from.
It also adds an implementation note to the current bead: canonicalize the request body before computing the signature, because proxies may preserve bytes while changing presentation.
Now the work graph carries two facts that source files leave implicit:
- why the retry bug exists in the backlog;
- which implementation decision the next agent must preserve.
10:27 — the session dies
The terminal closes before the agent can finish. Its uncompressed chain of thought is gone. Any unsaved shell output is gone. If it had uncommitted edits on disk, those files may still exist, but Beads makes no promise to reconstruct them.
The durable record remains:
bd-7f3ais in progress;- the acceptance criteria and note are attached;
- the test bead is blocked;
- the retry bug is recorded with provenance;
- Dolt history contains the work-state changes.
The lease itself is ephemeral: heartbeats do not create Dolt commits or history. This is the recovery boundary. Ephemeral session context disappears above it. Recorded work state survives below it.
10:31 — a replacement starts clean
A new agent session loads the project’s Beads instructions and runs the normal orientation flow. bd prime provides the operating workflow and project memory. The agent inspects in-progress work, opens bd-7f3a, and checks its graph.
The replacement does not steal a live lease. After the old worker stops heartbeating, the five-minute lease expires. Once the configured grace period has also elapsed, bd reclaim clears the abandoned assignee, returns the bead to open, and records the recovery event. The default grace is ten minutes after expiry; an operator can change it with --older-than.
Only after reclaim can a replacement take ownership. It can then make a controlled choice:
- inspect the changed files and commits before touching code;
- claim the reopened bead and continue it in a valid workspace;
- assign it to another worker instead;
- keep the test bead blocked until signing is actually complete.
The replacement can reason from explicit state. The previous model’s exact words are incidental.
Compaction is a smaller crash
Context compaction usually looks graceful: the host summarizes the conversation and the agent keeps working. Operationally, it creates the same risk. Fine-grained decisions and discoveries can vanish while the session remains open.
Beads integrations refresh workflow context around the host’s lifecycle where reinjection is supported. Hooks bring the workflow back. The work graph brings the job back. The agent-recognition guide covers each host’s setup surface.
That pairing is stronger than relying on a summary to preserve every consequential detail. The summary can stay concise because decisions, status, and connected work have stable records elsewhere.
Terminal closure and agent replacement are the ordinary case
“Crash recovery” sounds like preparation for rare infrastructure failure. Coding agents lose continuity in much more mundane ways:
- a user closes the terminal;
- a remote session disconnects;
- an agent reaches its context limit;
- a model is changed mid-feature;
- a rate limit moves work to another account or provider;
- a developer asks a second agent to take over.
All of these replace a worker while the job remains. Durable work makes the replacement boring.
The durable-memory guide describes what to externalize. The short version is: record any fact that changes what a competent replacement should do.
Machine handoff adds synchronization
On one machine, the next session reads the same local Dolt database. Moving to another machine requires moving the work state too.
Beads supports Dolt remotes for push and pull. After the first machine syncs its work database, the second can retrieve the same beads and history. Remote replicas transfer state asynchronously; they are not one live claim store. Claim leases stay on the replica that granted them, and bd reclaim normally runs there. A shared Dolt server is the concurrent multi-writer option.
The sync concepts guide explains the model and its boundaries.
Put each kind of state in its durable home
Crash recovery works when each record has a clear home:
| State | Durable home |
|---|---|
| Code and committed changes | Git |
| Decisions, discoveries, status, and connected work | Beads |
| Session commands and conversation detail | CLI transcript |
| Saved terminal output | Project logs or artifacts |
| Secrets and transient credentials | The team’s secret store |
Beads carries the durable work graph that tells the next agent what exists, what happened to the job, and what can move now. The other systems preserve the material needed to continue the implementation safely.
Database corruption and backup restoration are a separate topic. The Beads documentation has dedicated recovery runbooks for storage failures. This page is about recovery from the far more common loss of an agent session.
Prepare one job now
You can test the recovery path without staging a failure:
- Put a real task in Beads with enough description for a new agent.
- Add one blocking relationship.
- Record one implementation note or discovered bead.
- End the session.
- Start another agent and ask it to recover the work from Beads.
If the second agent can explain the state and choose the next action without the transcript, the durable layer is doing its job.
Beads upgrades agent memory by letting the work continue after the worker disappears.
Set up Beads before the next crash.
Related articles
- Beads: Read the complete product and crash-survival story.
- Durable memory for coding agents: Decide which facts must leave the session before failure.
- Why coding agents need a work graph: Understand the relationships the replacement agent recovers.
- Test coding-agent recognition of Beads: See how project setup restores workflow context in a clean session.