2. checkpointRun canonicalizes the collection and the run directory (symlinks
resolved through the deepest existing ancestor) and refuses, before
touching anything, when they are the same or one contains the other
(CHECKPOINT_OVERLAP); restore applies the same check to source, target and
staging. Before, <root>/<run> equal to the live run replaced it.
3. Publication writes an immutable generation (generations/g<revision>-…),
renames it into place complete, then switches current.json with one
rename; the previous generation is kept, so an interruption at the publish
boundary (fault hook checkpoint-before-pointer) leaves the last checkpoint
current. A generation never replaces a newer one (higher run revision):
"CHECKPOINT: skipped … newer". Publication and restore hold the
collection's .lock; restore also holds <out>.lock.
4. Restore checks every listed file's real path stays inside the generation
(an ancestor symlink no longer copies outside files), parses run.json and
runs validateRun on the staged run before publishing; a refusal leaves
--out absent. readState reroots plan_input and plan_source for moved runs,
and a restore with the owner's plan file gone points both at the restored
copy, so a second restore cycle and a later revise work.
5. A checkpoint failure after a committed command prints
"CHECKPOINT: failed for <run>: … ; the command's result stands" on stderr
and keeps the command's exit code.
6. `gstack-autoplan checkpoints --from <dir>` lists generations newest first
(run, gate_rev, status, revision, time, hash ok|bad, current).
`resume --from <collection or root>` restores the newest generation that
verifies, printing each corrupt newer one it skipped; a root holding
several runs must name one.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
