fix(checkpoint): harden the write-probe fetcher per re-review

Findings from the wiring commit's multi-agent re-review:

- False absence on a fallback target (HIGH): when a checkpoint_remote is
  configured but unresolvable (unknown provider + unmappable origin
  protocol), FetchURL falls back to origin — a remote that never hosts the
  configured checkpoint refs. The ls-remote probe treated its emptiness as
  absence, silently dropping backfills for checkpoints that exist on the
  real checkpoint remote. fetchURLAuthoritative now reports whether the
  resolved URL is authoritative for checkpoint refs; probe-emptiness on a
  non-authoritative fallback is a failure, never absence.
- SSH hygiene in hooks (HIGH): the two hook wirings now use
  remote.HookCheckpointRefFetcher, which marks the context non-interactive
  (BatchMode SSH) like the pre-push path — a passphrase-protected key can
  no longer prompt or hang inside post-commit/stop hooks.
- Actionable errors (HIGH): lsRemote folds git's redacted stderr into its
  error, and FetchCheckpointRef folds the fetch output — a bare 'exit
  status 128' left auth, DNS, and missing-repo failures indistinguishable
  in hook Warn logs.
- Caller cancellation is no longer memoized as a network failure (a Ctrl-C
  mid-operation said nothing about the remote); the memoized-skip message
  notes its cause may name a different ref; mirrors never receive a
  RefFetcher (best-effort write-only copies must not pay network probes);
  the git-branch backfillTranscript gains the ctx.Err() guard its siblings
  have (pre-existing gap surfaced by the same review).

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

Author: peyton-alt

cmd/entire/cli/checkpoint/open.go

@@ -167,7 +167,11 @@ func buildMirrors(ctx context.Context, env OpenEnv, cfg *settings.CheckpointsCon
 			return nil, fmt.Errorf("checkpoints.mirrors[%d]: backend type %q is already used by the primary or another mirror; each backend type may appear at most once", i, m.Type)
 		}
 		seen[m.Type] = true
-		store, err := build(ctx, env, m.Type, m.Config)
+		// Mirrors are best-effort write-only copies whose failures are logged
+		// and dropped; never pay on-demand ref-fetch network probes for them.
+		mirrorEnv := env
+		mirrorEnv.RefFetcher = nil
+		store, err := build(ctx, mirrorEnv, m.Type, m.Config)
 		if err != nil {
 			return nil, fmt.Errorf("checkpoints.mirrors[%d]: %w", i, err)
 		}

cmd/entire/cli/checkpoint/persistent.go

@@ -1736,6 +1736,9 @@ func (s *GitStore) backfillSummary(ctx context.Context, checkpointID id.Checkpoi
 //
 // Returns ErrCheckpointNotFound if the checkpoint doesn't exist.
 func (s *GitStore) backfillTranscript(ctx context.Context, opts UpdateOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err //nolint:wrapcheck // Propagating context cancellation
+	}
 	if opts.CheckpointID.IsEmpty() {
 		return errors.New("invalid update options: checkpoint ID is required")
 	}

cmd/entire/cli/checkpoint/refs_store.go

@@ -38,9 +38,12 @@ type gitRefsStore struct {
 
 	// 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.
+	// (e.g. a stop hook finalizing every checkpoint of a turn) pays a dead —
+	// or too-slow-for-the-budget — network once instead of N times. Genuine
+	// remote absence is per-ref and
+	// is never memoized. The memo never clears — safe because every
+	// fetcher-wired store today is opened per command/hook invocation; a
+	// long-lived fetcher-wired store would need an expiry before reusing this.
 	fetchFailureMu sync.Mutex
 	fetchFailure   error
 }
@@ -339,7 +342,9 @@ func (s *gitRefsStore) resolveRefMaybeFetch(ctx context.Context, cid id.Checkpoi
 	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)
+		// Note the cause may name a DIFFERENT ref — it is the first failure
+		// of this operation, remembered so the outage is paid once.
+		return nil, fmt.Errorf("fetch checkpoint ref %s: skipped, an earlier checkpoint-ref fetch already failed in this operation: %w", refName, priorFailure)
 	}
 	if fetchErr := s.refFetcher(ctx, refName); fetchErr != nil {
 		if errors.Is(fetchErr, plumbing.ErrReferenceNotFound) {
@@ -350,11 +355,16 @@ func (s *gitRefsStore) resolveRefMaybeFetch(ctx context.Context, cid id.Checkpoi
 				slog.String("ref", refName.String()))
 			return nil, plumbing.ErrReferenceNotFound
 		}
-		s.fetchFailureMu.Lock()
-		if s.fetchFailure == nil {
-			s.fetchFailure = fetchErr
+		// Memoize only network verdicts: a cancellation originating from the
+		// CALLER's context says nothing about the remote and must not poison
+		// later fetches on this store.
+		if ctx.Err() == nil {
+			s.fetchFailureMu.Lock()
+			if s.fetchFailure == nil {
+				s.fetchFailure = fetchErr
+			}
+			s.fetchFailureMu.Unlock()
 		}
-		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

@@ -306,6 +306,36 @@ func TestGitRefsStore_FetchFailureMemoized(t *testing.T) {
 		assert.Equal(t, 1, calls, "the outage must be paid once, not per checkpoint")
 	})
 
+	t.Run("caller cancellation not memoized", func(t *testing.T) {
+		t.Parallel()
+		store := newRefsStore(t)
+		calls := 0
+		cancelCtx, cancel := context.WithCancel(context.Background())
+		store.SetRefFetcher(func(_ context.Context, _ plumbing.ReferenceName) error {
+			calls++
+			cancel() // the CALLER's context dies mid-fetch (e.g. Ctrl-C)
+			return context.Canceled
+		})
+		err := store.Write(cancelCtx, SessionSummary{
+			CheckpointID: id.MustCheckpointID("aaaaaaaaaaaa"),
+			Summary:      &Summary{Intent: "x"},
+		})
+		require.Error(t, err)
+
+		// A later fetch on the same store must still run: the cancellation
+		// said nothing about the network.
+		store.SetRefFetcher(func(_ context.Context, _ plumbing.ReferenceName) error {
+			calls++
+			return assert.AnError
+		})
+		err = store.Write(context.Background(), SessionSummary{
+			CheckpointID: id.MustCheckpointID("bbbbbbbbbbbb"),
+			Summary:      &Summary{Intent: "x"},
+		})
+		require.ErrorIs(t, err, assert.AnError)
+		assert.Equal(t, 2, calls, "a caller cancellation must not be memoized as a network failure")
+	})
+
 	t.Run("remote absence not memoized", func(t *testing.T) {
 		t.Parallel()
 		store := newRefsStore(t)

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

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/go-git/go-git/v6/plumbing"
@@ -27,11 +28,20 @@ const readFetchTimeout = 2 * time.Minute
 // 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)
+	target, _ := checkpointFetchTarget(ctx)
+	return target
+}
+
+// checkpointFetchTarget is CheckpointFetchTarget plus whether the target is
+// authoritative for checkpoint refs (see fetchURLAuthoritative). The bare
+// "origin" fallbacks are non-authoritative: they exist so a fetch can still
+// be attempted, not to certify where checkpoint refs live.
+func checkpointFetchTarget(ctx context.Context) (string, bool) {
+	url, authoritative, err := fetchURLAuthoritative(ctx)
 	if err == nil && url != "" {
-		return url
+		return url, authoritative
 	}
-	return "origin"
+	return "origin", false
 }
 
 // FetchCheckpointRef fetches a single per-checkpoint ref
@@ -52,7 +62,7 @@ func FetchCheckpointRef(ctx context.Context, ref plumbing.ReferenceName) error {
 	ctx, cancel := context.WithTimeout(ctx, readFetchTimeout)
 	defer cancel()
 
-	fetchTarget := CheckpointFetchTarget(ctx)
+	fetchTarget, authoritative := checkpointFetchTarget(ctx)
 
 	out, err := LsRemoteInDir(ctx, "", fetchTarget, ref.String())
 	if err != nil {
@@ -61,20 +71,47 @@ func FetchCheckpointRef(ctx context.Context, ref plumbing.ReferenceName) error {
 		return fmt.Errorf("probe checkpoint ref %s on %s: %w", ref, RedactURL(fetchTarget), err)
 	}
 	if len(bytes.TrimSpace(out)) == 0 {
+		if !authoritative {
+			// The probe hit an origin FALLBACK while a checkpoint_remote is
+			// configured (or undeterminable) — a remote that may simply never
+			// host the configured checkpoint refs. Emptiness there proves
+			// nothing; classifying it as absence would silently drop backfills
+			// for checkpoints that exist on the real checkpoint remote.
+			return fmt.Errorf("checkpoint ref %s not visible on fallback remote %s, and the configured checkpoint remote could not be resolved; refusing to treat this as absence", ref, RedactURL(fetchTarget))
+		}
 		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{
+	if fetchOut, err := Fetch(ctx, FetchOptions{
 		Remote:   fetchTarget,
 		RefSpecs: []string{refSpec},
 		NoTags:   true,
 	}); err != nil {
+		// Fold git's own output into the error (redacted): a bare
+		// "exit status 128" is undebuggable in hook Warn logs.
+		msg := strings.TrimSpace(string(fetchOut))
+		msg = strings.ReplaceAll(msg, fetchTarget, RedactURL(fetchTarget))
+		if msg != "" {
+			return fmt.Errorf("fetch checkpoint ref %s from %s: %s: %w", ref, RedactURL(fetchTarget), msg, err)
+		}
 		return fmt.Errorf("fetch checkpoint ref %s from %s: %w", ref, RedactURL(fetchTarget), err)
 	}
 	return nil
 }
 
+// HookCheckpointRefFetcher returns the write-probe fetcher for git-hook
+// contexts (post-commit attribution, stop-time transcript finalize): the
+// bounded budget plus BatchMode SSH, so a passphrase-protected key can never
+// prompt — or invisibly hang — inside a hook the user's git command is
+// waiting on.
+func HookCheckpointRefFetcher() func(context.Context, plumbing.ReferenceName) error {
+	bounded := BoundedCheckpointRefFetcher(WriteProbeFetchBudget)
+	return func(ctx context.Context, ref plumbing.ReferenceName) error {
+		return bounded(WithNonInteractiveSSH(ctx), ref)
+	}
+}
+
 // BoundedCheckpointRefFetcher returns a RefFetchFunc-shaped fetcher whose
 // per-call budget is capped at d, for wiring into write-path checkpoint
 // stores (see WriteProbeFetchBudget).

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

@@ -65,6 +65,23 @@ func TestFetchCheckpointRef_PresentRefFetches(t *testing.T) {
 	require.NoError(t, err, "fetched ref must exist locally: %s", out)
 }
 
+// TestFetchCheckpointRef_FallbackTargetNeverClassifiesAbsence: when a
+// checkpoint_remote is configured but cannot be resolved (unknown provider +
+// an origin whose protocol can't be mapped), the probe runs against an origin
+// FALLBACK that never hosts the configured checkpoint refs. Emptiness there
+// must be a failure, not absence — absence would silently drop backfills for
+// checkpoints that exist on the real checkpoint remote.
+func TestFetchCheckpointRef_FallbackTargetNeverClassifiesAbsence(t *testing.T) {
+	workDir, ref := checkpointRefFixture(t, false)
+	testutil.WriteFile(t, workDir, ".entire/settings.json",
+		`{"enabled": true, "strategy_options": {"checkpoint_remote": {"provider": "bogusforge", "repo": "acme/checkpoints"}}}`)
+
+	err := FetchCheckpointRef(context.Background(), ref)
+	require.Error(t, err)
+	require.NotErrorIs(t, err, plumbing.ErrReferenceNotFound,
+		"emptiness on a non-authoritative fallback target must not classify as absence")
+}
+
 // TestFetchCheckpointRef_UnreachableRemoteIsFailure: a transport-level
 // failure (unreachable remote) must NOT classify as absence.
 func TestFetchCheckpointRef_UnreachableRemoteIsFailure(t *testing.T) {

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

@@ -3,6 +3,7 @@ package remote
 import (
 	"context"
 	"encoding/base64"
+	"errors"
 	"fmt"
 	"log/slog"
 	"os"
@@ -461,6 +462,15 @@ func lsRemote(ctx context.Context, dir, remote string, patterns ...string) ([]by
 	disableTerminalPrompt(cmd)
 	out, err := cmd.Output()
 	if err != nil {
+		// Fold git's stderr into the error (redacted): a bare "exit status
+		// 128" leaves auth, DNS, and missing-repo failures indistinguishable.
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			if msg := strings.TrimSpace(string(exitErr.Stderr)); msg != "" {
+				msg = strings.ReplaceAll(msg, remote, RedactURL(remote))
+				return out, fmt.Errorf("git ls-remote: %w: %s", err, msg)
+			}
+		}
 		return out, fmt.Errorf("git ls-remote: %w", err)
 	}
 	return out, nil

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

@@ -39,6 +39,18 @@ type FetchURLOptions struct {
 // If ENTIRE_CHECKPOINT_TOKEN is set and a checkpoint remote is configured, HTTPS is
 // forced so the token can be used even when origin is configured via SSH.
 func FetchURL(ctx context.Context, opts ...FetchURLOptions) (string, error) {
+	url, _, err := fetchURLAuthoritative(ctx, opts...)
+	return url, err
+}
+
+// fetchURLAuthoritative is FetchURL plus whether the returned URL is
+// authoritative for checkpoint refs. It is false exactly when a
+// checkpoint_remote IS configured (or cannot be determined) but resolution
+// fell back to the origin URL — a remote that by construction does not host
+// the configured checkpoint refs. Callers that classify "ref absent on the
+// remote" (FetchCheckpointRef's ls-remote probe) must not treat emptiness on
+// a non-authoritative target as absence.
+func fetchURLAuthoritative(ctx context.Context, opts ...FetchURLOptions) (string, bool, error) {
 	var opt FetchURLOptions
 	if len(opts) > 0 {
 		opt = opts[0]
@@ -69,17 +81,20 @@ func FetchURL(ctx context.Context, opts ...FetchURLOptions) (string, error) {
 	if err != nil {
 		if originURL != "" {
 			logFallback(ctx, "fetch", originURL, "load settings", err)
-			return originURL, nil
+			// Settings unreadable → checkpoint_remote unknown; conservative:
+			// do not certify origin as authoritative for checkpoint refs.
+			return originURL, false, nil
 		}
-		return "", fmt.Errorf("load settings: %w", err)
+		return "", false, fmt.Errorf("load settings: %w", err)
 	}
 
 	config := s.GetCheckpointRemote()
 	if config == nil {
 		if originURL == "" {
-			return "", fmt.Errorf("no fetch URL found: %w", originErr)
+			return "", false, fmt.Errorf("no fetch URL found: %w", originErr)
 		}
-		return originURL, nil
+		// No checkpoint_remote configured: origin IS the checkpoint host.
+		return originURL, true, nil
 	}
 
 	if withToken {
@@ -90,25 +105,25 @@ func FetchURL(ctx context.Context, opts ...FetchURLOptions) (string, error) {
 				Host:     host,
 			}, config)
 			if err == nil {
-				return checkpointURL, nil
+				return checkpointURL, true, nil
 			}
 		}
 
 		// In token-based execution path, short-circuit to avoid additional
 		// change in protocol.
 		if originURL != "" {
-			return originURL, nil
+			return originURL, false, nil
 		}
 	}
 
 	if originURL == "" {
-		return "", fmt.Errorf("no fetch URL found: %w", originErr)
+		return "", false, fmt.Errorf("no fetch URL found: %w", originErr)
 	}
 
 	info, err := ParseURL(originURL)
 	if err != nil {
 		logFallback(ctx, "fetch", originURL, "parse origin remote URL", err)
-		return originURL, nil
+		return originURL, false, nil
 	}
 
 	checkpointURL, err := deriveCheckpointURLFromInfo(info, config)
@@ -118,13 +133,13 @@ func FetchURL(ctx context.Context, opts ...FetchURLOptions) (string, error) {
 		// provider). Honor the configured checkpoint_remote by targeting the
 		// provider's canonical host over HTTPS rather than falling back to origin.
 		if providerURL, ok := resolveProviderCheckpointURL(config, opt.WorktreeRoot); ok {
-			return providerURL, nil
+			return providerURL, true, nil
 		}
 		logFallback(ctx, "fetch", originURL, "derive checkpoint remote URL", err)
-		return originURL, nil
+		return originURL, false, nil
 	}
 
-	return checkpointURL, nil
+	return checkpointURL, true, nil
 }
 
 // PushURL returns the effective checkpoint push URL for the current repository.

cmd/entire/cli/strategy/manual_commit_hooks.go

@@ -1068,7 +1068,7 @@ func (s *ManualCommitStrategy) updateCombinedAttributionForCheckpoint(
 	// exists remotely but not locally. Bounded budget + the store's failure
 	// memo keep a dead network from stalling the post-commit hook.
 	stores, err := checkpoint.Open(ctx, repo, checkpoint.OpenOptions{
-		RefFetcher: remote.BoundedCheckpointRefFetcher(remote.WriteProbeFetchBudget),
+		RefFetcher: remote.HookCheckpointRefFetcher(),
 	})
 	if err != nil {
 		return fmt.Errorf("open checkpoint store: %w", err)
@@ -2908,7 +2908,7 @@ func (s *ManualCommitStrategy) finalizeAllTurnCheckpoints(ctx context.Context, s
 	// sessions). Bounded budget + the store's failure memo keep a dead
 	// network from stalling the stop hook N times.
 	stores, err := checkpoint.Open(ctx, repo, checkpoint.OpenOptions{
-		RefFetcher: remote.BoundedCheckpointRefFetcher(remote.WriteProbeFetchBudget),
+		RefFetcher: remote.HookCheckpointRefFetcher(),
 	})
 	if err != nil {
 		logging.Warn(logCtx, "finalize: failed to open checkpoint store",