# Phase 5: 토큰 회계 통합 + 모니터링

## 태스크 ID: task-911.1
## 한정위임: 설계 → 구현 → 테스트 → 보고까지 완료

---

## 배경

- Phase 3 ✅ (task-906.1): auto_orch.py 코어 + health.json 초기 파일 구현 완료
- Phase 2 ✅ (task-903.1): token_ledger.py 기본 구현 완료 (DAILY_HARD_LIMIT, MAX_CONCURRENT, MAX_STARTS)

Phase 5는 토큰 사용량을 추적하고, 위험 수준 도달 시 경고를 발송하며, 운영 가시성을 확보하는 단계.

## 설계서 참조

- **통합 구현 계획서**: `memory/specs/automation-impl-plan.md` (Phase 5 섹션)
- **자동화 에이전트 설계서**: `memory/specs/automation-agent-spec.md`
- **Phase 3 보고서**: `memory/reports/task-906.1.md`
- **Phase 2 보고서**: `memory/reports/task-903.1.md`

## 구현 범위

### 1. `orchestrator/token_ledger.py` 확장 (~60 LOC 추가)

- `estimate_session_tokens(team_id, duration_seconds)`: task-timers.json에서 세션 시간 기반 토큰 추정
  - Opus 세션: ~5,000 tokens/분 (팀장 설계 모드)
  - Sonnet 세션: ~3,000 tokens/분 (팀원 코딩 모드)
  - 추정치이므로 보수적 계수 적용
- `get_daily_usage_summary()`: 당일 토큰 사용량 + 잔여 예산 반환
- `check_warning_threshold(threshold=0.8)`: 사용량이 DAILY_HARD_LIMIT의 threshold 비율 도달 시 True 반환

### 2. `orchestrator/auto_orch.py` 확장 (~40 LOC 추가)

- `cmd_status()` 확장: 토큰 사용량 정보 포함
  ```
  === 파이프라인 상태 ===
  marketing-dev: step-2-implement (running, dev1-team)

  === 토큰 사용량 ===
  오늘: 450,000 / 1,000,000 (45%)
  경고 임계값: 800,000 (80%)
  ```
- `scan` 모드에서 매 tick 시:
  - `health.json` 갱신 (활성 파이프라인, 토큰 사용량, 오류 수)
  - 토큰 80% 도달 시 Telegram 경고 발송 (requests.post 직접, 1일 1회 제한)

### 3. Telegram 경고 통합 (~30 LOC)

- 토큰 80% 도달 시 경고 메시지:
  ```
  ⚠️ 일일 토큰 사용량 80% 도달
  사용: 800,000 / 1,000,000
  잔여: 200,000 토큰
  활성 파이프라인: 2개
  ```
- 스텝 타임아웃 시 경고 (task-timers.json에서 STALE_TASK_RUNNING_SECONDS 초과)
- 경고 중복 방지: `orchestrator/state/alerts_sent.json`에 당일 전송 기록

### 4. `orchestrator/health.json` 확장

```json
{
  "last_tick": "2026-03-24T11:30:00",
  "active_pipelines": 1,
  "errors_last_hour": 0,
  "token_usage": {
    "today": 450000,
    "limit": 1000000,
    "percentage": 45.0
  },
  "version": "1.1"
}
```

## 수정 대상 파일

- `orchestrator/token_ledger.py` — 확장 (기존 코드 유지 + 함수 추가)
- `orchestrator/auto_orch.py` — cmd_status 확장 + scan 모드 경고 로직
- `orchestrator/tests/test_phase5.py` — 신규 테스트

## 수정 금지 파일 (충돌 방지)

- `orchestrator/event_bus.py` — Phase 4에서 수정 중 (2팀)
- `orchestrator/pipeline_validator.py` — 변경 불필요
- `scripts/` — 1팀 작업 중
- `dashboard/` — 8팀 작업 중

## 검증 기준

1. DAILY_HARD_LIMIT 80% 도달 시 Telegram 경고 발송 (mock 테스트)
2. health.json에 token_usage 포함 확인
3. cmd_status 출력에 토큰 사용량 포함
4. 경고 중복 방지 (같은 날 동일 경고 재발송 안 함)
5. task-timers.json 데이터와 token_ledger.json 정합성
6. pyright 0 에러, pytest 전건 통과 (Phase 2+3 회귀 포함)