> ## 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 — Admin Guide

> Tenant-admin guide for durable multi-agent runs: the activation gate, guardrail-spine prerequisites, run permissions, monitoring, and emergency stop.

## Overview

PF-125 wraps the in-stack agentic loop in a **durable, resumable, checkpointed
run-state machine**. Authoritative state lives in four organization-scoped tables
under FORCE row-level security (`pf_agent_runs`, `pf_agent_tasks`,
`pf_agent_run_checkpoints`, `pf_agent_run_events`). Runs act under a **scoped
AgentPrincipal** (PF-30-EN-01 `pf_agent_can`) — never `service_role`, never
`auth.uid()` impersonation.

This guide covers the controls a tenant administrator owns. For step-by-step
incident handling, see the operator runbook in
`docs/runbooks/pf-125-agent-runs.md`.

## Activation gate (PF-45 flag)

Interactive agent tool use is gated by the feature flag
`pf.agents.interactive_tools_enabled`, seeded **off**. Flipping it on in
production is a **human decision**, not a deploy step, and it is **not** a
substitute for the guardrail spine — both must hold before any tool reaches a
model.

Enable it **per organization** (never globally as a first step): turn it on for
one pilot org, drive a single read-only run, watch the Run Timeline audit trail
end to end, then widen. To roll back, set the flag to `false`; tool use stops on
the next request because the gate is evaluated per request.

## Guardrail spine prerequisites

An agent's tools reach a model only when the full spine holds **and** the flag is
on, on every path identically:

1. a scoped AgentPrincipal is bound to the run,
2. redaction is active (PF-27-EN-01),
3. a budget check is available (PF-111),
4. injection screening is enabled (PF-126).

In the current release, redaction and injection screening are not yet built, so
the spine is unsatisfiable and tools are withheld fail-closed. A write-capable run
that reaches the boundary off-spine is refused outright and advanced to `failed`
— never silently downgraded. Confirm all four prerequisites are live before you
consider enabling the flag.

## Permissions

* `pf.agents.runs.view` — see the Run Timeline panel.
* `pf.agents.runs.manage` — Cancel and Resume runs.

Grant these through the standard role/permission administration screens. Both are
organization-scoped; a user only ever sees runs for their own organization under
FORCE RLS.

## Monitoring

The Run Timeline panel (**Settings → Platform → Agents → Runs**) is the primary
monitoring surface. The lifecycle event types are **registered** in the
workflow-events catalog (`pf_agent_run_started`, `pf_agent_run_checkpointed`,
`pf_agent_run_completed`, `pf_agent_run_failed`, `pf_agent_run_budget_exceeded`;
`owning_core: pf`, `category: platform`) so downstream automation and dashboards
can subscribe — the runtime emitters land with the flag-on rollout, not in Phase 1.

## Emergency stop

1. Set `pf.agents.interactive_tools_enabled` to `false` for the affected org (or
   all orgs) — new requests get zero tools on the next call.
2. Cancel each non-terminal run from the panel, or via
   `pf_agent_run_advance(<id>, 'cancelled', '<reason>')`.
3. Review the `pf_agent_run_events` audit trail for the affected runs and
   correlate with `pf_agent_can` grants if a scope looks wrong.

Never bypass the state machine with a direct SQL `UPDATE`: a BEFORE-UPDATE trigger
rejects any direct write to `lifecycle_state` (even by `service_role`), and doing
so would break the audit trail. State changes go only through the governed RPCs.

## Auditing & data handling

* Every run, task, checkpoint, and event is `organization_id`-scoped under FORCE RLS.
* No PHI is written to prompts, logs, code, or tests; redaction must be live
  before the flag is enabled.
* Checkpoints may carry working state and honor a retention expiry; the audit
  event trail is append-only.

## Related

* [User guide](./pf-125-user-guide.md)
* Operator runbook: `docs/runbooks/pf-125-agent-runs.md`
* ADR: `docs/architecture/decisions/ADR-026*.md`
* Source spec: `specs/pf/specs/PF-125*.md`