Checkpoints
Per-turn workspace snapshots in their own git ref namespace — find the turn that broke it, and restore to before it did.
An agent worked for forty turns and something broke on the way. Checkpoints are how you find out which turn did it, and how you get back to before it happened.
What gets recorded
Foreman commits the state of your workspace at each turn. You can see what any individual turn changed, and restore the workspace to how it looked at any recorded point.
Where they're stored
Checkpoints live in their own git ref namespace — refs/foreman/checkpoints/<session>/<turn> — not on your branches and not in your commit history. git log doesn't show them, git branch doesn't list them, and pushing doesn't carry them.
Commits are made with Foreman's own identity ([email protected]), passed explicitly on every invocation rather than read from your git config. That is deliberate: a repo where the user hasn't set user.email would otherwise fail with "unable to auto-detect email address", and a checkpoint must never be the thing that depends on your git setup being tidy.
Restoring
Restore workspace takes your files back to the selected checkpoint. Foreman first checks what would change and shows you, so restoring is never a leap.
Restoring is about the workspace. Your branches and commits are untouched — this is not git reset, and it will not rewrite history you care about.
A rewind is not itself recorded until a turn runs after it. If you restore and then immediately restore again expecting a checkpoint of the intermediate state, it isn't there. Run a turn to establish the new state before treating it as a point you can come back to.
Per-turn changes
Alongside the checkpoint list, each turn shows what it changed. This is the part that answers "which turn broke it" without reading forty turns of transcript — you scan the diffs, not the prose.
Turn zero is the baseline: the state of the workspace when the session started, so the first turn's changes are measured against something real rather than against nothing.
What it doesn't cover
- Files outside the repository. Checkpoints are git objects; something written to
/tmpor your home directory is not in them. - Anything the agent did that isn't a file change. A pushed branch, a sent request, a created PR — restoring the workspace does not undo those.
- Unbounded history. Checkpoints are pruned over time. They're a working-session safety net, not an archive.
Checkpoints versus fan-out
Both are ways of not being stuck with one attempt, but they answer different questions:
- Fan-out explores several approaches at once, when you don't know which is right. Decide by comparing.
- Checkpoints undo one approach that went wrong, when you thought you knew. Decide by reverting.
Use fan-out when the uncertainty is up front, checkpoints when it shows up halfway through.