Agent Runs
Every time an AI worker is dispatched to perform a task, the system creates an agent run — a structured record of what happened, how long it took, what it cost, and what it produced. Agent runs give you full visibility into worker activity without digging through log files.
What agent runs track
An agent run captures everything about a single dispatch:
| Data | What it records |
|---|---|
| Worker | Which worker instance was dispatched |
| Work item | The PPM work item that triggered the dispatch (if applicable) |
| Backend | The execution backend used (e.g. claude-code, codex, aider) |
| Model and provider | The actual model and provider used — which may differ from the preference if failover occurred |
| Tokens | Input and output token counts |
| Cost | Total cost in USD |
| Duration | Execution time in milliseconds |
| Branch and MR | The git branch created and the merge request URL (if applicable) |
| Status | The outcome of the run |
| Error details | Error message and exit code on failure |
Run lifecycle
Every agent run follows a defined lifecycle from creation to completion:
| Status | Meaning |
|---|---|
| RUNNING | The worker has been dispatched and is actively executing |
| SUCCESS | The run completed normally and produced valid output |
| FAILED | The run encountered an error during execution |
| TIMEOUT | The run exceeded its allowed time limit |
| BUDGET_EXCEEDED | The run was stopped because it would exceed the configured cost budget |
| INVALID_OUTPUT | The run completed but its output did not pass validation |
A run is created with status RUNNING at the moment of dispatch. When the worker finishes — successfully or not — the status is updated to one of the terminal states along with the final metrics (cost, tokens, duration).
A run that remains in RUNNING status beyond its expected duration indicates a crash or an unresponsive worker. The system uses this as a signal for crash detection — orphaned RUNNING records are flagged for investigation.
Run steps
Each agent run is broken down into steps — a structured trace of the phases the worker goes through during execution. Steps provide a timeline of what happened within a run, making it straightforward to identify where a failure occurred or where time was spent.
Steps are recorded in execution order:
| Step | What happens |
|---|---|
| CONFIG_RESOLVE | Resolve the worker's effective configuration (model, tools, prompts) |
| WORKTREE_CREATE | Create an isolated git worktree for the worker to operate in |
| BACKEND_DISPATCH | Send the task to the AI backend and wait for completion |
| MR_CREATE | Create a merge request from the worker's changes |
| EVAL | Trigger quality evaluation of the worker's output |
| GUARDRAIL | Run any configured guardrail checks |
| CLEANUP | Clean up temporary resources (worktrees, temp files) |
Each step tracks its own status (RUNNING, SUCCESS, FAILED, SKIPPED), start and end timestamps, and optional input/output summaries. Not every run includes every step — for example, a run that fails during BACKEND_DISPATCH will not have an MR_CREATE step.
Reading a step trace
A typical successful run produces a step trace like this:
| Order | Step | Status | Duration |
|---|---|---|---|
| 1 | CONFIG_RESOLVE | SUCCESS | 1.2s |
| 2 | WORKTREE_CREATE | SUCCESS | 3.4s |
| 3 | BACKEND_DISPATCH | SUCCESS | 142.7s |
| 4 | MR_CREATE | SUCCESS | 5.1s |
| 5 | EVAL | SUCCESS | 0.3s |
| 6 | CLEANUP | SUCCESS | 1.8s |
This makes it clear that the vast majority of time was spent in BACKEND_DISPATCH — the actual AI execution. If a run is slow, the step trace tells you whether the bottleneck is in configuration resolution, worktree setup, or the AI backend itself.
Run artifacts
A run can produce artifacts — output files and content generated during execution. Artifacts are stored alongside the run record so you can review what the worker produced without searching through file systems or git history.
| Artifact type | What it contains |
|---|---|
| OUTPUT_JSON | The structured JSON output from the worker (status, summary, file list) |
| DIFF | The git diff of changes the worker made |
| LOG | Execution log output |
| MR_DESCRIPTION | The merge request description the worker generated |
Small artifacts are stored inline as text content. Larger artifacts (such as full execution logs) are stored by reference — the run record contains a pointer to the artifact's storage location rather than the content itself.
How agent runs connect to other modules
Agent runs sit at the intersection of several platform modules:
- PPM — a work item triggers the dispatch that creates the agent run. The run links back to the work item, so you can see all runs associated with a piece of work.
- WRM workers — the run records which worker was dispatched and which model/provider it actually used.
- FND jobs — each dispatch creates a Foundation job record for concurrency control. The FND job system enforces limits on how many workers can run simultaneously.
- Eval scorers — after a successful run, evaluation scorers can assess the quality of the work. Eval results are linked to the run they assessed. See Eval Scorers for details.
- Cost management — run cost data feeds into budget tracking and provider health monitoring. See Cost Management for details.