Preserve macOS app permissions via dynamic launcher, .env workspace path, and session/audio tools

2026-08-11 21:15:37 -04:00
parent 583131221c
commit b5034b4b16
17 changed files with 1888 additions and 68 deletions
@@ -70,6 +70,41 @@ terminal under System Settings → Privacy & Security → Microphone.

 The speech model downloads itself the first time a locale is used.

+## macOS AirPods route switching checklist
+
+When no audio device is pinned, VoiceAgent follows macOS's current default
+microphone and speaker while a conversation is running. Use this checklist when
+validating AirPods or another Bluetooth headset:
+
+1. Connect AirPods before starting `./talk`; confirm that both microphone and
+   speaker audio use them.
+2. Start a conversation on the built-in microphone and speakers, then connect
+   AirPods. Confirm that each available direction moves independently to the
+   new macOS default without ending the conversation.
+3. Disconnect AirPods during a conversation. Confirm that the available input
+   and output return to the macOS defaults and that the conversation remains
+   usable.
+4. In Control Center or Sound settings, explicitly switch back to the built-in
+   microphone and speakers while AirPods remain connected. Confirm both routes
+   follow those defaults.
+5. Repeat connect, disconnect, and manual default changes several times to
+   catch delayed Bluetooth profile changes or a stale route listener.
+
+Run this validation without `--input-device` or `--output-device`: omitted
+values intentionally follow macOS defaults. Supplying either flag pins only that
+direction (for example, a pinned USB microphone still allows an unpinned output
+to follow AirPods); pinning both directions disables automatic route following.
+Use `./talk --list-devices` to identify a device by index or name substring.
+
+This behavior depends on macOS Core Audio notifications and the device profile
+currently exposed by Bluetooth. A headset may briefly expose only output, or
+reject the negotiated sample rate while switching profiles; VoiceAgent keeps the
+previous working route when a replacement cannot open. The terminal/app still
+needs macOS Microphone permission, and the global hold-key needs Input
+Monitoring. A sandboxed packaged app also needs the appropriate microphone usage
+description and audio-input entitlement; those platform permissions cannot be
+granted by route switching code.
+
 ## Turn taking, and why it's push-to-talk

 Detecting the end of a turn by listening for silence is both slow and wrong