session-relay 작업 규칙

📑 인덱스

🆕 신규 — 최근 확립된 규칙
§1 넘기는 시점 · §2 인계문 · §3 실행 · §4 금지

🆕 신규

2026-08-26 「돌고 있는 다른 세션에 지시 전달」 = tools/cody-bridge/send_to_window.py. 릴레이(relay.py)는 새 세션을 여는 도구라 이 용도엔 못 쓴다(/newsession 이 sessionId=undefined 고정). 진행중 세션에 넣는 경로는 브릿지 /send(클립보드+입력창 포커스) + Ctrl+V + Enter 뿐 — voicecody 의 VS Code 경로와 같은 절차인데 음성 데몬(numpy·whisper) 을 안 끌고 온다. 절차 = relay.find_vscode_window/bring_to_front/foreground_info 로 전면 재확인 후에만 키 전송(위 「무효라서 안전에 기대지 않는다」 규칙 그대로). 사용 = PYTHONUTF8=1 python tools/cody-bridge/send_to_window.py --file <msg.md> --title dev.
🔑대상 세션 특정 = 창 제목이 제일 확실하다(… - dev - Visual Studio Code 앞이 그 창의 활성 Claude 탭 이름). 스크립트가 [1] 전면화 OK: <제목> 으로 찍어주니 그걸 보고 판정한다. 브릿지 창이 여러 개면 --title 로 좁힌다.
도달 검증 = 대상 세션 transcript(~/.claude/projects/C--dev/<sid>.jsonl) 에서 보낸 문구를 grep. 작업중이면 queue-operation enqueue → 소비되면 remove 가 찍힌다. /send 200 은 도달 증거가 아니다(확장은 포커스만 준다, pasted:false).
2026-07-30 사용량 한도는 주 1회 자동보정한다(페페 지시). 예약작업 SessionRelay-Calibrate(매주 목 10:00, pythonw = 창 없음)이 calibrate.py 로 /usage 를 실행해 주간%·리셋시각을 읽고, 같은 창 로컬 토큰으로 한도를 역산해 10% 넘게 어긋나면 state.json 갱신 + 텔레그램 보고(임계 이내면 조용히). /usage 실행 실패·형식 변경은 실패로 보고한다(조용한 실패 금지). 사용률 3% 미만이면 역산 오차가 커서 건너뛴다. ⚠calibrate.py 는 셸을 안 거치고 인자 배열로 실행하므로 MSYS 경로변환이 아예 개입하지 않는다(수동으로 Bash 에서 칠 때만 MSYS_NO_PATHCONV=1 필요).
2026-07-30 구독 사용률은 claude -p "/usage" 로 실측한다(페페 아이디어, 실측 성공). 로컬 파일·transcript 어디에도 플랜 한도/사용률이 없어서 못 구하는 줄 알았는데, CLI 헤드리스로 슬래시 명령이 돈다. ⚠Git Bash 가 /usage 를 경로(C:/Program Files/Git/usage)로 바꾸므로 MSYS_NO_PATHCONV=1 필수(안 붙이면 "내장 명령이라 못 돌린다"는 엉뚱한 답이 온다). 결과 = 세션 %·주간 %(모델별)·리셋 시각·요청수까지 나온다.
2026-07-30 사용량 게이트 캘리브레이션(Max 20x): /usage 주간 19% ↔ 같은 창 로컬 토큰 68,109,289 → weekly_token_budget = 358,000,000 역산, 코디 계산 19.0% 로 일치 확인. 주간 창은 롤링 7일이 아니라 고정 리셋 시각 기준(week_reset_iso, 실측 8/3 22:00 KST) — 롤링으로 세면 2.1일 창에 7일치를 넣어 3배 부풀려진다. 한 달에 한 번쯤 /usage 와 대조해 보정.
2026-07-30 릴레이 안전장치 3종(페페 지시). ①체인 상한 — chain_window_h(12h) 안에 max_chain(5)회를 채우면 텔레그램 승인을 받아야 이어간다(무한 릴레이 = 토큰 낭비 방지). ②매 릴레이 텔레그램 보고 — 요약·새 세션 id·체인 회차·주간 사용량을 broker /ask 로 보내되 기다리지 않는다(자동 진행 유지). 그 문자에 중단 이라고 답장하면 다음 릴레이의 preflight 가 읽고 막는다(해제 = state.json 의 stopped_reason → null). ③주간 사용량 70% 초과 시 매 릴레이 승인제. 승인 무응답(600초)이면 진행하지 않는다(안전측). 임계값은 전부 tools/session-relay/state.json.
⚠2026-07-30 사용량 지표에서 cache_read 는 기본 제외. 실측 7일 = cache_read 33.7억 vs 나머지 1.6억 → 캐시 읽기가 95% 라 그냥 더하면 지표가 통째로 왜곡된다(캐시 읽기는 매 요청마다 전체 컨텍스트를 다시 세고 단가도 1/10). 단가 비례로 반영하려면 usage_read_weight=0.1.
2026-07-30 도달 검증은 "실행 전 파일 스냅샷"으로 자기 자신을 걸러야 한다. 인계문 문자열은 릴레이를 돌린 세션의 transcript 에도 들어 있어서(그 세션이 인계문을 작성했으니까) find_transcript 가 자기 자신을 새 세션으로 잡고 [OK] 를 냈다 — 첫 실전에서 실측. 실행 전 transcript_files() 스냅샷을 exclude 로 넘긴다. 검증이 통과했다고 새 세션이 열린 게 아니다: 세션 ID 가 지금 세션과 다른지 눈으로 확인할 것.
🔴 2026-07-30 키 전송은 "무효라서 안전"에 기대지 않는다(사고 후 확립). 07-29 기록 "코디 Bash 는 GetForegroundWindow()=0 이라 SendInput 무효"를 믿고 --enter-only 를 코디 Bash 에서 테스트했더니 Enter 가 실제로 나갔고 전면 창인 Chrome(YouTube)이 받았다. → 키를 보내는 코드는 대상 창 특정 → 전면화 → 전면 재확인 3단계를 통과해야만 전송한다(enter_into_vscode). 창을 못 찾으면 무조건 미전송, 자체검사 t_window_guard 가 이를 강제한다.
2026-07-30 릴레이는 Enter 까지 자동(페페 승인). Enter 주체 = 브릿지 확장 v1.6(/newsession {prompt, submit}). 확장은 VS Code 프로세스 안에서 돌므로 자식 프로세스의 SendInput 이 먹고, 창 전면화도 헬퍼가 자동으로 한다(페페 지시 "코디가 실행하는 것이니 창 전면화도 자동"). --submit 기본 auto = bridge. 확장이 구버전이면 relay 가 종료코드 8 + "Enter 만 누르면 된다" 안내.
2026-07-30 실사용 = 페페의 사용자 VS Code 인스턴스(페페 정정). CDP 격리 인스턴스(launch_vscode_cdp.vbs)는 개발·검증 전용이다. auto 가 CDP 를 자동 탐색하지 않는 이유 = 프리필한 창(브릿지 포트)과 CDP 포트가 다른 창일 수 있어 엉뚱한 세션에 Enter 가 박힌다.
2026-07-29 세션 넘기기 기준 = 컨텍스트 50~60% 구간에서 작업 단계를 끊을 수 있는 지점을 확인한 뒤 진행(페페 지시). 근거 = 60% 넘겨 넘기면 인계문 쓸 여유 자체가 부족.
2026-07-29 릴레이 전 시드 갱신 + 커밋이 선행 조건(페페 지시). relay.py가 user_brief 미커밋 변경을 게이트로 강제한다(--force는 예외용).
2026-07-29 코디 Bash는 대화형 데스크톱이 아니라 SendInput이 조용히 무효(GetForegroundWindow()=0) → 코디가 Enter를 누르는 경로는 CDP뿐이고, 그 CDP도 평소엔 없다(위 2026-07-30 항목이 이 규칙을 대체·정정한다).

§1 넘기는 시점

컨텍스트 50%에 도달하면 "지금 끊어도 되는 단계인가"를 본다.
끊을 수 있으면 넘기고, 아니면 그 단계를 끝낸 뒤 60% 전에 넘긴다.
넘기기 직전 순서 = 시드 갱신 → 로컬 커밋 → 인계문 작성 → relay 실행.

§2 인계문에 반드시 넣는 것

작업 폴더 / 이번 작업에서 확정된 규약(네이밍·구조·금지사항)
이미 끝난 것 / 남은 것 (남은 것은 번호로)
손대면 안 되는 파일과 그 이유
보고 형식(마커를 넣으면 relay --expect로 자동 채점된다)
시드 포인터(BRIEF.<P>.md, projects/<P>/handoff.md) — 새 세션이 §0 시드 체인을 다시 읽는다

§3 실행 (실사용 = 사용자 인스턴스)

PYTHONUTF8=1 python C:/dev/tools/session-relay/relay.py \
  --prompt-file <인계문.md> --workspace "C:/dev" --title dev \
  --model opus --effort xhigh --thinking on

--submit 생략 = 프리필까지. [OK] 새 탭 입력창에 지시문이 들어갔다 가 뜨면 페페가 그 창에서 Enter.
대상 창 = --title(워크스페이스 이름) 권장. --focused는 페페가 그 창을 보고 있을 때만.
--submit cdp:<port> 는 launch_vscode_cdp.vbs 로 띄운 개발·검증 인스턴스 전용.

§4 금지

진행 중인 다른 세션 창으로 넘기지 않는다 — 반드시 포트/타이틀로 대상 창을 명시한다.
인계문에 비밀값(토큰·비번)을 적지 않는다. 경로 포인터만.
시드 미갱신 상태로 --force 강행하지 않는다(다음 세션이 옛 상태를 읽는다).

🆕 신규

🆕VS Code X버튼 = 트레이 최소화(26.8.23(일) [코디] 페페 지시) — X 실수클릭으로 세션 날리던 사고 차단. 도구 = C:\dev\tools\vscode-tray\vstray.pyw(pythonw 상주, HKCU Run 자동시작). X/Alt+F4 를 저수준 훅으로 삼키고 SW_HIDE → 프로세스 살아있어 클로드코드 세션 유지. 트레이 우클릭 = 창별 복원·전체복원·창 리로드(ctrl+alt+shift+r 주입, keybindings.json 에 등록함)·VS Code 재시작·진짜 종료. 상세·한계 = C:\dev\tools\vscode-tray\README.md.
⚠막지 못하는 경로 = 관리자권한 Code 창(UIPI로 훅이 입력을 못 봄) · File>Exit · 작업표시줄 우클릭 닫기 · 전체화면(타이틀바 없음이라 개입 안 함). 이 경로들은 그대로 종료된다.
⚠히트박스가 하드코딩(클라이언트 우측 46 × 상단 32 CSS px, dpi/zoomLevel 로 스케일). VS Code 가 타이틀바 디자인 바꾸면 X 클릭이 그냥 종료로 샌다 → vstray.pyw 상단 BTN_W_CSS/TITLE_H_CSS 조정 후 test_vstray.py.
⚠SW_HIDE 는 최소화가 아니라 hot-exit 가 안 돈다 — 숨긴 상태로 PC 가 죽으면 미저장 백업이 없다.