Skip to content

Commit fb5fbb9

Browse files
cxrobxclaude
andcommitted
fix: mic restarts can no longer freeze the app; pinned mic falls back; mic in Settings; server Node 24 abort
From the 2026-10-02 XRF call: - The app froze at call end: a watchdog mic restart released the old AVAudioEngine on the main thread while Core Audio's HAL listener was disposing a converter for the AirPods' format change, and they deadlocked. Every engine build/start/stop/release now runs on micQueue; an open that hangs 8 s fails, abandons its queue and discards its late engine (gotcha #34, MicEngineQueueTests). - Start failed: the pinned built-in mic would not start (-10868) with AirPods in a call. A pinned mic that won't start now falls back to the default. - The mic choice is in the dashboard's Settings (app bridge listMics/setMic; e2e 08-mic-setting). - The server aborted at Start: better-sqlite3 11 under Node 24.19+ (GC frees a statement, nodejs/node#65446). Now ^13.0.3; only the darwin-arm64 prebuild ships. Server stderr goes to server.stderr.log and supervisor exits/restarts to app.log (gotcha #33, native-sqlite.test.ts). Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 1ae9235 commit fb5fbb9

15 files changed

Lines changed: 587 additions & 502 deletions

File tree

‎.claude/rules/gotchas.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Known Gotchas
22

3-
Organized by category. 32 items + recovery playbook, condensed format. Original numbering preserved (gaps intentional).
3+
Organized by category. 34 items + recovery playbook, condensed format. Original numbering preserved (gaps intentional).
44

55
## Index
66

@@ -38,6 +38,8 @@ Organized by category. 32 items + recovery playbook, condensed format. Original
3838
| 30 | Playwright newer than 1.61 cannot drive WebKit on macOS 14 — the ship gate breaks | Environment |
3939
| 31 | A process tap delivers nothing while no process makes sound | Environment |
4040
| 32 | A newly signed whisper build compiles its Metal shaders once (~10 s) before the first capture | Deployment |
41+
| 33 | better-sqlite3 below 13 aborts Node 24.19+ when GC frees a statement — the server dies silently | Deployment |
42+
| 34 | Releasing an AVAudioEngine can deadlock inside Core Audio — never touch the mic engine on the main thread | Environment |
4143
| — | **Recovery playbook** (system-wide SCK silence, server crash loops, zombie processes) | — |
4244

4345
Standard categories: Environment, Database, Backend, Frontend, Security, Deployment, External APIs
@@ -224,6 +226,21 @@ this default.
224226
**Solution**: `ship.sh` runs the capture self-test on the installed copy right after install, which pays it then, not at the next meeting's start. A Sparkle update whose whisper libraries are unchanged did not pay it (measured on 0.1.91 to 0.1.92). One that upgrades whisper-cpp will, on the first meeting after the update.
225227
**Pattern**: `scripts/ship.sh` (post-install self-test), `AudioCaptureManager.startCapture` (VAD before capture).
226228

229+
### 33. better-sqlite3 Below 13 Aborts Node 24.19+ When GC Frees a Statement — the Server Dies Silently
230+
**Symptom**: The server restarts with no error in server.log (a meeting's Start showed "Lost connection to server", 2026-10-02 10:33). A crash report `~/Library/Logs/DiagnosticReports/node-*.ips` shows SIGABRT in `node::Assert` ← `node::RemoveEnvironmentCleanupHook` ← `better_sqlite3.node Statement::~Statement()` (or `Database::~Database()`) ← `Heap::CollectGarbage`.
231+
**Cause**: from Node 24.19 `node::ObjectWrap`'s destructor calls `RemoveEnvironmentCleanupHook`, which needs an entered context; better-sqlite3 11.x and 12.x destroy statements inside V8 GC callbacks, where there is none (nodejs/node#65446). T230 pinned Node 24.21 that morning. Nothing reproduces it on demand: a GC soak passed on 11.10.0.
232+
**Solution** (applied 2026-10-02): better-sqlite3 `^13.0.3` (Node-API, prebuilds in the package, no install script). `build-app.sh` keeps only the `darwin-arm64` prebuild. The server's stderr now goes to `~/.meeting-copilot/server.stderr.log`, and the supervisor's exits and restarts to app.log with signal or code, so the next native abort shows up in one grep (it went to `print()`, gotcha #15).
233+
**Check**: `__tests__/native-sqlite.test.ts` fails when the pinned Node (`scripts/fetch-node.sh`) is 24+ and better-sqlite3 is below 13.
234+
**Pattern**: `server/package.json`, `app/MeetingCopilot/Sources/Core/Process/ProcessSupervisor.swift` (`makeStderrLogPipe`).
235+
236+
### 34. Releasing an AVAudioEngine Can Deadlock Inside Core Audio — Never Touch the Mic Engine on the Main Thread
237+
**Symptom**: The whole app freezes (dashboard, menu bar, Stop) right after a mic restart, typically when AirPods leave call mode as a call ends. app.log stops at `mic restarted successfully` except for per-second `meeting peak=` lines; the server stays healthy.
238+
**Cause**: Seen 2026-10-02 (`sample` of the hung app): the main thread, in a watchdog restart, was in `-[AVAudioEngine dealloc]` → `AudioComponentInstanceDispose`, spinning in Core Audio's object table, while the HAL listener thread was in `AudioConverterDispose` for the AirPods' format change (24 → 48 kHz), blocked on that table's mutex. Each waited on the other. Apple's lock; no app-side ordering avoids it.
239+
**Solution** (applied 2026-10-02): every engine build, start, stop and release runs on `micQueue` (`AudioCaptureManager.openMic` / `closeMic` / `tearDown`), and results are applied on main by generation number. An open that has not answered in `micOpTimeoutSec` (8 s) fails with `.microphoneStuck`, its queue is abandoned for a fresh one (at most 4), and its late engine is torn down, never applied. The watchdog's restart ladder carries on as before.
240+
**Check**: `Tests/MicEngineQueueTests.swift` hangs a fake engine factory forever and requires the main thread to keep running, the next open to succeed on a fresh queue, and the late engine to be discarded.
241+
**Also**: a pinned mic that will not start now falls back to the system default (`MicDevicePicker.attempts`): the built-in mic refused to start (`-10868`, `InitializeActiveNodesInInputChain`) while AirPods were in a call at 24 kHz, and with no second attempt the session never began. The mic choice is in the dashboard's Settings (the app's bridge: `listMics` / `setMic`).
242+
**Pattern**: `app/MeetingCopilot/Sources/Core/Audio/AudioCaptureManager.swift` (`openMic`), `Audio/MicDevicePicker.swift` (`attempts`, `choices`).
243+
227244
### 11. WKWebView Needs Health Polling Before Loading Localhost
228245
**Symptom**: Blank white panel on app launch
229246
**Cause**: WKWebView loads `/present` before the Node server finishes starting. Failed navigation shows blank page, `reload()` does nothing after failed provisional navigation.

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ cd app/MeetingCopilot && swift build
4242

4343
## Key Decisions
4444

45-
- **Audio**: Core Audio process tap (meeting — hears phone and FaceTime calls too; ScreenCaptureKit fallback) + AVAudioEngine (mic, **pinned to the built-in mic**, not the system default; `micDevice` default), 16kHz mono PCM. A dead mic is never silent: the app's watchdog and the server's (`capture/track-watch.ts`) each restart it and raise NO MIC in the menu bar, a notification and a dashboard banner with Restart mic (gotcha #28)
45+
- **Audio**: Core Audio process tap (meeting — hears phone and FaceTime calls too; ScreenCaptureKit fallback) + AVAudioEngine (mic, **pinned to the built-in mic**, not the system default; chosen in the dashboard's Settings, and a pinned mic that won't start falls back to the default; every engine start/stop runs off the main thread, gotcha #34), 16kHz mono PCM. A dead mic is never silent: the app's watchdog and the server's (`capture/track-watch.ts`) each restart it and raise NO MIC in the menu bar, a notification and a dashboard banner with Restart mic (gotcha #28)
4646
- **Transcription**: live streaming Grok Voice Transcribe 2.0 by default (the app sends 100 ms PCM frames; text trails speech by ~1 s), with the app's VAD chunks going to local Parakeet whenever a stream is down. Needs `COPILOT_ALLOW_CLOUD_AUDIO=true` + `XAI_API_KEY`; otherwise fully local (Parakeet, whisper fallback). `COPILOT_GROK_STREAMING=0` = per-chunk batch Grok; `COPILOT_CLOUD_TRANSCRIPTION=deepgram|off` for the others
4747
- **Intelligence**: gpt-6-luna triage via the OpenAI API (15s cadence) → Sonnet suggestions on the subscription CLI. Triage falls back to Haiku on the subscription CLI when the API is off (`COPILOT_LIVE_LLM_MODE=cli`) or fails twice. Context compression (the 5-min summaries fed back into triage) runs the same route
4848
- **Meeting pulse** (`intelligence/pulse.ts`): every 5 min, Opus 5.5 on the subscription CLI reads the whole meeting and updates one card: on track / drifting / stuck, up to 2 things to escalate, and what to settle before the end. A close-out pass runs 5 min before the calendar end (invite-started meetings), on wrap-up language after minute 10, or on the Wrap-up button, and the app raises a notification for it. It shares one CLI lane with the rolling summary (`intelligence/cli-lane.ts`) and always runs cold, since a warm session would carry the previous transcript. Costs no metered spend.

0 commit comments

Comments
 (0)