feat(v3): Fleet 터널 셀프호스트 — 컨테이너 하나 + 터널로 어디서든 브라우저 (메타)

[pdw96]

목표

데스크톱 Fleet 을 "어디서든 브라우저로 쓰는" 형태로 만든다 — 단, 클라우드 인프라를 사지 않는다. 내 PC 의 Docker 컨테이너 하나에 Fleet 서버·CLI·웹터미널을 담고 Cloudflare Tunnel(+Access) / Tailscale 로 노출한다.

배경

SaaS 전환 검토가 v1(풀 클라우드 K8s+microVM) → v2(Vercel+Supabase 하이브리드) → v3(터널 셀프호스트) 로 수렴. 근거: ① 1차 목표가 "개인이 어디서든" 이므로 멀티테넌트 격리·과금이 불필요, ② 실행이 본인 머신이라 구독 CLI ToS 제약(구독 OAuth 제3자 사용 금지, Anthropic 2026-04·Google 2026-03)이 데스크톱과 같은 위치로 내려옴, ③ 코어 엔진이 Electron 비의존 순수 TS + 포트/어댑터라 공사가 전송층 하나로 좁혀짐.

설계 요약 (계획서 v3)

• 두 개의 문: ① 웹터미널(ttyd+tmux) — TUI 직접 대화, 구독제 정석 사용, 헤드리스 불요 · ② Fleet 오케스트레이션 — 헤드리스(stream-json) 유지(기계 운전에는 기계용 출력 계약이 필수, TUI 스크레이핑은 버전 취약이라 기각)
• 유일한 실질 공사 = 전송층 교체: Electron IPC → WebSocket. ipcMain.handle→WS 요청-응답, webContents.send→WS broadcast, window.fleet 브리지 구현체 교체(renderer 무변경, src/shared/types.ts 가 계약). 어댑터 2개: SecretCrypto(safeStorage→파일 암호화)·워크스페이스 선택(다이얼로그→경로 입력)
• ApprovalGate: 로직 무변경 — WS 이벤트→승인 카드(폰 승인), 연결 클라이언트 부재 시 타임아웃=거부(fail-closed)
• CLI 이미지: 버전 태그 고정(자동 업데이트 차단), 로그인 볼륨 영속, 신 버전은 stream-json 파싱 스모크 GREEN 후 교체
• ToS 포지셔닝: 구독제 헤드리스 = "쓸 수 있는 동안 쓰는 할인". 기준은 API 키 — LlmSession 추상화 덕에 env 하나로 전환(코드 무변경)
• 확장 경로: "PC 꺼짐" 이 아프면 v2(Supabase 계층 추가), 상용화 시 v1. 전송층 추상화·CLI 이미지는 세 버전 공통 기반 — 단 v3 WS 프로토콜 자체는 단일 사용자 전제라 승격 시 인증·테넌트 계층을 위에 추가(설계 리뷰 정정)

계획서: docs/fleet-saas-infra-plan-v3.html (본 설계) · -v2.html(Supabase 하이브리드) · .html(v1 풀 클라우드) — 등재 PR 에서 커밋.

Phase 체크리스트 (체크포인트 1 리뷰 반영판)

• Phase A — 웹터미널 먼저 ✅ 완료(feat(#193-A): Phase A — 웹터미널 compose 스택 (CLI+ttyd+tmux+터널 · Fleet 코드 변경 0) #195 · PR feat(#195): Phase A 웹터미널 compose 스택 (ttyd+tmux+터널 · Fleet 코드 변경 0) #196 5034801, 2026-07-02): CLI+ttyd+tmux 이미지 · compose · 실 Cloudflare 터널+Access 프로덕션 라이브(5/5). 완료 정의 전량 충족: 폰 브라우저 claude 대화 + tmux 세션 생존 + CLI 로그인 볼륨 동시 세션 간섭 실측 기록 + 마운트 범위 문서화 + ttyd 선택 근거
• Phase B — 전송층 교체 ✅ 완료(feat(#193-B): Phase B — IPC→WS 전송층 교체 (server 엔트리·WS 브리지·보안층·자식 격리 · PR 6개) #197 · B1B6 6-PR, 2026-07-0306): B1 run 이벤트 커서(PR feat(#197-B1): run 이벤트 커서 — FleetEvent.seq 단조 스탬프 + eventCursor 갭 감지 (코어 계약) #198) · B2 WS 프로토콜+브리지(PR feat(#197-B2): WS 프로토콜 + 채널 매니페스트 + 클라이언트 브리지 #199) · B3 서버 엔트리+32핸들러+어댑터(PR feat(#197-B3): 서버 엔트리 + 핸들러 테이블 + 어댑터 + loopback bind + 정적 서빙 #200) · B4 renderer 웹모드 배선(PR feat(#197-B4): renderer 웹모드 배선 + Electron 표면 게이팅 + 웹 스모크 #202) · B5 보안층 JWT/JWKS/nonce(PR feat(#197-B5): 보안층 — Origin·Access JWT·WS nonce·CSP·authenticated presence #211) · B6 env allowlist+컨테이너(PR feat(#197-B6): 자식 env 격리 + 소켓 exp 종료 + fleet 컨테이너 배포 (Phase B 최종) #213). 계약 테스트 5종 포함 전량 GREEN + 라이브 터널 실배포(Access 실로그인→UI·WS·세션)
• Phase C — 승인 + 안정화 ✅ 완료(feat(#193-C): Phase C — 승인 + 안정화 (원격 승인 보류·모바일 승인 UX·graceful drain·운영 실측) #216 CLOSED, 2026-07-09): C1 hold-with-expiry(PR feat(#216-C1): 승인 보류(hold-with-expiry)·스냅숏 편입·재하이드레이션 #219) · C2 승인 카드 모바일 UX(PR feat(#216-C2): 승인 카드 모바일 UX·다중 pending·재접속 UX #220) · C3 graceful drain(PR feat(#216-C3): graceful drain — 신규 런 거부·통지·진행 런 대기·안전 종료 #224) · C5 운영 런북(PR feat(#216-C5): 운영 런북 + 로컬 라이브 하니스 (Part of #216) #225·docs(#216-C5): 백업 볼륨 특정 compose 라벨 정확화 (Codex P2 후속) #227). 완료 정의 실증: 실 터널+Access에서 폰 승인→런 완주 + docker stop 실드레인. C4 Web Push = feat(#193-C4): Web Push 원격 승인 알림 (VAPID + service worker) — 실사용 통증 확인 후 #226 분리(tier:later)
• Phase D — 확장 판단: v2/v1 승격 조건 검토 (착수 아님) — 트리거: "PC 꺼짐" 통증 실측 시 v2 검토

착수 전 실측 항목

• 문 ①·② 가 같은 CLI 로그인 볼륨 공유 시 세션 간섭 여부 — Phase A 완료 정의에 포함, 실측 기록(feat(#193-A): Phase A — 웹터미널 compose 스택 (CLI+ttyd+tmux+터널 · Fleet 코드 변경 0) #195)
• ttyd vs code-server — Phase A 에서 ttyd 1.7.7 채택(선택 근거 문서화, feat(#193-A): Phase A — 웹터미널 compose 스택 (CLI+ttyd+tmux+터널 · Fleet 코드 변경 0) #195)
• Cloudflare Tunnel+Access vs Tailscale — Cloudflare 채택, 프로덕션 실배포 라이브(feat(#193-A): Phase A — 웹터미널 compose 스택 (CLI+ttyd+tmux+터널 · Fleet 코드 변경 0) #195·feat(#193-C): Phase C — 승인 + 안정화 (원격 승인 보류·모바일 승인 UX·graceful drain·운영 실측) #216 §2b)
• Electron 앱 병행 시 store 볼륨 분리 — 컨테이너 fleet-data 볼륨 분리(0700, B6 PR feat(#197-B6): 자식 env 격리 + 소켓 exp 종료 + fleet 컨테이너 배포 (Phase B 최종) #213)로 해소

운영 규칙

• Phase 별 sub-issue 는 착수 시점에 생성 (#123-B 워크스페이스 무결성: 프로세스 격리 + adversarial-FS 하드닝 (A 후속) #128 선례)
• PR 은 Part of #이슈 사용 — Closes 금지 (메타: 워크플로 GitHub 동기화 (Claude 운영 프로세스 레포 정착 + 타겟 클라우드 Action) #135 교훈: 멀티 Phase 메타 조기 종료 방지)
• 체크포인트(설계→스펙→계획)는 이슈 코멘트 + @codex review (오케스트레이션 워크스페이스 무결성: ignored 파일 변경 감지·승인·롤백 #123-A 선례)

[pdw96]

🔍 체크포인트 1 — 설계 (코딩 전)

@codex review — 착수 전 아래 설계를 독립 검증해줘. 상세 근거는 PR #194 의 docs/fleet-saas-infra-plan-v3.html (v1·v2 문서 병행 등재).

검증 요청 포인트

1. 아키텍처 선택의 타당성 — "개인이 어디서든 브라우저로" 목표에 대해 v3(컨테이너+터널 셀프호스트)가 v2(Supabase 하이브리드) 대비 옳은 첫 단계인가. 특히 "IPC→WS 전송층은 v1·v2·v3 공통 선행 작업이라 버려지지 않는다" 는 주장의 반례가 있는가.
2. 전송층 교체 설계 — window.fleet 브리지 구현체 교체(renderer 무변경) 전제가 성립하는가: preload 브리지가 IPC 외 의존을 갖는 지점, 스트리밍 streamId(start|delta|end|error) 체계의 WS 이사에서 깨질 시맨틱(순서 보장·배압), 재접속 스냅숏 복구의 구멍.
3. ApprovalGate 웹 이사 — "연결 클라이언트 부재 시 타임아웃=거부(fail-closed)" 가 기존 게이트 계약과 충돌하는 경로가 있는가 (예: 데스크톱에서는 모달이 무기한 대기).
4. 보안 경계 — Cloudflare Access/Tailscale 앞단 인증 + 컨테이너 경계 + 기존 ApprovalGate 조합에서 빠진 위협 (특히 웹터미널=원격 셸 노출, CLI 로그인 볼륨).
5. ToS 판정 — "구독 CLI 를 본인 머신 컨테이너에서 사용 = 데스크톱과 동일 위치, 단 원격 트리거 자동화는 회색 → 기본값 API 키" 판정의 오류 여부.
6. Phase 분해 — A(웹터미널, 코드 변경 0) → B(전송층) → C(승인·안정화) 순서와 각 완료 정의(특히 B 의 "코어 vitest 전량 GREEN 유지")가 적절한가.

알려진 미해결 (이슈 본문 «착수 전 실측 항목» 참조)

CLI 로그인 볼륨 세션 간섭 · ttyd vs code-server · Cloudflare vs Tailscale · store 볼륨 분리(데스크톱 병행).

[chatgpt-codex-connector]

설계 리뷰 결론

조건부 승인입니다. v3(컨테이너 + 터널 셀프호스트)는 “개인이 어디서든 브라우저로”라는 1차 목표에는 v2(Supabase 하이브리드)보다 더 작은 첫 단계로 타당합니다. 다만 Phase B 완료 정의가 현재 너무 약합니다. “코어 vitest 전량 GREEN”만으로는 이번 설계의 핵심 리스크인 WS 전송층의 이벤트 순서·재접속·승인 라우팅·원격 셸 노출을 충분히 검증하지 못합니다.

제가 보는 주요 결론은 아래입니다.

• v3 우선순위 자체는 합리적: 현재 구조가 renderer → window.fleet → preload → main → core 로 분리되어 있고, core는 Electron 밖 포트 주입 구조로 조립되므로 “Electron IPC를 WS로 대체”하는 방향은 맞습니다. brain.md도 preload를 화면과 본체 사이의 단일 통로로 설명하고, main이 43개 IPC 채널을 engine에 연결한다고 요약합니다.
• “renderer 무변경”은 큰 방향에서는 가능하지만, 완전 무변경이라고 단정하면 위험: FleetBridge 표면은 preload 한 곳에 모여 있어 교체 지점은 명확합니다. 하지만 현재 preload 구현은 ipcRenderer.invoke와 Electron push 이벤트에 직접 묶여 있고, renderer의 스트리밍/스냅샷 코드는 IPC의 사실상 ordered local event bus 특성에 기대고 있습니다.
• ApprovalGate의 fail-closed 자체는 기존 계약과 충돌하지 않음: 이미 창이 없으면 즉시 거부, 무응답이면 타임아웃 거부입니다. 따라서 “연결 클라이언트 부재 시 타임아웃=거부”는 신규 정책이라기보다 기존 안전 기본값의 웹 이식입니다.
• 가장 큰 빠진 위협은 웹터미널/CLI 로그인 볼륨/워크스페이스 볼륨이 만드는 ‘원격 셸 + 장기 토큰 + 로컬 파일’ 결합입니다. ApprovalGate는 Fleet 오케스트레이션 경로의 위험 작업 집행 장치이지, ttyd/code-server 같은 웹터미널에서 사용자가 직접 셸을 실행하는 경로를 막아주지 않습니다. 현재 gate도 “무엇이 destructive인지 판정하지 않고 호출자가 신고한 risk를 집행”하는 구조입니다.
• Phase B의 완료 정의는 보강 필요: “코어 vitest 전량 GREEN”은 core 순수성 보존에는 좋지만, 이번 변경의 핵심은 main/preload/renderer 전송층입니다. 최소한 WS bridge contract test, 스트림 재정렬/중복/재접속 테스트, approval fail-closed 테스트, browser smoke가 Phase B/C 게이트에 추가되어야 합니다.

---

체크포인트별 검증

1. 아키텍처 선택 — v3가 v2보다 첫 단계로 맞는가?

판정: 대체로 맞습니다.

v3의 장점은 현재 Fleet의 구조와 잘 맞습니다.

• 현재 앱은 renderer가 직접 engine을 호출하지 않고 window.fleet 브리지를 통해서만 main과 통신합니다. brain.md는 이 계층을 “화면과 내부 엔진 사이에서 메시지를 안전하게 주고받는 단 하나의 통로”라고 설명합니다.
• main은 engine을 조립하고, renderer 요청을 engine 메서드에 연결하는 얇은 교환대입니다. 실제 engine 생성도 createFleetEngine에 store, stream callback, approver, runner, secretCrypto 같은 포트를 주입하는 방식입니다.
• core의 createFleetEngine은 store/session/registry/http/runner/secretCrypto 등 포트를 주입받아 생성되며, Electron 객체에 직접 의존하지 않는 구조입니다.

따라서 “먼저 전송층을 IPC → WS로 분리하고, 이후 v2/v1로 확장 가능”이라는 주장은 설계 방향상 맞습니다.

다만 “IPC→WS 전송층은 v1·v2·v3 공통 선행 작업이라 버려지지 않는다”는 주장은 80%만 맞습니다. 반례는 있습니다.

• v3는 단일 사용자/단일 서버/로컬 trust boundary에 가까워도 됩니다.
• v2/v1은 멀티 사용자 인증, tenant 분리, server-side session ownership, per-user workspace isolation이 필요합니다.
• 따라서 request/response envelope, event subscription, stream replay 같은 전송층 추상화는 재사용되지만, 인증·권한·tenant 라우팅 없는 v3 WS 프로토콜을 그대로 v2/v1에 올릴 수는 없습니다.

즉 “전송층 분리 작업은 버려지지 않는다”는 맞지만, “v3 WS 프로토콜이 그대로 v2/v1 공통 기반이다”라고 쓰면 과장입니다.

---

2. 전송층 교체 — window.fleet 구현체 교체만으로 renderer 무변경 가능한가?

판정: 표면 API는 가능하지만, 스트리밍/재접속 시맨틱은 명시적 보강이 필요합니다.

현재 preload는 FleetBridge 구현체를 한 곳에서 만들고 contextBridge.exposeInMainWorld('fleet', api)로 노출합니다. 따라서 renderer 입장에서는 window.fleet만 유지되면 호출 표면은 유지할 수 있습니다.

하지만 다음 지점들이 “renderer 무변경” 전제의 실제 리스크입니다.

2-1. Electron IPC 의존 지점

preload 구현은 전부 ipcRenderer.invoke(...)와 ipcRenderer.on(...)입니다.

따라서 WS bridge는 단순히 transport만 바꾸는 것이 아니라 아래 동작을 동일하게 흉내 내야 합니다.

• invoke와 같은 request/response correlation
• promise reject/error mapping
• listener 등록/해제의 idempotency
• event broadcast 구독
• app lifecycle 중 연결 끊김/재연결 처리

이걸 preload에만 숨기면 renderer 변경은 줄일 수 있지만, WS bridge 자체의 contract test가 필수입니다.

2-2. 스트리밍 이벤트 순서·중복·역순

현재 ChatStreamEvent 계약은 streamId별 seq가 1부터 증가하고, renderer가 seq로 멱등 적용 및 하이드레이션 레이스 정렬을 보장한다고 명시합니다.

renderer도 실제로 e.seq <= cur.seq이면 중복/역순 이벤트를 무시합니다.

따라서 WS 이사에서 반드시 지켜야 할 것은 다음입니다.

• 서버는 streamId 단위 단조 증가 seq를 계속 발급해야 함.
• 클라이언트는 재접속 후 스냅샷을 받은 뒤 seq보다 큰 이벤트만 replay/apply해야 함.
• WS 재연결 중 live event와 snapshot이 교차해도 “라이브 우선” 규칙이 유지되어야 함.

현 renderer는 마운트 시 onChatStream 구독을 먼저 걸고 getChatActivity() 스냅샷을 조회해 델타 유실을 줄이는 구조입니다.
이 패턴은 WS에서도 유효하지만, 브라우저 네트워크 단절/재접속에서는 “마운트 하이드레이션”보다 훨씬 긴 gap이 생깁니다. 따라서 현재 스냅샷 복구 로직만으로는 부족하고, WS bridge가 reconnect 시점마다 getChatActivity()와 getRunActivity()를 재조회하거나, 서버가 replay cursor를 제공해야 합니다.

2-3. ProjectPanel도 이벤트 복구가 필요

ProjectPanel도 라이브 이벤트와 저장소 스냅샷이 섞일 때 race guard를 두고 있습니다. 예를 들어 project.done/plan.failed를 기록해 stale snapshot이 끝난 실행을 되살리지 않게 합니다.

WS 전환 후에는 탭 전환이 아니라 네트워크 단절이 발생하므로, Phase B/C에서 다음이 완료 정의에 들어가야 합니다.

• 연결 끊김 중 project 이벤트 발생
• 재접속 후 getRunActivity() + listProjectEvents() + getProjectTasks()로 UI 복구
• stale snapshot이 완료된 run을 다시 running으로 만들지 않음

---

3. ApprovalGate 웹 이사 — “클라이언트 부재 시 타임아웃=거부”가 기존 계약과 충돌하는가?

판정: 충돌하지 않습니다. 오히려 기존 구현과 일치합니다.

현재 승인 경로는 이미 fail-closed입니다.

• createApprovalGate는 autoApprove에 없는 risk에 대해 approver가 없으면 rejected를 반환합니다.
• main에서 만든 createIpcApprover는 창이 없으면 즉시 false를 반환합니다.
• 응답이 없으면 APPROVAL_TIMEOUT_MS 후 pending을 삭제하고 false로 resolve합니다.
• timeout 값은 shared 타입에 60초로 정의되어 있고 renderer 카운트다운과 main 권위가 공유합니다.

따라서 “데스크톱에서는 모달이 무기한 대기”라는 반례는 현재 코드 기준으로는 성립하지 않습니다. 현재 데스크톱도 무응답 자동 거부입니다.

다만 웹 이사에서 주의할 점은 있습니다.

• Electron의 hasWindow()는 “승인 UI를 받을 BrowserWindow가 있다”는 뜻입니다.
• 웹에서는 “WS 클라이언트가 연결되어 있다”와 “해당 사용자가 실제로 승인 UI를 보고 있다”가 다릅니다.
• 따라서 웹 approver는 단순 연결 수가 아니라 승인 가능한 authenticated client presence를 기준으로 해야 합니다.
• 여러 브라우저/폰이 붙은 경우, 승인 요청 broadcast와 최초 응답 채택/중복 응답 무시/idempotency도 현재 resolve(id)와 동등하게 유지해야 합니다. 현재 구현은 미존재/이미 해소 id를 무시하는 idempotent resolve입니다.

---

4. 보안 경계 — 빠진 위협

판정: 가장 큰 구멍은 웹터미널입니다.

Cloudflare Access/Tailscale + 컨테이너 + ApprovalGate 조합은 “Fleet UI를 통한 오케스트레이션”에는 의미가 있습니다. 하지만 Phase A의 웹터미널은 Fleet의 ApprovalGate 바깥입니다.

현재 ApprovalGate는 core 내부 위험 작업 경로에 주입됩니다. engine은 caution까지 자동 승인하고 destructive는 approver에 위임합니다.
하지만 웹터미널 사용자가 rm -rf, cat ~/.config/..., CLI token 조회, git push 등을 직접 실행하면 이 경로는 ApprovalGate를 통과하지 않습니다.

따라서 v3 문서에는 아래 위협을 명시하는 것이 좋습니다.

1. 웹터미널 = 원격 셸 노출

   • Access/Tailscale 계정 탈취 시 컨테이너 안 셸이 열립니다.
   • 컨테이너에 bind mount한 workspace와 CLI login volume 범위가 피해 반경입니다.
   • 기본 mount는 최소화하고, workspace/token/cache/store 볼륨을 분리해야 합니다.

2. CLI 로그인 볼륨

   • Claude/Codex/Gemini 토큰은 장기 자격증명에 가깝습니다.
   • ttyd/code-server/Fleet server가 같은 UID로 같은 volume을 공유하면 한 경로의 compromise가 모든 CLI 세션을 탈취할 수 있습니다.
   • Phase A의 “로그인 볼륨 세션 간섭” 실측뿐 아니라 권한/소유자/volume 분리도 완료 정의에 넣어야 합니다.

3. 브라우저 공격면

   • Electron에서는 navigation/permission guard가 강합니다. main은 window.open/navigation을 막고 permission도 거부합니다.
   • 브라우저 배포에서는 Electron의 installNavigationGuards/installPermissionGuards가 사라집니다.
   • 따라서 CSP, same-origin 정책, CSRF/Origin 검사, WS origin allowlist, cookie/session hardening이 새 보안 경계가 됩니다.

4. WS CSRF / Cross-Site WebSocket Hijacking

   • Cloudflare Access가 앞에 있어도, server는 Origin 검증과 Access identity header 검증을 자체적으로 해야 합니다.
   • “터널 앞단 인증이 있으니 app server는 trust”라고 두면 로컬 네트워크/잘못된 터널/프록시 설정에서 위험합니다.

5. store 동시 쓰기

   • PR 본문에 “Electron 앱 병행 시 store 볼륨 분리”가 들어간 것은 맞습니다.
   • 현재 main은 app userData 아래 fleet JSON store를 씁니다.
   • Electron과 server가 같은 JSON store를 동시에 쓰면 corruption/lost update 위험이 있으므로, v3 server는 별도 store path를 기본값으로 해야 합니다.

---

5. ToS 판정

판정: 방향은 보수적으로 맞지만, 문구를 더 엄격하게 써야 합니다.

현재 코드/문서상 Fleet의 안전한 구독 경로는 “Fleet 자체 OAuth가 아니라 공식 CLI 인증에 위임”입니다. 기존 설계 문서도 Fleet이 자격증명을 만지지 않는 모델을 ToS-safe 구독 경로로 보고 있습니다.

다만 v3의 “본인 머신 컨테이너에서 사용 = 데스크톱과 동일 위치”라는 표현은 운영 위치 관점에서는 설득력 있지만, 자동화/원격 트리거 관점에서는 여전히 회색입니다.

추천 문구는 다음에 가깝습니다.

• 기본 안전 기준은 API key provider.
• 구독 CLI는 “공식 CLI가 허용하는 범위에서 사용자가 직접 인증한 로컬 도구를 Fleet이 호출”하는 선택지.
• 원격 브라우저에서 headless orchestration을 트리거하는 행위는 provider별 정책 변화에 민감하므로, 문서에는 “지원되는 동안 할인 경로, 차단/약관 변경 시 API key로 즉시 전환”이라고 명시.
• 특히 Gemini는 기존 문서에서도 위험 배너 대상으로 분류되어 있습니다.

---

6. Phase 분해와 완료 정의

판정: A → B → C 순서는 좋지만, B/C 완료 정의를 강화해야 합니다.

Phase A — 웹터미널 먼저

좋습니다. 코드 변경 0으로 가장 큰 unknown을 빨리 줄입니다.

다만 완료 정의에 아래를 추가하는 것이 좋습니다.

• 로그인 volume을 CLI별로 공유/분리했을 때 동시 세션 간섭 여부 기록
• workspace mount read/write 범위 명시
• ttyd/code-server 중 하나를 고르는 기준: 모바일 사용성, clipboard, auth boundary, process isolation
• 컨테이너에서 host Docker socket mount 금지
• 기본 이미지에서 자동 CLI 업데이트 차단/버전 pin

Phase B — 전송층 교체

현재 “코어 vitest 전량 GREEN 유지 + 브라우저에서 목표 입력→오케스트레이션 런 완주”는 부족합니다.

추가 완료 정의를 권합니다.

• FleetBridge parity test: IPC bridge와 WS bridge가 shared FleetBridge 표면을 모두 구현하는지 검사
• request/response correlation test: concurrent invoke, reject propagation, timeout
• chat stream test: start 없이 delta 도착, 중복 seq, 역순 seq, end 후 stale snapshot
• project event test: 재접속 중 project.done 발생 후 stale snapshot이 running을 되살리지 않음
• approval test: no client → reject, connected but no response → timeout reject, duplicate response ignored
• WS origin/auth test: unknown Origin 또는 missing Access identity 거부

Phase C — 승인 + 안정화

Phase C의 “재접속 스냅숏 복구”는 맞습니다. 다만 일부는 Phase B의 필수 인프라로 앞당겨야 합니다. 특히 window.fleet가 WS로 바뀌는 순간부터 네트워크 단절은 정상 상황이므로, 최소 재접속 스냅샷은 B의 exit criteria, Web Push/폰 승인 UX polishing은 C로 두는 편이 안전합니다.

---

제안하는 PR/이슈 코멘트용 요약

아래 정도로 PR에 남기면 좋겠습니다.

v3 우선은 타당. 현재 코드 구조상 window.fleet 단일 브리지와 Electron 비의존 core 덕분에 IPC→WS 전송층 분리는 버려지는 공사가 아니다. 다만 v3 WS 프로토콜은 단일 사용자 전제라 v2/v1의 tenant/auth/session ownership까지 자동 재사용된다고 보면 안 된다.

주요 보강점은 세 가지:

1. “renderer 무변경”은 API 표면 한정으로 쓰고, WS bridge가 IPC의 invoke/event semantics, stream seq, reconnect snapshot을 보장해야 한다.
2. ApprovalGate fail-closed는 기존 구현과 일치하지만, 웹에서는 “연결 있음”이 아니라 “승인 가능한 authenticated client presence” 기준이어야 한다.
3. 웹터미널은 ApprovalGate 밖의 원격 셸이므로 별도 보안 경계로 다뤄야 한다. CLI login volume, workspace mount, store volume을 분리하고, Phase A에서 피해 반경을 문서화해야 한다.

Phase B 완료 정의에는 core vitest 외에 FleetBridge parity, WS reconnect/stream ordering, approval no-client timeout, Origin/auth 검증, browser smoke를 추가하는 것을 권장.

---

작업 상태

코드 변경은 하지 않았습니다. 따라서 커밋 및 새 PR 생성도 하지 않았습니다.

Testing / Checks

• ✅ pwd && rg --files -g 'AGENTS.md' -g 'brain.md' -g 'docs/fleet-saas-infra-plan*.html' -g 'src/preload/index.ts' -g 'src/shared/types.ts' -g 'src/main/**/*.ts' | sed -n '1,120p'
• ✅ sed -n '1,220p' brain.md && printf '\n---plan lines---\n' && nl -ba docs/fleet-saas-infra-plan-v3.html | sed -n '1,220p' && printf '\n---preload---\n' && nl -ba src/preload/index.ts | sed -n '1,260p' && printf '\n---types bridge excerpt---\n' && nl -ba src/shared/types.ts | sed -n '1,260p'
  • 참고: 현재 checkout에는 docs/fleet-saas-infra-plan-v3.html 파일이 없어 nl이 해당 파일을 열지 못했습니다. 그래서 문서 본문은 입력된 PR 정보에 의존했고, 코드 검증은 로컬 파일 기준으로 했습니다.
• ✅ find docs -maxdepth 2 -type f -name '*saas*' -o -name '*infra*' | sort && rg -n "Fleet SaaS|v3|터널|WebSocket|ApprovalGate|Cloudflare|Tailscale|ttyd|code-server|ToS" docs src/main src/preload src/shared -g '!docs/fleet-saas-infra-plan-v3.html'
• ✅ nl -ba src/main/index.ts | sed -n '1,320p'; printf '\n--- approval ---\n'; nl -ba src/main/core/safety/approval.ts | sed -n '1,140p'; printf '\n--- bridge ---\n'; nl -ba src/main/core/safety/approval-bridge.ts | sed -n '1,180p'; printf '\n--- engine relevant ---\n'; nl -ba src/main/core/engine.ts | sed -n '170,245p'; printf '\n--- ChatPanel stream handling ---\n'; nl -ba src/renderer/components/ChatPanel.tsx | sed -n '1,220p'
• ✅ nl -ba src/shared/types.ts | sed -n '300,430p'; printf '\n--- ProjectPanel orch events maybe ---\n'; nl -ba src/renderer/components/ProjectPanel.tsx | sed -n '1,170p'; git status --short
• ✅ git status --short && git log --oneline -5

View task →

[pdw96]

✅ 체크포인트 1 리뷰 반영 (조건부 승인 → 조건 이행)

리뷰 감사. 6개 검증 포인트 판정 전부 수용, 75f40f6 로 문서 반영 완료 (PR #194):

1. "공통 기반" 명제 정정 — "전송층 추상화 는 재사용, v3 WS 프로토콜 그대로 v2/v1 이관은 과장(인증·테넌트·session ownership 부재)" 으로 §1 callout·§2·§13 수정. 이슈 본문도 동일 정정.
2. renderer 무변경 = API 표면 한정 — WS 브리지가 재현할 IPC 시맨틱(invoke correlation·streamId별 seq 단조·리스너 멱등·재접속)을 §6 에 명문화. 재접속 스냅숏 복구를 Phase C→B 로 앞당김 (WS 에선 단절이 정상 상황이라는 지적 수용).
3. ApprovalGate — "fail-closed 는 신규 정책이 아니라 기존 계약(창 부재 즉시 거부 + APPROVAL_TIMEOUT_MS 60s)의 이식" 으로 정정. 웹 기준 = 연결 수 아닌 승인 가능한 인증된 presence, 다중 기기 중복 응답 멱등 명시. (제 체크포인트 질문의 "데스크톱 모달 무기한 대기" 가정이 코드와 달랐음 — 정정 감사.)
4. 웹터미널 위협 — §7 마운트 최소화(ttyd = workspace+cli-auth 만, fleet-data 미마운트) + 정직한 피해 반경 = workspace+cli-auth(문 ① 본질상 CLI 토큰 노출 감수) 명시 + Docker 소켓 미마운트 + 시크릿 키를 fleet-data 볼륨에서 분리(호스트 주입) (P2).
5. 브라우저 신규 보안 경계 — Electron guards 소멸 → §6 신규 행 + §8 위협 행: CSP · WS/REST Origin 검증 · Access identity(JWT) 서버 자체 검증 · CF_Authorization 쿠키 cross-site 전송 리스크 (P1).
6. Phase B 완료 정의 강화 — 전송층 계약 테스트 5종(parity·correlation·스트림 순서·승인 fail-closed·Origin/identity 거부) + 브라우저 스모크를 exit criteria 로. 이슈 본문 Phase 체크리스트 갱신 완료.

ToS 문구도 권고안대로 엄격화("공식 CLI 가 허용하는 범위에서 사용자가 직접 인증한 로컬 도구를 호출하는 선택지 · 지원되는 동안의 할인 경로").

v2 문서 인라인 3건(P1 runner→owner RLS 매핑 · P2 Broadcast private 채널 · P2 완결 메시지 러너 영속)도 같은 커밋에 반영.