[Agent] 승인 메시지에서 죽는 preview 링크를 뺀다 [ #391 ]

[dldnsgkr]

두 승인 게이트가 대화 메시지 본문에 태스크의 previewUrl 을 넣고 있었다.

// ResultApprovalGate:227      + "- preview: " + previewUrl + "\n"
// RepositoryBindingGate:131   + (previewUrl == null ? "" : "- preview: " + previewUrl + "\n")

그런데 POST /preview-sessions/{id}/access 가 accessToken 을 회전시켜 이전 주소를 죽인다(G4, #77). 사용자가 화면에서 프리뷰를 여는 것이 곧 그 호출이므로:

1. 승인 메시지가 preview 링크와 함께 뜬다
2. 사용자가 프리뷰를 연다 → access 발급 → 회전
3. 그 순간부터 대화창 링크는 404. 대화 이력은 남으므로 영구히 죽은 링크가 된다

BE 가 스스로 이걸 문서화해 놓고 있었다

PreviewSessionController:47:

이전에 받은 주소(작업 응답의 previewUrl 포함)는 즉시 404가 됩니다.

알면서 그 URL 을 메시지에 넣고 있었다. 내부적으로 모순이었다.

실제로 걸렸다 — 로그가 둘을 가른다

2026-09-25 dev 검증(project 63, cafe-home):

13:09:56  POST .../access                      → 토큰 회전
13:10:34  회전된 새 토큰으로 iframe 로드        → 200  (index·styles·main.js·이미지 6장 전부)
13:10:44  대화창 링크의 옛 토큰으로 요청        → 404

FE 코드는 #77 때 이미 방어돼 있었다(agentPreview.utils.ts:8: "Agent 태스크 응답의 previewUrl이 아니다 — 그쪽은 토큰이 회전되어 이미 무효일 수 있다"). 그런데도 이 메시지를 믿고 움직인 쪽은 죽은 주소를 잡았다. 실제 사용자도 같다.

고친 내용

주소를 뺀다. 안내조차 남기지 않았다 — 승인 카드가 이미 화면에 프리뷰와 함께 뜨므로 주소도 안내도 중복이고, 주소는 거기에 해롭기까지 했다.

FRONTEND_API_GUIDE.md 483행도 고쳤다. "previewUrl 은 GET /agent/tasks/{taskId} 응답에서 얻습니다" 라고만 적혀 501행("반드시 access 응답의 previewUrl 을 사용")과 충돌했다 — 483행만 읽으면 죽은 주소를 쓴다. 회전 경고와 이번 사고를 함께 박았다.

검증

• 전체 1740건 통과, 실패 0 (skip 12)
• 회귀망 역검증: 링크를 다시 넣자 신규 테스트가 실패했다
• 기존 테스트 둘의 이름·단정을 새 계약에 맞췄다. chatMessageShowsThePreviewUrlAndThe… → …ButNeverThePreviewUrl 로 바꾸고 contains(url) 을 doesNotContain 으로 뒤집었다. 승인을 가리키는 정보(승인 ID·타입·저장소 기본 이름)는 그대로 남는지도 같이 본다 — 링크만 빼는 것이고 메시지를 비우는 게 아니다

별건

필드 이름이 같은 것(previewUrl 이 두 응답에 있고 하나만 유효)이 함정의 뿌리다. #392 로 분리했다 — 호환 깨는 변경이고 FE 는 main 머지가 곧 프로덕션이라 순서를 맞춰야 한다.

Closes #391

🤖 Generated with Claude Code

https://claude.ai/code/session_013y8USoCXTsRTATAhy88M93