[codex] Add client failure reporting and visible surfacing

[anantham]

Summary

This PR closes the immediate silent-failure gaps in the reader and lays down the first client telemetry path for production debugging. It makes known and unexpected translation failures visible to users, records the failure type at the store boundary, and adds a Vercel callback proof for best-effort client telemetry.

Root Cause

Translation failures could disappear in production because three paths were incomplete:

• the shared trial banner visibility check was inverted, so trial users could miss the banner entirely
• store-backed notifications were written but never rendered
• auto-translate fired a promise without a catch path, so unexpected failures could look like a hang instead of a surfaced error

A post-review regression surfaced at the async boundary:

• MainApp assumed handleTranslate() always returned a thenable and chained .catch() directly
• the integration test exposed that sync or mock implementations returning undefined broke that assumption

Changes

• MainApp.tsx: mount NotificationToast once at the app root, catch unexpected auto-translate failures, and normalize the handleTranslate() boundary through Promise.resolve().then(...)
• components/DefaultKeyBanner.tsx: fix shared-trial banner visibility and emit visible render telemetry
• components/NotificationToast.tsx: add the missing notification renderer
• components/ChapterView.tsx and components/chapter/ChapterContent.tsx: carry error telemetry into the reader surface and emit ui_error_rendered
• services/clientTelemetry.ts and types/telemetry.ts: add the v1 client telemetry contract, redacting transport, and callback/analytics routing
• services/telemetryService.ts: forward early boot errors, uncaught exceptions, and unhandled rejections into the client telemetry path
• services/ai/apiKeyValidation.ts, services/translationService.ts, store/slices/translationsSlice.ts, store/slices/uiSlice.ts, store/slices/chaptersSlice.ts: classify translation failures and propagate structured telemetry metadata through the store
• api/client-telemetry.js: add the Vercel callback proof handler
• tests/store/appScreen.integration.test.tsx: align the mocked handleTranslate() contract with the async store API
• Rebased branch onto current main to pick up ff5d821 and 54d4279
• tests + docs: add regression coverage and document deployed callback verification plus post-review verification notes

Testing

• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vitest run tests/store/appScreen.integration.test.tsx
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vitest run tests/db/migrations/fresh-install.test.ts
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vitest run tests/services/navigationService.test.ts
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vitest run tests/components/NotificationToast.test.tsx tests/components/DefaultKeyBanner.test.tsx tests/components/chapter/ChapterContent.test.tsx tests/current-system/translation.test.ts tests/services/clientTelemetry.test.ts tests/services/api-key-validation.test.ts tests/api/client-telemetry.test.ts
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vitest run tests/smoke/critical-components.smoke.test.tsx
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npm run build
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vercel build
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vercel curl /api/client-telemetry --deployment https://codex-telemetry-fa9kmjyhm-adityas-projects-9c03351d.vercel.app
• export PATH="$HOME/.nvm/versions/node/v22.17.0/bin:$PATH" && npx vercel curl /api/client-telemetry --deployment https://codex-telemetry-fa9kmjyhm-adityas-projects-9c03351d.vercel.app -- --request POST --header 'content-type: application/json' --data '{"event_type":"translation_failed"}'
• Mixed-suite note: the large combined Vitest command still produced timeout-shaped failures in appScreen.integration and the smoke import, but both files passed immediately in isolated reruns after rebase. fresh-install and navigationService were green in the combined run, confirming the original branch-skew failures are resolved.

Review Checklist

• Non-trivial change stays on feature branch fix/codex-telemetry-ux
• Diff is scoped to the telemetry/visibility slice plus the post-review async-boundary fix
• No vercel.json rewrite change was made because the deployed proof showed /api/client-telemetry is not shadowed by the SPA rewrite
• Branch is rebased onto current main
• Ready for Codex review

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lexicon-forge	Ready	Preview, Comment	Apr 3, 2026 1:51am