# Run states and labels

Interpret local state, pull-request labels, and terminal outcomes.

| State | Meaning |
| --- | --- |
| pending | Run created but not started |
| migrating | Cloud agent is working |
| pr_opened | PR located; gate not started |
| testing | Checks or local gate running |
| retrying | Agent resumed with gate output |
| ready | Gate passed; human review remains |
| needs_attention | Retry budget ended without a passing gate |
| error | Pipeline could not complete |

## PR labels

PatchFlow removes the opposite label when an outcome changes. It also writes a PR comment with the gate mode and evidence.

- patchflow:ready — configured gate passed
- patchflow:needs-attention — configured gate failed

## Local state

State stores the most recent 100 runs and the last-seen package version. Writes are atomic and each pipeline update reloads current state before saving.

```
.patchflow/state.json
```