When checks run
Task-runner runs
A task-runner run is checked when all three of these are true:- The task ran on the task runner. That means an agent Routine whose task names a repository (set through the API), or a run started with
POST /api/runtimes/:id/runand arepoPath. How a team works explains the two paths. A worktree completed through the board’s workspace API is also checked, without a reviewer. - The task changes files, so it got its own git worktree. Research and review tasks get none.
- The agent changed something. A run that changed no files lands in Done without a check.
Team chat
A task that runs in team chat is checked when all three of these are true:- The team has a work check. That is the verify command you set in the team’s settings (see Teams). Without one, team-chat work is not checked: a lot of it writes documents rather than code, and a check with no command can only fail.
- The agent works in the team folder. A Claude Code, Codex, Hermes or Clawboo Native run on a task starts in the task’s own folder,
~/clawboo-work/teams/<team id>/tasks/<task id>, which sits inside the team folder in the work folder. OpenClaw agents work in their Gateway’s workspace and are not checked. - The run changed the team folder, task folders included, compared with the folder as it was when the task first started. A run that changed nothing, with no failed attempt before it, lands in Done without a check.
Never checked
- Team-chat work on a team with no work check, or by an OpenClaw agent
- One-to-one chats
- OpenClaw work. An OpenClaw Routine run gets a comment saying it completed without verification.
- Agent Routines created in the app (a team Routine posts into team chat, where the rules above apply)
- Research and review tasks on the task runner
- Tasks you move to Done yourself
What happens during a check
- The agent’s run ends. On the Board the card stays in In progress with a Verifying badge.
- Clawboo runs the team’s verify command if the team has one, otherwise the one named in the worktree’s
init.sh, inside the worktree, and reads its exit code. A team-chat task’s check runs the team’s command in the team folder. The command gets 10 minutes. Time the computer spends asleep does not count, except a sleep of under about a minute. - If the command passes and the change is large, risky or handed down from another task, a reviewer agent reads the committed change. The reviewer is a paid run, so the same budgets answer first: a hard cap that refuses it leaves the check with no review, and the card says why.
- Clawboo stores the result on the task and moves the card to match. In team chat, whoever handed out the task hears about it only after the check: on a pass, as a normal result.
The three outcomes
In Needs you, the card reads Needs review, whether the test command still fails or only reviewer findings are left.
Each task gets two attempts by default: the first, plus one fix round. The
CLAWBOO_MAX_FIX_CYCLES environment variable sets the number of fix rounds; 0 means a single attempt.
The verify command in practice
Clawboo knows your project’s test command only if you set it for the team: under Work check in the team’s settings (see Teams), or withPUT /api/team-verify-command/:teamId and {"command": "npm test"} (see the Teams API). When the team has one, every check runs it, whatever init.sh says, and each new worktree’s init.sh starts with it.
Without one, each new worktree gets an init.sh whose verify line is a placeholder:
TASK.md say to set VERIFY_CMD in init.sh to the command that proves the work. If it does, and that command passes, the first check can pass. If it does not, the first check fails and the fix note tells it again; a task whose agent never sets a command ends in Needs you.
The agent that did the work can edit init.sh, so without a team verify command it can also weaken its own check. Each check therefore records where its command came from, and the task drawer shows the command with its source: set for the team, from the task setup (the init.sh Clawboo wrote, unchanged), or written by the agent, which is flagged. Only set for the team is a guarantee: an agent can also write a commit that looks like the setup’s, so from the task setup means no edit was found, not that none was made. The reviewer is the independent part.
When the reviewer runs
The reviewer runs only after the test command passes, and only when at least one of these holds:- The task was handed down from another task (it has a parent task). In team chat, a hand-off straight from the lead, or a task you give on the Board, has no parent task; one a teammate hands off while working on its own task does.
- More than 5 files changed.
- More than 300 lines changed, counting lines added and removed.
- The task’s title or description names a risky action: delete, destroy, drop table, deploy, publish, release,
rm -rf, prod or production, secret, credential, API key or force push. It is the same word list team chat uses to ask a leader before a risky hand-off.
- It is a second run of the same runtime. It starts a fresh session, on a separate checkout of the committed change that has no branch to push. It gets none of the first agent’s session or runtime home.
- It uses the same model unless you set
CLAWBOO_REVIEWER_MODEL, which picks a different model on that runtime. - Only five kinds of finding block: security, crash, data loss, wrong algorithm, and missing acceptance criteria. Style, performance and other notes are recorded and never block.
- It cannot hold the work back by failing. If the reviewer fails to run, the test command alone decides. A reply Clawboo cannot read becomes one note that does not block. The task drawer names the reviewer only when it returned a verdict; otherwise it says Review did not complete or Review returned nothing.
- Its spend counts. The reviewer’s run is charged to the same agent, mission and team budgets as the work it reviews, and shows in Tokens Used under that agent. A review that reports no cost is charged an estimate. It is not added to the run cost on the task’s card, and because it runs after the work has finished, a cap it crosses stops the next run, not this one.
What you can do
- Move a card while it is being checked. If you move it to Done, Cancelled or Blocked, your move wins. Clawboo keeps the check’s result on the task if it answers, but moves nothing.
- Accept the work anyway. While the card is still in In progress with Verifying, move it to Done: if the stored result is a failure, the board asks you to confirm with Complete anyway, and Clawboo records the override in the audit log. Once the card is in Needs you, the dashboard cannot move it to Done; through the API, move the task to
in_progressand then todonewithhumanOverride(see the Board API). - Run it again. Retry, or another agent picked from the card’s More menu, sends the task back to To do and clears its check result. A task the task runner ran goes back through the runner, with the repository and kind it ran with, and its model when the agent is on the same runtime. It gets a worktree when the task names a repository, and is checked again. That needs an agent the runner can run, not one on OpenClaw. Other tasks, and tasks the runner ran before Clawboo started saving these settings, rerun through the team, with no worktree and no check.
- Drop it. Dismiss moves the task to Cancelled.
The failures checks are for
Checks in team chat
A team-chat task has no worktree: each task’s run works in the task’s own folder, and every task folder sits inside the same team folder. To see what a task changed, Clawboo keeps a history of the folder outside it, in~/.clawboo/team-folder-history/<team id>.git, and saves the folder there when the task first starts and again each time a run of it ends well. A later run (a fix round, or a Retry) keeps that first starting point. A run that fails or is stopped saves nothing: its changes are seen by the task’s next checked run, and a cancelled task’s are never checked. The folder itself never becomes a git checkout, and no VERIFICATION.md is written into it; the result is stored on the task.
- A fix round gets the note of what failed together with the task itself, because a team-chat run starts a fresh session. Its check compares the folder with how it was when the task first started, so it covers all of the task’s work.
- The reviewer reads a separate checkout of the folder as it was when the check started, made from that history.
- Whoever handed out the task hears about it once, after the check. When the last attempt fails, they are told the task failed the team’s check and needs a person.
- A task that hands out work is checked when that work has closed and its agent’s last turn has ended, not when it first handed the work out. Its sub-tasks would still be writing the folder. The check measures from where the task first began, so it covers what they changed as well as its own work, and the sub-tasks’ own checks ran on their part first.
- While a task is checked, its agent takes no other task, and a reply the agent gives you in that time is not taken as the task’s result.
- A check waits its turn on the folder. It does not start while another run of the team is working in the team folder, or while another task’s check is running, so it does not run in the middle of a change a teammate is still making. The cases it cannot rule out are listed below. Two tasks that finish together are checked one after the other. Until its turn comes the card reads Waiting to check, a comment says who it is waiting for, and the task stays In review. A waiting check takes no run slot and spends no budget, and it never delays a teammate’s start. When its turn comes, Clawboo saves the folder again, so the check and the reviewer see the folder as the teammate’s run left it, whether that run finished well or not. The result records how long it waited.
- The wait has a limit of 15 minutes. A teammate’s long run must not park the task, and parking it would ask you to look at work that may well be fine. So at the limit the check runs anyway, which is what it would have done without the wait, and says so in a comment and in its result. If it then fails with an attempt left, the fix round’s note warns the agent that the failure may come from someone else’s unfinished work.
- Whose change is whose. The wait does not keep teammates’ work apart. A task’s change is everything that changed in the folder since it started, so it includes what a teammate changed while the task ran. A teammate’s bug can fail this task’s check and send its fix note to this task’s agent, and a teammate’s change can pass under this task’s check. The reviewer reads all of it.
- A run that starts after the check began. The check runs on the live folder, and the wait never delays a run’s start, so a teammate can start changing the folder under a running check. A check at the limit runs beside whatever is still going too. The result says so, and the fix note warns the agent.
- A process a run left behind. A dev server or a watcher an agent started in the background can keep changing the folder after its run ends. It reports no run, so a check does not wait for it.
- A teammate caught at the task’s start. The folder is saved as the task starts, without waiting, so it can hold a teammate’s half-written change. The rest of that change then counts as this task’s.
- Files outside the team folder. Claude Code, Codex and Hermes can change any file your user account can; only the team folder, with its task folders, is compared.
- Dependency folders.
node_modules,.venv,venv,__pycache__,.next,.turboandtargetare not counted as changes. - Uncommitted edits inside a git repository an agent cloned into the team folder. Only a new commit there counts as a change.
- Files a
.gitignorein the team folder ignores. They are not counted as changes, so a run that changed only those is not checked. They stay out on purpose: they include files such as.env, which would otherwise land in the history and the reviewer’s checkout.
- Clawboo restarts, or the chat is closed, while the check runs or waits. The task moves once Clawboo is running again. The agent’s reply went on the task when the check started, so it is still there, and whoever handed out the task is told it was not checked.
- The check does not answer within 30 minutes. That clock starts when the check does, after any wait. The verify command itself is stopped after 10.
- The check cannot run, for example because the folder’s history is missing, or a fix round can no longer be checked after an earlier attempt failed.
- A fix round cannot be started, for example because the board could not record its run. The comment says why.
- Clawboo stops while the check runs. The task’s run stays open until the verdict, so the task moves within about 4 minutes of Clawboo running again.
- The check does not answer within 30 minutes, in time the computer is awake. A reviewer still working at that point is not stopped, and what it says is ignored.
- The check itself fails.
Limits
- Only task-runner runs in a worktree, and team-chat tasks on a team with a work check, are checked. The dashboard cannot start a task-runner run.
- A check is only as strong as its command, and without a team verify command the agent can edit
init.sh. - The team’s verify command can be changed by any local caller of the API, an agent’s shell included. It keeps a cooperative agent from choosing its own check; it does not stop one that sets out to.
- The reviewer runs on the agent’s own runtime, with the agent’s model unless you set
CLAWBOO_REVIEWER_MODEL. - Task-runner work stays on its own branch,
clawboo/task-<id>. Clawboo never merges it; merging is up to you. Team-chat work stays in the team folder, where the agent made it. - A check is not continuous integration: it runs one command, once per attempt, with no pipeline, cache or test matrix.
Under the hood
Under the hood
- Where it runs.
verifyTask(apps/web/server/lib/verification/index.ts) is called fromactOnTaskWorkspace(apps/web/server/lib/worktrees.ts) and from the team chat’s work check (apps/web/server/lib/teamChat/teamWorkCheck.ts). The task runner callsactOnTaskWorkspacewith a reviewer when a run completes (apps/web/server/lib/executorRunner.ts).PATCH /api/board/:taskId/workspacewith{"action": "complete"}calls it without one, so that route never runs the reviewer. The task runner closes its execution after the verdict and beats the task while it isin_review, so the boot reap orreconcileStaleInReviewblocks a task whose check died with its process. A check still going afterWORK_CHECK_TIMEOUT_MSof awake time is abandoned and blocks the task the way a thrown one does.actOnTaskWorkspacedrops the verdict once that execution is closed or a newer one has started, and a run that has already lost its execution touches neither the checkout nor the card. That route has no execution to find, so a crash during its check still leaves the taskin_review. - Team chat. The team engine’s
workCheckdependency (@clawboo/team-orchestration) callsbeginbefore it delivers a fresh run of a task, which commits the team folder to a bare repository outside it and pinsrefs/clawboo/base/<task id>, andpreparewhen the run ends well. A changed folder moves the task toin_reviewand runsverifyTaskthere with the team’s command, the commit as the reviewed revision, and noVERIFICATION.md. ItsshouldRecorddrops the verdict once the task has leftin_reviewor a newer execution of it has started. A pass lets the engine mark the task done; a failure with an attempt left moves it back toin_progressand the engine delivers a fix round as a new execution; the last failure moves it toblockedand the delegator’s[Task Update]has the outcomecheck_failed. The base ref stays until a pass, or a person’s Done or Cancelled, so a Retry is measured from the task’s first start. A task leftin_reviewwith an open engine execution and no check under way is blocked by the next engine’sresume()(outcomecheck_interrupted), and the dispatch pump builds the engine of any room holding one (listRoomsWithEngineTasksInReview). The boot reap leaves those rows alone: a check does not beat, so its clock says nothing about it. - The wait.
preparehands back the check with ahold, which the engine awaits first, detached from the run’s drain, with the session still bound and counted bychecksInFlight.apps/web/server/lib/runtimes/teamFolderActivity.tskeeps, per folder and in this process, the runs going and the checks in line:serverDeliver,driveAgentChat,runTeamExchangeandexecutorRunnerreport a run in the team folder, and a run’s report ends before itsdonereaches the engine, so its own check does not wait on it. Checks take turns first come first served, and only runs and a running check hold one back, so two checks cannot wait on each other. The engine bounds the wait withWORK_CHECK_HOLD_LIMIT_MSin awake time, and aborts it for a person’s move, a Stop or a teardown. A waiting task isin_reviewwithcheckHeldSinceset, which any move out of review clears, and so does the check as it starts. A person’s move is asked about before any card move, so a card moved back toin_progressthrough the API stays there: the engine frees the session, keeps the report, and leaves the open run to the stale sweep. The check gives its turn back only once its outcome is acted on, so a fix round is already going when the next check looks. - The command. The team’s verify command (settings key
team-verify-command:<teamId>) wins and is recorded ascommandSource: 'configured'. Otherwise the gate readsVERIFY_CMD='...'frominit.sh, then the- Verify:line ofVERIFICATION.md, and recordsscaffoldwhen that command matches theinit.shof the task’s scaffold commit (read from the repository withgit --no-replace-objects), elseagent. A command containingconfigure VERIFY_CMDcounts as none (packages/governance/src/verify/commandParser.ts). It runs through a shell in the worktree with Clawboo’s secrets removed from its environment, keeps the last 4,000 characters of output, and runs only in a task or review checkout or a team folder under the work folder’sworktrees/,reviews/andteams/, in a folder under the Clawboo folder (older layouts), or in a checkout the work folder move kept at its old place. It refuses anything else, the work folder itself, its other folders and a link whose real path leaves those places included, and runs in the real path, links resolved (apps/web/server/lib/verification/deterministicGate.ts; see The work folder). It readsinit.shandVERIFICATION.mdwithout following a link an agent put there. - The stored result. Statuses are
pass,failandcompleted_with_debt, which is given at the last attempt. Acompleted_with_debtresult lists the open issues indebtNotes, and a later pass with debt adds to them. A later check whose command passes drops the failed command’s issue, even when the reviewer then fails the work. Afailkeeps the rest, and the task drawer lists them under the failure, marked Still open from an earlier pass with debt. Apassclears them all when its review completed. A pass with no review, or with a review that returned nothing or did not complete, keeps the reviewer’s issues, because nobody looked at them again. The task drawer lists those under Passed, marked Not reviewed again. Each attempt’s own result stays inattempts, and a team-chat attempt that waited, or that had another run going in the folder, has ahold(waitedMs,limitReached,runBeside).PATCH /api/board/:taskIdrefusesdonewith409 verification_requiredwhile a stored result blocks it, unless the request setshumanOverride, which writes averificationaudit row. A stored result that cannot be parsed does not block, andcompleted_with_debtover a passing command does not block a later move to Done. - Skipped by Clawboo. A run that changed nothing, and an OpenClaw Routine completion (an
unverifiedaudit row), both reachdonewithout the gate. - The reviewer trigger.
shouldRunCriticinpackages/governance/src/verify/criticTrigger.ts. ItsriskFlagcomes fromisRiskyDelegation(apps/web/server/lib/teamChat/riskyDelegation.ts) run on the task’s title and description, inverifyTask. - Clearing. Any move to
todoclears the stored result.
Related
- How a team works: which work runs on the task runner.
- Worktrees and handoff: the checkout a check runs in.
- Board: Needs you, Retry and Dismiss.
- What agents can do: why a worktree is not a sandbox.
- Environment variables:
CLAWBOO_MAX_FIX_CYCLESandCLAWBOO_REVIEWER_MODEL.