feat: env 토글 기반 headless + lean Chrome 런치 (리소스 절감)

[pghoya2956]

배경 (근본원인)

bridge가 띄우는 Chrome은 토스 화면을 렌더/스크레이프하지 않는다. 데이터는 페이지 안 fetch(url, {credentials:"include"})로 토스 cert API를 직접 호출해 가져오고(daemon.py evaluate→fetch), 브라우저는 ① 로그인 세션 보관(persistent profile) ② 토스 JS 요청서명용 App-Version 추출 호스트 역할만 한다. 즉 GPU 컴포지터·이미지 디코드·1440×960 창 전체가 순수 오버헤드.

그런데 start_browser()는 launch_persistent_context(... headless=False, args=["--window-size=..."])로 하드코딩돼 있어 env로 못 바꿨다.

변경

• resolve_browser_launch_options() 순수 함수 추가 — env 토글을 읽어 launch kwargs 빌드
• env 토글 2개 (기존 _env_flag + TOSS_BRIDGE_ENABLE_FINAL_SUBMIT 패턴 재사용):

  토글	기본	동작
  TOSS_BRIDGE_HEADLESS	off	on → headless=True (Playwright 신형 headless)
  TOSS_BRIDGE_LEAN	off	on → LEAN_CHROME_ARGS (GPU/이미지/확장 비활성 등)

• start_browser()는 **resolve_browser_launch_options()로 호출부만 교체
• README env 토글 표 + 운용 모델 문서
• 단위테스트 신규 (tests/test_browser_launch.py)

하위호환

토글 둘 다 미설정이 기본이며, 그때 launch 인자는 현행(headed + --window-size=1440,960)과 바이트 단위로 동일하다. test_no_toggles_matches_current_hardcoded_baseline로 회귀 고정. 잘못된 env 값(off/오타/빈값)은 전부 안전하게 off.

검증

• 신규 단위테스트 10건 pass (회귀 고정 + 토글 조합 + 오타값 안전처리)
• clean env 전체 스위트 99 passed (financier-v2 .envrc의 TOSS_BRIDGE_* 누출 제외 시)

미완 (Phase 2 — 토스 로그인 필요)

이미지/GPU OFF·headless가 실제 토스 조회/주문에 통과하는지 라이브 실측과 Chrome RSS 전후 수치는 헤디드 1회 로그인 후 별도 진행. headless는 토스 anti-automation 차단 가능성이 있어 조회 4종(account-summary/positions/quote/completed) 검증 후 주문 확대 원칙. 이 PR은 backward-compatible scaffolding(기본 off)이라 머지해도 회귀 위험 0.

스펙: tasks/20260617-bridge-headless-lean/spec/initial.md

🤖 Generated with Claude Code

[pghoya2956]

Phase 2 — 라이브 실측 결과 (✅ 통과)

financier-v2 격리 env(TOSS_BRIDGE_PORT=42184), 로그인 세션 attached 상태에서 브랜치 설치 후 실측.

플래그 실제 적용 확인 (main chrome cmdline)

--headless · --disable-gpu · --blink-settings=imagesEnabled=false · --window-size=1440,960 모두 박힘.

봇 탐지 / 세션

• TOSS_BRIDGE_HEADLESS=on TOSS_BRIDGE_LEAN=on 재기동 → session_state: attached, 토스 차단 없음.
• 세션은 chrome-profile에 잔존 → headed 재로그인 없이 headless 재기동에서 그대로 재사용 확인.

조회 end-to-end (health 플래그 아닌 실데이터)

account-summary / positions / quote 실호출 모두 정상 응답 (cert-API App-Version 서명 경로 포함). account_summary_ready/positions_ready/quote_ready/completed_orders_ready/order_preview_ready 전부 true.

Chrome RSS (동일 ps 합산 방법, shared-page 중복 포함 — 전후 비교용)

모드	프로세스	합계 RSS
headed (baseline)	9	6916.7 MB
headless + lean	7	1062.6 MB

→ 약 85% 감소. audio 프로세스 제거, 창/컴포지터 제거 효과.

비고

• 주문(place) 경로 headless 기본 전환은 범위 밖(조회 검증까지). order-preview capability는 ready 확인했으나 실 preview 호출은 주문 가드(스킬 경유) 존중해 생략.
• 측정 후 소비자 bridge는 v0.4.1 headed로 원복함.