# Run e2e against a configurable checkpoint backend + git-refs CI

`3bf5cae`→[main](/content/gh/entireio/cli/commits/main/index.html)·

Soph·2w ago·15 files·+289 added/-61 removed

- settings: LoadCheckpointsConfig honors ENTIRE_CHECKPOINTS_PRIMARY (+ comma-separated ENTIRE_CHECKPOINTS_MIRRORS), env-wins-over-file, matching the other ENTIRE_* overrides. Backend selection only.
- e2e: make the harness backend-aware (e2e/testutil/backend.go: checkpointStoreMode, CheckpointState advance digest, checkpointBlobSpec/checkpointRefName/checkpointShard). Advance detection, metadata reads, CheckpointIDs, push, and artifact capture route through it; the v1-branch-specific alternate-object sync test skips under git-refs. AssertCheckpointIDFormat keeps the production Validate (hex or ULID).
- e2e TestMain maps E2E_CHECKPOINT_STORE (git-branch default, or git-refs) to the ENTER_CHECKPOINTS_PRIMARY override so every spawned binary/hook uses it.
- CI: e2e-checkpoint-store workflow with a checkpoint_store input; e2e/README doc.

## Sessions

d9646529ed6eView transcript

## Changes

15

- cmd/entire/cli/settings

- Mcheckpoints.go+39

- Mcheckpoints_test.go+38

- e2e

- MREADME.md+1

- tests

- Malternates_test.go+3

- Mattach_test.go+1/-1

- Medge_cases_test.go+2/-2

- Mexplain_test.go+1/-2

- Mmain_test.go+8

- Mresume_remote_test.go+4/-6

- Mrewind_test.go+1/-1

- Msession_lifecycle_test.go+3/-3

- testutil

- Martifacts.go+16/-6

- Massertions.go+33/-22

- Abackend.go+94

- Mrepo.go+45/-18

---

```go
// block is malformed (e.g. a backend with no type).
var ErrInvalidCheckpointsConfig = errors.New("invalid checkpoints config")

// Environment overrides for checkpoint backend selection. When EnvCheckpointsPrimary
// is set, it (and the optional comma-separated EnvCheckpointsMirrors) fully
// replaces any checkpoints block in settings — env wins over file, matching the
// other ENTIRE_* overrides (ENTIRE_LOG_LEVEL, ENTIRE_TOKEN, …). Primarily for
// driving e2e/CI and rollout against a specific backend without editing settings.
const (
	EnvCheckpointsPrimary = "ENTIRE_CHECKPOINTS_PRIMARY"
	EnvCheckpointsMirrors = "ENTIRE_CHECKPOINTS_MIRRORS"
)

// CheckpointsConfig selects checkpoint storage backends: one primary (source of
// truth, serves all reads and writes) and zero or more mirrors (independent
// backends that receive best-effort write fan-out). When absent, the checkpoint
// a deep-merged document). Clone preferences carry no checkpoint config and are
// not consulted.
func LoadCheckpointsConfig(ctx context.Context) (*CheckpointsConfig, error) {
	// Env override wins over any settings file (precedence like ENTIRE_LOG_LEVEL).
	if cfg, ok := checkpointsConfigFromEnv(); ok {
		if err := cfg.validate(); err != nil {
			return nil, err
		}
		return cfg, nil
	}

base, local := checkpointsSettingsPaths(ctx)

// "local replaces base wholesale": prefer a checkpoints block from local
	return env.Checkpoints
}

// checkpointsConfigFromEnv builds a CheckpointsConfig from the environment when
// EnvCheckpointsPrimary is set. Mirrors are taken from EnvCheckpointsMirrors as a
// comma-separated list of backend types (no per-backend config blocks — the env
// override is for backend selection only). Returns ok=false when no primary is
// set, leaving file-based resolution in charge.
func checkpointsConfigFromEnv() (*CheckpointsConfig, bool) {
	primary := strings.TrimSpace(os.Getenv(EnvCheckpointsPrimary))
	if primary == "" {
		return nil, false
	}
	cfg := &CheckpointsConfig{Primary: BackendConfig{Type: primary}}
	for _, m := range strings.Split(os.Getenv(EnvCheckpointsMirrors), ",") {
		if t := strings.TrimSpace(m); t != "" {
			cfg.Mirrors = append(cfg.Mirrors, BackendConfig{Type: t})
		}
	}
	return cfg, true
}

func (c *CheckpointsConfig) validate() error {
	if c.Primary.Type == "" {
		return fmt.Errorf("%w: checkpoints.primary.type is required", ErrInvalidCheckpointsConfig)
	}
}
```

| `E2E_ENTIRE_BIN` | Path to a pre-built `entire` binary | builds from source |
| `E2E_TIMEOUT` | Timeout per prompt | `2m` |
| `E2E_KEEP_REPOS` | Set to `1` to preserve temp repos after test | unset |
| `E2E_CHECKPOINT_STORE` | Checkpoint backend to run the suite against (`git-branch`, `git-refs`). Maps to the `ENTIRE_CHECKPOINTS_PRIMARY` override that every spawned binary/hook honors. | `git-branch` |
| `E2E_ARTIFACT_DIR` | Override artifact output directory | `e2e/artifacts/<timestamp>` |
| `ANTHROPIC_API_KEY` | Required for Claude Code | — |
| `GEMINI_API_KEY` | Required for Gemini CLI | — |

// collectCommitsSince() fails with "object not found" on alternate-resident
// checkpoint commits, even though git itself resolves them.
func TestAlternates_RelativeObjectAlternate_CheckpointSync(t *testing.T) {
	if testutil.UsingGitRefs() {
		t.Skip("git-branch-specific: exercises the v1 checkpoint branch's non-fast-forward push/rebase sync over an object alternate; the git-refs store force-pushes independent per-checkpoint refs with no such rebase path")
	}
	// Siblings under one parent so the relative alternate path is short and
	// mirrors a real shared-clone layout.
	parent := t.TempDir()
}

// Some more test utilities follow in similar format...

```