Checkpoint Restore
Resume From the Position Checkpoint
Resume restores committed state and runs forward from the checkpoint.
4 milestones 0 tasks
5 plan 16 execute 31 review
10h 59m total
This run replaced resume replay with checkpoint restore. The digest split the work into the durable position record, live resume from that record, the pattern-output and planner semantics exposed by the change, and the docs that state the rule. The run did not land without stress. The ledger records reviewer retries on the checkpoint reconstruction work, and the output-semantics unit took a red run-scoped gate before the reference dataset was regenerated.
How this walkthrough is structured
Feature
What did the run build and ship?
The tree now contains checkpoint reconstruction support, resume diff handling for trailerless operator commits, synchronized pattern reference data, and published pattern docs for checkpoint restore.
Build
How did Gantry structure the work?
The cut kept the interpreter-state work separate from resume execution, then used the later pattern and docs units to settle the consequences of that restore rule.
Milestone 1
Position Checkpoint
`src/engine/repair.rs` still contains `repair_position_checkpoint` and `reconstruct_position_checkpoint`. A run with no checkpoint can be inspected, have the checkpoint reconstructed from `run-identities.jsonl` and frozen pattern data, and have `state/position-checkpoint.json` written atomically. The reconstruction rebuilds invocation frames outward-in and keeps run-scoped output bindings separate from frame-local bindings. Unsupported or incomplete records fail with explicit checkpoint errors instead of silent fallback.
This piece carried the durable position record and the legacy repair path. That scope was narrow enough for a fresh agent because it stayed inside checkpoint reconstruction and did not make ordinary resume consume the record yet. The boundary was not clean on the first reviewer pass; the ledger shows reviewer retries before the unit landed green. That stress fits the work, because reconstruction had to recover parameters, tasks, output bindings, and identity counters from existing records.
Milestone 2
Resume Restore
`Worktree::session_attempt_base_revision` now scans first-parent history for the latest commit carrying a `Gantry-Step` trailer. `EngineContext::start_session_identity` uses that revision as the session attempt base, so a later session diff can span a trailerless operator commit. The regression test in `src/engine/run/tests/commit.rs` commits operator work between Gantry session commits and asserts that the next session diff includes both the operator file and the new Gantry file. Current resume code also reads checkpoint restore state before entering the generic pattern runtime.
This piece connected checkpoint restore to resume behavior and kept operator commits in scope. The brief made the resume path broad, but its strongest isolated obligation was trailer-aware commit reading: Gantry had to preserve a trailerless operator commit while still finding the last Gantry boundary. The ledger records a green finish, so the cut held without a recorded retry. Its boundary was the point where checkpoint restore stopped being only a record format and affected live run history.
Milestone 3
Output Semantics
The surviving files for this unit are the exported reference datasets under `docs/reference/data/reference.json` and `web/db/data/reference.json`. Their bundled `build` and `milestone` pattern comments now describe checkpoint restore preserving an existing brief directory so ledger `DONE` rows keep naming the same task paths. The direct `next_attempt_ceiling` implementation is not isolated in the surviving git facts for this run. What remains checkable here is the synchronized reference-data copy that keeps the documented bundled-pattern semantics aligned with the source export.
This piece absorbed the pattern-language fallout from checkpoint restore. Its brief coupled the `next_attempt_ceiling` defect with the rule that a resumed `build` planner must not rewrite existing sprint briefs under new task paths. The run-scoped gate went red after the unit body completed, and the fixing commit regenerated the reference dataset from the corrected bundled pattern comments. That failure located the risk in synchronized generated artifacts rather than in the engine path alone.
Milestone 4
Resume Docs
`manual/spec.md` and `web/app/documents/manual/spec.md` now state that after checkpoint restore no step is replayed. The same passage says a resumed `for` omits tasks with latest ledger status `DONE`, while other steps in the resumed invocation execute again. `docs/agents/status.md` no longer phrases that behavior as a checkpoint-specific skip during restore; it names the broader ledger cross-check for `DONE` task omission. The docs still carry the rule in the source and the website copy.
This was the documentation pass after the behavior units had landed. A fresh agent could hold it because the brief named the exact sources and the single rule they had to state consistently: checkpoint restore, not recorded-outcome replay. The unit landed green, while the later merge still needed conflict resolution at run level. Its boundary was prose consistency across source docs, website copies, and the status page.