Checkpoints

A checkpoint is retained recovery material for a Session Run: metadata over one sandbox snapshot, plus either bounded harness continuation material or a marker to rebuild from the retained event log. A Run produces one; a qualified resume or fork consumes one. A checkpoint is subordinate to Session and provider-effect authority. It is not a second transcript, a mutable configuration source, or proof that an external action completed.

​

They expire after 30 days

Every checkpoint carries an immutable expires_at, defaulting to 30 days after it was created. A Workspace retention policy may shorten that window but never lengthen it. GET /v1/sessions/{id}/checkpoints lists a Session’s checkpoints as secret-free metadata: the snapshot boundary (through_sequence, through_event_id), the harness and Environment revisions it was taken against, and the timestamps. It never returns snapshot contents. Those exact internal identifiers remain part of the current public metadata even though they are not the common Agent authoring model.

​

Expiry can fall back to a retained log

The Session event log is the durable Session execution record; the sandbox snapshot is retained recovery material on top of it. checkpoint expiry therefore loses the fast path to disk and native state, not a retained Session event prefix. Independent retention expiry, subject erasure, or zero-data-retention omission can still make content positions unreadable and prevent an exact reconstruction.

• An ordinary later Run does not name a checkpoint. If the latest snapshot expired while its conversation is still readable, its Runner claim says event_log_rebuild with reason checkpoint_expired; the fresh sandbox receives the retained conversation but none of the old disk.
• Explicitly forking against an expired checkpoint returns 409 runtime.checkpoint_expired. It does not silently reinterpret the named snapshot as a log-only fork.
• If you retained the checkpoint’s through_event_id and that complete prefix remains readable, you can explicitly request an at_event rebuild, which restores conversational state only. This rebuild does not restore sandbox disk or harness-native state. An incomplete prefix instead returns 409 runtime.session_history_unavailable.

The distinction to hold onto: conversation can be reconstructed while its selected log prefix remains readable; sandbox and harness-native bytes are recoverable only while eligible retained material exists. Anything an Agent must not lose belongs in Memory, a FileTree revision, or an Outcome deliverable, not in un-checkpointed sandbox scratch. Snapshot expiry ends recovery eligibility. It does not by itself prove physical deletion of provider-held snapshot bytes.

​

Replacement attempts are evidence-gated

A failed RunAttempt is not automatically replaced merely because a checkpoint exists. Post-ready replacement requires the same durable Run, a new fenced attempt generation, retained compatible bytes, the required recovery frontier, and current verification for that exact execution lane. Accepted Session events are never rewound. When the required authority, bytes, compatibility coordinates, or verification are absent, Checkfu reports the recovery limit instead of manufacturing a replacement attempt.

​

checkpoints do not settle provider effects

A worker can die after dispatching an external request but before the trusted capability or effect boundary accepts its receipt. Neither a nearby checkpoint nor the presence of a Session event proves whether the provider performed the action. The effect remains indeterminate. Recovery preserves the original effect identity and reconciles it through an authoritative provider lookup or idempotency mechanism, an accepted trusted-boundary receipt, or an explicit governed decision. It must not issue a blind duplicate under a fresh identity. An ActionApproval can authorize one exact frozen action, but it is not evidence that the provider completed that action. Conversely, a provider-effect receipt cannot create a missing human approval.

​

Credential boundary

Checkpoint listing exposes secret-free metadata, not private harness state. A public continuation capsule admits only the supported idle resume identifiers; a suspended turn with live bridge authority or arbitrary tool inputs is not eligible for that projection. Private retained continuation material is encrypted and subject to its own custody, expiry and recovery checks. Its arbitrary native state is not covered by a blanket credential-free guarantee. Neither retained state nor a public capsule grants fresh execution authority.

​

Next steps