The run lifecycle

What a run does, what its states mean, and the different ways to do it again.

A run is one execution of a workflow for one task. A task keeps an ordered history of runs — at most one active at a time — so nothing about an earlier attempt is ever lost.

States

The Runs list groups these into seven headings: Running, Pending, Waiting (asleep at a wait step), Awaiting review — one heading for every run stopped and waiting on a person, with the row saying which kind of waiting — Failed, Completed, and Canceled.

The live session

Open any run and you watch the work as it happens, on every device. The transcript shows:

• The agent's narration and its reasoning.
• Every tool call — file edits as diff cards, commands with their output.
• The exact prompt each step sent, split into its layers.
• Check results — failures open, passes folded away.
• Gate, question, and preview panels where a decision is waiting.
• Published artifacts, and per-step time, token, and cost chips.

Opening a run late replays the whole history, then tails live. A phase that ran on a machine you paired carries that machine's name in its header.

Three different "do it again"s

• Request changes — re-runs the current phase in the same run, with your note as feedback, on the same branch. This is the everyday loop.
• Start over — mints a fresh run from the first phase on a fresh branch, suffixed -r2, -r3. The old run, its branch, and its log stay in the task's history. Starting over while a run is active cancels it first.
• Cancel — final, available from every state. Stops any in-flight work and closes the open gate. Cancel never re-runs anything.

There is also Restart phase on a phase header, which runs the phase again from the branch as it stands.

Resuming from the step that broke

When a step fails, the failed step's own card offers Resume from this step — run the phase again from here, keeping what the earlier steps produced. A phase of four prompts that broke on the fifth does not re-run four agents to get back where it was.

It appears only on the newest failed attempt of a phase, and only where the partial work was saved. Everything else keeps Restart phase, which stays the safe default.

Trying several approaches at once

From a task in the dashboard or the desktop app, you can start parallel attempts — several runs of the same task at the same time, each with its own workflow, its own extra instructions, and its own model, effort, or instruction substitutions. Save a combination you like as a preset and reuse it; saving one takes Manage board setup.

The attempts group together wherever runs are listed, on every surface. When they settle, the dashboard's comparison panel puts them side by side: status, elapsed time, tokens, cost, and how big each diff is. It does not pick a winner — you read them and choose.

Filing a run away

The Runs list answers one question — is anything waiting on me — and it answers it by showing everything. Archive is the way out: any finished run leaves the list for an archive of its own, and comes back with one action.

Only a finished run can be archived. A run that is executing, queued, or parked on a person is work in progress, and hiding it in the place people look when they have decided nothing will is how something gets forgotten. To get one out of the way: finish it, or cancel it.

Archiving is not a state. It says where a run is read, never what it is doing — its status, its machine, its slot, and its quota are untouched. Archiving a row that stands for several attempts files all of them.

Who can act on a run

Starting a run takes Start runs. On a run you started, the same permission lets you cancel, restart, start over, answer and archive it. Doing any of that to somebody else's run — or to one a trigger or an API key started — takes Manage runs. Gates are different: approving a phase's work is decided by the phase's approver rules. Requesting changes sends the work back, so it is acting on the run: yours with Start runs, anybody else's with Manage runs — or as an approver the gate's rules name, since reviewing is their job. See Roles & permissions.

Restricted folders and files

A folder or file that a project closes to somebody — a row on its Access page that takes away View files — is restricted, and every run leaves it out unless it includes it, whoever starts it. A run includes one when asked:

• Include restricted folders, on New run, a task's Run, Run with… and the other forms that start a run, lists the restricted folders and files you can open, none ticked: "Left out of runs unless you include them. Only what you can open is offered." A one-press Run asks for none.
• A workflow's phase can ask with include:; the person who starts the run gets what they can open of it.
• Starting over asks for the same again, as far as whoever does it can open them.
• A run started by an API key, or by a trigger with permissions of its own, includes what that list opens, without asking. A run with nobody behind it — an import, a trigger with no list — includes nothing.

A run that worked with a restricted folder or file shows only its row to people who can't open it — its title, its status, who started it and when — and, in place of the transcript, the changes and the files, This run worked with files you can't open. Restart and Cancel work as above; answering, reviewing, previews and its gate are for the people who can open what it worked with. How such a run reaches the repository is in Git & credentials.

Cost and usage

Each phase reports tokens split into four buckets — input, output, cache reads, cache writes — so run totals are honest sums that compare across agents. Claude reports exact dollars; Codex does not, so Peractor estimates from a rate table and marks any total that includes an estimate with ~$.

Queued, not rejected. Past your plan's concurrency cap, new runs — including reworks and retries — enter as pending and start automatically. You never lose a click to a busy moment. Only the monthly quota hard-stops a new run.