Checkpoints V2: allow for a checkpoints_version setting in settings.json

[computermode]

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

(Not intended for production use at this time, followup to #970).

Replaces checkpoints_v2_only with a checkpoints_version setting. The default for now is "1", though "2" is also supported. Same as checkpoints_v2_only, when checkpoints_version is set to 2, checkpoints v1 writes are disabled.

Allows for 2 or "2" as options, but any unsupported version or string value will fall back to version 1 as the default for now.

---

Note

Medium Risk
Changes checkpoint write/push behavior based on a new numeric checkpoints_version setting, which can disable v1 metadata writes and affect sync/migration flows. Risk is moderate due to touching commit hooks, push logic, and settings parsing (with fallback behavior).

Overview
Introduces strategy_options.checkpoints_version (defaulting to 1) as the new switch for checkpoint format selection, replacing the prior checkpoints_v2_only boolean. A value of 2 disables v1 checkpoint metadata writes/pushes while keeping v2 refs enabled; invalid/unsupported values fall back to 1 with a one-time stderr warning.

Updates attach/condensation/finalization and pre-push paths to key off CheckpointsVersion()==2 for v1 skipping and error propagation semantics, and adjusts migration hinting to detect committed checkpoints_version: 2. Integration and unit tests are updated/expanded to cover version parsing and the “version 2 skips v1” behavior.

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

[Copilot]

Pull request overview

Replaces the legacy checkpoints_v2_only setting with a more general strategy_options.checkpoints_version setting (defaulting to v1), while preserving the behavior that selecting version 2 disables v1 writes and enables v2 ref pushing.

Changes:

• Introduces CheckpointsVersion() parsing (accepting 2 or "2", falling back to 1 on invalid values) and updates v2 enablement logic accordingly.
• Updates push/condensation/finalization/attach flows to gate v1 writes based on checkpoints_version == 2.
• Renames and updates unit/integration tests to use checkpoints_version: 2 instead of checkpoints_v2_only.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
cmd/entire/cli/settings/settings.go	Adds CheckpointsVersion() API and routes v2 enablement through checkpoints_version.
cmd/entire/cli/settings/settings_test.go	Adds table-driven coverage for checkpoints_version parsing and updates v2-related tests.
cmd/entire/cli/strategy/push_common.go	Updates “committed settings” detection + migration hint to use checkpoints_version == 2.
cmd/entire/cli/strategy/push_common_test.go	Renames tests and fixtures to assert the new committed-setting behavior.
cmd/entire/cli/strategy/manual_commit_push.go	Gates v1 metadata branch push on CheckpointsVersion() != 2; updates docs.
cmd/entire/cli/strategy/manual_commit_hooks.go	Uses checkpoints_version == 2 to disable v1 updates and choose v2 read paths.
cmd/entire/cli/strategy/manual_commit_condensation.go	Switches v1/v2 write behavior based on version-2 mode vs dual-write mode.
cmd/entire/cli/strategy/checkpoint_remote.go	Skips v1 metadata-branch fetch when checkpoints_version is 2.
cmd/entire/cli/integration_test/v2_push_test.go	Updates integration test to use checkpoints_version: 2 and renames branch.
cmd/entire/cli/integration_test/v2_dual_write_test.go	Updates integration test to use checkpoints_version: 2 and renames branch.
cmd/entire/cli/attach.go	Gates v1 write and v2 error propagation based on checkpoints_version == 2.