Session Lifecycle - Human in the Loop

State machine

active ──pause──▶ paused ──resume──▶ active
  │                                     │
  └──complete──▶ completed ◀────────────┘

active / paused ──idle 24h──▶ abandoned (TTL 30d, then deleted)

Each transition is its own endpoint and each rejects invalid transitions with 409 Conflict.

Pause

POST /v1/api/sessions/{id}/pause

Transitions active → paused. Paused sessions reject new turns.

Resume

POST /v1/api/sessions/{id}/resume

Transitions paused → active.

Complete

POST /v1/api/sessions/{id}/complete

Transitions active|paused → completed. Complete is terminal and idempotent — calling it on an already-completed session returns the session with no error.