fix(attribution): actionable guidance when checkpoint metadata is missing; refine session-fallback caveat

Addresses review feedback on #1535.

Karthik's report (community Discord + karthik-rameshkumar#1): `entire why`
on a line whose checkpoint metadata is missing printed
"Full context: entire checkpoint explain <id>", but running that command fails
identically ("no checkpoint or commit found matching <id>") because the same
remote fetch `why` attempts has already failed. The hint pointed at a command
that immediately errors.

- Resolve metadata-missing during attribution (resolveFileAttribution with
  fetchOnMiss) and record a MetadataMissingReason that states the cause and the
  actionable remedy: `git fetch <remote> entire/checkpoints/v1:...`, then re-run
  `entire checkpoint explain <id>`. Surfaced in the line and file `why` views
  and in JSON. Also drops the separate post-resolution enrich step, which left
  the checkpoint map non-deterministic across calls. (Mechanism and tests
  adapted from Karthik's PR.)
- Suppress the bare "Full context: entire checkpoint explain <id>" hint when
  metadata is missing: it would fail the same way, and the reason line above now
  gives the fetch-then-explain sequence.
- Refine the session-fallback caveat (Soph's review): flag the multi-session
  fallback whose chosen session has empty FilesTouched (one of several sessions,
  no path evidence) via `sessionsRead > 1 || len(FilesTouched) > 0`, while still
  suppressing the single-session empty-paths false positive. Tests for both.

Co-authored-by: karthik-rameshkumar <6728802+karthik-rameshkumar@users.noreply.github.com>

Author: suhaanthayyil

cmd/entire/cli/attribution.go

@@ -52,21 +52,22 @@ type rawBlameLine struct {
 }
 
 type attributionLine struct {
-	LineNumber      int                   `json:"line_number"`
-	Authorship      attributionAuthorship `json:"authorship"`
-	Tag             string                `json:"tag"`
-	CommitSHA       string                `json:"commit_sha,omitempty"`
-	ShortCommitSHA  string                `json:"short_commit_sha,omitempty"`
-	Author          string                `json:"author,omitempty"`
-	AuthorTime      *time.Time            `json:"author_time,omitempty"`
-	CheckpointID    string                `json:"checkpoint_id,omitempty"`
-	SessionID       string                `json:"session_id,omitempty"`
-	Agent           string                `json:"agent,omitempty"`
-	Model           string                `json:"model,omitempty"`
-	Prompt          string                `json:"prompt,omitempty"`
-	Intent          string                `json:"intent,omitempty"`
-	MetadataMissing bool                  `json:"metadata_missing,omitempty"`
-	SessionFallback bool                  `json:"session_fallback,omitempty"`
+	LineNumber            int                   `json:"line_number"`
+	Authorship            attributionAuthorship `json:"authorship"`
+	Tag                   string                `json:"tag"`
+	CommitSHA             string                `json:"commit_sha,omitempty"`
+	ShortCommitSHA        string                `json:"short_commit_sha,omitempty"`
+	Author                string                `json:"author,omitempty"`
+	AuthorTime            *time.Time            `json:"author_time,omitempty"`
+	CheckpointID          string                `json:"checkpoint_id,omitempty"`
+	SessionID             string                `json:"session_id,omitempty"`
+	Agent                 string                `json:"agent,omitempty"`
+	Model                 string                `json:"model,omitempty"`
+	Prompt                string                `json:"prompt,omitempty"`
+	Intent                string                `json:"intent,omitempty"`
+	MetadataMissing       bool                  `json:"metadata_missing,omitempty"`
+	MetadataMissingReason string                `json:"metadata_missing_reason,omitempty"`
+	SessionFallback       bool                  `json:"session_fallback,omitempty"`
 	// PromptSessionLevel is set when Prompt is the session's overall/seed prompt
 	// (e.g. an attach/trail ReviewPrompt) rather than a prompt recorded for this
 	// specific checkpoint. `why` labels these differently and points at
@@ -84,15 +85,16 @@ type attributionLine struct {
 // deduplicated per-file checkpoint map — so attributionCandidate aliases it
 // rather than duplicating the fields.
 type attributionCheckpointContext struct {
-	CheckpointID    string   `json:"checkpoint_id"`
-	SessionID       string   `json:"session_id,omitempty"`
-	Agent           string   `json:"agent,omitempty"`
-	Model           string   `json:"model,omitempty"`
-	Prompt          string   `json:"prompt,omitempty"`
-	Intent          string   `json:"intent,omitempty"`
-	FilesTouched    []string `json:"files_touched,omitempty"`
-	MetadataMissing bool     `json:"metadata_missing,omitempty"`
-	Mixed           bool     `json:"mixed,omitempty"`
+	CheckpointID          string   `json:"checkpoint_id"`
+	SessionID             string   `json:"session_id,omitempty"`
+	Agent                 string   `json:"agent,omitempty"`
+	Model                 string   `json:"model,omitempty"`
+	Prompt                string   `json:"prompt,omitempty"`
+	Intent                string   `json:"intent,omitempty"`
+	FilesTouched          []string `json:"files_touched,omitempty"`
+	MetadataMissing       bool     `json:"metadata_missing,omitempty"`
+	MetadataMissingReason string   `json:"metadata_missing_reason,omitempty"`
+	Mixed                 bool     `json:"mixed,omitempty"`
 	// SessionFallback is set when the file is not in any resolved session's
 	// recorded paths (e.g. it was renamed after the checkpoint) and the
 	// agent/prompt shown is a best-effort guess from the checkpoint's first
@@ -255,7 +257,9 @@ func runAttributionWhy(ctx context.Context, w io.Writer, target string, opts att
 		line, hasLine = n, true
 	}
 
-	result, err := resolveFileAttribution(ctx, file, false)
+	// entire why is explanation-focused: when local metadata is missing it
+	// should attempt the same remote enrichment path as checkpoint explain.
+	result, err := resolveFileAttribution(ctx, file, true)
 	if err != nil {
 		return err
 	}
@@ -278,13 +282,6 @@ func runAttributionWhy(ctx context.Context, w io.Writer, target string, opts att
 	if selected == nil {
 		return fmt.Errorf("line %d is outside %s", line, result.File)
 	}
-	if selected.MetadataMissing && selected.CheckpointID != "" {
-		if err := enrichAttributionLineWithFetch(ctx, result.File, selected, result.Checkpoints); err != nil {
-			// Remote metadata enrichment is best-effort; the trailer-level
-			// explanation is still useful and should remain available.
-			selected.MetadataMissing = true
-		}
-	}
 
 	if opts.JSON {
 		payload := struct {
@@ -334,8 +331,9 @@ func resolveFileAttribution(ctx context.Context, file string, fetchOnMiss bool)
 		for _, candidate := range line.Candidates {
 			if candidate.MetadataMissing {
 				result.Checkpoints[candidate.CheckpointID] = attributionCheckpointContext{
-					CheckpointID:    candidate.CheckpointID,
-					MetadataMissing: true,
+					CheckpointID:          candidate.CheckpointID,
+					MetadataMissing:       true,
+					MetadataMissingReason: candidate.MetadataMissingReason,
 				}
 				continue
 			}
@@ -450,12 +448,15 @@ func (r *attributionResolver) readCheckpointContext(cpID id.CheckpointID, file s
 	ctx := attributionCheckpointContext{CheckpointID: cpID.String()}
 	summary, err := readAttributionCheckpointSummary(r.ctx, r.store, cpID)
 	if err != nil && r.fetchOnMiss {
-		if fetched, fetchErr := r.fetchCheckpointContext(cpID, file); fetchErr == nil {
+		fetched, fetchErr := r.fetchCheckpointContext(cpID, file)
+		if fetchErr == nil {
 			return fetched
 		}
+		err = fmt.Errorf("%w (remote refresh failed: %v)", err, fetchErr)
 	}
 	if err != nil {
 		ctx.MetadataMissing = true
+		ctx.MetadataMissingReason = metadataMissingReason(r.ctx, cpID.String(), err)
 		return ctx
 	}
 
@@ -547,33 +548,15 @@ func readAttributionCheckpointSummary(ctx context.Context, reader attributionChe
 	return summary, nil
 }
 
-func enrichAttributionLineWithFetch(ctx context.Context, file string, line *attributionLine, checkpoints map[string]attributionCheckpointContext) error {
-	if line == nil || len(line.Candidates) == 0 {
-		return nil
+func metadataMissingReason(ctx context.Context, checkpointID string, cause error) string {
+	reason := "checkpoint metadata was not found locally"
+	if cause != nil {
+		reason = fmt.Sprintf("%s (%v)", reason, cause)
 	}
-	resolver, err := newAttributionResolver(ctx, true)
-	if err != nil {
-		return err
-	}
-	defer resolver.Close()
-
-	candidates := make([]attributionCandidate, 0, len(line.Candidates))
-	for _, candidate := range line.Candidates {
-		cpID, idErr := id.NewCheckpointID(candidate.CheckpointID)
-		if idErr != nil {
-			candidates = append(candidates, candidate)
-			continue
-		}
-		cpCtx := resolver.checkpointContext(cpID, file)
-		checkpoints[cpCtx.CheckpointID] = cpCtx
-		candidates = append(candidates, cpCtx)
+	if checkpointID == "" {
+		return fmt.Sprintf("%s. Run: %s.", reason, suggestCheckpointFetchCommand(ctx))
 	}
-	preferred := preferredAttributionCandidate(candidates, file)
-	applyPreferredToLine(line, preferred)
-	line.Candidates = candidates
-	line.Authorship = authorshipForPreferred(preferred)
-	line.Tag = attributionTag(line.Authorship)
-	return nil
+	return fmt.Sprintf("%s. Run: %s. Then re-run entire checkpoint explain %s.", reason, suggestCheckpointFetchCommand(ctx), checkpointID)
 }
 
 func (r *attributionResolver) fetchCheckpointContext(cpID id.CheckpointID, file string) (attributionCheckpointContext, error) {
@@ -1137,7 +1120,11 @@ func renderAttributionLineWhy(w io.Writer, file string, line attributionLine) {
 			fmt.Fprintf(w, "  %s %q\n", sty.render(sty.bold, "Intent:"), stringutil.TruncateRunes(stringutil.CollapseWhitespace(line.Intent), 160, "..."))
 		}
 		if line.MetadataMissing {
-			fmt.Fprintf(w, "  %s\n", sty.render(sty.yellow, "Checkpoint metadata was not found locally; showing trailer-level attribution only."))
+			message := "Checkpoint metadata was not found locally; showing trailer-level attribution only."
+			if line.MetadataMissingReason != "" {
+				message = line.MetadataMissingReason
+			}
+			fmt.Fprintf(w, "  %s\n", sty.render(sty.yellow, message))
 		}
 		if line.SessionFallback {
 			fmt.Fprintf(w, "  %s\n", sty.render(sty.yellow, "This file is not in the checkpoint session's recorded paths (it may have been renamed); the agent and prompt shown are a best-effort guess, not necessarily the session that produced this line."))
@@ -1201,6 +1188,13 @@ func renderAttributionFileWhy(w io.Writer, result *fileAttributionResult) {
 		if ctx.Prompt != "" {
 			fmt.Fprintf(w, " %s %q", sty.render(sty.dim, "·"), stringutil.TruncateRunes(stringutil.CollapseWhitespace(ctx.Prompt), 90, "..."))
 		}
+		if ctx.MetadataMissing {
+			message := "Checkpoint metadata was not found locally."
+			if ctx.MetadataMissingReason != "" {
+				message = ctx.MetadataMissingReason
+			}
+			fmt.Fprintf(w, "\n    %s %s", sty.render(sty.yellow, "metadata missing:"), message)
+		}
 		fmt.Fprintln(w)
 	}
 	fmt.Fprintf(w, "\n  %s\n\n", sty.render(sty.dim, "Tip: entire why "+result.File+":<line> shows the prompt behind a specific line."))
@@ -1301,6 +1295,7 @@ func applyPreferredToLine(line *attributionLine, preferred *attributionCandidate
 	line.Prompt = preferred.Prompt
 	line.Intent = preferred.Intent
 	line.MetadataMissing = preferred.MetadataMissing
+	line.MetadataMissingReason = preferred.MetadataMissingReason
 	line.SessionFallback = preferred.SessionFallback
 	line.PromptSessionLevel = preferred.PromptSessionLevel
 }

cmd/entire/cli/attribution_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"os/exec"
@@ -385,12 +386,40 @@ func TestAttributionResolverUsesCheckpointReader(t *testing.T) {
 	require.Equal(t, "Explain the authentication change.", ctx.Prompt)
 }
 
+func TestAttributionResolverMissingMetadataIncludesReason(t *testing.T) {
+	newAttributionRepo(t)
+
+	cpID := checkpointid.MustCheckpointID("cab2c3d4e5f6")
+	stubReader := &attributionCheckpointReaderStub{
+		readErr: errors.New("checkpoint summary unavailable"),
+	}
+	resolver := &attributionResolver{
+		ctx:             context.Background(),
+		store:           stubReader,
+		fetchOnMiss:     true,
+		checkpointCache: make(map[string]attributionCheckpointContext),
+	}
+
+	ctx := resolver.readCheckpointContext(cpID, "auth.py")
+	require.True(t, ctx.MetadataMissing)
+	require.Contains(t, ctx.MetadataMissingReason, "checkpoint summary unavailable")
+	// "remote refresh failed" confirms fetch-on-miss was attempted.
+	require.Contains(t, ctx.MetadataMissingReason, "remote refresh failed")
+	require.Contains(t, ctx.MetadataMissingReason, "git fetch ")
+	require.Contains(t, ctx.MetadataMissingReason, "entire/checkpoints/v1:entire/checkpoints/v1")
+	require.Contains(t, ctx.MetadataMissingReason, "entire checkpoint explain cab2c3d4e5f6")
+}
+
 type attributionCheckpointReaderStub struct {
 	summary *checkpoint.CheckpointSummary
 	content *checkpoint.SessionContent
+	readErr error
 }
 
 func (s *attributionCheckpointReaderStub) Read(context.Context, checkpointid.CheckpointID) (*checkpoint.CheckpointSummary, error) {
+	if s.readErr != nil {
+		return nil, s.readErr
+	}
 	return s.summary, nil
 }
 
@@ -519,6 +548,93 @@ func TestAttributionWhyPreservesLineIndentation(t *testing.T) {
 	require.Contains(t, out.String(), "      return True")
 }
 
+func TestAttributionWhyLineJSONShowsMissingMetadataReason(t *testing.T) {
+	repoRoot := newAttributionRepo(t)
+	testutil.WriteFile(t, repoRoot, "auth.py", "human_line = 1\nmissing_line = 2\n")
+	testutil.GitAdd(t, repoRoot, "auth.py")
+	testutil.GitCommit(t, repoRoot, trailers.FormatCheckpoint("missing metadata", checkpointid.MustCheckpointID("fab2c3d4e5f6")))
+
+	var out bytes.Buffer
+	require.NoError(t, runAttributionWhy(context.Background(), &out, "auth.py:2", true))
+
+	var payload struct {
+		File        string                                  `json:"file"`
+		Line        attributionLine                         `json:"line"`
+		Checkpoints map[string]attributionCheckpointContext `json:"checkpoints,omitempty"`
+	}
+	require.NoError(t, json.Unmarshal(out.Bytes(), &payload))
+	require.Equal(t, "auth.py", payload.File)
+	require.True(t, payload.Line.MetadataMissing)
+	require.Contains(t, payload.Line.MetadataMissingReason, "entire checkpoint explain fab2c3d4e5f6")
+	require.Contains(t, payload.Line.MetadataMissingReason, "git fetch ")
+	require.Contains(t, payload.Line.MetadataMissingReason, "entire/checkpoints/v1:entire/checkpoints/v1")
+	checkpointCtx := payload.Checkpoints["fab2c3d4e5f6"]
+	require.True(t, checkpointCtx.MetadataMissing)
+	require.Equal(t, payload.Line.MetadataMissingReason, checkpointCtx.MetadataMissingReason)
+}
+
+func TestAttributionWhyFileJSONShowsMissingMetadataReason(t *testing.T) {
+	repoRoot := newAttributionRepo(t)
+	testutil.WriteFile(t, repoRoot, "auth.py", "human_line = 1\nmissing_line = 2\n")
+	testutil.GitAdd(t, repoRoot, "auth.py")
+	testutil.GitCommit(t, repoRoot, trailers.FormatCheckpoint("missing metadata", checkpointid.MustCheckpointID("eab2c3d4e5f6")))
+
+	var out bytes.Buffer
+	require.NoError(t, runAttributionWhy(context.Background(), &out, "auth.py", true))
+
+	var payload fileAttributionResult
+	require.NoError(t, json.Unmarshal(out.Bytes(), &payload))
+	checkpointCtx := payload.Checkpoints["eab2c3d4e5f6"]
+	require.True(t, checkpointCtx.MetadataMissing)
+	require.Contains(t, checkpointCtx.MetadataMissingReason, "entire checkpoint explain eab2c3d4e5f6")
+}
+
+func TestAttributionWhyFileJSONLocalMetadataHasNoMissingReason(t *testing.T) {
+	repoRoot := newAttributionRepo(t)
+	writeAttributionCheckpoint(t, repoRoot, "dab2c3d4e5f6", checkpoint.WriteOptions{
+		SessionID:        "session-why-file-12345678",
+		Prompts:          []string{"Add a line with local checkpoint metadata."},
+		FilesTouched:     []string{"auth.py"},
+		Agent:            agent.AgentTypeClaudeCode,
+		CheckpointsCount: 1,
+	})
+	testutil.WriteFile(t, repoRoot, "auth.py", "human_line = 1\nwhy_line = 2\n")
+	testutil.GitAdd(t, repoRoot, "auth.py")
+	testutil.GitCommit(t, repoRoot, trailers.FormatCheckpoint("local metadata", checkpointid.MustCheckpointID("dab2c3d4e5f6")))
+
+	var out bytes.Buffer
+	require.NoError(t, runAttributionWhy(context.Background(), &out, "auth.py", true))
+
+	var payload fileAttributionResult
+	require.NoError(t, json.Unmarshal(out.Bytes(), &payload))
+	checkpointCtx := payload.Checkpoints["dab2c3d4e5f6"]
+	require.False(t, checkpointCtx.MetadataMissing)
+	require.Empty(t, checkpointCtx.MetadataMissingReason)
+}
+
+func TestAttributionWhySuccessiveCallsKeepCheckpointMapStable(t *testing.T) {
+	repoRoot := newAttributionRepo(t)
+	testutil.WriteFile(t, repoRoot, "auth.py", "human_line = 1\nmissing_line = 2\n")
+	testutil.GitAdd(t, repoRoot, "auth.py")
+	testutil.GitCommit(t, repoRoot, trailers.FormatCheckpoint("missing metadata", checkpointid.MustCheckpointID("bab2c3d4e5f6")))
+
+	var lineOut bytes.Buffer
+	require.NoError(t, runAttributionWhy(context.Background(), &lineOut, "auth.py:2", true))
+	require.Contains(t, lineOut.String(), "bab2c3d4e5f6")
+
+	var firstOut bytes.Buffer
+	require.NoError(t, runAttributionWhy(context.Background(), &firstOut, "auth.py", true))
+	var firstPayload fileAttributionResult
+	require.NoError(t, json.Unmarshal(firstOut.Bytes(), &firstPayload))
+
+	var secondOut bytes.Buffer
+	require.NoError(t, runAttributionWhy(context.Background(), &secondOut, "auth.py", true))
+	var secondPayload fileAttributionResult
+	require.NoError(t, json.Unmarshal(secondOut.Bytes(), &secondPayload))
+
+	require.Equal(t, firstPayload.Checkpoints, secondPayload.Checkpoints)
+}
+
 func newAttributionRepo(t *testing.T) string {
 	t.Helper()
 	repoRoot := t.TempDir()