d3ro-voice/.agents/rules/desktop-app-execution-and-windows.md

Windows 데스크톱 앱 실행 및 Electron GUI 환경 지침

1. Windows 데스크톱 윈도우 스테이션 격리 (CRITICAL)

• 배경: AI 에이전트 CLI(Antigravity 등) 내부의 도구 실행(run_command) 환경은 보안 격리 가상 데스크톱(WinSta0\exebox-...)에서 동작한다.
• 현상: 에이전트 서브쉘에서 Electron GUI 앱을 실행하면 프로세스는 정상 구동되고 로그도 정상(Main window shown)이지만, 사용자의 실제 모니터 화면(WinSta0\Default)에는 창이 물리적으로 보이지 않는다.
• 규칙:
  • 에이전트가 단독으로 GUI 창을 사용자 화면에 띄우려고 무리하게 백그라운드 구동을 반복하지 말 것.
  • GUI 테스트/실행이 필요할 때는 사용자가 직접 외부 터미널 또는 파일 탐색기에서 run-desktop.bat 또는 pnpm --filter @d3ro/desktop dev를 실행하도록 안내한다.

2. Electron 단일 인스턴스 잠금 (Single Instance Lock) & 사일런트 종료 방지

• 앱 식별자 명시: src/main/index.ts 최상단에서 app.requestSingleInstanceLock() 호출 전에 반드시 app.setName('d3ro-voice')와 app.setAppUserModelId('kr.twentyoz.d3ro-voice')를 선언하여 일반 'Electron' 프로세스와의 식별자 충돌을 방지한다.
• 사일런트 종료 방지: 개발 환경(!app.isPackaged)에서 락 파일 잔여물로 인해 무조건 사일런트 종료(app.quit())되는 일이 없도록 보호 처리를 유지한다.
• 실행 스크립트 선제 정리: run-desktop.bat에는 잔여 프로세스 및 stale lockfile 정리가 포함되어 있어야 한다.

3. 오디오 장치 탐색 동기 블로킹 금지

• Windows 마이크 디바이스 열거 시 execSync를 절대 사용하지 않는다. (Windows 환경에서 5초 ETIMEDOUT 메인 이벤트루프 프리징 유발)
• 반드시 child_process.exec 비동기 논블로킹 및 3초 타임아웃, 기본 마이크 폴백 구조를 유지한다.

4. GPU 하드웨어 가속 충돌 및 투명 창 방지

• NVIDIA 드라이버, Razer Chroma, Oculus 등의 훅 소프트웨어로 인해 창이 투명/블랭크 처리되는 문제를 방지하기 위해 app.disableHardwareAcceleration() 및 disable-gpu 스위치를 유지한다.

5. 윈도우 화면 배치 및 작업표시줄 등록

• screen.getPrimaryDisplay().workAreaSize를 기준으로 (x, y) 중앙 좌표를 명시 계산하여 다중 모니터 이탈을 방지한다.
• setSkipTaskbar(false)로 작업표시줄 노출을 보장하고, ready-to-show에서 show(), restore(), focus(), flashFrame(true)를 순차 실행한다.