Add checkpoint format compatibility checks

[pfleidi]

https://entire.io/gh/entireio/cli/trails/649

Why

Checkpoints can now carry an explicit checkpoint_version. Older CLIs need a narrow compatibility gate before they decode checkpoint data, otherwise user-driven read commands may try to interpret a format they do not support or fall back to unrelated remote-recovery behavior.

What changed

Adds a small checkpoint compatibility package that parses checkpoint format identifiers and reports unsupported read versions. Explain, export, resume, and rewind read paths now validate the stored checkpoint_version immediately after loading the checkpoint summary and before decoding session content or transcripts.

branch-v1 remains the only read-supported checkpoint format in this PR. Legacy checkpoints with no stored version continue to normalize to branch-v1 through the existing checkpoint summary normalization. Newer known formats such as refs-v1 produce a clear unsupported-version error.

Unknown format families are intentionally treated as invalid rather than unsupported. That keeps the Family model constrained to families this CLI actually knows about. The trade-off is that a future CLI using a brand-new family will produce an invalid-version error in this older CLI until that family is added here, instead of the nicer unsupported-version error used for known but unreadable formats. We are accepting that trade-off to keep the first compatibility gate simple and explicit.

Usage examples

Supported legacy and branch-v1 checkpoints continue to work:

entire checkpoint explain abc123def456
entire session resume my-branch

When a checkpoint stores a newer known version such as refs-v1, user-driven read commands fail with a clear error like:

checkpoint abc123def456 uses unsupported checkpoint_version "refs-v1": not read-supported by this Entire CLI

For squash-merge commits with multiple checkpoint trailers, entire session resume <branch> now fails if any listed checkpoint cannot be read, including unsupported checkpoint versions. If all listed checkpoints are readable, resume chooses the checkpoint with the newest CreatedAt timestamp and prints that it is resuming from the latest checkpoint.

Resume behavior details

Unsupported-version errors now propagate from all resume read paths instead of being treated as missing metadata:

• direct checkpoint resume through the picker-backed path
• branch resume after reading local checkpoint metadata
• checkpoint-remote and origin fallback reads in checkRemoteMetadata
• single-session log restore before transcript content is read
• squash-merge checkpoint selection in resolveLatestCheckpoint

This keeps the behavior conservative: a newer or unreadable checkpoint nudges the user to upgrade or fetch the missing metadata rather than silently resuming from a different checkpoint that happened to be readable.

Decisions made during development

This PR only handles per-checkpoint read compatibility. It intentionally does not add the repository policy ref, policy command, hook warnings, or policy enforcement; those are split into follow-up PRs to keep this review focused.

The read check lives at each command boundary after CheckpointSummary is loaded instead of inside low-level checkpoint storage. That keeps storage capable of preserving newer metadata for future clients while user-driven commands stop before decoding unsupported content.

The parser recognizes only known format families. Known unreadable formats become unsupported-version errors; unknown families remain invalid-version errors by design.

Technical tradeoffs

Failing multi-checkpoint resume on the first unreadable checkpoint is stricter than attempting to pick the newest readable checkpoint. The tradeoff is intentional: the confusing case should be rare, and a clear error is easier to reason about than resuming from a checkpoint that may not represent the newest session state.

Treating unknown families as invalid is also intentional. It gives up a slightly nicer forward-compatibility error for brand-new families in exchange for keeping the typed family model narrow and avoiding acceptance of arbitrary typo families as syntactically valid policy input.

The PR does not verify checkpoint commit signatures. Signature verification is related to trusting policy/config changes, but it is outside the scope of this read-compatibility split.

Reviewer notes

This is PR 1 of the checkpoint policy split. Follow-up stacked PRs will add the hidden entire policy checkpoint command and repository policy storage/enforcement.

---

Note

Medium Risk
Touches core user flows (resume, rewind, explain/export) with stricter multi-checkpoint and remote-fallback behavior; mistakes could block legitimate resumes or mis-handle version strings, but changes are read-path only with broad test coverage.

Overview
Adds a checkpointpolicy package that parses family-vN checkpoint formats and allows reads only for branch-v1 (empty version still normalizes to branch-v1). Known but unreadable versions such as refs-v1 return a typed unsupported-version error via EnsureCanReadVersion and IsUnsupportedVersion.

Explain, export (JSON and transcript streaming), resume, rewind, and manual-commit rewind now call that check right after loading CheckpointSummary and before session content or transcripts are decoded. Unsupported versions fail with an explicit message instead of being treated as missing metadata or falling through to remote recovery.

Resume behavior is stricter for squash merges with multiple checkpoint trailers: resolveLatestCheckpoint fails on the first unreadable checkpoint (including unsupported version) rather than skipping bad IDs and picking the newest readable one; user messaging refers to resuming from the latest checkpoint. Remote metadata fallback surfaces unsupported-version errors when that is what was found on the remote tree.

Tests cover policy parsing, rejection paths across explain/export/resume, and e2e resume output expectations.

^{Reviewed by Cursor Bugbot for commit efc3ca2. Configure here.}

[Copilot]

Pull request overview

This PR introduces an explicit read-compatibility gate for checkpoints via a new checkpointpolicy package, ensuring user-facing read commands (explain/export/resume/rewind) fail early and clearly when encountering newer checkpoint formats that the current CLI cannot decode.

Changes:

• Added cmd/entire/cli/checkpointpolicy to parse family-vN checkpoint format identifiers and enforce a read-allowlist (currently branch-v1).
• Wired compatibility checks into checkpoint read paths (including manual-commit logs-only rewind restore, interactive rewind transcript restore, resume selection, explain, and export).
• Added targeted tests to cover unsupported versions (e.g., refs-v1) and multi-checkpoint resume selection behavior.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cmd/entire/cli/strategy/manual_commit_rewind.go	Validates checkpoint_version before restoring logs-only rewind transcripts from committed checkpoints.
cmd/entire/cli/rewind.go	Ensures checkpoint version compatibility before decoding committed session transcript content; propagates unsupported-version errors.
cmd/entire/cli/resume.go	Enforces version compatibility in resume metadata reads; adjusts latest-checkpoint resolution to skip unsupported candidates.
cmd/entire/cli/resume_test.go	Adds coverage for skipping unsupported checkpoints and returning unsupported-version errors when no readable checkpoints exist.
cmd/entire/cli/explain.go	Validates checkpoint version immediately after reading the checkpoint summary during explain loading.
cmd/entire/cli/explain_test.go	Adds a regression test asserting explain rejects unsupported checkpoint versions.
cmd/entire/cli/explain_export.go	Adds compatibility checks for export JSON and transcript streaming paths.
cmd/entire/cli/explain_export_test.go	Adds helper to rewrite committed checkpoint summary version and tests that export paths reject unsupported versions.
cmd/entire/cli/checkpointpolicy/version.go	Implements EnsureCanReadVersion and a typed unsupported-version error plus helper predicate.
cmd/entire/cli/checkpointpolicy/format.go	Implements family-vN parsing and the read-allowlist decision (CanRead).
cmd/entire/cli/checkpointpolicy/format_test.go	Unit tests for format parsing and read support behavior.
cmd/entire/cli/checkpoint_policy_read_test.go	Ensures resume’s metadata-read helper rejects unsupported checkpoint versions early.

[pfleidi]

Bugbot run

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[pfleidi]

Bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit efc3ca2. Configure here.}

[pjbgf]

Maybe use value-based error instead?

Suggested change

	return &unsupportedVersionError{
	return unsupportedVersionError{

[pjbgf]

Doing from memory, so maybe the syntax is slighlty off, but we are better off using error.Is in this case:

Suggested change

	var unsupported *unsupportedVersionError
	return errors.As(err, &unsupported)
	return errors.Is(err, unsupportedVersionError)

[pjbgf]

Suggested change

	return nil, fmt.Errorf("%w", err)
	return nil, err

[pjbgf]

Suggested change

	return nil, nil, fmt.Errorf("%w", err)
	return nil, nil, err

[pjbgf]

Suggested change

	return fmt.Errorf("%w", err)
	return err

[pjbgf]

Suggested change

	return fmt.Errorf("%w", err)
	return err

[pjbgf]

Suggested change

	return nil, fmt.Errorf("%w", err)
	return nil, err

[pjbgf]

Suggested change

	return "", fmt.Errorf("%w", err)
	return "", err