Runs & statuses
A run is one execution of a pipeline for one issue (or task). It records the issue, the workspace and branch, every step’s status, output and logs, the cost and tokens, and links found in the output. Runs are listed on the Runs page and the Dashboard; see Runs in the app for the UI.
Anatomy of a run
Section titled “Anatomy of a run”| Field | Meaning |
|---|---|
| Number | Sequential across all pipelines (#1, #2, …). Available as {{run.number}} and $FACTORY_RUN_NUMBER. |
| Id | Internal id (run_…). {{run.id}}, $FACTORY_RUN_ID. |
| Pipeline | The pipeline name, plus a snapshot of its definition taken when the run was created. |
| Trigger | Manual, or the trigger that started it (Linear, Jira, GitHub, Schedule, Webhook). |
| Issue | Key, title, description, URL, labels, and provider-specific fields. |
| Workspace / branch | Set once the workspace is prepared. |
| Cost / tokens | Summed over every attempt of every step, for harnesses that report them (Claude Code, Codex, the API harnesses, the Simulator). |
| Links | Pull requests, merge requests and previews detected in step output. |
| Error | For failed runs, which steps failed and the first error. |
The run’s copy of the pipeline
Section titled “The run’s copy of the pipeline”A run works from a copy of the pipeline taken when it started. Editing the pipeline doesn’t change runs already in progress. New runs get your edits, and so does a run you Retry, because a retry reloads the pipeline’s current definition. Harness settings aren’t copied: they’re read fresh on every attempt, so a fixed harness applies to the next attempt of any run.
To change one step for one run, use Edit or Skip on the run page. Those changes stay with that run and survive its retries. See Fix a run in place.
Run statuses
Section titled “Run statuses”| Status | UI label | Meaning |
|---|---|---|
queued |
Queued | Created and waiting for a slot. Limited by Settings → General → Max concurrent runs (default 3) and the pipeline’s Max concurrent runs. |
preparing |
Preparing | The workspace is being prepared (worktree, clone, folder). |
running |
Running | Steps are executing. |
awaiting_approval |
Needs approval | At least one approval step is waiting and no step is running. |
succeeded |
Succeeded | Every step succeeded, was skipped, or failed with Continue on error. |
failed |
Failed | A step failed without Continue on error, workspace setup failed, or the app was closed mid-run. |
cancelled |
Cancelled | You cancelled it (while queued or active). |
queued ─► preparing ─► running ⇄ awaiting_approval ─► succeeded │ │ │ └► failed │ └───────────┴──────────────────────────► failed / cancelled └──────────────────────────────────────────────────► cancelledsucceeded, failed and cancelled are terminal. A terminal run can be retried, which puts it back to queued. queued, preparing, running and awaiting_approval count as active.
A run that was active when the app quit becomes Failed at the next launch, with the error “Interrupted: the app was closed while this run was in progress. Use Retry to resume.” Its running and waiting steps become Cancelled. Queued runs are simply queued again.
Step statuses
Section titled “Step statuses”| Status | UI label | Meaning |
|---|---|---|
pending |
Pending | Not started yet, or reset by a loop or retry. |
running |
Running | An agent or shell attempt is in progress (including backoff between retries). |
awaiting_approval |
Needs approval | An approval step is waiting for a decision. |
succeeded |
Succeeded | The step passed (exit code 0 / approved / verdict passed). |
failed |
Failed | All attempts failed, the verdict failed, or the approval was rejected, and no loop-back remains. |
skipped |
Skipped | The step didn’t run. See skip reasons below. |
cancelled |
Cancelled | The run was cancelled or interrupted while the step was pending, running or waiting. |
Skip reasons
Section titled “Skip reasons”A skipped step records why:
- Condition: its Run only if template rendered falsy. The error reads
Condition not met: <template>. Steps that depend on it still run. - Upstream: a dependency failed or was cancelled (without Continue on error), or was itself skipped for an upstream reason. The error reads “Skipped because an upstream step failed”. This propagates down the graph.
- By hand: you clicked Skip or Skip and continue on the run page. The error reads “Skipped by hand”. Steps that depend on it still run, as if it had passed.
Attempts and iterations
Section titled “Attempts and iterations”Each time a step executes, it records an attempt with its own log file, start and finish time, exit code, status and error. Two counters distinguish why a step ran again:
- Attempt number increases on every execution: retries after failures, loop-backs and run retries all add attempts.
- Iteration (the loop number) increases each time the step is reset by a feedback loop. It’s available in templates as
{{loop.iteration}}(0 on the first pass).
On the run page, the step’s attempt selector shows entries like Attempt 3 (loop 1) · succeeded, and the Details tab lists all attempts.
Output
Section titled “Output”- Agent steps: the harness’s final answer. For structured formats (Claude Code stream-json, Codex JSON, Pi JSON) it’s the parsed result; for
textoutput it’s the process’s stdout; for API harnesses it’s the response text. - Shell steps: stdout and stderr lines combined, trimmed.
- Approval steps: the approver’s comment (empty if none).
The complete output is what {{steps.<id>.output}} returns and what pass/fail patterns are matched against. When it’s longer than 20,000 characters, the run keeps the last 20,000 as a preview (prefixed with …[N earlier chars omitted]) and saves the whole text next to it; Show the full output on the step’s Data tab loads it. Rendered prompts that long are kept the same way, from their start.
The step’s Data tab shows each attempt’s rendered input (prompt, command or message) next to its output. Files the step made are on its Artifacts tab; see Artifacts.
Jimothy scans step output for links and shows them as buttons in the run header:
| Pattern | Button label |
|---|---|
https://github.com/<owner>/<repo>/pull/<n> |
PR #<n> |
https://gitlab.<host>/…/-/merge_requests/<n> |
MR !<n> |
https://bitbucket.org/<owner>/<repo>/pull-requests/<n> |
PR #<n> |
https://<name>.vercel.app |
Preview |
So a shell step that runs gh pr create (which prints the PR URL) automatically gives the run a PR button.
Cost and tokens
Section titled “Cost and tokens”Each step records cost (USD) and tokens (input, output, cache read, cache write) when its harness reports them. They’re summed per step across attempts and per run across steps, and feed the Dashboard’s spend KPIs. Harnesses with plain text output don’t report cost or tokens.
Deleting runs
Section titled “Deleting runs”A run can be deleted from its page once it’s no longer active (“Cancel the run before deleting it” otherwise). Deleting a run removes its record and logs, not its workspace. Deleting a pipeline keeps its existing runs.