Align API error envelopes

docs/CODEX_EXECUTION_LOG.md

@@ -2349,3 +2349,33 @@ Limitations:
 
 Next recommended pass:
 - Run a backend error-envelope audit for expected user-error paths.
+
+## Sprint 60 API error-envelope contract hardening (2026-06-18)
+
+Changed:
+- Audited the backend error payload shape against `docs/API_CONTRACTS.md`.
+- Changed central FastAPI error serialization to return top-level `error`, `message`, `details` and `request_id` fields.
+- Preserved HTTPException detail dict support for future explicit error codes.
+- Updated the frontend API client to parse the canonical top-level error contract while remaining tolerant of the older nested `error.code/message/details` shape.
+- Added regression tests for AppError, HTTPException and validation-error envelopes.
+- Updated provider-registry error assertions to the canonical top-level schema.
+- Added static frontend parser coverage for canonical and legacy error payloads.
+- Updated `docs/TODO.md` and `CHANGELOG.md`.
+
+Tested:
+- `cd backend && python -m pytest tests/test_error_envelope_contract.py tests/test_sprint7b_provider_registry.py::test_provider_api_envelopes_and_invalid_provider -q` (`4 passed`)
+- `python -m compileall backend/app`
+- `cd frontend && npm run typecheck`
+- `cd backend && python -m pytest -q` (`224 passed`)
+- `cd frontend && npm run build`
+- `cd backend && python -m pytest tests/test_error_envelope_contract.py tests/test_frontend_api_client_error_parser.py tests/test_sprint7b_provider_registry.py::test_provider_api_envelopes_and_invalid_provider -q` (`6 passed`)
+- `bash scripts/run_readiness_check.sh` (`226 passed`)
+
+Open:
+- Deploy Tower and verify a live expected-error response on the browser-facing API.
+
+Limitations:
+- This pass changes only the centralized response envelope and frontend parser. It does not rename route-level error codes or change product behavior.
+
+Next recommended pass:
+- Expand golden datasets beyond the current building QA fixtures.

docs/TODO.md

@@ -59,7 +59,7 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Demo workflow orchestration hook decomposition.
 - [x] Final `App.tsx` import/encoding cleanup and size audit.
 - [x] Optional final bootstrap-effect extraction.
-- [ ] Decide next V1 stabilization focus: backend error-envelope audit or golden dataset expansion.
+- [ ] Decide next V1 stabilization focus: golden dataset expansion or frontend visual polish backlog.
 
 ## Sprint 8 status
 
@@ -329,4 +329,5 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Add a safe export retention/cleanup command for demo environments.
 - [x] Add a live dry-run maintenance smoke for demo export cleanup.
 - [x] Add browser screenshot artifact automation for visual regression handoff.
-- [ ] Add backend error-envelope audit for expected user-error paths.
+- [x] Add backend error-envelope audit for expected user-error paths.
+- [ ] Expand golden datasets beyond building QA fixtures.