Merge pull request #1819 from entireio/fix/git-refs-skip-v1-orphan-seed

fix: skip empty v1 orphan seed under git-refs backend

Author: gtrrz-victor

cmd/entire/cli/strategy/common.go

@@ -464,6 +464,17 @@ func resolveAgentType(ctxAgentType types.AgentType, state *SessionState) types.A
 // origin holds the store — when Primary is in Push and the local ref is missing
 // or un-initialized, the local ref is created/updated from origin's
 // remote-tracking ref. Otherwise an empty orphan is created.
+// primaryIsGitRefs reports whether the configured primary checkpoint backend is
+// git-refs. Resolution is fail-soft: any config-load error is treated as the
+// default git-branch backend (returns false), preserving legacy behavior.
+func primaryIsGitRefs(ctx context.Context) bool {
+	cfg, err := settings.LoadCheckpointsConfig(ctx)
+	if err != nil {
+		return false
+	}
+	return checkpoint.PrimaryIsRefs(cfg)
+}
+
 func EnsurePrimaryRef(ctx context.Context, repo *git.Repository) error {
 	// Rebind settings/remote resolution to the repository being modified rather
 	// than the ambient working directory, so the "is a checkpoint_remote
@@ -477,6 +488,17 @@ func EnsurePrimaryRef(ctx context.Context, repo *git.Repository) error {
 	refs := checkpoint.ResolveRefs(ctx)
 	primaryName := refs.Primary.Short()
 
+	// Under the git-refs primary backend, checkpoints are written to
+	// per-checkpoint refs and nothing is ever written to the v1 metadata
+	// branch. Seeding an empty orphan v1 here would leave a vestigial,
+	// never-written branch — the surprise a user hit when `entire enable`
+	// selected git-refs yet still created entire/checkpoints/v1. We still adopt
+	// real v1 data that already exists on origin or a checkpoint_remote below
+	// (so legacy checkpoints stay readable); we only suppress the empty-orphan
+	// fallback. Resolution is fail-soft: an unreadable config keeps the legacy
+	// git-branch seeding behavior.
+	skipEmptyOrphan := primaryIsGitRefs(ctx)
+
 	localRef, localErr := repo.Reference(refs.Primary, true)
 	if localErr != nil && !errors.Is(localErr, plumbing.ErrReferenceNotFound) {
 		return fmt.Errorf("failed to check metadata ref: %w", localErr)
@@ -515,6 +537,9 @@ func EnsurePrimaryRef(ctx context.Context, repo *git.Repository) error {
 		// Nothing usable on the checkpoint remote (fetch skipped/failed or the
 		// remote has no data) — create a fresh orphan that future pushes publish
 		// there. Still never origin.
+		if skipEmptyOrphan {
+			return nil
+		}
 		return createOrphanMetadataRef(ctx, repo, refs)
 	}
 
@@ -565,6 +590,9 @@ func EnsurePrimaryRef(ctx context.Context, repo *git.Repository) error {
 	}
 
 	// No local or origin ref — create an empty orphan.
+	if skipEmptyOrphan {
+		return nil
+	}
 	return createOrphanMetadataRef(ctx, repo, refs)
 }
 

cmd/entire/cli/strategy/common_test.go

@@ -988,6 +988,38 @@ func TestEnsurePrimaryRef(t *testing.T) {
 			t.Errorf("expected empty tree, got %d entries", len(tree.Entries))
 		}
 	})
+
+	t.Run("skips empty orphan when primary is git-refs", func(t *testing.T) {
+		t.Parallel()
+		dir := t.TempDir()
+		initTestRepo(t, dir)
+
+		// Select the git-refs backend for this repo. EnsurePrimaryRef rebinds
+		// the config lookup to the repo root, so a repo-local settings file is
+		// what it reads.
+		settingsDir := filepath.Join(dir, ".entire")
+		if err := os.MkdirAll(settingsDir, 0o750); err != nil {
+			t.Fatalf("failed to create .entire dir: %v", err)
+		}
+		cfg := []byte(`{"checkpoints":{"primary":{"type":"git-refs"}}}`)
+		if err := os.WriteFile(filepath.Join(settingsDir, "settings.json"), cfg, 0o600); err != nil {
+			t.Fatalf("failed to write settings: %v", err)
+		}
+
+		repo, err := git.PlainOpen(dir)
+		if err != nil {
+			t.Fatalf("failed to open repo: %v", err)
+		}
+		if err := EnsurePrimaryRef(t.Context(), repo); err != nil {
+			t.Fatalf("EnsurePrimaryRef() failed: %v", err)
+		}
+
+		// Under git-refs, checkpoints live in per-checkpoint refs and nothing
+		// is ever written to v1, so no vestigial empty orphan should be created.
+		_, err = repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
+		require.ErrorIs(t, err, plumbing.ErrReferenceNotFound,
+			"expected no v1 branch under git-refs primary")
+	})
 }
 
 func TestEnsurePrimaryRef_WritesVercelConfigWhenEnabled(t *testing.T) {