Skip to main content
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.
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.

​
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.
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.

Cloud and device

Where a run executes and how to choose.

Approvals and questions

How a run hands control back to you.