feat(desktop): make local speech transcription work end to end

Local dictation had never produced a transcript on an installed build. The
engine itself was healthy; every connection to it was broken.

Installed builds shipped no speech engine at all: the packaging config had no
entry for the faster-whisper sidecar and no pipeline step built one, so the app
always fell back to a system Python without the runtime. Development was broken
too, because the sidecar and SoX paths were resolved against the Vite output
directory instead of the app root, which also meant recording failed with a SoX
ENOENT. On hosts where localhost resolves only to IPv6, every local request was
refused outright, which silently disabled both local transcription and the local
LLM.

The sidecar is now built and bundled (including the Silero VAD data it needs),
gated by a packaging check that fails when the engine or its data is missing.
Paths are discovered from the app root and fail loudly when the engine is
absent. Local engine URLs are normalized to the IPv4 loopback, decoding is tuned
so repeated hallucinations cannot compound (the same transcript now takes about
a fifth of the time), the engine is warmed up at startup, and holding the hotkey
now shows the text forming live in the recording tip.

apps/desktop/tests/main/services/STTManager.test.ts

@@ -383,4 +383,44 @@ describe('STTManager & Multi-provider Drivers', () => {
       expect(result.text).toBe('로컬 Whisper 폴백 성공')
     })
   })
+
+  describe('STTManager Live Partial (미리보기)', () => {
+    it('routes partial transcription through the local engine', async () => {
+      const mgr = getSTTManager()
+      mgr.setProvider('local')
+
+      const { getLocalSTTService } = await import('../../../src/main/services/LocalSTTService')
+      const partialSpy = vi
+        .spyOn(getLocalSTTService(), 'transcribePartial')
+        .mockResolvedValue('미리보기 텍스트')
+
+      await expect(mgr.transcribePartial(Buffer.alloc(32000))).resolves.toBe('미리보기 텍스트')
+      expect(partialSpy).toHaveBeenCalledOnce()
+    })
+
+    it('does not call the local engine for cloud providers', async () => {
+      const mgr = getSTTManager()
+      mgr.setProvider('groq')
+      mgr.setProviderConfig('groq', { apiKey: 'gsk-test' })
+
+      const { getLocalSTTService } = await import('../../../src/main/services/LocalSTTService')
+      const partialSpy = vi.spyOn(getLocalSTTService(), 'transcribePartial')
+
+      await expect(mgr.transcribePartial(Buffer.alloc(32000))).resolves.toBe('')
+      expect(partialSpy).not.toHaveBeenCalled()
+    })
+
+    it('warms up the local engine only for the local provider', async () => {
+      const mgr = getSTTManager()
+      const { getLocalSTTService } = await import('../../../src/main/services/LocalSTTService')
+      const warmSpy = vi.spyOn(getLocalSTTService(), 'warmUp').mockResolvedValue(true)
+
+      mgr.setProvider('local')
+      await expect(mgr.warmUpLocal()).resolves.toBe(true)
+
+      mgr.setProvider('deepgram')
+      await expect(mgr.warmUpLocal()).resolves.toBe(false)
+      expect(warmSpy).toHaveBeenCalledOnce()
+    })
+  })
 })

apps/desktop/tests/main/utils/loopback.test.ts

@@ -0,0 +1,54 @@
+// tests/main/utils/loopback.test.ts
+// 로컬 엔진 URL 정규화 테스트.
+// Windows에서 localhost가 ::1로만 해석되어 Ollama/sidecar 연결이 실패했던 회귀를 고정한다.
+
+import { describe, it, expect } from 'vitest'
+import { loopbackUrl, normalizeLoopbackUrl } from '../../../src/main/utils/loopback'
+
+describe('normalizeLoopbackUrl', () => {
+  it('rewrites a bare localhost host to the IPv4 loopback', () => {
+    expect(normalizeLoopbackUrl('http://localhost:11434')).toBe('http://127.0.0.1:11434')
+  })
+
+  it('keeps the port and path', () => {
+    expect(normalizeLoopbackUrl('http://localhost:8000/v1')).toBe('http://127.0.0.1:8000/v1')
+  })
+
+  it('handles https and trailing dot host forms', () => {
+    expect(normalizeLoopbackUrl('https://localhost:5000/health')).toBe(
+      'https://127.0.0.1:5000/health',
+    )
+    expect(normalizeLoopbackUrl('http://localhost.:1234')).toBe('http://127.0.0.1:1234')
+  })
+
+  it('leaves remote hosts untouched', () => {
+    expect(normalizeLoopbackUrl('https://api.openai.com/v1')).toBe('https://api.openai.com/v1')
+    expect(normalizeLoopbackUrl('http://192.168.0.10:11434')).toBe('http://192.168.0.10:11434')
+    expect(normalizeLoopbackUrl('http://127.0.0.1:11434')).toBe('http://127.0.0.1:11434')
+  })
+
+  it('does not treat lookalike hostnames as loopback', () => {
+    expect(normalizeLoopbackUrl('http://localhost.evil.com')).toBe('http://localhost.evil.com')
+  })
+
+  it('falls back to a textual rewrite when the URL is not parseable', () => {
+    // 잘못된 포트는 URL 파서가 던진다 → 정규식 폴백 경로를 탄다.
+    expect(normalizeLoopbackUrl('http://localhost:99999999')).toBe(
+      'http://127.0.0.1:99999999',
+    )
+  })
+
+  it('passes through inputs without a recognizable host', () => {
+    expect(normalizeLoopbackUrl('localhost:11434')).toBe('localhost:11434')
+  })
+
+  it('returns empty input unchanged', () => {
+    expect(normalizeLoopbackUrl('')).toBe('')
+  })
+})
+
+describe('loopbackUrl', () => {
+  it('builds an IPv4 loopback URL for a port', () => {
+    expect(loopbackUrl(18765)).toBe('http://127.0.0.1:18765')
+  })
+})

apps/desktop/tests/main/utils/paths.test.ts

@@ -0,0 +1,97 @@
+// tests/main/utils/paths.test.ts
+// dev/packaged 경로 해석 테스트.
+//
+// 회귀 배경: electron-vite dev에서 app.getAppPath()가 `out/main`을 가리켜
+// sidecar/SoX가 존재하지 않는 경로로 잡혔고, 결과적으로 로컬 전사와 녹음이
+// 모두 실패했다(시스템 python/PATH 폴백). 여기서 그 해석을 고정한다.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { app } from 'electron'
+import {
+  getAppRoot,
+  getSidecarCommand,
+  getSidecarBaseUrl,
+  getSoxPath,
+  resetPathCache,
+} from '../../../src/main/utils/paths'
+
+const desktopDir = path.resolve(__dirname, '..', '..', '..')
+
+describe('paths (dev)', () => {
+  beforeEach(() => {
+    resetPathCache()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    resetPathCache()
+  })
+
+  it('resolves the app root a level above the vite out/main bundle', () => {
+    // dev에서 app.getAppPath() = <desktop>/out/main 이다.
+    vi.mocked(app.getAppPath).mockReturnValue(path.join(desktopDir, 'out', 'main'))
+    resetPathCache()
+
+    expect(getAppRoot()).toBe(desktopDir)
+  })
+
+  it('prefers the bundled SoX binary over the system PATH', () => {
+    expect(getSoxPath()).toContain(path.join('resources', 'sox', 'sox'))
+    expect(existsSync(getSoxPath())).toBe(true)
+    expect(getSoxPath()).not.toBe('sox')
+  })
+
+  it('uses the sidecar virtualenv python when it exists', () => {
+    const launch = getSidecarCommand()
+
+    expect(launch.source).toBe('venv')
+    expect(launch.command).toContain('.venv')
+    expect(launch.args[0]).toBe(path.join(desktopDir, 'sidecar', 'main.py'))
+    expect(existsSync(launch.command)).toBe(true)
+  })
+
+  it('builds the sidecar base URL on the IPv4 loopback', () => {
+    expect(getSidecarBaseUrl(18765)).toBe('http://127.0.0.1:18765')
+  })
+})
+
+describe('paths (packaged)', () => {
+  beforeEach(() => {
+    resetPathCache()
+    Object.defineProperty(app, 'isPackaged', { value: true, configurable: true })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(app, 'isPackaged', { value: false, configurable: true })
+    vi.restoreAllMocks()
+    resetPathCache()
+  })
+
+  it('fails loudly when the packaged sidecar bundle is missing', () => {
+    Object.defineProperty(process, 'resourcesPath', {
+      value: path.join(desktopDir, 'definitely-not-bundled'),
+      configurable: true,
+    })
+
+    expect(() => getSidecarCommand()).toThrowError(/사이드카를 찾을 수 없습니다/)
+  })
+
+  it('uses the packaged sidecar executable when present', () => {
+    Object.defineProperty(process, 'resourcesPath', {
+      value: path.join(desktopDir, 'resources'),
+      configurable: true,
+    })
+
+    // resources/sox 는 커밋되어 있으므로 resources/sidecar/sidecar(.exe)도
+    // 같은 방식으로 배치된다. 존재하지 않는 플랫폼이면 번들 실패로 처리된다.
+    const exeSuffix = process.platform === 'win32' ? '.exe' : ''
+    const bundled = path.join(desktopDir, 'resources', 'sidecar', `sidecar${exeSuffix}`)
+    if (existsSync(bundled)) {
+      expect(getSidecarCommand().source).toBe('bundled')
+    } else {
+      expect(() => getSidecarCommand()).toThrow()
+    }
+  })
+})