Sessions and the two ledgers

A session is not a process and not a conversation. It is a durable machine plus the records that describe its work precisely enough to rebuild it.

The two ledgers

A session has exactly one history, and it is kept in two ledgers: the host event log, written outside the machine, and the transcript inside it. Both carry sequence numbers, so the two can be reconciled: on a resume, the service compares them and records the reconciliation before the program inside wakes. A fork starts a new lineage whose event log begins with a record of the parent and the point it branched from, so every lineage can be rebuilt from its own chain of records.

The state those ledgers point at is the session’s checkpoints: each one the whole machine saved at one moment (its disk, its memory and its device state). The boundary is the machine: a checkpoint does not include the provider’s model weights or the cache the provider keeps on its own servers, neither of which is KeepState’s to save (KV cache).

checkpoints    c_0000 -> c_0008 -> c_0016 -> c_0040 -> c_0041
event log      seq 1402, 1403, 1404, 1405, 1406, 1407 ...
fork           parent c_0040 · new lineage from seq 0

The block above illustrates lineage; it is not live data. That a killed agent resumed with the two ledgers reconciled, and the gap it closed recorded, is on the proof page.

The lifecycle

An agent session and a plain session go through the same steps, each with its own commands. In the app, the agent-session commands run as / commands (/pause, /resume, /checkpoints, /restore); the plain-session commands run from a terminal.

• A save writes the session into content-addressed chunks as one checkpoint.
• A fork branches a checkpoint into new lineages. Each child has a separate writable workspace and history.
• A resume restores saved guest state and reconciles session history before work continues. The five commands that resume something are told apart in the glossary.
• When a model call is interrupted by a save, the gateway keeps the completed response and serves the retry from its store rather than buying it twice. That was proven on the evidence bench (gate 3); its standing in production is on What can I use today.
• Budgets and what a session has used: usage and costs.

Cruise uses checkpoints and forks beneath its independent verification. Every command is in the CLI reference.

Why a save must be atomic

If the disk is captured at one moment and the process memory 40 ms later, the program wakes into a world where it remembers writing a file that does not exist. So the disk, the memory and the device state are written as one checkpoint or not at all, and a checkpoint does not exist until it is complete. How that is done, and what was tested: architecture.

Content-addressed chunks

Checkpoints use content hashing to identify and verify stored content. Two things follow.

First, storage does not grow linearly with checkpoints: identical content is stored once, however many checkpoints reference it. Measured across 82 checkpoints in a soak of about seven hours: 4,233 MiB stored against 80,952 MiB without deduplication, 19.1x (the soak, gate 6).

Second, forks are cheap in storage for the same reason: a child starts from its parent’s checkpoint, so the chunks that describe the shared past are the same chunks, and only what diverges costs bytes.

Integrity checks detect changed content; atomic publication prevents an incomplete checkpoint from appearing complete. Storage limitations are in Limits.