FE-1656: Add a rerunnable Voice end-to-end harness

[kostandinang]

🌟 What is the purpose of this PR?

Make Petrinaut Voice regressions reproducible with synthetic speech through the real Chrome → Realtime → Flue → Brunch path. Local helper and provider-free checks pass; the live sweep remains unverified. This harness does not establish naturalness, first-audible latency, or human acceptance.

🔗 Related links

• FE-1656: Add a rerunnable Voice end-to-end harness (internal)
• Parent PR: FE-1654: Test Realtime rephrasing of completed Brunch responses #9638; this PR targets ka/realtime-voice-rephrasing.

🚫 Blocked by

• Parent PR FE-1654: Test Realtime rephrasing of completed Brunch responses #9638 before landing on main.
• macOS-generated WAV fixtures and paid-run approval for the six-scenario sweep.
• Live trace, screenshot, and listening review. No paid calls or live scenario passes are claimed.

🔍 What does this change?

• Add an on-demand harness for clarification, long analysis without model changes, interruption, queued follow-up, hesitant speech, and a one-word answer.
• Record trace, WebM audio, screenshots, and deterministic verdicts; latency budgets warn only.
• Add pure helper tests, setup documentation, and a proof pointer in the existing mission. No product source changes.

🏗️ Agent notes

• Imperative: Make Voice regressions reproducible with repeatable synthetic-speech scenarios.
• Throughline: Chrome fake microphone → Realtime → Flue → Brunch → Realtime paraphrase → recorded remote audio.
• Proof: PCM and trace-check tests, provider-free connection-failure capture, and WebRTC loopback pass. A real six-scenario sweep with artifact inspection remains outstanding.
• Constraints: No product source changes; no raw provider payloads, SDP, or credentials in evidence; browser runs are paid, on-demand, and never CI. The $5 aggregate ceiling requires external spend tracking.
• Fog-line: Real fake-audio timing, queued-turn behavior, interruption timing, and acoustic results remain unverified.
• Stop or reorient: Do not infer live success from mocked or loopback checks; obtain the fixtures and paid approval before running the sweep.

See apps/petrinaut-website/scripts/voice-e2e/README.md for selectors, timing choices, artifact layout, setup traps, and verification limits.

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

The new voice:e2e command is deliberately outside CI; pure tests use the existing unit-test task.

⚠️ Known issues

The live sweep is pending. Recording duration is not proof of audible speech, diagnostic coverage cannot prove the absence of uninstrumented output, and dollar spend must be tracked externally. Latency budgets remain warn-only until three baseline sweeps exist.

🐾 Next steps

Complete the blocked live sweep and record per-scenario observations before requesting readiness. Human naturalness and acceptance assessment remain separate from this harness.

🛡 What tests cover this?

• synthesize-utterance.test.ts and trace-checks.test.ts: 34 tests passed, covering PCM validation, capture silence, and missing, reordered, interrupted, and rejected turns.
• Local website build, unit tests, typecheck, and lint passed; separate harness typechecks, lint, and formatting passed.
• Provider-free WebRTC loopback recorded remote audio. A blocked connection retained failure artifacts and correctly failed; neither establishes the live path.

❓ How to test this?

1. Run yarn workspace @apps/petrinaut-website exec vitest run scripts/voice-e2e/synthesize-utterance.test.ts scripts/voice-e2e/trace-checks.test.ts and confirm all 34 tests pass, including invalid PCM and incomplete or reordered traces.
2. With disposable local Brunch and website services configured per the harness README, provide macOS WAV fixtures and obtain paid-run approval, then run VOICE_E2E_APPROVED=true yarn workspace @apps/petrinaut-website voice:e2e.
3. Inspect each trace and screenshot, listen to each WebM, and compare the scenario verdicts with the canonical text. Steps 2–3 have not yet been performed.

📹 Demo

No live demo yet. The six-scenario audio and screenshot evidence is pending the blockers above.

[vercel]

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

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 10, 2026 10:28pm UTC
petrinaut	Ready	Preview	Sep 10, 2026 10:28pm UTC
petrinaut-docs	Ready	Preview	Sep 10, 2026 10:28pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 10, 2026 10:28pm UTC

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ kostandinang
❌ ampagent
_{You have signed the CLA already but the status is still pending? Let us recheck it.}