Known Issues & Lessons Learned

이 파일은 SSOT(Single Source of Truth)입니다. 디버깅이나 구현 전에 반드시 이 파일을 확인하세요. 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.

Tip

해결 완료된 과거 이슈는 known-issues-archive.md에 보관되어 있습니다. 비슷한 문제가 재발하면 archive에서 검색하세요.

포맷

### [날짜] [키워드] — 한줄 요약
- **증상**: 무엇이 잘못되었는가
- **원인**: 근본 원인
- **해결**: 올바른 해결 방법
- **주의**: 재발 방지를 위한 교훈

증상: !auto, !stop, 텍스트 릴레이 등 Discord→Extension 방향 명령이 전부 작동 안 함. Extension log에 [AUTO] 로그 0건
원인: watchCommandsDir()의 fs.watch가 Windows에서 silent fail. watcher 세팅은 되지만 이벤트가 실제로 fire 안 됨
해결: fs.watch 유지 + 3초 setInterval 폴링 fallback 추가. processAllCommands() 함수로 공통화
주의: fs.watch는 Windows에서 구조적으로 불안정. 새 watcher 추가 시 반드시 polling fallback 병행

증상: Discord에서 승인 클릭해도 AG Extension에서 아무 동작 안함
원인: _disconnect()에서 Extension 연결 끊기면 pending_owners[rid] 삭제 → 재연결 후 owner 정보 소실
해결: (1) 삭제 대신 같은 project 다른 연결로 재할당, (2) _register_connection에서 orphaned pending 재할당, (3) 같은 project 활성 연결 fallback
주의: Gateway 모드에서 file bridge fallback은 완전히 무용 — Docker 볼륨에 파일 작성하지만 Extension은 로컬 bridge/ 감시

증상: Discord 메시지가 2개씩 도착
원인: writeChatSnapshot/writePendingApproval이 WS 전송 후 파일도 동시에 씀
해결: WS 연결 시 return으로 파일 쓰기 건너뛰기
주의: writePendingApproval 수정 시 diff_review metadata 캐싱 + memory dedup 로직이 WS 경로에서도 실행되어야 함

증상: Extension이 pending 생성 후 WS 연결 끊김 → Discord 승인 클릭 → AG에 전달 안 됨
원인: ApprovalView가 Hub 전달 실패 시 file bridge를 건너뜀
해결: send_response_to_pending_owner() 반환값 확인 → False면 file bridge fallback (5곳)
주의: send_response_to_pending_owner는 pending_owners에 conn_id가 없으면 False 반환. Hub 존재 ≠ 전달 성공

아래는 과거 이슈에서 반복적으로 나타난 패턴을 규칙으로 정리한 것입니다.

#	규칙	관련 이슈 (archive 참조)
1	Hub WS와 file bridge는 상호 배타적 — `if hub: ws + return` / `else: file`	WS dual-write, _auto_approve 이중 쓰기
2	WS 경로 추가 시 file-bridge의 모든 분기를 포팅	diff_review WS regression
3	AG RPC `{}` 응답은 실패로 간주 — 메서드명 틀려도 에러 없이 `{}` 반환	AcknowledgeCascadeCodeEdit
4	ResolveOutstandingSteps는 CANCEL 동작 — 승인에 절대 사용 금지	Step probe reject
5	Extension 코드 수정 후 반드시 VSIX 빌드 + AG 풀 재시작	Extension 버전 미배포
6	HTML 패치 변경 시 V8 CachedData 삭제 필수	V8 CachedData, CSP
7	`bridge/pending/` 조작 시 반드시 `project_name` + `conversation_id` 필터	크로스 프로젝트 DEDUP MERGE
8	`processResponseFile` 상태 리셋은 `sawRunningAfterPending=true`만	processResponseFile 무한 루프
9	fs.watch Windows 불안정 — 반드시 polling fallback 병행	fs.watch silent fail
10	diff_review는 VS Code 커맨드만 유효 — RPC 3개 전략 모두 실패 확정	diff_review RPC dead-end