Closing the loop
Three commands take the operator out of the steps between “a worker finished” and “its work is on the target
branch”: operator post-checks grade a run with checks the agent never sees, uh queue launches missions in order
under an orchestrator cap, and uh land puts verified, reviewed worker branches on a target branch or leaves the
target exactly as it was. The hive records what those commands prove, so every later agent starts from it.
Operator post-checks
Section titled “Operator post-checks”A required check the agent can read is a check it can game. uh mission run --post-checks <file> gives the operator
a grader that stays outside the agent’s view.
uh mission run .harness/missions/<mission-id>/mission.yaml --runtime <adapter> --post-checks <checks-file>The file is YAML or JSON, a list of checks:
- name: reading-coverage command: python <grader> <spec> timeout_ms: 600000The same list may be wrapped as { schema_version: uh.post-checks.v0, checks: [...] }; both shapes mean the same.
- The file is read at launch. Its path and commands never reach the prompt, the runtime’s environment or argv, or any artifact under the project root. Keep the file and anything it runs outside the tree the agent can read.
- Each command runs after the runtime settles, with no window, in the run’s working root (the sandbox worktree when
the mission is routed into one), with
UH_MISSION_ID,UH_RUN_ID,UH_RUN_DIRandUH_ROOTin its environment. - The console prints only the number of checks and the name of a failed one. Each check’s output goes to a
logsdirectory beside the checks file. runtime-result.yamlrecordspost_checksas names and outcomes.- A cancelled run is not graded: its post-checks do not run and its status stays
cancelled. Ctrl-C or SIGTERM while a check runs kills that check’s whole process tree and leaves the run’s status as it was. Each stream of a check’s output is capped at 1 MiB in its log, with a marker where it was cut, and UH warns when the logs would land inside the project. - A failed, timed-out or unrunnable check fails the run with exit code
1whatever the stop code, and the mission-levelruntime-result.yaml,latest.jsonand the runs index show the failure. An error inside the post-check runner itself fails the run withpost-check runner failed;UH_RESULTis still printed.
uh queue
Section titled “uh queue”uh queue run <queue.yaml> launches missions in file order once the entries they depend on have passed, at most
--max-orchestrators (default 2) at a time.
id: eveningentries: - id: hive mission: .harness/missions/<mission-a>/mission.yaml runtime: claude-code - id: docs mission: .harness/missions/<mission-b>/mission.yaml runtime: command-code - id: acceptance mission: .harness/missions/<mission-c>/mission.yaml runtime: claude-code after: [hive, docs]uh queue run evening.yaml --max-orchestrators 2uh queue status evening- Sandbox routing. An entry runs as
uh mission runwould run it: a mission with a bound sandbox runs in that sandbox, and a worker mission with none is refused. An entry that must run in the project root sayssandbox: false; nothing else gives the queue that route. - Memory floor. A launch is held unless measured free memory covers one more run (1024 MB) above a 1024 MB reserve, through the same admission helper team workers use; memory is probed again after a short wait.
- Settlement. Each entry settles from its run’s recorded settlement through the same path as
uh wait, never from the launcher process exiting. An orphaned run is recorded asfailedwith reasonorphaned; a slow run staysrunninguntil its record settles. A wait that times out fails withwait-timeoutand keeps the run id for a later resume; a launcher that exits non-zero before any run record appears fails withlaunch-failed. - State. Per-entry state (
pending,running,passed,failed,skipped, with run id, start and finish times and exit code) is written atomically to.harness/queue/<queue-id>/state.jsonafter every change. - Resume. A restarted queue resumes from
state.jsonand waits on recorded run ids instead of relaunching them. - Failure. Entries that depend on a failed entry are
skipped. - Notifications. Each settle sends one notification through the configured sinks (notifications.md).
uh land
Section titled “uh land”uh land runs in the target branch’s own worktree and lands one or more worker branches as a single commit.
uh land --worker-branch uh/team/<team>/<worker> --onto <target-branch> \ --message-file <message-file> --fast-forward <other-checkout>It refuses before touching anything unless the worktree it runs in has --onto checked out (a detached HEAD or
another branch is refused, naming the branch it found) and every branch passes both gates:
- Verified. The branch has a passed
uh verifyresult in its retained worktree (run the team with--retain). - Reviewed. A collected independent review names the branch’s team mission (read from
uh/team/<team>/<role>), matches its request digest, captured the same file hashes as the branch tip, and contradicts no claim. Binding is to the team, not the individual worker; a review of one worker of a team can satisfy the gate for another. Reviews are read from--review-rootwhen given, otherwise from the project that owns the worker worktrees: the parent of the.harnessdirectory they live in.--accept-review <reason>overrides only this gate and writes the reason, branches and review ids to.harness/land/<timestamp>-decision.json.
It then:
- cherry-picks the branches without committing;
- runs the project’s checks (default
bun run typecheckandbun run test); - scans the staged diff and the message for forbidden patterns (default
co-authored-by,anthropic,claude-session,generated withand the robot emoji, case-insensitive); - commits with the repository’s configured git identity as author and committer;
- runs the build (default
bun run build); - fast-forwards every
--fast-forwardcheckout to the new commit; - removes each landed worker’s retained worktree, and a team’s leader worktree once none of that team’s worker
worktrees remain. Branches are kept, and so are the target and every
--fast-forwardcheckout. A worktree that cannot be removed stays and does not fail the land.--keep-worktreesskips this step.
Any failure after the gates restores the target to its recorded HEAD, keeps every worktree, and exits non-zero
naming the step and the reason.
The checks, patterns and build come from an optional land block in .harness/project.yaml; an absent field keeps
the default:
land: checks: - name: typecheck command: bun run typecheck - name: test command: bun run test forbidden_patterns: [co-authored-by, generated with] build: bun run buildTeam workers commit under the same rule: the repository’s configured user.name and user.email, falling back to
uh team worker <uh-team@example.com> only when the repository has none.
The hive
Section titled “The hive”.harness/hive is the shared blackboard of a project: open items (items.yaml), proven facts (facts.ndjson) and
agent claims (claims.ndjson). It belongs to the project that owns the worker, the parent of the outermost .harness
directory in a worktree’s path, so every worker of a project reads the same hive and a project that is itself a linked
git worktree keeps its own.
uh hive import open-items.md # seed items from a markdown checklist: '- [ ] A8: title', '[x]' means doneuh hive show # items and facts; --json for machinesuh hive verify # facts chain, intervention ledger chain and land decision indexuh hive verify --repair # re-link a chain forked by the old append bug (explicit; keeps the original)- Only the controller writes facts.
uh land,uh queueanduh verifyappend a fact after a successful land, a passed queue entry or a passed verification, and mark any item they name as done. Each fact cites controller evidence (a run record, a verification result, a collected review or a commit) by hash; a fact whose hash does not match its evidence is refused. Agent statements go toclaims.ndjson, never to facts. - Tamper-evident. Facts, the intervention ledger and the land decision index are hash-chained;
uh hive verifyreports the first broken line, anduh landanduh queuerefuse to proceed on a broken chain. Unchained ledger lines written before the chain existed are kept as a legacy prefix. One break is not a refusal: before the appends were serialized, two writers could each link an entry to the same parent (a fork).uh landanduh queuego on with a[WARN]that namesuh hive verify --repair;uh hive verifyreports it as[FORK]and exits1; recording new facts stays paused until it is repaired.--repairre-links the forked entries, and each entry after them, to one chain, keeps the original file beside the repaired one (<file>.pre-repair-<time>) and writes<file>.repair-report-<time>.jsonlisting every entry it re-linked with its old and new hashes. It never runs on its own, and it refuses a chain with any other break (an edited, deleted or reordered entry) without touching it. The chain alone detects edits, not a rewrite that recomputes it, so each fact also carries amac: an HMAC-SHA256 of its body under a controller key kept in the user data directory (<user data>/controller.key, created on first use), outside every repository. A re-link keeps everymacvalid, because themaccovers the body and not the chain fields. - Evidence stays in the project. A fact’s evidence ref is a path relative to the project that owns the hive; an absolute ref, or one that leaves the project, never verifies.
- Guarded. Any agent write, edit or delete of the hive is a
guard_tamperstop in the Command Code hook, the Claude Code hook and the oh-my-pi extension, and direct reads are denied in favour ofuh hive show. A.harness/hiveinside a worker’s own scratch project is not the project’s hive and stays allowed. - Injected as data. Only facts whose chain is intact, whose
macthis controller’s key produced and whose evidence still hashes to its recorded value reach a worker’s prompt, selected by the item ids and paths the packet names, bounded in size, and rendered as a block labelled as data, not instructions, with every field escaped.