Runs, cancellation, and recovery

A run executes a deployed agent program step by step. Stead records durable events, results, approvals, and reported costs. A customer starts only the program published in the agent’s endUserRuns configuration.

Start and follow

Use client.startRun({ agent, input, async: true }), then client.streamRun(run.id). The asynchronous start response acknowledges a run; it is not evidence that all its steps completed.

Status	Meaning
running	Work is executing or eligible for recovery.
awaiting-approval	A gated action is waiting for an owner decision.
completed	The program finished.
failed	The run ended with a failure; inspect its trace.
budget-exceeded	Recorded spend reached a configured cap.
cancelled	The server recorded cancellation.

The client may show unknown before receiving a durable event, and the React hook shows idle before sending anything. Connection status is separate from run status: a closed browser connection does not mean a run was cancelled.

Project owners can inspect runs in the console or terminal:

npx --yes getstead@0.2.1 runs
npx --yes getstead@0.2.1 runs --status awaiting-approval
npx --yes getstead@0.2.1 trace "$RUN_ID"

Set RUN_ID to an ID from the list. Traces can contain customer inputs and tool results. Share only the diagnostic details needed to explain a failure.

Streaming and reconnection

The stream uses server-sent events. Durable events carry sequence numbers; the client reconnects with the last sequence it received. Model deltas are temporary display updates, without sequence numbers. They are not replayed token by token after reconnect; completed step results are authoritative.

stream.close() or an aborted stream signal stops watching. It does not cancel server execution. Keep consuming the stream, or subscribe to its state if your UI only needs a status indicator. See the client reference for reconnection bounds and errors.

Cancel on the server

Call client.cancelRun(runId) for a customer’s own run, or use Cancel run in the owner’s console. A 202 response means cancellation was requested and is still settling. Continue watching until a terminal event arrives. If the run already ended, its existing terminal outcome remains authoritative.

Cancellation cannot undo an external action that already happened or refund provider usage. The React hook’s stop() requests server cancellation and keeps watching; unmounting the hook only detaches its local work.

Recover an interrupted run

The hosted service automatically retries eligible interrupted work. The trace can report the next recovery attempt and the last infrastructure error. Completed checkpoints are reused. A handler interrupted before its result was committed may run again with the same idempotency key; external effects require the tool’s own deduplication.

For an owner-initiated manual retry of an existing run:

npx --yes getstead@0.2.1 run --resume "$RUN_ID"

Do not supply a scenario with --resume. The server uses the recorded program. If another execution already owns the run, the CLI waits for its result for up to three minutes before directing you to the trace.

An error after a mutation can leave its result uncertain. Refresh the run, deployment, or project state before repeating the change. Starting a new run is different from resuming the existing one and can repeat real-world effects.