Worktrees, checkpoints and reports as data safeguards

Agentic systems change files, generate artefacts, update configuration and trigger external processes. While a person often pauses after a few steps, an agent can execute long action chains. Failure may therefore erase not only an output but intermediate states, decisions and dependencies.

Worktrees, commits and run reports are often called „backups". The label is understandable but technically imprecise. A worktree is a parallel working tree, not an independent copy. A commit does not automatically include untracked files, databases or secrets. A report can describe missing bytes but cannot restore them.

A dependable architecture separates work isolation, versioning, operational evidence and backup with tested restoration.

Worktrees isolate work, not failure

Git can connect several working trees to one repository, allowing branches to be checked out simultaneously. This is valuable for agentic work: an agent receives a named assignment in its own directory while the main workspace stays clean. Diffs, tests and approvals remain task-specific.

Isolation has limits. Linked worktrees share important repository data and references. Corruption, misconfiguration or loss of the common repository can affect several trees. External dependencies—databases, object stores, model artefacts, caches and secret stores—are not copied by adding a worktree.

A worktree is therefore a collision and contamination boundary. It protects parallel changes from accidental mixing. By itself it does not protect against hardware loss, destructive cleanup, malicious encryption or common-storage failure.

The baseline must be known

Before an agent begins, a run needs an origin reference: repository, branch, commit ID, index state, working-tree changes, untracked files, submodules, relevant tool releases and referenced external snapshots.

A clean start is easier to verify than an unknown dirty workspace. If existing changes are required, the run does not inherit them silently. A preflight manifest classifies each as assignment input, protected foreign state or blocker.

git status exposes the index, working tree and untracked files, but visibility is not preservation. Untracked files remain outside commits until deliberately added. Ignored files need a separate policy.

A checkpoint is a semantic state marker

Not every commit is a useful checkpoint. A checkpoint marks a state to which the project can meaningfully return: „import complete", „schema migrated and validated", or „publication package prepared but not approved".

It is atomic enough to understand and complete enough not to depend on invisible intermediate actions. It contains or references the commit ID, external snapshots, artefact versions, schema and tool releases, validation results, known deviations, owner, time, run ID and next permitted transition.

Names do not replace immutable identity. A branch or tag can move; the commit ID addresses a concrete Git state. External objects need stable IDs, versions or hashes.

Commits capture only the versioned slice

A commit is a strong basis for reconstructing file state, but not a snapshot of the entire project. It records content selected through the index or a targeted commit. Local databases, binaries, generated exports, logs, credentials and untracked files may remain outside.

A state inventory therefore distinguishes versioned source, non-versioned authoritative data, reproducible outputs, runtime queues, external services, secrets and disposable cache. Each class needs a different recovery route. Cache may need no backup but requires a rebuild procedure. Secrets stay outside Git and return through a protected secret lifecycle.

A run report is evidence, not a copy

The report connects assignment, baseline, plan, actions, tool calls, diffs, tests, approvals, checkpoints and outcome. It answers what was intended, what occurred, which state resulted, what changed externally and what remains open.

Stable references matter. Instead of „current file", the report records path, version or hash. Instead of „backup succeeded", it records the job, destination, verification and last restore exercise. Reports are retained outside volatile runtime state and cannot be silently overwritten.

Yet a report does not replace payload data. Its value lies in provenance, diagnosis and selection of the correct recovery point.

Real backups need a separate failure domain

A copy on the same device, account or administrative path may be destroyed by the same event. Dependable backups occupy a separate failure domain through another storage system, independent permissions, immutable retention, geographic separation or an offline copy as risk requires.

A Git remote improves availability but is not automatically complete: unpushed commits and local references may be absent, and damaging changes can replicate. A full bundle can package Git objects and references for transport. It still requires separate storage, protection, verification and restoration testing.