---
title: Session lifecycle
description: The states a session machine moves through, the timeouts that drive them, and the resume contract.
status: draft
sidebar:
  order: 1
---

## Machine states

| State | Meaning |
|---|---|
| `bootstrapping` | VM provisioning and warm-up |
| `ready` | warm in the pool, waiting to be claimed |
| `claimed` | owned by a session (sub-state: `active` while a turn runs, `idle` between turns) |
| `dead` | released or reaped; may be `preserved` for diagnostics |

## Timeouts (org-configurable; these are the defaults)

| Timeout | Default | What happens |
|---|---|---|
| session inactivity | 15 min | the agent process winds down silently; your claim on the machine survives, and a thread reply re-attaches |
| claimed idle | 12 h | a long-idle claim is auto-released |
| ready max age | 4 h | warm machines are recycled (clamped below the compute provider's VM lifetime) |
| provision | 30 min | a machine that hasn't come up is abandoned and retried |
| claim queue | 5 min | how long a session request waits for capacity |

## Resume tiers

A reply resumes a session through the first tier that applies:

1. **Live claim** — the machine is still yours; the session re-attaches in
   place, with full working state.
2. **Checkpoint restore** — the machine is gone, but the last consistent
   checkpoint restores onto a fresh machine. History is preserved; a session
   is resumable whenever a checkpoint exists and the session wasn't
   explicitly released.

Checkpoints are taken after every agent turn; retention and size caps are in
[limits](/sessions/reference/limits/).

## Failure modes

- **Fleet at capacity** — requests return HTTP `529` with a retry message;
  the claim queue holds your spot for up to 5 minutes.
- **Broker restart** — sessions and history are preserved; idle sessions
  reconnect within seconds and affected threads get a restart notice.
- **Transport drop mid-turn** — the session recovers or surfaces an error
  attributed to transport, agent, or broker — reply-to-resume keeps working.