fix(checkpoint): fetch a locally-missing ref before declaring a backfill target absent

[peyton-alt]

Follow-up to the #1811 review (addressed directly per discussion, no issue filed). Complete fix: store-layer semantics and production wiring.

Problem

The git-refs store's reads on-demand fetch a checkpoint ref that's missing locally; its backfill writes (summary, stop-time transcript finalize, attribution) probed with a local-only lookup. For a checkpoint written or migrated on another machine, a backfill declared it absent — landing on a stale fallback copy under kind routing (#1811), or failing — while reads served the refs copy, leaving the backfilled data permanently invisible.

Fix (three layers)

1. Store: backfills fetch-probe — refBaseForBackfill → resolveRefMaybeFetch fetches a locally-missing ref once when a fetcher is wired. Creates keep the local-only probe (their ref never exists yet). Zero cost when the ref exists locally (pinned).

2. Absence ≠ failure at the fetch layer — remote.FetchCheckpointRef (moved from the cli package so strategy hooks can import it; thin aliases keep old call sites) now probes with ls-remote before fetching: a ref the remote genuinely lacks returns an error wrapping plumbing.ErrReferenceNotFound → classified as absence → safe fallthrough under kind routing. Transport failures on either leg surface as-is — never absence, so a dead network can't fork a write onto a stale copy. This was the blocker that made naive wiring unsafe (git fetch of a missing refspec fails like a network error).

3. Wiring with a hook-safe budget — remote.BoundedCheckpointRefFetcher(remote.WriteProbeFetchBudget) (15s per probe) wired at the three backfill write sites: explain --generate's write store, the stop-hook transcript finalize, and post-commit attribution. The git-refs store memoizes the first transport-level fetch failure per store instance, so a stop hook finalizing N checkpoints on a dead network pays the outage once, briefly. Remote absence is per-ref and never memoized.

Verification

• TDD throughout: store-level fetch-restores-ref (all three backfill types, with read-back + parent-hash assertions), fetch-failure-aborts (NotErrorIs ErrCheckpointNotFound), absent-after-fetch, local-ref-never-fetches, creates-never-fetch, absence-classification chain-through, and failure-memo behavior (transport memoized once; absence never)
• Remote-level fixtures against a local bare origin: missing ref → absence sentinel; present ref → fetched into the local ref; unreachable remote → hard error
• Multi-agent review pass applied (comments re-anchored order-agnostically vs fix(checkpoint): kind-route backfill writes to the store holding the checkpoint #1811; FetchCheckpointRef's inverted contract comment fixed; ref-checkpoint-backend.md updated)
• Full unit suite green (8180 tests), mise run fmt + mise run lint clean

Relationship to #1811

Independent; merges in either order (comments phrased order-agnostically). Reconciliation: whichever lands second drops #1811's "backfill absence probes are local-only" sentence from the kindRoutingStore Write doc comment.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes a consistency gap in the git-refs checkpoint store: backfill writes (summary, transcript finalize, attribution) now resolve a checkpoint ref the same way reads do—by attempting a one-time on-demand fetch when the ref is missing locally—preventing kind-routing fallthrough from writing backfills to a stale backend copy.

Changes:

• Introduces refBaseForBackfill (fetch-aware) and refactors shared tip/tree loading into refTip.
• Switches backfill write paths to use refBaseForBackfill while keeping creates on the local-only refBase.
• Adds unit tests covering fetch-on-backfill, fetch-failure behavior, genuine absence after fetch, and “creates never fetch”.

Reviewed changes

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

File	Description
cmd/entire/cli/checkpoint/refs_store.go	Adds fetch-aware base resolution for backfills and updates backfill writers to avoid false “not found” when a ref is missing locally.
cmd/entire/cli/checkpoint/refs_store_test.go	Adds targeted tests to pin backfill fetch behavior and failure/absence semantics.

[peyton-alt]

Fixed in 96013ab — backfillTranscript now has the same ctx.Err() short-circuit as its two siblings, so a cancelled context never reaches the (potentially fetching) base resolution.

[peyton-alt]

Applied the review fix set in 2b4b736. Highlights:

• Rescoped (review CRITICAL): the silent-failure agent found no production write path wires a RefFetcher, so the fetch branch was inert outside tests. Rather than wiring it hastily — which would break the pre-migration-hex fallthrough (git fetch of a ref the remote lacks fails like a network error, and the write path treats failure ≠ absence by design) and add multi-minute hook stalls — the PR is now honestly scoped as store-layer semantics, with the two wiring prerequisites named in the description.
• Tests hardened (coverage review): local-ref-never-fetches pin (zero-cost claim), read-back verification for all three backfill types, parent-hash assertion (no orphaning over fetched history).
• Comments re-anchored (comment review): the fix(checkpoint): kind-route backfill writes to the store holding the checkpoint #1811 write-fallthrough was cited as current fact; now phrased as the absence-vs-failure contract, order-agnostic. refBase's doc names the migrate.go and attach callers. FetchCheckpointRef's comment said callers treat fetch failure as not-found — the exact inversion of the contract; fixed.
• Docs: ref-checkpoint-backend.md write-shape and on-demand-fetch sections updated for the probe split.

Field test (fresh local clone, ref absent locally): the ref was fetched and restored end-to-end — via the read store's fetcher, which is exactly the masking the review identified; the write-path wiring remains the named follow-up. Full suite green (8173 tests).

[peyton-alt]

Wiring follow-through in b33b3c2 — the review's CRITICAL ("fix is inert: no production write path wires a RefFetcher") is now resolved rather than rescoped around. Both named prerequisites were implemented: absence-vs-failure discrimination via an ls-remote probe in the relocated remote.FetchCheckpointRef (remote-lacks-ref → plumbing.ErrReferenceNotFound wrap → safe fallthrough; transport failure → hard error), and a hook-safe budget (15s bounded fetcher + per-store failure memo, so N checkpoints on a dead network cost one short stall). Wired at explain --generate, stop-hook transcript finalize, and post-commit attribution; creates remain unwired by design. PR description rewritten to match. 8180 tests green, fmt + lint clean.

[peyton-alt]

Re-review of the wiring commit complete (code-reviewer + silent-failure agents, scoped to b33b3c2) — fixes applied in 96013ab and 4fdb8aa:

Code-reviewer: clean — probe semantics verified (same auth path as fetch, no tail-match over-matching, no prompt hang), memo concurrency correct, 15s budget correctly clamps the internal 2-minute timeout, layering sound.

Silent-failure agent found three HIGHs, all fixed:

1. False absence on a fallback target: when a checkpoint_remote is configured but unresolvable, the probe ran against an origin fallback that never hosts checkpoint refs and read its emptiness as absence — silently dropping backfills. fetchURLAuthoritative now marks fallback URLs non-authoritative; probe-emptiness there is a failure, never absence (regression-tested with a bogus-provider fixture).
2. SSH hygiene: hook wirings now use HookCheckpointRefFetcher (BatchMode SSH, matching the pre-push path) so a passphrase-protected key can't prompt or hang inside post-commit/stop hooks.
3. Undebuggable errors: lsRemote and the fetch leg now fold git's redacted stderr/output into their errors — no more bare exit status 128 in hook Warn logs.

Also: caller cancellation is no longer memoized as a network verdict (tested), the memoized-skip message clarifies its cause may name a different ref, mirrors never receive a RefFetcher, and the git-branch backfillTranscript gained the ctx.Err() guard its siblings have (the true home of Copilot's finding — the refs-store one was fixed in 96013ab).

Field-tested in a fresh clone: present-on-remote ref resolves end-to-end in ~3s; absent-everywhere ULID returns a clean not-found in under a second. Full suite green (8182 tests), fmt + lint clean.