# 세션 복원력 시스템 (Session Resilience System)

## 배경
봇 세션이 컨텍스트 윈도우 한도에 도달하면 작업 중 세션이 터짐 (실제 사례: task-1091.1).
기존 인프라 조각은 있지만 엮는 오케스트레이션이 없음.

### 기존 인프라 (활용해야 할 것)
- `utils/context_compressor.py` — 5단계 컨텍스트 압축 (128K 한도, 50% 트리거)
- `utils/context_summarizer.py` — 규칙 기반 세션 요약 (LLM 비용 0)
- `utils/session_store.py` — SQLite WAL 세션 저장소
- `utils/checkpoint.py` — 타임스탬프 백업
- `memory/token-ledger.json` — 태스크별 토큰 기록
- `dispatch.py` — session_id 파라미터 지원

## 요구사항

### 핵심 목표
**"세션이 터지기 전에 자동으로 요약 → 새 세션 시작 → 요약 자동 인식"**

### 구현 범위

#### 1. 세션 모니터 (`utils/session_monitor.py`)
봇 세션의 토큰 사용량을 실시간 추적:
- Anthropic API 응답의 `usage` 필드에서 토큰 수 추출
- 누적 토큰 카운터 유지 (input_tokens + output_tokens)
- **WARNING 임계값**: 총 컨텍스트의 70% 도달 시 경고 로그
- **CRITICAL 임계값**: 총 컨텍스트의 85% 도달 시 자동 압축/요약 트리거
- 임계값은 설정 가능하게 (기본: 70%/85%)
- `get_usage_status()` → `{"total_tokens": N, "limit": 200000, "usage_pct": 75, "level": "warning"}`

#### 2. 자동 압축 훅 (`utils/session_auto_compress.py`)
세션 모니터가 CRITICAL 감지 시 자동 실행:
1. `context_compressor.compress(messages)` 호출
2. 압축된 메시지로 세션 히스토리 교체
3. 토큰 카운터 리셋 (압축 후 실제 토큰 수로)
4. 이벤트 로그: `memory/events/session-compressed-{timestamp}.json`

#### 3. 세션 요약 + 재시작 프로토콜
CRITICAL 도달 + 압축으로도 부족 시 (90% 초과):
1. `context_summarizer.generate_summary()` 로 현재 세션 전체 요약
2. 요약을 파일로 저장: `memory/sessions/summary-{task_id}-{timestamp}.md`
3. 요약 내용:
   - 작업 ID, 팀, 현재 진행 상황
   - 수정한 파일 목록
   - 남은 작업 (체크리스트)
   - 마지막으로 성공한 단계
   - 실패/에러 있었으면 그 내용
4. `dispatch.py`에 `--resume-from <summary_path>` 옵션 추가
5. 새 세션 프롬프트에 요약 자동 주입: "이전 세션 요약을 읽고 이어서 작업하세요"

#### 4. DIRECT-WORKFLOW.md 통합
팀 워크플로우에 세션 모니터 통합:
- 워크플로우 시작 시 세션 모니터 초기화
- 주요 단계(파일 읽기/편집/테스트) 전후 토큰 체크
- WARNING 시: 불필요한 파일 읽기 자제, 출력 간결화
- CRITICAL 시: 현재 진행 상황 저장 → 요약 생성 → 보고서에 "세션 한도 도달, 재시작 필요" 명시

#### 5. 아누 대시보드 연동
아누가 팀 세션 상태를 조회할 수 있도록:
- `python3 utils/session_monitor.py --status` → 현재 활성 세션들의 토큰 사용률 출력
- whisper-briefing에 세션 사용률 추가 (80%+ 팀만 표시)

## 설계 원칙
- **기존 코드 최대 활용**: context_compressor, context_summarizer, session_store 이미 있음. 새로 만들지 말고 import해서 씀.
- **비침투적**: 기존 봇 워크플로우를 깨지 않음. 모니터는 옵트인 방식.
- **점진적 적용**: 먼저 utils/ 모듈만 만들고, DIRECT-WORKFLOW 통합은 별도 Phase.
- **비용 최소**: 세션 요약은 LLM 없는 규칙 기반 (context_summarizer.py 활용)

## Phase 분리

### Phase 1 (이번 위임)
1. `utils/session_monitor.py` 구현 + 테스트
2. `utils/session_auto_compress.py` 구현 + 테스트
3. 세션 요약 + 재시작 파일 저장 로직
4. `dispatch.py`에 `--resume-from` 옵션 추가
5. CLI 상태 조회: `python3 utils/session_monitor.py --status`

### Phase 2 (별도 위임)
- DIRECT-WORKFLOW.md 통합
- whisper-briefing 연동
- 실제 봇 세션에 적용 + 테스트

## 검증
1. session_monitor.py: 토큰 카운팅 정확성, WARNING/CRITICAL 임계값 트리거 테스트
2. session_auto_compress.py: 압축 후 토큰 감소 확인, 메시지 무결성 보존 테스트
3. 세션 요약: 요약 파일 생성, 필수 필드(작업ID/진행상황/남은작업) 포함 확인
4. dispatch.py --resume-from: 요약 파일 로드 + 프롬프트 주입 테스트
5. 기존 150개 autoresearch 테스트 영향 없음 확인
6. pyright 에러 0건

## 참조
- 사고 사례: task-1091.1 (5팀, 컨텍스트 윈도우 소진으로 세션 사망)
- 기존 인프라: utils/context_compressor.py, utils/context_summarizer.py, utils/session_store.py
- 토큰 한도: Claude Max 200 = 세션당 ~200K 토큰 컨텍스트 윈도우