fix(strategy): sync checkpoints to a single elected remote (ENT-1451)

[peyton-alt]

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

Problem

In a repo with multiple remotes (e.g. origin and publish), pushing to any remote synced checkpoint data to it — leaking session transcripts onto remotes where they don't belong. The two storage backends failed in mirror-image ways:

• git-branch: every push re-synced entire/checkpoints/v1, so every remote received full transcripts (Checkpoint reads always target origin while pushes follow the hook remote (non-origin remotes unsupported) #1634, write side)
• git-refs: the push queue had no per-remote state, so the first push drained it and a second remote silently never received checkpoints (git-refs: push queue is drained by the first successful push — checkpoints never reach a second remote #1635)

Change

Checkpoint data now syncs to exactly one elected remote, identical on both backends:

• Election precedence (strategy.ResolveCheckpointSyncRemote): strategy_options.checkpoint_push_remote (a plain remote name; fail-closed — a name that isn't a configured remote disables sync with a warning rather than falling back) → the current branch's own push destination, mirroring git's push resolution (branch.<name>.pushRemote → remote.pushDefault → branch.<name>.remote; dangling tracking entries are skipped, not fail-closed) → origin → the sole remote → the first remote in .git/config order. The tracking tier fixes the fork setup where origin is a base repo the user cannot push (cloned base + added fork): the branch's tracking remote wins, so checkpoints sync to the fork instead of stranding locally.
• Pre-push gate: pushes to any other remote — including raw-URL pushes — carry no checkpoint data and skip the policy sync/OPF work entirely. The dedicated checkpoint_remote URL store is exempt (it's addressed directly, not selected by the push).
• git-refs queue: only drained by pushes to the elected remote, fixing the first-push-wins loss (git-refs: push queue is drained by the first successful push — checkpoints never reach a second remote #1635).
• doctor migrate-checkpoints: --remote now defaults to the elected remote instead of hardcoded origin; explicit --remote still wins.
• Observability (entire status, text + --json): Checkpoints sync to: origin destination line (with source annotation), an unpushed-checkpoint counter, and a checkpoint_sync_error surface for the fail-closed case — so the behavior change is visible, not silent.

Behavior change

Multi-remote repos where a secondary remote previously received checkpoints stop getting them. That was the bug for most users (transcripts on a public remote are unrecoverable; a deferred sync is not), and checkpoint_push_remote is the escape hatch for choosing which remote. Should be called out in the next release's changelog.

Testing

• Unit: resolver precedence table (incl. fail-closed, pushurl-only invisibility, config-order-beats-alphabetical), gate, migrate helper, counter (both backends), status text/JSON.
• Integration: 6 tests / 11 subtests across both backends with remote-side assertions on bare repos — default election, config override, fail-closed (through the real installed pre-push hook), raw-URL push, status before/after, dedicated-store exemption (HTTPS fixture). Negative-control verified: reverting the gate makes the matrix fail.
• Full mise run check green (unit + integration -race + Vogon canary).

Notes for reviewers

• Doctor recovery for checkpoints already leaked to non-elected remotes is a deliberate follow-up PR.
• test: git-remote coverage (3/4) — divergence & recovery matrix #1638 interaction: the open git-remote test stack pins the old git-refs: push queue is drained by the first successful push — checkpoints never reach a second remote #1635 behavior in TestGitRefsQueue_TwoRemotesQueueClearedByFirstPush with a flip-me comment; when that stack rebases onto this, the assertion flips (this PR's integration matrix already pins the new semantics).
• Read paths still target origin (coherent with the default election); routing them through the resolver is the Checkpoint reads always target origin while pushes follow the hook remote (non-origin remotes unsupported) #1634 read-side follow-up.

Fixes ENT-1451. Closes #1635. Refs #1634 (write side).

Trail: https://entire.io/gh/entireio/cli/trails/967 — full session history (spec, plan, and per-commit checkpoints) for this change.

🤖 Generated with Claude Code

---

[!NOTE] Medium Risk
Changes where session transcripts are pushed in multi-remote repos (intentional privacy fix); misconfigured checkpoint_push_remote disables sync until fixed, though status surfaces the failure.

Overview**
**Checkpoint data now syncs to one elected git remote instead of following every git push target. Election uses strategy_options.checkpoint_push_remote (errors if the name is missing — no fallback), then origin, sole remote, or first remote in .git/config order.

The pre-push hook skips checkpoint/OPF work unless the push targets that remote (or uses dedicated checkpoint_remote URL mode). Other remotes and raw-URL pushes leave git-refs queue entries intact.

entire status (text and --json) reports sync destination, source, fail-closed errors, and a local unpushed checkpoint count (CountUnpushedCheckpoints: v1 ahead-of-tracking on git-branch, push-queue Peek on git-refs).

doctor migrate-checkpoints defaults --remote to the elected sync remote instead of origin. GetCheckpointPushRemote reads the new setting. Docs and integration tests cover both backends.

Reviewed by Cursor Bugbot for commit 03abd8d. Configure here.

[Copilot]

Pull request overview

This PR fixes multi-remote checkpoint syncing by ensuring checkpoint metadata (including transcripts) is pushed to exactly one elected git remote across both checkpoint backends, preventing accidental leakage to non-intended remotes. It adds a shared remote-election resolver, gates pre-push checkpoint work to the elected remote (with a dedicated checkpoint_remote exemption), and improves observability via entire status and supporting counters.

Changes:

• Add single-remote election (strategy_options.checkpoint_push_remote → origin → sole remote → first in .git/config order) and enforce it in the pre-push hook for both git-branch and git-refs backends.
• Add local-only observability: entire status (text + --json) now reports checkpoint sync destination/source, fail-closed errors, and an “unpushed checkpoints” approximation.
• Update doctor + plumbing/tests: doctor migrate-checkpoints defaults to the elected remote; git-refs push-queue gains a read-only Peek; unit + integration coverage added.

Reviewed changes

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

Show a summary per file

File	Description
docs/architecture/sessions-and-checkpoints.md	Documents the new single-remote checkpoint sync behavior and exemption rules.
CLAUDE.md	Updates strategy behavior documentation with single-remote sync semantics.
cmd/entire/cli/testutil/testutil.go	Adds test helpers for remotes, settings, and ref updates used by new tests.
cmd/entire/cli/strategy/unpushed_checkpoints.go	Implements local-only unpushed checkpoint counting for both backends.
cmd/entire/cli/strategy/unpushed_checkpoints_test.go	Unit tests for unpushed checkpoint counting behavior.
cmd/entire/cli/strategy/manual_commit_push.go	Adds the single-remote pre-push gate to prevent syncing to non-elected remotes.
cmd/entire/cli/strategy/manual_commit_opf_prompt_test.go	Adjusts OPF prompt test setup to satisfy the new gate with a hermetic remote.
cmd/entire/cli/strategy/checkpoint_sync_remote.go	Introduces resolver + gate predicate for electing/allowing checkpoint sync remotes.
cmd/entire/cli/strategy/checkpoint_sync_remote_test.go	Unit tests covering election precedence and gating semantics.
cmd/entire/cli/status.go	Adds shared checkpoint-sync info computation + text/JSON status surfaces.
cmd/entire/cli/status_test.go	Tests new status text/JSON output for elected/dedicated/fail-closed cases and counters.
cmd/entire/cli/settings/settings.go	Adds GetCheckpointPushRemote() accessor for the new setting.
cmd/entire/cli/settings/settings_test.go	Unit tests for GetCheckpointPushRemote().
cmd/entire/cli/integration_test/checkpoint_sync_remote_test.go	End-to-end integration matrix asserting single-remote routing across both backends.
cmd/entire/cli/doctor_migrate.go	Defaults migrate push target to the elected sync remote (fail-closed on misconfig).
cmd/entire/cli/doctor_migrate_test.go	Unit tests for migrate remote resolution logic.
cmd/entire/cli/checkpoint/pushqueue.go	Adds Peek() for non-mutating queue inspection (status/counters).
cmd/entire/cli/checkpoint/pushqueue_test.go	Tests that Peek() is read-only and de-duplicates without compacting.