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.

Benches and workspaces

wet paint: New or experimental.Open as Markdown

A bench is one task’s git worktree, identified by a key (letters, digits, _ and -, up to 80 characters, starting with a letter or digit). It lives under the data directory at benches/<key> and works on a task branch, bench/<key> unless --branch names another, cut from a base branch (main by default).

Benches share git objects through a bare mirror per repository. A fetch updates only remote-tracking refs, never a branch another bench has checked out. Do not prune mirrors or alter their refs by hand.

bench create records a durable creation intent (task, repository, branch, target path and the pinned source commit) and syncs it before the worktree is made. If create stops after making the worktree but before registering it, repeat the command with exactly the same arguments: the retry adopts only the exact clean checkout the intent describes. Dirty, changed or conflicting checkouts are preserved for review, never reset.

Creation and recovery also prepare the checkout before they report it ready (see Supervised runs and setup). create-cold and recover-cold are local administrative commands that register without setup; they are never a fallback from a failed warm create.

A bench moves through create, lease, work, checkpoint, release, and in the end archive and reap:

  1. create (or recover) registers and prepares the checkout.
  2. lease grants it to one holder. See Leases.
  3. The holder commits as usual. run executes one supervised command instead, on Linux.
  4. checkpoint pushes the existing HEAD and confirms it. See Checkpoints.
  5. release frees the bench for the next holder.
  6. archive freezes a released, clean, confirmed bench read-only; plan-reap and reap delete it after review. See Archive and reap.

status is read-only at every step and never migrates state.

A workspace is a bench that spans several repositories: 1 to 32 members, each with a logical name, its repository, and optionally a branch and base. One member is the checkpoint repository. The whole workspace has one lease, one total quota allocation and one checkpoint vector across every member.

Workspaces are reached through the v2 API and bench workspace OP; the scalar top-level commands keep their single-repository behavior, and v2 mutations refuse scalar records. A member list is a JSON array:

[
{"name":"app","repository":"/absolute/path/to/app.git"},
{"name":"library","repository":"/absolute/path/to/library.git"}
]
Terminal window
bench workspace create --socket /run/superbench/api.sock \
--repositories members.json --checkpoint-repository app \
--request-id create-task-1 task-1
bench workspace run --socket /run/superbench/api.sock \
--holder run-1 --repository-name app --request-id run-task-1 \
task-1 -- go test ./...
bench workspace status --socket /run/superbench/api.sock task-1

Workspace creation and recovery always initialize every member and confirm a first checkpoint (the genesis) on the remote before reporting ready. Recovery creates a fresh workspace with distinct task refs from an exact historical seal. Moving original task refs to a new workspace is a separate reviewed transfer.

The grouped request and response shapes are proposed contract data. They are implemented and tested here, but no suite consumer uses them yet.