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

Known Issues & Lessons Learned

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

---

포맷

각 항목은 아래 형식을 따릅니다:

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

---

공통 이슈

[2026-03-08] PowerShell curl — Invoke-WebRequest 충돌

• 증상: curl 명령이 예상과 다른 응답 형식을 반환
• 원인: PowerShell에서 curl은 Invoke-WebRequest의 별칭
• 해결: **curl.exe**를 명시적으로 사용
• 주의: HTTP 관련 모든 명령에서 curl.exe 사용 필수

[2026-03-08] PowerShell npm — 실행 정책 오류

• 증상: npm run 명령이 실행 정책 관련 오류로 실패
• 원인: PowerShell 스크립트 실행 정책이 제한적으로 설정됨
• 해결: cmd /c npm run dev 형식으로 cmd를 통해 실행
• 주의: npm 관련 명령은 항상 cmd /c 접두어 사용 권장

---

프로젝트별 이슈

아래에 프로젝트 특화 이슈를 추가하세요.

[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] Extension 컴파일 경로 != 설치 경로

• 증상: npm run compile 후 Extension 동작이 변하지 않음
• 원인: npm run compile은 extension/out/extension.js에만 빌드. Antigravity는 ~/.antigravity/extensions/variet.gravity-bridge-X.X.X/out/extension.js에서 로드
• 해결: 컴파일 후 반드시 설치 경로로 수동 복사하거나, vsce package → VSIX 재설치
• 주의: extension/out/ ≠ 실행 경로. 항상 설치 경로 확인 필요

[2026-03-08] Electron 메인 프로세스 체크섬 캐시 — Reload Window 불충분

• 증상: product.json 체크섬 업데이트 + HTML 패치 후 Reload Window → 패치 미적용
• 원인: Electron 메인 프로세스가 시작 시 product.json 체크섬을 메모리에 캐시. Reload Window는 렌더러만 재시작하므로 캐시된 구 체크섬 사용
• 해결: Antigravity를 완전 종료 후 재시작 필요 (File → Exit 후 재실행)
• 주의: Reload Window ≠ 앱 재시작. 체크섬 변경 시 항상 풀 재시작 필요

[2026-03-08] Renderer 동기 XHR — Electron 보안 정책 차단

• 증상: tryPing() 함수가 동기 XMLHttpRequest로 HTTP bridge에 연결 시도 → 타임아웃
• 원인: Electron 렌더러 프로세스에서 동기 XHR이 보안 정책에 의해 차단됨
• 해결: fetch() + AbortSignal.timeout(2000) 비동기 방식으로 교체 (tryPingAsync)
• 주의: async/await 사용 불가 (ES5 환경). .then() 체이닝으로 구현

[2026-03-08] DOM Observer — Run 버튼 감지 불가 (webview iframe 격리)

• 증상: Allow Once/Allow This Conversation는 감지되나 Run/Accept 버튼은 감지 안 됨
• 원인: Trust/permission 버튼은 워크벤치 외부 DOM에 렌더링, Run/Accept는 Antigravity 채팅 webview iframe 내부의 별도 DOM에 렌더링. 렌더러 스크립트의 document.querySelector()는 iframe 내부 접근 불가
• 해결: Run 버튼은 DOM Observer가 아닌 latestToolCallStep RPC 기반 즉시 감지로 대체
• 주의: webview iframe에 스크립트 주입은 Electron executeJavaScript()로 가능하나, 현재 RPC 방식이 더 안정적

[2026-03-08] Accept all/Reject all 리뷰 바 — agent 패널 밖 DOM

• 증상: 코드 변경 리뷰 바(Accept all/Reject all)가 DOM Observer에 감지 안 됨
• 원인: scan() 함수가 findPanel() (.antigravity-agent-side-panel 등) 내부만 검색. 리뷰 바는 에디터/notification 영역에 렌더링되어 패널 밖에 있음
• 해결: scan() 검색 범위를 document.body 전체로 확장, Accept all / Reject all 패턴 추가
• 주의: 패널+body 이중 검색 시 dedupe 필요 (같은 버튼이 두 번 잡힐 수 있음)

[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()가 자동으로 모든 패치를 수행:
  1. workbench.html + workbench-jetski-agent.html 인라인 스크립트 삽입
  2. product.json SHA256 체크섬 자동 업데이트
  3. HTTP bridge 서버 시작 + 결정론적 포트
• 주의: 패치 후 반드시 Antigravity 풀 재시작 필요 (Reload Window 불가). Extension VSIX만 설치하면 수동 패치 불필요

[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파일과 중복로드 방지됨). 직접 JS파일 패치는 Reload시 소스에서 재생성되어 덮어씌워짐
• 해결: 항상 extension.ts의 generateApprovalObserverScript() 함수를 수정 → 컴파일 → 배포 → Reload
• 주의: HTML inline은 JS파일이 먼저 로드되어 window.__agSDK 가드에 의해 실행 안 됨. 실제 실행되는 것은 JS파일 경로의 스크립트

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

• 증상: Discord 승인 → antigravity.terminalCommand.run 등 7개 명령 → 모두 command not found
• 원인: SDK(command-bridge.ts)에 정의된 7개 승인 명령이 현재 AG 빌드에 등록되어 있지 않음. 활성 시 72개, 세션 중 119개로 동적 등록되지만 승인 관련 명령은 없음
• 검증:
  • HandleCascadeUserInteraction RPC 3 variants → 모두 socket hang up
  • ResolveOutstandingSteps → run state not found (500 에러, 실제로는 CANCEL 동작)
  • sendChatActionMessage, executeCascadeAction → 119개 명령 중 미등록
  • 존재하는 approval-like 명령: agentAcceptAllInFile (코드 diff), agentAcceptFocusedHunk (hunk), acceptCompletion (자동완성) — 터미널 승인과 무관
• 해결: Renderer DOM Click 구현됨 (미검증) → v1 검증 실패: webview iframe 격리 확인. v3 deepFindButtons()로 업그레이드 (iframe contentDocument + webview.executeJavaScript + shadow DOM). AG 완전 재시작 후 DOM-DUMP로 접근 가능 여부 확인 필요
• 주의: agentPanel.focus도 미등록, agentSidePanel.focus만 존재

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

• 증상: Renderer trigger-click이 document.querySelectorAll('button')으로 버튼 검색 → Run 버튼 미발견. 감지된 것은 외부 DOM의 trust-level 버튼(RunAlt+?)뿐
• 원인: Run/Accept 버튼은 AG 채팅 webview iframe (vscode-webview:// origin) 안에 렌더링. 외부 workbench DOM (vscode-file:// origin)에서 cross-origin으로 접근 불가
• 해결: Renderer v3 deepFindButtons() 구현:
  1. Main document 검색 (기존)
  2. iframe.contentDocument 접근 시도 (same-origin이면 성공)
  3. <webview>.executeJavaScript() 접근 시도 (Electron API)
  4. Shadow DOM 재귀 탐색 → 미검증 (AG 재시작 후 DOM-DUMP 결과 필요)
• 주의: CDP(Chrome DevTools Protocol)는 사용자 결정에 의해 명시적으로 거부됨 (--remote-debugging-port 필요, 비표준 접근). 표준 DOM API/Electron API 범위 내에서만 해결할 것

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

• 증상: AG DevTools 콘솔에 붙여넣기 불가 (Chromium 보안 정책)
• 원인: Electron 렌더러 DevTools에서 allow pasting이 SyntaxError 발생 (Unexpected identifier 'pasting')
• 해결: Extension HTTP bridge에 /deep-inspect 엔드포인트 추가. curl.exe http://127.0.0.1:34332/deep-inspect로 bridge→renderer→재귀 DOM 분석→결과 JSON 반환. 결과는 ~/.gemini/antigravity/bridge/deep-inspect-result.json에도 저장됨
• 주의: 시작 3초 후 자동 실행 + curl로 재트리거 가능. renderer가 2초마다 /deep-inspect-trigger 폴링

---

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

• 증상: AG 재시작 후 /deep-inspect timeout — renderer v3 스크립트 미로딩
• 원인: setupApprovalObserver()가 workbench-jetski-agent.html에만 inline 삽입하고, workbench.html에는 외부 <script src>만 추가. vscode-file:// 프로토콜은 커스텀 .js 파일을 서빙하지 않으므로 사실상 미로딩
• 해결: HTML 패치 로직을 htmlFiles = ['workbench.html', 'workbench-jetski-agent.html'] 루프로 변경하여 양쪽 모두 inline 삽입. 수동 pre-patch 스크립트(/tmp/patch_workbench.py)로 즉시 적용 + product.json 체크섬 업데이트
• 주의: 항상 양쪽 HTML을 동일하게 패치. AG가 어느 HTML을 로드할지 런타임까지 알 수 없음. pre-patch 후 1회 풀 재시작이면 충분 (체크섬 사전 업데이트 완료)

---

승인 전략 결정 체인 (다음 세션 필독)

이 섹션은 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 격리

✅ 현재 진행 중인 접근

#	접근	상태	다음 단계
1	Renderer v3 Deep DOM Traversal	구현+배포+pre-patch 완료, AG 재시작 후 검증 필요	AG 재시작 → /deep-inspect 결과 확인
2	<webview>.executeJavaScript()	v3에 포함, 미검증	위 결과에서 hasExecJS=true이면 유력
3	TerminalExecutionPolicy.EAGER (Turbo)	미시도, 최후 수단	통제권 포기이므로 사용자 승인 필요

🔑 핵심 전제

• 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 패치 필수