Skip to content
Not released yet. SuperBench is an experimental single-host prototype under active development. Nothing is released or supported for use yet. These docs describe themain branch and will be refreshed at the first release.

Checkpoints

wet paint: New or experimental.Open as Markdown

A checkpoint makes a bench’s committed work durable on the remote.

Terminal window
bench checkpoint fix-login

It 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.

  • 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 release needs 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.

  • 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.

On a replacement host with empty state and data directories:

Terminal window
bench recover --repo /absolute/path/to/remote.git --branch bench/fix-login fix-login

Only 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.

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.