H-6763: Improve voice preview reliability diagnostics

[kostandinang]

🌟 What is the purpose of this PR?

This PR hardens the disabled-by-default OpenAI voice preview introduced by the lower H-6763 stack. It adds actionable, privacy-safe diagnostics and closes failure-handling gaps so developers can distinguish permission, device, network, timeout, abort, provider-response, transcription, and playback failures.

The scope is reliability and observability only. It does not enable production voice or add the authentication, distributed quotas, replay/recovery, completion, and projection contracts required for production use.

🔗 Related links

• H-6763: Support for realtime audio interviewing of domain experts (internal)
• #9357: Speak finalized Brunch responses with OpenAI — required parent PR
• ADR-0009: OpenAI voice UI turn shell

🚫 Blocked by

• #9357

🔍 What does this change?

• Defines a sanitized voice-error taxonomy covering microphone permission/device failures, aborted requests, network errors, timeouts, invalid responses, and unavailable preview endpoints.
• Adds validated UUID request correlation plus content-free timing diagnostics across browser connection/transcription/playback, website voice routes, and the existing Brunch inspection join.
• Adds valid Server-Timing metrics while explicitly excluding audio, SDP, transcripts, prompts, canonical speech, credentials, and provider response bodies from diagnostics.
• Makes startup and teardown deterministic across timeout, disconnect, stale-event, malformed-response, provider-error, and reconnect paths; aborts remain classified as request-aborted while SDP is read or applied.
• Prevents late answer delivery from overwriting active playback or a speech failure.
• Adds a fully local mocked boundary test spanning WebRTC setup, transcript delivery, the composer/Brunch boundary, canonical response selection, speech streaming, and playback.
• Updates the website README, Petrinaut user guide, ADR-0009, and Brunch steering documentation.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• Production voice remains disabled; this PR does not close the production gates recorded in ADR-0009.
• Verification uses local mocks and fixtures. No live microphone, OpenAI Realtime/Speech request, or configured remote Brunch conversation was exercised.
• Existing production-build chunk-size warnings are unchanged.

🐾 Next steps

• Land after H-6763: Speak finalized Brunch responses with OpenAI #9357 as part of the H-6763 stack.
• Address authentication, distributed quotas, replay/recovery, production telemetry, completion, and projection contracts before enabling production voice.
• Capture a credentialed browser witness separately from deterministic automated coverage.

🛡 What tests cover this?

• yarn workspace @apps/petrinaut-website test:unit — 17 files and 109 tests, including the mocked browser-to-playback boundary.
• yarn workspace @apps/petrinaut-website lint:tsc and lint:eslint — website type and lint coverage.
• Focused regressions cover startup, permission/device failures, network failures, request aborts, timeouts, malformed/provider responses, request-ID validation, teardown, reconnect/stale-event rejection, media cleanup, and late delivery races.
• Brunch app and transport unit suites cover the inspection join used by voice diagnostics.
• CI covers package builds, formatting, documentation, architecture checks, and Semgrep.

❓ How to test this?

1. Check out this branch with H-6763: Speak finalized Brunch responses with OpenAI #9357 beneath it.
2. Run yarn workspace @apps/petrinaut-website test:unit.
3. Run yarn workspace @apps/petrinaut-website lint:tsc and yarn workspace @apps/petrinaut-website lint:eslint.
4. Confirm the local integration test crosses the mocked browser → voice route → transcript → composer/Brunch → canonical speech → playback path.
5. Confirm serialized diagnostics contain request IDs, timing, stage, operation, and sanitized error codes, but none of the private fixture payloads.
6. Do not point tests at a remote Brunch endpoint or real OpenAI credentials without separate approval.

📹 Demo

Not included. This PR changes reliability, diagnostics, and automated coverage rather than the interaction design, and no credentialed external voice flow was run.

[vercel]

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

Project	Deployment	Actions	Updated
petrinaut	Ready	Preview	Sep 1, 2026 3:49pm UTC
petrinaut-docs	Ready	Preview	Sep 1, 2026 3:49pm UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
hash	Ignored	Preview	Sep 1, 2026 3:49pm UTC
hashdotdesign-tokens	Ignored	Preview	Sep 1, 2026 3:49pm UTC

[CLAassistant]

All committers have signed the CLA.

[kostandinang]

• H-6763: Integrate voice mode into the AI assistant #9467
• H-6763: Migrate voice interviews to GPT-Realtime-2 #9399
• H-6763: Add the voice interview experience #9380
• H-6763: Improve voice preview reliability diagnostics #9378 👈 (View in Graphite)
• H-6763: Speak finalized Brunch responses with OpenAI #9357
• H-6763: Add OpenAI Realtime voice input to Brunch #9356
• H-6763: Add a generic Petrinaut composer submission API #9355
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Merge activity

• Sep 1, 2:58 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.