---
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](references/gate-w-8.md).

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

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

## 감지 상태 표 (간추림)

> 상세 감지 로직/패턴 → [references/cmux-event-monitoring.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](references/gate-w-3.md), [vision-diff-protocol.md](references/vision-diff-protocol.md), [cmux-event-monitoring.md](references/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` + 재배정.

## 사용법 (테스트)

```bash
# 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](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** 로 읽어서 참조한다.