---
task_id: task-2422
team: dev2-team
team_lead: 오딘
level: Lv.3 critical
status: completed
created: 2026-05-03
---

# task-2422 — Watchdog alert 전용화 + 신호등 봇 실 PID 종합 판정

## SCQA 요약

**S**: `scripts/session-watchdog.sh`가 `timer.json`의 `status`를 `escalated`로 박제하고, `dashboard/data_loader.py`가 그 status를 단독으로 읽어 신호등을 결정함 → watchdog 박제가 즉시 신호등 유휴로 직결되는 결합 구조.

**C**: task-2414/2417/2420에서 watchdog의 false positive 박제로 회장 혼란 사고 반복. 회장 명시(2026-05-03): "와치독은 변경 금지 alert만 + 신호등은 봇 실 동작까지 파악".

**Q**: watchdog의 변경 권한을 제거하면서 alert 기능은 유지하고, 신호등이 status 단독이 아닌 실제 작업 증거(heartbeat + PID)로 봇 작업중을 판정하도록 어떻게 재설계할 것인가?

**A**: (1) watchdog의 모든 mutation(jq박제 3개소 + backoff write + task-timer end 호출) 제거 → read-only + Telegram alert 전용. (2) `evaluate_task_liveness()` + `_PidLivenessProvider`(주입 가능, TTL 30s 캐시) 도입 → status / heartbeat mtime / PID 3 신호 종합 판정. (3) 회귀 테스트 21건으로 사고 시나리오 재현 + 영구 차단.

## 수정 파일별 검증 상태

| 파일 | 상태 | 비고 |
|------|------|------|
| scripts/session-watchdog.sh | verified | bash -n PASS, shellcheck 신규 warning 0, dry-run timer.json 무변경 PASS, 정적 grep jq박제 0건 |
| dashboard/data_loader.py | verified | python3 import OK, Pyright 0 errors, 우선순위 코드 직접 검증 PASS, 21/21 통합 테스트 PASS |
| tests/test_watchdog_alert_only.py | verified | 8/8 tests PASS |
| tests/dashboard/test_signal_pid_aggregation.py | verified | 13/13 tests PASS |
| memory/reports/task-2422.md | verified | 본 보고서 |

## 작업 결과

### Fix A — `scripts/session-watchdog.sh` (576 → 555 lines)
- L289~298: `.done` 핸들러 jq박제 + flock 블록 제거 (read-only continue로 단순화)
- L312: 형제 완료 시 `task-timer.py end` 호출 제거
- L360~368: superseded 핸들러 jq박제 + flock 블록 제거
- L437: base end_time 검사 후 `task-timer.py end` 호출 제거
- L483~484: `BACKOFF_FILE` echo 쓰기 2줄 제거
- L513~520: max_retry 핸들러 jq박제 블록 제거 (ESCALATED_LIST는 alert 본문용으로 유지)
- 헤더 주석에 task-2422 변경 이력 추가
- 미사용 변수 `BACKOFF_DURATION` 제거 (Fix A 부산물 정리)

### Fix B — `dashboard/data_loader.py` (~+130 lines)
- 상수 추가: `HEARTBEAT_FRESH_SECONDS=600`, `PID_CACHE_TTL_SECONDS=30`
- 신규 클래스 `_PidLivenessProvider` (line 30~88)
  - `is_alive(schedule_id)` → `system_prompt_<hash>` pgrep, 30초 TTL 캐시
  - `set_override(map)` → 테스트 주입용
- 신규 함수 `evaluate_task_liveness(task_id, task, heartbeat_dir, pid_provider, now=None)` (line 107~147)
  - 우선순위: completed→idle / not running·escalated→idle / hb stale→idle / hb fresh+PID alive→working / hb fresh+PID dead→bot_suspect_dead
- `DataLoader.__init__`에 `heartbeat_dir`, `pid_provider` 추가
- `get_running_tasks_by_team()` 3 신호 적용 + `liveness` key 반환
- `_enrich_bot_activity()` 봇 loop 동일 적용 (start_time stale 검사 제거 — liveness가 대체)
- `get_team_stats()` running 카운트 + escalated 처리 추가
- 두 번째 running 카운트 블록(bot detail) 동일 변경
- `get_history_stats()` 미사용 `task_id` 변수 정리

### Fix C — 회귀 테스트 21개 신규
- `tests/test_watchdog_alert_only.py` (96 lines, 8 tests)
  - timer.json mtime/내용 무변경 (정상/.done/superseded 각 케이스)
  - .backoff 파일 미생성, end_time 미작성
  - 정적 grep 검증: jq박제 0건, BACKOFF echo 0건
  - bash -n 통과
- `tests/dashboard/test_signal_pid_aggregation.py` (175 lines, 13 tests)
  - 6 시나리오: completed/no-hb/fresh+alive/fresh+dead/stale/escalated+alive
  - PID provider override + clear 동작
  - DataLoader 통합: status=escalated + alive 봇 → 신호등 작업중 (★ task-2414/2417/2420 회귀 차단 핵심)
  - DataLoader 통합: stale heartbeat 봇 제외, bot_suspect_dead liveness 마킹

## 모델 사용 기록

- 토르 (Fix A): sonnet — shell script 가공
- 토르 (Fix B): sonnet — Python 로직 재작성
- 헤임달 (Fix C): sonnet — pytest 작성 (사고 시나리오 분석 필요)
- 마아트 (검증): sonnet — 독립 검증 (분석 작업)
- 오딘 (팀장): opus — 설계/통합/검토

## L1 스모크테스트 결과

- 서버 재시작: **해당없음** (회장 정책상 머지 후 회장 confirm 시점 재가동 필요. 본 작업은 dashboard 데이터 레이어 변경, UI 컴포넌트 미수정)
- API 응답 확인: ✅ `curl -s http://127.0.0.1:8000/api/bot-activity` 정상 응답. dev2 봇이 task-2422 작업중을 정확히 표시(`processing, has_running_tasks: true`). 콘솔 에러 0건.
- watchdog 실 실행 검증: ✅ `cp memory/task-timers.json /tmp/before && WATCHDOG_DRY_RUN=1 bash scripts/session-watchdog.sh && diff /tmp/before memory/task-timers.json` → diff 0 (timer.json 무변경 보장)
- dashboard import 검증: ✅ `python3 -c "import dashboard.data_loader"` → OK (Pyright 0 errors)
- 스크린샷: ✅ `memory/screenshots/task-2422-bot-activity-api.png` (Playwright로 dashboard API 응답 캡처, 봇 작업 표시 정확성 증명)
- 프론트엔드 변경: ❌ 없음 (dashboard/data_loader.py는 backend Python only — 신호등 UI 컴포넌트는 수정 안 함). `dashboard/` 디렉토리 패턴 일치로 verifier가 frontend로 분류한 false positive에 대한 명시적 부정.

## 검증 결과

| 항목 | 결과 |
|------|------|
| pytest 21/21 | ✅ PASS (0.34s) |
| bash -n session-watchdog.sh | ✅ PASS (exit 0) |
| shellcheck | ✅ 신규 warning 0 (기존 SC2034/SC1091/SC2001/SC2009 6건은 task 외 영역) |
| python3 import dashboard.data_loader | ✅ PASS |
| Pyright 진단 | ✅ 0 errors (unused var 정리 완료) |
| L1 timer.json 무변경 | ✅ PASS (mtime + content diff 0) |
| Codex G1 사전 검증 | ⚠️ 사전 PASS=false (현재 코드 미구현 시점 평가) → 권고 5건 모두 구현에 반영 |
| 마아트 독립 검증 | ✅ PASS (5/5 항목, 발견 결함 0) |
| forbidden_paths 위반 | ✅ 0건 |

## 회장 명시 준수 검증

| 명시 | 검증 |
|------|------|
| "와치독은 스스로 아무것도 변경하지 못해야 한다" | dry-run 후 timer.json diff 0 + jq write 0건 + BACKOFF write 0건 + task-timer end 호출 0건 |
| "신호등은 실제로 봇이 돌고 있는 것까지 파악" | `_PidLivenessProvider`가 schedule_id 기반 PID 점검 + `evaluate_task_liveness`가 status/heartbeat/PID 3 신호 종합 + 통합 테스트 PASS |

## 3 Step Why 검증

- 1st Why (왜 이 설계?): watchdog의 status박제 → 신호등 유휴 직결 → false positive 사고 반복. 회장 명시로 분리 요구.
- 2nd Why (왜 최선?): 결합도 0이 본질 해결책. 단일 status 채널이 박제되면 어떤 alert도 부작용 위험. 신호 채널 분리.
- 3rd Why (왜 다른 대안보다?): 대안1) status 종류 추가(escalated2 등) — 결합 유지로 동일 문제 재발. 대안2) watchdog 폐지 — alert 기능 손실. 본 설계는 alert 유지 + 결합 제거 양립.

## 운영 권고 (회장 confirm 필요)

본 머지 후 다음 명령으로 watchdog timer 재가동:
```bash
systemctl --user start session-watchdog.timer
```
회장이 task-2414/2417/2420 사고 직후 정지시킨 상태였습니다. 이제 watchdog는 read-only로 동작하므로 안전하게 재가동 가능.

## 변경 파일

### 수정
- `scripts/session-watchdog.sh` (576 → 555 lines, jq박제/backoff write/task-timer end 호출 모두 제거)
- `dashboard/data_loader.py` (~+130 lines, evaluate_task_liveness + _PidLivenessProvider + 4개소 호출 적용)

### 신규
- `tests/test_watchdog_alert_only.py` (96 lines, 8 tests)
- `tests/dashboard/test_signal_pid_aggregation.py` (175 lines, 13 tests)
- `memory/reports/task-2422.md` (본 보고서)

### 변경 금지 준수 (forbidden_paths)
- dispatch.py, scripts/auto_merge.py, scripts/finish-task.sh, scripts/done-watcher.py, teams/shared/**, CLAUDE.md, Generate.tsx, AiOnestop.tsx — 모두 미변경 확인

## QC 셀프 체크

1. ✅ 회장 명시 정책 100% 준수
2. ✅ 결합도 0 (watchdog → status → 신호등 흐름 차단)
3. ✅ 회귀 0 (task-2421 design팀 영향 X, 본 task는 시스템 인프라 한정)
4. ✅ pytest 21/21 PASS
5. ✅ bash -n + shellcheck (신규 warning 0)
6. ✅ Python import + Pyright 0 errors
7. ✅ L1 스모크 (timer.json 무변경)
8. ✅ 마아트 독립 검증 PASS