Worker Lifecycle

Every worker follows a defined lifecycle from creation to termination. Understanding these states helps you design templates, handle failures, and interpret trajectory data.

States

State	Description	Billed
Pending	Worker created, waiting for resources	No
Spawned	Resources allocated, workstation assembling	No
Running	Worker is executing its task or instructions	Yes
Suspended	Paused by the platform or operator (resumable)	No
WaitingApproval	Blocked on a human approval gate	No
Completed	Task finished successfully	No
Failed	Worker encountered an unrecoverable error	No
Stopped	Terminated by operator or timeout	No

State transitions

                    +-----------+
                    |  Pending  |
                    +-----+-----+
                          |
                    +-----v-----+
                    |  Spawned  |
                    +-----+-----+
                          |
                    +-----v-----+
               +--->|  Running  |<---+
               |    +--+--+--+--+    |
               |       |  |  |       |
    +----------+--+    |  |  |    +--+-------------+
    |  Suspended  |    |  |  |    | WaitingApproval |
    +-------------+    |  |  |    +----------------+
                       |  |  |
            +----------+  |  +----------+
            |             |             |
      +-----v----+  +----v---+  +------v--+
      | Completed |  | Failed |  | Stopped |
      +----------+  +--------+  +---------+

• Running / Suspended: A worker can be suspended and resumed (e.g., for cost control or rate limiting)
• Running / WaitingApproval: Workers pause when they hit an approval gate, and resume when the human approves
• Running to Completed: Task workers transition here when the task finishes successfully
• Running to Failed: Unrecoverable errors (model failure, sandbox crash, exceeded retries)
• Running to Stopped: Operator-initiated stop (arpi stop) or timeout expiry

Timeline events

Every state change is recorded as a timeline event. View them with:

arpi timeline <worker-id>

Each event includes:

• Type — The state transition or action (e.g., state.running, tool.call, approval.requested)
• Timestamp — When it occurred
• Duration — How long the state or action lasted
• Payload — Detailed data (tool call arguments, error messages, approval context)

Timeline events are the foundation of trajectories. A trajectory is the full sequence of events from spawn to terminal state.

Billing behavior

• Billed states: Only Running accrues compute costs
• Paused states: Suspended and WaitingApproval pause billing — the worker’s sandbox is preserved but not consuming compute
• Terminal states: Completed, Failed, and Stopped end billing permanently

This means you can design long-running daemon workers that suspend between tasks without accumulating idle costs.