What would you like to clarify about either question — the config-surface choice or the first-PR scope? Happy to add detail or reframe before you decide.

Right — and that's exactly the argument for the recommended option. The refs store is still a git backend in every meaningful sense: git refs, commit objects, tree surgery, CreateCommit/SignCommitBestEffort, the same push/OPF/cleanup machinery. The only thing that differs from today is the ref topology — N per-checkpoint refs (refs/entire/checkpoints/<shard>/<id>) instead of the single entire/checkpoints/v1 branch.

So the two options aren't "git vs non-git." Both are git. They differ in where the topology choice lives:

• Option A (recommended): the topology is a sub-mode inside the one registered "git" backend, picked by strategy_options.checkpoint_store. The git factory looks at the mode and returns the v1 store, the refs store, or a dual-writer. The registry still has a single "git" type.

• Option B: register a second backend type ("git-refs") in checkpoints.primary, sitting next to "git" in the registry.

Your instinct is the reason B is awkward. Because refs is git:

1. PR #1533's Open() has a guard that rejects any non-git primary (attach/resume/push/doctor/OPF all assume a git refs.Primary). A "git-refs" type would trip that guard or force you to weaken it — for something that's still git.
2. The v1 compatibility mirror is also git, and the PR's fanout rejects a git mirror (double-writes the ref). So even under option B you couldn't express the refs + v1 dual-write through the config; it'd still have to be internal.
3. The two would share ~all code (push, OPF, signing, tree building) — a separate registry "type" implies more separation than actually exists.

So the registry's backend types are best reserved for genuinely different storage substrates (a future S3/HTTP backend in checkpoints.mirrors), while "v1 branch vs per-checkpoint refs" — both git — is a rollout mode within the git backend, which is also precisely what the issue specifies (strategy_options.checkpoint_store).

Does that resolve it, or were you thinking the refs topology should be a distinct registered backend? And separately — still good with starting at "resolver + refsStore impl only," or want to reframe the scope question too?

What would you like to clarify? Happy to go deeper on any of it — e.g. the config/rollout surface (git-refs primary + git-branch mirror vs. keeping a strategy_options alias), how the v1 mirror gets pushed/OPF'd for downgrade safety, the push-discovery queue, ULID vs legacy IDs, or the PR scope. What's on your mind?

Got it — ULID refs shard on the last two characters: refs/entire/checkpoints/ZN/01KVBJCWYA4YW6J5M9GP655HZN. That keeps the IDs lexicographically sortable while still spreading evenly across 1,024 (32×32 Crockford-base32) shards.

So the resolver is asymmetric by ID type:

• Legacy 12-hex IDs → shard = first 2 chars (preserves today's a3/… layout the issue says to keep): refs/entire/checkpoints/a3/a3b2c4d5e6f7
• ULIDs → shard = last 2 chars: refs/entire/checkpoints/ZN/01K…ZN

ShardFor(id) dispatches on the ID's length/charset (12 lowercase hex vs 26 Crockford base32). The leaf is the full ID in both cases.

Anything else to pin down, or want me to fold this in and produce the written plan / first PR?

Saved. Here's the concrete, file-level plan for the agreed scope — a runnable git-refs primary behind config, in 3 reviewable PRs.

PR 1 — ID kind + ref resolver (pure, no behavior change)

cmd/entire/cli/checkpoint/id/id.go

• Add Kind(id) {Legacy, ULID} detection (12 lowercase hex vs 26 Crockford base32).
• Add ULID Validate; keep Generate() emitting legacy hex for now (switching generation touches the Entire-Checkpoint: trailer, Vogon regexes, and many tests — defer to a later PR; the refs store works fine on hex IDs).
• ShardFor(id) string — first-2 for legacy, last-2 for ULID. Pure string, no go-git import.

cmd/entire/cli/checkpoint/refs_naming.go (new)

• const CheckpointRefPrefix = "refs/entire/checkpoints/"
• CheckpointRefName(id) plumbing.ReferenceName → prefix + ShardFor(id) + / + id
• ParseCheckpointRef(name) (id.CheckpointID, bool) — for List/cleanup.
• Table-driven unit tests for both ID kinds, round-trips, the asymmetric shard.

PR 2 — gitRefsStore implementing PersistentStore

First, a shared refactor (the meat): extract the "build one checkpoint's subtree entries" step out of writeSession/writeStandardCheckpointEntries/spliceCheckpointSubtree so it returns the checkpoint-dir tree. The git-branch store splices it under <shard>/<id>/ into the v1 root (unchanged); the git-refs store uses it as the commit root tree.

cmd/entire/cli/checkpoint/refs_store.go (new) — gitRefsStore{repo, blobFetcher}:

• Write: type-switch the union; resolve the ref, read prior tip (orphan if none), build new checkpoint-root tree via the shared builder, CreateCommit parented on prior tip (auto-signed), SetReference, then enqueue for push (PR 3).
• Read / List (enumerate refs under prefix) / ReadSessionContent|Metadata|Prompts — reuse parse_tree helpers, rooted at the ref's tree instead of v1-at-shard-path.
• GetCheckpointAuthor (optional AuthorReader) — git-log on the ref.
• Stamp CheckpointVersion = "refs-1".

cmd/entire/cli/checkpoint/registry.go — add BackendTypeGitRefs = "git-refs" to the built-in map with gitBacked: true.

Tests — unit tests + a seam test (primary: git-refs, mirrors: [git-branch]) modeled on the existing fsstore seam test: all four WriteRequest variants land in refs, reads resolve from refs, v1 mirror also populated.

PR 3 — config-driven topology + push

Topology becomes config-aware. ResolveRefs(ctx) and PrePush currently hard-resolve to DefaultV1Refs(). Introduce a push-plan resolver that branches on the configured primary: branch-push (v1, today) vs ref-queue push (git-refs).

cmd/entire/cli/checkpoint/pushqueue.go (new) — flock-protected JSONL in the git common dir: Enqueue(refName), Drain() ([]refName, release). gitRefsStore.Write enqueues; PrePush drains, dedups, batch-pushes via the remote package (keeping today's fetch+rebase recovery), clears on success.

Per-ref OPF — generalize RewriteUnpushedV1WithOPF (currently one v1 tip) to run over each queued ref's unpushed commits before push. Required here: pushing refs with OPF enabled would otherwise leak unredacted content. On-demand ref fetch for reads of refs missing locally.

After PR 3, primary: git-refs (+ optional git-branch mirror) reads/writes/pushes end-to-end behind config.

Two things I'm explicitly flagging, not silently deciding:

• OPF-per-ref is the heaviest part of PR 3. If it balloons, the clean fallback is to split it into PR 3a (push, gated to refuse when OPF is enabled) + PR 3b (per-ref OPF) — but I'd aim to keep them together so refs push is never privacy-incomplete.
• The v1 mirror isn't pushed yet in this scope (mirror push+OPF = PR 4). So refs-v1-mirror gives you authoritative refs locally + pushed, but the v1 mirror stays local until PR 4 — i.e. full downgrade safety lands in PR 4, not here. Tell me if you want mirror-push pulled forward into this scope.

Want me to start on PR 1 now (it's self-contained and low-risk), or adjust the breakdown first?

PR 1 is done and committed. Summary of what landed:

PR 1 complete — ID kind + ref resolver

Branch feat/checkpoint-refs-resolver (off the phase2 base), one commit, pure naming layer — no behavior change (nothing constructs a ref store yet). mise run fmt && lint clean, affected package tests green.

id package (id.go)

• KindOf / CheckpointID.Kind() — classifies legacy 12-hex, 26-char Crockford-base32 ULID, or unknown.
• CheckpointID.ShardFor() — asymmetric shard per your spec: legacy hex → first 2 chars (keeps the v1 layout), ULID → last 2 chars. Unknown/short fall back to prefix.

checkpoint package (refs_naming.go)

• RefName(id) → refs/entire/checkpoints/<shard>/<id> (full ID as leaf).
• ParseRef(name) inverts it, rejecting mismatched-shard or extra-segment refs so a malformed ref never resolves to the wrong bucket (round-trip tested).

Renamed off the CheckpointRefName stutter to RefName/ParseRef per the linter. Generation still emits hex — the ULID generation switch stays deferred (it touches the Entire-Checkpoint trailer + Vogon regexes), but the resolver already recognizes both.

A couple of notes carried forward:

• OPF is fully descoped from this whole effort, per your call — recorded for PR 3.
• I haven't pushed or opened a PR (no remote action without your go-ahead).

Ready to move on to PR 2 (gitRefsStore implementing PersistentStore, starting with the shared "build one checkpoint's subtree" refactor extracted from writeSession), or do you want to review PR 1 first?

I've launched a fork to implement PR 2 (it inherits our full design context and the extracted internals). It's a sizable, delicate refactor of core write/read code, so it'll iterate against mise run test + test:integration before reporting back.

While it works, here's where things stand:

• PR 1 ✅ committed (a066c34310), rebased onto the current phase2 head so it sits on the git-branch/gitBacked taxonomy. ID-kind detection + RefName/ParseRef resolver, fmt/lint/tests green.
• PR 2 🔄 in progress on the fork: treeWriter extraction (shared per-checkpoint subtree builder) + GitStore refactored to use it byte-identically + new gitRefsStore registered as a git-backed git-refs primary + unit/seam tests. Two-commit split, suite-green gate.

One thing I corrected for the fork that's worth flagging to you: the seam test uses primary: git-refs + mirror: git-branch — which is allowed (that's exactly the parallel-rollout topology the reframe's one-of-each-type rule was designed to permit), not rejected. That validates the rollout shape end-to-end through checkpoint.Open.

I'll review the fork's diff when it lands — especially that the git-branch tree output is unchanged (the main risk) and that dupl doesn't fire (which would mean it under-shared). I won't push or open PRs without your go-ahead.

Relaunched the fork to finish PR 2 on the committed foundation. It will commit incrementally (Step A: route git-branch through the shared core with zero tree-output change → Step B: gitRefsStore + registry → Step C: tests), gated on mise run test + test:integration green.

Status recap:

• PR 1 ✅ a066c34310 — ID kind + ref resolver.
• PR 2 (1/3) ✅ acad3b43b9 — treeWriter extraction, behavior-neutral, suites green.
• PR 2 (2–3/3) 🔄 fork in progress — shared applyCheckpointWrite core + gitRefsStore + tests.

The main thing I'll scrutinize when it returns is the git-branch tree-output equivalence (the regression risk) — that the v1 subtree hashes are unchanged — plus that dupl stays quiet (proving the core is actually shared, not copied). I'll report back when it lands; I won't push or open a PR without your go-ahead.

PR 2 complete and independently verified ✅

Four commits on feat/checkpoint-refs-resolver (on top of the phase2 head):

I verified, not just trusted:

• Lint 0 issues — dupl stayed quiet, confirming the core is genuinely shared (git-branch and git-refs both route through applyCheckpointWrite), not copied.
• git-branch unchanged — checkpoint + strategy unit green, and integration 375 pass (the real condensation→v1 write path), strong evidence the v1 subtree output is identical.
• The two existing-test edits are signature adaptations (new checkpointVersion param; the flatten→build→splice helpers split), not weakened assertions.
• Refs write flow correct: missing ref → orphan; subsequent writes chain on the prior tip (per-checkpoint history); backfills return ErrCheckpointNotFound and resolve author like git-branch.

One legitimate deviation (matches our earlier deferral): end-to-end ULID storage isn't possible yet because id.Validate/UnmarshalJSON accept 12-hex only, so a ULID in metadata.json won't parse on read-back. The naming/sharding layer is ULID-ready; loosening validation rides with the deferred ULID-generation switch (which also touches the Entire-Checkpoint trailer regex). Tests cover legacy-hex storage + ULID naming.

Not done / not run: not pushed, no PR opened; e2e canary not run (it's part of mise run check — worth running before any push). OPF stays fully descoped per your call.

Next up is PR 3 — make ResolveRefs/PrePush topology-aware for a git-refs primary + the flock-JSONL push-discovery queue + batch push + on-demand ref fetch for reads. That's what makes git-refs actually sync to a remote.

Want me to start PR 3, run the e2e canary on what's landed, or pause here for you to review the diff?

While that maps the integration points, let me lay out the PR 3 decomposition I'm targeting (OPF descoped):

1. Push-discovery queue — flock-protected JSONL in the git common dir (checkpoint/pushqueue.go): Enqueue(ref) / Drain() / Remove(pushed). gitRefsStore.Write enqueues each ref after setRef. Durable: entries cleared only after a confirmed push, so a failed/interrupted push retries.
2. Config-aware PrePush — when the primary is git-refs, drain the queue and batch-push those refs (reusing the existing fetch+recovery path); otherwise today's v1 push. Unchanged at default config.
3. On-demand ref fetch for reads — wire a ref-fetcher into gitRefsStore (mirroring how BlobFetcher is wired in Open); a missing checkpoint ref triggers a targeted fetch then retry.

I'll wait for the machinery map, then implement (queue first — it's self-contained), gating each step on the suite. I'll report back when PR 3's first piece lands.

PR 3 complete — git-refs runs as primary end-to-end behind config ✅

Three commits, each gated on the suite:

Verified independently: lint 0, checkpoint + strategy + cli unit green, integration 375 pass (PrePush regression check).

The branch feat/checkpoint-refs-resolver now has 8 commits on the phase2 head:

With checkpoints.primary = git-refs (optionally + git-branch mirror), checkpoints now write to per-checkpoint refs, read from them (fetching missing ones), and push via the queue — the PR 1–3 scope you set.

Explicitly still out (as agreed): v1 mirror push for downgrade safety (later), and OPF (fully descoped). Not pushed; no PR opened.

It's yours to review now. When you're ready, I'll run the e2e canary (mise run test:e2e:canary) — it's no-cost/no-API and part of mise run check, so worth running before any push. Want me to kick that off now or wait until after your review?

Here's where things stand on your e2e-on-git-refs request:

The mechanism is built and committed (fc8c6aab3a):

• Production env override — settings.LoadCheckpointsConfig honors ENTIRE_CHECKPOINTS_PRIMARY (+ _MIRRORS), env-wins-over-file, matching the existing ENTIRE_* overrides.
• Backend-typed knob — E2E_CHECKPOINT_STORE=git-branch|git-refs; the e2e TestMain maps it to the override so every spawned binary + hook in the run uses it (agents don't strip ENTIRE_*, so it propagates).
• CI — repurposed the unconsumed e2e-checkpoints-v2 workflow (its v2-dual-write/v2-only inputs were never read by anything) into e2e-checkpoint-store with a checkpoint_store: git-branch|git-refs parameter. Documented in e2e/README.

Running it surfaced a real finding (which is the point of having the run): the e2e harness asserts on the v1 branch specifically — WaitForCheckpoint, the metadata readers (<v1-ref>:<shard>/<id>/… blob specs), and CheckpointIDs all assume the branch layout. Under git-refs the canary went 0/4 with "checkpoint ref entire/checkpoints/v1 did not advance" — not a store bug, the harness just isn't backend-aware yet.

So I've launched a fork to make the e2e/testutil helpers backend-aware via a single mode switch (state digest for advance-detection, backend-aware blob-spec for metadata reads, ref-listing for CheckpointIDs), with the gate being canary green in both modes (git-branch unchanged + git-refs). It'll commit incrementally and flag any failure that looks like a genuine store bug rather than a test assumption.

Net: the "additional CI parameter" you asked for exists now; the fork makes the suite actually pass under it. I'll report back with the both-modes canary results when it lands — and notably, that run doubles as real validation of the git-refs store end-to-end through agent flows.

Done. Here's the full picture.

Canary green in both modes ✅

• git-branch (default): vogon 59/59, roger 4/4 — no regression.
• git-refs: vogon 58/59 (+1 intentional skip), roger 4/4.

The git-refs run did real work: it validated the store end-to-end through agent flows and surfaced two genuine production read bugs, which I fixed.

What I built for your e2e-on-git-refs request (3 commits)

How to run it

• Locally: E2E_CHECKPOINT_STORE=git-refs mise run test:e2e:canary (no cost) or … mise run test:e2e --agent <agent> (real).
• CI: the E2E Checkpoint Store workflow (workflow_dispatch) takes agent + checkpoint_store: git-branch|git-refs.

Branch state — feat/checkpoint-refs-resolver, 11 commits, not pushed

PR1 (resolver) · PR2×4 (treeWriter extraction + git-refs store + tests) · PR3×3 (push queue + config-aware push + on-demand fetch) · e2e/CI×3 (above).

Still explicitly out, as agreed: OPF (descoped), and the v1 mirror push for full downgrade safety (later).

One judgment call I'd flag for your review: I renamed the metadata version constant refs-1 → refs-v1 to fit the existing branch-v1 format grammar. The issue #1471 text used refs-1 illustratively, but the code's ParseFormat requires the -v form — so refs-v1 is the consistent choice. Shout if you'd rather I keep refs-1 and teach the parser the dashless form instead.

It's all yours to review. Want me to do anything else before you run the real-agent e2e?

The skip is TestAlternates_RelativeObjectAlternate_CheckpointSync (e2e/tests/alternates_test.go:27), guarded by testutil.UsingGitRefs().

What that test does: it sets up a repo whose git objects live in a relative object alternate, lets two sides advance the entire/checkpoints/v1 branch, and asserts the branch syncs to origin — i.e. it specifically exercises the v1 branch's non-fast-forward push → fetch-and-rebase recovery path (the fetchAndRebaseRefCommon machinery), where one side's checkpoint commits get cherry-picked onto the other's tip.

Why it's skipped, not failing: that scenario has no analog under git-refs. The v1 model is one shared, ever-advancing branch, so concurrent writers create non-fast-forward divergence that must be rebased. The git-refs store instead force-pushes independent per-checkpoint refs (+refs/entire/checkpoints/<shard>/<id>:…) — each ref is its own history owned by one checkpoint, so there's no fast-forward to preserve and no rebase path to test. The skip reason says exactly this.

Coverage: it's not a gap — the git-refs push behavior it would otherwise cover (force-push semantics) is exercised by the batchForcePushRefs unit tests in strategy/refs_push_test.go, including TestBatchForcePushRefs_IsForcePush (non-fast-forward overwrite succeeds).

So it's a genuinely git-branch-specific test, correctly excluded under git-refs rather than weakened. The only thing I'd reconsider later: if/when the v1 mirror push lands (downgrade safety), the alternate scenario does re-apply to that mirror, so this test could come back for the dual-write topology specifically.

On-demand ref fetching wires through two layers (the per-checkpoint ref, then any missing blobs inside it). Here's the actual flow for a git-refs read of a checkpoint that isn't local yet.

The chain

1. Every read funnels through checkpointTree → resolveRefMaybeFetch (cmd/entire/cli/checkpoint/refs_store.go):

So a local miss triggers exactly one fetch of that one ref (refs/entire/checkpoints/<shard>/<id>), then retries. A failed fetch degrades to ErrCheckpointNotFound — never an error — so offline reads behave sanely.

2. The fetcher is injected, not hardcoded. The checkpoint package can't resolve a remote, so the CLI passes RefFetchFunc in via OpenOptions.RefFetcher → OpenEnv → gitRefsBackendFactory → store.SetRefFetcher. The concrete impl is FetchCheckpointRef (cmd/entire/cli/git_operations.go):

That git fetch pulls the checkpoint commit plus its reachable tree/blobs into the same-named local ref.

3. It's wired only at the read commands that already inject the blob fetcher: resume, explain, attribution, tokens (all OpenOptions{BlobFetcher: FetchBlobsByHash, RefFetcher: FetchCheckpointRef}). Strategy-side Opens (condensation, rewind) pass no fetcher — they only ever touch just-written local refs.

4. Blobs are a second, independent layer. After the ref resolves, reads go through a FetchingTree carrying BlobFetcher (FetchBlobsByHash), so any individual object still missing (partial/treeless clone) is fetched by hash on access. Ref-fetch gets you the checkpoint; blob-fetch backfills its contents.

Two trigger points

• Direct read by ID (resume/attribution/tokens, and explain once the ID is known): the store's resolveRefMaybeFetch above.
• Explain prefix→ID on a clone: matchCheckpointPrefixWithRemoteFallback (explain_export.go) — when local matching finds nothing and the primary is git-refs, if the prefix is a full checkpoint ID it calls FetchCheckpointRef then re-lists. (This is the fix from the last commit.)

The honest limitation

There's no remote enumeration. List() reads local refs only. So:

• Direct read by a known full ID → fetched on demand ✅ (and the Entire-Checkpoint: commit trailer is always the full ID, which is the normal way you arrive at a checkpoint).
• A partial prefix on a fresh clone → can't resolve, because we'd have to enumerate remote refs (an ls-remote refs/entire/checkpoints/**) which isn't wired. Under git-branch this "just worked" because fetching the one v1 branch brought all checkpoints at once; per-checkpoint refs trade that for not dragging the entire history on every read.

If partial-prefix-on-clone matters later, the clean fix is an ls-remote-backed enumeration in that same fallback — I scoped it out deliberately since the issue says storage-level listing stays local-only for now.

You're not missing anything — you're right, it's not a real scenario. Let me correct my over-cautious framing.

Where checkpoint IDs actually come from:

• The Entire-Checkpoint: commit trailer is always the full 12-hex ID. So every programmatic path — resume by branch, explain from a commit, attribution, tokens — resolves to a full ID. These all hit the direct-read fetch path, which works on a clone. ✅
• Partial prefixes are a local typing convenience (git short-hash style). You'd only ever have a partial prefix to type because you saw it in local output (entire checkpoint list, status, etc.) — and that output is generated from local refs, which means the checkpoint is already present, so local matching resolves it. ✅

The "gap" I described — partial prefix and nothing local — requires you to have learned a truncated ID that isn't derivable from anything on your machine (copied from another machine / a PR comment, then deliberately truncated). That's not a workflow we support, and honestly it wouldn't make sense to: a partial prefix is only meaningful relative to a known local set to disambiguate against.

So: no ls-remote enumeration needed, no real limitation. Full IDs (the canonical, trailer-derived path) fetch on demand; partial prefixes are inherently a local-set convenience. I'll drop that caveat from how I describe it — thanks for the push-back.

The one thing that genuinely remains is the deliberate read-policy choice from the issue — List() stays local-refs-only (no "fetch all checkpoints" on a clone), which is by design so reads don't drag full history. That's a property, not a gap.

Good check — and the honest answer is no, ULIDs do not work end-to-end yet, and that's the deliberate deferral we agreed on in PR 2. Only the ref-naming/sharding/resolver layer is ULID-ready; the identity/generation/serialization/trailer/e2e layers are all still 12-hex-only. Here's the precise audit:

✅ What handles ULIDs today

• id.KindOf / CheckpointID.Kind / id.ShardFor — classify + last-2 shard.
• checkpoint.RefName / ParseRef — round-trip ULID refs (unit-tested).
• e2e checkpointShard / checkpointRefName — len==26 → last-2.

❌ What still rejects/ignores ULIDs (the blockers)

1. Generate() (id.go:118) — emits 6 random bytes → 12-hex. ULIDs are never produced. So in practice every checkpoint is hex; a ULID only appears if injected.
2. Validate / NewCheckpointID / MustCheckpointID (id.go:128) — use checkpointIDRegex = [0-9a-f]{12} only → reject ULIDs.
3. CheckpointID.UnmarshalJSON (id.go:167) → calls Validate → a ULID in metadata.json fails to deserialize. This is the killer: even a ULID checkpoint that wrote fine can't be read back.
4. Trailer linkage — checkpointTrailerRegex is built from id.Pattern (12-hex), and ParseCheckpoint/ParseAllCheckpoints then call NewCheckpointID (Validate). So an Entire-Checkpoint: trailer with a ULID is neither matched nor parsed → commit↔checkpoint linkage breaks.
5. e2e — hexIDPattern + AssertCheckpointIDFormat (assertions.go:27,161) assert exactly 12-hex → would fail on ULIDs.

⚠️ One trap for whoever flips it on

id.Pattern (12-hex) is also reused for run IDs by investigate/state.go and provenance/env.go — those are different identifiers that just share the 12-hex shape. So you can't just widen id.Pattern globally; the checkpoint path needs its own combined hex|ulid pattern while run-id validation stays hex.

To actually turn ULIDs on end-to-end

• Accept both kinds in Validate/NewCheckpointID/UnmarshalJSON (gate on KindOf != KindUnknown).
• A checkpoint-specific trailer pattern matching hex-or-ULID (leave the run-id id.Pattern users alone — probably introduce id.CheckpointPattern).
• Switch Generate() to ULID (this is the rollout switch).
• e2e AssertCheckpointIDFormat/hexIDPattern accept both.
• Sweep for other {12}/length-12 assumptions on checkpoint IDs.

So: the refs store is ULID-ready by construction (sharding, ref names, resolver), but turning ULIDs on is its own focused change — exactly the "deferred ULID generation switch" we scoped out, and it's cleanly separable from the store work that's done. Want me to take that on as the next piece, or leave it parked?

It's a fair instinct, but I'd push back slightly: the refs store doesn't actually need to be rebuilt on top of ULIDs — they're orthogonal, and conflating them front-loads the riskiest change. Let me lay out why, then give a recommendation.

They're independent concerns

• ULID = checkpoint identity (generation, validation, the Entire-Checkpoint trailer). It's a global change — it affects the existing git-branch store and the trailers in users' commits too, not just refs.
• refs store = storage topology. It's ID-format-agnostic by construction: ShardFor already does first-2 for hex / last-2 for ULID, RefName/ParseRef round-trip both (unit-tested). The store works identically whichever ID format flows through.

And the issue mandates coexistence anyway — "existing checkpoint IDs cannot change" and "the resolver should support both legacy IDs and ULIDs for the time being." So even with ULIDs on, old repos keep hex IDs forever; the refs store must handle both regardless. There's no version of this where refs depends on ULID-only.

So "rebuild refs on ULID" buys ~nothing

If you reordered, the refs code barely changes — you'd just move Kind/ShardFor out of PR1 into the ULID PR (they're ID-format logic), and RefName/ParseRef + the store stay as-is. It's a re-label, not a rebuild. The only thing landing ULID first actually gives you is rollout cleanliness: new refs are ULID-sharded/time-sortable from day one, instead of a "hex refs now, ULID refs later" generational mix.

The real tradeoff is risk ordering

ULID is the wider blast radius of the two (trailer regex, validation, Vogon, every test that hardcodes {12}, and it changes the stable git-branch path). The refs store is opt-in/behind-config and self-contained. So "ULID first" front-loads the scarier change ahead of the isolated one.

My recommendation

Keep the refs branch as the independent, done, ID-agnostic unit it is — don't rebuild it. Spin ULID into its own standalone PR (id identity + Generate switch + trailer pattern + the Kind/ShardFor helpers + e2e/Vogon asserts), and land it first only because it's foundational identity worth baking on its own — not because refs needs it. The refs branch then rebases on top with essentially no code change.

That gets you the clean "ULIDs, then checkpoints-as-refs" story you're after, without treating the finished refs work as if it were built wrong.

One thing that decides it: do you want ULIDs to be the go-forward ID for all checkpoints (git-branch included), or only conceptually tied to the refs rollout? If it's global (which the issue implies), the standalone-ULID-PR-first ordering is clearly right. If you'd only ever want ULIDs once refs is the store, then it's fine to keep it parked as a later step. Which is it?

Right — and that's the key insight. Coupling them is a coupling, but the trick is that it's only one of the two layers that actually needs to couple. Splitting them resolves your worry:

Two separate layers, only one couples

Layer A — understanding both formats (universal, store-agnostic). Validation/NewCheckpointID/UnmarshalJSON/the trailer pattern/Kind/ShardFor all just need to accept and resolve both hex and ULID. This has no opinion about which store you run — it has to be universal anyway, because:

• a refs store holds both (migrated hex + native ULID), exactly as you said;
• migration and cross-reading need both readable regardless.

Layer B — emitting ULIDs (coupled to the refs store, by design). "New checkpoints get a ULID" only happens when the refs store is the primary. This is the one place the two axes touch — and it's justified coupling, not accidental: a ULID's only payoff (lexicographically sortable ref names, even last-2 sharding) is refs-specific. On the git-branch store a ULID buys nothing (the ID is just a subtree dir name under one branch). So "emit the ID format the storage actually benefits from" is cohesion, not entanglement.

Why that framing is the good outcome

• git-branch stays pristine — still hex, no trailer/Vogon/{12} churn on the stable path. The scary-blast-radius part of ULID shrinks to "the refs path emits them."
• It aligns with what already follows the store. checkpoint_version is already store-determined (branch-v1 vs refs-v1). ID format following the store is the same axis as version following the store — store → version → id-format, all consistent. You're not adding a new independent knob; you're saying "the refs format is ULID-shaped," which is what refs-v1 should mean.
• One clean seam. The only coupling point is the generator at condensation: if primary is git-refs → ULID, else hex. That's a single, honest branch, not generation logic smeared across the codebase.

So the bad coupling to avoid is the other one

The thing that would be harmful is coupling Layer A to the store — i.e., making the system only able to read ULIDs when refs is on. That creates the awkward 2×2 matrix and breaks migration/coexistence. Keep recognition universal; keep emission store-scoped.

What this means for sequencing

This actually argues against a big standalone "ULID everywhere" foundation PR. The real foundation is just Layer A (accept/resolve both — low-risk, no behavior change, "the CLI can now read ULIDs"). That can land first cleanly. Layer B (emit ULIDs for refs) then rides with the refs store, because that's where the coupling legitimately lives. The refs store I've built doesn't change — it already shards/names both formats; it just starts being fed ULIDs once Layer A + the generation seam exist.

So: don't reorganize the refs work onto a ULID base. Instead split the id work into Layer A (foundational, universal, first) and Layer B (refs-coupled generation), and your "new format for refs" intent falls out naturally without entangling the read path.

Does that match the model you had in mind — refs ⇒ ULID on emission, everyone ⇒ understands both?

All three done:

1. Decision recorded on #1471 — posted as a comment (link) capturing the two-layer split: understand both (universal) vs emit ULIDs (refs-coupled), the sharding rule, the coexistence story, and the sequencing.

2. Refs branch parked — feat/checkpoint-refs-resolver (11 commits) is untouched and intact; nothing of it is on the new branch.

3. Layer A underway — new branch feat/checkpoint-ulid-support off the phase2 base, and a fork is building the understanding layer:

   • id package: ULIDPattern/Kind/KindOf/ShardFor/CheckpointPattern, and widen Validate/NewCheckpointID/UnmarshalJSON to accept both formats. Generate() stays hex (emission is Layer B).
   • trailers: Entire-Checkpoint: matches ULIDs too.
   • e2e: ID-format assertion accepts both.
   • Leaves id.Pattern (run-id, hex) and the git-branch path untouched; gated on the full suite + canary staying green.

When Layer A lands, the refs branch rebases on top (no rebuild — it's already ID-agnostic) and gains the one new thing: emitting ULIDs in its write path when git-refs is primary.

I'll report back with the fork's results — commits, the verify tails, and especially its sweep findings (which {12}/format assumptions it widened vs. left as run-id/hex). I won't push or open PRs without your go-ahead.

Layer A (ULID understanding) is in ✅

Branch feat/checkpoint-ulid-support, 2 commits, verified independently:

Invariants I confirmed: Generate() still hex (emission is Layer B), id.Pattern untouched so run-IDs stay hex, Validate gates on KindUnknown, trailer uses the combined pattern. Gates: lint 0, full unit 6891, integration 375, e2e vet clean, canary unchanged (59/59 + 4/4) — exactly right, since nothing emits ULIDs yet so this is pure read-acceptance.

Sweep was thorough and correctly scoped — it widened only the three checkpoint-ID sites and deliberately left hex: id.Pattern (run IDs), investigate/provenance runIDPattern, trail.go idRegex (the trail feature's own ID type), and explain.go commit-SHA abbreviation. No surprises.

Where everything stands

• feat/checkpoint-ulid-support — Layer A, done, the new foundation.
• feat/checkpoint-refs-resolver — the refs stack (11 commits), parked, intact, ID-agnostic.
• Decision recorded on #1471.

Next, when you want it: rebase the refs branch onto Layer A (its PR1 Kind/ShardFor fixup away as redundant — now in Layer A), then add Layer B — the one new thing: the condensation ID generator emits a ULID when the git-refs store is primary, hex otherwise. That's the single coupling seam we agreed on.

Nothing pushed, no PRs opened. Want me to do the rebase + Layer B next, or pause here?

On it. Let me run /simplify on the branch, then I'll give you my take on the test shape.

The 4 review agents are running. While they work, let me give you my take on the test-shape question — it's a good one and the answer is nuanced.

Where both-format table tests pay off vs. where they're noise

The format only actually matters at three seams:

1. Recognition/validation (id: KindOf/Validate/UnmarshalJSON)
2. Sharding (ShardFor: first-2 vs last-2)
3. Ref naming (RefName/ParseRef, on the refs branch)

Everywhere else — condensation, the store's session indexing, resume, explain, status — the ID is an opaque string key / path segment. Parameterizing those over both formats would be churn that proves the same thing repeatedly: that a string round-trips as a string.

So my view:

• At the three seams: yes, table over {hex, ulid} is exactly right — and Layer A already does this for KindOf/ShardFor/Validate/trailer. That part of the shape is good; I wouldn't expand it.
• Across the broad suite: no — don't blanket-parameterize. It's redundant and makes tests harder to read for no added coverage.
• The one high-value addition is on the refs branch, not here: a single table-driven round-trip over {hex, ulid} that exercises RefName → write → ParseRef → read → ShardFor bucket end-to-end. That one parameterized test is where a real bug would hide (wrong shard bucket, ParseRef shard-mismatch, metadata round-trip with a ULID checkpoint_id). Today the refs store's write/read tests use hex only; adding a ULID row there is the meaningful coverage.

The honest gap: because Generate() stays hex in Layer A, nothing exercises a ULID through real generation → condensation → store → read yet. That end-to-end "both formats" proof can only exist once Layer B (emission) lands — and the natural home for it is (a) the refs-store round-trip table above, fed a ULID, and (b) one e2e canary run with ULID emission on under git-refs. So I'd deliberately defer the "end-to-end both formats" coverage to Layer B rather than fake it now.

Net: Layer A's test shape is good as-is — keep the seam-level both-format tables, don't widen the rest. Add the parameterized refs round-trip + an e2e-with-ULID pass when Layer B lands.

I'll fold any test-shape cleanups the simplify agents surface (e.g. ad-hoc tests that should be table-driven) into the apply phase, and report back with what got fixed.

/simplify done

Ran 4 parallel review agents (reuse / simplification / efficiency / altitude) over the Layer A diff. Committed as 83687eba4.

Applied (both the same theme — single source of truth, flagged by reuse + altitude):

• e2e/testutil/assertions.go — checkpointIDPattern now composed from id.CheckpointPattern instead of a hand-copied dual-format regex. (Confirmed safe: e2e is the same module and testutil already imports cli packages.)
• attach_test.go — dropped a hardcoded Entire-Checkpoint: [0-9a-f]{12} for the shared pattern. This one's a real catch: it would have broken at Layer B when ULIDs start being emitted. It's outside the strict diff, but it's exactly the bandaid the layer exists to remove, so worth fixing now.

Skipped, with reasons:

• resolveref.go looksLikeULID (reuse agent's "duplicate ULID validator") — it's a different domain: control-plane org/project name-vs-ULID disambiguation, case-insensitive. Not a checkpoint ID. Correctly separate; consolidating would couple unrelated concepts.
• Efficiency micro-opts (fold the KindOf/Kind regex passes in Validate/ShardFor, add ShardForKind variants) — negligible cost (one anchored match on a ≤26-char string, not a hot loop), and routing ShardFor through Kind() keeps format recognition centralized. Optimizing it would trade altitude for nothing measurable.
• Test dedup (TestValidateAcceptsBothFormats vs TestNewCheckpointID) — left as explicit; clearer than burying it.

Net: the layer was already clean; the only substantive findings were the two pattern-drift spots, now routed through the canonical CheckpointPattern. Verified: lint 0, id/trailers/attach green, e2e vet clean.

On the test-shape question

To restate now that simplify confirmed it: the seam-level both-format tables (KindOf/ShardFor/Validate/trailer) are the right shape and sufficient for Layer A — don't widen the broad suite (the ID is opaque almost everywhere). The one genuinely valuable both-format test is a parameterized refs round-trip (RefName → write → ParseRef → read → ShardFor bucket) over {hex, ulid}, plus an e2e-with-ULID pass — both of which belong with Layer B, since that's the first point a ULID can actually be generated and flow end-to-end. Faking it earlier would just test strings-as-strings.

Layer A branch is now 3 commits, green, not pushed. Want me to move on to the rebase + Layer B, or leave it here for review?

PR open: #1546 — independently mergeable ✅

Yes, Layer A merges independently — and I made sure of it. It was stacked on the (still-open) phase2 base for convenience, but it's logically independent (only id / trailers / two test asserts; nothing phase2-specific), so I rebased it onto main before opening the PR. The rebase was clean — phase2's attach_test.go change didn't touch my edited line.

The PR (main ← feat/checkpoint-ulid-support, 3 commits):

• Recognize ULIDs in the id package (Kind/ShardFor/CheckpointPattern, widened Validate/UnmarshalJSON)
• Trailer parser + e2e assert accept both formats
• /simplify pass (route format checks through the canonical CheckpointPattern)

The body spells out the deliberate boundaries: Generate() still emits hex (emission is the store-coupled layer, out of scope), id.Pattern stays hex for run-IDs, links the #1471 decision comment, and notes the canary is unchanged (nothing emits ULIDs yet). Verified on the main base: build, lint 0, cli/id/trailers unit green, e2e vet clean.

One thing to flag for later (recorded in memory): when the refs branch un-parks, it now depends on both #1533 (phase2) and #1546 (Layer A) — I'll rebase/cherry-pick it onto whatever lands first, and its old PR1 Kind/ShardFor will fixup away as redundant with Layer A.

Branch states:

• #1546 feat/checkpoint-ulid-support — Layer A, pushed, PR open against main.
• feat/checkpoint-refs-resolver — refs stack (12 commits), parked, still on the phase2 base, untouched.

Want me to leave it here for review, or start prepping the refs branch (rebase + Layer B emission) so it's ready once #1546 and #1533 settle?

The comment on #1546

It's a single inline review from Copilot (no human reviews yet): the new id_test.go test at line 123 didn't call t.Parallel(), unlike the repo convention for pure unit tests.

Valid nit — those tests are pure (no global state), so I addressed it:

• Added t.Parallel() to all 4 new tests and their subtests (TestKindOf, TestCheckpointID_ShardFor, TestValidateAcceptsBothFormats, REDACTED).
• Left the pre-existing non-parallel tests in that file alone (out of scope for this PR).
• Verified green + lint clean, pushed as 8ce947148, and replied to the review thread noting it's addressed.

The rest of the Copilot review was just an approving file-by-file summary — no other actionable items.

PR #1546 is updated and ready for human review. Want me to do anything else on it, or move on?

Done — both stale comments updated and pushed to #1546 (8a726209a):

• id.go — CheckpointID now documented as "either a legacy 12-char hex ID or a 26-char Crockford base32 ULID (see Kind / CheckpointPattern)."
• trailers.go — CheckpointTrailerKey format note now says "a checkpoint ID — either a legacy 12-hex ID … or a 26-char ULID (see checkpoint/id.CheckpointPattern)."

Doc-only; build + lint clean. PR #1546 is up to date. That clears all the review feedback so far (the t.Parallel() nit + these two comments).

Done. PR #1546 now validates ULIDs via oklog/ulid/v2 (a75a7a871).

What changed

• Added github.com/oklog/ulid/v2 v2.1.1 (no transitive deps — stdlib only).
• id.KindOf's ULID branch now calls isULID → ulid.ParseStrict(s) instead of the hand-rolled char-class regex. Validation and the future generator are now the same library, agreeing by construction.
• Stricter, in two good ways:
  • Rejects timestamp overflow (first char > 7) — the regex didn't.
  • Requires canonical form via a round-trip (v.String() == s), so lowercase and Crockford-normalized aliases (I/L→1, O→0) — which ParseStrict tolerates — are rejected. We only ever emit 26-char uppercase canonical, and this keeps ref names/shards deterministic.
• Kept ULIDPattern as the loose extraction shape for scanning the Entire-Checkpoint trailer (you still need a regex to find a candidate token in commit text); the captured token is then authoritatively validated through isULID. Removed the now-unused ulidRegex.
• Added an overflow case to the KindOf table; the existing "lowercase ULID is invalid" / "excluded letter" tests now pass for the right reason (canonical round-trip).

Verified: build, id/trailers/cli tests, e2e vet, and full lint including gomod all clean. Pushed to #1546.

This sets up Layer B nicely — the emission layer just calls ulid.Make() (monotonic entropy) and the values validate by definition. Anything else on the PR, or shall I leave it for review?

Fixed and pushed (ea67c0686).

AssertCheckpointIDFormat now calls checkpointid.Validate(checkpointID) instead of regex-matching CheckpointPattern. That's the right call: CheckpointPattern is deliberately the loose extraction shape (so the trailer scanner can find a candidate token), and it accepts ULID-shaped strings production rejects — exactly your overflow-8… example. The helper claims "valid checkpoint ID," so it should defer to the same validator production uses. Dropped the now-dead checkpointIDPattern var and regexp import.

Verified: go vet -tags e2e clean, lint clean, and the canary is 59/59 + 4/4 (real generated hex IDs pass Validate). It's the sole caller path — AssertValidCheckpointTrailer → AssertCheckpointIDFormat.

PR #1546 updated. This also tightens the layering nicely: CheckpointPattern = "find a candidate in text," Validate/KindOf (oklog-backed) = "is it actually valid" — and now both production and the e2e harness route validity through the latter.

Pushed (500e7e3fd).

Summary of the answer: ULIDPattern is still needed — but purely as the shape for extracting a checkpoint-ID token from commit-trailer text (via CheckpointPattern → checkpointTrailerRegex). oklog took over the validation role entirely. So it's not dead code, but its export was no longer justified (nothing outside the package used it, and an exported "shape" regex masquerading as a validator invites misuse). I unexported it to ulidPattern.

The exported surface now reads cleanly by intent:

• Pattern (exported) — legacy 12-hex, reused for run IDs.
• CheckpointPattern (exported) — loose extraction shape for scanning text; doc now explicitly says "validate the captured token via NewCheckpointID/Validate."
• ulidPattern (unexported) — internal compositional piece.
• Validation = oklog/ulid via KindOf/isULID.

Verified: build, id/trailers tests, e2e vet, lint all clean. PR #1546 updated.

Done — comment audit complete and acted on.

Verdict on the comments

After the audit, the comments are accurate and non-redundant — the oklog/unexport churn didn't leave any stale wording (no "regex validates ULID" leftovers; ulidPattern/isULID/CheckpointPattern docs all match reality). The one genuine relevance problem wasn't wording — it was that ShardFor + Kind() had no caller in this PR, forcing their comments to forward-reference the not-yet-present refs store.

Fix (per your call: move them out) — 5bd1049f1

• Removed CheckpointID.ShardFor and CheckpointID.Kind() (+ their tests) — sharding is a storage concern, and their only consumer is the refs store's RefName.
• Dropped the git-ref clause from the Kind type doc.
• #1546 is now purely the understanding layer: KindOf/Kind, isULID (oklog), Validate/NewCheckpointID/UnmarshalJSON, and the Pattern/CheckpointPattern matchers. No unused exports, no forward-referencing comments.

Verified: build, id/trailers/cli tests, e2e vet, lint all clean.

Nothing's lost — the parked refs branch already carries ShardFor/Kind() in its own PR1, so when it rebases onto Layer A it keeps them and just dedups the KindOf/Kind/pattern definitions against Layer A's (oklog-backed) versions. Recorded that in memory.

PR #1546 is now a tight, self-contained "recognize both ID formats" change. Want me to do anything else, or leave it for review?

Here's the state of the checkpoint-store stack (the "other" work besides ULID/#1546):

#1533 — Phase 2: pluggable stores (the foundation everything sits on)

• CI: all green (lint, test, canary, core, integration ×3, binary-size, licenses).
• mergeable: MERGEABLE, but BLOCKED / REVIEW_REQUIRED — i.e. CI isn't the blocker; it's that it's still a draft and has no human approval yet (reviews so far: Copilot, Cursor, and your own — all just "commented," bot feedback already addressed in the last commits).
• Last touched 2026-06-26.
• To move it: mark ready-for-review (un-draft) + get an approval/merge. Nothing code-wise is failing.

refs branch (feat/checkpoint-refs-resolver) — the actual ref store

• Not a PR, not even pushed — it's purely local (12 commits, parked on the phase2 base).
• Blocked on #1533 (its base) and now #1546 (Layer A) landing, after which it rebases onto main and becomes its own PR(s). It still also has the deferred bits: ULID emission (Layer B), v1-mirror push for downgrade safety, and OPF (all explicitly out so far).

#1546 — ULID understanding

• Open against main, green; leaving as-is per your call.

So the critical path is #1533: it gates the refs branch, it's green, and it's only held by draft-status + needing a review. Once #1533 (and #1546) merge, the refs work can surface.

Want me to:

• (a) scan #1533 for any unaddressed inline review threads (so it's clean to un-draft), or
• (b) push the refs branch up as a stacked draft PR on #1533 so it's visible/reviewable in parallel, or
• (c) just leave both as-is?

Recorded. Bottom line: #1533 needs no review work — both threads resolved+fixed, CI green, and it's even picked up two extra review/hardening commits since I branched. It's ready to come out of draft whenever you want a human approval on it; that (plus un-drafting) is the only thing standing between it and merge, and it's what unblocks the refs branch.

Want me to mark #1533 ready-for-review, or leave that to you?

Both foundations merged — and I've started the next step

#1546 (ULID understanding) and #1533 (phase2 pluggable stores) are both merged into main (today). That unblocks the refs work.

Best next step (and what I did): not a 12-commit rebase of the parked branch — that overlaps ~13 files with what merged and main drifted 179 files, so it'd be conflict-heavy and produce an unreviewable mega-PR. Instead, reconstruct as the reviewable PR stack on main, lifting net-new content from the parked branch (kept as archive).

PR A is built and green (branch feat/checkpoint-ref-resolver, 1 commit, not pushed):

• Re-added ShardFor + CheckpointID.Kind() to id.go — the bits #1546 deferred, now landing with their consumer, written against main's oklog API.
• refs_naming.go — RefName (refs/entire/checkpoints/<shard>/<id>) + ParseRef.
• Build, id/checkpoint tests, and lint all clean.

Remaining stack (each lifted onto main after A merges):

• B — treeWriter extraction + gitRefsStore + registry.
• C — push queue + config-aware pre-push + on-demand fetch + refs-v1 read policy.
• D — e2e backend matrix + E2E_CHECKPOINT_STORE + settings env override + CI workflow.

I held PR A local (no push) since you asked for the next step, not explicitly to open it. Want me to push PR A and open it against main, then proceed down to B? Or adjust the stack breakdown first?

Quick correction first, because it changes the answer: only PR A is actually reconstructed on main. B/C/D aren't separate branches yet — that content lives in the parked 12-commit branch on the old base (d0e4056687), which conflicts with merged main. So whichever way we go, B/C/D still need reconstructing onto main; it's not "just open them." That means the grouping is a free choice right now — I haven't sunk effort into 4 separate branches.

On the real question — is separation worth it beyond dev-cycle? Mostly no, with one important exception:

The treeWriter refactor genuinely benefits from its own PR. It refactors the battle-tested git-branch write path (persistent.go) with a "v1 tree output is byte-identical" guarantee, verified by the existing suite + integration tests. Isolating it lets a reviewer confirm "this changed nothing" without new-feature noise mixed in. That's a real review-quality win, not just dev-cycle.

The rest is a cohesive feature and reads better together. You can't actually judge the git-refs store's design without seeing how it pushes (queue) and reads-on-clone (fetch) — splitting store/push/fetch into separate PRs forces reviewers to context-switch to evaluate one decision, and adds stacked-rebase churn for pieces that don't ship value independently anyway. So A+store+push+fetch+e2e is best as one unit.

My recommendation — 2 PRs:

1. Refactor: treeWriter extraction (no behavior change) — small, independently verifiable, can merge on its own.
2. Feature: ref resolver (A) + gitRefsStore + registry + push queue + config-aware pre-push + on-demand fetch + e2e/CI matrix — the whole git-refs backend, reviewed end-to-end.

Avoid the 4-PR stack (over-fragmented for tightly-coupled code, most churn). And a single combined PR is also fine if you'd rather not stack at all — the refactor just lives as the first commits and relies on commit hygiene for the "no-change" claim.

Which do you want — 2 PRs (refactor + feature), or 1 combined PR? Either way I'll reconstruct onto current main (PR A's commit folds in as-is).

Status — the 2-PR approach is underway:

✅ PR 1 — #1556 "Extract checkpoint write helpers into treeWriter (no behavior change)"

Open against main. The behavior-preserving refactor that isolates the shared subtree-building core. Fully verified: lint 0, checkpoint + strategy unit green, integration 378 pass (v1 write path byte-identical). I trimmed the forward-declared refs-v1 const out of it so it's a pure refactor — that const lands in PR 2 with its consumer.

🔄 PR 2 — feat/checkpoint-git-refs (stacked on PR 1)

A fork is reconstructing the whole git-refs backend onto PR 1's branch: ref resolver + gitRefsStore + registry + push queue + config-aware pre-push + on-demand fetch + refs-v1 read policy + e2e/CI matrix. It's lifting from the parked branch and resolving conflicts against merged main (oklog id wins, Validate-based e2e assert wins, settings env-override composes with os.Root, refs-v1 not refs-1). Gated on the both-mode canary (git-branch unchanged + git-refs green). It'll commit incrementally and stop without pushing so I can review the branch first.

When the fork returns I'll verify it independently (especially that PR 1's "no v1 change" still holds underneath, and dupl stays quiet), then bring it to you before pushing/opening PR 2.

Two things worth noting:

• #1556 can be reviewed/merged now — it's independent and self-contained; PR 2 rebases trivially once it lands.
• I left the parked 12-commit branch and the interim feat/checkpoint-ref-resolver branch in place as archives until PR 2 is confirmed good.

I'll report back with PR 2's diff + both-mode canary results.

Both PRs are open and independently verified. 🎉

The 2-PR stack is up

PR 1 — #1556 · treeWriter refactor (no behavior change) → base main The behavior-preserving extraction of the shared subtree-builder. Verified: lint 0, unit green, integration 378, v1 tree byte-identical.

PR 2 — #1566 · per-checkpoint git-ref store → stacked on #1556 The whole git-refs backend: ref resolver, gitRefsStore + registry, push-discovery queue, config-aware pre-push, on-demand fetch, refs-v1 policy, e2e/CI matrix. 7 clean commits.

What I verified myself (not just the fork's word):

• Correctly stacked on #1556; clean 7-commit history.
• lint 0 — dupl quiet, confirming the core is genuinely shared from PR 1 (not copied).
• canary git-branch 59/59 + 4/4 (no regression) and git-refs 58/59 + 1 expected skip + 4/4 (works end-to-end through agent flows).
• Key conflict resolutions sound: refs-v1 (not the stale refs-1), main's oklog id + Validate-based e2e assert preserved, env override composes with main's os.Root reads, refsV1Format added to the read and write policy.

Suggested merge order

1. Review/merge #1556 first (small, self-contained, safe — it's a pure refactor).
2. #1566's base auto-retargets to main; review/merge it. It's opt-in (off by default), so it lands dark until someone sets checkpoints.primary: git-refs.

Deferred follow-ups (called out in #1566's description): ULID emission (the generation switch), v1-mirror push for full downgrade safety, and OPF on the git-refs push path.

Want me to drop the now-superseded local archive branches (feat/checkpoint-refs-resolver, the parked feat/checkpoint-refs-resolver stack), or leave them until the PRs merge?

You're right — and it's a GitHub limitation, not something about our setup.

workflow_dispatch workflows are only runnable once the file is on the default branch (main). The "Run workflow" button doesn't appear (and gh workflow run / the API 422s) for a dispatch workflow that exists only on a feature branch. So e2e-checkpoint-store.yml, living only on the PR branch, can't be dispatched until #1566 merges. (Once it's on main, you can dispatch it and pick ref: feat/checkpoint-git-refs to run the PR's code — but that's post-merge of the workflow.)

So to validate git-refs e2e before merging, the options are:

1. Local run (works today, what I've been using):

   • E2E_CHECKPOINT_STORE=git-refs mise run test:e2e:canary — no cost (vogon/roger-roger), already green (58/59 + 4/4).
   • E2E_CHECKPOINT_STORE=git-refs mise run test:e2e --agent claude-code — real agents (needs API keys, costs tokens).

2. Add a free git-refs canary to PR CI ← my recommendation. The repo's test:ci already runs the canary on every PR, but only on git-branch. I can add a small pull_request-triggered job (or extend CI) that runs the vogon canary with E2E_CHECKPOINT_STORE=git-refs — automatic signal on the PR, no manual dispatch, no default-branch limitation (pull_request triggers run from the branch directly), and no cost (vogon makes no API calls). That gives you exactly the "is git-refs green in CI" signal pre-merge.

3. Land the workflow file on main first (tiny precursor PR) — then dispatch it with ref: feat/checkpoint-git-refs for a real-agent run. More ceremony; only worth it if you specifically want the full multi-agent matrix before merge.

The workflow_dispatch workflow is still valuable post-merge for on-demand multi-agent runs against either backend — it's just not the pre-merge gate.

Want me to add the no-cost git-refs canary to PR CI (option 2)? It's a small change to #1566 and gives you automated pre-merge confidence on git-refs.

Both done.

Your question: yes, the standalone workflow PR is safe to merge

workflow_dispatch-only → merging triggers nothing automatically, can't affect CI or other workflows. It just becomes a manual "Run workflow" button (and, importantly, dispatchable — which it isn't from a feature branch).

1. Free git-refs canary in PR CI → on #1566

ci.yml's test-canary job is now a matrix over [git-branch, git-refs] (E2E_CHECKPOINT_STORE, fail-fast: false). The Vogon canary makes no API calls, so every PR now exercises git-refs at no cost alongside git-branch. It activates exactly when the backend exists — the matrix change ships in #1566, so #1566's own CI runs the git-refs leg against its code (green, matches local), and all future PRs are guarded after it merges. Pushed.

2. Standalone workflow PR → #1567

Just e2e-checkpoint-store.yml, base main, and removed from #1566 so it's not duplicated. Once it merges, you can dispatch the multi-agent e2e against either backend — and even before #1566 merges, dispatch it with ref: feat/checkpoint-git-refs to run the PR's git-refs code against real agents.

The three PRs now

• #1556 — treeWriter refactor (base main).
• #1566 — git-refs backend (stacked on #1556) — now self-validates git-refs in CI via the canary matrix.
• #1567 — dispatch workflow (base main, independent, safe to merge anytime).

Suggested order: #1567 anytime (independent) → #1556 → #1566. After #1556 merges, #1566 retargets to main automatically.

Want me to verify #1566's CI goes green once it runs (I can watch the checks), or anything else?

Confirmed — no missing slash. basePath carries the trailing / by convention, so the format string is correct.

The caller (persistent.go:1657) passes:

So fmt.Sprintf("%s%d/%s", basePath, latestIndex, paths.MetadataFileName) expands to:

The slash between basePath and the index comes from basePath's trailing /; the explicit / in the format is the one between the index and the filename.

The convention is consistent and self-corroborating throughout the file:

• rootMetadataPath := basePath + paths.MetadataFileName (line 269) — no slash added, because basePath has it.
• flattenExisting does strings.TrimSuffix(basePath, "/") (line 151) — only meaningful if basePath ends with /.
• writeTaskCheckpointEntries does basePath + "tasks/" (line 435) — same.
• sessionPath := fmt.Sprintf("%s%d/", basePath, sessionIndex) (line 366) — same pattern.

And for the git-refs store (#1566) the root anchoring is basePath = "", which yields "0/metadata.json" — also correct.

Worth adding: this isn't new logic — it's the pre-existing git-branch path-building, unchanged by the refactor (the refactor only moved the receiver and threaded basePath). So it's been correct in production; the "no behavior change" property holds here too. Good thing to double-check, though — that %s%d with no literal separator is exactly the kind of thing that looks wrong at a glance.

Here's the lay of the land. The package has no existing tree-path-join helper — it's all raw string-concat on the trailing-slash basePath convention, and that pattern appears ~19 times in persistent.go alone (plus similar in ephemeral.go). filepath.Join is used only for real filesystem paths (configloader, normalize helpers), never for tree keys.

So: yes, path.Join (stdlib path, forward-slash — not filepath.Join) is exactly "joins paths and does the right thing," and a small helper like checkpointSubtreePath(basePath, strconv.Itoa(idx), paths.MetadataFileName) would kill the trailing-slash invariant and read clearly. path.Join("a3/b2c4.../", "0", "metadata.json") → "a3/b2c4.../0/metadata.json", and path.Join("", "0", …) → "0/metadata.json" — correct for both git-branch and git-refs anchoring.

But I'd not do it in #1556 or #1566, for two reasons:

1. #1556's whole value is "no behavior change, byte-identical v1 tree." Rewriting ~19 path-construction sites — even to an equivalent — bloats the diff and undercuts the clean "pure extraction" verification. #1566 is the feature; same argument.
2. It's not refactor-specific — it's a longstanding, consistent, well-tested convention across the git-branch write path. The footgun is mild (it looked wrong but is correct everywhere).

Recommendation: a small dedicated follow-up PR that (a) adds the path.Join-based helper, (b) converts all the sites consistently (persistent.go + ephemeral.go), (c) is gated on the byte-identical-tree + read tests (which would catch any key mismatch — e.g. if path.Join's cleaning ever diverged from FlattenTree's keying). It's low-risk precisely because those tests prove tree-identity, and it has one clear purpose.

So I'd ship the stack as-is and queue this as a "use path.Join for checkpoint subtree paths" cleanup afterward.

Want me to:

• (a) queue it as that standalone follow-up PR (after the stack), or
• (b) fold it into #1556 now (it is the path-handling refactor — defensible, but expands its scope and re-opens the "no-change" verification), or
• (c) leave the convention as-is?

My vote is (a).

I've launched a fork to do the path.Join cleanup, based on the top of the stack (feat/checkpoint-git-refs) so it's linear. It'll:

• Add a checkpointSubtreePath(basePath, segs...) helper over stdlib path.Join (not filepath — git tree paths are always /).
• Convert the full-path sites (incl. the exact %s%d/%s line the reviewer flagged) and carefully cascade the directory-prefix sites (sessionPath/taskPath) into their consumers so nothing silently loses a separator.
• Gate on the byte-identical-tree suite: full unit (the tree-structure assertions), integration 378, and both-mode canary — any tree-key drift fails those.

It'll stop without pushing so I can review this delicate (tree-key-preserving) change before it becomes reviewer-facing.

When it returns I'll verify independently (especially that no committed-tree assertion changed and both canary modes stay green), then push and open the PR and give you the link. I'll also note the stacking for the reviewer: it targets feat/checkpoint-git-refs, so its diff is just the cleanup, but it lands after #1556/#1566 — when #1556 merges, the whole stack rebases down to main.

Good catch on both. Here's the honest answer to the force-push question first.

Why it currently force-pushes

batchForcePushRefs uses +ref:ref (force) for three reasons, in decreasing order of legitimacy:

1. I copied the existing convention. The pre-existing tryPushRefCommon already force-pushes non-branch refs (push_common.go:279, "+" + ref + ":" + ref). When I added the per-checkpoint push I mirrored that.
2. A "single-writer, append-only" mental model. Each checkpoint ref is its own independent commit chain (orphan → parented on each rewrite: condensation, then transcript/summary/attribution backfills). On one machine every update fast-forwards the prior tip, so I reasoned "non-fast-forward can't happen" and force let me skip the fetch+rebase recovery the v1 branch needs.
3. Batch simplicity — +ref:ref always succeeds in one git push, so a backfill of many refs needs no per-ref divergence handling.

Why your concern is right (and force is the wrong default)

"Can't happen" is doing too much work, and with no server-side ref protection the failure mode is bad:

• Divergence can occur — two clones/machines writing the same checkpoint, a re-run/re-condensation producing a different SHA (different timestamp/author/signature even for "same" content), or an aborted push. Force-push then silently overwrites the remote — last writer wins, data loss, no signal.
• Force also throws away the free safety net: a non-force push is fast-forward-only — it succeeds for the normal advancing-the-ref case and is rejected exactly on genuine divergence, which is precisely when you want to stop and reconcile rather than clobber.
• And force isn't even needed for the happy path: normal advances are fast-forwards, and a brand-new checkpoint ref has nothing on the remote to conflict with. Force only "helps" in the one case that's actually dangerous.

So: the default should be a non-force (fast-forward-only) push. Reserve --force-with-lease (compare-and-swap against the last-seen remote value, so a concurrent writer isn't silently lost) for the genuinely-need-to-rewrite cases — which today is only the OPF rewrite, and that's deferred. Net: nothing in the current scope needs force.

My recommendation for #1566: switch batchForcePushRefs to a plain ref:ref push; on rejection (non-fast-forward), log and leave the ref queued rather than overwrite (full reconciliation is the partial-failure work we already deferred). When OPF/rewrite lands later, that path uses --force-with-lease.

On RefName + empty cid

Agreed — RefName(EmptyCheckpointID) yields refs/entire/checkpoints//, a malformed ref. The store paths feed it validated IDs, and the explain_export.go branch I added gates via id.NewCheckpointID(prefix) first — but you're right that RefName itself is a footgun for future callers. I'd make it return (plumbing.ReferenceName, error) (or add a validating variant) so an empty/invalid cid can't silently produce a bad ref, and have callers handle it.

Both are real, in-scope fixes for #1566. Want me to:

1. switch the push to non-force (fast-forward-only) + log-and-requeue on rejection, and
2. make RefName validate (return error) and fix the call sites —

…as a commit on #1566? Or would you rather discuss the rejection-handling behavior (skip-and-requeue vs fetch-and-reconcile now) before I touch it?

Both fixes done and pushed to #1566, plus the stack tidied up.

Fix 1 — fast-forward-only push (ab394204c)

batchForcePushRefs → batchPushRefs, refspec +ref:ref → ref:ref (no force). Per your point about no server-side ref protection: per-checkpoint refs normally advance by fast-forward (so the common case still pushes fine), but a genuine non-fast-forward divergence is now rejected and left queued, not silently overwritten. The pre-push logs it; reconciliation is the deferred bit, and a future rewrite path (OPF) can use --force-with-lease.

• Tests flipped: TestBatchPushRefs_AllowsFastForward (descendant update pushes) + TestBatchPushRefs_RejectsNonFastForward (orphan/divergent update errors and the remote ref is unchanged — the safety property).

Fix 2 — RefName validates (bc296fd7d)

RefName(cid) now returns (plumbing.ReferenceName, error), erroring on an empty or unrecognized ID instead of silently producing refs/entire/checkpoints//. The store call sites (refBase/setRef/resolveRefMaybeFetch/GetCheckpointAuthor) and the explain-on-clone fetch propagate it; tests use a mustRefName helper and a new RefName_RejectsInvalidID case.

Verified: lint 0, checkpoint + strategy + cli unit green, both-mode canary (git-branch 59/59, git-refs 58/59 + 1 skip). And I restacked #1576 (path-join) on the updated #1566 so the stack stays consistent.

Where everything stands

• Merged to main: #1556 (treeWriter), #1567 (dispatch workflow).
• #1566 — git-refs backend, rebased onto main, base retargeted, now carries the canary matrix + both review fixes. Dispatchable e2e: run E2E Checkpoint Store with ref: feat/checkpoint-git-refs, checkpoint_store: git-refs.
• #1576 — path.Join cleanup, stacked on #1566 (your reviewer's link).

Both of your callouts were spot-on — the force-push default especially was a real latent footgun. Want me to kick off a git-refs e2e dispatch run now that the workflow's on main, or leave that to you?

Verified the machinery — and it makes your idea better than I'd have guessed. Two things I found:

1. The recovery already exists and already handles non-branch refs. fetchAndRebaseRefCommon (push_common.go:386) fetches a non-branch ref into a temp ref and cherryPickOntos the local commits onto the remote tip. So "fetch remote, put local on top" is reuse, not new code.
2. cherryPickOnto is delta-based, not whole-tree (it diffs each commit against its parent). So "local on top" is a real per-file merge, not a clobber: a remote write that touched different files (e.g. added a session dir) and a local write that touched others merge cleanly; only a genuine overlap (both rewrote the same file — realistically the root metadata.json/CheckpointSummary) would conflict. And divergence itself is rare (same checkpoint ID re-written on two machines).

So your instinct is right, and the recovery dominates my current reject-and-queue:

• common divergence (non-overlapping) → auto-heals, queue drains, no manual step;
• true content conflict → cherry-pick fails → it degrades to exactly today's "left queued" state. So we lose nothing and gain auto-recovery.

The one wiring detail: the shared non-branch push (tryPushRefCommon) currently force-pushes (+ref:ref) on the first attempt, so the recovery never triggers for non-branch refs. To adopt your approach I'd:

• make the non-branch push non-force (ref:ref) so a divergence is rejected, then
• let the existing doPushRef → fetchAndRebaseRefCommon recovery fetch+replay+retry.

The only tradeoff vs my batch path: this runs per-ref (N round-trips), whereas batch is one. For normal pre-push that's ~1 ref so it's a non-issue; batch only matters for bulk migration (which is deferred). Two ways to land it:

• (a) Simplest: drain the queue and push each ref via the existing pushRefIfNeeded (gets non-force + recovery for free); drop my custom batchPushRefs.
• (b) Keep batch fast-path: batch-push non-force; on rejection, fall back to per-ref pushRefIfNeeded recovery for the rejected refs. Preserves migration efficiency, a bit more code.

My recommendation: (a) now — it's the genuine "easy way out," reuses the proven recovery, and auto-heals; revisit batch when migration actually lands. Want me to implement (a) on #1566 (replacing the reject-and-queue behavior)?

You're right, and I muddied two different code paths — let me set it straight.

Yes — Fix 1 already made the git-refs push non-force. batchPushRefs (the path prePushCheckpointRefs uses for a git-refs primary) sends plain ref:ref. That part is done and correct.

The tryPushRefCommon force I pointed at is a separate, pre-existing helper — it's the per-ref pusher used by pushRefIfNeeded/doPushRef, which is the v1-branch-era path (and the one that carries the fetch+rebase recovery). The git-refs store doesn't use it today; it uses my batchPushRefs. So its +ref:ref is unrelated to what we already fixed. Sorry for the confusion.

So the accurate current state of the git-refs path:

• push: non-force (ref:ref) ✅
• on divergence: reject → log → leave queued (no auto-recovery)

Your proposal only adds the missing piece: auto-recovery (fetch remote, replay local on top, retry). And I was wrong that it requires flipping tryPushRefCommon — that was the "reuse the whole pushRefIfNeeded path" route. The cleaner route keeps everything we have:

• Keep batchPushRefs non-force as-is.
• On rejection, call the existing fetchAndRebaseRefCommon rebuild (it's already non-branch-aware + delta-based cherry-pick) for the rejected ref(s), then retry the push — and since the local ref is now rebased on top of remote, the retry is a fast-forward, so it stays non-force. No tryPushRefCommon, no reintroduced force.

So: nothing to undo from Fix 1 — we'd just bolt the rebuild onto the existing non-force reject path so it self-heals instead of staying queued.

Want me to add that recovery to the git-refs path on #1566?

All three review-driven changes are now in on #1566, verified, and the stack is clean.

What landed

1. ab394204c — non-force push (the earlier fix): batchPushRefs sends ref:ref, fast-forward-only.
2. bc296fd7d — RefName validates: returns (ReferenceName, error), refusing to build refs/entire/checkpoints// for an empty/invalid ID.
3. 64e40b817 — fetch+replay recovery (this one): on a rejected (diverged) ref, instead of leaving it stuck, it fetches the remote and replays the local-only commits on top via the existing fetchAndRebaseRefCommon, then retries — still non-force (the replay makes it a fast-forward, so the remote commit is preserved as an ancestor, never overwritten).

The recovery is exactly your "easy way out": it reuses the v1 branch's rebuild machinery (already non-branch-aware, delta-based cherry-pick), so non-overlapping divergence auto-merges, and a genuine same-file conflict degrades to the previous safe "left queued" state — never to a force overwrite. The pre-push keeps the batch push as the fast path and only drops to per-ref recovery for rejected refs.

Verified: lint 0, strategy + checkpoint + cli unit green, both-mode canary (git-branch 59/59, git-refs 58/59 + 1 skip). New test TestPushCheckpointRefWithRecovery_MergesDivergedRef proves a diverged ref ends up with both the remote-only and local-only changes.

Housekeeping: I'd accidentally committed the recovery on the path-join branch first — caught it from the push target, cherry-picked it onto #1566 where it belongs, and restacked #1576 so it's back to just the path-join commit. Both branches pushed and consistent.

Net: the force-push footgun you flagged is fully resolved — fast-forward by default, auto-heal on the rare divergence, and RefName can no longer mint a malformed ref.

The 4 review agents (reuse / simplification / efficiency / altitude) are running on the three review-fix commits. I'll wait for all four, dedup their findings, apply the worthwhile ones, and report what I fixed vs. skipped.

/simplify complete

Ran 4 review agents (reuse / simplification / efficiency / altitude) over the three review-fix commits. One substantive fix applied (e6934f439 on #1566):

Applied — the altitude finding (the real one):

• tryPushRefCommon no longer force-pushes non-branch refs. It still used +ref:ref for non-branch refs, contradicting the new fast-forward-only policy and leaving a latent footgun (a future caller routing a checkpoint ref through doPushRef would silently clobber a divergence). I verified that path has no production caller and no test dependency (the v1 pre-push loop only pushes the v1 branch), so dropping the force is safe and gives one consistent non-force policy for every checkpoint ref, with doPushRef's fetch+rebase recovery covering divergence.
• Minor: a clarifying comment that explain_export's RefName-error branch is defensive (cid is pre-validated, so it can't fire) — rather than adding a logging import for an unreachable path.

Skipped, with reasons:

• Duplicate mustRefName (two test packages) — sharing would require exporting a test-only helper or a new testutil; not worth it for a 4-line helper across package boundaries.
• Per-ref timeout in the recovery loop — it mirrors the existing doPushRef per-ref-budget convention, and pushCtx has no parent deadline so there's no nesting bug.
• Redundant re-push of batch-succeeded refs in the cold path — the efficiency agent rated it acceptable; git doesn't give granular per-ref failure data, and divergence is rare.
• fetchAndRebaseRefCommon naming — pushCheckpointRefWithRecovery already documents the delta-cherry-pick merge.

The rest of the diff the agents judged already clean (the recovery shape, the RefName error propagation in refs_store.go, the control flow in prePushCheckpointRefs).

Verified: lint 0, strategy + cli unit green, both-mode canary (git-branch 59/59, git-refs 58/59 + 1 skip). Pushed to #1566; #1576 restacked on the new tip. The non-force policy is now uniform across the whole checkpoint-push surface.

Done — PR #1580 (off main).

The E2E Checkpoint Store workflow now runs all agents when you leave agent blank:

• agent input is optional with a blank first option ("leave empty to run all agents"); pick one to run just that one.
• A matrix-setup job fans out to the eight real agents (the same set e2e.yml uses) when blank, or [selected] otherwise.
• The two jobs collapse into one matrix job (fail-fast: false) — copilot-cli now runs in the matrix with copilot-requests: write granted to every leg and COPILOT_GITHUB_TOKEN passed through, so the separate copilot job is gone.
• checkpoint_store (git-branch / git-refs) is unchanged and applies to every agent in the run. vogon stays selectable individually for a free smoke test.

Validated the YAML/structure (blank-first optional input, dynamic matrix, single fan-out job). It's workflow_dispatch-only, so it can't run automatically or affect other CI — and it'll be dispatchable with the blank-agent option once #1580 merges to main (the default-branch requirement again).

Quick recap of the open PRs in this effort:

• #1566 — git-refs backend (+ the review fixes & /simplify).
• #1576 — path.Join cleanup (stacked on #1566).
• #1580 — this workflow fan-out (independent, off main).

I switched back to feat/checkpoint-git-refs locally. Anything else?

Done — #1580 is rebased onto latest main (which had advanced 52 commits) and force-pushed. Clean rebase, no conflicts: the branch's diff is still exactly the one workflow file (e2e-checkpoint-store.yml), YAML validated. PR is current and ready for review/merge.

Good call — main moved 52 commits, so the workflow could be out of sync with current e2e.yml conventions (agent list, install commands, pinned action SHAs, env). Let me compare my workflow against e2e.yml on current main.

#1580 is correct and current. After rebasing onto main (which moved 52 commits), I diffed the actual pushed head against today's e2e.yml:

Everything that matters matches main's conventions:

• Pinned action SHAs (checkout/mise/upload-artifact) — identical
• Agent list — identical 8-agent set (claude-code, opencode, gemini-cli, factoryai-droid, cursor-cli, copilot-cli, roger-roger, codex)
• API-key env (ANTHROPIC/GEMINI/OPENAI/CURSOR/FACTORY), E2E_CODEX_MODEL, COPILOT_GITHUB_TOKEN, gnome-keyring/tmux setup, install case, bootstrap, mise run test:e2e --agent — all present and migrated to matrix.agent
• Blank-first optional agent input (- ""), matrix-setup fan-out, single matrix job with fail-fast: false and copilot-requests: write granted to every leg — all intact

The only differences are by-design, not staleness:

• No Classify failures / Notify Slack steps and no GH_TOKEN — those are e2e.yml's scheduled-run failure-reporting machinery; this is a manual workflow_dispatch tool, so they're intentionally absent (and GH_TOKEN is only consumed by them).
• No concurrency: block — e2e.yml has one to serialize scheduled/PR runs; the checkpoint-store workflow never had one. Not a regression. Optional nicety if you want to prevent two manual dispatches from racing, but it's harmless to leave off for a human-triggered tool.

So: rebase is clean, diff vs main is exactly the one workflow file, YAML valid, and the content is in sync with current main. No changes needed.

Done. Here's the full picture from the entire trail finding dashboard for #1580 (trail #706).

What the trail had: 9 open findings (2 high, 3 medium, 4 low)

Fixed and resolved (7) — committed in 21ba7e7be and pushed:

The three medium env findings are notably the ones my earlier key-only staleness diff missed (I compared env keys, not values, and missed keys e2e.yml sets at a different indent). I also fixed a divergence the bot didn't flag: roger-roger now runs through its deterministic task (no --rerun-fails), matching e2e.yml.

A nice confirmation: after the push, exactly those 7 findings flipped to stale (their lines changed) while the two below stayed current — proof I touched the right lines.

Left open for your call (2 high)

Both flag the same thing: the collapsed matrix grants copilot-requests: write and passes COPILOT_GITHUB_TOKEN + all provider keys to every agent leg, where the old separate-job design compartmentalized copilot.

I did not "fix" this, because main's e2e.yml — which runs on every push — already does exactly this (line 52 grants copilot-requests: write to the whole matrix; every leg gets COPILOT_GITHUB_TOKEN and all provider secrets). Splitting #1580 back out would make it diverge from the repo standard. The finding is a legitimate defense-in-depth observation, but tightening it should be a deliberate, repo-wide change to both workflows — not a one-off here.

I left these open rather than dismissing them, since that's a security trade-off you should decide. Your options:

• Dismiss as accepted (matches e2e.yml): entire trail finding dismiss 019f18e3-36d -m "..." (and 019f18ca-8b8)
• Tighten both workflows separately to scope copilot creds to only the copilot-cli leg

Want me to dismiss them with that rationale, or open a separate issue/PR to scope copilot credentials across both workflows?

Clear answer: it's been in e2e.yml for ~2.5 months — not added today, and not in #1580.

Timeline in e2e.yml (on main):

• 2026-03-04 (50f61d9a5 "copilot e2e") — copilot first added to the e2e suite.
• 2026-04-09 (a5505f195 "allow copilot use actions token") — COPILOT_GITHUB_TOKEN: ${{ github.token }} + copilot-requests: write granted to the whole shared matrix. At that commit copilot was already running in the matrix (not a separate job), so the token/permission has gone to every agent leg since then.

So today's PR (#1580) did not introduce this to e2e.yml, and it didn't invent it — it brought the checkpoint-store workflow into line with the e2e.yml pattern that's been live on every push since April. The bot's "regression" is real only relative to e2e-checkpoint-store.yml's own prior form (which had a dedicated copilot job); relative to the repo's actual standard, #1580 is consistent.

Net: the credential-to-all-legs exposure exists today on every push via e2e.yml, independent of #1580. If you want to tighten it, the meaningful fix is in e2e.yml (and #1580 follows), not a #1580-only change. Want me to open a separate issue/PR to scope copilot creds to just the copilot-cli leg across both workflows?

Done — PR #1583 off latest main.

What it fixes

The copilot GitHub token was being handed to every agent, not just copilot. I swept all the E2E workflows and found the leak in three:

e2e-checkpoints-v2.yml needed no change — it already runs copilot in a dedicated copilot-cli-only job, so its token never reaches other agents.

Approach

I kept #1580's single-matrix design rather than re-splitting copilot into a separate job (which would reintroduce the duplication that PR just removed). Two layers close the exposure:

1. Token env scoped per-leg — non-copilot agents now get an empty COPILOT_GITHUB_TOKEN.
2. persist-credentials: false on checkout — the copilot-scoped GITHUB_TOKEN isn't left in .git/config for an agent process to read.

The job-level copilot-requests: write permission has to stay (GitHub forbids matrix expressions in permissions:), but after this no non-copilot agent can reach that token — env or disk. I verified the harness uses local temp remotes and never touches origin, so dropping persisted credentials is safe.

One caveat worth flagging: these workflows are push/dispatch-triggered, so CI won't exercise them on the PR itself — the changes take effect on the next push to main / next manual dispatch. The diff is small and YAML-validated, but the first real run is the actual test.

Want me to link this PR back on the two open HIGH findings in trail #706 (and resolve them once it merges)?

#1566 rebased onto latest main and force-pushed. ✅

Summary:

• Clean rebase — all 12 feature commits replayed onto origin/main (which had advanced 62 commits) with no conflicts.
• The branch's only .github change is ci.yml (+8, the git-refs canary matrix) — intact. It doesn't touch e2e.yml/e2e-checkpoint-store.yml, so nothing on main was clobbered. (The "missing #1583 scoping" I checked was a non-issue: #1583 is the still-open PR I opened earlier, not yet on main.)
• Verified the rebase didn't break anything against 62 commits of drift: go build ./... OK, go vet on the changed packages OK, mise run lint clean (0 issues).

Note: PR #1576 (the path.Join cleanup) was stacked on #1566. If it's still meant to sit on top, it'll need re-stacking onto this rebased tip — want me to do that too?

I've got the full picture. Here's the verdict on run 28465462293:

✅ The git-refs backend passed — the 3 failures are agent flakiness, not the store

All three jobs confirmed E2E_CHECKPOINT_STORE: git-refs, and the fan-out worked (your blank-agent → all-agents change).

5/8 agents passed the full suite against git-refs, clean: claude-code, opencode, codex, copilot-cli, roger-roger — all green.

3 failed — all the known-flaky tier, all agent-side causes:

Why this is not a git-refs bug

• Every failure traces to the agent failing to start or respond (process exits, startup-prompt timeouts, Gemini rate limits, transient API errors). The checkpoint state did not advance within 30s lines are downstream — when the agent never produces output, no checkpoint is ever written, so state can't advance.
• The decisive signal: the reliable agents passed the entire suite against git-refs with zero failures. If git-refs had a real "checkpoint not advancing" or ref-push bug, those agents would have hit it too. They didn't. There's not a single refs/entire/... push rejection, RefName error, or store assertion anywhere in the logs.
• Backend gating works: alternates_test.go (a git-branch-only test) correctly SKIPPED on git-refs.

One small follow-up (non-blocking)

The git-refs skip reason in alternates_test.go:28 is now stale — it says "the git-refs store force-pushes independent per-checkpoint refs", but we switched git-refs to non-force fast-forward + fetch/replay. Worth updating that comment so it doesn't mislead. Want me to fix it on the #1566 branch?

Bottom line: git-refs is validated end-to-end. The red Xs are the same flaky agents that flake on main's git-branch runs too — re-running gemini-cli/cursor-cli/factoryai-droid would very likely green them.

Done — pushed to #1566 (feat/checkpoint-git-refs, commit c41e19d67).

The skip reason in alternates_test.go:28 now reads:

"git-branch-specific: exercises the v1 checkpoint branch's non-fast-forward push/rebase sync over an object alternate; the git-refs store writes independent per-checkpoint refs (fast-forward push with fetch+replay recovery) and has no such v1-branch rebase path"

The test stays skipped for git-refs (it's genuinely git-branch-only), just with accurate wording. Formatted and go vet -tags e2e ./e2e/tests/ passes.

So to recap the git-refs validation thread: the full e2e run proved the backend works (5/8 agents green, the 3 reds were agent flakiness), and the one stale comment it surfaced is now fixed.

Both stacked PRs are rebased and pushed cleanly:

For #1576: git dropped the 12 stale git-refs commits (patch-equivalent to the rebased ones in #1566) and replayed just its one unique commit, so its PR diff is now clean — only the path.Join change (persistent.go + the new subtree_path_test.go). It also inherits #1566's corrected alternates-test comment. Lint clean (0 issues), build OK.

The stack is consistent again: #1576 sits directly on the current #1566 head, and #1576's base branch is unchanged so the PR target is still correct. Once #1566 merges, #1576 will auto-retarget to main (or I can rebase again then if needed).

Looked at both comments on #1576 — both from the Copilot reviewer, both about the same edge case in the new checkpointSubtreePath helper. Addressed in 2e0a576aa (pushed to the branch).

The finding: checkpointSubtreePath delegated straight to path.Join, and path.Join("") cleans to "." — an invalid git tree key. The helper's doc claims it handles the ref root (base=="") safely, but that was only true when at least one segment was passed.

Reality check: Not a live bug — I verified all ~35 callers pass at least one segment, so the "." case is never actually hit today. But the reviewer is right that it's a latent footgun that contradicts the helper's own contract, so the fix is worth it:

• persistent.go: special-cased the no-segment path — base=="" → "" (ref root), non-empty base → path.Clean(base) (preserves the existing trailing-slash stripping). The multi-segment path is unchanged.
• subtree_path_test.go: added the ref root base only case ("", nil → "") the reviewer asked for, which would have returned "." before the fix.

Test passes (including the new case), lint clean (0 issues). Both review comments are now resolved by the change — want me to reply on the threads marking them addressed, or leave that for the merge?

Done. Here's the triage of all 6 review threads on #1566.

Closed (genuinely stale) — 1

#4 — pushqueue.go:172 (Copilot: "could force-push arbitrary refs like refs/heads/main") → resolved with an explanatory reply. The premise is gone: the queue is no longer force-pushed. batchPushRefs is fast-forward-only and pushCheckpointRefWithRecovery recovers divergence via fetch+replay, so a stray refs/heads/main entry would be rejected as non-ff, never clobbered.

Also fixed — 2 stale doc comments (code accuracy, pushed)

• manual_commit_push.go:125 still said "batch force-pushes" → corrected to fast-forward-only + fetch/replay (commit 8d1f57cf5 on #1566; #1576 restacked on top).
• (earlier) the alternates_test.go skip reason.

Left open — 5, because they're not actually stale

I checked each against current code — closing these would bury live feedback:

#2/#3/#5 are one coherent theme: "treat any ref-resolution error as not-found/stale," which masks real IO/corruption errors. The author chose this deliberately (//nolint comments document it), so it's a genuine trade-off, not a bug — but I can tighten all three in one small pass to distinguish plumbing.ErrReferenceNotFound from other errors if you want.

Want me to: (a) fix the #2/#3/#5 error-handling family, (b) address #0's policy-sync gap, and/or (c) just dismiss any of these as won't-fix?

Done. Both fixes are implemented, tested, pushed, and the stack is consistent — and I resolved the four review threads they close.

(a) Error handling — stop masking real errors as "not found"

Commit e99a03abf on #1566:

• refBase (#2): only plumbing.ErrReferenceNotFound starts a new orphan checkpoint; a real lookup error (IO/corruption) now surfaces instead of silently overwriting the ref's history.
• resolveRefMaybeFetch + checkpointTree + Read (#3): a failed on-demand fetch (offline/network/ctx-cancel) and broken commit/tree objects now propagate as real errors; only a genuinely absent ref (or a successful fetch that finds nothing) resolves to not-found. Rewrote the fetch-failure test to assert this (error propagates; genuine absence still reads as (nil, nil)).
• partitionLocalRefs (#5): a transient/IO lookup error keeps the ref pushable (retried next pre-push) instead of dropping it from the queue as stale.

(b) Pre-push policy sync for git-refs

• prePushCheckpointRefs (#0) now calls syncCheckpointPolicyForPrePush first — a diverged or unsupported-format checkpoint policy skips the ref push (leaving refs queued), matching the v1 path. Placed before Drain() so blocked refs aren't lost.

Verification: go build OK, checkpoint + strategy unit tests pass, integration green (379), lint clean.

Thread status on #1566

• Resolved (5 of 6): #0, #2, #3, #4 (earlier), #5 — each with a reply pointing at the fix commit.
• Still open (1): e2e/testutil/backend.go:51 — the checkpointShard test helper sharding any 26-char ID as ULID vs a strict ULID. Left open per your a+b scope; it's a latent, currently-unreachable test-helper nit (IDs are 12-hex until ULID emission lands). Say the word if you want me to tighten it (mirror id.ShardFor's strict-ULID check) to close it too.

#1576 was restacked on the new #1566 tip (6afd87cf3), so the stack is clean.

Your instinct is right, and the code actually makes it even safer than the finding implies. I traced production:

• RefName rejects any KindUnknown ID (refs_naming.go): a 26-char string that isn't a strict ULID is KindUnknown, so it errors out before sharding — it never gets a ref at all.
• ShardFor: strict ULID → last-2; everything else (incl. legacy 12-hex) → first-2.

So mapping the two divergence cases:

1. Your backfill case — existing checkpoints keep their 12-hex IDs (KindLegacy). Production shards them first-2, and the test helper (len != 26 → first-2) does the same. No divergence — backfilled legacy IDs already work identically.
2. The only place the helper differs is a 26-char non-strict-ULID, and production's RefName rejects that outright today, so it never reaches the ref layer for the helper to mismatch on. Unreachable in any passing flow.

So there's nothing to tighten for the realistic backfill path. The real decision you're pointing at isn't the test helper at all — it's a production-policy question for when backfill lands: should KindOf/RefName accept a broader ID class (non-hex, non-ULID) so backfilled-but-not-rewritten IDs get refs? Right now they'd be rejected as KindUnknown. When you decide that, the test helper should just be reconciled with whatever ShardFor/RefName settle on then (ideally by having it mirror them).

Given all that, I'd leave the code as-is and just not carry the thread as a phantom "unaddressed." My suggestion: dismiss #1 with a short note capturing this — "helper matches production for legacy (backfill) and strict-ULID IDs; 26-char non-ULIDs are rejected by RefName today; revisit if backfill broadens accepted ID formats."

Want me to dismiss it with that note, or leave it open as a marker for the future ULID/backfill work?

This is genuinely small — the design makes it almost free. Here's why and the estimate.

Why it's cheap

The git-refs ref tree is the v1 <shard>/<id> subtree, byte-identical (that was a deliberate design guarantee). And the primitives already exist:

• WalkCheckpointShards(ctx, repo, v1Tree, cb) enumerates every checkpoint, handing you (checkpointID, subtreeHash) directly.
• CreateCommit(ctx, repo, treeHash, parent, msg, author, email) takes a tree hash as-is — so you reuse the existing subtree object with no rebuild.
• setRef already sets the ref and enqueues it for push.

So the core migration is ~40–60 lines:

Estimate: ~1 day for a solid, tested MVP

• Core backfill function: ~1–2h
• Entrypoint (hidden entire checkpoint migrate --to git-refs): ~1–2h
• Tests (seed v1 with multi-session + task checkpoints, backfill, assert refs exist with byte-identical trees, Read works via git-refs, idempotent re-run): ~2–3h
• Edge cases, lint, docs: ~2h

Decisions that set the scope (all default to the cheap path)

1. Snapshot vs history — backfill creates one commit per checkpoint (current state), not the full v1 per-checkpoint history. Reconstructing history adds ~1–2 days and buys little. → Snapshot.
2. Imported provenance — marking backfilled checkpoints Imported=true means rewriting each metadata.json, which breaks the free byte-identical tree reuse (you'd rebuild every tree). → Reuse trees as-is, skip the flag for MVP (can add later if provenance matters).
3. Trigger — explicit hidden command vs auto-on-first-git-refs-write. → Explicit command (rollout-friendly, no surprise work in a hook).
4. Push — setRef enqueues → sent on next pre-push (consistent), optionally a direct push at the end.

Bonus: this dissolves finding #1

Backfilled checkpoints keep their 12-hex IDs — no ULID rewrite needed — which both the test helper and production ShardFor shard identically. So the whole 26-char-non-ULID divergence never arises for real backfilled data. That's a good reason to just dismiss #1 now (not tighten it): the realistic path is provably consistent.

Want me to build the MVP (snapshot, no Imported, hidden checkpoint migrate command) as a follow-up PR stacked on #1566? I'd keep it separate so it doesn't hold up the store landing.

Done — and all six review threads on #1566 are now resolved.

What shipped

ShardFor now uses one positional rule — the last two characters — for both ID formats (02e2f0880 on #1566):

• No more Kind branch, so there's nothing to compute inconsistently. Legacy 12-hex and ULID both shard on their (uniformly random) trailing chars → even distribution either way.
• RefName still rejects KindUnknown, so both supported formats map to a proper ref while invalid IDs are refused — exactly what you asked for.
• Only touches the git-refs ref namespace; the v1 branch tree keeps its independent first-two Path() layout, and there's no git-refs data yet, so zero migration cost.
• The e2e checkpointShard helper is the same one-line rule, so it can't diverge from production — which dissolves finding #1 by construction (no strict-ULID detection to get wrong).

Updated the shard expectations in the id / refs-naming / refs-store tests (including repointing the negative "shard mismatch" case, since f6/a1b2c3d4e5f6 is now the valid bucket). Verified: unit tests pass, lint clean, and the git-refs canary is green (58 passed, 0 failed).

A correction along the way

I initially committed the sharding change onto #1576 by mistake (I was on that branch). I moved it: cherry-picked onto #1566 and reset #1576 back so it's cleanly just the path.Join diff again. Final state:

• #1566 → 02e2f0880 (error-handling + policy-sync + sharding)
• #1576 → a0ec756d1 (only persistent.go + subtree_path_test.go)

All 6 review threads on #1566 are resolved; 0 open. No backfill/migration was added — just the robust dual-format ID→ref mapping you wanted.

Both descriptions are now current.

#1566 — rewritten (was significantly stale)

Corrected the three things that were actively wrong, and added what was missing:

• Stacking → now says it targets main, with #1576 stacked on top (dropped the merged-#1556 note).
• Sharding → "last-two for both formats, one positional rule" (was "first-2 legacy / last-2 ULID").
• Push → "fast-forward-only, never force; diverged refs recovered by fetch+replay" (was "force-pushes, no recovery needed").
• Added: RefName rejecting invalid IDs, read paths surfacing real errors instead of masking as not-found, pre-push honoring the checkpoint policy.
• Refreshed: dropped the "7 commits" framing, bumped integration to 379, added "backfill/migration" to the out-of-scope list, and fixed the TestAlternates skip rationale.

#1576 — minor top-up (was mostly accurate)

• Added the empty-base edge case (path.Join("") → "." fix + the ref root base only test) from the Copilot review.
• Bumped integration to 379.

I preserved the trail-link and <!-- CURSOR_SUMMARY --> blocks verbatim in both. Note the Cursor summaries still describe the old "force-push" behavior — those are bot-generated and regenerate on new commits/reviews, so I left them alone rather than hand-editing.

Now it's fully clear. Notably rewriteExportCheckpointVersionToRefsV1 already writes refs-v2 (body was updated but name + assertion weren't) — so I just align the name and assertion. Let me make all the cli-package flips:

#1566 (the PR you asked about) is fixed — rebased onto latest main, all conflicts resolved, tested green, and pushed. #1576's rebase I aborted deliberately; here's the full picture.

#1566 — done ✅

Rebased onto latest main (77 commits of drift). Resolved:

• Test-file conflicts (attach_test.go, explain_test.go) — main had refactored these around a shared writeUnsupportedCheckpointPolicyForCLITest helper.
• A real API break: main split syncCheckpointPolicyForPrePush into a void sync + a separate checkpointPolicyAllowsGitHook decision. Adapted the git-refs pre-push path to the new two-call shape.
• A semantic shift: main added several tests using refs-v1 as the "unsupported version" sentinel — but this branch makes refs-v1 supported. Moved those sentinels to refs-v2 (policy-print, explain-reject, agent-hook-skip, CanSatisfyPolicy, UnsupportedPolicyMessage) and renamed the export helper to match.

Verified: build clean, lint 0 issues, integration 380 pass, git-refs canary 58/0 fail (+expected skip). Pushed (7816aaeec), so #1566's conflicts are cleared.

#1576 — needs a fresh re-derivation (recommend deferring)

Its rebase conflicts non-trivially: main rewrote writeTranscript/writeCompactTranscript to return a new compact-transcript-start offset, and #1576's path.Join refactor (param rename + helper) touches those exact functions. Force-merging the 6 hunks risks the byte-identical-tree invariant that PR is built to preserve.

Since #1576 is a small cosmetic cleanup and #1566 merges first, my recommendation is to re-derive #1576 cleanly once #1566 lands — persistent.go stops moving then, and redoing the checkpointSubtreePath sweep against the settled file is one clean, verifiable pass (vs. resolving it now against a moving target and again after merge). I left #1576 untouched on its old base rather than push a tangled merge.

Want me to (a) re-derive #1576 now against the current rebased #1566 anyway, or (b) leave it and redo it after #1566 merges?

Done — compaction-on-Drain added to #1566 (40cded153).

What changed

The push queue's Enqueue only appends, so a long-lived session re-enqueuing the same checkpoint ref across many writes (without pushing) would grow the file unboundedly — Remove was the only thing that ever rewrote it. Now:

• Drain compacts in place: it already de-duplicated in memory; it now also rewrites the file to that de-duplicated set, dropping redundant lines (duplicate refs and malformed/blank records). The file is bounded to one line per distinct queued ref.
• Only when needed: readLocked now reports the raw non-empty line count, so Drain rewrites only when rawLines > len(refs) — no wasted I/O when the file is already compact.
• Behavior preserved: Drain still returns the refs and does not clear them (they survive until a confirmed Remove), and the rewrite is atomic (temp + rename). Factored the rewrite into a shared rewriteLocked helper that Remove now uses too.

Tests

Two new tests: TestPushQueue_DrainCompactsRedundantEntries (4 enqueues → file collapses to 2 lines, refs preserved, re-drain doesn't rewrite) and TestPushQueue_DrainCompactsMalformedLines (garbage lines dropped from disk). All 7 pushqueue tests pass, plus the full checkpoint + strategy suites; lint clean.

Note this lands on #1566, which is already rebased on latest main. (#1576 is still on its stale base pending the re-derivation we discussed — let me know if you want that now or after #1566 merges.)

Good instinct to push on it — checking the actual call sites, my commit message was a bit imprecise about the "(without pushing)" part. Here's the accurate picture.

The mechanics

Enqueue is append-only and runs on every write. The chain is: every checkpoint write (writeSession, backfillTranscript, backfillSummary, backfillAttribution) → setRef → enqueueForPush → Enqueue, which just appends one JSONL line:

Within a single session you write to the same checkpoint ref many times (each step, each transcript/summary/attribution backfill). So the same refs/entire/checkpoints/<shard>/<id> string gets appended over and over:

readLocked de-duplicates in memory (a seen map), so Drain always returned [A] — but the file still held N lines.

Compaction only ever happened in Remove. Remove is the only function that rewrites the file (temp + rename), and both Drain and Remove run only at pre-push (prePushCheckpointRefs). Enqueue runs continuously.

Where my commit message overstated it

I wrote "(without pushing) would grow unboundedly." Strictly, if you never push, the pre-push hook never fires, so Drain never runs either — and my new compaction is in Drain, so it wouldn't help that pure never-push case. That parenthetical was wrong.

The case the fix actually addresses is: the file was only compacted by Remove, and Remove(existing) runs only after a successful push. So:

• Offline / failing pushes: pre-push fires → Drain (old: no rewrite) → push fails → Remove(existing) never called → the N accumulated lines stay, and the next writes keep appending. Repeated failed pushes + writes → the file keeps growing across cycles.
• Even on success, the compaction was a side-effect of Remove removing the pushed refs, not an explicit "keep the queue tidy" step.

With compaction-on-Drain, the file is collapsed to the distinct set at Drain time, before and independent of whether the push (or the later Remove) succeeds. So a flaky/offline push can no longer let duplicates pile up.

Bottom line

• Accurate claim: "Between the successful pushes that trigger Remove, the queue file accumulated one appended line per write (the same ref repeated), and a failed push left them in place. Compacting on Drain bounds it to one line per distinct ref every time the queue is read."
• The literal "never push at all" scenario still grows until the first pre-push — neither old nor new code compacts a queue that's never drained.

Want me to reword the commit message to that more precise version? (Easy git commit --amend + force-push since #1566 hasn't merged.)

Verified both pieces. Short answer: file integrity is solid; there's one pre-existing delivery-completeness race that compaction doesn't affect. Here's the breakdown.

Concurrency (multiple agents, same host)

What's safe:

• Every Enqueue/Drain/Remove takes an exclusive flock (LOCK_EX) for its whole duration, so the three operations are fully serialized — no interleaved partial lines, no torn reads. Writes go through temp-file + rename (atomic). So no corruption regardless of how many agents hammer it.
• Compaction is race-free w.r.t. lost enqueues: Drain holds the lock across both the read and the rewrite. Any Enqueue either happened before the read (so it's included in the compacted set) or after the unlock (so it appends to the already-compacted file). There's no window where an append is dropped.
• flock is crash-safe: it's released on f.Close() or on process death (the OS closes fds). So a crashed agent can't leave a stale lock that deadlocks the others.
• Double-push is harmless: if two agents pre-push at once they may both drain and push the same refs, but the batch push is fast-forward/idempotent.

The real caveat (pre-existing, not from compaction): the lock is deliberately not held across the network push. The sequence is Drain (lock) … push (no lock) … Remove (lock). So between Drain and the post-push Remove, another agent can write the same checkpoint and Enqueue it again. Remove(pushed) then drops that ref's entry — even though what got pushed was the older state. The newer state is now local, un-pushed, and no longer queued. During an active session it self-heals (the next write re-enqueues), but if it was that checkpoint's last write in the window, its final state can sit un-pushed until some future write or resync.

I checked: compaction doesn't change this — the net outcome is identical with or without it. It's a property of the "don't hold a lock during network I/O" design, and the queue stores only the ref name, so Remove can't tell the ref advanced since Drain.

Worktrees

• The queue lives in the shared common dir (git rev-parse --git-common-dir), so all worktrees of a repo share one queue file and one lock. That's correct, because refs/entire/checkpoints/* are common-dir (shared) refs, not per-worktree — one queue matches one ref namespace.
• Consequence: any worktree's git push drains and pushes the whole shared queue, including refs enqueued by other worktrees. Usually desirable (any push flushes everything pending), and it's still all under the one lock so it's safe. Two wrinkles worth knowing:
  • The Drain→push→Remove race above now spans worktrees too (a write in worktree B during worktree A's push).
  • If two worktrees are configured with different checkpoint remotes (separate .entire/settings.json), the first pusher sends everything to its target — so B's refs could go to A's remote. Rare, but a real edge of the shared-queue design.