ROADMAP-25 — P3 — Prometheus /metrics endpoint and stuck-run reaper #117

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M17-T04 · Priority: P3 · Effort: medium

Problem

Observability is logging-only. No /metrics, no OpenTelemetry, no CORS middleware; ratelimit.py is a ready hook point and records nothing. Also, the stuck-run reaper (crash mid-run ⇒ rows stuck at running) has nothing like an updated_at heartbeat to even detect it.

Acceptance criteria

• Prometheus /metrics (unauthenticated or admin-scoped per deployment choice, documented): runs by status, step latency, rate-limiter trips, provider errors, in-flight runs
• Reaper: orphaned running rows transitioned to failed past a heartbeat threshold (pairs with ROADMAP-10's lifespan scope; standalone variant acceptable)
• Optional OTel export documented in docs/DEPLOY.md (dependency-gated so the default install stays light)
• Compose/dev docs updated

Suggested branch / commit

feat/prometheus-metrics · feat(api): Prometheus metrics and stuck-run reaper