This is the full developer documentation for SuperBench
# SuperBench
> Pre-release docs for SuperBench, an experimental single-host prototype. One task, one git worktree on a host, kept warm between holders and checkpointed to the remote. Not released yet.
SuperBench docswet paint: New or experimental.
## One task, one bench.
A bench is one task's git worktree on one host, kept warm between holders. SuperBench creates it, leases it to one holder at a time, and will not let it go until the work is committed, pushed and confirmed on the remote. It is an experimental prototype for trusted repositories, and it is not released yet.
[What SuperBench is →](/start/what-it-is/)[Status](/start/status/)[superbench.dev ↗](https://superbench.dev)
### Work with an agent
```
I'm reading about SuperBench, which is not released yet. Read https://docs.superbench.dev/llms.txt to see what its pre-release docs cover, and https://docs.superbench.dev/llms-full.txt for every page in one file.
Then explain what a bench is and what its leases do and do not protect against.
Name the docs page each answer comes from, and tell me when the docs do not cover something.
```
Copy prompt
### Quick start
There is no supported installation yet, and nothing here is meant for use outside development. Start with [Status](/start/status/), which lists what works on `main`, what is partial and what is not built.
### A bench's life (step through it; it waits for you)
1Create2Lease3Checkpoint4Release
1\. Createfix-login
2\. Leasefirst-agent
3\. CheckpointHEAD on remote
4\. Releasesecond-agent
**1. Create.** bench create registers a git worktree for the task from a shared mirror, on its own task branch (bench/\ by default), and prepares it. On a managed Linux host it also gets its own byte and inode caps.
**2. Lease.** bench lease hands the bench to one holder and prints a lease token once. Other bench acquisitions are refused while it is held. The lease is cooperative: it does not stop direct edits or other processes running as the same user, and it never expires on its own.
**3. Checkpoint.** The holder commits as usual. bench checkpoint pushes the existing HEAD to the task branch without force and confirms the remote has exactly that commit. It never makes a commit; a dirty or untracked tree is refused.
**4. Release.** bench release needs a clean worktree whose HEAD is checkpointed and still on the remote. Then the next holder can lease the same warm checkout.
← BackStep 1 of 4Next →
### Find your way
Copy Markdown
## What these docs are
[Section titled “What these docs are”](#what-these-docs-are)
These are pre-release docs. They describe what the source on the `main` branch does, and they are written from the repository’s own README, its `docs/` folder, the `bench` and `benchd` help and the API code. Where the repository says something is partial or unverified, so do these pages. They will be refreshed at the first release.
🖌
Wet paint
SuperBench is an experimental single-host prototype for trusted repositories. Leases are cooperative, nothing in it isolates untrusted code, and there is no supported installation. [Status](/start/status/) lists what is done, what is partial and what is not built.
For agents, the same docs are plain text: [`/llms.txt`](/llms.txt) indexes them, and [`/llms-full.txt`](/llms-full.txt) is every page in one file.
# Errors
> The closed set of error codes the local API returns, the HTTP status each comes with, and what to do about each one.
A failed response has `"ok": false` and an `error` object with a `code` from the closed set below and a human-readable `message` of at most 256 bytes. Each code comes with a fixed set of HTTP statuses; a client that sees any other pairing should treat the response as invalid. This table is checked against `internal/protocolv2` when the docs build.
| Code | HTTP status | Meaning | What to do |
| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `invalid_request` | 400, 405, 413, 415 | The request was malformed: not POST, not JSON, too large, an unknown or missing field, a bad value. | Fix the request. Nothing ran. |
| `forbidden` | 403 | The caller’s uid is not an operator (or a reader, for read-only operations), or the lease token is missing, wrong or no longer current (“valid holder capability required”). | Use an authorized account; for a token, check `status` and use the current holder’s token. |
| `not_found` | 404 | Unknown endpoint, or no such bench or workspace. | Check the path and key. |
| `conflict` | 409 | The current state refuses the operation, or a request ID was reused with a different body. | Read `status`; reuse an ID only with its original body. |
| `in_progress` | 409 | The same request is still running. | Wait, then retry with the same ID and body. |
| `operation_in_doubt` | 409, 503 | The daemon cannot tell whether an earlier attempt took effect, for example after a restart. It is never run again automatically. | Reconcile by hand: inspect status, stop the recorded execution, checkpoint and release. A new ID is not reconciliation. |
| `unavailable` | 503 | The service is shutting down, at its connection or active-operation limit, its receipt budget is exhausted, a complete result would not fit, or the operation was cancelled or hit a deadline such as the mirror timeout. | Inspect `status` and the retained state first; then retry with the same request ID, or query one key. |
| `operation_failed` | 422 | The operation ran and failed, for example a nonzero command exit or a refused checkpoint. A retained grant may come with it. | Inspect the retained workspace state. |
| `capacity_exhausted` | 422 | A fixed quota reservation cannot fit. The v2 refusal reports the needed and total byte and inode budgets. Only `/v2/operations` returns it. | Free capacity or request less. Limits are never raised to fit. |
When the receipt store is full, new growth operations are refused, but `stop`, `checkpoint`, `release` and `archive` stay available so work can always be reconciled.
## The CLI
[Section titled “The CLI”](#the-cli)
The `bench` CLI prints the response envelope and exits nonzero on an error. For `run`, a nonzero command exit status propagates through the CLI once fencing completed. Without `--socket`, direct local commands print the engine’s own JSON and report errors on stderr as `bench: `.
# v2 operations
> Every superbench.v2 operation on POST /v2/operations, its required and optional fields, and the response envelope, as internal/protocolv2 defines them.
Every v2 request is one JSON object posted to `/v2/operations` with `"version": "superbench.v2"` and an `operation`. The fields each operation requires and accepts are fixed; any other field is refused. These tables are checked against `internal/protocolv2` when the docs build.
```json
{
"version": "superbench.v2",
"operation": "lease",
"key": "task-1",
"holder": "run-1",
"request_id": "lease-task-1"
}
```
## Operations
[Section titled “Operations”](#operations)
Besides `version` and `operation`:
| Operation | Required | Optional | What it does |
| ------------- | -------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `create` | `key`, `repositories`, `checkpoint_repository`, `initialize`, `request_id` | `quota_bytes` | Create a workspace from its member vector, prepare every member and confirm its genesis checkpoint. |
| `recover` | `key`, `repositories`, `source`, `initialize`, `request_id` | `quota_bytes` | Rebuild a fresh workspace with distinct task refs from an exact historical seal. |
| `status` | (none) | `key` | Read one workspace, or the whole inventory. Read-only. |
| `host_status` | (none) | (none) | Read the host’s storage and admission state. Read-only. |
| `lease` | `key`, `holder`, `request_id` | (none) | Grant the workspace to one holder and prepare it. |
| `run` | `key`, `holder`, `arguments`, `request_id` | `checkpoint`, `repository_name`, `lease_token` | Run one supervised command in a member or the workspace root. |
| `setup` | `key`, `holder`, `request_id` | `offline`, `repository_name`, `lease_token` | Prepare one member, or every member. |
| `checkpoint` | `key`, `lease_token` | (none) | Checkpoint the complete member vector. |
| `release` | `key`, `lease_token` | (none) | Release the workspace after a complete checkpoint. |
| `stop` | `key`, `lease_token` | (none) | Fence the holder’s supervised execution. |
| `stop_admin` | `key` | (none) | Operator stop without the holder’s token; returns the retained capability only after fencing succeeds. |
| `archive` | `key` | (none) | Freeze the whole workspace read-only. Never approves deletion. |
`create`, `recover`, `lease`, `run` and `setup` are growth operations: they need a `request_id` and get durable receipts. `status` and `host_status` are open to readers; everything else needs an operator. See [The local API](/api/overview/).
## Fields
[Section titled “Fields”](#fields)
| Field | Shape |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | Letters, digits, `_` and `-`, starting with a letter or digit, at most 80 characters. |
| `repositories` | 1 to 32 objects: `name` (lowercase letters, digits, `_` and `-`, starting with a letter or digit, at most 64 characters), `repository`, and optional `branch` and `base`. |
| `checkpoint_repository` | The `name` of one member. |
| `source` | For `recover`: `repository`, `bench_id`, `commit` and `manifest_sha256` of the seal to rebuild from. |
| `initialize` | Must be `true`; warm initialization is mandatory. |
| `holder` | Letters, digits and `_ . : / -`, starting with a letter or digit, at most 200 characters. |
| `lease_token` | The holder’s token: 32 or 48 lowercase hex characters. |
| `arguments` | 1 to 128 strings, each at most 8192 bytes; the first is not empty. |
| `checkpoint` | For `run`: omitted or `true` checkpoints and releases after success; `false` keeps the lease. |
| `repository_name` | The member to run or set up. Omitted, `run` uses the workspace root and `setup` prepares every member. |
| `offline` | For `setup`: offline frozen setup. |
| `quota_bytes` | One total workspace budget, within host policy: 1024 to 2^50 bytes, a multiple of 1024. |
## The response envelope
[Section titled “The response envelope”](#the-response-envelope)
```json
{
"version": "superbench.v2",
"operation": "lease",
"request_id": "lease-task-1",
"ok": true,
"result": { "workspace": { "key": "task-1", "phase": "ready" }, "grant": { "lease_token": "…" } }
}
```
A failed response has `"ok": false` and an `error` with a `code` and a `message` of at most 256 bytes; see [Errors](/api/errors/). Results are closed shapes:
* **Mutation**: the `workspace` (key, bench ID, phase, member count, checkpoint repository, `ready_for_acquisition`, quota bytes and inodes, and when present the lease summary, the latest checkpoint, a pending generation, the recovery source and the archive record), an optional `grant` with a `lease_token`, and an optional `root_path`. A workspace’s `phase` is one of `materializing`, `initializing`, `prepared`, `ready`, `archived`, `reaping` or `reaped`; while it is being initialized, its lease holder is `initialization`.
* **Run outcome**: a mutation plus the `execution` (ID and a phase of `starting`, `running` or `stopped`), `exit_code` and `log_truncated`.
* **Setup outcome**: a run outcome plus a `preparation` status for each member.
Responses omit repository URLs, private member paths, command arguments and environment, raw manifests, continuation secrets and history. Status never discloses lease tokens. An outgoing original-ref transfer adds an optional `transfer_state` of `relinquishing` or `transferred`.
## v1
[Section titled “v1”](#v1)
The scalar API on `/v1/operations` (`"version": "superbench.v1"`) has the same operations for a single-repository bench, with `repository`, `branch` and `base` in place of the member vector, and no `archive`. `initialize: true` on `create` and `recover` asks for warm creation; the current CLI always sends it, and an older service rejects the unknown field rather than registering cold.
# The local API
> benchd serves JSON over one host-local Unix socket, authorized by kernel peer credentials, with durable request receipts. No TCP listener.
`benchd` owns one host-local Unix socket and one private state store, and serves the same operations as the `bench` CLI over HTTP on that socket. The `bench` CLI is its only implemented client: pass `--socket` to any operation. There is no TCP listener (read from the source; no test asserts it, see the [Security model](/start/security-model/)). Never expose the socket through a TCP proxy.
The request and response shapes are **proposed** contract data, pinned from the suite’s contract repository. They are implemented and tested here; no suite product consumes them yet, and a shared response schema and published SDK for v1 are still pending.
## Endpoints
[Section titled “Endpoints”](#endpoints)
| Method | Path | What it is |
| ------ | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `GET` | `/healthz` | A health check, open to any authorized peer (operator or reader). Returns the service name and API version. |
| `POST` | `/v1/operations` | Scalar (single-repository) operations, version `superbench.v1`. |
| `POST` | `/v2/operations` | Grouped workspace operations, version `superbench.v2`. See [v2 operations](/api/operations/). |
Operation requests are `POST` with `Content-Type: application/json`; the health check is a `GET`. Three further v2 extensions exist in source but are proposed and **disabled** in the public `Serve` entry point: cancellation (an `operation` of `cancel` on `/v2/operations`), `POST /v2/receipts/lookup` for historical receipt evidence, and `POST /v2/registrations/observe`. No request can turn them on.
## Who may call
[Section titled “Who may call”](#who-may-call)
The daemon reads the caller’s uid from the kernel (`SO_PEERCRED` on Linux, `LOCAL_PEERCRED` on macOS); supplied identity headers grant nothing.
* **Operators** (`--operator-uids`, by default the daemon’s uid and root) may run every operation. They are trusted to execute arbitrary commands as the daemon user.
* **Readers** (`--reader-uids`) may run `status` and `host_status` only.
* Anyone else gets `forbidden`.
The uid lists do not grant filesystem access by themselves: the socket is mode 0660 and its parent must not be group- or world-writable, so arrange a trusted local group. Lease tokens are holder capabilities, separate from the caller’s uid.
## Request IDs and receipts
[Section titled “Request IDs and receipts”](#request-ids-and-receipts)
Growth operations (`create`, `recover`, `lease`, `run`, `setup`) require a `request_id`. The CLI generates one and prints it to stderr when `--request-id` is omitted; save it before issuing work whose reply might be lost.
* Retry with the **same ID and the same body**. The same ID with a different body is a `conflict`.
* IDs and responses are scoped to the authenticated uid.
* A completed reply is cached durably and replayed exactly, including a historical lease token. A replayed token does not restore an ended lease; use `status` for the current state.
* A retry while the operation is still running gets `in_progress`. A disconnected client does not cancel the work.
* After a daemon restart, unfinished receipts become `operation_in_doubt` and are **never run again automatically**. Inspect status, stop the recorded execution if needed, checkpoint and release with the retained capability. Changing the ID is not reconciliation.
Checkpoint, release and stop do not create growth receipts, so a full receipt store never blocks reconciliation. Receipts are not collected; do not delete them to retry uncertain work.
## Shutdown
[Section titled “Shutdown”](#shutdown)
SIGTERM cancels supervised runs, which fence before keeping their lease for inspection. SIGKILL can leave descendants alive; restart and `stop --admin` recover them from the durable execution scope. HTTP shutdown has a ten-second grace period, which does not release ownership of an unfinished operation. No timeout proves that a writer stopped.
## Bounds
[Section titled “Bounds”](#bounds)
Requests are at most 64 KiB. Every v1 response is at most 1 MiB; on v2, read-only responses are at most 1 MiB and durable growth responses at most 64 KiB. Unknown fields, duplicate keys, null optional values, trailing documents and invalid UTF-8 are refused. At most 64 concurrent connections, and 8 active operations by default (`--max-active`, 1 to 64). An overlarge status fails; query one key. There is no pagination.
# Archive and reap
> A released, clean, remote-confirmed bench can be frozen read-only, and deleted only after a grace period and a person's approval of the exact file manifest.
Archive and reap are how a finished bench leaves the host. They are **local administrative commands, reviewed by a person**; neither is a socket operation for single-repository benches, and neither takes a lease over by time.
## Archive
[Section titled “Archive”](#archive)
Stop or reconcile any supervised execution, commit, checkpoint and release first. Then:
```sh
bench archive --state /absolute/state --data /absolute/data task
```
Archive checks the original mirror and branch, a clean tracked and untracked state, HEAD equal to the saved checkpoint, and the same commit still on the remote task branch. It then makes the bench unavailable to new leases and runs, keeps every file (ignored build output included), and removes write permission from regular files and directories after saving a durable permission intent. An archived key cannot be reused; recover the branch under a new key to resume work.
The read-only boundary is cooperative: ordinary writes are refused, but the trusted owner can `chmod` the tree, root can bypass mode bits, and already-open writable handles are not revoked.
## The grace period
[Section titled “The grace period”](#the-grace-period)
The first archive records `ArchivedAt` and `ReapAfter`. The default grace is seven days; `--archive-grace` on that first archive can choose 0 to 365 days, and `0s` explicitly waives the delay. Repeating archive never changes a recorded deadline, and no reap flag overrides it. An early reap is refused before anything is written or removed.
## Review, then reap
[Section titled “Review, then reap”](#review-then-reap)
Generate the plan without changing the checkout:
```sh
umask 077
bench plan-reap --state /absolute/state --data /absolute/data task > /private/plan.json
```
Read every `Tree.Entries` path, especially those marked `Recoverable: false`: ignored artifacts, nested repository contents and anything else outside the commit are lost on approval. Then approve the exact digest of that concrete plan:
```sh
bench reap --state /absolute/state --data /absolute/data \
--plan /private/plan.json --approve FULL_REVIEWED_DIGEST task
```
The engine checks the whole current snapshot still matches the plan, syncs an approval journal outside bench data, and commits its intent before deleting anything. New, replaced, edited or special files stop deletion and stay for review. Reap refuses effective uid zero: run it as the non-root service owner. It never pushes unknown files, auto-commits, or deletes the branch.
After an interruption, retry with the same plan and digest; only unchanged remaining approved entries are removed. A completed reap keeps a tombstone, and repeating it is idempotent.
## Quota retirement
[Section titled “Quota retirement”](#quota-retirement)
On managed XFS hosts, the worker removes the approved contents and the fixed root helper removes only the empty bench directory, after checking its allocation ID and filesystem and confirming that both blocks and inodes are zero. Open but unlinked files keep the reservation until they close. Retired project IDs and keys stay retired. This applies only on managed Linux hosts.
## Automatic archive and retention
[Section titled “Automatic archive and retention”](#automatic-archive-and-retention)
A repository can opt into automatic read-only archive after a verified unmerged-to-merged checkpoint transition (`[archive]` in `.bench/config.toml`, see [Repository settings](/reference/repository-settings/)). Deletion still waits for a reviewed reap plan after the grace period.
Run logs, receipts and journals live outside the deleted checkout. Reviewed log collection exists (`plan-collect`, `collect`), and the daemon can run an automatic log retention policy, which stays **off until an operator reviews and enables it** (`retention-preview`, `retention-enable`). Collection of shared caches, mirrors and request receipts is not built.
# Benches and workspaces
> A bench is one task's git worktree on one host. A workspace is a bench across several repositories, with one lease and one checkpoint vector.
## A bench
[Section titled “A bench”](#a-bench)
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/` and works on a task branch, `bench/` 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](/concepts/supervised-runs/)). `create-cold` and `recover-cold` are local administrative commands that register without setup; they are never a fallback from a failed warm create.
## Lifecycle
[Section titled “Lifecycle”](#lifecycle)
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](/concepts/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](/concepts/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](/concepts/archive-and-reap/).
`status` is read-only at every step and never migrates state.
## A workspace
[Section titled “A workspace”](#a-workspace)
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:
```json
[
{"name":"app","repository":"/absolute/path/to/app.git"},
{"name":"library","repository":"/absolute/path/to/library.git"}
]
```
```sh
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.
# Checkpoints
> A checkpoint pushes the bench's existing HEAD without force and confirms the remote has exactly that commit. Release and recovery depend on it.
A **checkpoint** makes a bench’s committed work durable on the remote.
```sh
bench checkpoint fix-login
```
It pushes the existing HEAD to the task branch (`HEAD:refs/heads/`, where `` is `bench/` 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”](#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 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.
## What it does not guarantee
[Section titled “What it does not guarantee”](#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”](#recovery-from-a-checkpoint)
On a replacement host with empty state and data directories:
```sh
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.
## Workspace checkpoints
[Section titled “Workspace checkpoints”](#workspace-checkpoints)
A [workspace](/concepts/benches-and-workspaces/) 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:
```text
refs/tags/superbench/pins///
```
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:
```text
refs/heads/superbench/checkpoints/
```
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.
# Fresh allocations and recovery
> Fresh payload materialization is disabled. What exists today is direct-root inspection of retained bootstrap evidence and retirement of an absent Fresh allocation.
A **Fresh allocation** is the storage a future payload-user bench would be bootstrapped into, using a fresh registered layout rather than the shared service-account one. **Fresh payload materialization remains disabled.** It stays disabled until interrupted or cancelled Fresh allocations have an operator release or reconciliation path, because a failed one-shot bootstrap can leave an allocation behind without a committed project ID.
What exists today is maintenance for that case, run by a **direct root operator** on Linux, through the quota helper. None of it is reachable through sudo, the daemon or the API.
## Inspecting retained bootstrap evidence
[Section titled “Inspecting retained bootstrap evidence”](#inspecting-retained-bootstrap-evidence)
```sh
bench-quota inspect-bootstrap-payload \
KEY OPERATION_ID EPOCH STATE_IDENTITY AUTHORITY BINARY_SHA256 < original-spec.json
```
It takes the exact original helper identity and the original canonical bootstrap specification on standard input, and reports the retained intent: its phase, recorded allocation, node identities and command metadata, bound to the specification by SHA-256 digests. It refuses sudo callers, policy overrides, unknown identities and missing, partial or foreign intent records. The original installed policy, registry, allocation authority and helper binary must still match; do not reinstall an old binary to get past a refusal.
Inspection releases nothing, repairs nothing and authorizes no retry. Its output is recorded metadata, not a current filesystem inventory or a quota check: a `completed` phase reports retained intent, not a revalidated tree.
## Retiring an absent allocation
[Section titled “Retiring an absent allocation”](#retiring-an-absent-allocation)
`bench-quota plan-retire-bootstrap` (same identity arguments, original specification on standard input) returns a `RetirementPlan`. It needs the original operation to be permanently denied, and the installed service to be stopped and persistently masked with no daemon, payload or helper processes left. The commands check those conditions; they do not stop, mask or configure anything.
After reviewing the whole plan, submit `Spec` and `Plan` as JSON to `bench-quota retire-bootstrap`. Retirement holds the operation lock, rechecks the denial, the retained provenance and the controller authority, and saves the exact reviewed plan as a root-owned 0600 file at `LEDGER/payload-retirements/KEY.json` before changing any reservation. A retry must match it exactly.
Only an **absent** fixed leaf, with XFS independently reporting zero blocks and zero inodes, can be retired. The key, project ID and Fresh marker stay retired forever; only the reservation drops to zero. No pathname is deleted and no kernel quota is changed. A refusal can happen after the plan is saved, so an error does not mean no effects occurred: keep the plan and retry it.
## Not built
[Section titled “Not built”](#not-built)
* Cleanup of nonempty Fresh allocations.
* Recovery when the original evidence is missing, and never-initialized projects with no quota report.
* The installed maintenance command lifecycle on a booted host. The privileged fixture tests cover the storage layer on disposable XFS; they do not prove that lifecycle.
# Leases
> A lease grants a bench to one holder at a time. Leases are cooperative, they survive restarts, and they never expire on their own.
A **lease** grants a bench to one holder. While it is held, other `bench` acquisitions of that bench are refused.
```sh
bench lease --holder first-agent fix-login
```
The response includes `Lease.Token`, the holder’s capability, and `Path`, the checkout. The token is returned only on acquisition, on an administrative stop (`stop --admin`) or on exact replay of a completed request’s receipt; status and checkpoint output redact it. Keep it in `BENCH_LEASE_TOKEN` rather than passing `--token`, which shows it in process arguments.
## Leases are cooperative
[Section titled “Leases are cooperative”](#leases-are-cooperative)
This is the caveat that travels with every lease claim:
* A lease stops other **`bench` acquisitions**. It does not stop direct edits, an arbitrary shell, or other processes running as the same user.
* There is **no automatic expiry**. A crashed holder’s lease is kept until someone inspects it. Time passing never ends a lease or reassigns a process.
* It covers **one host**. Moving a bench between hosts is a reviewed administrative procedure, not network coordination.
The repository’s tests cover one winner among twelve simultaneous lease requests, a lease that survives a restart, refusal of a wrong or old token, and a second holder finding the first holder’s files. Its recorded handoff shows files moving between holders; it does not show two agent harnesses working.
## Holding, losing and recovering a lease
[Section titled “Holding, losing and recovering a lease”](#holding-losing-and-recovering-a-lease)
* **A process crash keeps the lease.** Stop and inspect the holder before using its saved token to checkpoint or release.
* **A failed checkpoint keeps the lease.** A rejected push, a dirty tree or an ambiguous state save leaves it held.
* **A lost supervised token** is recovered with `bench stop --admin`: a local operator fences the recorded scope and gets the retained lease and token back. Cooperative shell leases still need manual inspection, because nothing fenced them.
* **Releasing twice** can fail after the first release cleared the lease. Check `status` rather than applying an old token to a new holder.
## Repair leases
[Section titled “Repair leases”](#repair-leases)
`bench lease-repair` is a local administrative lease for maintenance. It skips the mirror refresh that ordinary acquisition performs, so it stays available when the remote is not. Ordinary `lease`, `run` and `setup` refresh the shared mirror first and refuse if that fails.
## Leases through the daemon
[Section titled “Leases through the daemon”](#leases-through-the-daemon)
Over the socket, `lease` is a growth operation and needs a request ID. Repeating a completed lease request returns its historical reply, including its token, without changing the current holder. A replayed token does not restore an ended lease; always use `status` to find the current state. See [The local API](/api/overview/).
# Payload identity and the fixed helpers
> The two fixed-policy privileged helpers, bench-quota and bench-payload, and the separate payload user that main does not yet install and activate end to end.
SuperBench’s daemon runs unprivileged. The few things that need root go through two small, **fixed-policy** helpers that take logical requests, never arbitrary paths, limits or commands. On a managed host the only sudo rule permits exactly these two executables.
## bench-quota: the quota helper
[Section titled “bench-quota: the quota helper”](#bench-quota-the-quota-helper)
`bench-quota` (installed as `/usr/local/libexec/bench-quota`) applies and retires XFS project quotas for benches, the shared store and the shared mirrors. It reads the root-owned policy `/etc/superbench/storage.json`; paths, byte and inode ceilings and worker ownership all come from that policy, never from the caller. It uses fixed absolute XFS tools and a fixed environment. A policy override (`--policy`) is accepted only from a direct root caller, never through sudo.
Its retirement authority is narrow: it removes only an empty logical bench directory, after XFS reports zero blocks and zero inodes for that allocation. It never deletes files recursively and is not a tree-deletion interface. See [Quotas, mirrors and stores](/concepts/quotas-and-stores/).
## bench-payload: the payload helper
[Section titled “bench-payload: the payload helper”](#bench-payload-the-payload-helper)
`bench-payload` (installed as `/usr/local/libexec/bench-payload` on managed hosts) is the boundary for running a task’s payload as a separate **payload user**. It is a dedicated helper, never a daemon:
* It must be a **static** Linux executable (built with cgo off); the installer refuses one with a dynamic interpreter or shared-library dependency. On other platforms it refuses with `unsupported`.
* It accepts **no command-line arguments**; sudo permits it only with the explicit empty argument string. It reads one bounded request frame from standard input.
* It validates its fixed policy, the caller, the cgroup scope and the private payload layout, then drops credentials and executes. A credential drop may be irreversible, so on any error it exits rather than retrying or restoring privileges, and it prints only a closed refusal code.
* The payload’s environment is rebuilt, not inherited: a fixed `PATH`, `HOME` and `TMPDIR` from the validated private payload layout, git’s global and system configuration turned off, and only a small allowlist of locale and CI variables. Daemon credentials, loader hooks, shell startup programs and sudo metadata do not pass through.
## What is and is not active on `main`
[Section titled “What is and is not active on main”](#what-is-and-is-not-active-on-main)
This is the caveat that travels with the payload identity: **`main` installs the trusted service-account execution model; it does not yet install and activate the complete separate payload-user path.** The helper, the private payload policy and service registry it requires, the fresh registered layout, and the routing of run, setup and git through it must all land and be verified together before that boundary can be claimed. The packaging checks alone do not prove payload isolation.
Until then, supervised commands run with the launching account’s authority, inside a fenced cgroup. That is the boundary described in [Supervised runs and setup](/concepts/supervised-runs/) and the [Security model](/start/security-model/): lifecycle fencing for trusted commands, with no uid, mount or network isolation per bench.
# Quotas, mirrors and stores
> Per-bench byte and inode caps on managed Linux XFS hosts, shared git mirrors refreshed at acquisition, and shared or checkout-local package caches.
## Quotas, on managed hosts only
[Section titled “Quotas, on managed hosts only”](#quotas-on-managed-hosts-only)
On a **managed** Linux host, each bench gets its own byte and inode hard caps on a dedicated XFS filesystem with enforcing project quotas, and the shared package store and shared mirrors get their own caps. A root-owned policy, `/etc/superbench/storage.json`, sets the ceilings and the reserve.
The caveat that travels with this: **managed hosts only.** Enforcement needs Linux, a dedicated XFS mount provisioned by the operator, root-owned policy and the privileged quota helper. On macOS and unmanaged hosts a quota request is **recorded and not enforced**. The test that exercises real XFS enforcement is skipped unless a disposable managed XFS fixture is present, so the evidence for enforcement is the repository’s recorded drills on loop-backed XFS images, not a host in use. Those recorded runs are historical: at least one names an uncommitted working snapshot of a feature branch, so they are not runs of the current commit.
What managed storage does:
* **Admission.** Create, recover, new leases and supervised runs check free-space reserves on the data and state filesystems before starting work (`--min-data-free`, `--min-state-free`). Managed admission also rechecks quota enforcement through the helper.
* **Fixed-policy allocation.** The helper accepts logical allocations only: `apply bench KEY [BENCH_BYTES]`, `apply shared store`, `apply shared mirrors`, and `release bench KEY PROJECT_ID`. Every allocation is journaled before it touches the filesystem, so a retry after a lost reply reuses its original reservation. Project IDs start at 10000 and are never reassigned.
* **Conservative accounting.** Total bench caps plus the shared caps and the reserve cannot exceed the filesystem, for bytes or inodes, and unfinished allocations still count.
* **Bounded run logs**: per-command output (`--max-log-bytes`), the total retained and reserved log bytes (`--max-logs-bytes`) and the number of logs (`--max-log-files`).
A repository can ask for a smaller bench in `.bench/config.toml` with `[quota] size = "4G"`. The request is read from the immutable source commit at creation, and the root policy’s `BenchBytes` is both the maximum and the default. Changing the request later does not resize a bench: ordinary acquisition refuses the mismatch, while checkpoint, release and repair stay available. See [Repository settings](/reference/repository-settings/).
## Shared mirrors
[Section titled “Shared mirrors”](#shared-mirrors)
Benches start from a shared bare mirror per repository. Ordinary `lease`, `run` and explicit `setup` refresh it before granting ownership or launching task code:
* The refresh first checks the mirror’s physical path, its bare-repository identity and its single registered origin, and that the checkout still shares that mirror and names its task branch.
* The fetch updates and prunes only `refs/remotes/origin/*`, atomically. Local branches, tags, HEAD, the index, dirty and untracked files and ignored output are preserved. It does not pull, merge, rebase or reset a task branch.
* **A failed or cancelled refresh grants no ordinary lease.** A missing or changed mirror is refused, not recloned. `bench lease-repair` stays available because it skips the refresh.
* The deadline is `--mirror-timeout`, two minutes by default.
Partial mirror clones are staged and published atomically; abandoned staging directories are kept under their own reviewed collection (`bench mirror-clones`).
## Shared and checkout-local caches
[Section titled “Shared and checkout-local caches”](#shared-and-checkout-local-caches)
`.bench/config.toml` chooses, per tool, whether a cache is shared across benches or kept inside the checkout:
| Setting | Shared, under data | Checkout-local | Environment |
| ------------ | -------------------------------- | ---------------------------------------------- | ------------------------------------- |
| `pnpm` | `store/pnpm` | `.bench/cache/pnpm` | `npm_config_store_dir`; clone imports |
| `npm` | `store/npm` | `.bench/cache/npm` | `npm_config_cache` |
| `bun` | `store/bun` | `.bench/cache/bun` | `BUN_INSTALL_CACHE_DIR` |
| `playwright` | `store/playwright` | `.bench/cache/playwright` | `PLAYWRIGHT_BROWSERS_PATH` |
| `go` | `store/go-build`, `store/go-mod` | `.bench/cache/go-build`, `.bench/cache/go-mod` | `GOCACHE`, `GOMODCACHE` |
All five default to shared. A repository cannot name an arbitrary cache path. Setup hooks and supervised commands inherit these paths; a shell opened after a cooperative lease does not. Checkout-local caches count against the bench’s cap and should be ignored in `.gitignore` (`.bench/cache/`), or their files will block checkpoint and release.
The shared package store is part of the managed XFS setup above and shares its limits. Collecting old shared caches and mirrors is not built.
# Supervised runs and setup
> On Linux, bench run and bench setup fence a command's whole process tree in a delegated cgroup before checkpoint and release. Fencing, not isolation.
`bench run [flags] KEY -- COMMAND [ARGS]` acquires a lease and runs one noninteractive command in the bench’s checkout, fenced in its own cgroup. `bench setup` runs the repository’s preparation the same way.
```sh
bench run --holder reviewer --checkpoint=false --cgroup-root /delegated/cgroup fix-login -- sh ./verify.sh
```
**Linux only.** The runner needs a writable, delegated cgroup-v2 subtree (`--cgroup-root`), a stable machine identity, `clone3` with `CLONE_INTO_CGROUP`, and `cgroup.kill`. On macOS and unsupported Linux hosts a fenced run refuses before it takes a lease; there is no silent process-group fallback. The CLI does not create a delegation under the system root by itself.
## What a run does
[Section titled “What a run does”](#what-a-run-does)
1. State records a random scope ID, a stable host hash, the boot identity, a starting phase and the holder token, before launch.
2. The command is born inside its scope rather than moved there afterwards. The lease token is removed from its environment. Output goes to a private run log in state storage.
3. Stop marks the execution stopped only after the kernel reports no remaining members in the scope and the empty scope can be removed. Detached `setsid` descendants stay in the cgroup and are fenced too.
4. **On success** the command is fenced, then its existing committed HEAD is checkpointed and the lease released. There is no implicit `git add` or commit. `--checkpoint=false` keeps a stopped lease even on success.
5. **On failure** (a nonzero exit, dirty files, a rejected push, an ambiguous save) the lease stays held for inspection. A nonzero exit status propagates through the CLI once fencing completed.
```sh
bench stop --token "$BENCH_LEASE_TOKEN" fix-login
bench stop --admin fix-login
```
Killing the supervisor does not free the lease; the cgroup stays recorded so another local process can fence the surviving tree. A different host is refused, while a new boot of the same host proves its old processes cannot still be running. Copying state between hosts is not a supported handoff.
## Fencing is not isolation
[Section titled “Fencing is not isolation”](#fencing-is-not-isolation)
This is the caveat that travels with every claim about supervised runs: **it is process-tree fencing, not a sandbox.** No per-bench uid, mount or network isolation is implemented. Commands have the launching user’s authority, so a deliberate cgroup escape by that user is outside the boundary. Only trusted repositories are suitable. A payload run under a separate user is not done; see [Payload identity and the fixed helpers](/concepts/payload-identity/).
## Setup hooks
[Section titled “Setup hooks”](#setup-hooks)
`bench setup` reads `.bench/config.toml` in the checkout:
```toml
[setup]
once = "pnpm install --frozen-lockfile"
each = "pnpm install --offline --frozen-lockfile"
```
The hooks are trusted repository shell code, run as the account running `bench` or `benchd`, with `/bin/sh -e`, each in its own subshell rooted at the checkout. `once` runs on the first successful preparation; later acquisitions skip it only when the exact configuration bytes match a successful receipt for that bench. `each` runs before every handoff. Changing any byte of the configuration, comments included, invalidates the match. Hooks must be idempotent: shell side effects are not an exactly-once transaction.
With no hooks, setup uses a frozen install from exactly one supported pnpm or npm lockfile; a missing or ambiguous lockfile refuses. `--offline` selects offline frozen setup, and for custom hooks exports `BENCH_SETUP_OFFLINE=1`; it does not claim network isolation.
Configured hooks also run before `run` and before a cooperative `lease` is returned, and `create` and `recover` prepare the checkout before reporting it ready. With hooks, `run` prepares in a separate fenced execution, then moves the same lease straight to the command, with no release and reacquire gap. Setup failure, cancellation or a changed configuration leaves the lease held.
## Preparing without Linux
[Section titled “Preparing without Linux”](#preparing-without-linux)
Supervised preparation needs Linux. Whenever the repository has setup hooks or a supported pnpm or npm lockfile, warm `create`, `recover`, `lease` and `setup` prepare the checkout in a fenced execution and so need Linux cgroup delegation; on macOS they refuse rather than fall back. The laptop sequence is:
```sh
bench create-cold --repo /absolute/path/to/remote.git --branch card/example example
bench lease-repair --holder first-writer example
bench prepare-local example
bench acknowledge-local-preparation --digest REVIEWED_DIGEST --acknowledge-stopped-writers example
bench checkpoint example
bench release example
```
On macOS and Linux, `bench prepare-local` runs the same preparation under an explicit cooperative lease, for trusted operators. It does not fence processes or prove that descendants stopped. Review the result, stop every writer yourself, then acknowledge the exact attempt digest with `bench acknowledge-local-preparation --digest REVIEWED_DIGEST --acknowledge-stopped-writers KEY` before checkpoint and release.
# bench CLI
> Every bench command and flag as cmd/bench defines them on main. Flags precede the key; output is JSON.
`bench` is the command-line front door. Every command takes its flags **before** the task key. Output is JSON. With `--socket`, an operation goes to `benchd` and prints the versioned API result; without it, the command works directly on the local state and data directories and prints the engine’s own format. This page is checked against `cmd/bench` when the docs build.
There is no supported installation yet. `bench version` prints `dev` for a build from a branch.
## Bench lifecycle
[Section titled “Bench lifecycle”](#bench-lifecycle)
| Command | What it does |
| ------------ | ----------------------------------------------------------------------------------------------- |
| `create` | Register a task worktree from `--repo` on its task branch and prepare it. |
| `recover` | Rebuild a bench from its remote-confirmed task branch (`--repo`, `--branch`) into empty state. |
| `lease` | Grant the bench to `--holder` and print its token once. Refreshes the shared mirror first. |
| `checkpoint` | Push the existing HEAD without force and confirm the remote has exactly that commit. |
| `release` | Free the bench. Needs a clean, checkpointed, still-confirmed worktree. |
| `status` | Read one bench, or all of them. Read-only; never migrates. |
| `run` | `bench run [flags] KEY -- COMMAND [ARGS]`: lease and run one fenced command (Linux). |
| `stop` | Fence the holder’s supervised execution; `--admin` stops it without the token (local operator). |
| `setup` | Run the repository’s preparation in a fenced execution (Linux). |
## Local administration
[Section titled “Local administration”](#local-administration)
These work on local state only, as the trusted service owner, with the same `--state` and `--data` the daemon uses.
| Command | What it does |
| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `create-cold` | Register a checkout without setup. Never a fallback from a failed `create`. |
| `recover-cold` | Recover without setup. |
| `lease-repair` | A maintenance lease that skips the mirror refresh. |
| `migrate` | Upgrade the state schema explicitly. |
| `configure-host` | Record host storage settings: quota helper, free-space minimums, log budgets. |
| `host-status` | Read host storage and admission state. |
| `archive` | Freeze a released, clean, confirmed bench read-only (`--archive-grace`). |
| `plan-reap` | Print the concrete deletion plan for an archived bench. |
| `reap` | Delete exactly the approved plan (`--plan`, `--approve`) after the grace period. |
| `archive-run` | One sweep of automatic archive candidates (`--limit`, `--after-key`). |
| `history` | Run history for one bench, or all. |
| `inspect-log`, `adopt-log`, `reconcile-log` | Inspect, adopt or reconcile a retained run log. |
| `plan-collect`, `collect`, `resume-collect`, `cancel-collect`, `collections` | Reviewed log collection. |
| `retention-preview`, `retention-enable`, `retention-disable`, `retention-status`, `retention-run`, `retention-ack-pending` | The automatic log retention policy, off until enabled. |
| `prepare-local`, `acknowledge-local-preparation`, `local-preparation-status` | Cooperative preparation without Linux fencing. |
| `handoff` | Reviewed cross-host transfer: `offer`, `inspect-export`, `begin-export`, `continue-export`, `import`, `continue-import`. |
| `mirror-clones` | Reviewed collection of unpublished mirror clones: `inspect`, `collect`, `inspect-root-removal`, `reconcile-root-removal`, `forget`. |
| `workspace` | Grouped workspace operations; see below. |
| `version` | Print the build’s version. |
`--request-id` is accepted only by `create`, `recover`, `lease`, `run` and `setup`, the operations the daemon replays.
## Flags
[Section titled “Flags”](#flags)
The scalar commands share one flag set. Defaults that depend on the OS use Go’s user directories: the config directory for state and the cache directory for data (on Linux `~/.config` and `~/.cache` unless the XDG variables say otherwise; on macOS `~/Library/Application Support` and `~/Library/Caches`).
| Flag | Default | Meaning |
| ------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------- |
| `--state` | `/superbench/state` | Authoritative state, outside bench data. |
| `--data` | `/superbench/data` | Mirrors and checkouts. |
| `--socket` | (none) | Local benchd Unix socket; operation output uses the versioned API shape. |
| `--request-id` | (none) | Stable ID for replaying an accepted service request. |
| `--repo` | (none) | Git remote URL or absolute path. |
| `--branch` | `bench/` | Task branch. |
| `--base` | `main` | Base branch. |
| `--holder` | (none) | Lease holder. |
| `--token` | `$BENCH_LEASE_TOKEN` | Lease token; prefer the environment variable. |
| `--cgroup-root` | `/sys/fs/cgroup/superbench` | Delegated Linux cgroup-v2 root for fenced execution. |
| `--checkpoint` | `true` | Checkpoint and release a successful supervised command. |
| `--admin` | `false` | Local operator: stop a supervised execution without its holder token. |
| `--offline` | `false` | Offline frozen dependency setup. |
| `--mirror-timeout` | `2m0s` | Deadline for mirror clone, validation and fetch; the socket uses the daemon’s setting. |
| `--quota-helper` | `/usr/local/libexec/bench-quota` | Fixed-policy quota helper. |
| `--quota-policy` | (none) | Policy override for direct root testing and administration. |
| `--min-data-free` | `67108864` | Minimum free bytes on the data filesystem. |
| `--min-state-free` | `1048576` | Minimum free bytes on the state filesystem. |
| `--max-log-bytes` | `1048576` | Maximum captured output bytes per command. |
| `--max-logs-bytes` | `67108864` | Maximum retained and reserved run-log bytes. |
| `--max-log-files` | `4096` | Maximum retained run logs before admission stops. |
| `--archive-grace` | `168h0m0s` | Local archive retention before reviewed reap; zero explicitly waives it. |
| `--plan` | (none) | Private reviewed administrative plan JSON. |
| `--approve` | (none) | Exact `Digest` of the reviewed plan. |
| `--limit` | `100` | History and collection result limit. |
| `--after-key` | (none) | Archive sweep cursor from the previous report’s `Next` field. |
| `--older-than` | `168h0m0s` | Minimum time since release and log seal. |
| `--metadata-older-than` | `720h0m0s` | Minimum time since prior log collection. |
| `--max-collect-bytes` | `67108864` | Maximum log bytes per automatic collection cycle. |
| `--enable-automatic` | `false` | Approve future automatic collections under the reviewed policy. |
| `--acknowledge-stopped-writers` | `false` | Operator confirms legacy log writers were stopped. |
## bench workspace
[Section titled “bench workspace”](#bench-workspace)
`bench workspace OP [flags] [key]` runs grouped operations. `--socket` selects the v2 API on the daemon; without it, the command uses local state. The client never retries on its own or falls back to v1.
Operations: `create`, `recover`, `lease`, `setup`, `run`, `checkpoint`, `release`, `stop`, `stop_admin`, `archive`, `status`, `host_status`, `plan-reap`, `reap`, and the reviewed local procedures `inspect-history`, `reconcile-history`, `inspect-initialization`, `claim-initialization`, `continue-initialization`, `inspect-transfer`, `begin-transfer`, `continue-transfer`, `inspect-missing-transfer`, `begin-missing-transfer`, `continue-missing-transfer`, `inspect-root-removal` and `reconcile-root-removal`.
| Flag | Meaning |
| ------------------------- | --------------------------------------------------------------------------- |
| `--repositories` | File containing the canonical repositories JSON array. |
| `--checkpoint-repository` | Logical checkpoint coordinator member. |
| `--source` | File containing the exact recovery source JSON object. |
| `--repository-name` | Selected member; omitted, `run` uses the root and `setup` uses all members. |
| `--holder` | Workspace-wide lease holder. |
| `--token` | Holder token; ordinary operations accept `BENCH_LEASE_TOKEN`. |
| `--request-id` | Reuse this growth request ID after an interrupted reply. |
| `--socket` | benchd Unix socket; uses v2 only. |
| `--initialize` | Warm initialization is mandatory (default `true`). |
| `--checkpoint` | Checkpoint and release a successful payload (default `true`). |
| `--quota-bytes` | One total workspace budget, bounded by host policy. |
| `--offline` | Offline frozen setup. |
| `--archive-grace` | Local archive grace; zero explicitly waives retention (default `168h0m0s`). |
| `--plan` | Concrete reviewed local administration manifest file. |
| `--approve` | Exact reviewed plan `Digest`. |
| `--repair-id` | Explicit local initialization repair identity. |
| `--rerun-once` | Review uncertain once hooks for these comma-separated members. |
| `--transfer-id` | Explicit reviewed local transfer identity. |
| `--target` | Fresh destination key for reviewed local transfer. |
| `--disposition-id` | Fresh identity for explicit current empty-directory removal. |
| `--cgroup-root` | Delegated local cgroup root (default `/sys/fs/cgroup/superbench`). |
| `--mirror-timeout` | Local managed git deadline (default `2m0s`). |
| `--state`, `--data` | Local state and data, with the same defaults as above. |
# benchd
> The local daemon's flags as cmd/benchd defines them, and what it does on start, restart and shutdown.
`benchd` serves the [local API](/api/overview/) on one Unix socket, from one private state store. It also runs the bounded background loops for automatic archive and, once an operator approves a policy, automatic log retention. A lifetime lock stops a second daemon from serving the same state. This page is checked against `cmd/benchd` when the docs build.
```sh
benchd --state /absolute/private/state --data /absolute/data \
--socket /absolute/runtime/benchd.sock --cgroup-root /sys/fs/cgroup/superbench \
--operator-uids 1000,0 --reader-uids 1001
```
Replace the example uids with real local accounts. All paths must be absolute. The state directory must be private (0700), owned by the daemon and outside bench data.
## Flags
[Section titled “Flags”](#flags)
| Flag | Default | Meaning |
| ---------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
| `--state` | `/superbench/state` | Private authoritative state directory. |
| `--data` | `/superbench/data` | Bench data directory. |
| `--socket` | `/benchd.sock` | Absolute Unix socket path. |
| `--cgroup-root` | `/sys/fs/cgroup/superbench` | Delegated cgroup-v2 root. |
| `--operator-uids` | the daemon’s uid and `0` | Comma-separated local operator uids. |
| `--reader-uids` | (none) | Comma-separated local read-only uids. |
| `--max-active` | `8` | Maximum active operations, 1 to 64. |
| `--mirror-timeout` | `2m0s` | Deadline for mirror clone, validation and fetch. |
| `--retention-interval` | `1m0s` | Automatic retention check interval; inactive until a policy is approved. |
| `--archive-interval` | `1m0s` | Archive inspection interval; only a committed `branch-merged` repository policy opts in. |
`benchd version` prints the build’s version.
## Running alongside the CLI
[Section titled “Running alongside the CLI”](#running-alongside-the-cli)
Keep host configuration consistent with the state, data and cgroup paths the daemon uses. Do not run competing direct writers while `benchd` serves that state: direct core commands do not enforce the socket’s uid policy. The core’s OS lock still serializes git and state mutations. `migrate`, `configure-host`, `archive`, `plan-reap` and `reap` stay local administrative commands.
## Restart and shutdown
[Section titled “Restart and shutdown”](#restart-and-shutdown)
* A disconnected client does not cancel work the daemon admitted.
* On restart, unfinished requests become `operation_in_doubt` and are never run again automatically.
* SIGTERM stops admission and cancels supervised runs, which fence before keeping their lease. HTTP shutdown has a ten-second grace period; the state lock is kept until admitted handlers finish, including slow git work.
* SIGKILL can leave descendants alive. Restart, then `bench stop --admin` fences the recorded scope.
## On Linux under systemd
[Section titled “On Linux under systemd”](#on-linux-under-systemd)
The repository’s staged installer (used in drills on disposable hosts, not a supported installation) runs `benchd` as a stable `superbench` account with `Delegate=yes`, reads `/etc/superbench/benchd.env` for `BENCHD_OPERATOR_UIDS`, `BENCHD_READER_UIDS`, `BENCHD_MAX_ACTIVE`, `BENCHD_RETENTION_INTERVAL` and `BENCHD_MIRROR_TIMEOUT`, and serves `/run/superbench/benchd.sock`. It never starts or enables the service by itself. Systemd stops the whole service cgroup on shutdown, with 45 seconds for reconciliation; never infer release from systemd status alone.
# Files and paths
> Where SuperBench keeps state, bench data, mirrors, caches, logs and its git refs, and the paths the staged Linux installer uses.
## State and data
[Section titled “State and data”](#state-and-data)
SuperBench keeps two directory trees apart: **state** (authoritative, private) and **data** (mirrors and checkouts). They cannot overlap, including through symlinks. Use local filesystems and the same `--state` and `--data` on every invocation. On a managed host they must be on different filesystems, and the data tree is the dedicated XFS mount.
| Path | What it holds |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `/bench.db` | Versioned SQLite state, with FULL synchronous commits. Status reads it without migrating. |
| `/service.db` | The daemon’s durable request receipts. |
| `/benchd.sock` | The daemon’s socket, when `--socket` is not given. |
| `/run-.log` | A supervised run’s private, bounded output log. |
| `/reap-.json`, `/archive-freeze-.json` | Reap approval and archive permission journals. |
| `/benches/` | A bench’s checkout. |
| `/mirrors/` | Shared bare git mirrors, one per repository. |
| `/store/` | Shared caches: `pnpm`, `npm`, `bun`, `playwright`, `go-build`, `go-mod`. |
| `/.bench/config.toml` | The repository’s [settings](/reference/repository-settings/). |
| `/.bench/cache/` | Checkout-local caches, when a repository chooses them. |
The defaults are `/superbench/state` and `/superbench/data`, from Go’s user config and cache directories (see [bench CLI](/reference/bench/)). Earlier prototype JSON state is imported once on the next successful write and kept as a historical snapshot; SQLite is authoritative from then on.
## Git refs
[Section titled “Git refs”](#git-refs)
| Ref | What it is |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `refs/heads/bench/` | A bench’s task branch, unless `--branch` names another. Checkpoints push here without force. |
| `refs/tags/superbench/pins///` | A workspace checkpoint’s pin for one member. Never overwritten or deleted. |
| `refs/heads/superbench/checkpoints/` | A workspace’s checkpoint seal: commits holding only `checkpoint.json`. |
Mirror refreshes update only `refs/remotes/origin/*`.
## The staged Linux installer’s paths
[Section titled “The staged Linux installer’s paths”](#the-staged-linux-installers-paths)
The repository’s Linux installer stages these for review and is used in drills on disposable hosts. It is not a supported installation.
| Path | What it is |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `/usr/local/bin/bench`, `/usr/local/bin/benchd` | The CLI and the daemon. |
| `/usr/local/libexec/bench-quota` | The fixed-policy quota helper (the `--quota-helper` default). |
| `/usr/local/libexec/bench-payload` | Managed hosts only: the static payload helper. |
| `/usr/local/libexec/superbench-start` | The root-owned wrapper that starts `benchd` with its delegated cgroup. |
| `/etc/superbench/storage.json` | Root-owned managed storage policy: data root, ledger, owner uid and gid, byte and inode caps, reserves. |
| `/etc/superbench/benchd.env` | Root-owned daemon settings: operator and reader uids, active limit, intervals. |
| `/etc/sudoers.d/superbench` | Managed hosts only: sudo for the quota helper and the argument-free payload helper, nothing else. |
| `/var/lib/superbench/state` | The service account’s private state. |
| `/run/superbench/benchd.sock` | The service socket (parent 0750, socket 0660). |
| `/sys/fs/cgroup/superbench` | The default delegated cgroup root. The installed wrapper finds the service’s real cgroup instead. |
| `/payload-retirements/.json` | A reviewed Fresh retirement plan, root-owned 0600. |
The storage policy’s example uses `/srv/superbench-data` for the data mount and `/var/lib/superbench-quota` for the privileged ledger; both are choices made at provisioning, not fixed paths. Keep the ledger and state outside the bounded data filesystem.
# Repository settings
> The .bench/config.toml file a repository commits to configure setup hooks, caches, a quota request and automatic archive.
A repository configures its benches with `.bench/config.toml`, committed in the repository. It is read inside the acquisition transaction, and the same parsed file drives the command plan and the cache environment. This page is checked against `internal/setup` when the docs build.
```toml
[setup]
once = "pnpm install --frozen-lockfile"
each = "pnpm install --offline --frozen-lockfile"
[caches]
pnpm = true
npm = true
bun = true
playwright = false
go = false
[quota]
size = "4G"
[archive]
when = "branch-merged"
```
The file must be UTF-8, at most 64 KiB, a regular, unlinked `config.toml` in a physical `.bench` directory. A pinned TOML parser rejects duplicate keys, wrong types and unknown fields, and its errors never echo shell text. Changing any byte, comments included, changes the configuration digest and invalidates `once` reuse.
## `[setup]`
[Section titled “\[setup\]”](#setup)
| Key | Meaning |
| ------ | ---------------------------------------------------------------------------------------------- |
| `once` | Runs on the first successful preparation of a bench, then only when the configuration changes. |
| `each` | Runs before every handoff. |
Each command is trusted shell code, at most 16 KiB with no NUL, run as the account running `bench` or `benchd`, with `/bin/sh -e` in its own subshell at the checkout. With no hooks, setup does a frozen install from exactly one pnpm or npm lockfile. See [Supervised runs and setup](/concepts/supervised-runs/).
## `[caches]`
[Section titled “\[caches\]”](#caches)
| Key | Default | `true` (shared, under data) | `false` (checkout-local) |
| ------------ | ------- | -------------------------------- | ---------------------------------------------- |
| `pnpm` | `true` | `store/pnpm` | `.bench/cache/pnpm` |
| `npm` | `true` | `store/npm` | `.bench/cache/npm` |
| `bun` | `true` | `store/bun` | `.bench/cache/bun` |
| `playwright` | `true` | `store/playwright` | `.bench/cache/playwright` |
| `go` | `true` | `store/go-build`, `store/go-mod` | `.bench/cache/go-build`, `.bench/cache/go-mod` |
Only booleans are accepted; a repository cannot name a cache path. Ignore `.bench/cache/` in `.gitignore` when any cache is checkout-local. SuperBench never edits `.gitignore` for you.
## `[quota]`
[Section titled “\[quota\]”](#quota)
| Key | Meaning |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size` | A smaller byte cap for new benches: a positive whole number of KiB, up to 1 PiB. `K`, `M`, `G`, `T`, `P` and `KiB` to `PiB` are binary; `B` or no unit means bytes, divisible by 1024. |
The request is read from the source commit at creation and enforced only on managed Linux XFS hosts, within the root policy’s ceiling. Elsewhere it is recorded and not enforced. It never resizes an existing bench. See [Quotas, mirrors and stores](/concepts/quotas-and-stores/).
## `[archive]`
[Section titled “\[archive\]”](#archive)
| Key | Meaning |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `when` | `manual` (the default) or `branch-merged`: archive read-only automatically once a checkpoint recorded as unmerged is seen merged into the remote’s default branch. |
Automatic archive never deletes anything; deletion still needs a reviewed reap plan after the grace period. See [Archive and reap](/concepts/archive-and-reap/).
# Limits
> The deliberate limits of the SuperBench prototype, its bounds and what it refuses to do, from the repository README and docs.
These are the limits the repository states. Some are deliberate and will stay; others are unfinished work. [Status](/start/status/) says which is which.
## Deliberate
[Section titled “Deliberate”](#deliberate)
* **Leases never expire because time passed.** No process is reassigned by time. A crashed holder keeps its lease; stop and inspect it before using its saved token to checkpoint or release. If a supervised holder’s token is lost, `bench stop --admin` fences the recorded scope and returns the retained lease.
* **Nothing is auto-committed, force-pushed, reset or deleted to make recovery succeed.** Conflicting files are preserved for review.
* **Untracked files block checkpoint and release; ignored build files do not.** Ignored files stay in the bench but are not recoverable from the remote.
* **Recovery restores only remote-confirmed committed files.** Ignored build products, untracked files and unpushed commits do not come back. Recovery needs the remote task branch to exist.
* **State stays outside bench data.** The state and data directories cannot overlap, including through symlinks. Use local filesystems, and the same paths on every invocation.
* **All commands serialize** under one host-wide OS file lock, including their git calls.
* **Git and state updates are not one transaction.** Journaled worktree creation can be resumed; a pushed checkpoint may need retrying if saving state failed afterwards.
## Bounds
[Section titled “Bounds”](#bounds)
| What | Bound | Source |
| --------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| API request body | 64 KiB | `docs/service.md` |
| API response | 1 MiB for every v1 response; on v2, 1 MiB for read-only responses and 64 KiB for durable growth responses | `docs/service.md`, `docs/workspace-api.md` |
| Concurrent connections | 64 | `docs/service.md` |
| Active operations | 8 by default, 1 to 64 | `benchd --max-active` |
| Request receipts | 64 KiB reserved per pending result, at most 10,000 rows and 64 MiB of replies | `docs/service.md` |
| Repositories in a workspace | 1 to 32 | `internal/protocolv2` |
| Run arguments | 1 to 128, each at most 8192 bytes | `internal/protocolv2` |
| `.bench/config.toml` | 64 KiB, each command at most 16 KiB | `docs/setup.md` |
| Reap manifest | 100,000 entries, 16 MiB encoded | `docs/archive.md` |
| Archive grace | 0 to 365 days, seven days by default | `docs/archive.md` |
| Mirror deadline | two minutes by default, up to one hour | `docs/mirrors.md` |
| Captured output per command | 1 MiB by default (`--max-log-bytes`) | `bench` flags |
Receipt exhaustion refuses new growth (create, recover, lease, run, setup) until reviewed retention exists, but stop, checkpoint, release and archive stay available. Do not delete receipts by hand to retry uncertain work. There is no pagination yet: an overlarge status fails, so query one key.
## Unfinished
[Section titled “Unfinished”](#unfinished)
* Supervised runs and setup need Linux with a delegated cgroup-v2 root. On macOS and unsupported Linux hosts, a fenced run refuses before it takes a lease. There is no silent fallback.
* Quotas are enforced only on managed Linux hosts with a dedicated XFS mount. Elsewhere a quota request is recorded and not enforced.
* Shared-cache, mirror and receipt collection are not built.
* A response schema and SDK for the local API are still pending; the shapes are proposed contract data.
* Remote authentication, a UI and suite integrations are not built.
# Security model
> Who SuperBench trusts and what it enforces. Root, the daemon account and the payload user; cooperative leases; trusted repositories on one host.
SuperBench coordinates **trusted** callers working on **trusted repositories** on **one host**. It is not a sandbox, and the code does not isolate untrusted code beyond what this page says. Read this before anything else on the site.
## The assumptions
[Section titled “The assumptions”](#the-assumptions)
* **Trusted repositories.** Repository setup hooks are shell code, run as the service user. Local git configuration and hooks apply. Only trusted repositories are suitable.
* **Cooperative callers.** A lease stops other `bench` acquisitions. It does not stop direct edits, an arbitrary shell, or another process running as the same user.
* **One host.** State, leases and checkpoints are local. There is no network lease coordination.
* **Trusted operators.** An operator on the local API is trusted to run arbitrary commands as the daemon’s user.
## The accounts
[Section titled “The accounts”](#the-accounts)
| Account | Owns or does | Notes |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| root | Installed binaries and configuration, the storage policy `/etc/superbench/storage.json`, the privileged quota ledger, and the parents of managed data | The staged unit runs `benchd` as the unprivileged `superbench` account; `benchd` itself does not refuse root (its default `--operator-uids` includes 0). Reap refuses root. |
| The daemon account (`superbench` in the staged installer) | Private state (mode 0700) and runtime, the bench, cache and mirror directories it is assigned | A stable account, so lease and recovery ownership survive restarts. This is a trusted coding-agent account, not tenant isolation. |
| The payload user | A separate identity for running a task’s payload, entered through the fixed payload helper | Present in source. `main` does not install and activate the complete separate payload-user path, so payloads today run with the launching account’s authority. |
Managed hosts get one sudo rule, `/etc/sudoers.d/superbench`. It permits only the fixed quota helper, which takes its logical allocation arguments and refuses `--policy` from sudo callers, and the dedicated payload helper, pinned to no command-line arguments. There is no generic shell or XFS sudo, and a sudo caller cannot select another policy. See [Payload identity and the fixed helpers](/concepts/payload-identity/).
## What is enforced
[Section titled “What is enforced”](#what-is-enforced)
* **Socket authorization by kernel peer credentials.** `benchd` reads the connecting process’s uid from the kernel (`SO_PEERCRED` on Linux, `LOCAL_PEERCRED` on macOS). Identity headers cannot grant authority. Operators can mutate; readers can only query `status` and `host_status`. The socket is mode 0660 and its parent must not be group- or world-writable.
* **No TCP listener.** The only listener in the non-test source is a Unix socket. This is read from the source; no test asserts the absence of a TCP socket, so it holds only as long as the code does.
* **Lease tokens are holder capabilities.** A token is returned only on acquisition, on an administrative stop (`stop --admin`) or on exact replay of a completed request’s receipt. Status and checkpoint output redact it, and supervised commands do not receive it in their environment.
* **Checkpoints never rewrite history.** A checkpoint pushes the existing HEAD without force and confirms the remote has exactly that commit. Nothing in that path makes a commit.
* **Process-tree fencing on Linux.** A supervised run is born inside its own delegated cgroup-v2 scope, and stop kills the whole scope (`cgroup.kill`), including detached `setsid` descendants, before checkpoint or release.
* **Byte and inode caps on managed Linux XFS hosts**, through a fixed-policy root helper that accepts logical allocations only.
* **Archived trees are read-only to ordinary writes**, and deletion needs an exact reviewed manifest after a grace period.
## What is not enforced
[Section titled “What is not enforced”](#what-is-not-enforced)
* **No uid, mount or network isolation per bench.** Neither cooperative nor supervised mode provides it. A supervised command has the launching user’s authority, so a deliberate cgroup escape by that user is outside the boundary. The repository calls this lifecycle fencing for trusted commands, not a sandbox.
* **Direct local commands bypass the socket’s uid policy.** A `bench` command run without `--socket` on the daemon’s state does not go through the socket’s operator and reader checks. It is bounded only by the state directory being 0700 and owned by the daemon account.
* **Cooperative leases do not fence anything.** A shell or editor opened after `bench lease` is outside SuperBench’s control. Only `run` and `setup` create supervised scopes.
* **No automatic lease expiry.** A crashed holder keeps its lease until someone inspects it.
* **The archive permission boundary is cooperative.** The trusted owner can `chmod` an archived tree and root can bypass mode bits. Already-open writable handles are not revoked.
* **Cross-host handoff files are unsigned.** Their digests bind bytes, not machines or operators.
* **Git and network calls can block** without an application deadline, and no timeout proves a writer stopped.
* **The managed sudo path is retained on purpose.** Adding `NoNewPrivileges` or a capability filter would break the helpers; do not treat the service unit as a hardened sandbox.
## Secrets
[Section titled “Secrets”](#secrets)
Treat saved state and acquisition output as private: they hold lease tokens. Prefer the `BENCH_LEASE_TOKEN` environment variable to `--token`, which exposes the token in process arguments. Repository credentials belong in the service account’s own credential mechanism, never in a repository, a tracked environment file or a prompt.
# Status
> What works on main, what is partial and what is not built, from the repository's implementation plan. SuperBench is not released.
SuperBench is not released. There are no tags, no published binaries, no supported installation and no production deployment. This page follows the phase table in the repository’s [`docs/implementation.md`](https://github.com/SuperJackfruitLabs/superbench/blob/main/docs/implementation.md), which is the source of truth; when the two disagree, that file wins and this page is out of date.
“Verified” below means what the repository records: tests in its check suite, or a dated drill whose output is committed under `docs/`. Several drills ran on disposable Linux hosts, not on a host anyone relies on. Passing single-host drills are not evidence that a whole phase is done.
## The phases
[Section titled “The phases”](#the-phases)
| Phase | Outcome it requires | Where it stands |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | Host disk alert, a reviewed cleanup dry-run, branch and checkpoint rules for code stages | Partial. A host collector and capacity warning were checked; notification delivery and recovery, real handoff enforcement and an operator-reviewed cleanup remain unverified. |
| 1 | Standalone CLI and host service; durable state and leases; checkpoints and recovery; quotas, shared mirrors and stores; verified archive and reap | In progress. Most of the single-host core is built and tested (below). The acceptance still to prove is listed under [Phase 1 acceptance still to prove](#phase-1-acceptance-still-to-prove). |
| 2 | Suite adapters, a card panel, locality scoring, witness events; a read-only web view, terminal attach and MCP | Not built. Contracts come before consumers, and visual mockups before UI. Static mockups exist; no viewer ships. |
| 3 | Remote editor launch or browser IDE; a second-host recovery drill; per-bench isolation (none yet); Salaam layout and execution-host integration | Not built. |
## Works on `main`, with tests or recorded drills
[Section titled “Works on main, with tests or recorded drills”](#works-on-main-with-tests-or-recorded-drills)
* **Create, lease, checkpoint and release a bench**, with cooperative leases and remote-confirmed checkpoints. See [Leases](/concepts/leases/) and [Checkpoints](/concepts/checkpoints/).
* **Durable state**: versioned SQLite outside bench data, with creation intents journaled before a worktree is made, so an interrupted create can be retried with the same arguments.
* **Supervised runs on Linux**, fenced in a delegated cgroup-v2 scope before checkpoint and release. See [Supervised runs and setup](/concepts/supervised-runs/).
* **Managed storage on Linux XFS**: per-bench and shared byte and inode caps through a fixed-policy helper, free-space admission, shared mirrors refreshed at acquisition, shared or checkout-local caches and bounded run logs. See [Quotas, mirrors and stores](/concepts/quotas-and-stores/).
* **Repository setup hooks** (`.bench/config.toml`), run before work and at creation.
* **The local daemon**, `benchd`, with kernel peer-credential authorization, durable request receipts and restart reconciliation. See [The local API](/api/overview/).
* **Grouped workspaces** (several repositories in one bench) through the v2 API and `bench workspace`, including complete-vector checkpoints and distinct-ref recovery.
* **Archive and reviewed reap**, with a persisted grace period and an exact approved manifest. See [Archive and reap](/concepts/archive-and-reap/).
* **Reviewed log and history collection**, and an automatic log retention policy that stays off until an operator approves it.
* **A staged Linux service installer**, checked with a disposable systemd unit. It is not a supported installation.
## Partial
[Section titled “Partial”](#partial)
* **Recovery.** Recovering a bench from its remote-confirmed task branch into a separate, empty state and data pair works. Recovery into existing state, missing-checkout and cross-host original-ref recovery are not complete, and a second-host recovery drill is Phase 3 work.
* **Payload identity.** The separate payload user and its fixed helper exist in source, but `main` does not install and activate the complete separate payload-user path. See [Payload identity and the fixed helpers](/concepts/payload-identity/).
* **Fresh allocations.** Fresh payload materialization stays disabled. Inspection and retirement of an absent Fresh allocation exist as direct-root maintenance; cleanup of nonempty allocations does not. See [Fresh allocations and recovery](/concepts/fresh-allocations/).
* **Laptop preparation.** Supervised setup needs Linux. A cooperative path for macOS and Linux exists, but it does not fence processes.
* **Moving a bench between hosts.** A reviewed administrative handoff exists. It is unsigned, adds no network coordination, and needs both operators to verify each other independently.
* **Contracts.** The v2 grouped request and response shapes are proposed contract data, not accepted contracts with consumers.
## Phase 1 acceptance still to prove
[Section titled “Phase 1 acceptance still to prove”](#phase-1-acceptance-still-to-prove)
The repository’s implementation plan lists these before Phase 1 can be called complete. Passing single-host drills alone is not evidence that they are done.
* The standalone laptop preparation path (supervised hooks currently require Linux).
* The remaining complete multi-repository CLI and service lifecycle.
* Missing-checkout and cross-host original task-ref recovery.
* The automatic completion and archive lifecycle, and broader collection.
* The acquisition, prompt and checkpoint pilot on an opt-in board, after the contract boundaries are reviewed.
## Not built
[Section titled “Not built”](#not-built)
* A release: tags, binaries, an installer anyone can rely on.
* Automatic lease expiry. By design, time alone never ends a lease.
* Remote authentication, a web interface and suite integrations.
* No payload isolation under a separate user yet, enforced end to end.
* More than one host working together.
* Collection of shared caches, mirrors and request receipts.
* The suite pilot on an opt-in board.
# What SuperBench is
> One task, one git worktree on a host, kept warm between holders, with checkpoints the remote confirms. An experimental single-host prototype, not released yet.
SuperBench gives each task its own git worktree on a host, called a **bench**, and keeps it warm between the agents or people who take turns on it. One holder works in a bench at a time. Before the bench can pass to the next holder, the work has to be committed, pushed to the task branch and confirmed on the remote.
It is a Go command-line tool, `bench`, and an optional local daemon, `benchd`, that serves the same operations over a Unix socket. It has no TCP listener (read from the source; no test asserts it, see the [Security model](/start/security-model/)) and depends on no other suite product. Output is JSON.
## Why a bench
[Section titled “Why a bench”](#why-a-bench)
A coding task usually needs a checkout, installed dependencies and a build cache before any useful work starts. When several agents take turns on one task, each starting from a fresh clone is slow, and sharing one checkout without rules loses work. A bench is the middle ground:
* **One task, one checkout.** `bench create` makes a worktree for the task from a shared git mirror, on its own task branch (`bench/` by default), and runs the repository’s setup.
* **Kept warm.** The checkout, its ignored build output and its caches stay on the host between holders, so the next holder starts where the last one stopped.
* **One holder at a time.** `bench lease` grants the bench to one holder and refuses other `bench` acquisitions until the holder releases it. See [Leases](/concepts/leases/) for what that does and does not stop.
* **Checkpoints the remote confirms.** `bench checkpoint` pushes the existing HEAD without force and fails unless the remote branch is exactly that commit. `bench release` refuses until that is true. See [Checkpoints](/concepts/checkpoints/).
* **Recoverable, in part.** Because the committed work is on the remote, `bench recover` can rebuild a bench from its remote-confirmed task branch into a separate, empty state and data pair. Recovery into existing state is not supported, and no second-host recovery drill exists yet; see [Status](/start/status/).
The basic loop, from the repository README (flags precede the task key):
```sh
bench create --repo /absolute/path/to/remote.git fix-login
bench lease --holder first-agent fix-login
# Save Lease.Token from the response in BENCH_LEASE_TOKEN and cd to Path.
# Edit files, git add, and git commit as usual. Then:
bench checkpoint fix-login
bench release fix-login
bench lease --holder second-agent fix-login
bench status fix-login
```
There is no supported installation yet: the loop above shows what the commands do, not a way to start using SuperBench.
The loop as written needs Linux. Whenever the repository has setup hooks or a supported lockfile, warm `create`, `recover`, `lease` and `setup` prepare the checkout in a fenced execution, which needs Linux cgroup delegation. On a laptop the cooperative sequence is `create-cold`, then `lease-repair`, then `prepare-local`, then `acknowledge-local-preparation`; see [Supervised runs and setup](/concepts/supervised-runs/#preparing-without-linux).
## What it is not
[Section titled “What it is not”](#what-it-is-not)
* **Not released.** There are no tags, no published binaries and no supported installation. Nothing here is in production use.
* **Not a sandbox.** Leases are cooperative, and supervised runs on Linux are fenced in a cgroup, which is process-tree fencing; there is no user or mount isolation. SuperBench is for trusted repositories. See the [Security model](/start/security-model/).
* **Not multi-host.** It runs on one host. Moving a bench to another host is a reviewed administrative procedure, not network coordination.
* **Not integrated with the rest of the suite.** Suite adapters, remote authentication and a web interface are not built.
## Where to go next
[Section titled “Where to go next”](#where-to-go-next)
* [Status](/start/status/): what works on `main`, what is partial, what is not built.
* [Benches and workspaces](/concepts/benches-and-workspaces/): the two shapes a bench takes.
* [bench CLI](/reference/bench/): every command and flag as the source defines them.