docs: V8 CachedData diagnosis + cache clearing for renderer v3 #task-264

.agents/references/known-issues.md

@@ -200,6 +200,12 @@
 - **해결**: 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-09] V8 CachedData — 체크섬 정상이어도 스크립트 미실행
+- **증상**: HTML 패치 + product.json 체크섬 일치 + Bridge 서버 정상 → 그런데도 renderer 스크립트 미실행 (`/deep-inspect` timeout)
+- **원인**: AG 프로세스 인자 `--code-cache-schemes=vscode-webview,vscode-file`에 의해 V8 바이트코드 캐시가 `vscode-file://` 프로토콜에도 적용. product.json 체크섬 검증과 V8 코드 캐시는 **별도 메커니즘** — 체크섬이 맞아도 V8은 `%APPDATA%\Antigravity\CachedData`의 이전 컴파일된 바이트코드를 재사용
+- **해결**: `%APPDATA%\Antigravity\CachedData\*` 전체 삭제 후 AG 풀 재시작. AG 실행 중에도 삭제 가능 (파일 잠금 없음 확인됨)
+- **주의**: CachedData 삭제 후 첫 시작이 약간 느릴 수 있음 (V8이 모든 JS를 재컴파일). **HTML 패치 변경 시마다 CachedData 삭제 필수**. `product.json` 체크섬 업데이트만으로는 불충분
+
 ---
 
 ## 승인 전략 결정 체인 (다음 세션 필독)
@@ -224,7 +230,7 @@
 
 | # | 접근 | 상태 | 다음 단계 |
 |---|------|------|-----------|
-| 1 | **Renderer v3 Deep DOM Traversal** | 구현+배포+pre-patch 완료, **AG 재시작 후 검증 필요** | AG 재시작 → `/deep-inspect` 결과 확인 |
+| 1 | **Renderer v3 Deep DOM Traversal** | 패치+체크섬 OK, **V8 CachedData 삭제 완료, AG 재시작 후 검증** | AG 재시작 → `curl.exe http://127.0.0.1:34332/deep-inspect` |
 | 2 | `<webview>.executeJavaScript()` | v3에 포함, **미검증** | 위 결과에서 `hasExecJS=true`이면 유력 |
 | 3 | TerminalExecutionPolicy.EAGER (Turbo) | 미시도, **최후 수단** | 통제권 포기이므로 사용자 승인 필요 |
 
@@ -234,4 +240,5 @@
 - `<webview>.executeJavaScript()`가 **유일한 표준 관통 경로** (Electron API)
 - AG 패치 후 **반드시 풀 프로세스 재시작** 필요 (Reload Window 불충분)
 - **양쪽 HTML (workbench.html + workbench-jetski-agent.html) 모두 inline 패치** 필수
+- HTML 패치 변경 시 **`%APPDATA%\Antigravity\CachedData` 삭제 필수** (V8 바이트코드 캐시 무효화)