feat(import): anchor imported checkpoints to default branch head

Adds resolveImportLinkCommitSHA, which resolves the commit imported
checkpoints stamp as commit_sha: origin's tip of the default branch
(the commit the server already knows) preferred over the local branch
tip, then HEAD, then empty when nothing resolves. Wires it into
`entire import <agent>` via agentimport.Options.LinkCommitSHA.

Entire-Checkpoint: 01KY34D8R1WQXZCK1TV9T2RXHX

Author: peyton-alt

cmd/entire/cli/import_cmd.go

@@ -69,6 +69,7 @@ fails even with --dry-run.`, imp.AgentType()),
 			res, err := agentimport.Run(ctx, repo, imp, agentimport.Options{
 				RepoRoot: repoRoot, OverridePath: pathFlag, SessionFilter: sessions,
 				Now: time.Now(), DryRun: dryRun,
+				LinkCommitSHA: resolveImportLinkCommitSHA(repo),
 			})
 			if err != nil {
 				return fmt.Errorf("import %s: %w", imp.Name(), err)

cmd/entire/cli/import_link.go

@@ -0,0 +1,28 @@
+package cli
+
+import (
+	"github.com/go-git/go-git/v6"
+	"github.com/go-git/go-git/v6/plumbing"
+
+	"github.com/entireio/cli/cmd/entire/cli/strategy"
+)
+
+// resolveImportLinkCommitSHA returns the commit SHA imported checkpoints are
+// anchored to: the default branch's head at import time. Preference order:
+// origin's tip of the default branch (the commit the server already knows),
+// then the local branch tip, then HEAD. Best-effort — returns "" when nothing
+// resolves (e.g. an empty repo); import proceeds without a link.
+func resolveImportLinkCommitSHA(repo *git.Repository) string {
+	if name := strategy.GetDefaultBranchName(repo); name != "" {
+		if ref, err := repo.Reference(plumbing.NewRemoteReferenceName("origin", name), true); err == nil {
+			return ref.Hash().String()
+		}
+		if ref, err := repo.Reference(plumbing.NewBranchReferenceName(name), true); err == nil {
+			return ref.Hash().String()
+		}
+	}
+	if head, err := repo.Head(); err == nil {
+		return head.Hash().String()
+	}
+	return ""
+}

cmd/entire/cli/import_link_test.go

@@ -0,0 +1,129 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/entireio/cli/cmd/entire/cli/testutil"
+	"github.com/go-git/go-git/v6"
+	"github.com/go-git/go-git/v6/plumbing"
+	"github.com/stretchr/testify/require"
+)
+
+// TestResolveImportLinkCommitSHA_LocalDefaultBranchNoOrigin proves that when
+// there is no origin remote, the resolver resolves via the local default
+// branch arm (testutil.InitRepo checks out master, so GetDefaultBranchName
+// returns "master" and the local-branch lookup succeeds). The true HEAD
+// fallback is covered by TestResolveImportLinkCommitSHA_HEADWhenNoDefaultBranch.
+func TestResolveImportLinkCommitSHA_LocalDefaultBranchNoOrigin(t *testing.T) {
+	t.Parallel()
+
+	repoDir := t.TempDir()
+	testutil.InitRepo(t, repoDir)
+	testutil.WriteFile(t, repoDir, "f.txt", "init")
+	testutil.GitAdd(t, repoDir, "f.txt")
+	testutil.GitCommit(t, repoDir, "init")
+
+	repo, err := git.PlainOpen(repoDir)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = repo.Close() })
+
+	head, err := repo.Head()
+	require.NoError(t, err)
+
+	got := resolveImportLinkCommitSHA(repo)
+	require.Equal(t, head.Hash().String(), got)
+}
+
+// TestResolveImportLinkCommitSHA_PrefersOriginDefaultBranch proves that when
+// origin's default branch tip differs from the local branch tip, the
+// resolver prefers origin's tip — that's the commit the server already
+// knows about.
+func TestResolveImportLinkCommitSHA_PrefersOriginDefaultBranch(t *testing.T) {
+	t.Parallel()
+
+	repoDir := t.TempDir()
+	testutil.InitRepo(t, repoDir)
+	testutil.WriteFile(t, repoDir, "f.txt", "one")
+	testutil.GitAdd(t, repoDir, "f.txt")
+	testutil.GitCommit(t, repoDir, "first")
+	firstSHA := testutil.GetHeadHash(t, repoDir)
+
+	testutil.WriteFile(t, repoDir, "f.txt", "two")
+	testutil.GitAdd(t, repoDir, "f.txt")
+	testutil.GitCommit(t, repoDir, "second")
+	secondSHA := testutil.GetHeadHash(t, repoDir)
+
+	repo, err := git.PlainOpen(repoDir)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = repo.Close() })
+
+	// Manually create refs/remotes/origin/main -> first commit, and
+	// refs/remotes/origin/HEAD as a symbolic ref pointing at it.
+	firstHash := plumbing.NewHash(firstSHA)
+	originMainRef := plumbing.NewHashReference(plumbing.NewRemoteReferenceName("origin", "main"), firstHash)
+	require.NoError(t, repo.Storer.SetReference(originMainRef))
+	originHeadRef := plumbing.NewSymbolicReference(
+		plumbing.NewRemoteReferenceName("origin", "HEAD"),
+		plumbing.NewRemoteReferenceName("origin", "main"),
+	)
+	require.NoError(t, repo.Storer.SetReference(originHeadRef))
+
+	// Also create a local main -> second commit, so origin/main and local
+	// main genuinely diverge. testutil.InitRepo defaults to `master`, so
+	// without this the resolver's local-branch arm is never exercised and
+	// the assertion below can't pin the origin-over-local preference order.
+	secondHash := plumbing.NewHash(secondSHA)
+	localMainRef := plumbing.NewHashReference(plumbing.NewBranchReferenceName("main"), secondHash)
+	require.NoError(t, repo.Storer.SetReference(localMainRef))
+
+	got := resolveImportLinkCommitSHA(repo)
+	require.Equal(t, firstSHA, got)
+}
+
+// TestResolveImportLinkCommitSHA_HEADWhenNoDefaultBranch proves the HEAD
+// fallback: when the default branch name cannot be resolved at all (no
+// remotes, and the checked-out branch is neither main nor master), the
+// resolver still returns HEAD's commit instead of "".
+func TestResolveImportLinkCommitSHA_HEADWhenNoDefaultBranch(t *testing.T) {
+	t.Parallel()
+
+	repoDir := t.TempDir()
+	testutil.InitRepo(t, repoDir)
+	testutil.WriteFile(t, repoDir, "f.txt", "init")
+	testutil.GitAdd(t, repoDir, "f.txt")
+	testutil.GitCommit(t, repoDir, "init")
+	sha := testutil.GetHeadHash(t, repoDir)
+
+	repo, err := git.PlainOpen(repoDir)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = repo.Close() })
+
+	// Rename the branch away from main/master so GetDefaultBranchName
+	// returns "" (no origin, and no local main/master to fall back to).
+	hash := plumbing.NewHash(sha)
+	trunkRef := plumbing.NewHashReference(plumbing.NewBranchReferenceName("trunk"), hash)
+	require.NoError(t, repo.Storer.SetReference(trunkRef))
+	require.NoError(t, repo.Storer.SetReference(
+		plumbing.NewSymbolicReference(plumbing.HEAD, plumbing.NewBranchReferenceName("trunk")),
+	))
+	require.NoError(t, repo.Storer.RemoveReference(plumbing.NewBranchReferenceName("master")))
+
+	got := resolveImportLinkCommitSHA(repo)
+	require.Equal(t, sha, got)
+}
+
+// TestResolveImportLinkCommitSHA_EmptyRepo proves the resolver returns "" and
+// does not panic on a repo with no commits.
+func TestResolveImportLinkCommitSHA_EmptyRepo(t *testing.T) {
+	t.Parallel()
+
+	repoDir := t.TempDir()
+	// git.PlainInit deliberately (not testutil.InitRepo): the repo must stay
+	// commit-free, so the helper's user/GPG config is irrelevant here.
+	repo, err := git.PlainInit(repoDir, false)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = repo.Close() })
+
+	got := resolveImportLinkCommitSHA(repo)
+	require.Empty(t, got)
+}

docs/architecture/sessions-and-checkpoints.md

@@ -305,6 +305,14 @@ When condensing multiple concurrent sessions:
 - `sessions` array in `CheckpointSummary` maps each session to its file paths
 - `files_touched` is merged from all sessions
 
+Checkpoints written by `entire import <agent>` additionally carry a `commit_sha`
+(omitempty) on both the session `Metadata` and the root `CheckpointSummary`,
+set to the default branch's head at import time — origin's tip is preferred
+(the commit the server already knows about), falling back to the local branch
+tip, then HEAD, then empty when nothing resolves. It is a best-effort anchor
+for UI display only, not an attribution signal, and pre-existing imported
+checkpoints are not backfilled with it.
+
 ### Checkpoint Policy
 
 Repo-wide checkpoint policy lives at `refs/entire/policies/checkpoint`. The ref