Investigate and harden speech-to-text failure handling and diagnostics #243

Problem

Speech-to-text sometimes fails without enough visible or saved evidence to explain what happened. When dictation does not produce usable text, the user currently has too little information about whether the failure came from recording, permissions, local audio capture, network/API transport, Deepgram streaming, finalization, post-processing, or composer insertion.

This makes STT feel unreliable and hard to debug. We need to solidify the dictation pipeline so common edge cases are handled explicitly and every failure leaves actionable diagnostics.

Desired behavior

Dictation should either succeed or fail with a clear reason and enough debug context to investigate later.

Examples:

• microphone permission denied or device missing
• no audio / silence / too-short press
• recorder start/stop races
• pending audio chunks never flushed
• Deepgram websocket open/close failures
• Deepgram returns no transcript or partial-only transcript
• network interruption / auth failure / timeout
• final transcript exists but composer insertion fails
• post-processing/polish fails after raw transcript succeeded
• cancellation vs real failure is distinguishable

Investigation areas

Likely starting points:

• packages/agent-voice-dictation/src/speech/deepgram/streaming.ts
• src/main/ipc/dictation.ts
• src/main/dictationJournal.ts
• renderer dictation/composer integration and any saved dictation debug dumps

Check whether every phase emits structured debug events with correlation ids:

• press/start requested
• permission/device result
• recorder started
• audio chunks queued/sent
• stream opened
• transcript partial/final received
• stop requested
• flush/finalize completed
• result inserted into composer
• failure/cancel path completed

Acceptance criteria

• Add a clear phase model for dictation/STT so UI and debug logs agree on what happened.
• Every non-success path records a specific reason code and enough context to reproduce or categorize it.
• Silent failures become visible in the UI and saved diagnostics.
• Timeouts are explicit for websocket connect, first audio, final transcript, and composer insertion.
• Cancellation/short-press discard is separated from error failures.
• Add a focused regression or diagnostic harness for at least the highest-risk edge cases.
• Saved debug logs include enough dictation/STT context to diagnose failures after the fact.

Notes

This is separate from improving transcription accuracy with Deepgram keyterms/dictation context (#240). This issue is about reliability, lifecycle handling, and diagnostics when STT fails or produces no usable output.