d3ro-voice/memory/handoff-latest.md

Session Handoff — 2026-08-19 (Ollama 온보딩 & 데스크톱 윈도우 실행 아키텍처 완료)

Environment: Windows (ALPACA-HOME) Target: @d3ro/desktop, @d3ro/core, @d3ro/ui, @d3ro/i18n

---

1. 이번 세션에서 해결한 핵심 작업 내역

1) Ollama 가이드 모달 & 1-클릭 모델 매니저 전면 개편 (OllamaGuideModal.tsx)

• Ollama 서버 헬스체크 및 실시간 버전 파싱 (GET /api/version -> v0.32.13).
• 서버 미실행 시 🔴 오프라인 정확 표기 및 1-클릭 백그라운드 자동 기동 (electronAPI.llm.startServer).
• 최신 4종 모델 (gemma2:2b, llama3.2:3b, qwen2.5:3b, gemma2:9b) 1-클릭 다운로드(Pull) 및 실시간 프로그레스 바.
• 즉시 텍스트 정제 동작 시험 프롬프트 러너 탑재.

2) 로컬 AI 온보딩 모달 & 대시보드 상태 표기 개선

• OnboardingModal.tsx: 로컬 AI 독립 모드(100% 무료/오프라인) vs 온라인 클라우드 모드 선택 분기.
• DashboardPage.tsx: 무조건 "로컬 연결됨" 표기 버그 수정 ➔ 실시간 헬스체크 기반 🟢 연결됨 / 🔴 오프라인 표기.

3) 오디오 장치 탐색 비동기화 (AudioCaptureService.ts)

• Windows PowerShell 마이크 디바이스 탐색에서 execSync 동기 블로킹 제거 ➔ 완전 비동기 exec 논블로킹으로 변경 (기동 시 5초 ETIMEDOUT 프리징 완전 제거).

4) Windows 데스크톱 실행 및 윈도우 스테이션 격리 해결

• src/main/index.ts: app.setName('d3ro-voice'), app.setAppUserModelId('kr.twentyoz.d3ro-voice') 명시.
• GPU 하드웨어 가속 충돌 방지 (app.disableHardwareAcceleration(), --disable-gpu).
• run-desktop.bat: 잔여 프로세스 및 stale lockfile 선제 정리 후 electron-vite dev 기동.
• .agents/rules/desktop-app-execution-and-windows.md: 영구 지침 파일 생성 및 CLAUDE.md 규칙 반영.

---

2. 향후 에이전트 필수 준수 지침 (Rules)

1. AI 에이전트 서브쉘(가상 데스크톱 exebox)에서 GUI 백그라운드 구동을 반복하지 말 것:
   • 에이전트의 서브쉘 도구(run_command)는 보안 가상 데스크톱(WinSta0\exebox-...)에서 프로세스를 띄우므로 사용자의 실제 모니터 화면(WinSta0\Default)에는 창이 보이지 않는다.
   • GUI 실행은 사용자가 run-desktop.bat 또는 외부 터미널에서 실행하도록 안내한다.
2. Single Instance Lock & 사일런트 종료 방지:
   • app.setName('d3ro-voice')와 app.setAppUserModelId를 최상단에 항상 유지하고, dev 모드에서 락 파일 충돌로 인한 사일런트 종료를 방지한다.
3. 오디오 장치 탐색:
   • execSync 동기 블로킹 절대 금지.