Supervised runs and setup
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.
bench run --holder reviewer --checkpoint=false --cgroup-root /delegated/cgroup fix-login -- sh ./verify.shLinux 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”- State records a random scope ID, a stable host hash, the boot identity, a starting phase and the holder token, before launch.
- 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.
- Stop marks the execution stopped only after the kernel reports no remaining members in the
scope and the empty scope can be removed. Detached
setsiddescendants stay in the cgroup and are fenced too. - On success the command is fenced, then its existing committed HEAD is checkpointed and the
lease released. There is no implicit
git addor commit.--checkpoint=falsekeeps a stopped lease even on success. - 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.
bench stop --token "$BENCH_LEASE_TOKEN" fix-loginbench stop --admin fix-loginKilling 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”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.
Setup hooks
Section titled “Setup hooks”bench setup reads .bench/config.toml in the checkout:
[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”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:
bench create-cold --repo /absolute/path/to/remote.git --branch card/example examplebench lease-repair --holder first-writer examplebench prepare-local examplebench acknowledge-local-preparation --digest REVIEWED_DIGEST --acknowledge-stopped-writers examplebench checkpoint examplebench release exampleOn 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.