fix(study): the Speak sheet reports why a listen failed instead of closing

[jvsena42]

The bug

The Speak sheet sometimes closed without showing a success or an error.

StudySessionViewModel.onSpeechError() mapped every recognition failure to SpeakPhase.Idle, and on Android the common failures are ordinary rather than exceptional — ERROR_NO_MATCH, ERROR_SPEECH_TIMEOUT, and the engine still busy on a fast Try again. From the reader's side a sheet that closes on its own is indistinguishable from the app having missed the tap.

Driving it on the emulator turned up two more silent paths in the same flow:

• A listen the engine never finishes. The recognition service reports onReadyForSpeech and onBeginningOfSpeech, then returns neither a result nor an error. Nothing else ends the flow, so the sheet sits on "Say the word" for good.
• Every API 33 error code fell into UNKNOWN — including ERROR_LANGUAGE_NOT_SUPPORTED, which is exactly what a deck declaring a language the device has no model for looks like. It closed the sheet like all the others.

The fix

The reason travels instead of being thrown away. SpeechEvent.Error carries its SpeechError through to a new SpeakPhase.Failed, which says which failure it was and offers Try again — or a Close, for the two nothing can retry (a refused permission, a missing language model).

Around that:

• A retry joins the previous listen before starting one. The old recognizer is destroyed in the flow's awaitClose, so cancelling without joining let a fast Try again create a second one first — answered with ERROR_RECOGNIZER_BUSY, which closed the sheet.
• One listen is capped, with a stopListening grace first so a slow-but-working engine still delivers. A pronunciation attempt is a word or a short phrase; the cap cannot truncate a real one.
• A final result and an error can both arrive on some engines; whichever lands first is now the attempt's outcome, so "didn't catch that" can't overwrite a graded result.
• A late error is dropped exactly as a late transcript is, so nothing reopens a sheet the reader has moved on from.
• A refused microphone permission is a dismissal, not a failed listen: nothing was started.

iOS had the same silent close, and additionally collapsed every recognition error into .noMatch — so its alert for permission and unavailability never fired for the case that actually happens. It now reports through the same shared phase, which retires the separate alert: one place a Speak outcome is shown, on both platforms.

SpeechError gains LanguageUnavailable, and its entries become PascalCase like every other enum that crosses to Swift here — Kotlin exports them lowercased with the separators dropped, so a SCREAMING_SNAKE entry would cross under a name nothing in the repo can predict.

Verification

./gradlew :shared:jvmTest detektAll :composeApp:assembleDebug — green. Four new StudySessionViewModelTest cases cover the reported phase, the retry target, the non-retryable failure and the late-error guard.

Driven on emulator-5554 against the real homeserver ("Spanish basics", es-ES → en-US, Speak on) — journeys/09-speak-study.xml re-run, with the outcome and three new steps recorded in journeys/RESULTS.md:

Step	Result
Speak → rationale → RECORD_AUDIO grant	PASSED — unchanged
Say nothing, wait	PASSED — "Didn't catch that" with the reason and Try again. It used to hang on "Say the word" for good
Try again from the failure sheet	PASSED — straight back to Listening, no ERROR_RECOGNIZER_BUSY
Dismiss	PASSED — back to the card

Still manual on a device with Google speech: the Correct/Wrong outcome and which language each engine uses. The iOS half is written to match but is unverified — no macOS in this session, and xcodebuildmcp failed to connect.

🤖 Generated with Claude Code

https://claude.ai/code/session_0116NZ92Pe7aGQpqtiRkP4Ye