# Lifecycle and checkpointing

Follow a run from admission through provider execution, workspace durability, cancellation, and cleanup.

The run is the durable product object. Workers and sandboxes are replaceable execution resources around it.

```mermaid
sequenceDiagram
  participant Client
  participant API
  participant Worker
  participant Sandbox
  participant Provider
  participant Store as Checkpoint store

  Client->>API: Start or continue run
  API->>API: Authenticate and admit
  API->>Worker: Queue turn
  Worker->>Sandbox: Create or restore runtime
  Worker->>Provider: Run model loop
  Provider-->>Worker: Model output and tool calls
  Worker->>Sandbox: Execute tools and hooks
  Sandbox->>Store: Save workspace checkpoint
  Store-->>Worker: Checkpoint ready
  Worker-->>Client: Complete turn
  Worker->>Sandbox: Stop on cancellation or cleanup
```

## Why checkpoint after a successful turn

The completed turn and workspace mutations form one durability promise. If
Salambo marked the turn complete before preserving required workspace changes,
a replacement sandbox could continue the conversation with missing files.

Checkpointing after each successful state-changing turn means Salambo can recreate the sandbox and restore the workspace before a durable follow-up.

## Follow-up turn

For an existing run, Salambo restores session state, active model, thinking level, active tools, and the latest ready workspace generation before continuing.

## Cancellation

Cancellation stops active model and extension work, then finalizes turn state
and sandbox cleanup. Cancelling one turn does not discard earlier completed
turns in the same run.

## Deployment upgrade

With automatic workspace upgrades, Salambo checkpoints the current workspace, creates a sandbox from the new deployment, restores the run state, validates it, and switches authority only after the replacement is ready.

See [durable workspaces](/docs/operate/durable-workspaces) and [run diagnostics](/docs/operate/diagnostics) for operational evidence.