feat(metrics): cut over /api/metrics/db to the collector + PR-env wiring (TECH-6484)

[chong-techops]

⚠️ Deployment sequence (read before merging)

This PR turns off the app's DB-metrics scrape. It is safe only after the dedicated collector (PR #1439) is live and confirmed scraping. Merging out of order creates a metrics gap.

Required order:

1. Merge feat(metrics): dedicated keeperhub-metrics-collector service (TECH-6484) #1439 → collector deploys to staging (app still serving db-metrics too — harmless overlap).
2. Verify in staging: the keeperhub-metrics-collector-…-db-metrics Prometheus target is Up with gauges matching /api/metrics/db.
3. Then merge this PR → app stops serving db-metrics; collector is the sole source → no gap.
4. Prod: promote the collector first (verify target Up in prod), then promote this cutover. Never ship both to prod in one promotion (same gap risk).

Principle: always overlap (two sources briefly, max() dedupes), never gap.

What

Cutover (Stage 4):

• app/api/metrics/db route → 404 when METRICS_DB_OFFLOADED=true (reversible via config).
• Remove the db-metrics ServiceMonitor from deploy/keeperhub/{staging,prod} and set METRICS_DB_OFFLOADED=true. /api/metrics/api unchanged.

PR-env wiring (Stage 5):

• deploy/pr-environment/metrics-collector.template.yaml + deploy-pr-environment.yaml deploy-pr-metrics opt-in label (build + deploy a PR collector). Default off — existing PR envs unaffected.
• METRICS_REFERENCE.md note.

Validation

• Type-check / biome clean; all changed YAML parses.
• The deploy-pr-metrics path was exercised end-to-end (throwaway combined PR): built a PR-sha collector image and deployed a real pod (/metrics 200). The deploy-pr-metrics label was created in the repo.
• Fixed a gap found during that run (a9076653): the metrics-only label (added to an already-deployed PR) now re-runs the deploy so the collector actually lands, mirroring deploy-pr-executor.

Depends on #1439 (image stage + deploy config).

[chong-techops]

PR-env wiring validated (with one gap found)

Exercised the deploy-pr-metrics path here via a throwaway combined branch (this PR's wiring + #1439's image stage), labeled deploy-pr-environment + deploy-pr-metrics:

• check-labels set should-deploy-collector=true, build-collector-image built + pushed a PR-sha image, and the deploy step rolled out a real metrics-pr-N-common collector pod (Running 1/1, /metrics 200). So the primary both-labels path works.
• Also created the deploy-pr-metrics label in the repo (it didn't exist - required for this to be usable).

Gap to fix: the incremental path - adding deploy-pr-metrics to an already-deployed PR (without re-adding deploy-pr-environment) - builds the collector image but does not deploy it, because the collector deploy step lives inside the should-deploy-gated deploy job (the metrics-only branch sets should-deploy-collector but not should-deploy). The fix is to make the collector deploy its own step gated only on should-deploy-collector (or have the metrics-only branch also set should-deploy). Low impact (the both-labels path is the common case), but the incremental label currently doesn't do what it implies.