fix(dashboard): guide browser pairing with the hub and preserve error meaning

[lidge-jun]

Summary

A connected dashboard awaiting browser authentication now shows the hub identity and a copyable ocx gui pair --origin command for its exact browser origin. It explains where to obtain the one-time code and distinguishes it from data/API administrator credentials.

The shell and Dashboard share session readiness. Pairing success explicitly refreshes retained resource stores; expiry restores pairing; 403 permission denial keeps separate guidance. Authentication failures hide protected data, while other refresh failures can show labelled stale data with Retry. Connected clients are not told to run ocx start. Obsolete pairing submissions are cancelled before session installation.

Addresses #4206 and #4208 together. Independent PR targeting dev, with no native stack or live-service change.

Verification

• Local suites of every size, typecheck, build and install: NOT RUN, explicitly prohibited for this delivery.
• git diff --cached --check: passed. Independent design and entry audits passed after cache-refresh and state-contract corrections; implementation source review passed; final hosted execution remains pending.
• Added/extended regressions for pending/authenticated/expired state, a retained failed store, stale data, permission denial, error/shape classification and cancelled pairing bodies. All nine locales contain the new copy.
• Final-tip GitHub-hosted CI and GUI screenshot from the hosted build are pending; no fabricated preview is claimed.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults; independent implementation source review passed; hosted execution and rendered evidence remain pending.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[lidge-jun]

리뷰 · 우선순위 54 / 80

이 PR은 연결된(connected) 대시보드가 허브 브라우저 인증을 기다리는 동안, 사용자에게 “지금 뭘 해야 하는지”를 정확히 알려 주는 작업입니다. 현재 dev HEAD는 489af939b (package.json 2.52.0, 직전 머지 #4347 Claude prompt-cache opt-in)이고, GUI 페어링 축은 그대로 gui/src/App.tsx, gui/src/connect-pairing.ts, gui/src/connect-pairing-transport.ts, gui/src/pages/Dashboard.tsx, gui/src/pages/dashboard-core-poll.ts, gui/src/pages/use-dashboard-data.ts입니다. 이슈 #4206/#4208을 한 번에 겨냥합니다. “허브는 살아 있는데 브라우저 세션만 없다”는 상태를 “프록시가 꺼졌다”고 오해하면 ocx start만 권하게 되는데, 그건 틀린 처방입니다. 이 변경은 그 오해를 끊습니다.

핵심 동작은 네 갈래입니다. 첫째, 페어링 폼에 허브 serverOrigin과 현재 브라우저 origin용 ocx gui pair --origin 복사 명령을 보여 주고, 일회용 코드와 데이터 API/관리자 토큰을 구분해 설명합니다. 둘째, App이 SESSION_UNAVAILABLE_EVENT를 구독해 shared 세션 만료를 셸과 맞추고, 페어링 성공 시 sharedSessionEpoch를 올려 대시보드 리소스 스토어를 다시 읽게 합니다. 셋째, fetchDashboardOverview가 401/403/기타/잘못된 JSON/네트워크를 auth/denied/request/invalid/unavailable로 나눠서, 인증 실패는 보호 데이터를 숨기고, 그 외 실패만 stale 데이터+Retry를 허용합니다. 넷째, 페어링 요청에 AbortController를 붙여 폼이 바뀌거나 언마운트되면 오래된 응답이 세션을 심지 못하게 합니다. 로케일 9개와 gui/tests/connect-pairing.test.ts, 새 gui/tests/dashboard-connection-state.test.ts까지 같이 왔습니다.

현재 dev와의 관계는 좋습니다. #4372 원격 워크스페이스 대시보드, #4373 허브 클라이언트 usage 스코프와는 파일 축이 다릅니다. 다만 이 PR은 draft이고 mergeable 상태가 CONFLICTING(DIRTY)입니다. 지금 tip으로는 바로 머지할 수 없습니다. 본문도 로컬 suite/typecheck/build를 의도적으로 돌리지 않았고, 체크리스트에 보안 리뷰가 아직 pending입니다. 동작 수락은 호스티드 CI와 GUI 스크린샷에 맡기는 전제입니다.

devlog/_plan/260912_operations/ - 페어링 구현 PR 안에 update/listeners/totals/client-usage/transport 전체 로드맵 문서(000~070)가 같이 들어 있습니다. 실제 코드 변경은 pairing GUI 축인데, 문서는 #4185/#4111/#4205/#4315까지 계획합니다. 읽는 사람이 “이 PR이 그 전부인가?”로 헷갈리고, 특히 client-usage는 이미 열린 #4373과 겹칩니다. pairing 전용으로 문서를 줄이거나, 로드맵만 따로 두는 편이 안전합니다.

mergeable: CONFLICTING - 현재 dev HEAD 489af939b 기준 충돌입니다. draft라도 충돌을 풀기 전에는 CI 최종 tip을 신뢰하기 어렵습니다. 먼저 rebase/resolve가 필요합니다.

gui/src/api.ts / SESSION_UNAVAILABLE_EVENT - 예전에는 admin-token prompt가 막힌 배포에서만 이벤트를 쏘던 설명이 있었는데, 이제는 401 복구 실패 전반에서 쏩니다. 의도는 맞지만, standalone에서 세션이 진짜로 없을 때 대시보드가 pairing 쪽으로 기울지 않는지(connected=false 경로) 한 번 더 확인이 필요합니다. 테스트는 connected relay 경로 중심입니다.

Dashboard - authenticationPending이면 컴포넌트가 null을 반환합니다. App이 위에 페어링 폼을 그리므로 UX는 맞지만, 해시가 #dashboard인데 본문이 비는 구간이 생깁니다. 의도된 “폼만 보이기”라면 괜찮고, 빈 영역이 거슬리면 짧은 pending 안내를 Dashboard 안에 두는 선택지도 있습니다.

메인테이너의 판단이 필요한 지점

• 이 PR에 operations 전체 로드맵 문서를 남길지, pairing 슬라이스만 남길지
• CONFLICTING을 지금 고쳐 draft를 ready로 올릴지, 형제 operations PR(feat(usage): read connected hub usage scoped to the enrolled client key #4373 등) 순서를 먼저 정할지
• 로컬 검증 금지 전제를 유지한 채 호스티드 CI+스크린샷만으로 머지 게이트를 삼을지

너의 추천
충돌부터 풀고, devlog/_plan/260912_operations/에서 pairing(050)과 공통 로드맵 요약만 남기거나 로드맵 PR을 분리한 뒤, CI 초록과 pending 페어링 UI 스크린샷이 오면 ready로 올려 머지하세요. #4206/#4208 방향 자체는 맞고 dev의 다른 열린 축과도 잘 갈라져 있습니다.

이 댓글은 grok-bot이 작성했습니다

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• UI screenshot required.

What to do

• Add a screenshot of the UI change to the PR description.

This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.