fix(voice): stop mic-test ref stealing, unblock action queue, keep tail audio, and move context/LLM routing behind ports and pure policies

2026-09-28 02:16:16 +09:00 · 2026-09-28 02:16:16 +09:00 · 2f94d24c99
commit 2f94d24c99
parent 2cd462333f
13 changed files with 1672 additions and 353 deletions
--- a/apps/desktop/src/main/ipc/audio-handlers.ts
+++ b/apps/desktop/src/main/ipc/audio-handlers.ts
@ -3,7 +3,7 @@
 import { ipcMain } from 'electron'
 import { IPC_CHANNELS } from '@d3ro/core/ipc-channels'
 import { ipcSuccess, ipcError, ErrorCode } from '@d3ro/core/errors'
-import { getAudioCaptureService, calculateRMS } from '../services/AudioCaptureService'
+import { getAudioCaptureService, calculateRMS, type CaptureLease } from '../services/AudioCaptureService'
 import { getMainWindow } from '../windows/WindowManager'
 import { configGet, configSet } from '../services/ConfigService'
 import type { SetDeviceParams } from '@d3ro/core/types'
@ -12,6 +12,11 @@ let testTimer: ReturnType<typeof setTimeout> | null = null
 let testAudioHandler: ((payload: { buffer: Buffer; timestamp: number }) => void) | null = null
 let testLevelInterval: ReturnType<typeof setInterval> | null = null
 let testLastRms = 0
+/**
+ * 테스트가 실제로 잡은 캡처 참조. 테스트가 돌고 있지 않을 때 stop() 을 부르면 회의·자막·받아쓰기가
+ * 잡고 있는 참조를 빼앗아 그쪽 마이크가 조용히 끊긴다 — 테스트는 자기 임대만 놓는다.
+ */
+let testLease: CaptureLease | null = null

 function stopAudioTest(): void {
  const service = getAudioCaptureService()
@ -28,7 +33,9 @@ function stopAudioTest(): void {
    testTimer = null
  }
  testLastRms = 0
-  service.stop().catch(() => { /* ignore */ })
+  const lease = testLease
+  testLease = null
+  lease?.release().catch(() => { /* ignore */ })
 }

 export function registerAudioHandlers(): void {
@ -62,7 +69,7 @@ export function registerAudioHandlers(): void {
      stopAudioTest()

      const service = getAudioCaptureService()
-      await service.start()
+      testLease = await service.acquire()

      // 오디오 데이터에서 RMS 추적
      testAudioHandler = (payload: { buffer: Buffer; timestamp: number }) => {
--- a/apps/desktop/src/main/services/AudioCaptureService.ts
+++ b/apps/desktop/src/main/services/AudioCaptureService.ts
@ -18,8 +18,44 @@ const logger = getLogger('AudioCaptureService')
 /** 60ms 프레임 크기 (바이트): 16000 * 2 * 0.06 = 1920 */
 const FRAME_SIZE_BYTES = (AUDIO_FORMAT.SAMPLE_RATE * AUDIO_FORMAT.BYTES_PER_SAMPLE * 60) / 1000

+/**
+ * SoX stdout 버퍼 크기(바이트). SoX 기본값 8192 는 16kHz 16bit mono 에서 256ms 라, 청크가 늦게 오고
+ * 정지 시 버퍼에 남은 최대 256ms(끝 음절)가 버려졌다. 1024 = 32ms.
+ */
+export const SOX_BUFFER_BYTES = 1024
+
+/**
+ * 마지막 참조를 놓을 때 SoX 를 죽이기 전에 버퍼·파이프에 남은 꼬리 오디오를 받아 내는 시간.
+ * SoX 버퍼(32ms)의 두 배 이상이어야 정지 직전까지의 소리가 한 번은 쓰여 나온다.
+ */
+export const TAIL_FLUSH_MS = 80
+
 export type CaptureState = 'idle' | 'starting' | 'capturing' | 'stopping' | 'error'

+/**
+ * 캡처 참조 한 개. release() 는 멱등이고, 그사이 캡처가 죽었다 다시 시작됐으면(세대가 바뀜)
+ * 다른 소비자의 참조를 깎지 않는다.
+ */
+export interface CaptureLease {
+  release(): Promise<void>
+}
+
+/** SoX 녹음 인자 (Windows: -t waveaudio 필수, 그 외: -d) */
+export function buildSoxRecordArgs(deviceArg: string, platform: NodeJS.Platform = process.platform): string[] {
+  const input = platform === 'win32' ? ['-t', 'waveaudio', deviceArg] : ['-d']
+  return [
+    '--buffer', String(SOX_BUFFER_BYTES),
+    ...input,
+    '--no-show-progress',
+    '-r', String(AUDIO_FORMAT.SAMPLE_RATE),
+    '-c', String(AUDIO_FORMAT.CHANNELS),
+    '-b', '16',
+    '-e', 'signed-integer',
+    '-t', 'raw',
+    '-',
+  ]
+}
+
 interface AudioCaptureEvents {
  'audio-data': (payload: { buffer: Buffer; timestamp: number }) => void
  'audio-level': (payload: { level: number; timestamp: number }) => void
@ -59,6 +95,12 @@ class AudioCaptureService extends EventEmitter {
  private _soxProcess: ChildProcess | null = null
  private _stream: Readable | null = null
  private _levelInterval: ReturnType<typeof setInterval> | null = null
+  /** 새 SoX 를 띄울 때마다 증가 — 임대(lease)가 자기 캡처인지 판단한다 */
+  private _generation = 0
+  /** 진행 중인 꼬리 수집 정지의 토큰 (0 = 없음). start() 가 0 으로 만들어 정지를 취소한다 */
+  private _pendingStopToken = 0
+  private _stopSeq = 0
+  private _cancelTailWait: (() => void) | null = null

  /** 프레임 조립용 잔여 바이트 버퍼 */
  private _residualBuffer: Buffer = Buffer.alloc(0)
@ -83,6 +125,28 @@ class AudioCaptureService extends EventEmitter {
    return this._currentDevice
  }

+  /**
+   * 캡처 참조를 하나 잡고 임대(lease)로 돌려준다. 참조를 잡지 않은 쪽이 stop() 을 불러
+   * 다른 소비자(회의·자막·받아쓰기)의 참조를 빼앗는 일을 막는다.
+   */
+  async acquire(deviceId?: string): Promise<CaptureLease> {
+    await this.start(deviceId)
+    if (this._state !== 'capturing') {
+      throw new D3ROError(ErrorCode.AudioCaptureStartFailed, `Audio capture not running (state: ${this._state})`)
+    }
+    const generation = this._generation
+    let released = false
+    return {
+      release: async () => {
+        if (released) return
+        released = true
+        // 캡처가 죽었다가(장치 분리 등) 다시 시작됐으면 이 임대는 이미 무효다
+        if (this._generation !== generation) return
+        await this.stop()
+      },
+    }
+  }
+
  async start(deviceId?: string): Promise<void> {
    if (this._state === 'capturing') {
      this._refCount++
@ -90,6 +154,17 @@ class AudioCaptureService extends EventEmitter {
      return
    }

+    // 마지막 참조가 꼬리를 받는 중에 새 소비자가 오면 정지를 취소하고 같은 SoX 로 이어 간다
+    if (this._state === 'stopping' && this._pendingStopToken !== 0) {
+      this._pendingStopToken = 0
+      this._cancelTailWait?.()
+      this._state = 'capturing'
+      this._refCount = 1
+      this._startLevelTimer()
+      logger.debug('Pending stop cancelled by a new consumer — capture continues')
+      return
+    }
+
    if (this._state !== 'idle' && this._state !== 'error') {
      logger.warn(`Cannot start capture in state: ${this._state}`)
      return
@ -119,33 +194,15 @@ class AudioCaptureService extends EventEmitter {
        ? selectedDeviceId
        : 'default'

-      // Windows: sox -t waveaudio <device> --no-show-progress -r 16000 -c 1 -b 16 -e signed-integer -t raw -
-      // Linux/Mac: sox -d --no-show-progress ...
-      const soxArgs = process.platform === 'win32'
-        ? [
-            '-t', 'waveaudio', deviceArg,
-            '--no-show-progress',
-            '-r', String(AUDIO_FORMAT.SAMPLE_RATE),
-            '-c', String(AUDIO_FORMAT.CHANNELS),
-            '-b', '16',
-            '-e', 'signed-integer',
-            '-t', 'raw',
-            '-',
-          ]
-        : [
-            '-d',
-            '--no-show-progress',
-            '-r', String(AUDIO_FORMAT.SAMPLE_RATE),
-            '-c', String(AUDIO_FORMAT.CHANNELS),
-            '-b', '16',
-            '-e', 'signed-integer',
-            '-t', 'raw',
-            '-',
-          ]
+      // Windows: sox --buffer 1024 -t waveaudio <device> --no-show-progress -r 16000 -c 1 -b 16 -e signed-integer -t raw -
+      // Linux/Mac: sox --buffer 1024 -d --no-show-progress ...
+      const soxArgs = buildSoxRecordArgs(deviceArg)

      logger.info(`SoX args: ${soxArgs.join(' ')}`)
-      this._soxProcess = spawn(soxExe, soxArgs, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
-      this._stream = this._soxProcess.stdout
+      const child = spawn(soxExe, soxArgs, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+      this._soxProcess = child
+      this._generation++
+      this._stream = child.stdout
      this._residualBuffer = Buffer.alloc(0)
      this._levelAccumulator = []

@ -159,13 +216,16 @@ class AudioCaptureService extends EventEmitter {
      })

      // SoX stderr → 로그
-      this._soxProcess.stderr?.on('data', (chunk: Buffer) => {
+      child.stderr?.on('data', (chunk: Buffer) => {
        const msg = chunk.toString().trim()
        if (msg) logger.warn(`SoX stderr: ${msg}`)
      })

-      // SoX 프로세스 종료 감지
-      this._soxProcess.on('close', (code) => {
+      // SoX 프로세스 종료 감지.
+      // 자기 프로세스인지 먼저 확인한다 — 예전엔 kill 한 옛 SoX 의 'close' 가 몇 ms 뒤에 와서
+      // 그사이 시작된 새 캡처('capturing')를 오류로 끝냈다(회의 중 마이크 테스트로 회의 마이크가 끊김).
+      child.on('close', (code) => {
+        if (this._soxProcess !== child) return
        if (this._state === 'capturing') {
          logger.warn(`SoX process exited unexpectedly (code: ${code})`)
          this._handleError(
@ -175,7 +235,8 @@ class AudioCaptureService extends EventEmitter {
        }
      })

-      this._soxProcess.on('error', (err: Error) => {
+      child.on('error', (err: Error) => {
+        if (this._soxProcess !== child) return
        logger.error(`SoX process spawn error: ${err.message}`)
        const hint =
          soxExe === 'sox' && (err as NodeJS.ErrnoException).code === 'ENOENT'
@ -197,9 +258,7 @@ class AudioCaptureService extends EventEmitter {
      this._refCount = 1

      // 100ms 간격으로 audio-level 이벤트 emit
-      this._levelInterval = setInterval(() => {
-        this._emitAudioLevel()
-      }, TIMING.AUDIO_LEVEL_INTERVAL)
+      this._startLevelTimer()

      this.emit('started', { deviceId: this._currentDevice.deviceId })
      logger.info('Audio capture started')
@ -225,7 +284,17 @@ class AudioCaptureService extends EventEmitter {
      return
    }

+    // 곧바로 kill 하면 SoX 버퍼·파이프에 남은 끝부분(끝 음절)이 버려진다.
+    // 잠깐 더 읽어 소비자에게 흘려보낸 뒤 정리한다. 그사이 start() 가 오면 정지를 취소한다.
    this._state = 'stopping'
+    this._stopLevelTimer()
+    const token = ++this._stopSeq
+    this._pendingStopToken = token
+    await this._waitForTail()
+    if (this._pendingStopToken !== token || this._state !== 'stopping') return
+    this._pendingStopToken = 0
+
+    this._emitResidual()
    this._cleanup()
    this._state = 'idle'
    this._currentDevice = null
@ -233,6 +302,48 @@ class AudioCaptureService extends EventEmitter {
    logger.info('Audio capture stopped')
  }

+  /** TAIL_FLUSH_MS 만큼(또는 SoX 가 먼저 끝날 때까지, 또는 정지가 취소될 때까지) 기다린다 */
+  private _waitForTail(): Promise<void> {
+    const child = this._soxProcess
+    return new Promise<void>((resolve) => {
+      let done = false
+      const finish = (): void => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        child?.off('close', finish)
+        if (this._cancelTailWait === finish) this._cancelTailWait = null
+        resolve()
+      }
+      const timer = setTimeout(finish, TAIL_FLUSH_MS)
+      child?.once('close', finish)
+      this._cancelTailWait = finish
+    })
+  }
+
+  /** 60ms 프레임에 못 미친 잔여 바이트를 마지막 프레임으로 내보낸다 (샘플 경계로 자름) */
+  private _emitResidual(): void {
+    const usable = this._residualBuffer.length - (this._residualBuffer.length % AUDIO_FORMAT.BYTES_PER_SAMPLE)
+    if (usable <= 0) return
+    const frame = Buffer.from(this._residualBuffer.subarray(0, usable))
+    this._residualBuffer = Buffer.alloc(0)
+    this.emit('audio-data', { buffer: frame, timestamp: Date.now() })
+  }
+
+  private _startLevelTimer(): void {
+    this._stopLevelTimer()
+    this._levelInterval = setInterval(() => {
+      this._emitAudioLevel()
+    }, TIMING.AUDIO_LEVEL_INTERVAL)
+  }
+
+  private _stopLevelTimer(): void {
+    if (this._levelInterval) {
+      clearInterval(this._levelInterval)
+      this._levelInterval = null
+    }
+  }
+
  async getDevices(): Promise<AudioDevice[]> {
    // 캐싱: 네이티브 프로세스 호출이 느리므로 한번만 실행
    if (this._cachedDevices) return this._cachedDevices
@ -378,6 +489,8 @@ class AudioCaptureService extends EventEmitter {
  }

  dispose(): void {
+    this._pendingStopToken = 0
+    this._cancelTailWait?.()
    this._cleanup()
    this._state = 'idle'
    this._currentDevice = null
@ -396,13 +509,7 @@ class AudioCaptureService extends EventEmitter {
      ? selectedDeviceId
      : 'default'

-    const soxArgs = process.platform === 'win32'
-      ? ['-t', 'waveaudio', deviceArg, '--no-show-progress',
-         '-r', String(AUDIO_FORMAT.SAMPLE_RATE), '-c', String(AUDIO_FORMAT.CHANNELS),
-         '-b', '16', '-e', 'signed-integer', '-t', 'raw', '-']
-      : ['-d', '--no-show-progress',
-         '-r', String(AUDIO_FORMAT.SAMPLE_RATE), '-c', String(AUDIO_FORMAT.CHANNELS),
-         '-b', '16', '-e', 'signed-integer', '-t', 'raw', '-']
+    const soxArgs = buildSoxRecordArgs(deviceArg)

    return new Promise((resolve, reject) => {
      const proc = spawn(soxExe, soxArgs, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
@ -505,6 +612,7 @@ class AudioCaptureService extends EventEmitter {

    this._cleanup()
    this._state = 'error'
+    this._refCount = 0
    this._currentDevice = null
    this.emit('error', { error })
    this.emit('stopped', { reason: stopReason })
@ -514,10 +622,7 @@ class AudioCaptureService extends EventEmitter {
   * 녹음 프로세스와 타이머를 정리한다.
   */
  private _cleanup(): void {
-    if (this._levelInterval) {
-      clearInterval(this._levelInterval)
-      this._levelInterval = null
-    }
+    this._stopLevelTimer()

    if (this._stream) {
      this._stream.removeAllListeners()
@ -525,12 +630,19 @@ class AudioCaptureService extends EventEmitter {
    }

    if (this._soxProcess) {
+      const child = this._soxProcess
+      this._soxProcess = null
+      // 이 프로세스의 늦은 'close'/'error' 가 다음 캡처를 건드리지 못하게 떼어 낸다.
+      // 'error' 는 리스너가 없으면 throw 하므로 빈 sink 를 남긴다.
+      child.removeAllListeners('close')
+      child.removeAllListeners('error')
+      child.on('error', () => { /* 정리된 프로세스의 늦은 에러 무시 */ })
+      child.stderr?.removeAllListeners('data')
      try {
-        this._soxProcess.kill()
+        child.kill()
      } catch {
        // 이미 종료된 프로세스 kill 시 에러 무시
      }
-      this._soxProcess = null
    }

    this._residualBuffer = Buffer.alloc(0)
--- a/apps/desktop/src/main/services/ScreenContextService.ts
+++ b/apps/desktop/src/main/services/ScreenContextService.ts
@ -1,6 +1,8 @@
 // src/main/services/ScreenContextService.ts
 // 활성 윈도우 정보 + 선택된 텍스트를 캡처하여 LLM 프롬프트에 컨텍스트로 제공한다.
 // Phase 10.2 스크린 컨텍스트. Speakly ContextService 참조.
+// 활성 창 조회는 ForegroundWindowPort(foreground-window-port.ts)에 맡긴다 — 이 서비스는 컨텍스트
+// 정책(무엇을 언제 캡처해 어떻게 프롬프트로 만드는가)만 소유한다.

 import { clipboard } from 'electron'
 import { getLogger } from './LoggerService'
@ -8,6 +10,11 @@ import { configGet, configSet } from './ConfigService'
 import { D3ROError, ErrorCode } from '@d3ro/core/errors'
 import type { ScreenContext, CaptureContextResult } from '@d3ro/core/types'
 import { waitForModifiersReleased } from './modifier-state'
+import {
+  createDefaultForegroundWindowPort,
+  isTerminalHost,
+  type ForegroundWindowPort,
+} from './foreground-window-port'

 const logger = getLogger('screen-context')

@ -30,6 +37,13 @@ interface NutKeyboard {
  Key: NutModule['Key']
 }

+export interface ScreenContextServiceDeps {
+  /** 포그라운드 창 조회 (기본: 플랫폼 어댑터) */
+  foreground?: ForegroundWindowPort
+  /** 복사 단축키 수정자 결정용 플랫폼 (기본: process.platform) */
+  platform?: NodeJS.Platform
+}
+
 // ============================================================
 // 클립보드 스냅샷 (TextInsertService와 동일 패턴)
 // ============================================================
@ -46,9 +60,16 @@ interface ClipboardSnapshot {
 // ScreenContextService
 // ============================================================

-class ScreenContextService {
+export class ScreenContextService {
  private _nutKeyboard: NutKeyboard | null = null
  private _nutLoadPromise: Promise<void> | null = null
+  private readonly _foreground: ForegroundWindowPort
+  private readonly _platform: NodeJS.Platform
+
+  constructor(deps: ScreenContextServiceDeps = {}) {
+    this._platform = deps.platform ?? process.platform
+    this._foreground = deps.foreground ?? createDefaultForegroundWindowPort(this._platform)
+  }

  /**
   * nut-js lazy dynamic import (TextInsertService 패턴).
@ -90,7 +111,7 @@ class ScreenContextService {
  /**
   * 활성 윈도우 정보 + 선택된 텍스트를 캡처한다.
   *
-   * @param captureSelectedText true이면 Ctrl+C로 선택 텍스트 캡처 시도
+   * @param captureSelectedText true이면 복사 단축키로 선택 텍스트 캡처 시도
   */
  async captureContext(captureSelectedText = true): Promise<CaptureContextResult> {
    const capturedAt = Date.now()
@ -99,9 +120,9 @@ class ScreenContextService {
    let selectedText: string | null = null
    let selectedTextAttempted = false

-    // 1. 활성 윈도우 정보 (PowerShell)
+    // 1. 활성 윈도우 정보 (ForegroundWindowPort)
    try {
-      const appInfo = await this._getActiveWindowInfo()
+      const appInfo = await this._foreground.current()
      appName = appInfo.appName
      windowTitle = appInfo.windowTitle
    } catch (error) {
@ -115,7 +136,7 @@ class ScreenContextService {
    if (captureSelectedText) {
      selectedTextAttempted = true
      try {
-        selectedText = await this.captureSelectedText()
+        selectedText = await this._captureSelectionIn(appName)
      } catch (error) {
        logger.warn(
          `Failed to capture selected text: ${error instanceof Error ? error.message : String(error)}`
@ -142,13 +163,30 @@ class ScreenContextService {
   * 선택된 텍스트만 캡처한다 (클립보드 방식).
   * 수정자 키가 눌려 있으면 뗄 때까지 잠깐 기다리고, 그래도 쥐고 있으면 캡처하지 않고 null 을
   * 돌려준다(클립보드도 건드리지 않는다).
+   * 포그라운드가 콘솔/터미널이면 복사 단축키를 보내지 않는다 — 선택이 없을 때 Ctrl+C 는
+   * 실행 중 프로세스를 중단(SIGINT)하거나 입력 줄을 지운다.
   */
  async captureSelectedText(): Promise<string | null> {
+    let foregroundApp: string | null = null
+    try {
+      foregroundApp = (await this._foreground.current()).appName
+    } catch {
+      // 조회 실패 시엔 앱을 모른 채 진행한다
+    }
+    return this._captureSelectionIn(foregroundApp)
+  }
+
+  /** 포그라운드 앱을 이미 알고 있을 때의 선택 텍스트 캡처 */
+  private async _captureSelectionIn(foregroundApp: string | null): Promise<string | null> {
    const released = await waitForModifiersReleased(MODIFIER_RELEASE_TIMEOUT_MS)
    if (!released) {
      logger.info('Selected text capture skipped: modifier keys still held')
      return null
    }
+    if (isTerminalHost(foregroundApp)) {
+      logger.info(`Selected text capture skipped: terminal host (${foregroundApp ?? 'unknown'})`)
+      return null
+    }
    return this._captureSelectedText()
  }

@ -202,132 +240,9 @@ class ScreenContextService {

  // ── 내부 구현 ─────────────────────────────────────────

-  /**
-   * 활성 윈도우의 프로세스명과 타이틀을 가져온다.
-   * - Windows: PowerShell + user32.dll
-   * - macOS: osascript (System Events)
-   * - Linux: 미지원 (null 반환)
-   *
-   * 참고: macOS는 Accessibility 권한이 필요하다. 첫 호출 시 시스템이
-   * 권한 요청 다이얼로그를 띄운다. 사용자가 거부하면 { null, null } 반환.
-   */
-  private async _getActiveWindowInfo(): Promise<{
-    appName: string | null
-    windowTitle: string | null
-  }> {
-    if (process.platform === 'win32') {
-      return this._getActiveWindowInfoWin32()
-    }
-    if (process.platform === 'darwin') {
-      return this._getActiveWindowInfoDarwin()
-    }
-    return { appName: null, windowTitle: null }
-  }
-
-  /**
-   * Windows: PowerShell + user32.dll로 활성 윈도우 조회.
-   */
-  private async _getActiveWindowInfoWin32(): Promise<{
-    appName: string | null
-    windowTitle: string | null
-  }> {
-    const { execFile } = await import('child_process')
-    const { promisify } = await import('util')
-    const execFileAsync = promisify(execFile)
-
-    const psScript = `
-Add-Type @"
-using System;
-using System.Runtime.InteropServices;
-using System.Text;
-public class Win32 {
-  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
-  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);
-  [DllImport("user32.dll", CharSet = CharSet.Unicode)] public static extern int GetWindowText(IntPtr hWnd, StringBuilder lpString, int nMaxCount);
-}
-"@
-$hwnd = [Win32]::GetForegroundWindow()
-$pid = 0
-[void][Win32]::GetWindowThreadProcessId($hwnd, [ref]$pid)
-$proc = Get-Process -Id $pid -ErrorAction SilentlyContinue
-$sb = New-Object System.Text.StringBuilder 512
-[void][Win32]::GetWindowText($hwnd, $sb, 512)
-$procName = if ($proc) { $proc.ProcessName } else { '' }
-$title = $sb.ToString()
-"$procName$([char]10)$title"
-`.trim()
-
-    try {
-      const { stdout } = await execFileAsync('powershell.exe', [
-        '-NoProfile',
-        '-NonInteractive',
-        '-ExecutionPolicy', 'Bypass',
-        '-Command', psScript,
-      ], { timeout: 3000, windowsHide: true })
-
-      const lines = stdout.trim().split('\n')
-      const appName = lines[0]?.trim() || null
-      const windowTitle = lines[1]?.trim() || null
-
-      return { appName, windowTitle }
-    } catch (error) {
-      logger.warn(
-        `PowerShell active window query failed: ${error instanceof Error ? error.message : String(error)}`
-      )
-      return { appName: null, windowTitle: null }
-    }
-  }
-
-  /**
-   * macOS: osascript (AppleScript)로 frontmost process와 윈도우 타이틀 조회.
-   * Accessibility 권한 필요.
-   */
-  private async _getActiveWindowInfoDarwin(): Promise<{
-    appName: string | null
-    windowTitle: string | null
-  }> {
-    const { execFile } = await import('child_process')
-    const { promisify } = await import('util')
-    const execFileAsync = promisify(execFile)
-
-    // AppleScript: 프로세스명과 앞 윈도우 타이틀을 2줄로 반환.
-    // 윈도우가 없는 앱도 있으므로 try-fallback.
-    const script = `
-try
-  tell application "System Events"
-    set frontApp to first process whose frontmost is true
-    set appName to name of frontApp
-    try
-      set winTitle to name of front window of frontApp
-    on error
-      set winTitle to ""
-    end try
-    return appName & linefeed & winTitle
-  end tell
-on error errMsg
-  return "" & linefeed & ""
-end try
-`.trim()
-
-    try {
-      const { stdout } = await execFileAsync('/usr/bin/osascript', ['-e', script], {
-        timeout: 3000
-      })
-      const lines = stdout.split('\n')
-      const appName = lines[0]?.trim() || null
-      const windowTitle = lines[1]?.trim() || null
-      return { appName, windowTitle }
-    } catch (error) {
-      logger.warn(
-        `osascript active window query failed: ${error instanceof Error ? error.message : String(error)}`
-      )
-      return { appName: null, windowTitle: null }
-    }
-  }
-
  /**
   * 선택된 텍스트를 클립보드 방식으로 캡처한다.
-   * TextInsertService의 역방향: clipboard save → Ctrl+C simulate → clipboard read → clipboard restore
+   * TextInsertService의 역방향: clipboard save → 복사 단축키 simulate → clipboard read → clipboard restore
   */
  private async _captureSelectedText(): Promise<string | null> {
    const nut = await this._ensureNut()
@ -339,9 +254,10 @@ end try
      // 2. 클립보드 비우기 (이전 내용이 남아있으면 "선택 없음"을 감지할 수 없으므로)
      clipboard.clear()

-      // 3. Ctrl+C 시뮬레이션
-      await nut.pressKey(nut.Key.LeftControl, nut.Key.C)
-      await nut.releaseKey(nut.Key.LeftControl, nut.Key.C)
+      // 3. 복사 단축키 시뮬레이션 (macOS ⌘+C, 그 외 Ctrl+C)
+      const modifier = this._platform === 'darwin' ? nut.Key.LeftSuper : nut.Key.LeftControl
+      await nut.pressKey(modifier, nut.Key.C)
+      await nut.releaseKey(modifier, nut.Key.C)

      // 4. 클립보드에 텍스트가 복사될 때까지 대기
      await this._sleep(150)
--- a/apps/desktop/src/main/services/VoiceModeService.ts
+++ b/apps/desktop/src/main/services/VoiceModeService.ts
@ -35,6 +35,13 @@ import { TIMING } from '@d3ro/core/constants'
 import { RecognitionState, AudioState } from '@d3ro/core/types'
 import type { KeyBindingActionId, VoiceMode, VoiceState, LLMAction } from '@d3ro/core/types'
 import type { ScreenContext } from '@d3ro/core/types'
+import { resolveVoiceLlmRoute, routeUsesLlm, type VoiceLlmRoute } from '@d3ro/core/voice-llm-route'
+import {
+  deriveVoiceIntentPhase,
+  resolveGestureHoldMode,
+  resolveGestureMode,
+  resolveVoiceIntent,
+} from './voice-intent'

 const logger = getLogger('VoiceModeService')

@ -126,6 +133,8 @@ class SessionRun {
  /** 스크린 컨텍스트: 선택 텍스트 캡처 여부와 진행 중 작업 */
  captureSelection = false
  selectionCapture: Promise<string | null> | null = null
+  /** 스크린 컨텍스트: 녹음 시작 시점 활성 창 조회 (기다리지 않고 LLM 단계에서 합친다) */
+  windowContext: Promise<ScreenContext | null> | null = null

  dataHandler: ((payload: { buffer: Buffer }) => void) | null = null
  levelHandler: ((payload: { level: number }) => void) | null = null
@ -169,6 +178,19 @@ function describe(err: unknown): string {
  return err instanceof Error ? err.message : String(err)
 }

+/** LLM 을 실제로 부르는 경로 */
+type LlmProcessingRoute = Exclude<VoiceLlmRoute, { kind: 'insert-raw' }>
+
+/**
+ * 정지 요청의 결과. 오디오 해제까지는 요청 안에서 끝나고, 전사·LLM 후처리는 `finished` 로 따로 돈다.
+ * (async 함수가 Promise 를 반환하면 펼쳐지므로 객체로 감싼다)
+ */
+interface StopOutcome {
+  finished: Promise<void>
+}
+
+const NOTHING_PENDING: StopOutcome = { finished: Promise.resolve() }
+
 // ============================================================
 // VoiceModeService
 // ============================================================
@ -229,11 +251,11 @@ class VoiceModeService extends EventEmitter {
          return
      }

-      const holdMode = this._resolveHoldMode(payload.actionId, payload.holdMode)
+      const holdMode = resolveGestureHoldMode(payload.actionId, payload.holdMode)
      const action: VoiceAction = {
        type: payload.type === 'pressed' ? 'press' : 'release',
        timestamp: payload.timestamp,
-        mode: this._resolveMode(payload.actionId, payload.isDoublePress),
+        mode: resolveGestureMode(payload.actionId, payload.isDoublePress),
        actionId: payload.actionId,
        holdMode
      }
@ -300,16 +322,23 @@ class VoiceModeService extends EventEmitter {
    // 선택 텍스트(Ctrl+C)는 여기서 보내지 않는다: 이 시점엔 사용자가 아직 핫키(기본 Right Alt)를
    // 누르고 있어 대상 앱에 Ctrl+Alt+C 가 들어가고(복사 안 됨, AltGr 배열에선 문자 입력),
    // 클립보드만 비워진다. 선택 텍스트는 녹음 종료(키를 뗀 뒤)에 캡처한다.
-    let screenContext: ScreenContext | null = null
-    let captureSelection = false
+    // 활성 창 조회는 기다리지 않는다 — 예전엔 조회(PowerShell, 0.7~3초)가 세션·마이크 시작 앞을
+    // 막아 첫 말이 잘리고 짧은 hold-to-talk 가 'too-short' 로 취소됐다. 결과는 LLM 단계에서 합친다.
+    let windowContext: Promise<ScreenContext | null> | null = null
    try {
      const { getScreenContextService } = await import('./ScreenContextService')
      const ctx = getScreenContextService()
      if (ctx.isEnabled()) {
-        captureSelection = true
-        const result = await ctx.captureContext(false)
-        screenContext = result.context
-        logger.info(`Screen context captured: ${screenContext.appName ?? 'unknown'}`)
+        windowContext = ctx.captureContext(false).then(
+          (result) => {
+            logger.info(`Screen context captured: ${result.context.appName ?? 'unknown'}`)
+            return result.context
+          },
+          (err: unknown) => {
+            logger.debug(`Screen context capture skipped: ${describe(err)}`)
+            return null
+          },
+        )
      }
    } catch {
      // 컨텍스트 캡처 실패 시 무시 — 핵심 기능 아님
@ -320,7 +349,8 @@ class VoiceModeService extends EventEmitter {

    // 세션 생성
    const run = new SessionRun(randomUUID())
-    run.captureSelection = captureSelection
+    run.captureSelection = windowContext !== null
+    run.windowContext = windowContext
    this._run = run
    this._session = {
      id: run.id,
@ -332,7 +362,7 @@ class VoiceModeService extends EventEmitter {
      transcription: '',
      processedText: null,
      accidentalPress: false,
-      screenContext,
+      screenContext: null,
    }

    this._setRecognitionState(RecognitionState.PREPARING)
@ -360,16 +390,30 @@ class VoiceModeService extends EventEmitter {
    await this._startAudio(run)
  }

+  /**
+   * 세션을 정지하고 전사·후처리가 끝날 때까지 기다린다 (IPC 등 공개 API).
+   * 키 입력 경로는 _requestStop 만 기다려 액션 큐를 막지 않는다.
+   */
  async stopSession(): Promise<void> {
+    const { finished } = await this._requestStop()
+    await finished
+  }
+
+  /**
+   * 정지 요청과 오디오 해제까지만 수행한다. 전사·LLM 은 run 에 묶어 `finished` 로 따로 돈다.
+   * 예전엔 정지가 STT·LLM 전체(수 초)를 await 해 액션 큐를 막았고, 그사이 들어온 입력이
+   * 세션이 끝난 뒤 다른 의미로 재생됐다(더블탭 정지의 두 번째 탭이 새 핸즈프리 녹음을 시작).
+   */
+  private async _requestStop(): Promise<StopOutcome> {
    const run = this._run
    const session = this._session
-    if (!run || !session || !this._isCurrent(run) || this._isInTerminalState()) return
+    if (!run || !session || !this._isCurrent(run) || this._isInTerminalState()) return NOTHING_PENDING

    // 정지는 세션당 한 번이다. 지연 전사가 도는 중에 두 번째 release/토글이 오면
    // 예전엔 비어 있는 버퍼를 보고 'too-short' 로 조용히 취소해 받아쓰기를 잃었다.
    if (run.stopRequested) {
      logger.info('Stop already requested for this session — ignoring')
-      return
+      return NOTHING_PENDING
    }
    run.stopRequested = true

@ -380,23 +424,29 @@ class VoiceModeService extends EventEmitter {
      session.accidentalPress = true
      logger.info(`Accidental press detected (${duration}ms < ${TIMING.MIN_AUDIO_DURATION}ms)`)
      this._cancelSession('too-short')
-      return
+      return NOTHING_PENDING
    }

    // 오디오 캡처 중지
    this._setAudioState(AudioState.STOPPED)
    await this._releaseAudio(run)
-    if (!this._isCurrent(run)) return
+    if (!this._isCurrent(run)) return NOTHING_PENDING

    // Speakly 패턴: 녹음 종료 후 thinking 상태로 전환
    this.emit('phase', { phase: 'thinking', sessionId: run.id })

-    // 핫키를 뗀 뒤라 Ctrl+C 가 안전하다 — 전사와 병렬로 선택 텍스트를 캡처한다
-    this._startSelectionCapture(run)
+    // 핫키를 뗀 뒤라 복사 단축키가 안전하다 — LLM 이 쓸 것이 확실하면 전사와 병렬로 선택 텍스트를
+    // 캡처한다. 원문 삽입 경로(none·LLM 불가)에선 보내지 않는다: 쓰지도 않을 Ctrl+C 가 터미널에선
+    // 프로세스를 중단시킨다. 음성 단축키로 LLM 경로가 될 수도 있으면 LLM 단계에서 늦게 캡처한다.
+    if (routeUsesLlm(this._resolveLlmRoute(null))) this._startSelectionCapture(run)

    // 버퍼가 있으면 STT에 전달
    if (run.audioBuffer.length > 0 && run.sttReady) {
-      await this._transcribe(run)
+      return {
+        finished: this._transcribe(run).catch((err: unknown) => {
+          logger.error(`Unhandled error in _transcribe after stop: ${describe(err)}`)
+        }),
+      }
    } else if (run.audioBuffer.length > 0 && !run.sttReady) {
      // STT 아직 준비 안 됨 → _initSTT 완료 후 _tryFlushAll이 전사
      logger.info('Waiting for STT to be ready before transcribing')
@ -415,6 +465,7 @@ class VoiceModeService extends EventEmitter {
      logger.warn('No audio buffer, cancelling session')
      this._cancelSession('too-short')
    }
+    return NOTHING_PENDING
  }

  cancelSession(): void {
@ -601,17 +652,28 @@ class VoiceModeService extends EventEmitter {
   */
  private async _releaseAudio(run: SessionRun): Promise<void> {
    run.audioReleaseRequested = true
-    this._detachAudioHandlers(run)
-    run.audioStarted = false
    this._stopPartialLoop(run)

-    if (!run.audioAcquired) return
-    run.audioAcquired = false
-    try {
-      await getAudioCaptureService().stop()
-    } catch (error) {
-      logger.warn(`Audio stop error: ${describe(error)}`)
+    // 현재 세션의 정상 정지면 캡처가 꼬리 오디오(SoX 버퍼에 남은 끝 음절)를 흘려보낼 때까지
+    // 핸들러를 붙여 둔다 — 먼저 떼면 그 끝부분을 잃는다. 취소·교체된 run 은 꼬리가 필요 없다.
+    // (그동안 audioStarted 를 유지해 _tryFlushAll 이 전사를 앞당기지 않게 한다)
+    const keepForTail = run.audioAcquired && this._isCurrent(run)
+    if (!keepForTail) {
+      this._detachAudioHandlers(run)
+      run.audioStarted = false
    }
+
+    if (run.audioAcquired) {
+      run.audioAcquired = false
+      try {
+        await getAudioCaptureService().stop()
+      } catch (error) {
+        logger.warn(`Audio stop error: ${describe(error)}`)
+      }
+    }
+
+    this._detachAudioHandlers(run)
+    run.audioStarted = false
  }

  // ── 스크린 컨텍스트(선택 텍스트) ─────────────────────────
@ -629,18 +691,37 @@ class VoiceModeService extends EventEmitter {
    })()
  }

-  /** 선택 텍스트 캡처가 끝나기를 기다렸다가 세션 컨텍스트에 합친다. */
-  private async _applySelectionCapture(run: SessionRun): Promise<void> {
-    if (!run.selectionCapture) return
-    const selectedText = await run.selectionCapture
-    if (!selectedText || !this._isCurrent(run) || !this._session) return
-    const base: ScreenContext = this._session.screenContext ?? {
+  /**
+   * 활성 창 조회(녹음 시작 시점)와 선택 텍스트 캡처(정지 시점)가 끝나기를 기다렸다가
+   * 세션 컨텍스트로 합친다.
+   */
+  private async _applyScreenContext(run: SessionRun): Promise<void> {
+    if (!run.windowContext && !run.selectionCapture) return
+    const [windowContext, selectedText] = await Promise.all([
+      run.windowContext ?? Promise.resolve(null),
+      run.selectionCapture ?? Promise.resolve(null),
+    ])
+    if (!this._isCurrent(run) || !this._session) return
+    if (!windowContext && !selectedText) return
+    const base: ScreenContext = windowContext ?? this._session.screenContext ?? {
      appName: null,
      windowTitle: null,
      selectedText: null,
      capturedAt: Date.now(),
    }
-    this._session.screenContext = { ...base, selectedText }
+    this._session.screenContext = selectedText ? { ...base, selectedText } : base
+  }
+
+  /** 세션 컨텍스트를 LLM 입력 접두사로 만든다 (없으면 빈 문자열) */
+  private async _buildContextPrefix(): Promise<string> {
+    const screenContext = this._session?.screenContext
+    if (!screenContext) return ''
+    try {
+      const { getScreenContextService } = await import('./ScreenContextService')
+      return getScreenContextService().buildContextPrompt(screenContext)
+    } catch {
+      return ''
+    }
  }

  // ── 실시간 부분 전사(미리보기) ─────────────────────────────
@ -806,7 +887,6 @@ class VoiceModeService extends EventEmitter {

      // Phase 10.5: 음성 단축키 — 키워드 매칭으로 LLM 명령어 자동 선택
      let effectiveText = result.text
-      let overrideAction: string | null = null
      let overrideInstructionId: string | null = null
      try {
        const { getVoiceCommandService } = await import('./VoiceCommandService')
@ -815,7 +895,6 @@ class VoiceModeService extends EventEmitter {
          const match = vcSvc.match(result.text)
          if (match.matched && match.instructionId) {
            effectiveText = match.cleanedText
-            overrideAction = 'custom'
            overrideInstructionId = match.instructionId
            logger.info(`Voice command matched: keyword="${match.matchedKeyword}", instruction=${match.instructionId}`)
          }
@ -825,12 +904,9 @@ class VoiceModeService extends EventEmitter {
      }
      if (!this._isCurrent(run)) return

-      const llmAction = overrideAction ?? configGet('defaultLLMAction')
-      const backend = configGet('llmBackend')
-      const ollamaUnavailable = backend === 'local' && !getLocalLLMService().isAvailable()
-      const skipLLM = llmAction === 'none' || ollamaUnavailable
-      if (skipLLM) {
-        if (llmAction !== 'none' && ollamaUnavailable) {
+      const route = this._resolveLlmRoute(overrideInstructionId)
+      if (route.kind === 'insert-raw') {
+        if (route.reason === 'llm-unavailable') {
          this.emit('error', {
            error: new D3ROError(
              ErrorCode.LLMServerUnreachable,
@ -842,7 +918,7 @@ class VoiceModeService extends EventEmitter {
        }
        void this._completeSession(run, effectiveText)
      } else {
-        await this._processWithLLM(run, effectiveText, overrideInstructionId)
+        await this._processWithLLM(run, effectiveText, route)
      }
    } catch (error) {
      if (!this._isCurrent(run)) return
@ -874,50 +950,42 @@ class VoiceModeService extends EventEmitter {
    })
  }

+  /** 현재 설정으로 LLM 후처리 경로를 결정한다 (정책은 @d3ro/core/voice-llm-route 가 소유) */
+  private _resolveLlmRoute(overrideInstructionId: string | null): VoiceLlmRoute {
+    const backend = configGet('llmBackend')
+    return resolveVoiceLlmRoute({
+      defaultAction: configGet('defaultLLMAction'),
+      overrideInstructionId,
+      activeChainId: configGet('activeChainId') ?? null,
+      activeInstructionId: configGet('activeInstructionId') ?? null,
+      localLlmAvailable: backend === 'local' ? getLocalLLMService().isAvailable() : true,
+      backend,
+    })
+  }
+
  private async _processWithLLM(
    run: SessionRun,
    transcribedText: string,
-    overrideInstructionId?: string | null,
+    route: LlmProcessingRoute,
  ): Promise<void> {
    if (!this._isCurrent(run)) return

    try {
-      const configuredAction = configGet('defaultLLMAction')
-      // 음성 단축키가 특정 명령을 지목해 들어왔다면 기본 액션이 'none'이어도 처리한다.
-      // 명시적 요청을 기본 설정이 무효화하면 안 된다.
-      if (configuredAction === 'none' && !overrideInstructionId) {
-        void this._completeSession(run, transcribedText)
-        return
-      }
-
-      // 여기서 'none'이 남아 있다면 overrideInstructionId가 반드시 있다 → custom 경로.
-      const action: LLMAction = configuredAction === 'none' ? 'custom' : configuredAction
-
-      // Phase 10.2: 스크린 컨텍스트를 LLM 프롬프트에 주입 (선택 텍스트는 정지 시점 캡처)
-      await this._applySelectionCapture(run)
+      // Phase 10.2: 스크린 컨텍스트를 LLM 프롬프트에 주입 (선택 텍스트는 정지 이후 캡처).
+      // 정지 시점에 LLM 경로가 확실하지 않아 캡처를 미뤘다면 여기서 시작한다(멱등).
+      this._startSelectionCapture(run)
+      await this._applyScreenContext(run)
      if (!this._isCurrent(run)) return
-      let contextPrefix = ''
-      if (this._session?.screenContext) {
-        try {
-          const { getScreenContextService } = await import('./ScreenContextService')
-          contextPrefix = getScreenContextService().buildContextPrompt(this._session.screenContext)
-        } catch {
-          // 무시
-        }
-      }
+      const userText = (await this._buildContextPrefix()) + transcribedText

      // Phase 10.4: 체인 모드 처리
-      if (action === 'chain') {
+      if (route.kind === 'chain') {
        try {
          const { getChainService } = await import('./ChainService')
-          const activeChainId = configGet('activeChainId')
-          if (activeChainId) {
-            const chainResult = await getChainService().execute(activeChainId, contextPrefix + transcribedText)
-            if (!this._isCurrent(run)) return
-            if (this._session) this._session.processedText = chainResult.finalText
-            void this._completeSession(run, chainResult.finalText)
-            return
-          }
+          const chainResult = await getChainService().execute(route.chainId, userText)
+          if (!this._isCurrent(run)) return
+          if (this._session) this._session.processedText = chainResult.finalText
+          void this._completeSession(run, chainResult.finalText)
        } catch (error) {
          if (!this._isCurrent(run)) return
          logger.warn(`Chain execution failed: ${describe(error)}`)
@ -927,60 +995,14 @@ class VoiceModeService extends EventEmitter {
              ? error
              : new D3ROError(ErrorCode.ChainExecutionFailed, `Chain execution failed: ${describe(error)}`),
          )
-          return
        }
+        return
      }

-      let processedText: string
-
-      // 음성 단축키 오버라이드 또는 활성 명령어
-      const effectiveInstructionId = overrideInstructionId
-        ?? configGet('activeInstructionId')
-
-      const targetLanguage = resolveTargetLanguage()
-
-      if (action === 'custom' || overrideInstructionId) {
-        const userText = contextPrefix + transcribedText
-        let invocationText = userText
-        let instructionPrompt: string | undefined
-
-        if (effectiveInstructionId) {
-          const { getCustomInstructionService } = await import('./CustomInstructionService')
-          const instruction = getCustomInstructionService().getById(effectiveInstructionId)
-          if (instruction) {
-            const invocation = buildInstructionInvocation(
-              instruction.prompt,
-              userText,
-              targetLanguage,
-            )
-            invocationText = invocation.text
-            instructionPrompt = invocation.systemPrompt
-            logger.info(`Using custom instruction: "${instruction.name}"`)
-          } else {
-            logger.warn(
-              `Custom instruction not found: ${effectiveInstructionId} — processing without an instruction`,
-            )
-          }
-        }
-
-        processedText = await this._runProcessorWithFallback(
-          invocationText,
-          'custom',
-          undefined,
-          instructionPrompt,
-        )
-      } else {
-        logger.info(
-          action === 'translate'
-            ? `Processing with LLM (action: ${action}, targetLanguage: ${targetLanguage})`
-            : `Processing with LLM (action: ${action})`,
-        )
-        processedText = await this._runProcessorWithFallback(
-          contextPrefix + transcribedText,
-          action,
-          action === 'translate' ? targetLanguage : undefined,
-        )
-      }
+      const processedText =
+        route.kind === 'instruction'
+          ? await this._processWithInstruction(userText, route.instructionId)
+          : await this._processWithAction(userText, route.action)

      if (!this._isCurrent(run)) return

@ -1003,6 +1025,45 @@ class VoiceModeService extends EventEmitter {
    }
  }

+  /** 지시문(음성 단축키 또는 활성 지시문)으로 처리한다. 지시문이 없으면 지시문 없이 custom 처리 */
+  private async _processWithInstruction(userText: string, instructionId: string | null): Promise<string> {
+    let invocationText = userText
+    let instructionPrompt: string | undefined
+
+    if (instructionId) {
+      const { getCustomInstructionService } = await import('./CustomInstructionService')
+      const instruction = getCustomInstructionService().getById(instructionId)
+      if (instruction) {
+        const invocation = buildInstructionInvocation(instruction.prompt, userText, resolveTargetLanguage())
+        invocationText = invocation.text
+        instructionPrompt = invocation.systemPrompt
+        logger.info(`Using custom instruction: "${instruction.name}"`)
+      } else {
+        logger.warn(`Custom instruction not found: ${instructionId} — processing without an instruction`)
+      }
+    }
+
+    return this._runProcessorWithFallback(invocationText, 'custom', undefined, instructionPrompt)
+  }
+
+  /** 일반 액션(refine/translate/…)으로 처리한다 */
+  private async _processWithAction(
+    userText: string,
+    action: Extract<LlmProcessingRoute, { kind: 'action' }>['action'],
+  ): Promise<string> {
+    const targetLanguage = resolveTargetLanguage()
+    logger.info(
+      action === 'translate'
+        ? `Processing with LLM (action: ${action}, targetLanguage: ${targetLanguage})`
+        : `Processing with LLM (action: ${action})`,
+    )
+    return this._runProcessorWithFallback(
+      userText,
+      action,
+      action === 'translate' ? targetLanguage : undefined,
+    )
+  }
+
  // ── 세션 완료/취소 ─────────────────────────────────────

  private async _completeSession(run: SessionRun, finalText: string): Promise<void> {
@ -1161,10 +1222,8 @@ class VoiceModeService extends EventEmitter {
    try {
      switch (action.type) {
        case 'press':
-          await this._handlePress(action)
-          break
        case 'release':
-          await this._handleRelease(action)
+          await this._handleGesture(action)
          break
        case 'escape':
          this.cancelSession()
@ -1175,48 +1234,29 @@ class VoiceModeService extends EventEmitter {
    }
  }

-  private async _handlePress(action: VoiceAction): Promise<void> {
-    if (action.mode === 'dictation') {
-      // Dictation: hold-to-talk — press로 시작
-      if (!this.isActive) {
-        await this.startSession('dictation')
-      }
-    } else if (action.mode === 'hands-free') {
-      // HandsFree: toggle
-      if (this.isActive) {
-        await this.stopSession()
-      } else {
-        await this.startSession('hands-free')
-      }
-    }
-  }
-
-  private async _handleRelease(action: VoiceAction): Promise<void> {
-    if (action.holdMode && action.mode === 'dictation' && this.isActive) {
-      // Dictation: hold-to-talk — release로 즉시 종료
-      // Speakly 패턴: 딜레이 없이 즉시 stop (딜레이가 race condition 유발)
-      await this.stopSession()
-    }
-    // HandsFree(토글): release 무시
-  }
-
-  // ── 유틸리티 ───────────────────────────────────────────
-
-  private _resolveMode(actionId: KeyBindingActionId, isDoublePress: boolean): VoiceMode {
-    if (actionId === 'hands-free' || isDoublePress) {
-      return 'hands-free'
-    }
-    return 'dictation'
-  }
-
  /**
-   * 'command' 액션에는 아직 전용 핸들러가 없다.
-   * 현행 동작대로 dictation 파이프라인으로 fallback 하며, 그 경로는 hold-to-talk 이므로
-   * KEYBINDING_ACTIONS 의 holdMode(false)가 아니라 dictation 과 같은 값을 쓴다.
+   * 키 제스처를 세션 의도로 바꿔(voice-intent) 실행한다.
+   * 정지는 오디오 해제까지만 기다린다 — 전사·LLM 동안 큐가 풀려 있어야 처리 중에 들어온 토글이
+   * 'processing' 단계에서 무시되고, 세션이 끝난 뒤 새 녹음으로 재생되지 않는다.
   */
-  private _resolveHoldMode(actionId: KeyBindingActionId, specHoldMode: boolean): boolean {
-    if (actionId === 'command') return true
-    return specHoldMode
+  private async _handleGesture(action: VoiceAction): Promise<void> {
+    if (action.type === 'escape') return
+    const phase = deriveVoiceIntentPhase(this.isActive, this._run?.stopRequested ?? false)
+    const intent = resolveVoiceIntent(
+      { type: action.type, mode: action.mode, holdMode: action.holdMode },
+      phase,
+    )
+    switch (intent.kind) {
+      case 'start':
+        await this.startSession(intent.mode)
+        break
+      case 'stop':
+        // Speakly 패턴: 딜레이 없이 즉시 stop (딜레이가 race condition 유발)
+        await this._requestStop()
+        break
+      case 'ignore':
+        break
+    }
  }

  // ── 자막 모드 토글 (Phase 10.1) ─────────────────────────
--- a/apps/desktop/src/main/services/foreground-window-port.ts
+++ b/apps/desktop/src/main/services/foreground-window-port.ts
@ -0,0 +1,156 @@
+// src/main/services/foreground-window-port.ts
+// 포그라운드(활성) 창 조회 포트와 플랫폼 어댑터.
+//
+// ScreenContextService(컨텍스트 정책)는 "지금 앞에 있는 앱이 무엇인가"만 알면 되고, 그것을 어떻게
+// 읽는지(FFI, AppleScript)는 알 필요가 없다. 예전엔 서비스가 PowerShell + Add-Type 스크립트를 직접
+// 들고 있었다 — koffi 리더(utils/win32-foreground.ts)와 중복이었고, 그 사본은 읽기 전용 $PID 에
+// 대입하는 버그로 앱 이름이 늘 'powershell' 이었으며, 호출마다 0.7~3초가 걸렸다.
+
+import { getLogger } from './LoggerService'
+import { getForegroundWindowInfo, type ForegroundWindowInfo } from '../utils/win32-foreground'
+
+const logger = getLogger('foreground-window')
+
+export interface ActiveWindowInfo {
+  /** 프로세스 이름 (확장자 없음, 예: 'chrome'). 알 수 없으면 null */
+  appName: string | null
+  /** 창 제목. 알 수 없으면 null */
+  windowTitle: string | null
+}
+
+/** 포그라운드 창 조회 포트. macOS(osascript)는 비동기라 Promise 로 통일한다. */
+export interface ForegroundWindowPort {
+  current(): Promise<ActiveWindowInfo>
+}
+
+const UNKNOWN: ActiveWindowInfo = { appName: null, windowTitle: null }
+
+function blankToNull(value: string | null | undefined): string | null {
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : null
+}
+
+/** 'Code.exe' → 'Code'. 예전 PowerShell 경로(Process.ProcessName)와 같은 모양을 유지한다. */
+export function toProcessName(exeName: string): string {
+  return exeName.replace(/\.exe$/iu, '')
+}
+
+/** Windows: koffi FFI 리더(동기, 수 ms)를 감싼다. */
+export function createWin32ForegroundWindowPort(
+  read: () => ForegroundWindowInfo | null = getForegroundWindowInfo,
+): ForegroundWindowPort {
+  return {
+    async current() {
+      const info = read()
+      if (!info) return UNKNOWN
+      return {
+        appName: blankToNull(toProcessName(info.appName)),
+        windowTitle: blankToNull(info.title),
+      }
+    },
+  }
+}
+
+type ExecFileText = (
+  file: string,
+  args: string[],
+  options: { timeout: number },
+) => Promise<{ stdout: string }>
+
+async function defaultExecFileText(
+  file: string,
+  args: string[],
+  options: { timeout: number },
+): Promise<{ stdout: string }> {
+  const { execFile } = await import('child_process')
+  const { promisify } = await import('util')
+  const { stdout } = await promisify(execFile)(file, args, { ...options, encoding: 'utf8' })
+  return { stdout: String(stdout) }
+}
+
+// AppleScript: 프로세스명과 앞 윈도우 타이틀을 2줄로 반환. 윈도우가 없는 앱도 있으므로 try-fallback.
+const DARWIN_SCRIPT = `
+try
+  tell application "System Events"
+    set frontApp to first process whose frontmost is true
+    set appName to name of frontApp
+    try
+      set winTitle to name of front window of frontApp
+    on error
+      set winTitle to ""
+    end try
+    return appName & linefeed & winTitle
+  end tell
+on error errMsg
+  return "" & linefeed & ""
+end try
+`.trim()
+
+/**
+ * macOS: osascript (System Events). Accessibility 권한이 필요하다 — 거부되면 { null, null }.
+ */
+export function createDarwinForegroundWindowPort(
+  execFileText: ExecFileText = defaultExecFileText,
+): ForegroundWindowPort {
+  return {
+    async current() {
+      try {
+        const { stdout } = await execFileText('/usr/bin/osascript', ['-e', DARWIN_SCRIPT], { timeout: 3000 })
+        const lines = stdout.split('\n')
+        return { appName: blankToNull(lines[0]), windowTitle: blankToNull(lines[1]) }
+      } catch (error) {
+        logger.warn(
+          `osascript active window query failed: ${error instanceof Error ? error.message : String(error)}`,
+        )
+        return UNKNOWN
+      }
+    },
+  }
+}
+
+/** 미지원 플랫폼(Linux 등) */
+export function createNullForegroundWindowPort(): ForegroundWindowPort {
+  return { current: async () => UNKNOWN }
+}
+
+export function createDefaultForegroundWindowPort(
+  platform: NodeJS.Platform = process.platform,
+): ForegroundWindowPort {
+  if (platform === 'win32') return createWin32ForegroundWindowPort()
+  if (platform === 'darwin') return createDarwinForegroundWindowPort()
+  return createNullForegroundWindowPort()
+}
+
+// ── 선택 텍스트 캡처 안전성 ─────────────────────────────────
+
+/**
+ * 콘솔/터미널 호스트(소문자 프로세스 이름). 이런 창에서 선택 없이 Ctrl+C 를 보내면 복사가 아니라
+ * SIGINT(실행 중 프로세스 중단)나 입력 줄 지우기가 된다 — 선택 텍스트 캡처를 건너뛴다.
+ */
+const TERMINAL_HOSTS = new Set([
+  'windowsterminal',
+  'openconsole',
+  'conhost',
+  'cmd',
+  'powershell',
+  'pwsh',
+  'powershell_ise',
+  'wezterm-gui',
+  'alacritty',
+  'mintty',
+  'conemu',
+  'conemu64',
+  'kitty',
+  'hyper',
+  'tabby',
+  'warp',
+  'terminal',
+  'iterm2',
+  'iterm',
+  'ghostty',
+])
+
+export function isTerminalHost(appName: string | null): boolean {
+  if (!appName) return false
+  return TERMINAL_HOSTS.has(toProcessName(appName).trim().toLowerCase())
+}
--- a/apps/desktop/src/main/services/voice-intent.ts
+++ b/apps/desktop/src/main/services/voice-intent.ts
@ -0,0 +1,85 @@
+// src/main/services/voice-intent.ts
+// 키 제스처 → 음성 세션 의도(start/stop/ignore) 매핑 정책. 순수 함수만 둔다 (서비스·IO 의존 없음).
+//
+// 예전엔 이 규칙이 VoiceModeService 의 _handlePress / _handleRelease / _resolveMode /
+// _resolveHoldMode 에 흩어져 있었고, '처리 중(processing)' 이라는 단계가 코드에 드러나지 않아
+// 액션 큐의 직렬화 순서에 암묵적으로 기댔다. 정지가 전사·LLM 전체를 await 하는 동안 큐에 쌓인
+// 입력이 세션이 끝난 뒤 다른 의미로 재생됐다(더블탭 정지의 두 번째 탭이 새 핸즈프리를 시작).
+// 이제 단계를 명시적으로 받아 의도를 돌려준다. 처리 중의 토글·누름은 'ignore' 다.
+//
+// 남는 한계: 처리가 더블탭 간격(TIMING.DOUBLE_PRESS_DURATION)보다 빨리 끝나 세션이 이미 idle 이면
+// 두 번째 탭은 여전히 새 핸즈프리 세션을 시작한다. 의도 판단에 시간 정보가 필요한 경우로, 이 모듈의
+// 범위 밖이다.
+
+import type { KeyBindingActionId, VoiceMode } from '@d3ro/core/types'
+
+/** 의도 판단에 쓰는 세션 단계 */
+export type VoiceIntentPhase = 'idle' | 'recording' | 'processing'
+
+export interface VoiceGesture {
+  type: 'press' | 'release'
+  mode: VoiceMode
+  /** hold-to-talk 여부 — release 에서 세션을 끊을지 결정한다 */
+  holdMode: boolean
+}
+
+export type VoiceIntent =
+  | { kind: 'start'; mode: VoiceMode }
+  | { kind: 'stop' }
+  | { kind: 'ignore' }
+
+const IGNORE: VoiceIntent = { kind: 'ignore' }
+const STOP: VoiceIntent = { kind: 'stop' }
+
+/**
+ * 세션 상태에서 의도 판단용 단계를 도출한다. 별도 상태 필드를 두지 않는다.
+ * @param active 세션이 살아 있다 (비터미널)
+ * @param stopRequested 이 세션에 정지가 이미 요청됐다 (오디오 해제 이후 = 전사/LLM 처리 중)
+ */
+export function deriveVoiceIntentPhase(active: boolean, stopRequested: boolean): VoiceIntentPhase {
+  if (!active) return 'idle'
+  return stopRequested ? 'processing' : 'recording'
+}
+
+/**
+ * 키 제스처를 세션 의도로 바꾼다.
+ *
+ * | 제스처                          | idle             | recording | processing |
+ * |---------------------------------|------------------|-----------|------------|
+ * | press dictation                 | start dictation  | ignore    | ignore     |
+ * | press hands-free (토글)         | start hands-free | stop      | ignore     |
+ * | release dictation + holdMode    | ignore           | stop      | ignore     |
+ * | release 그 외 (토글의 release)   | ignore           | ignore    | ignore     |
+ *
+ * 핸즈프리 세션도 dictation release(holdMode) 한 번으로 멈춘다 — 기본 바인딩에서 더블탭 정지의
+ * 첫 탭이 이 경로다(두 번째 탭은 processing 에서 ignore).
+ */
+export function resolveVoiceIntent(gesture: VoiceGesture, phase: VoiceIntentPhase): VoiceIntent {
+  if (phase === 'processing') return IGNORE
+
+  if (gesture.type === 'press') {
+    if (gesture.mode === 'dictation') {
+      return phase === 'idle' ? { kind: 'start', mode: 'dictation' } : IGNORE
+    }
+    return phase === 'idle' ? { kind: 'start', mode: 'hands-free' } : STOP
+  }
+
+  if (gesture.holdMode && gesture.mode === 'dictation' && phase === 'recording') return STOP
+  return IGNORE
+}
+
+/** 키바인딩 액션 → 세션 모드. 더블탭은 항상 핸즈프리다. */
+export function resolveGestureMode(actionId: KeyBindingActionId, isDoublePress: boolean): VoiceMode {
+  if (actionId === 'hands-free' || isDoublePress) return 'hands-free'
+  return 'dictation'
+}
+
+/**
+ * 'command' 액션에는 아직 전용 핸들러가 없다.
+ * 현행 동작대로 dictation 파이프라인으로 fallback 하며, 그 경로는 hold-to-talk 이므로
+ * KEYBINDING_ACTIONS 의 holdMode(false)가 아니라 dictation 과 같은 값을 쓴다.
+ */
+export function resolveGestureHoldMode(actionId: KeyBindingActionId, specHoldMode: boolean): boolean {
+  if (actionId === 'command') return true
+  return specHoldMode
+}