Checkpoints that never touch your branch

“Undo for agents” sounds simple: save the files before the agent runs, put them back if you don’t like the result. In practice there are three traps, and we fell into each of them before getting it right.

#Trap 1: using the user’s Git state

The quickest way to snapshot a working copy is git stash or a commit on the current branch. Both change things the user cares about: the stash list, the branch history, the index. A checkpoint tool that rewrites your index while you’re mid-commit is worse than no tool.

Our approach: checkpoints are commits that no branch points to. They live under a private ref, refs/panescale/checkpoints/<id>, which keeps them safe from garbage collection and out of your git log. To build them we use a temporary index file, so the real index is never read or written. HEAD doesn’t move. Your branches don’t move. Nothing is pushed.

#Trap 2: “almost” the same bytes

Git is helpful with text: it normalizes line endings and runs filters on the way in and out. For a checkpoint, helpful is wrong. If a file had CRLF line endings before the agent ran, it must have CRLF after a rewind — byte for byte.

Our approach: files are hashed into the checkpoint without filters, so the stored blob is exactly what was on disk. On rewind, every restored file is read back and compared with what was intended.

#Trap 3: overwriting the human

This is the important one. An agent finishes a step at 14:05. At 14:07 you fix a typo in one of the files it touched. At 14:10 you decide the agent’s step was a mistake and rewind it.

A naive rewind restores every file from the 14:05 checkpoint and silently deletes your typo fix. You wouldn’t notice until much later.

Our approach: rewinding is refusing. Before writing a file back, PaneScale checks that the file on disk is still exactly what the step left behind. If it isn’t — because you or anyone else changed it since — that file is not restored. The result tells you so: “kept: edited after this step.” Everything else is restored, so you get a partial rewind rather than an all-or-nothing failure.

Redo follows the same rules in reverse.

#When checkpoints are taken

PaneScale takes a checkpoint whenever it is about to change your workspace on your behalf:

• before a turn in Agent mode or Chat that may edit files,
• before a card on the tasks board runs,
• before applying an autopilot result,
• before applying a Point & Fix change.

Interactive terminal panes are different: you are driving, and the agent is a tool in your hands. For those, isolation through a lane is the safety net — nothing reaches your branch until you merge.

#Cost

Checkpoints are ordinary Git objects. Unchanged files are shared with every other commit, so a checkpoint only costs what actually changed. Git’s housekeeping keeps the rest compact.

Details are in the Undo & checkpoints docs.