Run statuses and failures

​

Issue, dispatch, job and run

This page uses four words for four different things:

• Issue — the ticket in Linear or Jira that you flag.
• Dispatch — the orchestrator starting a workflow for that issue.
• Job — the orchestrator’s record of one dispatch, and what carries a status.
• Run — the workflow execution itself, and what produces a failure message.

One issue can accumulate several jobs over time, and each job is matched to at most one run — a job whose run never appears is the run_not_found case below.

​

Issue lifecycle

AI-Implement moves each issue through a fixed set of stages. The diagram shows the stages and what moves an issue between them. Each stage shows up as a Linear label or a Jira status:

​

Ticket comments

AI-Implement comments on the issue it is working so you can follow a run from your issue tracker, without watching the admin UI or the GitHub Actions logs.

• Progress comments — posted at each stage of a session run.
• Outcome comments — posted when a run opens a pull request or fails.
• Run stats — a per-pass breakdown, posted when the review approved the work.
• Run autopsy — the same breakdown when it did not.

​

Progress comments

When a run executes in a session (Fly Machines or local Docker), AI-Implement posts a comment at each stage:

​

Outcome comments

These report how a run finished:

• A pull-request link, posted when the run opens a PR.
• A failure notice when a run errors out: ⚠️ Planning failed: {reason} or ⚠️ Implementation failed: {reason}.
• A log excerpt, posted on a terminal failure or timeout and labeled with the context below.
• An explanation of the outcome, posted whenever a run did not finish cleanly.

What the explanation says depends on how the run ended: Each one also links to the troubleshooting guide. A run that finished cleanly gets no explanation, and neither does a sweep that tidied up an issue already marked done — there is nothing to account for.

​

Run stats and autopsy

An implementation run closes with a table of its passes, one row each:

• The iteration number
• What the implement pass did
• How many turns it took
• What it cost
• Whether review approved it

Which comment carries that table depends on how the run ended:

• Run stats, when review approved the work. Adds the total cost across passes, and compares the files the plan declared against the files the run actually changed.
• Run autopsy, when it did not. Names the reason the run stopped, quotes the reviewer’s final feedback, and links the draft pull request holding the work — or says none could be opened, when the run produced no changes at all.

​

Blocker reasons

The orchestrator checks for eligible issues on a schedule. When it skips one, the Blockers view in the admin UI shows why. Most reasons clear on their own once the condition changes — a slot frees up, or the issue’s dedup entry is cleared — but no-mapping needs you to add a project mapping. For step-by-step help when an issue is not picked up, see Troubleshooting.

​

Job status values

Each job moves through these statuses, shown in the dispatch log and the issue list. Non-terminal statuses describe a run still in flight; terminal statuses are the final outcome and do not change afterward. A timed_out status carries one of these reasons: For how completion statuses appear in Slack or Teams, see Notifications.

​

Overdue run recovery

A run does not hang forever when it stops reporting back. The orchestrator checks every job on its poll cycle and recovers the ones that have gone quiet. A run is overdue once it has stayed non-terminal for its project’s configured Job Timeout (min) plus a short grace period, counted from the moment its job was dispatched. The run hit the time limit covers where that timeout is set and how to raise it. Recovering one, the orchestrator:

• Cancels the workflow run, when one was ever linked to the job.
• Clears the issue’s in-progress marker and its dedup entry, which together are what make it eligible again.
• Leaves the next poll to dispatch a fresh job against the same issue.

The retry is bounded to three attempts, counted per issue and shared with ordinary run failures, so a mix of the two draws down one budget. On the fourth, recovery stops, and the orchestrator instead:

• Posts an AI Implementation Stuck — Needs Human comment on the ticket, naming the attempt count and the last run.
• Sends a notification, when a webhook is configured to receive one.
• Leaves the dedup entry in place, so no poll picks the issue up again.

An eligible issue stopped being dispatched covers how to tell this apart from a parked issue, and how to clear it.

​

Run failure messages

When a planning or implementation run fails, AI-Implement posts the reason on the issue as ⚠️ Planning failed: {reason} or ⚠️ Implementation failed: {reason}. The {reason} pairs a short note about which step failed with the underlying error from the tool involved (Claude, git, or the package manager). The most common failures are listed below.