Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(speech): a mic still opening when hold-to-talk closes no longer records and types later

reviewf20f6ca0a13f
diff --git a/src/renderer/components/DictationOverlay.lifecycle.test.tsx b/src/renderer/components/DictationOverlay.lifecycle.test.tsx
new file mode 100644
index 000000000..fdecf1b44
--- /dev/null
+++ b/src/renderer/components/DictationOverlay.lifecycle.test.tsx
@@ -0,0 +1,211 @@
+// @vitest-environment jsdom
+//
+// The overlay's lifecycle against a microphone that takes time to open. Opening the mic is not
+// instant (getUserMedia + an AudioContext + the worklet module — seconds on some Macs, longer
+// when a Bluetooth headset switches profile), and hold-to-talk closes the overlay inside that
+// window all the time: a sub-400 ms tap, any ⌘⌥<key> shortcut (the misfire guard), a window
+// blur. A capture that finishes opening AFTER its overlay is gone used to be adopted anyway —
+// nothing was left to stop it, so it recorded the room until the 2:30 cap and then typed the
+// transcript (whisper's "Thank you." over silence, or a meeting's audio) into the terminal.
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const h = vi.hoisted(() => {
+ class FakeCapture {
+ static instances: FakeCapture[] = []
+ /** True from a successful open until stop()/cancel() — the OS mic indicator. */
+ live = false
+ ended = false
+ private openMic: (() => void) | null = null
+ constructor() {
+ FakeCapture.instances.push(this)
+ }
+ start(): Promise<boolean> {
+ return new Promise<boolean>((resolve) => {
+ this.openMic = () => {
+ // A real PcmCapture cancelled mid-open releases the stream and reports false.
+ if (this.ended) return resolve(false)
+ this.live = true
+ resolve(true)
+ }
+ })
+ }
+ /** Test hook: the OS finishes opening the microphone. */
+ finishOpening(): void {
+ this.openMic?.()
+ }
+ stop(): Float32Array {
+ this.live = false
+ this.ended = true
+ return new Float32Array(16_000)
+ }
+ cancel(): void {
+ this.live = false
+ this.ended = true
+ }
+ level(): number {
+ return 0
+ }
+ }
+ return {
+ FakeCapture,
+ sendText: vi.fn(async (_id: string, _text: string, _opts?: { enter?: boolean }) => true)
+ }
+})
+
+vi.mock('../lib/pcm-capture', () => ({ PcmCapture: h.FakeCapture }))
+vi.mock('../session/session', () => ({ useSession: () => ({ api: { pty: { sendText: h.sendText } } }) }))
+
+import { DictationOverlay, type DictationTarget } from './DictationOverlay'
+import { useSettings } from '../state/settings'
+
+const target: DictationTarget = { kind: 'terminal', nodeId: 'n1', title: 'ssh mini' }
+const CAP_PLUS_MARGIN_MS = 200_000 // past MAX_RECORDING_MS (2:30)
+
+let host: HTMLDivElement
+let root: Root
+let onClose: ReturnType<typeof vi.fn>
+let micConsent: ReturnType<typeof vi.fn>
+let transcribe: ReturnType<typeof vi.fn>
+
+async function render(open: boolean, stopSignal = 0): Promise<void> {
+ await act(async () => {
+ root.render(
+ open ? (
+ <DictationOverlay target={target} stopSignal={stopSignal} onClose={onClose} onOpenLicense={() => {}} />
+ ) : null
+ )
+ })
+}
+
+/** Let pending promise continuations (the consent round trip, start()) run. */
+async function flush(): Promise<void> {
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(0)
+ })
+}
+
+function capture(): InstanceType<typeof h.FakeCapture> {
+ expect(h.FakeCapture.instances).toHaveLength(1)
+ return h.FakeCapture.instances[0]
+}
+
+beforeEach(() => {
+ vi.useFakeTimers()
+ h.FakeCapture.instances = []
+ h.sendText.mockClear()
+ onClose = vi.fn()
+ micConsent = vi.fn(async () => true)
+ transcribe = vi.fn(async () => ({ text: 'Thank you.' }))
+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = { speech: { micConsent, transcribe } }
+ const s = useSettings.getState().settings
+ useSettings.setState({ settings: { ...s, speech: { ...s.speech, engine: 'whisper', model: 'tiny' } } })
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+})
+
+afterEach(async () => {
+ await act(async () => root.unmount())
+ host.remove()
+ vi.useRealTimers()
+})
+
+describe('DictationOverlay — closed while the microphone is still opening', () => {
+ it('a quick tap (Canvas unmounts the overlay) leaves no live mic and types nothing', async () => {
+ await render(true)
+ await flush()
+ const c = capture()
+
+ await render(false) // hold-to-talk cancel(): <400 ms tap, ⌘⌥<key> misfire, window blur
+ expect(c.ended).toBe(true) // the in-flight open is told to give up at unmount, not later
+ c.finishOpening()
+ await flush()
+ expect(c.live).toBe(false) // the OS mic indicator must not light up for a closed overlay
+ expect(vi.getTimerCount()).toBe(0) // nor may a 20 Hz level poll run on the unmounted instance
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(CAP_PLUS_MARGIN_MS)
+ })
+ // The reported symptom: 2:30 later the room's audio was transcribed and typed in.
+ expect(h.sendText).not.toHaveBeenCalled()
+ expect(transcribe).not.toHaveBeenCalled()
+ })
+
+ it('a hold released before the mic opened discards the take and releases the mic', async () => {
+ await render(true)
+ await flush()
+ const c = capture()
+
+ await render(true, 1) // hold-to-talk stop(): stopSignal bump while phase is still 'idle'
+ expect(onClose).toHaveBeenCalledTimes(1)
+ await render(false)
+ c.finishOpening()
+ await flush()
+ expect(c.live).toBe(false)
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(CAP_PLUS_MARGIN_MS)
+ })
+ expect(h.sendText).not.toHaveBeenCalled()
+ expect(transcribe).not.toHaveBeenCalled()
+ })
+
+ it('a remount over a still-opening instance (header-mic retarget) never leaves the first mic live', async () => {
+ await render(true)
+ await flush()
+ const first = capture()
+
+ // A new React key = a fresh instance; the old one unmounts with its start still pending.
+ await act(async () => {
+ root.render(
+ <DictationOverlay key="2" target={target} stopSignal={0} onClose={onClose} onOpenLicense={() => {}} />
+ )
+ })
+ first.finishOpening()
+ await flush()
+ expect(first.live).toBe(false)
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(CAP_PLUS_MARGIN_MS)
+ })
+ // Only the live instance's own take may land (it auto-stops at the cap and inserts).
+ expect(h.sendText.mock.calls.length).toBeLessThanOrEqual(1)
+ })
+
+ it('closed during the consent round trip, it never opens the mic at all', async () => {
+ let grant: (ok: boolean) => void = () => {}
+ micConsent.mockImplementation(() => new Promise<boolean>((r) => (grant = r)))
+ await render(true)
+ await render(false)
+ grant(true)
+ await flush()
+
+ expect(h.FakeCapture.instances).toHaveLength(0)
+ })
+})
+
+describe('DictationOverlay — the ordinary hold still works', () => {
+ it('opens, records, and on stop transcribes and inserts without Enter', async () => {
+ await render(true)
+ await flush()
+ const c = capture()
+ c.finishOpening()
+ await flush()
+ expect(c.live).toBe(true)
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(1_500)
+ })
+ await render(true, 1) // release after a real hold → STOP
+ await flush()
+
+ expect(c.live).toBe(false)
+ expect(transcribe).toHaveBeenCalledTimes(1)
+ expect(h.sendText).toHaveBeenCalledWith('n1', 'Thank you.', { enter: false })
+ expect(onClose).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/src/renderer/components/DictationOverlay.tsx b/src/renderer/components/DictationOverlay.tsx
index ff8972281..49cc7fedc 100644
--- a/src/renderer/components/DictationOverlay.tsx
+++ b/src/renderer/components/DictationOverlay.tsx
@@ -204,16 +204,33 @@ export function DictationOverlay({ target, stopSignal, onClose, onOpenLicense }:
setError(err instanceof Error ? err.message : 'Could not request microphone access.')
return
}
+ // Closed during the consent round trip — never open the mic for an overlay that is gone.
+ if (!mountedRef.current || discardedRef.current) return
}
+ // Owned BEFORE the mic finishes opening, so the unmount cleanup can cancel a start that is
+ // still in flight (PcmCapture then releases the stream the moment it arrives). Opening takes
+ // hundreds of ms (seconds with a Bluetooth headset), and hold-to-talk closes inside that
+ // window on every quick tap, ⌘⌥<key> shortcut and window blur. Adopting the capture only
+ // after `start()` resolved left exactly those takes with no owner: the mic recorded the room
+ // until the 2:30 cap, and the transcript — whisper's "Thank you." over silence, or a
+ // meeting's audio — was typed into the terminal.
const capture = new PcmCapture()
+ captureRef.current = capture
+ let live: boolean
try {
- await capture.start()
+ live = await capture.start()
} catch (err) {
+ if (captureRef.current !== capture) return
+ captureRef.current = null
setError(err instanceof Error ? err.message : 'Could not start recording.')
return
}
- captureRef.current = capture
+ // Cancelled while opening (start() already released the stream), or superseded/unmounted.
+ if (!live || captureRef.current !== capture || !mountedRef.current) {
+ capture.cancel()
+ return
+ }
startedAtRef.current = Date.now()
setElapsedMs(0)
diff --git a/src/renderer/lib/pcm-capture.lifecycle.test.ts b/src/renderer/lib/pcm-capture.lifecycle.test.ts
new file mode 100644
index 000000000..9c97fd1ad
--- /dev/null
+++ b/src/renderer/lib/pcm-capture.lifecycle.test.ts
@@ -0,0 +1,131 @@
+// A cancel()/stop() that lands while start() is still opening the microphone. getUserMedia, the
+// AudioContext and the worklet module are all awaits, and the caller gives up inside that window
+// routinely (hold-to-talk: a sub-400 ms tap, a ⌘⌥<key> shortcut, a window blur). The stream that
+// arrives afterwards has no owner left to stop it — so start() must release it itself, and must
+// say it did not start, instead of adopting it into a capture nobody will ever end.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { PcmCapture } from './pcm-capture'
+
+interface Deferred<T> {
+ promise: Promise<T>
+ resolve: (v: T) => void
+}
+function deferred<T>(): Deferred<T> {
+ let resolve!: (v: T) => void
+ const promise = new Promise<T>((r) => (resolve = r))
+ return { promise, resolve }
+}
+
+let track: { stop: ReturnType<typeof vi.fn> }
+let stream: { getTracks: () => (typeof track)[] }
+let gum: Deferred<typeof stream>
+let addModule: Deferred<void>
+let contexts: FakeAudioContext[]
+let workletNodes: number
+
+class FakeAudioContext {
+ state: 'running' | 'closed' = 'running'
+ audioWorklet = { addModule: () => addModule.promise }
+ destination = {}
+ constructor() {
+ contexts.push(this)
+ }
+ createMediaStreamSource() {
+ return { connect: vi.fn(), disconnect: vi.fn() }
+ }
+ close() {
+ this.state = 'closed'
+ return Promise.resolve()
+ }
+}
+
+class FakeAudioWorkletNode {
+ port = { onmessage: null as unknown }
+ constructor() {
+ workletNodes += 1
+ }
+ disconnect() {}
+}
+
+beforeEach(() => {
+ track = { stop: vi.fn() }
+ stream = { getTracks: () => [track] }
+ gum = deferred()
+ addModule = deferred()
+ contexts = []
+ workletNodes = 0
+ vi.stubGlobal('navigator', { mediaDevices: { getUserMedia: () => gum.promise } })
+ vi.stubGlobal('AudioContext', FakeAudioContext)
+ vi.stubGlobal('AudioWorkletNode', FakeAudioWorkletNode)
+})
+
+afterEach(() => {
+ vi.unstubAllGlobals()
+})
+
+describe('PcmCapture.start — cancelled while the microphone is still opening', () => {
+ it('cancel() during getUserMedia: the late stream is stopped and start() reports false', async () => {
+ const capture = new PcmCapture()
+ const started = capture.start()
+ capture.cancel()
+ gum.resolve(stream)
+
+ await expect(started).resolves.toBe(false)
+ expect(track.stop).toHaveBeenCalled()
+ expect(contexts).toHaveLength(0) // never went on to build an audio graph
+ })
+
+ it('stop() during getUserMedia: same — an empty take, and no live mic left behind', async () => {
+ const capture = new PcmCapture()
+ const started = capture.start()
+ expect(capture.stop()).toHaveLength(0)
+ gum.resolve(stream)
+
+ await expect(started).resolves.toBe(false)
+ expect(track.stop).toHaveBeenCalled()
+ })
+
+ it('cancel() while the worklet module loads: no node is built on the dead graph', async () => {
+ const capture = new PcmCapture()
+ const started = capture.start()
+ gum.resolve(stream)
+ await vi.waitFor(() => expect(contexts).toHaveLength(1))
+ capture.cancel()
+ addModule.resolve()
+
+ await expect(started).resolves.toBe(false)
+ expect(track.stop).toHaveBeenCalled()
+ expect(contexts[0].state).toBe('closed')
+ expect(workletNodes).toBe(0)
+ })
+
+ it('a start() that runs to completion reports true', async () => {
+ const capture = new PcmCapture()
+ const started = capture.start()
+ gum.resolve(stream)
+ addModule.resolve()
+
+ await expect(started).resolves.toBe(true)
+ expect(workletNodes).toBe(1)
+ expect(track.stop).not.toHaveBeenCalled()
+ capture.cancel()
+ expect(track.stop).toHaveBeenCalled()
+ })
+
+ it('the same instance starts cleanly again after a cancelled start', async () => {
+ const capture = new PcmCapture()
+ const first = capture.start()
+ capture.cancel()
+ gum.resolve(stream)
+ await expect(first).resolves.toBe(false)
+
+ gum = deferred()
+ const secondTrack = { stop: vi.fn() }
+ const second = capture.start()
+ gum.resolve({ getTracks: () => [secondTrack] } as unknown as typeof stream)
+ addModule.resolve()
+
+ await expect(second).resolves.toBe(true)
+ expect(secondTrack.stop).not.toHaveBeenCalled()
+ })
+})
diff --git a/src/renderer/lib/pcm-capture.ts b/src/renderer/lib/pcm-capture.ts
index afdda12a2..e548918b7 100644
--- a/src/renderer/lib/pcm-capture.ts
+++ b/src/renderer/lib/pcm-capture.ts
@@ -51,7 +51,8 @@ function rms(chunk: Float32Array): number {
/**
* Captures the default microphone as mono 16 kHz PCM until `stop()`.
* `teardown()` resets to constructor state, so a fresh `start()` after
- * `stop()`/`cancel()` is fully supported.
+ * `stop()`/`cancel()` is fully supported — including one that landed while an
+ * earlier `start()` was still opening the microphone (see `generation`).
*/
export class PcmCapture {
private chunks: Float32Array[] = []
@@ -65,19 +66,41 @@ export class PcmCapture {
private scriptNode: ScriptProcessorNode | null = null
/** Silent sink the ScriptProcessorNode fallback routes through — see `startScriptProcessor`. */
private scriptSink: GainNode | null = null
-
- /** Requests the microphone and starts collecting chunks. Idempotent while already running. */
- async start(): Promise<void> {
- if (this.running) return
+ /**
+ * Bumped by every `teardown()`. A `start()` remembers the value it began with and, after each
+ * await, gives up if it moved: `stop()`/`cancel()` landed while the microphone was still
+ * opening. That window is routine — getUserMedia + the AudioContext + the worklet module take
+ * hundreds of ms (seconds when a Bluetooth headset switches profile), and hold-to-talk closes
+ * inside it on every quick tap. Adopting the late stream anyway left a live mic that nothing
+ * would ever stop.
+ */
+ private generation = 0
+
+ /**
+ * Requests the microphone and starts collecting chunks. Resolves `true` once capturing, and
+ * `false` when `stop()`/`cancel()` arrived before the microphone finished opening — the late
+ * stream is released here, so nothing is live and the caller has nothing to undo. Idempotent
+ * while already running (`true`).
+ */
+ async start(): Promise<boolean> {
+ if (this.running) return true
// Set the flag synchronously before the first await to guard against
// re-entry: a second `start()` called during setup will see this.running
// true and return early. Doubled as an in-flight guard so it must flip
// before any suspension point.
this.running = true
+ const generation = this.generation
+ const cancelled = (): boolean => generation !== this.generation
try {
const stream = await this.acquireStream()
+ if (cancelled()) {
+ // Its owner already tore down — these tracks are on no field, so release them here or
+ // the OS microphone stays open.
+ for (const track of stream.getTracks()) track.stop()
+ return false
+ }
// Adopt the stream IMMEDIATELY: if AudioContext construction or
// createMediaStreamSource throws below, the catch's teardown() must be
// able to stop these tracks — a live mic (OS indicator lit) must never
@@ -94,13 +117,18 @@ export class PcmCapture {
}
try {
- await this.startWorklet(audioContext, sourceNode, onChunk)
+ await this.startWorklet(audioContext, sourceNode, onChunk, cancelled)
} catch {
+ if (cancelled()) return false
// `addModule` (or worklet construction) failed — fall back to the
// deprecated-but-universal ScriptProcessorNode. Same chunk flow.
this.startScriptProcessor(audioContext, sourceNode, onChunk)
}
+ // The teardown that cancelled us already stopped the tracks and closed the context; a
+ // newer start() may own the fields by now, so touch nothing.
+ return !cancelled()
} catch (err) {
+ if (cancelled()) return false
// On any failure, reset running and tear down partial state.
this.running = false
this.teardown()
@@ -139,13 +167,17 @@ export class PcmCapture {
private async startWorklet(
audioContext: AudioContext,
sourceNode: MediaStreamAudioSourceNode,
- onChunk: (chunk: Float32Array) => void
+ onChunk: (chunk: Float32Array) => void,
+ cancelled: () => boolean
): Promise<void> {
// Vite/electron-vite statically recognizes this `new URL(relative,
// import.meta.url)` pattern and emits pcm-worklet.ts as its own
// same-origin asset, satisfying CSP `worker-src 'self' blob:'`.
const workletUrl = new URL('./pcm-worklet.ts', import.meta.url)
await audioContext.audioWorklet.addModule(workletUrl)
+ // Torn down during the module load: the context is closed, and `workletNode` may already
+ // belong to a newer start() — build nothing.
+ if (cancelled()) return
const node = new AudioWorkletNode(audioContext, WORKLET_PROCESSOR_NAME, {
numberOfInputs: 1,
@@ -183,6 +215,7 @@ export class PcmCapture {
}
private teardown(): void {
+ this.generation += 1
if (this.workletNode) this.workletNode.port.onmessage = null
this.workletNode?.disconnect()
this.workletNode = null