docs: devlog #004 + known-issues — Collector multi-project polling bug

.agents/references/known-issues.md

@@ -426,3 +426,9 @@
 - **해결**: (1) Extension에 파일별 `requiredMarker` 검증 추가 (workbench.html은 `workbench.desktop.main.css`, jetski는 `jetskiMain.tailwind.css` 필수), (2) 첫 패치 전 `.orig` 백업 자동 생성, (3) 손상 또는 잘못된 타입 감지 시 `.orig`에서 자동 복원. **두 HTML 파일은 절대 크로스 복원 불가**
 - **주의**: `workbench.html`과 `workbench-jetski-agent.html`은 **교환 불가능**. CSS 경로, JS 엔트리 포인트, CSP 세부 설정이 모두 다름. 수동 복원 시도 금지 — Extension의 자동 복원 로직에 의존할 것
 
+### [2026-03-12] Collector 단일 프로젝트 폴링 — 멀티 프로젝트 command 전달 불가
+- **증상**: Discord `ag-deriva` 채널에서 메시지 전송 → Deriva AG IDE에 전달되지 않음. Gateway에 command 정상 저장됨
+- **원인**: `collector.py` `_poll_commands_loop()`이 `self.project_name` (= `.env`의 `PROJECT_NAME`, 기본 `gravity_control`)으로만 `GET /api/commands/{project}` 폴링. Gateway는 프로젝트별로 command를 저장(`_commands["deriva"]`)하지만 Collector가 `"gravity_control"`만 요청 → 다른 프로젝트 명령이 30분 TTL 후 만료
+- **해결**: `_discover_local_projects()`로 `bridge/register/*.json`에서 로컬 프로젝트 목록을 자동 발견, 모든 프로젝트에 대해 폴링. Extension은 L131에서 `project_name` 필터링이 있어 자기 프로젝트만 소비
+- **주의**: 멀티 PC 환경에서 `/api/commands/all` 엔드포인트는 크로스 PC 명령 오염을 유발하므로 사용 금지. 각 Collector가 자기 PC의 `register/` 기반으로 프로젝트를 발견하는 것이 올바른 설계
+