[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 4, 2026 8:25pm

[anantham]

Code review

Note: This PR is still a draft. Review based on current state.

Found 3 issues:

1. translationsSlice.ts is now 1,168 LOC after adding the emitTranslationFailure telemetry helper (lines 85-157). This telemetry emission concern has a different change cadence from translation orchestration and meets the split criteria in CLAUDE.md: "The file has more than one reason to change" and all four friction signals are present (high surprise radius, bad locality, poor findability, weak testability). Consider extracting to services/translationTelemetry.ts. (CLAUDE.md says ">1000 LOC: Friction is likely -- investigate and propose a split if confirmed")

LexiconForge/store/slices/translationsSlice.ts

Lines 85 to 157 in 7900adb

	const emitTranslationFailure = ({
	chapterId,
	origin,
	provider,
	model,
	failureType,
	errorMessage,
	expected,
	}: {
	chapterId: string;
	origin: TranslationOrigin;
	provider: AppSettings['provider'];
	model: string;
	failureType: Extract<
	TelemetryFailureType,
	'trial_limit' | 'missing_api_key' | 'timeout' | 'provider_malformed_response' | 'unknown'
	>;
	errorMessage: string;
	expected: boolean;
	}): TelemetryErrorContext => {
	const sourceEventType = failureType === 'trial_limit' ? 'known_limit_reached' : 'translation_failed';
	clientTelemetry.emit({
	eventType: sourceEventType,
	failureType,
	surface: origin,
	severity: sourceEventType === 'known_limit_reached' || expected ? 'warning' : 'error',
	expected,
	userVisible: null,
	provider,
	model,
	chapterId,
	errorMessage,
	dedupeCallback: !expected,
	});
	return {
	sourceEventType,
	failureType,
	surface: origin,
	expected,
	provider,
	model,
	chapterId,
	};
	};
	export const createTranslationsSlice: StateCreator<
	any,
	[],
	[],
	TranslationsSlice
	> = (set, get) => ({
	// Initial state
	activeTranslations: {},
	pendingTranslations: new Set(),
	feedbackHistory: {},
	amendmentProposals: [],
	translationProgress: {},
	// Translation operations
	handleTranslate: async (chapterId, origin = 'manual_translate') => {
	const state = get();
	if (state.pendingTranslations.has(chapterId)) {
	debugLog('translation', 'summary', '[Retranslate] Already translating, ignoring click', { chapterId });
	return;
	}
	const context: TranslationContext = {
	chapters: (state as any).chapters || new Map(),
	settings: (state as any).settings,
	activePromptTemplate: (state as any).activePromptTemplate
	};

2. getBuildId() falls back to VERCEL_URL (a deployment URL like my-app-abc123.vercel.app) as a build identifier. This produces misleading telemetry -- every deployment gets a different "build_id" that looks like a URL, not a commit SHA. The fallback should be null, not a deployment URL.

LexiconForge/services/clientTelemetry.ts

Lines 104 to 107 in 7900adb

	const getBuildId = (): string | null => {
	const env = getRuntimeEnv();
	return env.VERCEL_GIT_COMMIT_SHA || env.VITE_APP_BUILD_ID || env.VERCEL_URL || null;
	};

3. In the auto-translate .catch() block, requestedRef.current.delete(currentChapterId) removes the deduplication guard that prevents re-triggering. On persistent failures (bad API key, network down), the next render cycle will re-trigger auto-translate since the guard was deleted, creating a retry loop. The pendingTranslations check in handleTranslate provides a secondary guard, but the ref deletion defeats the primary intent. Consider keeping the ref intact on error so the chapter is not re-requested with the same settings.

LexiconForge/MainApp.tsx

Lines 219 to 232 in 7900adb

	.catch((error) => {
	console.error('[AutoTranslate] Unexpected translation failure:', error);
	requestedRef.current.delete(currentChapterId);
	const store = useAppStore.getState();
	const message = error instanceof Error ? error.message : 'Unexpected translation failure';
	clientTelemetry.emit({
	eventType: 'translation_failed',
	failureType: 'unknown',
	surface: 'auto_translate',
	severity: 'error',
	expected: false,
	userVisible: null,
	provider: settings.provider,
	model: settings.model,

Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[anantham]

Follow-up pushed in 44de755 to address the two concrete review items only:

• services/clientTelemetry.ts: build_id no longer falls back to VERCEL_URL; it now resolves to VERCEL_GIT_COMMIT_SHA, VITE_APP_BUILD_ID, or null
• MainApp.tsx: the auto-translate catch path no longer clears requestedRef, so the same chapter/settings pair is not auto-requested again after an unexpected failure
• Added focused regression coverage in tests/services/clientTelemetry.test.ts and tests/store/appScreen.integration.test.tsx

The translationsSlice.ts size/splitting concern is valid, but I left that out of this PR to keep the fix scoped to the concrete behavioral bugs.