gravity_control/.agents/references/known-issues-archive.md

Known Issues — Archive

해결 완료된 이슈 아카이브입니다. 현재 활성 이슈는 known-issues.md를 참조하세요. 비슷한 문제가 재발할 때 이 문서에서 과거 해결 방법을 검색하세요.

---

포맷

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

---

승인 전략 결정 체인 (2026-03-08~09 전체 요약)

이 섹션은 2026-03-08~09 전체 세션의 시행착오를 요약합니다. 이미 거부된 접근을 다시 시도하지 마세요.

❌ 시도 후 거부된 접근 (재시도 금지)

#	접근	결과	거부 사유
1	LS RPC HandleCascadeUserInteraction	socket hang up	AG 빌드에서 핸들러 미구현
2	LS RPC ResolveOutstandingSteps	CANCEL 동작 (승인이 아님)	명칭과 달리 step을 취소함
3	VS Code 7개 승인 명령 (terminalCommand.run 등)	command not found	AG 런타임에 미등록
4	키보드 시뮬레이션 (type {Enter})	빈 메시지 전송	Chat input에 캡처됨
5	sendChatActionMessage / executeCascadeAction	미등록	119개 명령에 없음
6	pywinauto (OS 레벨)	사용자 결정 폐기	크로스플랫폼 불가, 창 겹침 문제
7	CDP (Chrome DevTools Protocol)	사용자 명시적 거부	비표준, --remote-debugging-port 필요
8	Renderer v1 DOM Click (flat scan)	Run 버튼 미발견	webview iframe 격리

🔑 핵심 전제

• Run/Accept 버튼은 vscode-webview:// origin의 격리된 iframe 안에 있음
• 외부 workbench DOM에서 querySelector로 접근 불가 (cross-origin)
• <webview>.executeJavaScript()가 유일한 표준 관통 경로 (Electron API)
• AG 패치 후 반드시 풀 프로세스 재시작 필요 (Reload Window 불충분)
• 양쪽 HTML (workbench.html + workbench-jetski-agent.html) 모두 inline 패치 필수
• HTML 패치 변경 시 %APPDATA%\Antigravity\CachedData 삭제 필수 (V8 바이트코드 캐시 무효화)
• CSP script-src에 'unsafe-inline' 패치 필수 (없으면 인라인 스크립트 무조건 차단)

---

Renderer / HTML 패치 관련 (2026-03-08~09)

[2026-03-08] Antigravity Renderer Injection — Electron 캐시 차단

• 증상: workbench.html, workbench-jetski-agent.html에 <script> 태그 추가 후 리로드해도 실행되지 않음
• 원인: Electron의 V8 코드 캐시가 수정된 HTML을 무시하고 캐시된 버전을 서빙
• 해결: 렌더러 인젝션 방식 포기. Extension Host에서 RPC 폴링 방식으로 전환
• 주의: Antigravity는 workbench-jetski-agent.html을 사용 (Jetski = 내부 코드네임)

[2026-03-08] Antigravity 승인 대기 = RUNNING (NOT IDLE)

• 증상: IDLE 기반 승인 감지가 실제 승인 대기를 놓침
• 원인: 승인 대기 시 세션 상태가 CASCADE_RUN_STATUS_RUNNING (IDLE 아님), IDLE은 대화 대기(notify_user 후)
• 해결: RUNNING + delta=0 (stall) 기반 감지로 전환. 6 polls (30초) 이상 FROZEN 시 pending 생성
• 주의: Thinking/생성 중에도 RUNNING + delta=0이 발생 → lastModifiedTime으로 구분 시도했으나 불완전

[2026-03-08] ResolveOutstandingSteps RPC — 승인이 아닌 취소!

• 증상: Discord 승인 → ResolveOutstandingSteps 호출 → step이 취소됨
• 원인: ResolveOutstandingSteps는 blocking steps를 "resolve" = REJECT/CANCEL, approve가 아님
• 해결: ResolveOutstandingSteps 제거. HandleCascadeUserInteraction은 socket hang up
• 주의: KI에 "more reliable"로 기록되어 있으나 실제 동작은 cancel임. KI 업데이트 필요

[2026-03-08] VS Code Accept Commands — Silent Success 문제

• 증상: 4개 accept command 모두 OK(undefined) 반환하나 실제 승인 안 됨
• 원인: webview에 활성 포커스가 필요. panel.focus()로는 충분하지 않음
• 해결: 미해결. Windows UI Automation 등 OS 레벨 접근 필요
• 주의: reject commands는 동작함. accept만 focus 의존성 있음

[2026-03-08] Multi-Window 세션 등록 경쟁 조건

• 증상: 이 창(gravity_control)의 대화가 #ag-variet_agent 채널로 메시지 전달
• 원인: writeRegistration()이 폴링 루프에서 호출 → 먼저 폴링한 확장이 세션을 자기 프로젝트로 등록
• 해결: writeRegistration을 폴링에서 제거, writeChatSnapshot/writePendingApproval에서만 지연 호출
• 주의: GetAllCascadeTrajectories는 모든 창의 세션을 반환하므로 세션→창 매핑은 불가능. 활동 기반 등록만 신뢰 가능

[2026-03-08] 공유 렌더러 스크립트 파일 덮어쓰기 문제

• 증상: DOM Observer 렌더러 스크립트가 잘못된 HTTP bridge 포트에 연결
• 원인: 두 확장이 동일한 ag-sdk-variet-gravity-bridge.js 파일에 각자 포트를 씀 → 마지막 확장 것만 남음
• 해결: ag-bridge-ports.json에 모든 확장의 port를 JSON으로 기록, 렌더러가 all ports를 순회하며 ping
• 주의: 렌더러 스크립트 파일 경로는 SDK patcher namespace에 의해 고정 — 변경 불가

[2026-03-08] workbench.html vs workbench-jetski-agent.html

• 증상: 렌더러에서 [GB Observer] 로그가 전혀 안 나옴
• 원인: DevTools가 workbench.html을 로드 — 스크립트 태그는 workbench-jetski-agent.html에만 패치됨
• 해결: workbench.html에도 스크립트 태그 필요. Antigravity 재설치 후 SDK patcher가 올바르게 패치하도록 함
• 주의: SDK patcher는 both HTML 파일을 패치하지만, 수동 수정은 Antigravity integrity check에 의해 되돌려질 수 있음

[2026-03-08] product.json 체크섬 불일치 → 렌더러 스크립트 미로딩

• 증상: <script> 태그가 HTML에 존재하고 .js 파일도 디스크에 있으나, 렌더러 콘솔에 스크립트 로그가 전혀 없음
• 원인: Antigravity 재설치 시 product.json의 SHA256 체크섬이 원본으로 리셋됨. Extension이 HTML을 패치하지만 IntegrityManager.suppressCheck()를 호출하지 않아 체크섬 불일치. vscode-file:// 프로토콜이 체크섬 불일치 파일을 무시하고 원본 캐시 HTML을 서빙
• 해결: product.json의 checksums 항목에서 수정된 파일(workbench.html, workbench-jetski-agent.html)의 SHA256 해시를 실제 파일 기준으로 업데이트. SDK IntegrityManager.suppressCheck() 호출 또는 수동 스크립트로 해결
• 주의: Extension setupApprovalObserver()에 suppressCheck() 호출을 영구 추가해야 재설치마다 반복 안 됨. 해시 = base64(sha256(file)).replace(/=+$/, '')

[2026-03-08] vscode-file:// 프로토콜 — 커스텀 .js 파일 서빙 불가

• 증상: <script src="./ag-sdk-variet-gravity-bridge.js"> 태그가 HTML에 있으나 net::ERR_FILE_NOT_FOUND 발생, GB Observer 로그 전혀 없음
• 원인: vscode-file:// 프로토콜은 원본 배포에 포함된 파일만 서빙. Extension이 디스크에 쓴 커스텀 .js 파일은 프로토콜 레벨에서 차단됨
• 해결: 외부 <script src> 참조 대신 인라인 <script>...코드...</script> 방식으로 HTML에 직접 삽입
• 주의: ag-bridge-ports.json도 같은 이유로 XHR 로딩 불가. 모든 렌더러 스크립트/데이터는 HTML 인라인으로 전달해야 함

[2026-03-08] Renderer 포트 디스커버리 — ag-bridge-ports.json XHR 실패

• 증상: [GB Observer] Port discovery timeout after 2min — 렌더러가 bridge 포트를 찾지 못함
• 원인: 렌더러 스크립트가 ./ag-bridge-ports.json을 동기 XHR로 읽으려 하나, vscode-file:// 프로토콜이 .json 파일 서빙 거부
• 해결: (1) 프로젝트명 해시 기반 결정론적 포트 사용 (gravity_control→34332), (2) 스크립트 생성 시 포트를 HARDCODED_PORT=${port}로 직접 삽입
• 주의: server.listen(0) 랜덤 포트 → 매 재시작마다 변경되어 렌더러와 불일치. 결정론적 포트는 EADDRINUSE 시 랜덤 폴백 필요

[2026-03-08] GetCascadeTrajectorySteps — cascadeId 파라미터 발견

• 증상: GetCascadeTrajectorySteps에 trajectoryId 파라미터 → 500 "trajectory not found"
• 원인: 파라미터명이 trajectoryId가 아니라 cascadeId. 값은 GetAllCascadeTrajectories.trajectorySummaries의 맵 키(세션 ID)
• 해결: { cascadeId: sessionId }로 호출 → 전체 step 배열 반환 성공
• 주의: latestToolCallStep 필드는 GetAllCascadeTrajectories 응답에 존재하지 않음 (KI 오류)

[2026-03-08] Step 구조 — CORTEX_STEP_STATUS_WAITING 즉시 감지

• 증상: stall-based 감지(100초)가 너무 느림
• 원인: 이제 GetCascadeTrajectorySteps로 최신 step의 status를 직접 확인 가능
• 해결: stall 5초 후 step probe → CORTEX_STEP_STATUS_WAITING 확인 → 즉시 pending 생성
• Step 구조: {type: "CORTEX_STEP_TYPE_RUN_COMMAND", status: "CORTEX_STEP_STATUS_WAITING", metadata: {toolCall: {name, argumentsJson}}, runCommand, requestedInteraction}
• 주의: 775-step 하드 리밋은 여전히 존재. 긴 세션에서는 fallback(40초) 사용

[2026-03-08] Extension 재설치 안전성 — 자동 패치 메커니즘

• 증상: Antigravity 삭제 후 재설치 시 렌더러 스크립트가 동작 안 함
• 원인: 재설치 시 HTML/product.json이 원본으로 리셋됨
• 해결: Extension의 setupApprovalObserver()가 자동으로 모든 패치를 수행
• 주의: 패치 후 반드시 Antigravity 풀 재시작 필요 (Reload Window 불가)

[2026-03-08] Response 파일 Race Condition — DOM Observer 승인 실패

• 증상: Discord에서 승인 → [RESPONSE] renderer-handled approval 로그 출력 → 실제 버튼 클릭 안 됨
• 원인: processResponseFile (파일 감시자)이 response 파일을 즉시 삭제 → renderer의 pollResponse가 HTTP GET /response/:rid로 조회 시 파일 이미 없음
• 해결: DOM observer 소스일 때는 response 파일을 삭제하지 않도록 수정. HTTP endpoint가 renderer에게 서빙한 후 삭제
• 주의: non-DOM (stall/step_probe relay)는 watcher에서 삭제해도 됨

[2026-03-08] Renderer 스크립트 소스 혼동 — 3곳의 코드

• 증상: extension.ts에 BTN-DUMP 추가 → Reload 2번 → 콘솔에 안 나옴
• 원인: renderer 코드가 3곳에 존재: (1) extension.ts의 generateApprovalObserverScript() (소스), (2) ag-sdk-variet-gravity-bridge.js (배포됨, Reload시 소스에서 재생성), (3) workbench-jetski-agent.html inline (HTML, JS파일과 중복로드 방지됨)
• 해결: 항상 extension.ts의 generateApprovalObserverScript() 함수를 수정 → 컴파일 → 배포 → Reload
• 주의: HTML inline은 JS파일이 먼저 로드되어 window.__agSDK 가드에 의해 실행 안 됨. 실제 실행되는 것은 JS파일 경로의 스크립트

---

승인 / RPC 관련 (2026-03-09)

[2026-03-09] VS Code Accept — SDK 승인 명령이 AG에 미등록

• 증상: Discord 승인 → antigravity.terminalCommand.run 등 7개 명령 → 모두 command not found
• 원인: SDK(command-bridge.ts)에 정의된 7개 승인 명령이 현재 AG 빌드에 등록되어 있지 않음
• 해결: Renderer DOM Click 구현 → v3 deepFindButtons() 업그레이드
• 주의: agentPanel.focus도 미등록, agentSidePanel.focus만 존재

[2026-03-09] Renderer DOM — webview iframe 격리 확인 + v3 deep traversal

• 증상: Renderer trigger-click이 document.querySelectorAll('button')으로 버튼 검색 → Run 버튼 미발견
• 원인: Run/Accept 버튼은 AG 채팅 webview iframe (vscode-webview:// origin) 안에 렌더링
• 해결: Renderer v3 deepFindButtons() 구현 (iframe contentDocument + webview.executeJavaScript + shadow DOM)
• 주의: CDP(Chrome DevTools Protocol)는 사용자 결정에 의해 명시적으로 거부됨

[2026-03-09] Deep Inspect HTTP Endpoint — curl로 DOM 분석 트리거

• 증상: AG DevTools 콘솔에 붙여넣기 불가 (Chromium 보안 정책)
• 원인: Electron 렌더러 DevTools에서 allow pasting이 SyntaxError 발생
• 해결: Extension HTTP bridge에 /deep-inspect 엔드포인트 추가
• 주의: 시작 3초 후 자동 실행 + curl로 재트리거 가능

[2026-03-09] workbench.html inline 스크립트 미삽입 — jetski만 패치한 버그

• 증상: AG 재시작 후 /deep-inspect timeout — renderer v3 스크립트 미로딩
• 원인: setupApprovalObserver()가 workbench-jetski-agent.html에만 inline 삽입
• 해결: HTML 패치 로직을 양쪽 모두 inline 삽입으로 변경
• 주의: 항상 양쪽 HTML을 동일하게 패치

[2026-03-09] V8 CachedData — 체크섬 정상이어도 스크립트 미실행

• 증상: HTML 패치 + product.json 체크섬 일치 → 그런데도 renderer 스크립트 미실행
• 원인: V8 바이트코드 캐시가 vscode-file:// 프로토콜에도 적용
• 해결: %APPDATA%\Antigravity\CachedData\* 전체 삭제 후 AG 풀 재시작
• 주의: HTML 패치 변경 시마다 CachedData 삭제 필수

[2026-03-09] CSP script-src — 인라인 스크립트 무조건 차단

• 증상: HTML 패치 ✅, 체크섬 ✅, CachedData 삭제 ✅ — 그런데도 renderer 미실행
• 원인: CSP script-src에 'unsafe-inline' 없음
• 해결: CSP script-src에 'unsafe-inline' 추가
• 주의: style-src에는 'unsafe-inline'이 있어 스타일은 동작 → 스크립트만 차단되는 것이 함정

[2026-03-09] 중복 승인 요청 — DOM scan + Step probe 동시 발동

• 증상: Discord에 같은 명령에 대해 승인 요청이 2개 도착
• 원인: DOM Observer + Step probe가 동일 step에 대해 2개 파일 생성
• 해결: writePendingApproval()에 15초 dedup 윈도우 추가
• 주의: DOM scan은 제거 불가 — step probe가 감지 못하는 UI 버튼 존재

[2026-03-09] Step probe reject → ResolveOutstandingSteps가 AI 작업 취소

• 증상: Discord에서 거부 클릭 → AI의 현재 step뿐 아니라 진행 중인 작업 전체가 중단
• 원인: step probe 경로의 tryApprovalStrategies(approved=false) → ResolveOutstandingSteps RPC 호출
• 해결: step probe 경로에서 reject 시 tryApprovalStrategies 호출 제거
• 주의: ResolveOutstandingSteps는 이름과 달리 "해결"이 아닌 "취소". 승인에 절대 사용 금지

[2026-03-09] Pending 파일 무한 누적 — write_response 후 미삭제

• 증상: bridge/pending/ 디렉토리에 79개 이상의 .json 파일 누적
• 원인: write_response()가 pending 파일을 삭제하지 않음
• 해결: pending 파일 삭제 + 5분 age filter + 시작 시 cleanup
• 주의: 봇 재시작 시 자동 정리

[2026-03-09] Discord 승인 "Run" 표시 — DOM/step_probe 타이밍 불일치

• 증상: Discord에 상세 명령어 대신 "Run"만 표시
• 원인: DOM observer가 "Run" pending 생성 → 봇이 3초 후 전송 → step_probe MERGE가 10초 후 완료
• 해결: step_probe가 기존 DOM pending에 MERGE + 봇에서 짧은 명령어 대기
• 주의: MERGE 타이밍은 최소 10초

[2026-03-09] DOM observer false positive — Proceed/Continue/Open 버튼 오감지

• 증상: 작업 전환 시 승인 요청 없는데도 Discord에 승인 요청 도착
• 원인: DOM observer가 AG UI의 PathsToReview 버튼을 승인 버튼으로 오인
• 해결: FALSE_POSITIVE_RE 필터 추가 + sessionStalled 조건
• 주의: 렌더러 인라인 스크립트는 VSIX 빌드 필요

[2026-03-09] Discord ApprovalView timeout — 5분 후 버튼 무응답

• 증상: 시간이 지난 후 Discord 승인 버튼 클릭해도 반응 없음
• 원인: Discord.py View의 기본 timeout이 300초
• 해결: timeout을 1800초로 증가
• 주의: Discord View timeout은 서버 재시작 후만 적용

---

멀티 프로젝트 / Pending 관련 (2026-03-10)

[2026-03-10] DOM Observer 승인 ENOENT — response 파일 Race Condition

• 증상: Discord에서 ✅승인 → ENOENT: response/xxx.json 에러
• 원인: processResponseFile()이 response 파일 즉시 삭제 → renderer 조회 실패
• 해결: DOM observer 경로에서 response 파일을 삭제하지 않고 HTTP handler가 서빙 후 삭제
• 주의: DOM observer와 step_probe 두 경로가 독립적

[2026-03-10] Allow Once + Allow This Conversation — 별개 pending으로 분리되는 문제

• 증상: 파일 접근 시 Discord에 2개 별도 메시지로 도착
• 원인: renderer scan()이 한 사이클에 한 버튼만 처리
• 해결: findButtonContainer() + collectSiblingButtons()로 그룹화, buttons 배열 전송
• 주의: buttons 배열이 없는 legacy pending은 기존 2버튼(✅승인/❌거부)으로 표시

[2026-03-10] step_probe verbosity — argumentsJson 미포함

• 증상: Discord 승인 메시지에 파라미터 이름만 표시, 값 없음
• 원인: GetCascadeTrajectorySteps 기본 verbosity에서 argumentsJson 빈 문자열
• 해결: verbosity: 1 (DEBUG) 추가
• 주의: verbosity 0=NORMAL (키만), 1=DEBUG (값 포함)

[2026-03-10] 파일 권한 응답 — "unexpected user interaction type: not file permission"

• 증상: .agents 디렉토리 접근 시 에러
• 원인: 봇이 file_permission pending에 잘못된 interaction type 전송
• 해결: step_type별 올바른 RPC 라우팅
• 주의: file_permission과 run_command가 동시에 대기 시 올바른 RPC 라우팅 필수

[2026-03-10] active_project.lock — 멀티 프로젝트 동시 사용 차단

• 증상: 여러 AG 프로젝트 실행 시 첫 번째만 bridge 연결
• 원인: active_project.lock 파일이 단일 프로젝트만 허용
• 해결: lock 메커니즘 완전 제거, project_name 필터 기반으로 전환
• 주의: bridge 격리는 project_name 필드 기반 filtering으로 충분

[2026-03-10] step_probe file_permission — 3-button 미주입

• 증상: Discord에 3개 선택지 대신 2개만 표시
• 원인: writePendingApproval()이 buttons 배열 미주입
• 해결: step_type === 'file_permission'일 때 자동 3-button 배열 주입
• 주의: DOM observer 경로는 기존 command 텍스트 기반 감지 유지

[2026-03-10] GetAllCascadeTrajectories — 크로스 윈도우 세션 가로채기

• 증상: Deriva AG에서 대화 시작 → gravity_control 채널에 Deriva 내용이 릴레이
• 원인: GetAllCascadeTrajectories가 모든 인스턴스의 세션 반환
• 해결: workspaces[0].workspaceFolderAbsoluteUri 비교하여 자기 workspace 세션만 처리
• 주의: workspace URI normalize 필수 (protocol strip, %3A decode, 슬래시 통일, lowercase)

[2026-03-10] 크로스 프로젝트 Response Watcher 우회

• 증상: Deriva 세션 승인 시도가 gravity_control에서 실패
• 원인: pending 파일 삭제 후 response watcher가 project_name 체크 건너뜀
• 해결: response JSON의 project_name으로 fallback 필터
• 주의: response 데이터 자체에 project_name 필수

[2026-03-10] file_permission — write 도구 3-button 미주입

• 증상: replace_file_content 등 파일 수정 시 Discord에 2개만 표시
• 원인: step_probe의 file_permission 도구 리스트에 write 도구 누락
• 해결: write 도구를 file_permission 리스트에 추가
• 주의: AG가 파일 접근 권한을 요청하는 모든 도구는 이 리스트에 포함필요

[2026-03-10] bestSession IDLE 고착 — RUNNING 세션 못 잡는 버그

• 증상: 새 대화 시작 → bridge가 구 IDLE 세션만 추적
• 원인: bestSession 선택이 lastModifiedTime만 비교
• 해결: RUNNING 세션이 IDLE보다 항상 우선
• 주의: Reload Window로도 해결되지만 근본적으로는 RUNNING 우선 로직 필요

[2026-03-10] Bot IDLE 채널 자동 생성 — 불필요한 Discord 채널 증식

• 증상: 봇 시작 시 모든 등록된 프로젝트의 채널을 자동 생성
• 원인: pending_approval_scanner가 매 사이클마다 채널 생성
• 해결: 자동 채널 생성 루프 제거, on-demand 생성
• 주의: _get_channel()은 이미 on-demand 생성 로직 포함

[2026-03-10] Reload Window 후 세션 stale

• 증상: Reload Window 후 세션이 IDLE/구 stepCount로 고정
• 원인: LS 프로세스는 유지되어 trajectory tracker 캐시 미갱신
• 해결: AG 완전 종료 → 재실행 (Full restart)
• 주의: Extension 코드 변경 후 배포 시 Full restart 권장

[2026-03-10] start_bot.bat — Windows Store Python 스텁 우선 실행

• 증상: start_bot.bat 실행 시 스텁이 먼저 실행
• 원인: where python이 Windows Store의 Python 스텁을 먼저 찾음
• 해결: conda 경로를 우선 확인
• 주의: Windows 10/11에서 App Aliases의 python.exe가 PATH에 기본 포함

[2026-03-10] VSIX 빌드 — SDK JS 파일 미포함 (require 실패)

• 증상: Extension 활성화 후 SDK not initialized
• 원인: TypeScript 컴파일러가 .js 파일을 out/에 복사하지 않음
• 해결: compile 스크립트에 복사 단계 추가 (src/sdk/ → out/sdk/)
• 주의: VSIX 패키징은 out/sdk/를 포함함. 문제는 빌드 단계 복사 누락

[2026-03-10] SDK _findLSProcess — 대소문자 구분 workspace hint 매칭 실패

• 증상: variet-agent AG에서 Discord에 신호 미도달
• 원인: SDK가 workspace hint를 대소문자 구분으로 비교
• 해결: fixLSConnection() 함수로 대소문자 무시 비교 + 재연결
• 주의: 각 AG 창마다 별도 LS 프로세스 존재 (workspace_id로 구분)

---

환경변수 / 설정 관련 (2026-03-11)

[2026-03-11] config.py BRAIN_PATH — .env 빈 문자열 → CWD 해석 버그

• 증상: 봇이 Extension의 snapshot/pending을 전혀 읽지 못함
• 원인: .env에 BRAIN_PATH= (빈 값)이면 빈 문자열 반환
• 해결: os.getenv("BRAIN_PATH") or default 패턴
• 주의: os.getenv(key, default)는 빈 값이라도 default 미사용

[2026-03-11] Extension DEDUP MERGE — 크로스 프로젝트 pending 오염

• 증상: #ag-lifetimepd 채널에 variet_agent의 승인 요청 표시
• 원인: DEDUP 로직이 project_name을 체크하지 않음
• 해결: 3곳 dedup 조건에 project_name 가드 추가
• 주의: 모든 Extension 인스턴스가 동일한 bridge/pending/ 디렉토리 공유

[2026-03-11] Collector 동기 HTTP — aiohttp 전환

• 증상: Collector가 이벤트 루프 전체 블로킹
• 원인: urllib.request.urlopen() 사용 (blocking I/O)
• 해결: aiohttp.ClientSession 기반 비동기 전환
• 주의: import aiohttp는 lazy

---

Rate Limit / 무한 루프 관련 (2026-03-12)

[2026-03-12] RemoteTransport 429 무한 루프 — Extension 크래시 + AG 먹통

• 증상: 429 Rate limited 로그가 초당 수십 건 무한 반복
• 원인: 3가지 복합 (백오프 없음 + 개별 HTTP 요청 + 공격적 rate limit)
• 해결: 지수 백오프 + Retry-After 지원 + rate limit 완화
• 주의: AG 먹통은 봇 자체가 유발한 문제

[2026-03-12] workbench.html 0-byte 파괴 — AG 새 창 먹통

• 증상: AG 새 창 열면 화면 먹통
• 원인: 3개 Extension 인스턴스가 동시에 workbench.html 읽기/쓰기 → 0 bytes로 덮어쓰기
• 해결: pre-patch backup(.orig) + 구조 검증 + 자동 복원
• 주의: 멀티 윈도우 환경에서 HTML 패치 race condition은 파일 잠금 없이 완전 해결 불가

[2026-03-12] workbench.html 크로스 복원 — CSS 미로딩으로 레이아웃 깨짐

• 증상: 아이콘은 보이지만 레이아웃 완전 깨짐
• 원인: workbench.html을 jetski HTML에서 복원할 때 CSS 교체 누락
• 해결: 파일별 requiredMarker 검증 + .orig 백업 + 자동 복원
• 주의: workbench.html과 workbench-jetski-agent.html은 교환 불가능

[2026-03-12] Collector 단일 프로젝트 폴링 — 멀티 프로젝트 command 전달 불가

• 증상: Deriva AG IDE에 명령 전달되지 않음
• 원인: Collector가 단일 프로젝트만 폴링
• 해결: _discover_local_projects()로 모든 프로젝트 폴링
• 주의: /api/commands/all 엔드포인트는 크로스 PC 명령 오염을 유발

[2026-03-12] RemoteTransport backing off 무한 반복

• 증상: IDLE 시 backing off 1s 경고가 영구 반복
• 원인: 3가지 구조적 결함 (즉시 리셋 + 불필요 요청 + asyncio burst)
• 해결: 연속 5회 성공 후 절반 감소 + adaptive 간격 + 루프 stagger
• 주의: _reset_backoff() 즉시 리셋 패턴은 다중 소비자 환경에서 절대 사용 금지

---

DEDUP / 크로스 세션 관련 (2026-03-15)

[2026-03-15] DEDUP step_index 크로스 세션 충돌 — 승인 신호 누락

• 증상: WAITING step 감지 → pending 미생성 → 10분+ 대기
• 원인: DEDUP 로직이 conversation_id를 비교하지 않음
• 해결: DEDUP 조건에 conversation_id 가드 추가
• 주의: project_name 가드만으로는 불충분 — 같은 Extension이 여러 세션을 볼 수 있음

[2026-03-15] Discord Gateway MESSAGE_CREATE 중복 — embed 이중 전송

• 증상: Discord 명령 시 동일 embed가 2개 전송
• 원인: Discord Gateway가 WebSocket 불안정 시 이벤트 중복 전달
• 해결: on_message에 _processed_message_ids dedup 추가
• 주의: Gateway reconnection, RESUME 실패 시 발생 빈도 증가

[2026-03-15] HTML 패치 멀티 인스턴스 race condition — 화면 파괴

• 증상: Extension 패치 후 AG 재시작 시 전체 화면 날아감
• 원인: 2+ Extension 인스턴스가 동시에 같은 HTML에 readFileSync/writeFileSync
• 해결: .patch-lock 파일 기반 cross-instance lock 추가
• 주의: Lock은 "방지", .orig 백업은 "복구". 둘 다 유지

[2026-03-15] 로컬 승인 ↔ Discord 승인 교차 race condition

• 증상: AG에서 직접 Run 클릭 후 Discord 승인 요청이 "완료됨" 표시 안 됨
• 원인: auto_resolve가 Discord에 알림 없음 + processResponseFile 상태 미체크
• 해결: writeChatSnapshot 추가 + 상태 확인 후 skip + _approval_messages dict
• 주의: processResponseFile L2534의 리셋이 핵심 gate

[2026-03-15] 크로스 프로젝트 DEDUP MERGE — Deriva→gravity_control 오염

• 증상: Deriva의 데이터가 gravity_control pending에 MERGE됨
• 원인: MERGE 조건에 project_name 가드 없음
• 해결: MERGE 조건에 project_name 추가
• 주의: bridge/pending/ 디렉토리는 모든 Extension 인스턴스가 공유

[2026-03-15] Double-Fire Auto-Approve — AI 세션 중단

• 증상: auto-approve ON 시 AI 세션이 간헐적으로 중단
• 원인: Extension auto-approve 경로 + Bot auto-approve 경로 동시 실행 → 2번 RPC
• 해결: Extension auto-approve 경로 제거. Bot만 담당
• 주의: 단일 경로 원칙 유지

[2026-03-15] DOM Observer "Deny" False Positive — Auto-approve 세션 크래시

• 증상: auto-approve ON 시 "Deny" command가 자동 승인됨 → 세션 크래시
• 원인: DOM observer가 Deny를 독립 pending으로 생성. default 분기로 잘못된 RPC 전송
• 해결: FALSE_POSITIVE_RE에 Deny/Allow Once 등 추가 + reject-word 차단 가드
• 주의: VSIX 빌드 → AG 풀 재시작 필요

[2026-03-15] PATS 배열 Deny 트리거 — 근본 수정

• 증상: Deny가 주 트리거로 사용됨
• 원인: PATS 배열에 Deny 패턴 포함
• 해결: PATS에서 거절/보조 버튼 제거. 긍정 버튼만 그룹 트리거
• 주의: PATS = "그룹 생성 트리거", ALL_ACTION_RE = "형제 수집 패턴"

[2026-03-15] Auto-Resolved 채팅 폭주 — 루프 내 writeChatSnapshot

• 증상: "✅ AG에서 직접 승인됨" 메시지가 반복 전송
• 원인: 루프 내부에서 매 파일마다 writeChatSnapshot 호출
• 해결: 루프 바깥에서 1회 + conversation_id 조건 추가
• 주의: 외부 시스템에 메시지 보낼 때는 반드시 루프 바깥에서 집계 후 1회 발송

[2026-03-15] projectName=default 승인 오발

• 증상: workspace 없는 AG 창이 다른 프로젝트의 WAITING을 감지
• 원인: detectProjectName()이 workspace 없으면 "default" 반환
• 해결: projectName === 'default'이면 pending 생성/auto-approve 억제
• 주의: Empty Window에서는 bridge 기능을 최소화

[2026-03-15] 이전 분석 오판(False Positive) — 교훈

• 증상: P0/P1으로 보고한 문제들이 이미 방어되고 있었음
• 원인: 로컬 코드 스니펫만 보고 판단
• 해결: 전체 Flow 추적으로 교차 검증
• 주의: 코드 감사 시 반드시 producer→transport→consumer→side effects 전체 경로를 추적

---

processResponseFile 상태 관리 (2026-03-16)

[2026-03-16] processResponseFile 상태 리셋 — 무한 루프 vs auto_resolve 회귀

• 증상: Discord 승인 후 같은 step에 대해 pending이 반복 생성 → 무한 auto-approve 루프
• 원인: processResponseFile이 무조건 리셋 → step_probe가 같은 WAITING step을 새 step으로 착각
• 해결: sawRunningAfterPending = true만 설정. lastPendingStepIndex와 stallProbed 유지
• 주의: processResponseFile의 상태 리셋은 sawRunningAfterPending = true만 설정. docs/approval-flow.md 참조

[2026-03-16] recentPendingSteps 메모리 dedup

• 증상: pending 파일 삭제 → 같은 step_index로 새 pending 생성
• 원인: writePendingApproval()의 dedup이 파일 존재 여부에만 의존
• 해결: recentPendingSteps Map (TTL 60초) 추가
• 주의: DOM observer HTTP 경로는 이 메모리 dedup 미적용

[2026-03-16] 멀티 프로젝트 동시 신호 정지 — Scanner O(N) Discord API 병목

• 증상: 여러 프로젝트 동시 pending → 모든 프로젝트 신호 전달 정지
• 원인: scanner가 1 tick에 모든 pending 순차 처리 → Discord 429 rate limit
• 해결: discord.utils.get(guild.channels) 캐시 + per-tick cap (5건)
• 주의: guild.channels는 discord.py 내부 캐시

---

Diff Review 관련 (2026-03-16)

[2026-03-16] step_type 매핑 버그 — write_to_file이 file_permission으로 잘못 매핑

• 증상: 코드 편집 승인 시 잘못된 RPC 전송
• 원인: 쓰기 도구가 읽기 도구와 함께 file_permission으로 매핑
• 해결: 읽기/쓰기 도구 분리, 쓰기는 code_edit step_type 사용
• 주의: AG는 대부분 파일 쓰기에 WAITING 안 만듦

[2026-03-16] diff_review isDirty 실패 — AG diff는 VS Code dirty 아님

• 증상: Accept 클릭 → isDirty 문서 0개 → 효과 없음
• 원인: AG stacked code review는 VS Code isDirty와 무관
• 해결: AcknowledgeCascadeCodeEdit RPC → fallback으로 VS Code 커맨드
• 주의: diff_review pending에 modified_files와 edit_step_indices 필수

[2026-03-16] diff_review pending 순서 — AI 응답보다 먼저 Discord 도착

• 증상: diff_review 버튼이 먼저, AI 응답 텍스트가 나중
• 원인: pending_approval_scanner가 chat_snapshot_scanner보다 먼저 fire
• 해결: diff_review pending 생성을 setTimeout(8000)으로 지연
• 주의: 8초는 전체 전파 경로 고려

[2026-03-16] diff_review AcknowledgeCascadeCodeEdit steps=[] — Collector pending 삭제 race

• 증상: Accept all 클릭 → RPC SUCCESS → diff review 바 안 사라짐
• 원인: Collector가 pending 파일 즉시 삭제 → Extension이 메타데이터 못 읽음
• 해결: diffReviewMetadata 인메모리 Map 추가
• 주의: Extension Reload 시 소실되지만 새 diff_review는 정상 동작

[2026-03-16] AcknowledgeCascadeCodeEdit SUCCESS → diff review bar 미해제 — 잘못된 RPC 메서드명

• 증상: RPC SUCCESS 반환 → diff review bar 여전히 표시
• 원인: RPC 메서드명 자체가 틀렸음 (AcknowledgeCascadeCodeEdit → 실제는 acknowledgeCodeActionStep)
• 해결: agentAcceptAllInFile / agentRejectAllInFile VS Code 커맨드 사용
• 주의: AG의 RPC는 잘못된 메서드명도 에러 없이 {} 반환. RPC {}는 실패로 간주해야 함

[2026-03-16] diff_review RPC 3개 전략 모두 dead-end

• 증상: 3개 RPC 전략 모두 실패
• 원인: (1) submitCodeAcknowledgement 미등록, (2) acknowledgeCodeActionStep 404, (3) AcknowledgeCascadeCodeEdit no-op
• 해결: VS Code 커맨드 기반 (agentAcceptAllInFile / agentRejectAllInFile)
• 주의: diff_review를 RPC로 해결하려는 시도 모두 실패 확정. VS Code 커맨드 기반만 유효

[2026-03-16] AG 소스 역분석 — diff review 내부 동작 체인

• 증상: Accept all / Reject all 내부 동작을 재현해야 함
• 원인: AG 공식 API/문서 없음
• 해결: AG 설치 경로의 JS 소스에서 역분석
• 주의: minified JS에서 변수명은 버전마다 변경됨

[2026-03-16] diff_review 이중 승인 요청 — DOM observer가 Accept/Reject 버튼 캡처

• 증상: diff_review 외에 별도 "Accept"/"Reject" pending 도착
• 원인: openReviewChanges 커맨드가 diff UI 패널 → DOM observer 감지
• 해결: FALSE_POSITIVE_RE에 Accept/Reject all 추가
• 주의: diff review bar 버튼은 전용 시스템에서 처리

[2026-03-16] diff_review가 brain/ artifact에도 트리거

• 증상: task.md만 수정해도 "코드 리뷰" pending 생성
• 원인: diff_review 감지 로직이 모든 수정 파일 추적
• 해결: .gemini/antigravity/brain/ 경로 파일 필터링하여 제외
• 주의: 코드 파일 + brain artifact 혼합 시 코드 파일만 diff_review

---

WS Hub 전환 관련 (2026-03-16~17)

[2026-03-16] !auto 이중 메시지 — Extension echo + Bot embed

• 증상: !auto 토글 시 메시지 2개 표시
• 원인: Bot embed + Extension writeChatSnapshot echo
• 해결: Extension의 !auto handler에서 writeChatSnapshot echo 제거
• 주의: Bot 재시작 시 auto_approve_projects 초기화 → 수동 모드 복귀

[2026-03-16] 병렬 WAITING step 누락 — step_probe break문

• 증상: 병렬 tool call 시 1개만 승인 요청 도착
• 원인: step_probe 루프에서 break문이 첫 번째 WAITING 후 종료
• 해결: break 제거, 모든 WAITING step에 pending 생성
• 주의: 중복 방지는 recentPendingSteps Map이 처리

[2026-03-16] Bot chat_snapshot 전송 로깅 부재

• 증상: 전송 성공/실패를 Bot 로그에서 확인 불가
• 원인: channel.send() 성공 후 INFO 로그 없음
• 해결: 전송 성공/실패 로그 추가
• 주의: _get_channel() 실패 시 WARNING은 이전에도 있었음

[2026-03-16] 크로스 프로젝트 이벤트 폭주 — Watcher/Collector 무필터

• 증상: /start 시 타 프로젝트 알림 유입
• 원인: watcher.py가 brain/ 전체를 감시
• 해결: _is_my_session() 필터 + 이벤트 전달 필터 추가
• 주의: 미등록 세션은 allow-through 방식

[2026-03-16] pending 파일 139개 누적 — 정리 로직 부재

• 증상: bridge/pending/에 139개 파일 누적
• 원인: auto_resolved/expired 파일을 아무도 삭제 안 함
• 해결: Collector에서 auto_resolved/expired 전달 후 삭제 + 10분 자동 삭제
• 주의: startup_pending은 정리 대상에서 제외

[2026-03-17] NPM WebSocket 프록시 — Upgrade 헤더 미전달

• 증상: wss://ag.variet.net/ws 연결 시 HTTP 400
• 원인: Nginx Proxy Manager에 WebSocket Support 미활성화
• 해결: NPM 대시보드에서 Websockets Support 체크
• 주의: 새 프록시 호스트 생성 시 반드시 확인

[2026-03-17] WS auth_fail 무한 재연결 — _cleanup() close 이벤트

• 증상: Auth failed 후 60초마다 재연결 반복
• 원인: _cleanup()이 ws.close() → close 이벤트 → _scheduleReconnect() 체인
• 해결: this.shouldReconnect = false를 _cleanup() 이전에 설정
• 주의: _cleanup()은 이벤트 핸들러를 트리거하므로 상태 변경은 반드시 호출 전에

[2026-03-17] initStepProbe workspaceUri 누락 — 세션 감지 완전 불능

• 증상: POLL alive만 출력, SESSION-FILTER/SNAPSHOT 없음
• 원인: initStepProbe() 호출 시 필수 필드 미전달 + as 캐스트가 런타임 검증 없음
• 해결: workspaceUri, diffReviewMetadata: new Map() 추가
• 주의: TypeScript as 캐스트는 런타임 검증 없음

[2026-03-17] WS 명령어 에코 릴레이 — Discord 메시지 2번 표시

• 증상: Discord 메시지 입력 → 같은 메시지가 다시 표시
• 원인: handleWSCommand에서 recentDiscordSentTexts에 마킹 안 함
• 해결: recentDiscordSentTexts.set() 추가
• 주의: 파일 기반 경로에는 이미 마킹 있었음

[2026-03-17] writeRegistration 이중 쓰기 — WS 전송 후 파일도 작성

• 증상: WS 상태에서도 register/ 파일 생성
• 원인: WS 전송 후 return 없이 파일 쓰기 실행
• 해결: WS 전송 후 return 추가
• 주의: 새 WS 전송 함수 추가 시 file fallback과 상호 배타적 return 확인