Checkpoints
A checkpoint makes a bench’s committed work durable on the remote.
bench checkpoint fix-loginIt pushes the existing HEAD to the task branch (HEAD:refs/heads/<branch>, where <branch> is
bench/<key> unless --branch named another at creation) with no force option, then reads the remote branch back with ls-remote and fails unless it is exactly the
checkpointed commit.
What it guarantees
Section titled “What it guarantees”- It never makes a commit. Commit with git as usual; a checkpoint publishes what is already
committed. There is no implicit
git add. - It never force-pushes.
- A dirty or untracked tree is refused. Untracked files block checkpoint and release; ignored build files do not.
- A rejected push fails the checkpoint and keeps the lease, and release stays blocked.
- Release requires it.
bench releaseneeds a clean worktree, the current HEAD checkpointed, and the remote still matching.
The repository’s tests cover a dirty or untracked tree being refused, a wrong token being refused, release requiring a checkpoint, a fresh host recovering the same commit from the remote branch, and a remote that rejects the push. The remote match itself is enforced in code; no test forces a mismatch, so that refusal is read from source rather than exercised.
What it does not guarantee
Section titled “What it does not guarantee”- The guarantee is about the pushed commit, not the remote’s other branches.
- Git and state updates are not one transaction. If saving local state fails after the push, the checkpoint may need retrying.
- Ignored files are not part of a checkpoint, so they do not recover.
Recovery from a checkpoint
Section titled “Recovery from a checkpoint”On a replacement host with empty state and data directories:
bench recover --repo /absolute/path/to/remote.git --branch bench/fix-login fix-loginOnly remote-confirmed committed files recover. The implementation does not rebuild a lost checkout in an existing state store or reset a conflicting local branch. Keep the old files and state intact, stop old writers, and use a separate replacement state and data pair.
Workspace checkpoints
Section titled “Workspace checkpoints”A workspace checkpoints its whole member vector as one generation. Each member’s task branch is pushed without force and confirmed, then pinned with a lightweight tag:
refs/tags/superbench/pins/<bench_id>/<generation_id>/<member>After every task branch and pin is confirmed, a commit whose tree holds only a generated
checkpoint.json seals the generation on a metadata branch:
refs/heads/superbench/checkpoints/<bench_id>Only a normal fast-forward push with exact remote confirmation completes the seal. This is a completion boundary across remotes, not an atomic cross-repository push: earlier members’ pushes stay in place after a later failure, and the generation stays incomplete. Pins are never overwritten or deleted. Control pushes skip local pre-push hooks, which could otherwise start unfenced writers; server receive hooks still apply.