Checkpoints and restore

What a checkpoint is, when AutoDev makes one, how to list them and rewind to one, and what a restore does and does not undo.

What a checkpoint is #

A checkpoint is a git commit that AutoDev makes in your repository, on the branch you are on. Its subject is autodev: <label>. Its author is autodev <autodev@localhost>, so it works in a repository with no user.name set, and it skips commit hooks.

A checkpoint holds everything except .autodev/. A restore exists to rewind the code, and rewinding memory.md with it would erase what the run learned on the way.

Each checkpoint also has an entry in checkpoints.json, kept on the machine with the rest of the run's state. The entry has an id such as c1 or c2, the full commit, a label, a kind and a time. The list below reads from that file.

Checkpoints need a git repository. In a folder that is not one, AutoDev writes Not a git repository; checkpoints/rollback disabled (git init to enable recovery snapshots) and goes on without them. The checkpoints key turns them off, and it is on by default. Every config key describes it.

When one is made #

There are three kinds:

• baseline: when a run starts, if the working tree has changes that are not committed, AutoDev commits them as autodev: baseline before run. A clean tree gets no baseline.
• task: when a participant's work_done is credited. If the changes are not committed, AutoDev commits them as autodev: thread — <first line of the post>. If the participant already committed, that commit is the checkpoint. A turn that an approved gate started is recorded the same way.
• pre-restore: a restore records the work it replaced, so that the restore itself can be undone.

One more case makes a commit and a branch, and it is not a checkpoint. When work fails after an approved irreversible action, AutoDev parks the tree on a branch named autodev/parked-<time> and does not rewind it, since the tree may show an action that cannot be undone. The run halts as error.

Listing them #

autodev restore with no id lists the checkpoints, newest first:

✔ <label>   <task> · <sha> · <mode> · <age>

The mark at the start of the line is ─ for a baseline, ✔ for a task and ⤿ for a pre-restore. <task> is — for a checkpoint that belongs to no task, which is every one a thread makes today. The line of the checkpoint the repository is on ends with ← HEAD. With checkpoints off, the list says so instead.

In the panel, the Restore button shows the same list. Clicking a line rewinds to it, and the click is the confirmation. The result appears as Restored to "<label>", or as Restore: <reason> when it failed.

Rewinding #

autodev restore <id> rewinds the code to that checkpoint, in this order:

1. If the tree has changes that are not committed, AutoDev commits them and puts them on a branch named autodev/pre-restore-<time>. A clean tree is reset directly.
2. It runs git reset --hard to the checkpoint's commit.
3. It adds a pre-restore entry for the work it parked, so the list can undo the restore.
4. It sets the status to idle and clears the current task.
5. It appends a RESTORE: line to memory.md, so the next turn knows the code went back.

It prints Restored to "<label>" (<7 characters of the commit>); saved on <branch>., and leaves the branch out when the tree was clean. A wrong id prints Restore failed: unknown checkpoint: <id>. If git cannot park the work or reset, nothing is rewound, and the work you had stays where it was.

What it does not do #

• It refuses while a daemon is running: Stop the run before restoring — restore resets the project tree. The panel's Restore is disabled with only while the run is stopped, and so is New run. When a stopped run has checkpoints, Needs you says <n> restore point(s) — rewind now that the run is stopped.
• It rewinds git and nothing else. It does not rewind thread.jsonl, events.jsonl, the sessions or memory.md. The thread keeps every post, including the ones about work that no longer exists, and memory.md gains a line. A participant that reads both sees the code before the restore and the account of what happened after it.
• It cannot undo what happened outside the repository. An irreversible action that a gate approved stays done.
• If checkpoints.json is lost, the list is empty, and the commits are still in git under their autodev: subjects. Nothing about the run is lost with it.

Every CLI command describes autodev restore. What survives a restart covers the other files, and Where state lives lists them.