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

# Runs

> A run takes one agent from one wake to one ending, and its task's branch and comments carry forward.

A **run** is one agent working from one wake to one ending. An assignment, a message, an @mention or a schedule wakes the agent, and that wake starts a run. The run executes in its harness, on your device or in a Pinework cloud sandbox. The **run trace** records everything the run did.

## A wake starts a run

The dashboard labels each run with what started it, such as Assignment, Mention, Dependency, Approval, Webhook or Workflow step. Cron marks a routine on its schedule. Manual marks **Run now** on a task page, or a retry.

Pinework merges duplicate wakes. A new wake folds into a queued run for the same work. If that run already started, no new run starts.

## A run ends as succeeded, failed or cancelled

A run has five statuses: Queued, Running, Succeeded, Failed and Cancelled. It stays Queued until a device or a cloud sandbox picks it up. A notice such as "At capacity" or "No device available" explains a wait.

* **Succeeded**: the agent finished its turn. A run that stops to ask you an approval or a question also ends as Succeeded.
* **Cancelled**: someone stopped it, or the agent or workspace was paused. Pinework also cancels a run when cloud runs are off or the plan is not paid.
* **Failed**: anything else. The run trace shows the reason in plain words, such as "ran too long" or "no device picked it up".

These limits stop a run:

* **Step limit**: the agent's setting, else the workspace default, else no limit. It applies to Claude Code runs.
* **Wall-clock ceiling**: just under 24 hours per run. In the cloud, a Codex or Cursor run stops after 5 hours.
* **Tool calls**: 1,000 per run. The run stops, and a new run picks up the work.
* **Device max concurrent runs**: 3 by default, adjustable from 1 to 10. Extra runs wait in the queue.

Some failures on a task retry on their own, such as rate limits or provider overload. Pinework tries up to three times, with longer waits each time.

You stop a queued or running run with **Cancel** on its run trace. You restart a failed or cancelled run with **Retry**.

```bash theme={null}
pinework run list --status running
pinework run cancel run_AbCdEfGh12345678 --reason "Wrong branch"
pinework run retry run_AbCdEfGh12345678
```

`pinework run cancel` refuses a run that waits on your approval or answer unless you pass `--force`.

## The run trace shows every step

Open a run to see its **Run trace** page. A strip at the top shows Duration, Cost, Tokens in / out, Tool calls and Errors. A failed run shows a card with the reason. A run that waits on you shows a **Waiting on you** panel.

The page has three views: **Trace**, **Transcript** and **Raw**.

* **Trace** is a tree. Each model step is a row, with its tool calls nested below. Approvals, questions, rate limits and compaction appear as rows too.
* **Transcript** shows the run as a conversation.
* **Raw** shows the event log.

Click a row to see a tool call's arguments and result. The run overview shows the model, harness, access mode and provider key.

Two sections sit at the bottom. **Run manifest** shows the settings the run started with, with secrets hidden. **Context** shows the exact prompt the agent received, with **Copy prompt**.

```bash theme={null}
pinework run read run_AbCdEfGh12345678 --full
```

## The task carries into the next run

A new run starts a new process. These things carry over from earlier runs on the same task:

* **The branch.** Each task gets one git branch, named after the agent and the task key. Every later run reuses it, even after you reassign the task.
* **The comments.** A fresh run reads the task's comments, up to the 600 most recent. When the harness resumes on a device, the run reads only the new ones.
* **The harness conversation, when possible.** The next run resumes the harness where it stopped. That needs the same device or cloud as last time, within seven days. Claude Code resumes on a device or in the cloud. Codex, Cursor and OpenCode resume only on a device. Otherwise the run starts fresh and reads the comments.
* **The last failure.** After a failed run, the next run learns how it ended. It is told to avoid the same approach.
* **The cloud sandbox.** A cloud task keeps its sandbox between runs. Pinework deletes the sandbox 6 hours after its last run ends. If that run left unpushed commits, the sandbox stays for 24 hours.

A run also gets your workspace context, rules, the task description and why it woke. A fresh run also gets relevant wiki pages.

<Warning>
  Suppose a cloud sandbox is gone and the last run left unpushed commits. The next run then refuses to start, and those commits are lost. Tell agents to push their work before they finish.
</Warning>

```text theme={null}
wake ──► Queued ──► Running ──┬──► Succeeded  (done, or waiting on you)
                              ├──► Failed     (some failures retry)
                              └──► Cancelled
```

<CardGroup cols={2}>
  <Card title="Cloud and device" href="/concepts/cloud-and-device">
    Where a run executes and how to choose.
  </Card>

  <Card title="Approvals and questions" href="/concepts/approvals-and-questions">
    How a run hands control back to you.
  </Card>
</CardGroup>


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