Checkpoints
What the worker saves in .agent-orchestration/, how checkpoints reach the control plane, and how recovery uses them.
The worker keeps a task's state in .agent-orchestration/ in the project folder:
| Content | Purpose |
|---|---|
| Task state and metadata | What the worker is doing and why |
| Checkpoints | Where to continue after a crash, restart or context reset |
Progress (progress/<task>.json) | What the agent reports: steps done, changed files |
| Plans and reviews | .plan.json and .review.json for plan and review tasks |
| Verification results and logs | For the report and remediation |
The folder is added to the project's .git/info/exclude, so it is never committed. Checkpoints are also sent to
the control plane as CheckpointCreated events.
How recovery uses them
- Crash or restart: the agent restarts with backoff and resumes its session where supported; otherwise a fresh session starts from the checkpoint.
- Context exhausted: a fresh session starts from the checkpoint — resuming would bring back the full context.
- Lost worker: another worker continues the requeued task from the checkpoint the control plane holds.
- Retry after
RECOVERY_REQUIREDcontinues from the checkpoint; Restart fresh ignores it.