feat(checkpoint): wire the backfill ref fetcher into write paths

Completes the #1824 fix — previously the fetch-probing backfill base was
store-layer plumbing with no production caller wiring a RefFetcher. The two
prerequisites the review named are now in place:

- remote.FetchCheckpointRef (moved from the cli package so strategy hooks
  can wire it; cli keeps thin aliases) probes with ls-remote before
  fetching: a ref the remote genuinely lacks returns an error wrapping
  plumbing.ErrReferenceNotFound (absence — safe fallthrough under kind
  routing), while transport failures on either leg surface as-is. git fetch
  of a missing refspec fails indistinguishably from a network error, which
  is why wiring was unsafe before this discrimination existed.
- Write probes are budget-bounded (remote.WriteProbeFetchBudget, 15s via
  remote.BoundedCheckpointRefFetcher) and the git-refs store memoizes the
  first transport-level fetch failure per store, so a stop hook finalizing
  N checkpoints on a dead network pays the outage once, briefly. Remote
  absence is per-ref and never memoized.

Wired at the three backfill write sites: explain --generate's write store,
the stop-hook transcript finalize, and post-commit attribution. The
carry-forward and other creates stay unwired — creates never probe.

Tests: remote-level absence/present/transport-failure fixtures against a
local bare origin; store-level absence classification chain-through and
failure-memo behavior (transport memoized once, absence never).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: peyton-alt

cmd/entire/cli/checkpoint/refs_store.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"log/slog"
 	"strconv"
+	"sync"
 
 	"github.com/go-git/go-git/v6"
 	"github.com/go-git/go-git/v6/plumbing"
@@ -34,6 +35,14 @@ type gitRefsStore struct {
 
 	blobFetcher BlobFetchFunc
 	refFetcher  RefFetchFunc
+
+	// fetchFailureMu guards fetchFailure: the first transport-level ref-fetch
+	// failure, memoized for the store's lifetime so a loop over N missing refs
+	// (e.g. a stop hook finalizing every checkpoint of a turn) pays a dead
+	// network once instead of N times. Genuine remote absence is per-ref and
+	// is never memoized.
+	fetchFailureMu sync.Mutex
+	fetchFailure   error
 }
 
 // newGitRefsStore constructs the per-checkpoint-ref store for a repository.
@@ -323,7 +332,26 @@ func (s *gitRefsStore) resolveRefMaybeFetch(ctx context.Context, cid id.Checkpoi
 	if s.refFetcher == nil {
 		return nil, err //nolint:wrapcheck // genuinely absent; caller maps ErrReferenceNotFound to ErrCheckpointNotFound
 	}
+	s.fetchFailureMu.Lock()
+	priorFailure := s.fetchFailure
+	s.fetchFailureMu.Unlock()
+	if priorFailure != nil {
+		return nil, fmt.Errorf("fetch checkpoint ref %s: skipping after earlier fetch failure: %w", refName, priorFailure)
+	}
 	if fetchErr := s.refFetcher(ctx, refName); fetchErr != nil {
+		if errors.Is(fetchErr, plumbing.ErrReferenceNotFound) {
+			// The fetcher probed the remote and it genuinely lacks this ref
+			// (remote.FetchCheckpointRef's absence signal) — absence, not a
+			// failure, and per-ref, so it is not memoized.
+			logging.Debug(ctx, "git-refs: remote has no such checkpoint ref",
+				slog.String("ref", refName.String()))
+			return nil, plumbing.ErrReferenceNotFound
+		}
+		s.fetchFailureMu.Lock()
+		if s.fetchFailure == nil {
+			s.fetchFailure = fetchErr
+		}
+		s.fetchFailureMu.Unlock()
 		logging.Debug(ctx, "git-refs: on-demand checkpoint ref fetch failed",
 			slog.String("ref", refName.String()), slog.String("error", fetchErr.Error()))
 		return nil, fmt.Errorf("fetch checkpoint ref %s: %w", refName, fetchErr)

cmd/entire/cli/checkpoint/refs_store_test.go

@@ -2,6 +2,7 @@ package checkpoint
 
 import (
 	"context"
+	"fmt"
 	"testing"
 
 	git "github.com/go-git/go-git/v6"
@@ -252,6 +253,79 @@ func TestGitRefsStore_BackfillFetchFailureAborts(t *testing.T) {
 		"a fetch failure must not read as absence")
 }
 
+// TestGitRefsStore_RemoteAbsenceFromFetcherIsNotFound pins the classification
+// chain for a fetcher that reports "the remote has no such ref" by wrapping
+// plumbing.ErrReferenceNotFound (remote.FetchCheckpointRef's absence signal):
+// both backfills and reads must treat it as checkpoint-not-found, not as a
+// hard failure.
+func TestGitRefsStore_RemoteAbsenceFromFetcherIsNotFound(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	store := newRefsStore(t)
+	store.SetRefFetcher(func(_ context.Context, rn plumbing.ReferenceName) error {
+		return fmt.Errorf("checkpoint ref %s not found on origin: %w", rn, plumbing.ErrReferenceNotFound)
+	})
+
+	err := store.Write(ctx, SessionSummary{
+		CheckpointID: id.MustCheckpointID("ffffffffffff"),
+		Summary:      &Summary{Intent: "orphan"},
+	})
+	require.ErrorIs(t, err, ErrCheckpointNotFound, "remote absence must classify as not-found for backfills")
+
+	summary, err := store.Read(ctx, id.MustCheckpointID("ffffffffffff"))
+	require.NoError(t, err)
+	assert.Nil(t, summary, "remote absence must classify as not-found for reads")
+}
+
+// TestGitRefsStore_FetchFailureMemoized: a transport-level fetch failure is
+// remembered for the store's lifetime, so a loop backfilling N checkpoints on
+// a dead network pays the outage once instead of N times (stop hooks finalize
+// every checkpoint of a turn). The memoized error stays a hard error — never
+// absence. Genuine remote absence is NOT memoized (per-ref, not an outage).
+func TestGitRefsStore_FetchFailureMemoized(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+
+	t.Run("transport failure fetched once", func(t *testing.T) {
+		t.Parallel()
+		store := newRefsStore(t)
+		calls := 0
+		store.SetRefFetcher(func(_ context.Context, _ plumbing.ReferenceName) error {
+			calls++
+			return assert.AnError
+		})
+
+		for _, cid := range []string{"aaaaaaaaaaaa", "bbbbbbbbbbbb"} {
+			err := store.Write(ctx, SessionSummary{
+				CheckpointID: id.MustCheckpointID(cid),
+				Summary:      &Summary{Intent: "x"},
+			})
+			require.ErrorIs(t, err, assert.AnError)
+			require.NotErrorIs(t, err, ErrCheckpointNotFound)
+		}
+		assert.Equal(t, 1, calls, "the outage must be paid once, not per checkpoint")
+	})
+
+	t.Run("remote absence not memoized", func(t *testing.T) {
+		t.Parallel()
+		store := newRefsStore(t)
+		calls := 0
+		store.SetRefFetcher(func(_ context.Context, rn plumbing.ReferenceName) error {
+			calls++
+			return fmt.Errorf("ref %s not on remote: %w", rn, plumbing.ErrReferenceNotFound)
+		})
+
+		for _, cid := range []string{"aaaaaaaaaaaa", "bbbbbbbbbbbb"} {
+			err := store.Write(ctx, SessionSummary{
+				CheckpointID: id.MustCheckpointID(cid),
+				Summary:      &Summary{Intent: "x"},
+			})
+			require.ErrorIs(t, err, ErrCheckpointNotFound)
+		}
+		assert.Equal(t, 2, calls, "absence is per-ref and must not suppress later fetches")
+	})
+}
+
 // TestGitRefsStore_BackfillAbsentAfterFetchIsNotFound pins the genuine-absence
 // contract: a fetch that succeeds but restores no ref means the checkpoint
 // really does not exist in this backend, and the backfill reports the

cmd/entire/cli/checkpoint/remote/checkpoint_ref.go

@@ -0,0 +1,87 @@
+package remote
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/go-git/go-git/v6/plumbing"
+)
+
+// WriteProbeFetchBudget bounds the on-demand ref fetch performed by a
+// BACKFILL's absence probe. Write paths run inside git hooks (post-commit,
+// stop-time finalize) where a dead network must not stall the user's
+// workflow for the read path's full fetch window; combined with the
+// per-store failure memo in the git-refs store, a loop over N checkpoints
+// pays a dead network once, briefly.
+const WriteProbeFetchBudget = 15 * time.Second
+
+// readFetchTimeout bounds the interactive read-path fetch (unchanged from
+// the historical FetchCheckpointRef behavior).
+const readFetchTimeout = 2 * time.Minute
+
+// CheckpointFetchTarget returns the git remote (URL or name) that checkpoint
+// data is fetched from. It prefers the effective URL resolved by FetchURL,
+// which is the source of truth for checkpoint fetch location. If URL
+// resolution fails, it falls back to the origin remote name so callers can
+// still attempt a fetch.
+func CheckpointFetchTarget(ctx context.Context) string {
+	url, err := FetchURL(ctx)
+	if err == nil && url != "" {
+		return url
+	}
+	return "origin"
+}
+
+// FetchCheckpointRef fetches a single per-checkpoint ref
+// (refs/entire/checkpoints/<shard>/<id>) from the checkpoint remote into the
+// local ref of the same name, so the git-refs store can resolve a checkpoint
+// written on another machine.
+//
+// Contract — absence is distinguishable from failure:
+//   - The remote genuinely lacking the ref returns an error wrapping
+//     plumbing.ErrReferenceNotFound (probed via ls-remote before fetching,
+//     because `git fetch` of a missing refspec fails indistinguishably from a
+//     transport error). Store probes classify this as "checkpoint not found",
+//     which write routing may legitimately act on.
+//   - Any transport-level failure (probe or fetch) is surfaced as a real
+//     error, never mapped to absence — a false "absent" would misdirect a
+//     backfill onto another backend instead of retrying.
+func FetchCheckpointRef(ctx context.Context, ref plumbing.ReferenceName) error {
+	ctx, cancel := context.WithTimeout(ctx, readFetchTimeout)
+	defer cancel()
+
+	fetchTarget := CheckpointFetchTarget(ctx)
+
+	out, err := LsRemoteInDir(ctx, "", fetchTarget, ref.String())
+	if err != nil {
+		// Redact: fetchTarget can be a remote URL with embedded credentials
+		// (CI origin URLs), and this error is logged and shown to users.
+		return fmt.Errorf("probe checkpoint ref %s on %s: %w", ref, RedactURL(fetchTarget), err)
+	}
+	if len(bytes.TrimSpace(out)) == 0 {
+		return fmt.Errorf("checkpoint ref %s not found on %s: %w", ref, RedactURL(fetchTarget), plumbing.ErrReferenceNotFound)
+	}
+
+	refSpec := "+" + ref.String() + ":" + ref.String()
+	if _, err := Fetch(ctx, FetchOptions{
+		Remote:   fetchTarget,
+		RefSpecs: []string{refSpec},
+		NoTags:   true,
+	}); err != nil {
+		return fmt.Errorf("fetch checkpoint ref %s from %s: %w", ref, RedactURL(fetchTarget), err)
+	}
+	return nil
+}
+
+// BoundedCheckpointRefFetcher returns a RefFetchFunc-shaped fetcher whose
+// per-call budget is capped at d, for wiring into write-path checkpoint
+// stores (see WriteProbeFetchBudget).
+func BoundedCheckpointRefFetcher(d time.Duration) func(context.Context, plumbing.ReferenceName) error {
+	return func(ctx context.Context, ref plumbing.ReferenceName) error {
+		ctx, cancel := context.WithTimeout(ctx, d)
+		defer cancel()
+		return FetchCheckpointRef(ctx, ref)
+	}
+}

cmd/entire/cli/checkpoint/remote/checkpoint_ref_test.go

@@ -0,0 +1,79 @@
+package remote
+
+import (
+	"context"
+	"os/exec"
+	"testing"
+
+	"github.com/go-git/go-git/v6/plumbing"
+	"github.com/stretchr/testify/require"
+
+	"github.com/entireio/cli/cmd/entire/cli/testutil"
+)
+
+// checkpointRefFixture creates a work repo whose origin is a local bare repo
+// holding (or not holding) a checkpoint ref, and chdirs into the work repo so
+// fetch-target resolution finds origin.
+func checkpointRefFixture(t *testing.T, withRef bool) (workDir string, ref plumbing.ReferenceName) {
+	t.Helper()
+	bareDir := t.TempDir()
+	out, err := exec.CommandContext(t.Context(), "git", "init", "--bare", bareDir).CombinedOutput()
+	require.NoError(t, err, "git init --bare: %s", out)
+
+	workDir = t.TempDir()
+	testutil.InitRepo(t, workDir)
+	testutil.WriteFile(t, workDir, "f.txt", "content")
+	testutil.GitAdd(t, workDir, "f.txt")
+	testutil.GitCommit(t, workDir, "init")
+	out, err = exec.CommandContext(t.Context(), "git", "-C", workDir, "remote", "add", "origin", bareDir).CombinedOutput()
+	require.NoError(t, err, "git remote add: %s", out)
+
+	ref = plumbing.ReferenceName("refs/entire/checkpoints/Z9/01KVBJCWYA4YW6J5M9GP655HZ9")
+	if withRef {
+		out, err = exec.CommandContext(t.Context(), "git", "-C", workDir, "push", "--quiet", "origin", "HEAD:"+ref.String()).CombinedOutput()
+		require.NoError(t, err, "git push checkpoint ref: %s", out)
+	}
+
+	t.Chdir(workDir)
+	return workDir, ref
+}
+
+// TestFetchCheckpointRef_RemoteMissingRefIsAbsence: a remote that does not
+// have the requested checkpoint ref is ABSENCE, not a transport failure — the
+// error must wrap plumbing.ErrReferenceNotFound so store probes (reads and
+// backfill writes) classify it as "checkpoint not found" and, under kind
+// routing, may legitimately fall through to another backend. Before this
+// distinction, git fetch of a missing refspec failed like a network error,
+// which made wiring a fetcher into write paths unsafe.
+func TestFetchCheckpointRef_RemoteMissingRefIsAbsence(t *testing.T) {
+	_, ref := checkpointRefFixture(t, false)
+
+	err := FetchCheckpointRef(context.Background(), ref)
+	require.Error(t, err)
+	require.ErrorIs(t, err, plumbing.ErrReferenceNotFound,
+		"a ref the remote does not have must classify as absence")
+}
+
+// TestFetchCheckpointRef_PresentRefFetches: the ref exists on the remote but
+// not locally; the fetch must create the local ref of the same name.
+func TestFetchCheckpointRef_PresentRefFetches(t *testing.T) {
+	workDir, ref := checkpointRefFixture(t, true)
+
+	require.NoError(t, FetchCheckpointRef(context.Background(), ref))
+
+	out, err := exec.CommandContext(t.Context(), "git", "-C", workDir, "show-ref", "--verify", ref.String()).CombinedOutput()
+	require.NoError(t, err, "fetched ref must exist locally: %s", out)
+}
+
+// TestFetchCheckpointRef_UnreachableRemoteIsFailure: a transport-level
+// failure (unreachable remote) must NOT classify as absence.
+func TestFetchCheckpointRef_UnreachableRemoteIsFailure(t *testing.T) {
+	workDir, ref := checkpointRefFixture(t, false)
+	out, err := exec.CommandContext(t.Context(), "git", "-C", workDir, "remote", "set-url", "origin", workDir+"/nonexistent-remote").CombinedOutput()
+	require.NoError(t, err, "%s", out)
+
+	err = FetchCheckpointRef(context.Background(), ref)
+	require.Error(t, err)
+	require.NotErrorIs(t, err, plumbing.ErrReferenceNotFound,
+		"a transport failure must stay distinguishable from absence")
+}

cmd/entire/cli/explain.go

@@ -23,6 +23,7 @@ import (
 	"github.com/entireio/cli/cmd/entire/cli/agent/types"
 	"github.com/entireio/cli/cmd/entire/cli/checkpoint"
 	"github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
+	"github.com/entireio/cli/cmd/entire/cli/checkpoint/remote"
 	"github.com/entireio/cli/cmd/entire/cli/interactive"
 	"github.com/entireio/cli/cmd/entire/cli/logging"
 	"github.com/entireio/cli/cmd/entire/cli/palette"
@@ -719,7 +720,12 @@ func runExplainCheckpointWithLookup(ctx context.Context, w, errW io.Writer, chec
 			return err
 		}
 		stopLoad(false) // generation prints its own progress to w/errW
-		writeStores, openErr := checkpoint.Open(ctx, lookup.repo, checkpoint.OpenOptions{})
+		// RefFetcher: the summary backfill's absence probe fetches a ref that
+		// exists remotely but not locally (written/migrated on another
+		// machine), bounded by the write-probe budget.
+		writeStores, openErr := checkpoint.Open(ctx, lookup.repo, checkpoint.OpenOptions{
+			RefFetcher: remote.BoundedCheckpointRefFetcher(remote.WriteProbeFetchBudget),
+		})
 		if openErr != nil {
 			return fmt.Errorf("open checkpoint store: %w", openErr)
 		}

cmd/entire/cli/git_operations.go

@@ -462,43 +462,18 @@ func FetchMetadataFromCheckpointRemote(ctx context.Context) error {
 }
 
 // resolveCheckpointFetchTarget returns the fetch target for checkpoint data.
-// It prefers the effective URL resolved by checkpoint/remote.FetchURL, which is
-// the source of truth for checkpoint fetch location. If URL resolution fails, it
-// falls back to the origin remote name so callers can still attempt a fetch.
+// Thin alias for remote.CheckpointFetchTarget (the single source of truth).
 func resolveCheckpointFetchTarget(ctx context.Context) string {
-	url, err := remote.FetchURL(ctx)
-	if err == nil && url != "" {
-		return url
-	}
-	return "origin"
+	return remote.CheckpointFetchTarget(ctx)
 }
 
-// FetchCheckpointRef fetches a single per-checkpoint ref (refs/entire/checkpoints/
-// <shard>/<id>) from the checkpoint remote into the local ref of the same name,
-// so the git-refs store can resolve a checkpoint written on another machine.
-//
-// Contract: a fetch failure is surfaced as a real error, never mapped to
-// "checkpoint not found" — callers (resolveRefMaybeFetch, for both reads and
-// backfill writes) deliberately keep transient unavailability distinguishable
-// from absence. Note this includes a ref the remote does not have: git fetch
-// of an explicit refspec fails outright, so "absent on the remote" currently
-// surfaces as a fetch error, not as absence.
+// FetchCheckpointRef fetches a single per-checkpoint ref from the checkpoint
+// remote. Thin alias for remote.FetchCheckpointRef, kept so existing cli-side
+// call sites and OpenOptions wiring stay unchanged; see that function for the
+// absence-vs-failure contract (remote-lacks-ref wraps
+// plumbing.ErrReferenceNotFound; transport failures surface as-is).
 func FetchCheckpointRef(ctx context.Context, ref plumbing.ReferenceName) error {
-	ctx, cancel := context.WithTimeout(ctx, 2*time.Minute)
-	defer cancel()
-
-	fetchTarget := resolveCheckpointFetchTarget(ctx)
-	refSpec := "+" + ref.String() + ":" + ref.String()
-	if _, err := remote.Fetch(ctx, remote.FetchOptions{
-		Remote:   fetchTarget,
-		RefSpecs: []string{refSpec},
-		NoTags:   true,
-	}); err != nil {
-		// Redact: fetchTarget can be a remote URL with embedded credentials
-		// (CI origin URLs), and this error is logged and shown to users.
-		return fmt.Errorf("fetch checkpoint ref %s from %s: %w", ref, remote.RedactURL(fetchTarget), err)
-	}
-	return nil
+	return remote.FetchCheckpointRef(ctx, ref) //nolint:wrapcheck // thin alias; the remote error carries full context
 }
 
 // FetchBlobsByHash fetches specific blob objects from the remote by their SHA-1 hashes.