Fix #294: checkpoint exports bundle the Forgejo repo of record

[ealt]

Summary

• Why: under Compose, every checkpoint archive — manual and auto alike — carried an empty repo.bundle: the task-store-server ran without --repo-path, so the export route emitted the chapter 10 §6 zero-byte placeholder. Wire state round-tripped; git history silently did not (structurally valid, but non-resumable). Confirmed by live repro before the fix (0-byte checkpoint/repo.bundle while Forgejo held main + work/* + variant/*).
• The fix: the task-store-server keeps its own bare clone, synced from Forgejo per export (new --forgejo-url / --credential-helper flags → shared eden_git.ensure_local_clone; clone-on-first-export, fetch --prune thereafter). The sync is lazy (startup never touches the remote, so the import-receiver posture keeps working); a failed sync fails the export loudly with 503 eden://reference-error/checkpoint-repo-unavailable rather than emitting a stale/empty bundle.
• Ordering (chapter 10 §6): export_checkpoint now takes a repo_bundle_provider invoked after the store snapshot (outside the transaction), so the bundle is a §12-permitted superset of what the snapshot references; non-empty bundles are self-validated against the frozen snapshot with the importer's own §12 check (export-time failure beats import-time rejection), and exported_at is stamped at the snapshot instant.

What this does NOT cover

• Helm substrate — the chart's task-store-server Deployment still runs without --repo-path/--forgejo-url, so Kubernetes-substrate exports still carry the empty placeholder. The server-side machinery from this PR is substrate-agnostic; chart wiring only → Helm: wire the checkpoint-export repo (--repo-path/--forgejo-url) on the task-store-server #306.
• Smoke round-trip depth — smoke-checkpoint.sh Phase 6 compares counts + sorted id-sets, not full per-object field equality → smoke-checkpoint: deepen post-import equality from counts/id-sets to full-object comparison #312.
• Streaming export — the route materializes the whole archive in memory (chapter 10 §6 permits buffering); a streaming temp-file model for very large archives → Track streaming checkpoint export for very large archives #313.
• Pre-existing flake — test_loop_respawns_on_subprocess_crash (ideator subprocess, unrelated path) flakes under parallel load → Flaky: test_loop_respawns_on_subprocess_crash fails with BrokenPipeError under parallel pytest load #307. Did not recur in this PR's full-suite run.

Fresh-operator walkthrough

• Walkthrough performed against the changed operator surface (the checkpoint-export flow under Compose) via bash reference/compose/healthcheck/smoke-checkpoint.sh, which runs setup-experiment → full stack → quiescence → POST /v0/experiments/<id>/checkpoint → teardown+wipe → import on a fresh receiver.
• Notes: passed cleanly. The new assertion confirms the operator-visible payload is now correct — repo.bundle OK: 3247 bytes, 3 variant refs (git bundle verify passes; ref set carries refs/heads/main + one variant/* per integrated variant), then the import round-trips wire state. New flags documented in reference/services/task-store-server/README.md; the observability §2.9 operator gap ("empty git bundle under Compose") is replaced with the new posture.

Test plan

• python3 scripts/check-complexity.py — clean (0 blocking)
• uv run ruff check . — clean
• uv run pyright — 0 errors
• markdownlint (CI-pinned) — 0 errors
• full pre-push gate — all checks clean
• uv run pytest -q — 2355 passed, 254 skipped
• bash reference/compose/healthcheck/smoke-checkpoint.sh — PASS, with the new non-empty-bundle + git bundle verify + ref-set assertions (extended to close the smoke gap that let Checkpoint archives carry an empty git bundle under Compose (no --repo-path on task-store-server) #294 ship)
• bash reference/compose/healthcheck/smoke-auto-checkpoint.sh — PASS (asserts non-empty repo.bundle in every periodic + terminal archive)

Codex-review provenance

Impl-stage records under docs/plans/review/issue-294-checkpoint-bundle/impl/. Round 0: 3 blocking findings, all addressed (snapshot↔bundle race + late exported_at → §12 export-side self-validation + snapshot-instant stamping; silent bundle-failure → 503; format_version query unenforced → 400). Round 1: round-0 fixes verified; one stale-doc finding (README --shared-token) fixed.

Related issues

• Closes Checkpoint archives carry an empty git bundle under Compose (no --repo-path on task-store-server) #294 — Checkpoint archives carry an empty git bundle under Compose
• Refs Helm: wire the checkpoint-export repo (--repo-path/--forgejo-url) on the task-store-server #306, smoke-checkpoint: deepen post-import equality from counts/id-sets to full-object comparison #312, Track streaming checkpoint export for very large archives #313 — deferrals filed during this work
• Refs Automatic checkpointing (cadence + on-terminate; optional safety net) #131, Backfill: compose-smoke-checkpoint CI job (Phase 12b deferral) #152 — the auto-checkpointing / Phase-12b chunks that surfaced the gap

🤖 Generated with Claude Code