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

# Agent runs: watch Zespan investigate an issue

> A run is one capped investigation of a Failed issue, in seven steps you can watch, pause, stop or continue.

An **agent run** is one investigation of one issue. It reads the issue's own traces, works out the cause, runs proofs that spend nothing, and writes drafts for you to review. You can watch it step by step on its own page, pause it, or stop it.

> [!NOTE]
>
> Runs need the **Pro** plan or higher, and the organization's AI processing must be on. Where runs are not enabled the run page and **Assign to Zespan** are not shown.

## What starts a run

A run starts on its own when an issue is all of these:

* **Failed** (a Degraded issue never starts a run on its own)
* **proven**, not likely
* **open**, with at least 3 occurrences
* seen in the last 24 hours, with its newest occurrence still inside your retention window

An issue gets one automatic run per occurrence band (3 to 29, 30 to 299, 300 and above), and never within 24 hours of its last one. A fix that regressed, or an issue that reopened after you resolved it, starts one new run. Only one run is active in a project at a time.

You can always start a run yourself on any open issue with **Assign to Zespan**. A run you start does not count against the automatic-run limit.

> [!NOTE]
>
> **Degraded issues wait for you.** A Degraded issue never starts a run by itself. It shows **Assign to Zespan**, and a suggestion that was already written for it stays visible.

## What a run may and may not do

A run **may** read this project's traces, spans, findings, scores, changes and issues, work out a cause, run proofs that touch nothing live, write drafts, add items to [Needs you](https://docs.zespan.com/dashboard/needs-you.md), and write its own rows in [Activity](https://docs.zespan.com/dashboard/activity.md).

A run **never** applies anything (a policy, guardrail, alert rule, prompt version, SDK setting or cost action), changes an issue's state (no resolve, dismiss or escalate), runs your tools, or lets text from a trace choose what it does. It reports a cause only when it can ground it in what it read. "Not checked" is a valid result.

## The limits

Limits are counts. Every one is checked before the work it limits.

| Scope | Default |
| - | - |
| One run | 16 model calls (retries included), 24 tool calls, 10 minutes of running time |
| One project, per UTC day | 5 automatic runs |
| One organization, per UTC day | 15 automatic runs |
| Plan ceiling | Pro: 2 times these counts. Team and above: 5 times |

When the day's automatic runs are used, the issue says `Not investigated` with the time the limit resets, shown in your own time zone. **Run now** starts a run by hand where there is room, and owners and admins can change the limit. When several Failed issues wait for tomorrow, [Home](https://docs.zespan.com/dashboard/home.md) says how many.

## Change the limits

The automatic-run limits live in two cards. Both show counts, never money, and both are shown only where runs are on.

| Card | Where | Who | What it holds |
| - | - | - | - |
| **Automatic runs** | Settings > General | Owners and admins | The toggle **Start runs on their own for Failed issues**, the number **Automatic runs per day** (0 to the most your plan allows), today's count (`Today: 3 of 5 automatic runs used`) and the note `Up to <max> on your plan.` |
| **Automatic runs for this organization** | Admin > Settings | Owners only | The organization's number **Automatic runs per day** and today's count across all projects |

Press **Save**. The result appears in a line under the form, and focus moves to it. If the count could not be read, the card says `Today: not available` rather than showing 0. A limit of 0 turns automatic runs off for that project or organization. A run starts only when both the project's limit and the organization's have room. A run you start yourself is not counted. When an issue says `Not investigated` because the limit is reached, its **Change limit** link goes to the matching card.

## The run page

Open a run from the issue, or from the top-bar chip while one is running.

**1. Read the head**

The head shows the run's title, its status (`Queued`, `Running`, `Paused`, `Done`, `Stopped at limit`, `Stopped` or `Failed`), how many model calls it has used, and why it started.

**2. Follow the steps**

The ledger has one row per step: read the issue, pick sample runs, read where each run breaks, check recorded changes and findings, work out the cause, run zero-spend proofs, write drafts. Each row shows what it looked at, a count, its state and how long it took. Only the step that is running opens its log lines.

**3. Review the drafts**

The drafts panel reads **Drafting** until the run finishes. Then each draft appears with a link to Needs you, where you decide. A run never applies a draft.

Below the ledger, **Zespan's own trace** draws one bar per step on a shared time axis, so you can see where the time went.

A screen reader announces one line, `Step 5 of 7 running: Worked out the cause`, when the running step changes, and `Run Done.` when the status does. It says nothing on a refresh that changes neither, and nothing once the run has ended.

## Pause and Stop

* **Pause** takes effect before the next step. A paused run keeps the project's one run slot and its time does not count against the 10 minutes. After 30 minutes paused it stops, with the reason "paused too long". **Resume** continues at the first unfinished step.
* **Stop** asks first: `Stop this run?`. Drafts whose evidence is complete are kept and marked partial.

## Stopped at limit

When a run reaches its per-run limit it stops with the status **Stopped at limit** and the line `Stopped · run limit reached after step 5 of 7`. Drafts whose evidence is complete are kept and marked, for example, `Partial · cause not confirmed · 3 of 5 sample runs read`. A **Not checked** list names what was skipped.

## Continue run

**Continue run** appears only on a run that stopped at its limit. It starts one new linked run at the first unfinished step, with its own per-run limits and the same daily limits. The page then shows both runs as one ledger, with a divider reading `Continued by <initials> at <time>`. People without access to the audit log see `team` in place of initials. A run can be continued once.

## Next steps

* [Issues](https://docs.zespan.com/dashboard/issues.md): Assign to Zespan and where a run starts
* [Needs you](https://docs.zespan.com/dashboard/needs-you.md): the drafts a run leaves for you
* [Home](https://docs.zespan.com/dashboard/home.md): the last run, and issues waiting for the limit
* [ZespanPilot](https://docs.zespan.com/dashboard/zespanpilot.md#what-the-agent-may-do): what the agent may and may not do
* [Activity](https://docs.zespan.com/dashboard/activity.md): the rows a run writes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.