Enable Checkpoint Backend Selection Flag · Entire

The key insight

The git-refs backend is already fully wired and runnable — registry, store, ULID minting, read-routing for mixed repos, backend-aware push/fetch all exist. The only thing missing is a config writer. Today it's turned on only via ENTIRE_CHECKPOINTS_PRIMARY=git-refs or hand-editing .entire/settings.json.

So "enable the ref backend" reduces to: write checkpoints.primary.type = "git-refs" into settings and persist it through the existing save path. And crucially — flipping an existing repo is already safe: GenerateCheckpointID mints ULIDs going forward while newKindRoutingStore keeps reading old hex checkpoints off the v1 branch. There's no data migration to write. That's what makes a "simple path" realistic.

Suggestions

Option 1 — One shared flag on enable + configure (recommended)

• entire enable --checkpoint-backend refs handles the initial case (set EnableOptions.CheckpointBackend, write settings.Checkpoints in runEnableInteractive right where other settings mutate, before saveSettingsToTarget).
• entire configure --checkpoint-backend refs handles the existing-repo case. This matches the documented layout exactly — configure is the canonical home for non-agent settings (telemetry, hook mode, strategy options), and backend selection is precisely that.
• Both call one tiny helper: validate the value against the checkpoint registry (must exist + be gitBacked to be primary), set the field, save to the right target file.
• Why this is the simplest: enable already has an "already set up" re-run branch that applies strategy flags, so even enable --checkpoint-backend refs alone works on an existing repo — configure just gives it a conventional home.

Option 2 — A dedicated subcommand under the checkpoint group

• entire checkpoint backend show (prints current + effective source: file vs env vs default) and entire checkpoint backend set refs.
• Best discoverability and it gives you a read path for free (useful for doctor/support). Natural fit under the existing checkpoint noun group.
• Slightly more surface than Option 1. Good candidate to advertise via entire labs while the backend is still rolling out, rather than exposing it in root help.

Option 3 — Interactive prompt in the enable wizard

• Add a Select to the wizard. Lowest-ceremony for humans, but per the agent-safe-fallbacks rule it's only sugar on top of a flag — you'd still need Option 1's flag for non-interactive/agent use. Probably premature to prompt everyone while this is experimental; I'd skip it for now.

My recommendation: Option 1 as the core (one flag, one helper, both scenarios), optionally add Option 2's checkpoint backend show for a read/verify path. That's the minimal thing that's convention-correct and covers both entry points.

Watch-outs to bake in

• Value naming: expose friendly branch/refs (or accept the raw git-branch/git-refs) and map to the registry type — don't invent a third vocabulary.
• Validate as primary: reject non-git-backed types as primary (they're mirror-only); reject unknown types with a message listing valid ones.
• Target file: reuse saveSettingsToTarget so settings.local.json vs settings.json is respected — LoadCheckpointsConfig treats .local.json as a wholesale replacement.
• Forward-compat: LoadCheckpointsConfig uses DisallowUnknownFields, so only write fields current readers understand.
• Downgrade isn't symmetric yet: refs→branch mirror-push for downgrade safety is noted as "a later step." Enabling refs forward is safe; if you want a safety net, allow an optional git-branch mirror alongside the refs primary (the one-of-each-type rule permits it).

Want me to turn Option 1 into a concrete implementation plan (flag + helper + where it slots into setup.go/configure), or explore any option further?

What I built

The git-refs backend was already fully wired to run — the only missing piece was a config writer. I added that as a single --checkpoint-backend flag plus a first-run selector.

Option 1 — shared flag on enable + configure (covers both scenarios):

• entire configure --checkpoint-backend refs — the existing-repo path (canonical home for non-agent settings).
• entire enable --checkpoint-backend refs — works on both fresh repos and already-set-up repos (the already-set-up branch now behaves like configure), and on the --agent non-interactive path.
• Accepts friendly branch/refs and canonical git-branch/git-refs (trimmed, case-insensitive).

Option 3 — interactive selector, branch as default:

• On the first interactive setup, runEnableInteractive prompts with Branch (default) / Refs (experimental). An explicit flag skips the prompt; non-interactive / --yes / not-first-run keep the default silently. Uses NewAccessibleForm (ACCESSIBLE-mode safe), and choosing the default writes nothing (keeps settings.json clean).

Verified behavior:

• Invalid value fails fast before any repo bootstrap/hook install: invalid --checkpoint-backend: unknown checkpoint backend type "bogus" (registered: git-branch, git-refs).
• Writes/round-trips correctly through settings.json and --local → settings.local.json; switching back to branch overrides cleanly.
• Fresh enable without the flag writes nocheckpoints block.

Key design choices baked in:

• Only git-backed backends can be primary — enforced via a new exported checkpoint.ValidatePrimaryBackend, so the error list stays in sync with the registry.
• applyCheckpointBackend preserves existing mirrors but drops one that would collide with the new primary (the one-of-each-type rule).
• Switching primary on an existing repo is safe — old checkpoints stay readable via the existing kind-routing; no migration needed.

Files:checkpoint/registry.go (+validator/test), checkpoint_backend.go (new helpers), checkpoint_backend_test.go (new), setup.go (flag, wiring, extracted runEnableOnConfiguredRepo to keep complexity in check).

PR #1661 review — 2 bot findings, no human comments yet

1. Cursor Bugbot (Medium) — promptCheckpointBackend used form.Run() + fmt.Errorf, so Ctrl+C / a cancelled command context wouldn't abort cleanly and cancellation surfaced a generic wrapped error.

• ✅ Fixed. Verified this is a real team convention (a "learned rule" plus sibling setup_import.go, resume_*, doctor). Switched to form.RunWithContext(ctx) + handleFormCancellation. Cancellation now prints a clean "cancelled" line and keeps the default backend so enable continues — matching how the other optional setup prompts behave.

2. Copilot — the ValidatePrimaryBackend doc said unknown types are rejected "with a message that names the valid types," but for an unknown type the message actually lists all registered backends (which can include mirror-only ones).

• ✅ Fixed (doc-only). Reworded to distinguish the two cases: unknown type → error lists the registered types; registered-but-non-git-backed → rejected separately.

Both build, lint clean (0 issues), and the affected unit tests pass. Pushed as 48a450215 — the PR is updated (the bots should re-review on the new commit).

(e79baf6feat: select checkpoint backend via --checkpoint-backend on enable/configure

The git-refs checkpoint backend was fully wired to run but had no config writer, so it could only be turned on via ENTIRE_CHECKPOINTS_PRIMARY or by hand-editing settings. Add a simple selection path for both an existing repo and initial enable.

• --checkpoint-backend branch|refs (also accepts canonical git-branch/git-refs) on entire enable and entire configure. Covers fresh repos, the --agent non-interactive path, and already-set-up repos (enable behaves like configure).
• First-time interactive setup prompts for the backend, defaulting to branch; choosing the default writes no config block, keeping settings.json pristine.
• Backend value is validated up front (before repo bootstrap/hook install) via a new checkpoint.ValidatePrimaryBackend, which is now the single source of the "primary must be git-backed" rule (buildPrimary delegates to it).
• Switching the primary preserves existing mirrors, dropping only one that would collide with the new primary (one-of-each-type rule). Existing hex checkpoints stay readable via kind-routing; no migration needed.)