bug(api-spec): OpenAPI spec missing response codes that endpoints actually return (501, 500, 400, 404)

[fireddd]

Bug

The generated OpenAPI spec (backend/internal/httpd/apispec/openapi.yaml) is missing several HTTP response codes that the controllers actually return. This causes generated SDK clients and API validators to reject valid daemon responses as unexpected.

Analyzed against: 96d1649 (current main)
Confidence: High — cross-referenced every controller handler's error paths against the spec operations in specgen/build.go.

Missing Response Declarations

1. Missing 501 on project endpoints

Controllers: backend/internal/httpd/controllers/projects.go — every handler (GET/POST /projects, GET/DELETE /projects/{id}, PUT /projects/{id}/config) returns 501 when c.Mgr == nil.

Spec: backend/internal/httpd/apispec/specgen/build.go lines 360-414 — project operations do not include http.StatusNotImplemented in their response lists.

2. Missing 501 on session endpoints

Controllers: backend/internal/httpd/controllers/sessions.go — list, get, spawn, kill, restore, rename, rollback, send, cleanup all return 501 when c.Svc == nil.

Spec: Session operations in build.go lines 416-588 are similarly missing 501.

3. Missing 500 on PR endpoints

Controller: backend/internal/httpd/controllers/prs.go:75 — writePRError falls through to 500 for unrecognized errors.

Spec: build.go lines 594-621 — mergePR and resolveComments don't declare 500.

4. Missing 400 on resolveComments

Controller: backend/internal/httpd/controllers/prs.go:50 — returns 400 for invalid JSON body.

Spec: resolveComments operation doesn't declare 400.

5. Missing 500 and 404 on review endpoints

Controller: backend/internal/httpd/controllers/reviews.go:104-113 — writeReviewError maps ErrNotFound → 404 and unknown errors → 500.

Spec: listReviews declares 200/422/501 but is missing 404 and 500. triggerReview and submitReview are also missing 500.

Reproduction

# Example: project endpoint returning undeclared 501
# Build daemon without project manager wired
curl http://127.0.0.1:3001/api/v1/projects
# Returns 501 — not in spec

# Example: PR endpoint returning undeclared 500
# Send request that triggers unexpected error
curl -X POST http://127.0.0.1:3001/api/v1/prs/abc/merge
# If service throws unexpected error → 500 — not in spec

# Example: resolveComments returning undeclared 400
curl -X POST http://127.0.0.1:3001/api/v1/prs/1/resolve-comments -d 'not json'
# Returns 400 — not in spec

Impact

• Generated TypeScript client (frontend/src/api/schema.ts) doesn't type these error responses
• API validators/mocking tools reject valid responses
• SDK consumers can't discriminate between "not implemented" (501) and "server error" (500)

Suggested Fix

Add the missing status codes to each operation's response list in backend/internal/httpd/apispec/specgen/build.go, then regenerate:

npm run api

The drift tests (go test ./internal/httpd/... and the api-drift CI job) will then enforce the updated spec.