refactor(gitrepo): route all repo opens through gitrepo for reftable safety

checkpoint/remote's openRepoAt opened repositories with
git.PlainOpenWithOptions directly, bypassing the reftable-aware opener. On a
reftable repository that call fails with 'unknown extension: refstorage', so
provider checkpoint-URL resolution silently lost the ability to reuse an
existing remote's scheme. Route openRepoAt through gitrepo.OpenCurrent/OpenPath
(threading ctx) so every repo open goes through the single reftable- and
alternates-aware entry point.

Detect reftable stacks with os.Lstat instead of os.Stat so a symlink in place
of the reftable/ directory is not mistaken for a genuine stack.

Document in CLAUDE.md that gitrepo is the sole sanctioned opener and no code
may call git.Open/PlainOpen directly. Add TODOs to drop the reftableStorer shim
once go-git ships native reftable support.

Assisted-by: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Paulo Gomes <paulo@entire.io>
Entire-Checkpoint: 01KYM8EC609H2J2N4S0KYA95TA

Author: pjbgf

CLAUDE.md

@@ -460,6 +460,31 @@ Don't use `fmt.Print*` for operational messages (checkpoint saves, hook invocati
 
 We use github.com/go-git/go-git for most git operations, but with important exceptions:
 
+#### Opening Repositories - Always Use `gitrepo`
+
+**Never call `git.Open`, `git.PlainOpen`, or `git.PlainOpenWithOptions` directly.
+`cmd/entire/cli/gitrepo` is the single source of truth for opening a
+repository.** Use `gitrepo.OpenCurrent(ctx)` for the current worktree or
+`gitrepo.OpenPath(root)` for a specific worktree root. Both funnel through
+`openPathWithAlternates`, which is the only place that opens a `*git.Repository`.
+
+Routing every open through `gitrepo` guarantees two behaviours no ad-hoc
+`git.PlainOpen` call gets right:
+
+- **Object alternates** are rewritten to absolute paths so shared clones resolve
+  their objects (`PlainOpen` cannot follow relative/absolute alternates).
+- **Reftable repositories** are detected and opened through the git-CLI-backed
+  reference storer (`reftableStorer`). A direct `git.PlainOpen` on a reftable
+  repo fails outright with `unknown extension: refstorage`, because go-git's
+  filesystem storer cannot read the reftable backend. The reftable storer also
+  re-approves the `objectformat` (sha1/sha256) and `worktreeconfig` extensions
+  that go-git verifies at open time.
+
+If a code path opens a repo with a bare go-git call, it silently breaks on
+reftable and sha256 repositories. Reviewers should flag any new
+`git.PlainOpen*`/`git.Open` outside `gitrepo`. Key files: `gitrepo/repository.go`
+(open entry points) and `gitrepo/reftable.go` (`reftableStorer`).
+
 #### go-git v5 Bugs - Use CLI Instead
 
 **Do NOT use go-git v5 for `checkout` or `reset --hard` operations.**

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

@@ -9,6 +9,7 @@ import (
 	"strings"
 
 	"github.com/entireio/cli/cmd/entire/cli/gitremote"
+	"github.com/entireio/cli/cmd/entire/cli/gitrepo"
 	"github.com/entireio/cli/cmd/entire/cli/logging"
 	"github.com/entireio/cli/cmd/entire/cli/settings"
 
@@ -117,7 +118,7 @@ func FetchURL(ctx context.Context, opts ...FetchURLOptions) (string, error) {
 		// or an entire:// mirror of a different forge than the configured
 		// 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 {
+		if providerURL, ok := resolveProviderCheckpointURL(ctx, config, opt.WorktreeRoot); ok {
 			return providerURL, nil
 		}
 		logFallback(ctx, "fetch", originURL, "derive checkpoint remote URL", err)
@@ -223,7 +224,7 @@ func PushURL(ctx context.Context, pushRemoteName string) (string, bool, error) {
 		// The checkpoint token is an HTTPS credential for the provider host;
 		// it can't ride through the entire:// helper (which does its own
 		// auth). Route to the provider over HTTPS instead of the mirror.
-		if providerURL, ok := resolveProviderCheckpointURL(config, ""); ok {
+		if providerURL, ok := resolveProviderCheckpointURL(ctx, config, ""); ok {
 			return providerURL, true, nil
 		}
 	}
@@ -235,7 +236,7 @@ func PushURL(ctx context.Context, pushRemoteName string) (string, bool, error) {
 		// configured provider). Honor the configured checkpoint_remote by
 		// targeting the provider's canonical host over HTTPS rather than
 		// misrouting checkpoints to the origin remote.
-		if providerURL, ok := resolveProviderCheckpointURL(config, ""); ok {
+		if providerURL, ok := resolveProviderCheckpointURL(ctx, config, ""); ok {
 			return providerURL, true, nil
 		}
 		fallbackURL, fallbackErr := resolvePushFallbackURL(ctx, pushRemoteName, originURL)
@@ -340,8 +341,8 @@ func deriveCheckpointURLFromInfo(info *Info, config *settings.CheckpointRemoteCo
 //
 // Returns ok=false when no transport can be determined (unknown provider with no
 // usable signal), in which case the caller falls back to the origin remote.
-func resolveProviderCheckpointURL(config *settings.CheckpointRemoteConfig, dir string) (string, bool) {
-	repo, err := openRepoAt(dir)
+func resolveProviderCheckpointURL(ctx context.Context, config *settings.CheckpointRemoteConfig, dir string) (string, bool) {
+	repo, err := openRepoAt(ctx, dir)
 	if err != nil {
 		repo = nil // Fall back to env/provider-only signals.
 	}
@@ -384,12 +385,20 @@ func pickProviderTransport(repo *git.Repository, config *settings.CheckpointRemo
 }
 
 // openRepoAt opens the git repository at dir (current directory when dir is
-// empty), walking up to the enclosing .git directory.
-func openRepoAt(dir string) (*git.Repository, error) {
+// empty). It routes through gitrepo, the single reftable-aware opener, so a
+// reftable repository is opened via the git-CLI storer rather than rejected by
+// go-git's extension check. gitrepo.OpenCurrent resolves the worktree root from
+// the current directory (the walk-up equivalent of the previous DetectDotGit
+// open) when no explicit root is given.
+func openRepoAt(ctx context.Context, dir string) (*git.Repository, error) {
 	if dir == "" {
-		dir = "."
+		repo, err := gitrepo.OpenCurrent(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("open git repository: %w", err)
+		}
+		return repo, nil
 	}
-	repo, err := git.PlainOpenWithOptions(dir, &git.PlainOpenOptions{DetectDotGit: true})
+	repo, err := gitrepo.OpenPath(dir)
 	if err != nil {
 		return nil, fmt.Errorf("open git repository: %w", err)
 	}

cmd/entire/cli/gitrepo/reftable.go

@@ -44,7 +44,11 @@ func repoUsesReftable(dotGitPath, commonGitPath string) bool {
 		candidates = append(candidates, filepath.Join(commonGitPath, "reftable"))
 	}
 	for _, dir := range candidates {
-		if info, err := os.Stat(dir); err == nil && info.IsDir() {
+		// Lstat, not Stat: git creates reftable/ as a real directory, so a
+		// symlink in its place is not a genuine reftable stack. Lstat inspects
+		// the entry itself rather than following the link, so a symlink reports
+		// IsDir()==false and is correctly not treated as a reftable repository.
+		if info, err := os.Lstat(dir); err == nil && info.IsDir() {
 			return true
 		}
 	}
@@ -60,6 +64,12 @@ func repoUsesReftable(dotGitPath, commonGitPath string) bool {
 //
 // It also advertises reftable support via the ExtensionChecker interface so
 // go-git's extension verification does not reject the repository on open.
+//
+// TODO: remove this entire type (and its wiring in repository.go) once go-git
+// gains a built-in reftable reader/writer. It exists only because the vendored
+// go-git has no reftable backend, so ref operations must shell out to the git
+// CLI. When upstream supports reftable natively, the plain filesystem storer
+// handles these repositories and this shim can be deleted.
 type reftableStorer struct {
 	*gitfilesystem.Storage
 

cmd/entire/cli/gitrepo/repository.go

@@ -124,6 +124,11 @@ func openPathWithAlternates(repoRoot string) (*git.Repository, error) {
 	// authoritative in a reftable repository, and its extension check rejects
 	// extensions.refstorage=reftable outright. Route ref operations through the
 	// git CLI for such repositories while keeping object storage on go-git.
+	//
+	// TODO: drop the reftable branch below and the whole reftableStorer
+	// (reftable.go) once go-git ships a native reftable reader/writer. At that
+	// point a plain git.Open(storage, worktreeFS) will handle reftable
+	// repositories directly and this CLI-backed shim is dead weight.
 	worktreeFS := osfs.New(repoRoot, osfs.WithBoundOS())
 	if repoUsesReftable(dotGitPath, commonGitPath) {
 		repo, err := git.Open(newReftableStorer(storage, dotGitPath), worktreeFS)