fix(attach): tolerate unpublished v1 branch on explicit-target refresh

Same gap as the git-refs fix, on the git-branch backend: a repo that has
never published entire/checkpoints/v1 made the fail-closed refresh reject
every explicit-target attach. Probe the branch with ls-remote first —
absent means genuinely new (proceed); transport/auth failures still fail
closed. Also extracts readAttachTranscript to keep runAttach under the
maintidx threshold.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Entire-Checkpoint: 01KY56BD4NF340J1HV27JC0CZF

Author: dipree

cmd/entire/cli/attach.go

@@ -17,6 +17,7 @@ import (
 	"github.com/entireio/cli/cmd/entire/cli/agent/types"
 	cpkg "github.com/entireio/cli/cmd/entire/cli/checkpoint"
 	"github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
+	checkpointremote "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"
 	cliReview "github.com/entireio/cli/cmd/entire/cli/review"
@@ -286,26 +287,15 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 		reviewSkills = resolveReviewSkills(opts.ReviewSkillsOverride)
 	}
 
-	transcriptData, err := ag.ReadTranscript(transcriptPath)
+	transcriptData, storedTranscript, err := readAttachTranscript(logCtx, ag, transcriptPath)
 	if err != nil {
-		return fmt.Errorf("failed to read transcript: %w", err)
-	}
-
-	// Normalize Gemini transcripts for storage.
-	storedTranscript := transcriptData
-	if ag.Type() == agent.AgentTypeGemini {
-		if normalized, normErr := geminicli.NormalizeTranscript(transcriptData); normErr == nil {
-			storedTranscript = normalized
-		} else {
-			logging.Warn(logCtx, "failed to normalize Gemini transcript, storing raw", "error", normErr)
-		}
+		return err
 	}
-
 	meta := extractTranscriptMetadata(transcriptData)
 	warnEmptyTranscriptMetadata(errW, ag.Name(), meta, opts)
+	tokenUsage := agent.CalculateTokenUsage(logCtx, ag, transcriptData, 0, "")
 
-	// Determine checkpoint ID: an explicit target uses the caller-supplied ID
-	// (new by construction, bound to opts.CommitSHA); otherwise reuse HEAD's
+	// Explicit targets use the caller-supplied ID; otherwise reuse HEAD's
 	// trailer if present or generate a fresh ID.
 	var checkpointID id.CheckpointID
 	var isExistingCheckpoint bool
@@ -343,6 +333,12 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 		}
 	}
 
+	saveState := func() {
+		if err := saveAttachSessionState(logCtx, repo, existingState, sessionID, ag.Type(), transcriptPath, checkpointID, meta, tokenUsage, opts, reviewSkills); err != nil {
+			logging.Warn(logCtx, "failed to save session state", "error", err)
+		}
+	}
+
 	if opts.explicitTarget() {
 		freshRepo, alreadyAttached, expErr := prepareExplicitTarget(ctx, logCtx, w, repo, refs, checkpointID, sessionID)
 		if freshRepo != repo {
@@ -357,6 +353,10 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 			return expErr
 		}
 		if alreadyAttached {
+			// The checkpoint write may have succeeded on an earlier attempt while
+			// its best-effort state save failed. Repair local state on every
+			// idempotent retry before returning success.
+			saveState()
 			return nil
 		}
 	}
@@ -366,8 +366,6 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 		return fmt.Errorf("failed to get git author: %w", err)
 	}
 
-	tokenUsage := agent.CalculateTokenUsage(logCtx, ag, transcriptData, 0, "")
-
 	_, redactSpan := perf.Start(ctx, "redact_transcript")
 	redactedTranscript, redactErr := redact.JSONLBytes(storedTranscript)
 	redactSpan.End()
@@ -400,9 +398,7 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 	}
 
 	// Create or update session state.
-	if err := saveAttachSessionState(logCtx, repo, existingState, sessionID, ag.Type(), transcriptPath, checkpointID, meta, tokenUsage, opts, reviewSkills); err != nil {
-		logging.Warn(logCtx, "failed to save session state", "error", err)
-	}
+	saveState()
 
 	fmt.Fprintf(w, "Attached session %s\n", sessionID)
 	printAttachFooter(w, meta, tokenUsage)
@@ -578,6 +574,24 @@ func ensureCheckpointAvailable(ctx, logCtx context.Context, repo *git.Repository
 	return repo, missingCheckpointError(logCtx, checkpointID, primaryIsRefs)
 }
 
+// readAttachTranscript reads the session transcript, normalizing Gemini
+// transcripts for storage (raw is kept when normalization fails).
+func readAttachTranscript(logCtx context.Context, ag agent.Agent, transcriptPath string) ([]byte, []byte, error) {
+	transcriptData, err := ag.ReadTranscript(transcriptPath)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to read transcript: %w", err)
+	}
+	storedTranscript := transcriptData
+	if ag.Type() == agent.AgentTypeGemini {
+		if normalized, normErr := geminicli.NormalizeTranscript(transcriptData); normErr == nil {
+			storedTranscript = normalized
+		} else {
+			logging.Warn(logCtx, "failed to normalize Gemini transcript, storing raw", "error", normErr)
+		}
+	}
+	return transcriptData, storedTranscript, nil
+}
+
 // linkExistingSessionCheckpoint handles a session whose state already records
 // a checkpoint: reviews are refused (review-upgrade of an existing checkpoint
 // is unsupported), otherwise the existing checkpoint is offered as a trailer
@@ -655,8 +669,8 @@ func prepareExplicitTarget(ctx, logCtx context.Context, w io.Writer, repo *git.R
 // after the refresh is NOT an error — an explicit-target ID is normally brand
 // new; the refresh exists so a retry from a fresh clone sees the earlier
 // attempt instead of rebuilding the ID as an orphan that would clobber it on
-// push. For git-refs, an explicitly missing remote source ref proves the ID is
-// new and is safe to proceed; transport/auth/unknown failures still fail closed.
+// push. An explicitly missing remote source ref/branch proves the ID is new and
+// is safe to proceed; transport/auth/unknown failures still fail closed.
 func ensureExplicitCheckpointFreshness(ctx context.Context, repo *git.Repository, refs cpkg.PersistentRefs, checkpointID id.CheckpointID) (*git.Repository, bool, error) {
 	cfg, err := settings.LoadCheckpointsConfig(ctx)
 	if err != nil {
@@ -672,6 +686,16 @@ func ensureExplicitCheckpointFreshness(ctx context.Context, repo *git.Repository
 		return repo, true, nil
 	}
 
+	if !primaryIsRefs {
+		remotePresent, probeErr := explicitTargetMetadataBranchPresent(ctx, refs)
+		if probeErr != nil {
+			return repo, false, fmt.Errorf("failed to probe explicit checkpoint metadata branch before attach: %w", probeErr)
+		}
+		if !remotePresent {
+			return repo, false, nil
+		}
+	}
+
 	freshRepo, fetchErr := refreshCheckpoint(ctx, checkpointID, primaryIsRefs)
 	if fetchErr != nil {
 		if primaryIsRefs && errors.Is(fetchErr, errCheckpointRefNotFound) {
@@ -686,6 +710,21 @@ func ensureExplicitCheckpointFreshness(ctx context.Context, repo *git.Repository
 	return freshRepo, present, nil
 }
 
+// explicitTargetMetadataBranchPresent distinguishes a genuinely unpublished v1
+// branch from an inconclusive fetch failure. `git ls-remote` succeeds with empty
+// output when the branch is absent, while transport/auth failures return errors.
+func explicitTargetMetadataBranchPresent(ctx context.Context, refs cpkg.PersistentRefs) (bool, error) {
+	fetchTarget, err := checkpointremote.FetchURL(ctx)
+	if err != nil {
+		return false, fmt.Errorf("resolve checkpoint fetch target: %w", err)
+	}
+	output, err := checkpointremote.LsRemoteInDir(ctx, "", fetchTarget, refs.Primary.String())
+	if err != nil {
+		return false, fmt.Errorf("list metadata branch on %s: %w", checkpointremote.RedactURL(fetchTarget), err)
+	}
+	return strings.TrimSpace(string(output)) != "", nil
+}
+
 // refreshCheckpoint fetches the checkpoint referenced by HEAD from the remote and
 // returns a freshly-opened repo so go-git sees the newly-fetched refs/packfiles.
 // The fetch is backend-aware: git-refs fetches just this checkpoint's ref, while

cmd/entire/cli/attach_test.go

@@ -1171,7 +1171,9 @@ func TestAttach_ReviewWithExistingCheckpointErrors(t *testing.T) {
 // when HEAD carries no Entire-Checkpoint trailer, and must never amend HEAD.
 func TestAttach_ReviewExplicitTargetCreatesShaBoundCheckpoint(t *testing.T) {
 	setupAttachTestRepo(t)
-	setupAttachCheckpointOrigin(t)
+	// A reachable origin with no metadata branch is the normal first-checkpoint
+	// case and must be accepted as a genuinely new explicit target.
+	setupAttachBareOrigin(t)
 
 	repoRoot := mustGetwd(t)
 	repo, err := git.PlainOpen(repoRoot)
@@ -1307,6 +1309,107 @@ func TestAttach_ReviewExplicitTargetCreatesShaBoundCheckpoint(t *testing.T) {
 	}
 }
 
+// An idempotent retry must repair session state as well as avoid duplicating
+// checkpoint data. This models a first attach whose checkpoint write succeeded
+// but whose best-effort state save failed.
+func TestAttach_ExplicitTargetRetryRepairsMissingSessionState(t *testing.T) {
+	setupAttachTestRepo(t)
+	setupAttachCheckpointOrigin(t)
+
+	repoRoot := mustGetwd(t)
+	sessionID := "review-session-retry-state-repair"
+	setupClaudeTranscript(t, sessionID, `{"type":"user","message":{"role":"user","content":"review retry state"},"uuid":"u1"}
+`)
+	targetID := id.CheckpointID("aabbccddeeff")
+	opts := attachOptions{
+		Force:                true,
+		Review:               true,
+		ReviewSkillsOverride: []string{"/security-review"},
+		ReviewPromptOverride: "review the target commit for security regressions",
+		CheckpointID:         targetID,
+	}
+
+	var out bytes.Buffer
+	if err := runAttach(context.Background(), &out, &out, sessionID, agent.AgentNameClaudeCode, opts); err != nil {
+		t.Fatalf("first explicit-target attach failed: %v", err)
+	}
+	stateFile := filepath.Join(repoRoot, ".git", "entire-sessions", sessionID+".json")
+	if err := os.Remove(stateFile); err != nil {
+		t.Fatalf("remove state to simulate failed first save: %v", err)
+	}
+
+	out.Reset()
+	if err := runAttach(context.Background(), &out, &out, sessionID, agent.AgentNameClaudeCode, opts); err != nil {
+		t.Fatalf("idempotent retry failed: %v", err)
+	}
+	if !strings.Contains(out.String(), "already attached") {
+		t.Fatalf("retry did not take idempotent path: %q", out.String())
+	}
+
+	stateStore, err := session.NewStateStore(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	state, err := stateStore.Load(context.Background(), sessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if state == nil {
+		t.Fatal("retry did not recreate session state")
+	}
+	if state.AgentType != agent.AgentTypeClaudeCode {
+		t.Errorf("AgentType = %q, want %q", state.AgentType, agent.AgentTypeClaudeCode)
+	}
+	if state.Kind != session.KindAgentReview {
+		t.Errorf("Kind = %q, want %q", state.Kind, session.KindAgentReview)
+	}
+	if !reflect.DeepEqual(state.ReviewSkills, opts.ReviewSkillsOverride) {
+		t.Errorf("ReviewSkills = %v, want %v", state.ReviewSkills, opts.ReviewSkillsOverride)
+	}
+	if state.ReviewPrompt != opts.ReviewPromptOverride {
+		t.Errorf("ReviewPrompt = %q, want %q", state.ReviewPrompt, opts.ReviewPromptOverride)
+	}
+	if !state.LastCheckpointID.IsEmpty() || state.BaseCommit != "" {
+		t.Errorf("retry incorrectly trailer-linked explicit checkpoint: LastCheckpointID=%s BaseCommit=%q", state.LastCheckpointID, state.BaseCommit)
+	}
+}
+
+// A missing metadata branch on a reachable origin is safe, but a failed branch
+// probe is inconclusive and must not create a local v1 orphan under the supplied
+// checkpoint ID.
+func TestAttach_ExplicitTargetGitBranchRejectsProbeFailure(t *testing.T) {
+	setupAttachTestRepo(t)
+
+	repoRoot := mustGetwd(t)
+	runGit(t, repoRoot, "remote", "add", "origin", filepath.Join(t.TempDir(), "missing.git"))
+	sessionID := "review-session-broken-metadata-remote"
+	setupClaudeTranscript(t, sessionID, `{"type":"user","message":{"role":"user","content":"review retry"},"uuid":"u1"}
+`)
+	targetID := id.CheckpointID("aabbccddeeff")
+
+	var out bytes.Buffer
+	err := runAttach(context.Background(), &out, &out, sessionID, agent.AgentNameClaudeCode, attachOptions{
+		Force:        true,
+		Review:       true,
+		CheckpointID: targetID,
+	})
+	if err == nil || !strings.Contains(err.Error(), "failed to probe explicit checkpoint metadata branch") {
+		t.Fatalf("expected inconclusive metadata probe to fail closed, got: %v", err)
+	}
+
+	stateStore, err := session.NewStateStore(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	state, err := stateStore.Load(context.Background(), sessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if state != nil {
+		t.Fatalf("session state was written after an inconclusive metadata probe: %+v", state)
+	}
+}
+
 // Under git-refs, a brand-new explicit-target ID has no source ref on the
 // remote. Git reports that as a failed fetch; attach must recognize this
 // specific absence as the safe, normal create path.