Runs

A run starts when a ready story is picked up and ends when the story is done, or when it stops for good. On the way it may pause to ask you. Everything about it is on the run page: what kanman is doing right now, every step with its checks and its time, the evidence, the agent log, the cost and the decisions the run raised.

Open a run from the story card on the team page, from the team’s Runs tab, or directly at app.kanman.ai/<workspace>/teams/<team>/runs/<run-key>. Run keys are short, for example run-7f3k.

Desktop Mobile

The run page

The run page has five tabs. Each tab has its own address, so a link always opens exactly the part you want to show someone, for example .../runs/run-7f3k/evidence. You open it from the team’s Runs tab, and it reads like a closer look at that row: a bar at the top shows the story’s key and title, the run key and the status, and stays in place while you scroll. Its back arrow returns you to where you opened the run, exactly where you left it: the runs list, the story or the conversation. Opened from a link someone sent you, it leads to the run’s story. A decision that waits for you, the actions (Stop, Retry, Open pull request) and notes about what the run is waiting for stay above the tabs, whichever tab you are on.

Overview

The overview tells you at a glance where the run stands. Now says in one sentence what kanman is doing, for example “I’m running the acceptance tests in a fresh environment”, “I need your decision to go on” or “Ready for your review: every check passed”, and how long the run has been working. When a run is blocked or stopped, the reason is right there, for example Path infra/alarms.tf is not allowed by policy Balanced.

Below it are the steps diagram, the Key numbers (cost against the run budget, duration, attempts and how many criteria are proven), Delivery with the pull request, CI and the merge, and the Latest progress: the last three progress lines, with a link to all of them on the Steps tab.

The steps diagram

Every run goes through the same seven steps:

Each step shows its state and how long it took. A step can be not started, running, passed, failed, skipped, waiting for you or stopped; the step the run is at is highlighted. Quick stories need no acceptance spec: their Acceptance tests and Clean room steps are shown as skipped, with the reason. When a check fails and kanman reworks the change, the diagram draws a loop from the step that failed back to Code and says how often that happened.

Click or tap a step to open it on the Steps tab with its checks.

Steps

Desktop Mobile

The Steps tab shows the diagram again, then Time per step: one bar per step, so you see where the time of the latest attempt went. Below it, the step you selected lists its checks with their results and proof files, the tests that failed with file, line and message, and what each attempt did in this step.

Further down are the run’s complete Progress and its attempts, see Attempts and rework.

Evidence

Desktop Mobile

While the run is checked, its evidence assembles check by check as each one finishes. When the checks are done, the Evidence tab shows the evidence pack: the outcome first, then Criteria coverage, a table with one row per acceptance criterion and what proves it: the code that implements it, the acceptance test, the clean room and the review. Below it are screenshots of the pages the story changes, before and after the change, in light and dark mode, and every check with its result and its proof files. See The evidence pack.

Agent log

The Agent log tab shows what the coding agent did, live while the run works. See What kanman is doing right now.

Cost and details

Desktop Mobile

The Cost & details tab shows the cost of each attempt against the run budget, the time from Ready to PR ready split into coding, waiting for people and kanman’s checks (see Ready to PR ready), the plan with the approaches kanman weighed and how it scored them, and the facts of the run: the model and the coding agent, the story class, the tokens, when it started and finished, and where it ran, in kanman Cloud or on your runner, with how quickly the runner picked up its work.

Stages

The status of a run, on its cards and on the run page, follows five stages:

The executor reports progress while it works. These lines appear live on the run page, for example “Reading the invoices module”: the latest three on the overview, all of them on the Steps tab.

A run from planning to review, its steps passing one by one and its evidence ready at the end:

Status

Cards and the run page show one status per run:

What kanman is doing right now

While a run works, its card on the team board and in the conversation shows one short sentence below the status, for example “Claude Code is editing src/app.ts”, “Running checks: clean room” or “Waiting for a runner to pick this up”. The sentence changes in place as the work moves on, softly and without moving the card. It disappears when the run is done. When kanman works through a plan, the sentence names the step instead, for example “Step 4 of 7: migrate the export”, and changes only when kanman moves on to the next step.

Click or tap the sentence to open the run’s Agent log tab: what the coding agent wrote, the steps it reported and every file it read or changed and every command it ran, each with its result. The log follows the newest line while the run works; scroll up to read and it stays where you are. It stays with the run after it ends. Passwords, tokens and other secrets are removed before anything reaches the log. On a runner-only workspace the log shows which tools the agent used, while their inputs and results stay on your runner.

Attempts and rework

A run can have more than one attempt. All attempts share the same run key. If verification fails, kanman starts one automatic rework attempt and gives the executor the gate output and the reviewer’s findings. The steps diagram draws the rework as a loop back to Code. The run’s Steps tab shows, for example, Attempt 1: criterion 2 failed, and its Progress marks where each attempt begins (Attempt 1, Attempt 2), so you can tell what the rework did.

kanman keeps its own list of a story’s steps across attempts. A step counts as done only when kanman’s checks passed after it, not because the coding agent said so. A new attempt starts fresh from that list, from what earlier attempts tried and from the new failure, picks up at the first open step and does not redo proven steps or repeat an approach that already failed.

A failing run does not loop. When the same failure comes back, kanman first checks the same code again, then tries one different approach, and if that fails the same way too, or the story has used its attempts, the run waits and you get one item in your brief: narrow the story, keep going, or drop it for now (see When a gate fails). On some days, while kanman confirms that this works better for your team, the run instead goes to the decision inbox as Verification failed or Repeated gate failure, as set in the policy (rework_attempts, gate_failure_budget).

In the team’s chat kanman says why it stopped, for example “SBX-460 failed verification again after my automatic rework (Reviewer: Criterion ac-2 failed), so I stopped.”, with the decision right under it. Click Retry once more there once you have changed what made it fail; kanman answers “I started attempt 3 of SBX-460 as you asked.” with the run’s live card, so you can follow the new attempt without leaving the conversation.

Runs that keep restarting

If a run restarts three times within two hours without anyone asking for it, kanman pauses it so it does not burn compute in circles. Restarts you asked for never count: answering a decision with a retry or your guidance, Retry on the run page, a spec rewrite you requested or resuming a paused run. While you are steering a run this way, kanman leaves it alone.

When kanman pauses a run, it always asks you right away: the decision shows the reason and when each attempt started, and offers Resume the run or Stop this run. You can also use Undo on kanman’s notice; the decision then closes on its own. The run page explains the pause and points to Decisions only while that decision is open; otherwise it offers Resume right there.

Every new attempt, the automatic rework as well as a retry you start, uses the team’s policy as it is at that moment. If you raise the model or the effort limit for a story size under Settings > Agent and models, the next attempt of a running story already gets them. The audit log records which policy version and which model and step count the new attempt got.

One run per story

A story has at most one active run. When a new run of a story starts, for example because you moved the story back to Ready while an older run was still being checked, kanman stops the older run. It does not keep checking, reviewing or retrying it, and its open decisions close with the note that a newer run took over. The audit log records the change.

The older run’s page then says Superseded by with a link to the newer run, and its progress ends with the same line. It offers no Stop or Retry: continue with the newer run instead.

Branch names

kanman pushes each run’s work to a branch of its own, named after the story: kanman/<key>-<title>, for example kanman/fm-1234-update-the-billing-client. When the story is linked to a tracker issue, the branch carries the issue’s key, because that is what people search for in the repository.

If your repositories only accept certain branch names (for example a GitLab push rule that asks for feature/ or fix/ followed by a Jira key), set the team’s own branch names in Team settings > Repositories and tracker, under Branch names in the Repositories card. A template uses these placeholders:

For example, {type}/{tracker_key}-{slug} gives fix/FM-1234-login-redirect-loops. The template needs {key} or {tracker_key}, so every story gets its own branch, and it may have at most 80 characters.

While you type, the settings show an example name for one of your stories, or what is wrong with the template (an unknown placeholder, no key, or characters Git does not accept in a branch name). When your runner has checked a GitLab repository and found a branch name rule there, the settings also say this repository will refuse this name for every repository whose rule the example breaks, so you can fix the template before a run fails on it. Leave the field empty to go back to kanman’s names.

The template applies to new runs, to the branches of a rollout to many repositories and to the changelog follow-up after a merge, which gets the run’s branch name with -changelog at the end. Runs that already started keep their branch.

When the template uses {tracker_key} and a story has no linked tracker issue, kanman does not start the run under a name your repository would refuse. The run waits with a decision Link a ticket: link the issue to the story (the Tracker card of Team settings > Repositories and tracker says which tracker the team uses), then choose I linked a ticket, start the run, or stop the run. A rollout marks its repositories as needing attention for the same reason.

Complexity routing

When a run starts, kanman classifies the story as trivial, routine or complex. The class picks the model tier, the turn budget and the ceremony:

A story sized as trivial that has to install, build or run tests to be accepted, for example a dependency change in package.json and the lockfile, or acceptance criteria that run npm ci, a build or the test suite, is routed as routine. Installing and testing takes more steps than a small model with a short budget has.

This is the main cost lever: small changes do not pay for the most expensive model. You can change the tier and turn budget per class in the policy (routing), under the team’s Settings > Agent and models, Which model works on what: the model and the effort limit for each story size.

The reviewer run that checks the acceptance criteria uses a model from the other vendor (a Codex model for Claude Code and the other way round), so the code is never checked by the model that wrote it.

The run scratchpad

Each run keeps an append-only scratchpad with these sections:

• Classification
• Approaches
• Plan
• Implementation notes
• Self-review
• Review verdict
• Retrospective
• Decisions

The plan and the scored approaches appear in the evidence pack and on the run’s Cost & details tab. The retrospective and the reviewer’s objections feed the team’s conventions, and your notes on decisions reach the next attempt from here.

Waiting for a free run slot

Each team runs a limited number of stories at a time: the concurrency of its policy, within what the team’s plan allows. On Local, after the trial or a plan has ended, no runs start at all: the story waits in Ready, and kanman says once in the team’s conversation that a plan is needed, with a pointer to Plan & billing. A run holds its slot while it is queued, works or is checked; a run that waits for a decision or is parked frees it.

When every slot is taken, a story you move to Ready waits instead of starting, and kanman tells you why:

• the story card in Ready and the story page say Waiting for a free run slot (1 of 1 in use by run-7f3k), with a link to the run that holds the slot;
• the team’s status line counts the waiting stories, and kanman says it once in the team’s conversation;
• the run page of a queued run shows the same line, and the run holding the slot names the stories waiting for it.

Owners and admins also see where the limit comes from, with a link to Workspace settings › Plan and usage when the plan sets it, or to Team settings › Limits and budgets when the team’s own Stories at the same time does. The story starts on its own as soon as a slot is free. Expedite stories are never held by the limit.

Which story starts next

When a slot frees up and several stories wait, kanman starts the one that is worth the most to start now. It weighs each waiting story the same way:

• how close its outcome is to done: a story that finishes an outcome delivers that outcome sooner;
• how urgent it is: its priority, its class of service and how close its due date is;
• how much work is left and how likely the next attempt succeeds: short, well-understood work first.

A story fixing the problem other stories stopped on counts more. Stories with the same weight start in the order they reached Ready.

Your choice comes first. A story you move to Ready yourself (by dragging it on the board, with Start now or by saying “start PU-43”) starts before the stories kanman picked itself. Among the stories people moved, the same weighing decides.

The board shows the order. kanman keeps the Backlog and Ready columns in the order it will start the stories, so the card at the top of Ready is the next one to run. The same order applies when kanman approves its own low-risk stories into Ready, and on self-hosted runners.

A story never jumps ahead of what it has to wait for: stories that come after another story, stories whose files another run is changing, and stories held by your working hours or budget still wait.

Cost

The key numbers on the run’s overview show the cost of the run against the run budget (2.00 EUR by default), and the Cost & details tab shows what each attempt cost. When a run would exceed its budget, it stops with Stopped: budget reached, no pull request is created, and the decision inbox asks Raise budget for this run?. See Budgets and cost.

Actions on a run

Every state change of a run is written to the audit log as run_state_changed, with the person who clicked as the actor.

Ran out of steps

Each attempt has a step budget (the turn budget of its class). When an attempt uses all its steps before it is done, the run ends as Failed with the reason Stopped: I used all my steps. The run page then offers Retry with more steps as its main button and says what the new attempt gets, for example “The retry gets 120 steps on sonnet”. The new attempt runs with the next class up (a trivial story gets the routine model and plan) and at least twice the steps, but never more than the largest step budget your policy allows for any class. The run budget applies as usual.

If your policy allows no more steps, the page shows the plain Retry and a link to the team’s policy, where you can raise the steps.

Transient failures heal quietly

Network errors, an overloaded model API or a crashed executor are not your problem. kanman parks the run and retries it after 1, 5 and 15 minutes. These failures never reach the decision inbox. The run’s Steps tab shows Recovered after a transient error once it continues. After three failed retries the run ends as Failed with the reason on the run page.

If your git host or tracker does not answer, kanman holds new runs and parks running ones until the service is back, for at most three hours.

The health check

kanman regularly checks the team’s runs between attempts (every 15 minutes) and the team’s main branch (every 5 minutes):

• A run whose gates keep failing (the gate_failure_budget is used up, or the story failed twice as often across runs) is parked, and a Repeated gate failure decision offers Retry with my guidance, Retry as is or Stop this run. Both retries start a new attempt that gets the failed check, what it printed and your note, with the team’s current policy.
• When a new attempt after failed checks ends without a new commit, kanman does not run the same checks again, because they would fail the same way. A No change made decision quotes what kanman said at the end of the attempt and offers the same three answers.
• When a check finished but kanman could not take its result in right away (for example because your runner was briefly unreachable), kanman keeps the result and picks it up again a few minutes later instead of running the check a second time. This works for the checks of a finished attempt as well as for the clean-room check in Review.
• When the clean-room check fails because the environment failed and not the spec (a slow sign-in page of your identity provider, an app that was not reachable, a browser that could not start), kanman waits a short moment and runs the check once more before it fails. The run’s progress says so (“The environment failed on … I run the check again in 20 s”), so nobody has to push an empty commit to start it again. A failing assertion or a missing element of your story is never retried: that is a real failure.
• When the checks of a finished attempt have shown no progress for 20 minutes, kanman starts them again and says so in the team activity (see Checks that stop making progress).
• A run whose spend reached its budget is parked, and a Budget stop decision offers to raise the budget or stop.
• If CI on your main branch turns red, kanman holds its automatic merges in that repository (the team’s other repositories merge as usual) and opens a Main branch is red decision. For nightly and other default-branch pipelines across many repositories, see Failing pipelines. When a merged pull request from a kanman run is the likely cause, kanman opens a revert pull request (on GitLab a revert merge request) and asks before it is merged. In a workspace that runs everything on its runners, the runner opens it; the decision follows as soon as the runner has opened it.

The team’s chat shows the result as a notice above the message box, for example 1 run parked for repeated gate failure or Main is red, merges are on hold, with a link to the runs or the decision.

Related

• How kanman orders a goal’s stories
• The outcome gate and evidence
• Decisions
• Budgets and cost