test: git-remote coverage (2/4) — real-hook P0 tests, cross-machine fetch, explain fix

[Soph]

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

Part 2 of the stack on #1636. The P0 test groups from the plan, plus two fixes they surfaced.

Tests

• A-group (real pre-push hook, both backends): plain-push checkpoint sync with user-push assertions (A1), no-new-checkpoints no-op via remote digest (A2), branch-delete and tag-only pushes through the hook (A3), unreachable checkpoint target degrades gracefully under the real hook (A4), git-refs queue drain via real push (A6 slice).
• C-group (cross-machine clone flows): production fetchMetadataBranchIfMissing exercised for real over HTTPS (C1 — previous clone tests substituted a raw git fetch), git-refs on-demand RefFetcher fetches exactly the needed ref and nothing else (C2), unreachable-remote reads surface the real fetch error (C3), authenticated HTTPS clone auto-fetch under both backends (C4).
• G1 (e2e): resume_remote_test.go / explain_test.go clone tests now rely on the installed hook (AssertCheckpointsOnRemote) instead of explicit PushCheckpointRefs — a broken hook can no longer pass the e2e suite.

Fixes

• Graceful-degradation test false-positive: the test staged the session's files after the stop hook, so neither backend condensed anything; git-branch passed only because the v1 branch was inherited from the clone. Reordered to stage-before-stop and the assertion now requires a new checkpoint ID.
• fix: surface git-refs checkpoint fetch failures in explain fallback: matchCheckpointPrefixWithRemoteFallback discarded the FetchCheckpointRef error, reporting an unreachable remote identically to an absent checkpoint — re-masking the error class 7bbdad0 fixed at the store layer. The fallback now propagates the error (repos with no resolvable checkpoint source keep the clean not-found; the commit-ref prefetch stays best-effort; the v1-branch path keeps its historical fail-soft behavior). C3 asserts it hard.

Verification

• mise run fmt && mise run lint clean per commit
• mise run test:integration green (430 tests, 0 skips at tip)
• mise run test:e2e:canary green under both E2E_CHECKPOINT_STORE values

🤖 Generated with Claude Code

https://claude.ai/code/session_012yi3hHGAGepwfrfjPETjGq

---

Note

Medium Risk
Changes user-visible error handling on checkpoint explain and attribution when remotes are unreachable; behavior is more correct but could surprise scripts that only matched on “not found”.

Overview
Adds broad integration and e2e coverage for checkpoint sync and cross-machine reads: real git push through the installed pre-push hook (sync, no-op pushes, delete/tag shapes, unreachable checkpoint_remote, git-refs push-queue drain), HTTPS clone flows (fetchMetadataBranchIfMissing, tokenized auto-fetch, per-ref RefFetcher precision), plus e2e tests that assert checkpoints land on the remote via the hook instead of explicit PushCheckpointRefs.

Fixes misleading “checkpoint not found” when the remote fetch actually failed (regression 7bbdad0): matchCheckpointPrefixWithRemoteFallback now returns a third error value; git-refs FetchCheckpointRef failures and post-fetch re-list errors propagate through checkpoint explain, JSON export, and attribution remote enrichment. Repos with no resolvable remote still get a clean local not-found; the v1 metadata-branch path keeps prior fail-soft behavior.

Test harness / correctness tweaks: TestEnv helpers for config, tags, push-queue peek, and hook pushes with arbitrary args; graceful-degradation clone test stages files before stop and requires a new checkpoint ID (fixes a false positive from inherited v1 metadata).

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

[Copilot]

Pull request overview

This PR (part 2/4 of the #1636 stack) expands integration + e2e coverage around git-remote checkpoint behavior—especially “real git push through installed pre-push hook” flows and cross-machine clone/read fetch paths—and fixes a production bug where checkpoint explain could incorrectly mask an unreachable-remote fetch failure as “checkpoint not found”.

Changes:

• Adds integration tests for real-hook pushes (sync, no-op, delete/tag shapes, unreachable checkpoint_remote degradation, git-refs push-queue drain) and HTTPS clone/read auto-fetch flows.
• Adds git-refs clone read coverage to ensure the on-demand RefFetcher fetches exactly the needed checkpoint ref and surfaces real remote fetch errors.
• Updates explain/prefix-match remote fallback to propagate git-refs fetch errors (instead of reporting “not found”), and updates e2e clone tests to assert hook-driven remote checkpoint sync.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
e2e/tests/resume_remote_test.go	Switches clone flow to assert hook-driven remote checkpoint sync instead of explicitly pushing checkpoint refs.
e2e/tests/explain_test.go	Same as above for explain-from-clone e2e coverage.
cmd/entire/cli/integration_test/testenv.go	Adds integration test helpers (git config/tag, push queue peek, push-with-hooks args).
cmd/entire/cli/integration_test/remote_operations_test.go	Fixes graceful-degradation test ordering and strengthens assertion to require a new checkpoint.
cmd/entire/cli/integration_test/refs_fetch_test.go	New C2/C3 git-refs clone/read tests for exact-ref fetch and unreachable-remote error surfacing.
cmd/entire/cli/integration_test/real_hook_push_test.go	Adds A2/A3/A4/A6 integration coverage around real pre-push hook behavior.
cmd/entire/cli/integration_test/http_remote_test.go	Adds HTTPS cross-machine clone → fetch/read tests (C1/C4).
cmd/entire/cli/git_operations.go	Updates FetchCheckpointRef contract comment to require surfacing fetch failures.
cmd/entire/cli/explain.go	Propagates remote fetch failures from the prefix-match fallback instead of returning not-found.
cmd/entire/cli/explain_export.go	Threads fallback errors through export + commit-ref prefetch behavior; updates fallback helper signature.
cmd/entire/cli/attribution.go	Ensures attribution refresh path sees remote fallback errors (instead of treating as not-found).

[Soph]

Fixed in a9b0334 — PushQueueRefs now resolves the common dir via git rev-parse --path-format=absolute --git-common-dir, matching production (checkpoint/pushqueue.go), so it's correct from linked worktrees.

[Soph]

Reworded in a9b0334. One nuance: the wrapper forwarding only the remote name is not a fidelity gap — it matches the production hook template (strategy/hooks.go runs entire hooks git pre-push "$1"), and stdin is inherited via exec. The docs now state that explicitly instead of the blanket "exactly as git runs it".

[pfleidi]

I'm not 100% sure how applicable it is but it came up in an automated review using Fable:

I think the git-branch half of this test passes without actually exercising the auto-fetch. cloneFromBareWithHTTPS does a plain clone of the bare dir, and since env.RunPrePush("origin") already pushed checkpoints by that point, the clone comes with refs/remotes/origin/entire/checkpoints/v1 and all its objects included. The store is happy to serve reads from that remote-tracking ref (getSessionsBranchTree in checkpoint/persistent.go), so the checkpoint explain at the end never talks to the HTTPS server and never uses the token — everything it needs is already local.

The CheckpointsPresentLocally() guard doesn't catch this because it only looks at the local branch, not the remote-tracking ref. It's the same trap as the inherited-v1 false positive this PR fixes in the graceful-degradation test. (Cloning over HTTPS instead of the file path wouldn't change anything — the remote-tracking ref comes along either way.)

Suggested fix: for the git-branch case, delete the remote-tracking v1 ref in the clone before the read — TestExplain_CheckpointFetchesFromRemoteWhenMissingLocally already does exactly this. Then assert clone.BranchExists(paths.MetadataBranchName) after the explain, which proves the fallback fetch really ran.

One more small thing: the docstring says "Both require ENTIRE_CHECKPOINT_TOKEN to reach the server", but the test server only checks Authorization on push — reads are anonymous. I'd either adjust the docstring ("token-authenticated push, anonymous HTTPS read"), or add an opt-in requireAuthForReads to startGitHTTPSServer and assert the read fails without a token. The latter fits nicely into the plan's F-group, so a follow-up is fine.```