Skip to content
Jimothydocs

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.

Run statuses

Section titled “Run statuses”
Status UI label Meaning
queued Queued Created and waiting for a slot. Limited by Settings → 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
   └──────────────────────────────────────────────────► cancelled

succeeded, 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.

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 text output 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).

Only the last 20,000 characters are kept as the step’s output. Longer output is prefixed with …[N earlier chars omitted]. The full stream is in the step’s logs. The output is what {{steps.<id>.output}} returns and what pass/fail patterns are matched against.

The Prompt / Command / Message tab shows the rendered input of the last attempt.

Section titled “Links”

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.