feat(api): GET /api/v1/deployments/:id/events — failure timeline read surface

[mastermanas805]

Summary

• Adds GET /api/v1/deployments/:id/events — read-only failure-timeline endpoint.
• Closes the silent-deploy-failure gap from the 2026-05-30 swarm: GET /deployments/:id surfaces only the LATEST failure_autopsy row inside the optional failure field; agents debugging a stuck deploy need the full chronological timeline so they can distinguish a single OOM from a retry storm.
• Read-only — events are written by the worker (deploy_failure_autopsy + deploy_status_reconcile), never by the api.

Contract

GET /api/v1/deployments/:id/events?limit=50
Auth: Bearer token (same RBAC as GET /deployments/:id)
200 → { ok, deployment_id, events: [...], count }
400 → invalid_id          (empty id)
401 → unauthorized
404 → not_found           (unknown id OR cross-team)
503 → fetch_failed / events_query_failed

Per-row shape: { kind, reason, exit_code, event, last_lines, hint, created_at }. Ordered DESC by created_at. Default limit 50, hard cap 200, silent clamp. Cross-team returns 404 (NOT 403) — the platform never confirms the existence of deployments owned by another team.

Rule 22 surface checklist

• api/internal/handlers/openapi.go — new path entry + DeploymentEventsResponse + DeploymentEvent schemas. TestOpenAPI_CoversAllRegisteredRoutes still green.
• content/llms.txt — lives in a sibling repo (instanodedev/content, per memory project_repo_topology). Follow-up TODO: add a one-line entry to content/llms.txt listing the new endpoint so the public agent reference stays in sync.
• Dashboard surface: no UI change in this PR — FailureTimeline panel is a separate workstream the dashboard team can land on top.

Rule 25 observability

• instant_deploy_events_query_total{result} Prom counter — result ∈ {ok, not_found, invalid, error}. Incremented on every code path.
• Follow-up (infra repo): alert deploy events query error rate — fires when rate(instant_deploy_events_query_total{result=\"error\"}[10m]) / rate(instant_deploy_events_query_total[10m]) > 5%. Plus dashboard tile on instanode-reliability.json and the row in infra/observability/METRICS-CATALOG.md. Tracked here because the infra repo is a separate review surface.

Rule 17 coverage block

Symptom:        no read API for deployment_events autopsy rows
Enumeration:    rg -F 'deployment_events' internal/handlers (read paths)
Sites found:    1 (deploymentToMapWithDB → latest autopsy only)
Sites touched:  +1 (new Events handler, separate read path; existing
                failure-field read path preserved verbatim)
Coverage test:  TestOpenAPI_CoversAllRegisteredRoutes guards a future
                /deployments/:id/* route landing without an OpenAPI entry
Live verified:  awaiting post-merge SHA verify on api.instanode.dev
                per rule 14

Test plan

• go build ./... clean
• go vet ./... clean
• go test ./internal/handlers/ -run 'TestDeployEvents_|TestOpenAPI' -count=1 → PASS
• go test ./internal/models/ -run 'TestGetDeploymentEvents|TestDeploymentEventsListConstants' -count=1 → PASS
• go test ./internal/handlers/ -run 'TestDeploy' -count=1 (regression) → PASS
• Post-merge: rule 14 SHA verify — curl https://api.instanode.dev/healthz | jq .commit_id must equal git rev-parse --short HEAD
• Post-merge: live curl -H "Authorization: Bearer ..." https://api.instanode.dev/api/v1/deployments/<id>/events on a failed deploy returns the autopsy row

Test coverage (8 model + 7 handler tests)

Model (sqlmock):

• TestGetDeploymentEvents_LimitClamp — default + max + verbatim
• TestGetDeploymentEvents_EmptyResult
• TestGetDeploymentEvents_HappyPath_OrderingPreserved
• TestGetDeploymentEvents_CorruptJSONB_Recovers
• TestGetDeploymentEvents_QueryError
• TestGetDeploymentEvents_ScanError
• TestGetDeploymentEvents_RowsErr
• TestDeploymentEventsListConstants_AreSane

Handler (live Fiber test app + real Postgres):

• TestDeployEvents_HappyPath_OrderingAndShape
• TestDeployEvents_Empty_ReturnsZeroCountWithEmptyArray
• TestDeployEvents_CrossTeam_Returns404
• TestDeployEvents_UnknownID_Returns404
• TestDeployEvents_LimitClamp_AboveMaxReturnsAtMost200
• TestDeployEvents_Unauthenticated_Returns401
• TestDeployEvents_InvalidLimit_FallsBackToDefault

Anti-goals (deliberately not in scope)

• No autopsy creation / event writes — the worker owns that path (sibling PRs in instanodedev/worker from agents A + B in the swarm).
• No dashboard FailureTimeline UI — separate workstream.
• No content/llms.txt edit — sibling repo, follow-up.
• No infra alert JSON — sibling repo, follow-up.

🤖 Generated with Claude Code