# task-1715.1 완료 보고서

## SCQA

**S**: 세션 자동 이어가기 Watchdog Phase 1이 완료되어 heartbeat hook, session-watchdog.sh, systemd timer가 2분 주기로 정상 동작 중이다. (task-1710.1)

**C**: 재위임 후 즉시 재실패하는 usage limit 상황에서 무한 재위임이 발생할 수 있고, 8팀 동시 stalled 시 dispatch.py 16건 연속 호출과 개별 Telegram 알림 폭주가 우려된다.

**Q**: Circuit Breaker 패턴과 동시 재위임 상한으로 watchdog의 안정성을 확보할 수 있는가?

**A**: 3가지 보호 메커니즘 추가 완료 — 빠른 재실패 감지(3분 윈도우) + 30분 백오프, 사이클당 최대 3건 재위임 상한, 집계 알림 단일 전송. 대시보드 `/api/watchdog/history` 엔드포인트 추가. 전체 36/36 테스트 통과.

---

## 구현 내용

### 1. Circuit Breaker 세밀화
- `.backoff` 파일 2행 포맷: line 1 = 마지막 재위임 epoch, line 2 = 백오프 만료 epoch (0이면 미적용)
- 재위임 후 다음 사이클(3분 이내)에서 재stalled → "빠른 재실패" 판정 → 30분 백오프 설정
- 백오프 중 재위임 스킵, 만료 후 정상 재위임 재개
- 상수: `RAPID_REFAIL_WINDOW=180`, `BACKOFF_DURATION=1800`

### 2. 동시 재위임 상한
- `MAX_REDELEGATIONS_PER_CYCLE=3`: 사이클당 최대 3건만 재위임
- 4건째부터 `deferred` 태그로 다음 사이클 연기 + 알림 포함

### 3. 집계 알림
- 개별 curl 3곳 제거 → 루프 종료 후 단일 curl 1회 전송
- 3개 배열: `REDELEGATED_LIST`, `ESCALATED_LIST`, `STALLED_LIST`
- 형식: `[Watchdog] 🔄 재위임 2건: ... / 🚨 에스컬레이션 1건: ... / ⚠️ stalled 1건: ...`

### 4. 대시보드 재위임 이력 엔드포인트
- `GET /api/watchdog/history?limit=50` → JSON 배열
- session-watchdog.log 역순 파싱: redelegation, escalation, backoff, rapid_refail, deferred 6가지 액션 유형
- 기존 `send_api_response()` 패턴 준수

### 5. 테스트 강화
- TC9: 빠른 재실패 감지 (60초/300초/파일없음 3시나리오)
- TC10: 동시 재위임 상한 초과 (5건 중 3건 실행, 2건 연기)
- TC11: 백오프 만료 후 재개 (유효/만료/파일없음 3시나리오)
- `check_backoff()` 헬퍼 함수 추가

---

## 생성/수정 파일 목록

| 파일 | 변경 | 줄수 |
|------|------|------|
| `scripts/session-watchdog.sh` | 수정 | 182→234줄 (+52) |
| `scripts/tests/test_session_watchdog.sh` | 수정 | 482→596줄 (+114) |
| `dashboard/server.py` | 수정 | 라우트 2줄 + 메서드 48줄 추가 |

---

## 테스트 결과

```
결과: 36/36 (0건 실패)
```

- TC1~TC8 (Phase 1 기존): 전체 통과 (회귀 없음)
- TC9~TC11 (Phase 2 신규): 전체 통과
- BONUS (jq 쿼리): 전체 통과
- `bash -n session-watchdog.sh`: 문법 OK
- `python3 -m py_compile server.py`: 컴파일 OK

---

## 셀프 QC 체크리스트

- [x] 1. 영향 파일: session-watchdog.sh, test_session_watchdog.sh, server.py (3개)
- [x] 2. 엣지 케이스: .backoff 파일 1줄만 있는 경우(sed -n '2p' 빈 문자열 → fallback 0), 빈 배열(set -u 안전), 비숫자 필드(정규식 체크)
- [x] 3. 작업 지시 5개 항목 모두 구현 완료
- [x] 4. 보안: .backoff 파일 HEARTBEAT_DIR 내 저장 (기존 퍼미션 계승), Telegram 토큰 환경변수 유지
- [x] 5. 테스트 36/36 전체 통과, TC9~11이 새 경로 커버
- [x] 6. 발견 이슈 모두 해결 (아래 참조)
- [x] 7. SOLID/DRY: 집계 알림으로 curl 중복 3곳→1곳으로 통합
- [x] 8. 인터페이스: 새 API `/api/watchdog/history` 문서화 (본 보고서)
- [x] 9. 이미지 작업 없음 (N/A)
- [x] 10. CLAUDE.md 33줄 (100줄 미만)

---

## 발견 이슈 및 해결

### 이슈 1: set -u 환경에서 빈 bash 배열 참조 위험
- **발견**: `${STALLED_LIST[@]}`가 비어있으면 `set -u`에서 에러 발생
- **해결**: 모든 배열 접근 전 `${#arr[@]} -gt 0` 길이 체크 패턴 적용

### 이슈 2: .backoff 파일 파싱 시 비정상 내용 방어
- **발견**: .backoff 파일이 수동 편집 등으로 비숫자 문자열을 포함할 수 있음
- **해결**: `sed -n` 결과에 `if ! [[ ... =~ ^[0-9]+$ ]]; then ... =0; fi` 정규식 검증 추가

### 이슈 3: server.py JSON 응답 패턴 불일치 가능성
- **발견**: 기존 코드가 `send_api_response()` 사용, 설계 초안은 `_send_json()` 가정
- **해결**: 기존 패턴 확인 후 `send_api_response()` 로 통일

---

## 모델 사용 기록

| 팀원 | 역할 | 모델 | 작업 |
|------|------|------|------|
| 루(Lugh) | 백엔드 | sonnet | session-watchdog.sh 수정 (항목 1-3) |
| 루(Lugh) | 백엔드 | sonnet | server.py 엔드포인트 (항목 4) |
| 모리건(Morrigan) | 테스터 | sonnet | 테스트 강화 TC9-11 (항목 5) |
| 다그다(Dagda) | 팀장 | opus | 설계, 검토, 통합, 보고서 |

---

## 체크리스트 갱신 제안

Phase 2 항목 체크 완료:
- [x] 빠른 재실패 감지 (재위임 후 3분 내 재종료)
- [x] 30분 백오프 로직
- [x] 동시 재위임 상한 (3건/cycle)
- [x] 집계 알림 (8팀 동시 실패 시 단일 알림)
- [x] 대시보드 재위임 이력 표시
- [ ] bats-core 통합 테스트 (범위 외 — 기존 bash 테스트로 대체)
- [ ] heartbeat 통계 분석 (범위 외 — 별도 작업 필요)

## 세션 통계
- 총 도구 호출: 14회

### 수정 파일 목록
- /home/jay/workspace/scripts/session-watchdog.sh: 8회 (Edit)
- /home/jay/workspace/dashboard/server.py: 2회 (Edit)
- /home/jay/workspace/scripts/tests/test_session_watchdog.sh: 2회 (Edit)
- /home/jay/workspace/memory/reports/task-1715.1.md: 1회 (Write)
- /home/jay/workspace/memory/tasks/task-1715.1.md: 1회 (dispatch)

### 도구 사용 현황
- Edit: 12회
- Write: 1회
- dispatch: 1회