fix: gate recording on mic liveness so AirPods stop losing the first words

[claude]

Requested by Dylan Fox · Slack thread

What & why

Before: on AirPods (any Bluetooth mic), the pill and the start chime appear the instant the hotkey is pressed — but the device takes ~1–2 s to switch its audio profile (A2DP→HFP) before the mic actually delivers anything, and macOS drops back to A2DP after every idle gap. So on the first dictation and every dictation after a pause, the user is cued to speak while nothing is being captured, and the first words of the utterance are missing from the transcript.

After: the pill still appears immediately on key-down, but in a distinct "Connecting…" warming-up state (no REC tag, no waveform). It flips to the normal recording state — and the start chime plays — only once the mic is actually delivering audio. On wired/built-in mics the warming state is a blink (audio flows near-instantly); on AirPods the chime now arrives when it's true. The trade-off is deliberate: the cue is honest, not early. Speech during the switch is not recovered — the OS never receives any audio while the profile switch is in flight, so nothing can capture it; the fix is to stop inviting the user to speak into that dead window.

How: MicCapture.start() no longer trusts AVAudioRecorder.record() returning true (that only means the AudioQueue started). It now polls recorder.currentTime every 50 ms until it advances past 0 — the recorder's clock only moves once the input device delivers frames, which distinguishes "route still switching" from "user is silent" (a level meter can't). The wait is capped per transport via CoreAudio's kAudioDevicePropertyTransportType: ~2.5 s for Bluetooth/BluetoothLE, ~300 ms for everything else, and on timeout it fails open (proceeds exactly as today) so a silent or broken mic can't brick the press. The cap policy and poll loop live in a new pure MicLiveness enum (unit-tested against the injected TestClock); the gap is logged so the fix is measurable in the field. DictationSession surfaces the wait as a new non-terminal .connecting phase claimed before mic.start(), projected to a new OverlayUIState.connecting (breathing "Connecting…" status line) while the menu bar stays at rest; RecordingCueGate needed no change — it keys on .recording, so the start chime now rides the connecting→recording edge by construction. A release or cancel landing mid-bring-up queues behind the press on the session's serial command queue and finalizes/tears down cleanly (pinned by a new GatedStartMic test); warmUp() is untouched and still starts no capture.

How it was tested

• scripts/check.sh passes (or CI will, if I'm not on a Mac) — scripts/check.sh --portable passes locally; Swift build/tests need CI's macOS runner
• I read AGENTS.md and this doesn't reintroduce anything deliberately removed (stays on the per-session AVAudioRecorder; no AVAudioEngine, no capture outside a press)
• Docs updated if behavior changed (AGENTS.md, BLURTENGINE.md phase diagram + MicCapture contract)

New/updated engine tests: MicLivenessTests (transport caps, immediate/delayed/timeout waits on TestClock), DictationSessionTests (idle → connecting → recording sequencing; release landed during the bring-up still finalizes cleanly), RecordingCueGateTests (no chime during .connecting or on a failed bring-up), plus the .connecting rows in the PipelinePhase/OverlayUIState/MenuBarStatus projection tables.

Worth a real-device pass on AirPods before merging: dictate, wait ~10 s (so macOS falls back to A2DP), dictate again — the chime should land ~1–2 s after key-down and the first words should survive.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CNFeP9D8k1HJ1piwyidUv3

---

Generated by Claude Code

[github-actions]

Dev build

Download Blurt.app — built from 6f91766, Debug-Local,
ad-hoc signed. Expires in 14 days.

Installing it

cd ~/Downloads
unzip -o blurt-dev-build-pr-134.zip   # GitHub wraps every artifact in a zip
unzip -o Blurt-dev-6f91766.zip
find Blurt.app -exec xattr -c {} +   # clear quarantine: xattr lost -r in macOS 12.3
rm -rf /Applications/Blurt.app && cp -R Blurt.app /Applications/
open -a Blurt

It is ad-hoc signed and not notarized: Gatekeeper refuses to open it until
the quarantine flag is cleared, and macOS treats it as a different app from a
released Blurt, so you have to re-grant Microphone, Accessibility, and Input
Monitoring. Reinstall the release DMG
when you are done reviewing.

Expect that re-grant once per dev build, including a second build of this
same PR. TCC pins an Accessibility grant to the signature that took it, and an
ad-hoc signature is just a hash of the binary, so every build is a new app as far
as tccd is concerned. Blurt clears the orphaned grant at launch, which is what
keeps the Accessibility step from getting stuck on a Blurt row that is switched on
and still denied. If you are coming from a build old enough to predate that,
clear the grant yourself once:

tccutil reset Accessibility dev.alex.blurt

[alexkroman]

Closing in favour of #133, which now carries this PR's liveness gate plus four fixes for the same report that this one doesn't cover.

This PR had the key insight and #133 didn't. record() returning true only means the AudioQueue started, not that frames are arriving — so polling recorder.currentTime until it advances is the right signal, and it's the only thing here that actually saves the first words of an utterance. #133 was independently addressing the same Slack report from a different angle and had it wrong on one point: it moved the start chime to the press, which pushes the "speak now" cue even earlier into the dead window. That's reverted, and this PR's ordering (chime rides the connecting→recording edge) is what shipped.

Carried over from here essentially as written:

• MicLiveness — the poll loop and the per-transport wait caps (2.5 s Bluetooth / 300 ms otherwise), failing open on timeout, with its TestClock-driven tests
• stopGeneration, covering the suspension the wait introduces
• The .connecting phase and its projections, and the Duration.milliseconds hoist out of AssemblyAITranscriber

What #133 adds on top, none of which this PR touches:

• The tail. stop() keeps capturing 220 ms past key-up on a Bluetooth input, so the last word isn't truncated by the link's buffering. This PR fixes the head of the utterance; the tail was the other half of the same complaint.
• A per-session recorder re-warm. The profile switch is paid at prepareToRecord(), i.e. every dictation, and warmUp() only ever covered the first one. Re-arming after each capture keeps the route open, so the honest wait this PR introduces usually returns immediately instead of costing 1–2 s. The two compose: the re-warm makes it fast, the gate makes it correct. (Bounded by a 60 s expiry, since holding the input open is what pins AirPods in the degraded-output profile.)
• cancelCapture(), so a cancel skips both the tail linger and the file read-back rather than paying them to preserve audio it's about to discard.
• Cue re-priming on output-route changes. Opening the mic drops the format the chime players were pre-rolled against, so the first chime after the flip is the one that stalls — and that's the chime at the start of a dictation.

The Slack request this came from is being served, not dropped — #133 is where it landed, and it keeps the real-device checklist from this PR's description (dictate, wait ~10 s for the link to fall back, dictate again).

Thanks — the gate was the right call and it's the core of the merged version.

---

Generated by Claude Code