perf(covgate): pre-warm build cache before parallel coverage runs

[ben-miru]

What

Add a build-cache pre-warm pass to the covgate service so its parallel per-package coverage runs don't stampede the Go build cache.

Why

covgate fans out N parallel go test -coverpkg=<pkg> processes (N = effective parallelism, default runtime.NumCPU()). When they start together, each independently begins compiling the same shared dependency packages before any finishes populating ~/.cache/go-build — and Go does not lock build actions across separate go test processes. The result is a compile stampede that roughly doubles per-package wall time on heavy dependency graphs.

Proven downstream (the backend repo): inserting a single coherent go test -run='^$' compile pass before covgate cut its wall time from ~188s → ~44s. That was a CI-side stopgap; the fix belongs here, because covgate is what creates the stampede — and fixing it in the tool also speeds local runs (e.g. preflight), which suffer the same contention.

Key insight: the stampede is on the shared non-instrumented dependency compiles, not the per-package instrumented target (each run instruments only its own small, unique -coverpkg target — never a shared contention point). So a single plain compile pass is sufficient; the warm pass does not replicate per-package instrumentation.

How

• New prewarm func(testPaths []string) error seam on the runner struct (mirrors the existing goModule/goListPackages/measure seams), wired in Run() to a new gocover.PrewarmBuild, which runs one go test -run=^$ <paths...> (no -coverpkg/-coverprofile) and propagates any build error with combined output.
• collectWarmPaths(pkgs, ctx) reuses the same gocover.RelPkg + gocover.BuildTestPaths(...) calls checkPackage already uses — unioned and de-duplicated — so the warmed set exactly matches what the real runs build (no duplicated path logic).
• Inserted in (*runner).run after checkPackageCtx is built and before the start := time.Now() bracket, gated on parallelism > 1 && len(pkgs) > 1 (no concurrency ⇒ no stampede ⇒ no warm pass).
• Runs no tests (-run=^$), needs no DB/external services, and is excluded from the reported "Total time" (still measured only around runPackages), so covgate's output stays byte-identical.

Tests

• TestRun_Prewarm*: warm pass invoked once with the full package/test-path set when parallel + multi-package; skipped when serial or single-package; warm-pass build error propagated and measure never called.
• TestCollectWarmPaths_DeduplicatesSharedPaths; TestPrewarmBuild_Empty/_Success/_BuildError.
• Pre-existing parallel runner{} test literals given a no-op prewarm seam so the new gated call doesn't nil-panic (found all four, not just the obvious two).

Validation

• go build ./..., go vet ./..., repo lint (./scripts/lint.sh, custom stricter ruleset), gofumpt, and gopls modernize — all clean.
• go test ./internal/services/covgate/... ./internal/services/gocover/... — pass. covgate gate 100.0%, gocover gate 93.3% (.covgate floor bumped for the new code).

Out of scope / pre-existing: internal/services/lint shows a LOOSE covgate threshold (64.7% actual vs 63.6% floor). Verified present on main before this change and in a package this PR does not touch — left for a separate ratchet commit (./scripts/ratchet-covgates.sh).

Downstream follow-up

Once released, backend bumps its gotools dependency and removes its CI pre-warm stopgap (keeping only the unrelated cache-save-on-main fix). See backend PR #321.

🤖 Generated with Claude Code