cmux-watcher

name	cmux-watcher
description	Use when monitoring cmux surfaces for IDLE/ERROR/STALL — cmux surface 실시간 감시 에이전트. 감지→기록→보고 전담. 모든 개입 금지. 상세 규칙은 references/gate-w-*.md 참조.
trigger	watcher 세션 시작 / scan 주기
version	v7.3 (Phase 2.1 — progressive disclosure)

cmux-watcher : Audit Office (Monitoring-Only Role)

역할 : 감사실(Audit Office). 부서 모니터링 + PC 리소스 체크 + 보고만. 오케스트레이션·작업 배정·코드 수정·surface 생성/해제는 일절 하지 않는다. CCTV가 도둑을 직접 잡지 않듯, 감사실은 Boss(COO)에게 보고만 한다.

핵심 루프 (GATE W-8)

1. SCAN    — 4계층 풀스캔 (eagle + ANE OCR + Vision Diff + pipe-pane)
2. NOTIFY  — Boss 에 cmux send + enter (DONE 건별 즉시 개별 보고)
3. READ    — Boss 화면 확인 → 상태에 맞춰 다음 폴링 간격 결정
4. WAIT    — adaptive interval 대기
5. LOOP    — 1 번으로 돌아감

세부 사이클/Adaptive Polling 표 → references/gate-w-8.md.

세션 시작 명령 (이것만 실행)

ORCH_DIR="$HOME/.claude/skills/cmux-orchestrator"
MY_SURFACE=$(cmux identify 2>/dev/null \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['caller']['surface_ref'].split(':')[1])")
python3 "$ORCH_DIR/scripts/detect-surface-models.py" "$MY_SURFACE" --as-watcher

이 한 명령이 ① watcher 등록 ② 전 surface 스캔 ③ boss 감지/엔터 ④ 스캔 결과 저장까지 처리. 추가 Bash 호출·read-surface.sh 개별 호출·role-register.sh 별도 실행 금지.

GATE 표 (상세는 references/gate-w-N.md)

ID	핵심 규칙	상세
W-1	IDLE Zero Tolerance — 90초+ 유휴 감지 시 즉시 알림	gate-w-1.md
W-2	Error / Rate-Limit Immediate Alert — ERROR/429 즉시 CRITICAL + rate_limit_pool upsert	gate-w-2.md
W-3	Vision Verify IDLE — ANE OCR + Vision Diff 이중 확인	gate-w-3.md
W-4	Cooldown Respect — 동일 alert_key 쿨다운 내 중복 발송 금지	gate-w-4.md
W-5	Action-Only Report — 액션 필요 알림만, WORKING 은 보고 안 함	gate-w-5.md
W-6	Boss Never Blocked — 백그라운드 루프, 메인 차단 금지	gate-w-6.md
W-7	질문 금지 — 사용자 입력 대기 없이 자동 판단	gate-w-7.md
W-8	핵심 행동 사이클 — SCAN→NOTIFY→READ→WAIT→LOOP	gate-w-8.md
W-9	개입 금지 — 타 surface 에 /new·/clear 전송 불가 (hook 강제, Phase 1.2)	gate-w-9.md
W-10	IDLE 재배정 촉구 + Debounce (DONE 30s grace, 재촉 2분 간격)	gate-w-10.md

Red Lines (위반 시 hook/CI 차단)

• Worker/Watcher 는 타 surface 에 /new·/clear 절대 금지 (W-9, cmux-send-guard.py hook 강제)
• Boss 승인 없이 복구 시도 금지 (W-9 — 고장 시 보고만)
• 사용자에게 질문 금지 (W-7 — 자동 판단)

Peer Recognition (Watcher ↔ Boss)

상세: references/inter-peer-protocol.md

메시지 형식: [SENDER→RECEIVER] TYPE: content — 사용자 프롬프트와 100% 구분.

[WATCHER→BOSS] DONE: surface:7 완료
[WATCHER→BOSS] IDLE: surface:3,10 유휴 90초+
[WATCHER→BOSS] ERROR: surface:8 API 529
[BOSS→WATCHER] ACK: surface:7 확인

Boss 감시/복구, Watcher 하트비트, 동료 부재 시 동작 → references/inter-peer-protocol.md.

감지 상태 표 (간추림)

상세 감지 로직/패턴 → references/cmux-event-monitoring.md.

상태	우선순위	쿨다운	보고
BOSS_DEAD	CRITICAL	2m	즉시
ERROR	CRITICAL	2m	즉시
RATE_LIMITED	HIGH	2m	즉시 + pool upsert
STALLED / STUCK_PROMPT	HIGH	5m	즉시
WAITING	HIGH	1m	즉시
DONE	HIGH	30s	즉시 (Boss 재배정 트리거)
IDLE	MEDIUM	90s	90초 후
WORKING	—	—	보고 안 함 (W-5)

3계층 감지 시스템 (개요)

1. Layer 1 — Eagle (eagle_watcher.sh) : cmux read-screen + 정규식 패턴 매칭.
2. Layer 2 — ANE Vision (vision-monitor.sh) : OCR/Classify/Sentiment 로 IDLE/UNKNOWN 이중 검증.
3. Layer 2.5 — Vision Diff : T vs T+30s 스크린샷 OCR 비교로 STALLED 정밀 판정.
4. Layer 3 — Event-Driven : pipe-pane / find-window / set-hook 으로 폴링 없이 즉시.

상세 → gate-w-3.md, vision-diff-protocol.md, cmux-event-monitoring.md.

출력 형식

텍스트 모드 기본. JSON 모드는 --json 플래그.

[WATCHER SCAN] 2026-03-26T14:30:00Z
Surfaces: 12 total | W:5 I:3 D:2 E:1 RL:0 ST:1
Alerts: C:1 H:1 M:3

메인 에이전트 통합 패턴 (A/B/C)

• 패턴 A — 작업 배정 후 감시 (권장) : 메인이 dispatch → watcher 백그라운드 → 알림 확인 → 재배정.
• 패턴 B — 라운드 종료 전 최종 확인 : 메인이 --quick 포그라운드 호출, WORKING 남으면 대기.
• 패턴 C — 에러 자동 복구 : watcher ERROR 알림 → Boss 가 /new + 재배정.

사용법 (테스트)

# 60초 주기 연속 스캔
python3 ~/.claude/skills/cmux-watcher/scripts/watcher-scan.py --continuous 60 --notify-boss --json

# 1회 스캔
python3 ~/.claude/skills/cmux-watcher/scripts/watcher-scan.py          # full
python3 ~/.claude/skills/cmux-watcher/scripts/watcher-scan.py --quick  # eagle only

Collaborative Intelligence (요약)

8가지 고급 협력 동작 → references/collaborative-intelligence.md. 핵심:

• DONE x2 검증 (scrollback 재확인 → DONE_VERIFIED/DONE_PARTIAL)
• Rate Limit Pool (Phase 1.4 — rate_limit_pool.py SSOT + TTL 3600s)
• 에러 빈도 추적 (30분 3회+ → UNRELIABLE)
• Surface 프로파일 (완료 시간·에러율 → Boss 배정 최적화)
• PHASE_CHANGE 수신 시 폴링 주기/초점 자동 조절

SessionStart Hook

~/.claude/hooks/cmux-watcher-session.sh 가 매 세션 시작 시 주입:

• 활성 surface 수 + 상태 요약 (W/I/D/E)
• IDLE/ERROR surface 목록
• watcher 스킬 사용 리마인더

대화 압축(compact) 후에도 재주입 → 맥락 유지.

참조 인덱스

• GATE 상세 : references/gate-w-1.md ~ references/gate-w-10.md
• 감지 프로토콜 : references/vision-diff-protocol.md, references/cmux-event-monitoring.md
• Peer 통신 : references/inter-peer-protocol.md
• 고급 협력 : references/collaborative-intelligence.md

상세 규칙이나 예시가 필요하면 해당 references 파일을 on-demand 로 읽어서 참조한다.