feat(checkpoint): push checkpoint refs to one destination, and say where

[Soph]

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

Stacked on #1897 (base branch is soph/multi-pushurl-tests) — it carries the test helpers this builds on. Merge #1897 first; the diff here is then just the behavior change.

Why refs need one destination

The push-discovery queue records only a ref — {"ref": …}, no per-destination state — so "this ref is pushed" has to mean one place. git's fan-out across a remote's several push URLs can't provide that, in two distinct ways:

1. One failing URL fails the whole invocation, so no ref unqueues even though other URLs took it. A dead mirror wedges the queue indefinitely, retried on every push.
2. git's iteration isn't uniform. A ref rejection returns and git carries on to later URLs; a transport failure (missing repo, auth, bad host) die()s. Verified:

First URL fails with…	Later URLs	Exit
non-fast-forward rejection	✅ still pushed	1
unreachable / transport	❌ skipped entirely	128

So an unreachable mirror in first position meant nothing was pushed anywhere, while the same mirror last was harmless. Position silently decided the outcome.

What changes

When a remote carries more than one push URL, checkpoint refs target its first push URL directly and the rest are skipped. The recovery fetch uses the same target, which also fixes a real mismatch: fan-out reconciled the remote's fetch url while pushing to its pushurls, so with a pushurl configured we were reconciling a repository nothing had been pushed to.

A single push URL keeps the remote NAME as the target, so the overwhelmingly common topology is byte-identical to before — remote-tracking refs still update, output still says origin, no URL-keyed promisor config appears. Only multi-URL remotes are affected.

git-branch deliberately keeps fan-out. Its v1 branch is a single shared ref with no queue to keep coherent, and mirroring it to every push URL is what people configure those remotes for (guarded by ..._Branch_RepeatedPushesKeepBothURLsInSync in #1897). The backends therefore differ on multi-URL remotes; that's documented at the decision point in refs_push_destination.go rather than left to be discovered.

Trade, accepted deliberately

• Checkpoint refs live in exactly one repository. Clone that repository and reads resolve (its url becomes the clone's fetch URL); clone a different mirror of the same code and they don't. checkpoint_remote remains the way to name a checkpoint repository explicitly.
• A first push URL that rejects a ref no longer lets later URLs receive it. git would have carried on; we stop. That's the price of a destination the queue can reason about.

Saying where — three surfaces

Since the choice is otherwise invisible:

• pre-push warns on stderr, naming the chosen URL and how many were skipped;
• entire enable notes it (both the first-time setup path and re-enable);
• entire doctor reports it under Checkpoint destination: REVIEW.

All three also cover the other ambiguous topology — several remotes, where checkpoints follow whichever remote you push to while resume/explain always read via origin, so checkpoints pushed elsewhere aren't found again. All are silent on an ordinary repo and whenever checkpoint_remote already pins a destination.

Two message fixes on the way past

• The batch-rejection retry claimed "Some checkpoint refs diverged" for every failure, including an unreachable destination — pointing users at the wrong problem. It now says the push was rejected without asserting why.
• printCheckpointRemoteHint ("a checkpoint remote is configured in Entire settings") fired for any URL target, and would now fire for a URL we picked ourselves. Gated on an actual checkpoint_remote.
• RedactURL renders a plain filesystem path as :///path/to/repo; display now passes paths through and only redacts URL-shaped values.

Tests

Refs tests from #1897 change meaning, so the diff shows the behavior flip:

• ..._Refs_FanOutToBothPushURLs → ..._Refs_GoesToFirstPushURLOnly: first URL receives them, second does not, and they unqueue — the property the whole rule exists to enable.
• ..._Refs_UnreachableSecondPushURL_RefsStayQueued → ..._IsIgnored: a broken later mirror is now irrelevant; refs land and unqueue. Previously this topology wedged the queue forever.
• New ..._Refs_UnreachableFirstPushURL_ReachesNothing: the die() case, previously uncovered.
• New ..._DestinationNoteSurfaces: doctor reports both ambiguous topologies and stays silent on an ordinary repo.

mise run check green (lint 0 issues, canary 59 + 4).

Note for reviewers

gitremote.GetPushURLs is also added by #1898. Whichever lands first, the other rebases and the duplicate drops out — trivial either way.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes pre-push checkpoint sync for multi-push-URL remotes (git-refs only); wrong first URL or user expecting mirrors could miss checkpoints until they set checkpoint_remote.

Overview
Git-refs checkpoint ref pushes no longer rely on git’s multi-URL fan-out. When a remote has more than one push URL, refs go to the first push URL only (single-URL remotes still push by remote name, unchanged). Recovery fetch uses the same target so push and reconcile stay aligned.

Adds gitremote.GetPushURLs / remote.GetPushURLs, resolveRefsPushDestination, and remote_topology so entire doctor and entire enable explain ambiguous setups (multi-push-URL remotes and multiple remotes vs origin for reads). Pre-push stderr warns when extra push URLs are skipped; checkpoint_remote still pins an explicit repo and suppresses those notes.

Also fixes misleading “refs diverged” retry messaging and limits printCheckpointRemoteHint to configured checkpoint_remote.

Integration tests flip from fan-out expectations to first-URL-only behavior and add doctor coverage.

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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

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

[Copilot]

Pull request overview

This PR changes how the git-refs checkpoint backend selects a push destination on remotes with multiple push URLs, ensuring checkpoint refs are pushed to one deterministic destination (the first push URL) so the ref-only push queue can reason about “pushed” as a single place. It also adds user-facing surfacing of the chosen destination (pre-push warning, entire enable, and entire doctor) and updates integration coverage for the new behavior.

Changes:

• Add resolveRefsPushDestination to target the first push URL only for multi-push-URL remotes (git-refs), while keeping single-URL remotes byte-identical to prior behavior.
• Surface ambiguous checkpoint topologies via entire enable and entire doctor, and warn during pre-push when push URLs are being skipped.
• Add gitremote.GetPushURLs and update integration tests to validate the new single-destination behavior and destination reporting.

Reviewed changes

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

Show a summary per file

File	Description
cmd/entire/cli/strategy/refs_push_destination.go	Introduces deterministic destination resolution for git-refs checkpoint ref pushes, including multi-push-URL handling and warning/logging.
cmd/entire/cli/strategy/manual_commit_push.go	Wires destination selection into the pre-push and manual push paths; updates progress/error messaging and gates the checkpoint-remote hint.
cmd/entire/cli/setup.go	Adds a checkpoint destination note to entire enable output when topology is ambiguous.
cmd/entire/cli/remote_topology.go	New helper to inspect remotes/push URLs and describe ambiguous checkpoint destinations for enable/doctor.
cmd/entire/cli/integration_test/multi_pushurl.go	Adds a test helper to configure an unreachable first push URL.
cmd/entire/cli/integration_test/multi_pushurl_test.go	Updates git-refs expectations to “first push URL only”, adds unreachable-first coverage, and validates doctor destination surfacing.
cmd/entire/cli/gitremote/gitremote.go	Adds GetPushURLs to enumerate push destinations as git will use them.
cmd/entire/cli/checkpoint/remote/util.go	Wraps gitremote.GetPushURLs for checkpoint/remote callers.
cmd/entire/cli/doctor.go	Adds a doctor check that reports checkpoint destination ambiguity.

Suppressed comments (1)

cmd/entire/cli/strategy/manual_commit_push.go:314

• Same as the pre-push path: emitting warnIgnoredPushURLs before checking whether the queue is non-empty can print warnings even when there is nothing to push (and can duplicate output across multiple hook invocations on multi-push-URL remotes).

	dest := resolveRefsPushDestination(ctx, ps)
	dest.warnIgnoredPushURLs(ctx, os.Stderr)
	pushed, err = flushCheckpointRefsQueue(ctx, repo, dest)