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.

feat(windows): read the Windows mic privacy gate and say how to fix a denial

review8363cbc28584
diff --git a/src/main/index.ts b/src/main/index.ts
index f84422a0a..a291f0e9b 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -23,6 +23,7 @@ installLogSink(logBuffer)
import { nativeMux, setNativeWindowsAgentOptIn, useNativeSsh } from '../core/remote-ssh/native/native-runtime'
import { writeFilesToClipboard } from './clipboard-files'
import { writeWindowsFileDrop } from './clipboard-files-win'
+import { micConsentDecision, micSettingsUrl } from './mic-consent'
import { pickProjectIcon } from './project-icon-upload'
import { allowGuestNavigation } from './webview-nav'
import { appEntryUrlFor, decideMainFrameNavigation, isSafeExternalUrl } from './navigation-guard'
@@ -1512,9 +1513,14 @@ app.whenReady().then(async () => {
// Electron-only mic consent: not core-bound (systemPreferences is main-process-only), so it's
// a raw ipcMain handler like the other Electron-only surfaces (dialogs, shell, media) rather
// than going through registerSpeechIpc/corePlatform.
- ipcMain.handle(IPC.speechMicConsent, async () =>
- process.platform === 'darwin' ? systemPreferences.askForMediaAccess('microphone') : true
- )
+ ipcMain.handle(IPC.speechMicConsent, async () => micConsentDecision(process.platform, systemPreferences))
+ // Fixed allowlisted URL per OS (never renderer-supplied); false where there is no such page.
+ ipcMain.handle(IPC.speechOpenMicSettings, async () => {
+ const url = micSettingsUrl(process.platform)
+ if (!url) return false
+ await shell.openExternal(url)
+ return true
+ })
registerClaudeCliIpc()
// Invariant 11 for probes: registered in BOTH shells, or session-id minting silently works on
// the desktop and not in the browser, with nothing to say which.
diff --git a/src/main/mic-consent.test.ts b/src/main/mic-consent.test.ts
new file mode 100644
index 000000000..a8df6cdb4
--- /dev/null
+++ b/src/main/mic-consent.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from 'vitest'
+import { micConsentDecision, micSettingsUrl, type MicConsentDeps } from './mic-consent'
+
+const deps = (status: string | (() => string) = 'granted', asked = true): MicConsentDeps => ({
+ askForMediaAccess: vi.fn(async () => asked),
+ getMediaAccessStatus: vi.fn(typeof status === 'function' ? status : () => status)
+})
+
+describe('micConsentDecision', () => {
+ it('asks the macOS TCC prompt on darwin, exactly as before', async () => {
+ const d = deps('denied', false)
+ expect(await micConsentDecision('darwin', d)).toBe(false)
+ expect(d.askForMediaAccess).toHaveBeenCalledWith('microphone')
+ expect(d.getMediaAccessStatus).not.toHaveBeenCalled()
+ expect(await micConsentDecision('darwin', deps('denied', true))).toBe(true)
+ })
+
+ it('refuses on win32 only for an explicit Windows privacy denial', async () => {
+ expect(await micConsentDecision('win32', deps('denied'))).toBe(false)
+ for (const status of ['granted', 'not-determined', 'restricted', 'unknown']) {
+ expect(await micConsentDecision('win32', deps(status))).toBe(true)
+ }
+ })
+
+ it('fails open when the Windows status read throws, and never prompts there', async () => {
+ const d = deps(() => {
+ throw new Error('unsupported')
+ })
+ expect(await micConsentDecision('win32', d)).toBe(true)
+ expect(d.askForMediaAccess).not.toHaveBeenCalled()
+ })
+
+ it('stays true on linux without touching systemPreferences', async () => {
+ const d = deps('denied', false)
+ expect(await micConsentDecision('linux', d)).toBe(true)
+ expect(d.askForMediaAccess).not.toHaveBeenCalled()
+ expect(d.getMediaAccessStatus).not.toHaveBeenCalled()
+ })
+})
+
+describe('micSettingsUrl', () => {
+ it('is a fixed per-OS privacy page, or null', () => {
+ expect(micSettingsUrl('win32')).toBe('ms-settings:privacy-microphone')
+ expect(micSettingsUrl('darwin')).toMatch(/^x-apple\.systempreferences:.*Privacy_Microphone$/)
+ expect(micSettingsUrl('linux')).toBeNull()
+ })
+})
diff --git a/src/main/mic-consent.ts b/src/main/mic-consent.ts
new file mode 100644
index 000000000..68c5cd518
--- /dev/null
+++ b/src/main/mic-consent.ts
@@ -0,0 +1,38 @@
+/**
+ * Desktop microphone consent, decided per OS. Pure over an injected `systemPreferences` slice so
+ * the Windows leg is testable on Linux.
+ *
+ * - darwin: `askForMediaAccess` — the TCC prompt (unchanged).
+ * - win32: there is no prompt API; Windows answers through Settings → Privacy & security →
+ * Microphone. Only an explicit `'denied'` refuses (so the overlay can point at that setting
+ * instead of surfacing a raw DOMException). Every other answer — granted, not-determined,
+ * restricted, unknown — and a throw FAIL OPEN: `getUserMedia` is still the real gate, and a
+ * wrong "no" here would block a mic that works.
+ * - elsewhere: true (the OS has no app-level gate we can read).
+ */
+export interface MicConsentDeps {
+ askForMediaAccess(media: 'microphone'): Promise<boolean>
+ getMediaAccessStatus(media: 'microphone'): string
+}
+
+export async function micConsentDecision(platform: string, deps: MicConsentDeps): Promise<boolean> {
+ if (platform === 'darwin') return deps.askForMediaAccess('microphone')
+ if (platform === 'win32') {
+ try {
+ return deps.getMediaAccessStatus('microphone') !== 'denied'
+ } catch {
+ return true
+ }
+ }
+ return true
+}
+
+/**
+ * The OS microphone-privacy page, from a FIXED allowlist (never a renderer-supplied URL — this is
+ * handed to `shell.openExternal`). `null` = no such page on this platform.
+ */
+export function micSettingsUrl(platform: string): string | null {
+ if (platform === 'win32') return 'ms-settings:privacy-microphone'
+ if (platform === 'darwin') return 'x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone'
+ return null
+}
diff --git a/src/preload/index.ts b/src/preload/index.ts
index e389a5868..b4ffc41b2 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -287,7 +287,8 @@ const api: NodeTerminalApi = {
ipcRenderer.on(IPC.speechProgress, handler)
return () => ipcRenderer.removeListener(IPC.speechProgress, handler)
},
- micConsent: () => ipcRenderer.invoke(IPC.speechMicConsent)
+ micConsent: () => ipcRenderer.invoke(IPC.speechMicConsent),
+ openMicSettings: () => ipcRenderer.invoke(IPC.speechOpenMicSettings)
},
ssh: {
list: () => ipcRenderer.invoke(IPC.sshList),
diff --git a/src/renderer/bridge/ws-bridge.ts b/src/renderer/bridge/ws-bridge.ts
index 8df46c1e0..5707a2add 100644
--- a/src/renderer/bridge/ws-bridge.ts
+++ b/src/renderer/bridge/ws-bridge.ts
@@ -939,6 +939,8 @@ export function buildSpeechApi(client: RpcClient): Pick<NodeTerminalApi, 'speech
deleteModel: (id) => client.request(IPC.speechModelDelete, { id }) as Promise<void>,
onProgress: (cb) => client.subscribe(IPC.speechProgress, cb as Listener),
micConsent: () => Promise.resolve(true)
+ // `openMicSettings` is deliberately ABSENT: a browser's mic permission is its own site
+ // setting, and the dictation overlay hides its "Open microphone settings" button without it.
}
return { speech }
}
diff --git a/src/renderer/components/DictationOverlay.lifecycle.test.tsx b/src/renderer/components/DictationOverlay.lifecycle.test.tsx
index 06069d1d2..8c5cf4c9e 100644
--- a/src/renderer/components/DictationOverlay.lifecycle.test.tsx
+++ b/src/renderer/components/DictationOverlay.lifecycle.test.tsx
@@ -209,3 +209,40 @@ describe('DictationOverlay — the ordinary hold still works', () => {
expect(onClose).toHaveBeenCalledTimes(1)
})
})
+
+describe('DictationOverlay — a denied microphone', () => {
+ const asWindows = (): void => {
+ vi.spyOn(navigator, 'platform', 'get').mockReturnValue('Win32')
+ }
+ afterEach(() => vi.restoreAllMocks())
+
+ it('on Windows names the privacy toggle and offers to open it', async () => {
+ asWindows()
+ const openMicSettings = vi.fn(async () => true)
+ micConsent.mockResolvedValue(false)
+ ;(window as unknown as { nodeTerminal: { speech: object } }).nodeTerminal.speech = {
+ micConsent,
+ transcribe,
+ openMicSettings
+ }
+ await render(true)
+ await flush()
+
+ expect(h.FakeCapture.instances).toHaveLength(0)
+ expect(document.body.textContent).toContain('Let desktop apps access your microphone')
+ const button = [...document.querySelectorAll('button')].find((b) => b.textContent === 'Open microphone settings')
+ expect(button).toBeTruthy()
+ await act(async () => button!.click())
+ expect(openMicSettings).toHaveBeenCalledOnce()
+ })
+
+ it('renders no settings button where the bridge has no openMicSettings (Server Edition)', async () => {
+ asWindows()
+ micConsent.mockResolvedValue(false)
+ await render(true)
+ await flush()
+
+ expect(document.body.textContent).toContain('Microphone access')
+ expect(document.body.textContent).not.toContain('Open microphone settings')
+ })
+})
diff --git a/src/renderer/components/DictationOverlay.tsx b/src/renderer/components/DictationOverlay.tsx
index 49cc7fedc..d27c2d1ea 100644
--- a/src/renderer/components/DictationOverlay.tsx
+++ b/src/renderer/components/DictationOverlay.tsx
@@ -17,6 +17,7 @@ import { IconClose } from './icons'
import { createPortal } from 'react-dom'
import { equalizerBars } from '../lib/dictation-equalizer'
import { PcmCapture } from '../lib/pcm-capture'
+import { micDeniedMessage, micPlatform } from '../lib/micPermission'
import { useSession } from '../session/session'
import { useSettings } from '../state/settings'
import { hasSpeechModel } from '@shared/speech'
@@ -195,9 +196,7 @@ export function DictationOverlay({ target, stopSignal, onClose, onOpenLicense }:
try {
const ok = await window.nodeTerminal.speech.micConsent()
if (!ok) {
- setError(
- 'Microphone access was not granted — allow it in System Settings (or your browser site settings) and try again.'
- )
+ setError(micDeniedMessage(micPlatform()))
return
}
} catch (err) {
@@ -306,9 +305,20 @@ export function DictationOverlay({ target, stopSignal, onClose, onOpenLicense }:
const mode = dictationMode(target, modelReady)
+ // Desktop only: the browser bridge leaves `openMicSettings` absent (its permission is the
+ // browser's own site setting), so the button simply does not render there.
+ // Only macOS and Windows have a privacy page to open.
+ const platform = micPlatform()
+ const openMicSettings =
+ platform === 'darwin' || platform === 'win32' ? window.nodeTerminal.speech?.openMicSettings : undefined
const errorBlock = error && (
<div className="dictation__error">
<span>{error}</span>
+ {openMicSettings && error === micDeniedMessage(platform) && (
+ <button type="button" className="dictation__error-action" onClick={() => void openMicSettings().catch(() => undefined)}>
+ Open microphone settings
+ </button>
+ )}
{isProGateError(error) && (
<button type="button" className="dictation__error-action" onClick={onOpenLicense}>
See nodeterm Pro
diff --git a/src/renderer/lib/micPermission.test.ts b/src/renderer/lib/micPermission.test.ts
new file mode 100644
index 000000000..3f43fb0a1
--- /dev/null
+++ b/src/renderer/lib/micPermission.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { micDeniedMessage, micErrorMessage } from './micPermission'
+
+describe('micDeniedMessage', () => {
+ it('names the setting that actually gates the mic on each platform', () => {
+ expect(micDeniedMessage('win32')).toContain('Let desktop apps access your microphone')
+ expect(micDeniedMessage('win32')).not.toContain('System Settings')
+ expect(micDeniedMessage('darwin')).toContain('System Settings')
+ expect(micDeniedMessage('browser')).toContain('browser settings')
+ expect(micDeniedMessage('other')).toContain('system settings')
+ })
+})
+
+describe('micErrorMessage', () => {
+ const named = (name: string): Error => Object.assign(new Error('raw'), { name })
+
+ it('maps the permission, busy and missing-device DOMException names', () => {
+ expect(micErrorMessage(named('NotAllowedError'), 'win32')).toBe(micDeniedMessage('win32'))
+ expect(micErrorMessage(named('SecurityError'), 'browser')).toBe(micDeniedMessage('browser'))
+ expect(micErrorMessage(named('NotReadableError'), 'win32')).toMatch(/in use by another app/)
+ expect(micErrorMessage(named('NotFoundError'), 'darwin')).toMatch(/No microphone/)
+ // A DOMException-shaped object that is not an Error instance still maps.
+ expect(micErrorMessage({ name: 'NotFoundError' }, 'win32')).toMatch(/No microphone/)
+ })
+
+ it('returns null for anything else so the caller keeps the original error', () => {
+ expect(micErrorMessage(named('AbortError'), 'win32')).toBeNull()
+ expect(micErrorMessage('boom', 'win32')).toBeNull()
+ expect(micErrorMessage(null, 'win32')).toBeNull()
+ })
+})
diff --git a/src/renderer/lib/micPermission.ts b/src/renderer/lib/micPermission.ts
new file mode 100644
index 000000000..15db4a87c
--- /dev/null
+++ b/src/renderer/lib/micPermission.ts
@@ -0,0 +1,47 @@
+import { isBrowserRuntime } from '../bridge/runtime'
+import { isMacPlatform, isWindowsPlatform } from '@shared/platform-utils'
+
+/**
+ * Whose rules govern the microphone for this renderer. The Server Edition is `browser` whatever
+ * the viewer's OS — its permission lives in the browser's site settings, not the OS's.
+ */
+export type MicPlatform = 'darwin' | 'win32' | 'browser' | 'other'
+
+export function micPlatform(): MicPlatform {
+ if (isBrowserRuntime()) return 'browser'
+ if (isMacPlatform()) return 'darwin'
+ if (isWindowsPlatform()) return 'win32'
+ return 'other'
+}
+
+/** The denial copy, naming the one setting that actually blocks the mic on that platform. */
+export function micDeniedMessage(platform: MicPlatform): string {
+ switch (platform) {
+ case 'win32':
+ return 'Microphone access is blocked by Windows — turn on "Microphone access" and "Let desktop apps access your microphone" in Settings → Privacy & security → Microphone, then try again.'
+ case 'darwin':
+ return 'Microphone access was denied — allow nodeterm in System Settings → Privacy & Security → Microphone and try again.'
+ case 'browser':
+ return "Microphone access was denied — allow it in this site's browser settings and try again."
+ default:
+ return 'Microphone access was denied — allow it in your system settings and try again.'
+ }
+}
+
+/**
+ * Map a `getUserMedia` rejection to readable copy. Unknown errors keep their own message — only
+ * the three names whose raw DOMException text says nothing useful are rewritten.
+ */
+export function micErrorMessage(err: unknown, platform: MicPlatform): string | null {
+ const name = err instanceof Error || (typeof err === 'object' && err !== null && 'name' in err)
+ ? String((err as { name?: unknown }).name)
+ : ''
+ if (name === 'NotAllowedError' || name === 'SecurityError') return micDeniedMessage(platform)
+ if (name === 'NotReadableError' || name === 'TrackStartError') {
+ return 'The microphone could not be opened — it may be in use by another app.'
+ }
+ if (name === 'NotFoundError' || name === 'DevicesNotFoundError') {
+ return 'No microphone was found — connect one and try again.'
+ }
+ return null
+}
diff --git a/src/renderer/lib/pcm-capture.lifecycle.test.ts b/src/renderer/lib/pcm-capture.lifecycle.test.ts
index 9c97fd1ad..a2a99af9b 100644
--- a/src/renderer/lib/pcm-capture.lifecycle.test.ts
+++ b/src/renderer/lib/pcm-capture.lifecycle.test.ts
@@ -129,3 +129,29 @@ describe('PcmCapture.start — cancelled while the microphone is still opening',
expect(secondTrack.stop).not.toHaveBeenCalled()
})
})
+
+describe('PcmCapture.start — a getUserMedia rejection becomes platform copy', () => {
+ const rejectWith = (name: string): void => {
+ const err = Object.assign(new Error(`raw ${name}`), { name })
+ vi.stubGlobal('navigator', { mediaDevices: { getUserMedia: () => Promise.reject(err) } })
+ }
+
+ it('NotAllowedError names the Windows privacy toggle on win32 and System Settings on darwin', async () => {
+ rejectWith('NotAllowedError')
+ await expect(new PcmCapture(() => 'win32').start()).rejects.toThrow(/Privacy & security → Microphone/)
+ await expect(new PcmCapture(() => 'darwin').start()).rejects.toThrow(/System Settings/)
+ await expect(new PcmCapture(() => 'browser').start()).rejects.toThrow(/browser settings/)
+ })
+
+ it('in-use and missing devices read as such instead of raw DOMException text', async () => {
+ rejectWith('NotReadableError')
+ await expect(new PcmCapture(() => 'win32').start()).rejects.toThrow(/in use by another app/)
+ rejectWith('NotFoundError')
+ await expect(new PcmCapture(() => 'win32').start()).rejects.toThrow(/No microphone was found/)
+ })
+
+ it('an unknown error keeps its own message', async () => {
+ rejectWith('AbortError')
+ await expect(new PcmCapture(() => 'win32').start()).rejects.toThrow('raw AbortError')
+ })
+})
diff --git a/src/renderer/lib/pcm-capture.ts b/src/renderer/lib/pcm-capture.ts
index e548918b7..88c865916 100644
--- a/src/renderer/lib/pcm-capture.ts
+++ b/src/renderer/lib/pcm-capture.ts
@@ -17,6 +17,8 @@
* name is duplicated as a plain string constant below.
*/
+import { micErrorMessage, micPlatform, type MicPlatform } from './micPermission'
+
/** Must match `PCM_WORKLET_NAME` in `./pcm-worklet.ts` (not imported — see file header). */
const WORKLET_PROCESSOR_NAME = 'pcm-capture'
@@ -24,8 +26,6 @@ const CAPTURE_SAMPLE_RATE = 16000
/** Buffer size for the `ScriptProcessorNode` fallback; 4096 frames @ 16 kHz ≈ 256 ms per chunk. */
const SCRIPT_PROCESSOR_BUFFER_SIZE = 4096
-export const MIC_PERMISSION_DENIED_MESSAGE =
- 'Microphone access was denied — allow it in System Settings (or your browser site settings) and try again.'
/** Concatenates PCM chunks, in order, into one buffer. Pure — no side effects. */
export function concatChunks(chunks: Float32Array[]): Float32Array {
@@ -55,6 +55,9 @@ function rms(chunk: Float32Array): number {
* earlier `start()` was still opening the microphone (see `generation`).
*/
export class PcmCapture {
+ /** Which platform's denial copy to show; injectable so tests can pin each one. */
+ constructor(private readonly platform: () => MicPlatform = micPlatform) {}
+
private chunks: Float32Array[] = []
private lastChunk: Float32Array = new Float32Array(0)
private running = false
@@ -157,9 +160,10 @@ export class PcmCapture {
audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true }
})
} catch (err) {
- if (err instanceof Error && err.name === 'NotAllowedError') {
- throw new Error(MIC_PERMISSION_DENIED_MESSAGE)
- }
+ // Denied / in use / missing → copy that names the setting to change (per platform: the
+ // Windows privacy toggle, macOS System Settings, or the browser's site settings).
+ const readable = micErrorMessage(err, this.platform())
+ if (readable) throw new Error(readable)
throw err
}
}
diff --git a/src/shared/ipc.ts b/src/shared/ipc.ts
index 1bc9e6a1c..335d0b87c 100644
--- a/src/shared/ipc.ts
+++ b/src/shared/ipc.ts
@@ -770,5 +770,8 @@ export const IPC = {
// Electron-only: registered in src/main/index.ts (systemPreferences.askForMediaAccess) and
// stubbed `async () => true` in src/server/index.ts (browser mic permission is the browser's
// own prompt, not ours to gate).
- speechMicConsent: 'speech:mic-consent'
+ speechMicConsent: 'speech:mic-consent',
+ // Electron-only, NOT registered by the server: opens the OS mic-privacy page from a fixed
+ // allowlist (src/main/mic-consent.ts). The browser bridge leaves `openMicSettings` absent.
+ speechOpenMicSettings: 'speech:open-mic-settings'
} as const
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 679d2e87a..eea6b2c11 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -2481,6 +2481,11 @@ export interface SpeechApi {
/** Ask for microphone permission. Electron: OS-level (macOS TCC prompt); browser: always
* resolves true — the browser's own getUserMedia prompt is not ours to gate. */
micConsent(): Promise<boolean>
+ /** Open the OS microphone-privacy page (Windows `ms-settings:privacy-microphone`, macOS System
+ * Settings). Desktop only — ABSENT in the browser bridge (a browser's mic permission lives in
+ * its own site settings), and the overlay hides its button when absent. Resolves false where
+ * the OS has no such page. */
+ openMicSettings?(): Promise<boolean>
}
export interface SshApi {