Background Runner

The Background Runner dispatches eligible Kanban cards into isolated agent lanes. It drains one board at a time: the cards in that board’s Ready column.

Connecting a board and starting

To run Kanban cards, the Runner needs a connected board (a Runner that only runs loops needs none). Until one is connected the header chip reads Runner: No board. You can connect a board in any of these places:

Header chip. Open Runner: No board, pick the board and the column to run cards from, and choose Connect and start. The picker preselects the board with the most cards waiting and a column named Ready (or To do). It also picks Doing and Done columns if the board has them. A workspace with no board offers Add a Kanban board.
Background Runner tile. An unconnected Runner shows the same picker in place of the queue.
Runner settings (All settings). The Source board section shows which board is drained and lets you switch to another board or column.
The board itself. The Runner icon in the board header sets any column as the Ready column. On the connected board, the same menu offers Start the runner on ”…”, naming the Ready column.

Switching the Runner away from another board asks for confirmation first, and the dialog shows how many of that board’s Ready cards stay behind. Those cards stay where they are and do not run, and cards already running there finish. To connect a board and start the Runner in one step, choose Make source and start (or Switch and start).

Work sources

The Runner draws work from two sources, listed under Sources in the Background Runner tile:

Kanban: cards from the configured board’s Ready column, described on this page.
Loops: a task prompt re-run in fresh lanes until its exit checks pass. Loops are available only where the deployment enables the loop source. Turn the Loops switch on to let queued loops run. See Loops.

Both sources share the workspace’s worker capacity, and a loop’s accepted result lands under the same After success setting as a card. Launching a loop from the Loop Designer turns the loop source on and starts a stopped Runner. If that would also run cards waiting in the Ready column, it asks you first.

Card execution

Admission claims the card and reserves workspace capacity together. The worker receives the card prompt and a lane. Dispatch moves the card to the configured Doing column.

Completion records the outcome for that claim and releases its capacity. A card moves to the configured Done column once its result is usable, as described under Dependencies and landing. Failed or cancelled outcomes do not mark the card Done.

Dependencies and landing

A dependency requires a successful result with durable evidence of the work produced. A commit dependency also requires verified landing. Moving a card to Done alone does not establish that evidence.

The Runner moves a code card to Done only after its commit lands (or its result is superseded or abandoned); until then it stays in Doing marked “Awaiting merge”. Report and workspace cards move to Done as soon as their result is stored.

Completion and landing are separate facts: the worker’s exit reports its result, while a signed merge event supplies evidence for the repository, branches, and exact source commit. A merge does not turn a failed worker into a successful one.

Agent review

The Agent review section of the Background Runner settings (beside After success) chooses whether an independent agent must approve each result before anything relies on it:

Off (default): cards behave exactly as described above.
Required: after an implementation succeeds, the Runner reviews its exact product, meaning the commit for code or the stored result for report and workspace cards, before dependents can use it, before it reaches Done, and before Auto merge may land it.

Agent review is separate from After success. Neither setting implies the other. An agent approval is not a pull-request review on your Git provider, and it never merges anything: code still lands under your landing mode, and any reviews your repository requires still apply. The setting is fixed onto each card when that card starts, so changing it affects only cards started afterwards.

Review is a phase of the same card while it stays in Doing. There is no Review column. The card shows Implementing, Queued for review, Reviewing, Changes requested, Fix queued or Fixing findings, Approved · merge or Review approved. It shows Review needs you or Review failed when a person must act. Reviews use the same worker capacity as cards, and pausing or stopping the Runner also pauses them.

Independence. The reviewer must run a different underlying model from the one that did the work, and a different model family or provider is preferred. If the implementation’s model is unknown, or no independent model is available, the review waits and asks for you. It never falls back to the same model reviewing its own work.
Exact product. An approval covers only what was reviewed. A later commit (for example a conflict repair), an edited card description or a new attempt needs a new review. A result merged by hand is recorded as merged, but it still waits for approval before dependents use it. Dragging a card to Done does not count as approval.
Evidence. The card’s details show the verdict, the findings, the checks the reviewer ran and their limitations, the exact commit or result that was reviewed, and why that reviewer was chosen. Review failed means the review could not run: no verdict exists, and it is not a finding.
Changes requested. The work stays recorded as successful execution, but nothing uses it, and the Runner does not retry it by itself. Open the card and choose Fix findings, then select the findings to address. This queues a new attempt of the same card, starting from the reviewed commit or result, and that attempt is always reviewed again. Code that is already merged cannot be fixed this way; create a follow-up card.
Workspace actions. A workspace card changes the live workspace before it is reviewed. Review decides whether its recorded result can be relied on. It cannot prevent or undo actions that already happened. Fix findings on a workspace result asks you to confirm that those actions are not repeated. Use a decision step before the work for anything that needs approval before it happens.

Stopping work

In the Background Runner tile:

Finish current, then pause stops new cards from starting while running ones finish.
Cancel active work asks the running agents to stop. Their capacity is released only once each worker confirms it stopped.
Release held slots is a last resort for a worker that can never confirm — for example, one whose sandbox went away.

Runner settings also holds Queue mode (Drain once, which stops when the Ready column is empty, or Standing, which waits for new cards) and Concurrent executions (1 to 4 cards at a time).

Concepts — boards, cards, dependencies, and outcomes
Loops — iterate an agent toward exit checks
CLIs — the agent binaries that run inside lanes
Workspace MCP Server — board and tile tools

When execution finishes but dependencies wait

A code card that finished successfully stays in Doing, marked “Awaiting merge”, until its exact output commit is merged; dependent cards start only after that. The card’s Work panel shows the branch, commit, PR link when available, and the current blocker. Dependent cards name the predecessor waiting to land.

Where the native landing workflow is enabled, Off leaves PR creation and merge to you, Review prepares a PR and waits for your review/merge on the provider, and Auto uses your existing landing grant only when verification and repository protection permit it. Starting Background does not raise landing autonomy. Missing credentials, conflicts, checks and changed PR heads remain visible. Waiting for your PR review or merge consumes no worker slot.

Choose what happens after success

Open Background Runner → Configure → After success:

Manual (Off): you create PRs and merge them after review.
PR + review (Review): Background prepares PRs; you review and merge them on your Git provider.
Auto merge (Auto): Background prepares PRs and merges eligible work after required repository checks pass. Enabling it requires confirmation and also applies to existing completed cards. You can limit it to certain branches with Only into: PRs into any other branch wait for your review, as under PR + review. With no branches listed, Auto merge applies to every target branch.

Starting Background does not change this choice. Changing it does not require a runner restart; existing landing jobs evaluate the new mode on their next check, which can take up to five minutes. Conflicts, missing credentials, or unavailable required checks remain visible blockers in Auto merge.

The runner displays the current landing mode and distinguishes active execution, work awaiting dispatch, and cards waiting for review or dependencies. Its detail view names the blocking cards and shows completed branches, exact commits, and available PR links. Zero active workers can mean that your review is required: it does not mean the queue finished or that restarting it will help. An enabled queue resumes dependent work automatically after verified landing. Waiting for your PR review or merge consumes no execution slots; a Required agent review does use worker capacity.