# 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` 동기 블로킹 절대 금지.