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) |
| Execution harness | The agent CLI or runtime used (e.g. Claude Code, Codex, Aider) — resolved from the selected model availability. See Execution Harnesses |
| Model | The canonical model used for the completed run |
| Provider | The provider used for the completed run |
| Model identifier | The provider-specific identifier sent in API calls |
| 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) and determine the execution harness |
| WORKTREE_CREATE | Create an isolated git worktree for the worker to operate in |
| HARNESS_DISPATCH | Send the task to the resolved execution harness 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 | HARNESS_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 HARNESS_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 execution harness itself.
Failover and per-attempt provenance
When failover occurs, the step trace records each attempt. Each attempt captures the model, provider, provider-specific model identifier, and execution harness that were used (or would have been used), along with the outcome. The final run record reflects the provenance of the successful or last attempt.
This means you can see not just which model the run ended up using, but which candidates were tried and why they were skipped — for example, a circuit breaker tripping on one provider, or a harness not being available on the current runner. See Execution Harnesses for details on cross-harness failover.
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, and execution harness 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.