> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Runs — User Guide

> How to read the Run Timeline panel: lifecycle states, write-capable badges, principal attribution, and the live audit trail for durable multi-agent runs.

## Overview

A **run** is one agent task with a tracked lifecycle, an append-only audit trail,
periodic checkpoints, and a hard token/step budget. The Run Timeline panel lets
authorized users watch those runs end to end without touching any control surface
— it is read-only except for the governed Cancel and Resume actions.

<Note>
  Interactive agent tool use is **off by default** in the current release (the
  PF-45 flag `pf.agents.interactive_tools_enabled` is disabled and the guardrail
  spine is not yet fully wired). Until an administrator enables it, there is no
  run-creation path and the Run Timeline shows the empty state. The panel exists
  so the audit trail is observable the moment the durable path goes live.
</Note>

## Opening the Run Timeline

Navigate to **Settings → Platform → Agents → Runs**
(`/settings/platform/agents/runs`). The panel requires the `pf.agents.runs.view`
permission; managing a run (Cancel / Resume) additionally requires
`pf.agents.runs.manage`. If you do not see the menu entry, ask your administrator
to grant the view permission.

## Reading a run row

Each row summarizes one run:

* **Skill** — the agent task the run is executing.
* **Lifecycle badge** — the current state (see below).
* **Write-capable badge** — shown when the run is permitted to make changes, not
  just read. Treat write-capable runs with extra scrutiny.
* **Principal** — the scoped agent identity bound to the run, shown as the **last
  four characters only** for attribution. Agents never act as `service_role` or
  impersonate a user.
* **Budget** — token usage against the run's hard budget.
* **Audit trail** — expand the row to see every lifecycle transition (from → to)
  with its reason and timestamp.

## Lifecycle states

| State                 | Meaning                                          |
| --------------------- | ------------------------------------------------ |
| `queued`              | accepted, not yet started                        |
| `running`             | actively executing                               |
| `waiting_approval`    | paused pending a human decision                  |
| `paused` / `resuming` | suspended, then being restored from a checkpoint |
| `completed`           | finished successfully (terminal)                 |
| `failed`              | stopped on an error (terminal)                   |
| `cancelled`           | stopped by an operator (terminal)                |
| `budget_exceeded`     | hit its token/step budget (terminal)             |

Terminal states have no further transitions. A `cancelled` run cannot be resumed.

## Cancelling or resuming a run

With the manage permission you can **Cancel** a non-terminal run or **Resume** a
`paused` run directly from the panel. Both actions route through governed RPCs —
the UI never writes the lifecycle state itself, so the audit trail always reflects
exactly what happened.

## Related

* [Admin guide](./pf-125-admin-guide.md)
* Operator runbook: `docs/runbooks/pf-125-agent-runs.md`
* Source spec: `specs/pf/specs/PF-125*.md`