Run Lifecycle

An agent that works with humans spends much of its life waiting — for an approval, for a reply, for Monday's schedule. This page is the contract for that time: what a pause is, what survives a restart or a deploy, what is retried, and what is charged.

The shape of a run

A session is the long-lived conversation between a customer and an agent. A run is one unit of execution inside it: pending → running → succeeded | failed | cancelled. Every run starts on a fresh machine that belongs to its workspace and is destroyed when the run ends; webhooks report the terminal state. What outlives the machine is everything written along the way: the transcript, the run record, the workspace files, and the meter.

A wait releases the machine

A run can stop mid-work to wait — for an approval, for the customer's reply, for a sub-agent, or for a scheduled time. A pause is not a sleeping process:

1. The turn's position is checkpointed to the database, and the agent's workspace files are kept.
2. The run ends and its machine is released.
3. Whatever it was waiting for arrives — the decision, the message, the schedule firing — and dispatches a new run on the same session, which resumes from the checkpoint instead of from the top.

Between those two runs nothing is executing and nothing is being metered. A wait is rows in a database; holding one for a minute or for a month costs the same: nothing.

What survives

A worker restart, a platform deploy, or a reclaimed machine does not lose:

• The session — the transcript and run records live in the database, not in any process.
• The checkpoint — a turn interrupted mid-work resumes from its last completed step.
• Pending waits — an approval waiting on a decision, or a schedule waiting for its time, is a database row. A deploy neither drops it nor fires it twice.
• The ledger — everything already metered stays metered, once (see below).

The machine is the one disposable part, by design. Work a step has done but not yet written to the workspace or the transcript when its machine dies is redone by the retry, not recovered.

What is retried

A run stopped by a platform fault — a worker restart, a machine dying, a timeout — is re-woken automatically, up to five attempts. Because the checkpoint and the workspace persist, a retry continues from where the work stood rather than starting over. Side effects that must fire once — dispatching a sub-agent, recording a message — are checkpointed before the wait they open, so a retry re-enters the wait instead of re-firing them.

A run that still fails is reported as run.failed with the session intact: the next trigger or message continues from the same state.

A retry does real work, and the model calls it makes are metered like any others. What is never duplicated is the accounting of work already done.

What is charged, once

Two meters, both attributed per workspace: model usage, one debit per model request, and compute, one debit per run for its wall-clock execution time — started_at to finished_at. Waits fall between runs, so they land on neither meter. Machine start-up and post-run idle aren't billed either: compute charges cover execution time.

Every debit is keyed to a stable event ID, and the ledger enforces uniqueness on that key. A redelivered event, a restarted consumer, or two code paths reaching the same terminal state write one row. The compute debit for a run is keyed to the run's ID, so no retry, replay, or restart can bill the same run's time twice.

You can check this against the numbers: GET /api/v1/org/usage reports month-to-date spend per workspace. Leave a fleet waiting on approvals overnight and read it twice — spend moves when runs execute, not while they wait. For per-run granularity, the Analytics endpoints show each run's compute charge matching its execution time, with no line item for the gaps between runs.

Timeouts, in three layers

Execution is bounded at three layers, each with a defined outcome:

Timeouts bound execution, not waits: a run waiting for an approval has no machine and no running step, so there is nothing for a timeout to stop. The wait ends when the answer arrives — whether that takes an hour or a week.