Skip to main content
Snapshots speed up workspace startup and preserve paused work on supporting backends. Formation separates reusable clean repository state from one task’s changes: new work starts from a baseline; continuing work can restore its own checkpoint. An unrelated task never adopts another task’s dirty checkout. For setup and supported providers, see Sandboxed execution. Modal supports project snapshots. Fly Sprites supports holding a paused task’s live filesystem, but its Formation adapter does not implement project snapshots.

​
Baselines and checkpoints

A baseline is keyed by agent, repository, backend, base image and canonical ref. Checkout fetches the upstream ref and validates a clean canonical tree before publishing a baseline, before task changes begin. Validation rejects tracked or staged changes, non-ignored untracked files and in-progress Git operations. Credential files and unrelated repositories are outside the capture root. Restoring a baseline does not assume its commit is current. Checkout fetches and normalizes to the requested ref before creating the task branch, dropping stale local branches and untracked files while retaining eligible ignored caches. A checkpoint has a work-context ID, sequence and predecessor. The work context comes from durable task state: a single accepted commitment uses its task ID across automatic attempts; a human-authorized continuation uses its root run; other work uses the current run. Conversation identity alone does not establish continuity. Multi-task executions do not restore a single task’s private tree.

​
Restore order

Acquisition tries these paths in order:
  1. Adopt a still-held workspace belonging to the continuing task, after current ownership and credential checks.
  2. On a snapshot-capable backend, restore the same work’s current checkpoint.
  3. Restore an eligible clean repository baseline.
  4. Cold-start and check out the repository.
A failed checkpoint restore can fall back to a baseline; a failed baseline restore can fall back to cold start. Neither path selects another task’s checkpoint. The resume context reports the restore outcome so the agent can inspect durable external state before repeating any effect. Filesystem state is not proof that a push, issue update or other external action happened.

​
Pause, resume and completion

When a task pauses, Formation saves its continuation and attempts a checkpoint before delivering the paused reply. The append is fenced against the expected lineage head; concurrent or stale captures cannot silently overwrite a newer head. A checkpoint preserves the task tree without promoting it to a shared baseline. A live workspace may also be held for continuation. Newly saved pauses on an idle-persistent backend can hold it for fourteen days; other backends use a one-hour handoff window. Existing shorter holds are not retroactively extended. These holds have limits and can end after cancellation, expiry, credential revocation or provider-side loss. Resumed work reports completion of the original task separately from its reply text. Answering a side question does not complete the task or retire its lineage. Explicit task completion or requester rejection retires the corresponding lineage; an unrelated request does not adopt it. Accepted criteria tasks also capture before attempt settlement, including silent background attempts and model failures after file writes. Their persisted project routing lets an exec-first successor restore its task checkpoint after a process restart. Capture is preceded by a durable hold: failed or interrupted capture cannot make release destroy the only live tree. A successor can inherit that held tree only for the same agent and single task, after the prior run ends, with no competing release claim. Backend and credential checks still apply on acquisition. Successful capture permits normal release. Cancellation or other terminal task state ends the hold; otherwise it is bounded by the task deadline and fourteen days. A provider can still lose an ephemeral sandbox; an unsuccessful capture is not proof of preserved files. Recovery of an interrupted command in the same run keeps the original workspace. Reading its routing and building checkpoint context do not authorize another command or settle an unknown effect. These reads retain task, disclosure, deadline, and lease checks; transferring another run’s tree or writing a new checkpoint also requires the full uncertain-effect guard. Receipt collection remains subject to admission for the exact saved command. There is no final checkpoint on arbitrary workspace release and no operator API for selecting a historical checkpoint and forking a task from it. The pause-time and accepted-attempt checkpoints are the implemented recovery boundaries.

​
Authorization and cleanup

Snapshot ownership includes the agent and work context. Credential rotation or coding-delivery permission changes retire retained snapshots from reuse, because shell code may have copied a token into the project tree. Capture is serialized with revocation. Revoking reuse does not revoke a token at its issuer. The reaper retires checkpoint heads neither captured nor restored for fourteen days and reclaims retired/superseded/failed artifacts after a seven-day retention window. Cleanup uses the backend recorded on each snapshot, not the agent’s current backend selection. A backend’s disabled acquisition switch does not remove its cleanup responsibility. Missing credentials or provider failures can leave artifacts pending operator repair. Restore events are recorded in snapshot_restores; snapshot metadata is in project_snapshots. A pre-lineage snapshot was retired during migration rather than asserted to be a validated baseline. Snapshots and held workspaces are recovery aids, not publication or backup. Commit and push code and save final artifacts outside the workspace. Neither mechanism makes an air-gapped or local execution backend available. Implementation: internal/workspace, internal/coding, and internal/execution/modal.