---
name: "long-running-task-checkpointer"
description: "Persist JSON agent state with atomic checkpoints and explicit recovery limits. Use when the user needs: Get a working checkpoint helper and recovery fixtures."
metadata: {"version": "2026-10-17.1", "category": "agents-workflows", "publisher": "AIDiveForge"}
---

# Long-Running Task Checkpointer

Get a working checkpoint helper and recovery fixtures.

## Requirements

Python 3.10+ is required. The included helper uses only the standard library.

## Workflow

1. Use scripts/checkpoints.py to save JSON state after a completed logical step; include the last completed operation identifier.
2. The helper writes a checksum-protected envelope to a temporary file and atomically publishes a numbered checkpoint.
3. On recovery, load the newest valid checkpoint; inspect reported invalid files and any operation whose completion is uncertain.
4. Reconcile uncertain external side effects before retrying them. A state snapshot does not make a payment, email or tool call exactly once.
5. Run the supplied save/load example before integrating the helper into a real agent loop.

## Worked example

Read `examples/input.txt` and `examples/expected.txt` before adapting the workflow.

## Acceptance checks

The round trip preserves state and step ID; incomplete/corrupt newer files cannot displace a valid checkpoint.

## Limits

The helper does not capture an agent automatically or guarantee exactly-once external actions. JSON state must omit secrets you do not want persisted.

Worked example included. Model-specific performance and vendor compatibility have not been benchmarked.