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

[peyton-alt]

https://entire.io/gh/entireio/cli/trails/916

What

entire import now stamps a commit_sha field into every checkpoint it writes — the default branch's head at import time (origin tip preferred → local branch → HEAD → empty). It lands in both the session metadata.json and the root CheckpointSummary (omitempty, preserve-on-rewrite), giving the UI a join key to anchor imported sessions to a commit so repo pages and stats populate immediately after an import.

Why

Imported history is commit-less: the normal commit↔checkpoint join is the Entire-Checkpoint trailer, which pre-existing commits don't have and never will (we don't rewrite history). The anchor is deliberately a link, not attribution — it says "imported at this point in time", not "this session built that commit". The sha lives inside the checkpoint metadata rather than in a ref name: checkpoint IDs are strictly 12-hex/ULID, and stuffing a 40-hex sha into refs/entire/checkpoints/ would break ID validation and force a growing shared-ref list for the common all-anchors-same-sha case.

How

• WriteOptions.CommitSHA → session Metadata + root CheckpointSummary (commit_sha, omitempty; root summary preserves a stamped value if a later write carries an empty one, mirroring the existing Imported/HasReview pattern)
• agentimport.Options.LinkCommitSHA threaded through Run → writeTurn; resolution stays out of the package
• resolveImportLinkCommitSHA in the cli package: origin's default-branch tip (the commit the server already knows) → local branch → HEAD → "" (best-effort; an unresolvable repo imports unlinked, never fails)
• No new refs, no new commits, no flags, no backfill of previously-imported checkpoints

Per-turn real-commit anchors

When a Claude Code transcript records the commits a turn made (toolUseResult.gitOperation.commit, kind committed), that turn's checkpoint anchors to the real commit instead of the head anchor: the recorded (short) sha is resolved, must be an ancestor of the default-branch tip (ancestry doubles as the reachability check — squash-merged/rebased-away commits fall through), and the last such commit of the turn wins. Everything else — older transcripts without the records, unresolvable or unreachable shas — falls back to the default-branch-head anchor above. The fallback's ancestor set is memoized lazily (one history walk per import run). Same commit_sha field either way; consumers see no schema difference.

Testing

• TDD unit tests throughout, including a mutation-verified origin-over-local preference test (diverged origin/main vs local main) and coverage of the HEAD-fallback and empty-repo arms
• Manual E2E on both backends: git-branch (v1) and git-refs — commit_sha present and correct in both, idempotent re-import leaves it untouched
• Prod smoke test (fresh /et repo, real transcript, full enable→import→push flow): refs with commit_sha round-trip through the server intact. Control experiment confirmed server ingestion is currently trailer-driven: a normal checkpoint ingested into /me/recap in ~2 min while the imported refs (on the server, commit_sha and all) were never indexed.

Notes for reviewers

• Bounded ancestor walk: the resolver's memoized ancestor set is capped by date (lookback + 60d slack) and by commit count (50k), walking newest-first (committer-time order) so early-stopping is sound. Addresses the inline review comment about unbounded time/memory on huge histories.
• Mixed CLI versions: Metadata/CheckpointSummary are not schema-versioned, so an older CLI that rewrites an existing checkpoint (OPF pre-push re-redaction, compact-marker update, multi-session summary rebuild) round-trips through structs without commit_sha and silently drops it. This is the same exposure every additive metadata field has had; the existing fence is the checkpoint policy ref (checkpoint_min_version). Practical blast radius for imported checkpoints is narrow — attribution never targets them and rewind/generate are blocked.

Out of scope / follow-ups

• entire.io ingestion + UI (the other half): index checkpoint refs whose metadata carries commit_sha (kind imported) and join on that field; render imported sessions as anchored to the commit, not attributed to it. The smoke test above is the repro.
• Historical-commit matching (v2) would only change the stamped value, not the schema.
• The test-only fsstore backend doesn't map the new field (consistent with it already skipping Imported).

🤖 Generated with Claude Code

---

Note

Low Risk
Additive metadata and best-effort import resolution; no changes to normal checkpoint writes or git history rewriting.

Overview
Adds an optional commit_sha field on checkpoint WriteOptions, session Metadata, and root CheckpointSummary so imported history can be tied to a git commit without an Entire-Checkpoint trailer.

entire import now resolves a link SHA at the CLI (resolveImportLinkCommitSHA: origin/<default> → local default branch → HEAD → "") and passes it through agentimport.Options.LinkCommitSHA into each imported turn. The anchor is display-only (“imported at this point”), not attribution; import still succeeds when resolution fails.

The persistent git store persists commit_sha on session metadata and the root summary, with omitempty and preserve-on-rewrite when a later write leaves it empty (same pattern as Imported / HasReview). Architecture docs describe the field; tests cover resolver preference, import stamping, and persistence.

^{Reviewed by Cursor Bugbot for commit d2df272. Configure here.}

[Copilot]

Pull request overview

Adds an optional commit_sha anchor to checkpoints produced by entire import, linking imported (commit-less) history to the default branch head at import time so downstream UI/services can immediately join imported sessions to a repo/commit context without rewriting git history.

Changes:

• Thread commit_sha through import (resolveImportLinkCommitSHA → agentimport.Options.LinkCommitSHA → checkpoint WriteOptions.CommitSHA).
• Persist commit_sha on both per-session metadata.json and root CheckpointSummary (with preserve-on-rewrite behavior added for the root summary).
• Add unit tests and update architecture docs describing the new import anchoring behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/architecture/sessions-and-checkpoints.md	Documents commit_sha behavior for imported checkpoints and resolution precedence.
cmd/entire/cli/import_link.go	Implements best-effort default-branch/HEAD commit SHA resolution for import anchoring.
cmd/entire/cli/import_link_test.go	Adds unit coverage for origin-vs-local preference, HEAD fallback, and empty repo behavior.
cmd/entire/cli/import_cmd.go	Wires resolved LinkCommitSHA into the import runner options.
cmd/entire/cli/checkpoint/persistent.go	Persists CommitSHA into session metadata + root summary; root summary preserves existing value on rewrite.
cmd/entire/cli/checkpoint/persistent_imported_test.go	Verifies persistence + omitempty behavior for commit_sha in imported checkpoints.
cmd/entire/cli/agentimport/agentimport.go	Threads LinkCommitSHA through to each imported checkpoint write.
cmd/entire/cli/agentimport/agentimport_test.go	Tests that LinkCommitSHA is stamped (and omitted when unset).
api/checkpoint/metadata.go	Adds CommitSHA fields to WriteOptions, session Metadata, and root CheckpointSummary.