fix(audio): defer capture rebuilds during route changes

[kitlangton]

Summary

• keep Fast Mode warm-buffer behavior unchanged during ordinary idle and repeated dictation
• when Core Audio route events occur, clear stale pre-roll and defer capture-engine rebuilds until the next explicit warm-up or recording request
• avoid eager AVAudioEngine teardown/recreation while AirPods handoff or Bluetooth profile changes may still be dispatching Core Audio callbacks
• release fallback AVAudioRecorder instances after export instead of re-priming them while idle
• keep standard-mode capture startup on demand after environment changes

Why

Issue #226 includes an AirPods handoff crash where an AVAudioIOUnit property callback races AVAudioEngine deallocation. This is a containment patch: it narrows teardown timing risk without disabling Fast Mode or changing its normal low-latency path.

Verification

• git diff --check
• cd HexCore && swift test
• xcodebuild -scheme Hex -configuration Debug build

Follow-up

This does not claim to fully solve Bluetooth A2DP-to-HFP stabilization. A later PR should add explicit capture outcomes and generation-scoped callback handling so route interruptions are surfaced rather than silently producing invalid audio.

Stack

Depends on #235.

Stack

1. fix: harden microphone and recording reliability #235
2. fix(audio): defer capture rebuilds during route changes #236 👈 current

Summary by CodeRabbit

• New Features

  • Fast Mode capture rebuilds now defer until audio route changes finish settling, improving handling of audio input/output switches.

• Bug Fixes

  • Enhanced stability when connecting/disconnecting audio devices or switching system audio routes.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR refactors capture-environment event handling in RecordingClientLive to defer capture-engine restarts in super-fast mode until audio-route changes settle. The forceRestart parameter is removed, restart decisions centralize through deferred state (captureControllerNeedsRestartReason), and all system observers (wake, device, hardware) enqueue non-forcing changes. A new ensureCaptureControllerReadyAfterDeferredRestart helper applies deferred restarts at recording start and warm-up. Fallback stop is simplified to always attempt duplicate + release.

Changes

Deferred Capture Restart Flow

Layer / File(s)	Summary
Environment-change handler refactoring Hex/Clients/RecordingClient.swift	Removes forceRestart parameter; enqueueCaptureEnvironmentChange debounces and calls the updated handleCaptureEnvironmentChange(reason:). Handler now decides whether to defer rebuild (super-fast mode: set captureControllerNeedsRestartReason, clear warm buffer, release recorder) or apply immediately (standard mode: adjust inputs, stop/release).
Deferred restart support infrastructure Hex/Clients/RecordingClient.swift, Hex/Clients/SuperFastCaptureController.swift	New ensureCaptureControllerReadyAfterDeferredRestart(for:reason:) helper applies deferred restarts by checking and clearing captureControllerNeedsRestartReason. New clearWarmBuffer() method on SuperFastCaptureController synchronously clears ring buffer when no recording is active.
Observer callback updates Hex/Clients/RecordingClient.swift	Capture engine configuration changes, wake/screen-wake events, AV device connect/disconnect, and CoreAudio hardware property observers all enqueue environment changes using simplified signature (no force restart).
Recording start and warm-up integration Hex/Clients/RecordingClient.swift	startRecording and warmUpRecorder now arm capture controller via ensureCaptureControllerReadyAfterDeferredRestart instead of direct call, so restart decisions incorporate deferred-restart state.
Fallback stop path simplification Hex/Clients/RecordingClient.swift	Recorder fallback stop logic no longer conditionally primes recorder based on copy success; always attempts to duplicate current recording (best-effort) then immediately releases recorder with fallback-stop reason.
Release notes .changeset/4dca4969.md	Patch release entry: Fast Mode capture rebuilds are deferred until audio route changes settle.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• kitlangton/Hex#235: Both PRs modify Hex/Clients/RecordingClient.swift's recording lifecycle to handle deferred capture restart more reliably—this PR introduces the deferred environment-change restart flow via super-fast restart state, while the related PR hardens fallback stop/cleanup to flush that deferred restart path.

Poem

🐰 A capture's dance, now swift and sure,
Defers its rebuild, lets changes endure,
No forced restart blocks the way,
Warm buffers clear, recorders play.
Audio routes may shift and bend,
But captures flow from start to end. 🎙️

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(audio): defer capture rebuilds during route changes' directly summarizes the main change: deferring capture-engine rebuilds when audio routes change, which is the central objective across all three modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/audio-route-containment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/4dca4969.md:
- Line 5: Append the GitHub issue/PR reference to the changeset summary line
"Defer Fast Mode capture rebuilds until audio route changes settle" by appending
the tracking token in the required format, e.g. " (`#236`)" so the fragment
matches release-note conventions and includes the user-facing impact plus the
PR/issue number in parentheses.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1408268c-af43-42b6-8ed0-8724cad4767c

📥 Commits

Reviewing files that changed from the base of the PR and between c00a91d and 0ec8b73.

📒 Files selected for processing (3)

• .changeset/4dca4969.md
• Hex/Clients/RecordingClient.swift
• Hex/Clients/SuperFastCaptureController.swift

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add PR/issue reference to the changeset summary.

Please append the tracking reference in the required format, e.g. (#236), so this fragment matches release-note conventions.

Suggested edit

-Defer Fast Mode capture rebuilds until audio route changes settle
+Defer Fast Mode capture rebuilds until audio route changes settle (`#236`)

As per coding guidelines: “Include user-facing impact and GitHub issue/PR number in the format 'Improve Fn hotkey stability (#89)'.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	Defer Fast Mode capture rebuilds until audio route changes settle
	Defer Fast Mode capture rebuilds until audio route changes settle (`#236`)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.changeset/4dca4969.md at line 5, Append the GitHub issue/PR reference to
the changeset summary line "Defer Fast Mode capture rebuilds until audio route
changes settle" by appending the tracking token in the required format, e.g. "
(`#236`)" so the fragment matches release-note conventions and includes the
user-facing impact plus the PR/issue number in parentheses.