# Orchestrator runtime invariants

- Every exit persists a `CompletedRequest`.
- A provider `stop` is successful only when the terminal, tool-less response
  contains user-visible output. Reasoning-only stops emit a fatal error and
  persist the final assistant message as failed.
- Literal pseudo-tool markup inside reasoning is never executed. It is
  classified as `unparsed_tool_call`, allowing the user to retry or choose a
  model whose tool template is compatible.
- Client hosts receive the same terminal semantics as server-hosted runs.
- The executor is the single owner of provider exception logging, retry state,
  and terminal error emission. Provider adapters classify and annotate, then
  re-raise; they never print tracebacks or emit a provisional fatal error.
- Raw transport exceptions are classified by type before provider-specific
  string matching. Empty-message `httpx` failures retain a non-empty exception
  name and become `connection_error` / `provider_timeout`, never blank
  `unknown_error`.
- `usage_history` is exact provider-call history. Every billed failed attempt
  is harvested before retry and every successful attempt is stamped with its
  logical iteration. Legacy `cx_request` persistence groups calls into the one
  iteration row while preserving attempt-level models, tokens, outcomes, raw
  usage, and catalog costs in row metadata.
- Every image/video provider call is completion-shielded independently of its
  caller. Cancellation waits for the paid operation, asset + conversation
  response persistence, and usage capture, then propagates; it never discards
  an in-flight generation.
- **Out-of-lane request snapshots use a one-shot ORM `Session`.** The durable
  conversation gate commits the parent first; `_write_request_snapshot` then
  uses an explicit `allow_direct_coordinator_write` acknowledgement because no
  request `Coordinator` exists to own the append-only audit row.
- A scheduled `provider_retry` carries `discard_partial_output=true`. Clients
  rewind all text, reasoning, render blocks, citations, and content timeline
  entries emitted since that iteration's `cx_request` reservation before
  accepting output from the replacement attempt.

Verified against `executor.py`, `conversation_gate.py`, and the Coordinator
firewall on 2026-08-19.

## Change log

- 2026-08-19 — Made the intentional out-of-lane snapshot write explicit and
  transactionally governed.
