세션 인증 picker 후속 (auth 실패 라우팅·CLI 번들·probe·외부링크·resolved-path)

[pdw96]

#143/#144(세션 인증 picker) 머지 후 §10 후속 묶음. 전부 v1 의도적 비목표/이연. 착수 시 fleet-backlog-induction(brainstorm→spec→plan→체크포인트). 근거·계약 = 머지된 docs/superpowers/specs/2026-06-25-session-auth-picker-design.md §7a·§10 · docs/superpowers/plans/2026-06-25-session-auth-picker.md §"미해결/후속".

picker(#144 squash a71df18)는 v1 스코프로 출하됐고, 아래는 의도적으로 뒤로 미룬 항목들. 각자 ROI 게이트(솔로 pre-1.0) 통과분만 착수.

진행 상태 (2026-06-28)

✅ 항목1·3·4·5 출하 · ⏳ 잔여 2(대형·"설치 마찰 완전 제거 필요 시" 게이트). 파생 후속 #158 ✅ 머지(PR #159 squash de218ff — 실행계층 워크스페이스 cwd shadow 하드닝: defaultRunner PATH-only 절대경로 해석으로 win32 워크스페이스 내 악성 *.cmd 셰도 차단. Codex P2·CodeRabbit Major×2 반영).

후속 항목

1. ✅ 완료 — 첫 사용 auth 실패 전용 라우팅 (스펙 §7a). classifyCliAuthHint advisory recovery hint(단일 seam assertRunOk·IPC/렌더러 무변경). 설계·스펙 Codex 리뷰 2회 + PR 봇 리뷰 클린. → CLI auth 실패 advisory recovery hint (#145 항목1·§7a 후속) #148 · PR feat(#148): CLI auth 실패 advisory recovery hint #149 squash a0d23cb.
2. CLI 번들/자동설치 (방안 ③) — 설치 의존 완전 제거. Fleet이 CLI 번들/자동 다운로드 + *auth login 대리 구동. main·CLI lifecycle·버전관리·3 CLI 각각 = 대형. 설치 마찰 완전 제거가 필요해질 때.
3. ✅ 완료 — "연결 테스트" probe (스펙 §7). CLI 세션 등록 시 선택형 인증 검증(headless 최소 프롬프트 1회·짧은 타임아웃·transient·등록 비차단). → CLI 세션 "연결 테스트" probe (#145 항목3·§7 후속) #150 · PR feat(#150): CLI 세션 '연결 테스트' probe #151 squash b3f80ad.
4. ✅ 완료 — 클릭형 외부링크 열기 (스펙 §6a). 가드된 IPC(https: only + hostname allowlist). → feat(#145): picker 문서 링크 클릭형 외부열기 (가드된 IPC) #147 5e915b6.
5. ✅ 완료 — CLI resolved-path 표시 (PATH shadowing, 스펙 §6a). picker 설치 카드에 which@2(실행기 cross-spawn 동일 계열) 해석 실행경로 표시 + 상대 PATH·앱 cwd 히트(Windows cwd-first 포함) 위험 플래그·표시 전용·비차단. → feat(#145): CLI resolved-path 표시 (PATH shadowing 탐지) #157 squash a65fa29. 봇: Codex 설계승인+P2/P1 반영·CodeRabbit 3건. 실행계층 cwd 하드닝은 CLI 세션 워크스페이스 cwd shadow 하드닝 — PATH 해석 절대경로로 cwd-독립 실행 (#157 Codex P1 후속) #158 로 분리.

비목표

• v1에서 이미 출하/해결된 것(copy-only·단일출처·미검증 배지·API parity[listModels race-guard·effort·cacheTtl·baseUrl]·키 마스킹/초기화/검증·displayName·더블서밋 가드·loadingModels 인디케이터)은 재론 금지 — 봇 리뷰 라운드까지 반영 완료.

참고

• 메타: 메타: 백로그 우선순위 / 로드맵 (코드 검증 기반) #27 · 머지: feat(#143): 세션 등록 인증 picker — 구독(CLI 위임) / API 키 가이드 흐름 #144(a71df18)·feat(#145): picker 문서 링크 클릭형 외부열기 (가드된 IPC) #147(5e915b6, 항목4)·feat(#148): CLI auth 실패 advisory recovery hint #149(a0d23cb, 항목1)·feat(#150): CLI 세션 '연결 테스트' probe #151(b3f80ad, 항목3)·feat(#145): CLI resolved-path 표시 (PATH shadowing 탐지) #157(a65fa29, 항목5) · 후속: CLI 세션 워크스페이스 cwd shadow 하드닝 — PATH 해석 절대경로로 cwd-독립 실행 (#157 Codex P1 후속) #158 · 설계 체크포인트: 세션 등록 인증 picker — 구독(CLI 위임) / API 키 가이드 흐름 (opencode/antigravity식) #143·CLI auth 실패 advisory recovery hint (#145 항목1·§7a 후속) #148·CLI 세션 "연결 테스트" probe (#145 항목3·§7 후속) #150·feat(#145): CLI resolved-path 표시 (PATH shadowing 탐지) #157

[pdw96]

설계 체크포인트 — #145 항목4: picker 문서 링크 클릭형 외부열기(가드된 채널)

백로그 착수 체크포인트(코딩 전 설계). 코드 작성 전에 독립 검증을 받기 위한 등재 — @codex review 요청.
근거 계약 = 머지된 스펙 docs/superpowers/specs/2026-06-25-session-auth-picker-design.md §6a 외부 링크 보안 계약.

선정 맥락

• tier:next 소진(메타: 백로그 우선순위 / 로드맵 (코드 검증 기반) #27 13차 재랭킹) → 착수 가능 후보 중 사용자가 세션 인증 picker 후속 (auth 실패 라우팅·CLI 번들·probe·외부링크·resolved-path) #145 항목4(클릭형 외부링크 열기) 선택.
• 현재 src/renderer/components/AddAiWizard.tsx(구독 단계)는 meta.docsUrl을 copy-only(<code> + clipboard)로만 표시. 스펙 §6a가 "v1=copy-only, 클릭형 외부열기는 가드된 후속"으로 못박아둠 → 이 작업이 그 후속을 구현.
• 데이터(DOCS_HOST_ALLOWLIST 9-host·docsUrl)는 이미 src/shared/cliAuthInstallMeta.ts에 준비됨.

핵심 결정

• D1 — IPC 형태 = 식별자만 전달 (대안 검토 후 선택): renderer는 adapterId('claude'|'codex'|'gemini')만 전달 → main이 정적 CLI_AUTH_INSTALL_META[adapterId].docsUrl을 자기 측에서 도출 → 재검증 → shell.openExternal. renderer가 URL 문자열을 아예 보내지 않음 → 주입면 0.
  • 기각한 대안: "URL 전달 + main 재검증". 범용적이나 renderer(=LLM 출력이 닿을 수 있는 신뢰경계)가 URL을 결정 → allowlist 검증 버그 시 공격면 존재.
• D2 — 범위 = docsUrl만 외부열기. loginCommand/installHint는 명령어라 copy-only 유지(§6a "복사용 명령은 표시·복사 전용", 터미널 자동실행 비목표 D3).
• D3 — window-guards 불변: shell.openExternal은 main이 OS 기본 브라우저로 위임 — renderer 네비게이션/window.open이 아님. src/main/window-guards.ts의 installNavigationGuards(새 창·will-navigate/redirect/frame-navigate 전면 차단)는 약화 0으로 그대로. renderer는 여전히 외부로 못 감.

데이터 흐름

[wizard] "문서 열기" 버튼 클릭  (URL 복사 버튼 옆 — copy는 fallback 유지)
  → window.fleet.openCliDocs(adapterId)              [preload]
  → ipcRenderer.invoke('fleet:external:openDocs', adapterId)
  → ipcMain.handle (src/main/index.ts)
  → openVerifiedCliDocs(adapterId)                   [신규: src/main/external-links.ts]
       · CLI_AUTH_INSTALL_META[adapterId].docsUrl 도출  (정적 shared 맵)
       · 검증: new URL → protocol==='https:' && hostname ∈ DOCS_HOST_ALLOWLIST
       · 통과 → shell.openExternal(url)  /  실패 → throw (정적 맵이라 정상 경로는 항상 통과)

가드 (적대적)

차단 대상	방어
http:/file:/javascript:/vbscript:/SMB(\\) 스킴	protocol === 'https:' 정확 일치
docs.anthropic.com.evil.com 서브도메인 트릭	hostname allowlist 정확 매칭(부분일치 금지)
https://docs.anthropic.com@evil.com userinfo 트릭	new URL().hostname → evil.com 반환 → 매칭 실패
알 수 없는/스푸핑된 adapterId	맵 미존재 시 거부
정적 맵 미래 오염	심층방어 — renderer가 식별자만 보내도 main이 도출한 URL을 재검증

신규 표면 (격리·단일책임)

• src/main/external-links.ts — isAllowedDocsUrl(url): boolean(순수: https + allowlist 정확매칭) + openVerifiedCliDocs(adapterId, deps?)(맵 도출→검증→shell.openExternal). shell을 주입 가능하게 해 호출/미호출을 단위테스트로 단언. 검증 함수를 I/O와 분리 → 적대 케이스 전수 테스트.
• preload: FleetBridge.openCliDocs(adapterId): Promise<void> 추가 → IPC fleet:external:openDocs (src/main/ipc-parity.test.ts 자동 통과).
• UI: 구독 단계에 "문서 열기" 버튼 추가(URL 텍스트 노출 유지 → §6a "링크 텍스트와 실제 URL 함께 표시" 충족).

테스트 (TDD)

• 단위(external-links.test.ts): https 통과 / http·file·javascript 거부 / allowlist hostname 통과 / 비-allowlist·서브도메인·@userinfo 트릭 거부 / 각 adapterId의 meta.docsUrl이 allowlist에 ∈(meta 변경 시 가드 동기화 회귀) / 검증 통과 시 shell 호출·실패 시 미호출(mock 주입).
• renderer(vitest): "문서 열기" 버튼이 openCliDocs(adapterId) 호출.
• ipc-parity 자동. e2e는 실 shell.openExternal이 OS 브라우저를 띄워 회피 — 단위로 충분.

리뷰 요청 포인트 (@codex)

1. 식별자-전달 IPC가 URL-전달보다 실제로 공격면을 줄이는가? 놓친 우회 경로는?
2. shell.openExternal 도입이 window-guards 전면차단 모델을 약화시키지 않는다는 D3 주장이 타당한가? (main 위임 경로 vs renderer 네비)
3. https + hostname 정확매칭 외에 추가로 막아야 할 벡터 — redirect 체인 / IDN homograph / punycode 등? §6a는 "redirect 최종 URL까지 검증하거나 정적 상수만 허용"인데, 식별자-전달(정적 상수만) 선택이 redirect 검증 불요로 충분한가?
4. ADR 불요 판단(외부열기 정책이 스펙 §6a에 이미 정착 → 이번은 구현)이 맞나, 아니면 "전면차단 모델 첫 예외"라 ADR로 남길 가치가 있나?

@codex review

[chatgpt-codex-connector]

설계 리뷰 결과 — 승인 의견, 단 ADR는 “짧게” 권장

요청하신 #145 항목4 설계는 Fleet의 기존 보안 모델과 일관되며 구현해도 괜찮은 방향입니다. 특히 renderer가 URL을 보내지 않고 adapterId만 보내는 IPC는 URL 전달 방식보다 공격면을 실질적으로 줄입니다. 현재 스펙도 외부 링크 후속은 “main의 좁은 IPC + https: only + hostname allowlist”를 요구하고, docsUrl은 사용자 입력/원격/AI 출력이 아닌 정적 데이터만 허용한다고 못박고 있습니다.

질문별 검토

1. 식별자-전달 IPC가 URL-전달보다 공격면을 줄이는가?

네. 이 설계가 더 안전합니다.

현재 정적 메타는 CLI_AUTH_INSTALL_META에 있고, 각 CLI별 docsUrl도 이미 shared 단일 출처 데이터로 제한되어 있습니다. 또한 allowlist는 정적 9-host 집합으로 선언되어 있습니다.

따라서 renderer가 adapterId만 보내고 main이 CLI_AUTH_INSTALL_META[adapterId].docsUrl을 직접 도출하면:

• renderer/LLM 출력/DOM 조작이 URL 문자열을 결정할 수 없습니다.
• IPC 경계에서 URL parser·allowlist 검증 버그가 있더라도 “공격자가 임의 URL을 전달하는” 입력면이 사라집니다.
• 남는 위험은 정적 메타 오염뿐이고, 이는 코드 리뷰/테스트/타입으로 관리 가능한 supply-side 위험입니다.

반대로 “URL 전달 + main 재검증”은 검증이 완벽하면 안전하지만, renderer가 URL을 정하는 구조 자체가 남습니다. Fleet의 threat model이 renderer를 낮은 신뢰 경계로 보는 구조라면, 식별자 전달이 더 적합합니다. preload는 현재 renderer가 window.fleet로만 IPC를 호출하도록 고정된 얇은 브리지 역할을 합니다.

구현 시 권장 타입: adapterId는 가능하면 CliAdapterId = keyof typeof CLI_AUTH_INSTALL_META 같은 좁은 타입으로 공유하고, main에서는 런타임에서도 Object.hasOwn(CLI_AUTH_INSTALL_META, adapterId) 식으로 재확인하세요. 현재 CliAdapter.id 자체는 확장성을 위해 string입니다.

---

2. shell.openExternal 도입이 window-guards 전면차단 모델을 약화시키지 않는가?

D3 주장은 타당합니다. 단, “renderer navigation 예외”가 아니라 “main-mediated OS browser handoff 예외”라고 문서화하면 더 정확합니다.

현재 window guard는 Fleet 앱 창 내부에서 발생하는 window.open, 외부 링크 클릭, redirect, frame navigation, location 변경을 모두 차단하도록 되어 있습니다. 실제 구현도 새 창을 deny하고 will-navigate/will-redirect/will-frame-navigate를 모두 preventDefault합니다.

main에서 shell.openExternal을 호출하는 것은 이 guard를 “느슨하게” 만드는 것이 아니라, Fleet renderer가 외부로 이동하지 못한다는 모델은 유지한 채, main이 검증된 정적 링크만 OS 기본 브라우저에 위임하는 별도 경로를 추가하는 것입니다. installNavigationGuards(win.webContents)도 창 생성 시 그대로 설치되고 있습니다.

구현 리뷰 포인트는 다음입니다.

• renderer에서 <a href> / window.open / location.href를 쓰지 말 것.
• preload에 openCliDocs(adapterId)만 추가하고 URL 문자열 API는 만들지 말 것.
• main handler에서 URL을 다시 도출하고 검증한 뒤 shell.openExternal만 호출할 것.
• 실패 시 renderer에 raw URL이나 OS error를 과도하게 노출하지 않는 편이 좋습니다.

---

3. https + hostname 정확매칭 외 추가 벡터: redirect / IDN / punycode 등

현재 제안한 방어는 대체로 충분합니다. 다만 아래 세부를 테스트에 포함하면 더 단단합니다.

Redirect chain

스펙은 “redirect 최종 URL까지 검증하거나 정적 상수만 허용”이라고 되어 있습니다.

이번 설계는 정적 상수만 허용 쪽이므로, Fleet이 직접 HTTP request를 따라가며 최종 URL을 검증할 필요는 없습니다. shell.openExternal은 브라우저에 URL을 넘길 뿐이고, 브라우저가 이후 redirect를 따라가는 것은 Fleet 앱 내부 네비게이션이 아닙니다.

다만 보안 기대치를 명확히 하려면 주석/테스트명에 이렇게 적는 것을 권장합니다.

Fleet guarantees only that the initially opened URL is a compile-time docs URL on the allowlist; it does not police browser-side redirects after handoff.

즉, “브라우저 redirect 이후 목적지까지 Fleet이 보증한다”가 아니라 “Fleet이 넘기는 최초 URL이 정적 allowlist URL임을 보증한다”입니다.

IDN / punycode

new URL(url).hostname은 IDN을 punycode ASCII 형태로 정규화합니다. 현재 allowlist가 ASCII host만 포함하므로, homograph IDN은 정확 매칭에 실패합니다. 그래도 테스트에 아래 케이스를 넣으면 좋습니다.

• https://docs.anthropic.com.evil.com/... 거부
• https://docs.anthropic.com@evil.com/... 거부
• https://xn--.../ 형태의 non-allowlist punycode 거부
• 대문자 host: https://DOCS.ANTHROPIC.COM/...은 URL hostname이 lowercase 정규화되므로 허용되는지 명확히 결정
  • 개인적으로는 new URL().hostname 기준 allowlist exact match면 허용해도 괜찮습니다.

Port / path / username-password

현재 계약은 host allowlist 중심이므로 포트와 경로를 전면 금지할 필요는 없어 보입니다. 하지만 userinfo는 hostname 검증으로 막히는 케이스와 별개로, allowlisted host에 userinfo가 붙은 URL은 브라우저 UI 혼동을 만들 수 있습니다.

예: https://user:pass@docs.anthropic.com/path

이 URL은 hostname이 docs.anthropic.com이라 통과할 수 있습니다. 정적 상수에는 이런 값이 없겠지만, 심층방어로 parsed.username === '' && parsed.password === ''도 요구하면 좋습니다.

포트는 일반 docs URL에 필요 없으므로 더 엄격히 하려면 parsed.port === ''도 추가할 수 있습니다. 다만 https://host:443을 거부할지 허용할지는 정책 선택입니다. 정적 상수 기반이면 큰 차이는 없습니다.

권장 검증 함수

최소 권장:

const parsed = new URL(url)
return (
  parsed.protocol === 'https:' &&
  parsed.username === '' &&
  parsed.password === '' &&
  DOCS_HOST_ALLOWLIST.includes(parsed.hostname)
)

더 엄격한 권장:

parsed.port === ''

까지 추가할 수 있습니다.

---

4. ADR 불요 판단이 맞나?

완전한 ADR까지는 과할 수 있지만, “전면차단 모델의 첫 의도적 예외”라면 짧은 ADR을 권장합니다.

이유는 구현 자체가 큰 설계 변경은 아니지만, Fleet의 기존 보안 설명은 “외부 창/외부 이동 정상 경로 없음”에 가깝습니다. window guard 주석도 단일 창 SPA라 외부 창과 다른 문서 네비게이션 정상 경로가 없다고 설명합니다.

이번 작업은 그 모델을 약화하는 것은 아니지만, 사용자 의도 기반 외부 브라우저 위임이라는 예외 경로를 새로 만드는 것입니다. 그러므로 나중에 “왜 window guard는 전면차단인데 docs는 열린가?”라는 리뷰/보안 감사 질문이 나올 가능성이 큽니다.

권장 형태:

• 긴 ADR 불필요
• docs/adr/에 짧은 ADR 1개:
  • 결정: docs 외부열기는 renderer navigation이 아니라 main-mediated static URL handoff로만 허용
  • 대안: copy-only 유지, URL 전달 IPC
  • 보안 불변식:
    • renderer는 URL을 보내지 않는다
    • command/install hint는 계속 copy-only
    • window.open/navigation guard는 그대로 유지
    • 정적 docs URL + https + exact hostname allowlist
  • 한계: browser-side redirect after handoff는 Fleet 보증 범위 밖

즉, “정책 ADR”로 남길 가치는 있습니다. 다만 이미 스펙 §6a가 권위 있게 존재하므로, ADR은 스펙을 반복하지 말고 “전면차단 모델의 예외가 아니라 main handoff라는 별도 통제 경로”라는 결정만 짧게 기록하면 충분합니다.

---

구현 전 추가 권장사항

• src/main/external-links.ts는 main/core가 아니라 main 바로 아래에 두는 제안이 좋습니다. shell.openExternal은 Electron main 기능이므로 core 순수 TS 계약과 분리되어야 합니다. AGENTS 지침상 src/main/core/*에는 Electron import가 들어가면 안 됩니다.
• isAllowedDocsUrl는 순수 함수로 두고, openVerifiedCliDocs에는 openExternal dependency injection을 넣는 설계가 테스트하기 좋습니다.
• FleetBridge 타입과 preload 구현을 반드시 같이 갱신하세요. shared의 FleetBridge가 단일 진실 원천 역할을 합니다.
• UI는 현재 docs URL을 <code>로 표시하고 copy-only 버튼을 제공합니다. 여기에 “문서 열기” 버튼을 추가하되 URL 텍스트 노출은 유지하면 스펙의 “링크 텍스트와 실제 URL 함께 표시” 조건을 만족합니다.
• 명령어는 계속 copy-only로 유지해야 합니다. 현재 install hint와 login command는 각각 clipboard 복사만 수행합니다.

---

결론

승인 의견입니다.
D1 식별자-전달 IPC, D2 docsUrl-only, D3 window guard 불변 모두 타당합니다. 구현 시에는 userinfo/optional port 테스트를 추가하고, browser-side redirect는 Fleet 보증 범위가 아님을 명확히 하세요. ADR은 필수는 아니지만, 이 경로가 “외부 네비게이션 허용”이 아니라 “main이 검증된 정적 URL을 OS 브라우저에 위임”하는 예외라는 점을 짧게 남기는 것을 권장합니다.

검토에 사용한 명령

• ✅ pwd && rg --files -g 'AGENTS.md' -g 'brain.md' -g 'docs/superpowers/specs/2026-06-25-session-auth-picker-design.md' -g 'src/shared/cliAuthInstallMeta.ts' -g 'src/main/window-guards.ts' -g 'src/renderer/components/AddAiWizard.tsx' -g 'src/shared/types.ts' -g 'src/preload/index.ts' -g 'src/main/index.ts'
• ✅ sed -n '1,220p' brain.md && nl -ba src/shared/cliAuthInstallMeta.ts | sed -n '1,220p' && nl -ba src/main/window-guards.ts | sed -n '1,240p' && rg -n "§6a|외부|DOCS|docsUrl|copy-only|hostname|allowlist|redirect" docs/superpowers/specs/2026-06-25-session-auth-picker-design.md
• ✅ nl -ba docs/superpowers/specs/2026-06-25-session-auth-picker-design.md | sed -n '87,100p' && rg -n "docsUrl|loginCommand|installHint|CLI_AUTH_INSTALL_META" src/renderer/components/AddAiWizard.tsx && nl -ba src/renderer/components/AddAiWizard.tsx | sed -n '1,220p' && nl -ba src/shared/types.ts | sed -n '1,140p' && nl -ba src/preload/index.ts | sed -n '1,130p' && rg -n "ipcMain.handle|installNavigationGuards|shell|external" src/main/index.ts
• ✅ git status --short

View task →

[pdw96]

설계 리뷰 반영 완료 → spec 확정

Codex 독립 리뷰(승인 의견) 4보강 전량 반영, spec 커밋 2ad3f71 → docs/superpowers/specs/2026-06-26-picker-docs-external-open-design.md (브랜치 feat/145-picker-docs-external-open).

• Q1 식별자-전달 IPC — "더 안전" 확인, 유지 + CliAdapterId = keyof typeof CLI_AUTH_INSTALL_META 좁힘 + main Object.hasOwn(CLI_AUTH_INSTALL_META, adapterId) 런타임 재확인(D4 심층방어).
• Q2 window-guards — "renderer navigation 예외"가 아니라 **"main-mediated OS browser handoff 예외"**로 문구 정밀화(D3·§7). installNavigationGuards 불변.
• Q3 적대 벡터 — 검증함수에 username/password === ''·port === '' 심층방어 추가. userinfo(user:pass@allowlisted)·서브도메인(a.com.evil.com)·punycode·대문자 host 전수 테스트. redirect 보증범위 명시: Fleet은 핸드오프하는 최초 URL이 컴파일타임 정적 allowlist docs URL임만 보증, browser-side redirect는 범위 밖(정적 상수 선택이라 redirect 추적 불요).
• Q4 ADR — 사전판단(불요)에서 선회 → 짧은 정책 ADR docs/adr/0005-picker-docs-외부열기.md(D5·§8). 스펙 반복 없이 "전면차단 모델의 예외가 아니라 별도 통제 경로"라는 결정·보안 불변식·한계만 기록.

다음

writing-plans → TDD(RED→GREEN) → 품질게이트 4종 → 적대리뷰 → PR. PR 본문 = Part of #145(항목4만 완료, 나머지 1·2·3·5 잔존 — 5항목 묶음이라 Closes 금지).

[pdw96]

항목4 (클릭형 외부링크 열기) ✅ 완료

PR #147 머지 (squash 5e915b6, 2026-06-26). picker 구독 단계 docsUrl을 가드된 IPC fleet:external:openDocs로 OS 브라우저 외부열기.

구현

• 식별자만 전달(renderer는 adapterId만 → main이 정적 맵서 docsUrl 도출): 주입면 0.
• 가드 isAllowedDocsUrl: https + userinfo/port 금지 + exact hostname allowlist. Object.hasOwn adapterId 스푸핑 차단. 심층방어 이중 검증.
• window-guards 불변: shell.openExternal은 main→OS 브라우저 핸드오프(renderer 네비 아님). 전면차단 모델 약화 0.
• 범위: docsUrl만. loginCommand/installHint는 copy-only 유지.
• src/main/external-links.ts(순수 검증+DI) · CliAdapterId 단일출처(src/shared/types.ts) · ADR 0005.

검증

• 품질게이트 4종 + CI 7종(CodeQL·windows vitest 포함) green.
• Codex 설계 체크포인트 리뷰 승인 + 4보강 반영(issuecomment-4807449557).
• 자체 4렌즈 적대리뷰(18 에이전트): 확정 1건 반영, 기각 5건.
• CodeRabbit 4건 반영(CliAdapterId→types.ts 단일출처·test Object.values 도출·rejection err 처리·트레일러 위생)·스레드 resolve·"Review completed".
• Codex PR 명시리뷰는 한도소진 추정 미도착 → 위 3중 검증으로 대체.

잔여 (tier:later 유지) — 이슈 open: 항목 1(첫 사용 auth 실패 라우팅)·2(CLI 번들/자동설치)·3(연결 테스트 probe)·5(CLI resolved-path 표시). 5항목 묶음이라 PR은 Part of #145(Closes 미사용).