incident-agent 실행 흐름

마지막 업데이트 2026-11-19

긴급 신고 감지 → 로그 수집 → 규칙 분류 → Claude 조사 → 본인 DM 승인. launchd가 10분마다 incident-agent tick을 실행합니다.

10분tick 주기 (launchd StartInterval 600)
1건 · 1단계tick 한 번에 진행하는 양
섀도 모드POST_TO_CS=true 일 때만 CS 게시
10건/일조사 상한 · 재조사 최대 2회

1. tick 한 번의 순서

0

잠금 · 일시정지 확인 매 tick

runs/.lock flock — 이전 tick 이 돌고 있으면 종료. 하드 정지면 아무것도 안 함. SSO 만료로 멈춰 있었으면 aws sts 성공 시 자동 재개.

1

게시 도중 중단 정리 매 tick

posting 으로 남은 건 → 게시 여부 불확실 → 재시도하지 않고 needs_human (중복 게시 방지).

2

watch — Slack 조회 매 tick

headless claude -p(haiku) + Slack 커넥터, 읽기 전용. @철수·@해리 언급 → 원 신고(부모) 수집, 승인 대기 DM 의 반응·답글 수집. 실패해도 대기열은 계속 진행.

3

신고 등록 (parse) 매 tick

헤더 · child_id · 상황 요약 파싱 → new 로 저장(원 신고 ts 가 키). 긴급 형식이 아니면 skipped. 저장이 끝난 뒤에만 커서 전진.

4

승인 처리 매 tick

✅ → 게시(posted) · ❌ → rejected · 답글 → 재조사(investigating).

5

병합 후 재수집 매 tick

22시 전에 받은 1차 분석(partial) 건은 22시 이후 로그를 다시 받아 fetching 부터 재진행.

6

신고 1건 한 단계 전진 1건만

진행 가능한 건 하나를 골라 현재 상태의 단계만 실행 (아래 상태 흐름). 산출물이 있으면 건너뛰는 멱등 단계.

7

리마인드 매 tick

승인 대기 48시간 초과 건에 한 번만 맥 알림.

2. 신고 1건의 상태 흐름

new신고 등록 fetching회기 선택 완료 classifying로그 수집 완료 investigating분류 완료 reporting조사 완료 select fetch classify investigate awaiting_approvalDM 발송 · 승인 대기 report (DM) posting게시 중 posted ✅ 승인 rejected ❌ 반려 답글 → 재조사 (최대 2회) 22시 이후 재수집 (partial) needs_human어느 단계든 3회 실패 · 입장 기록 없음 · 게시 불확실 실패 반복

3. 단계별로 하는 일

상태함수하는 일산출물
newdo_selectDynamoDB 에서 회차 · 회차+1 입장 시각 조회 → 신고 본문 날짜(11/18, 어제 등)와 맞는 회기 선택, 없으면 신고 직전 회기. 둘 다 기록 없으면 needs_humanlesson_index, run_date
fetchingdo_fetchppi-classify fetch 로 세션 로그 · socket · livekit 로그 다운로드, gzip 해제. 22시 전이면 partial 표시logs/.fetch.json
classifyingdo_classifyppi-classify run 규칙 분류(위치×유형 상위 3). 하루 상한 10건이면 다음 날로classify.json
investigatingdo_investigateclaude -p opus, 최대 60턴 · 30분. repro-path 절차로 원인 타임라인 조사report.md, result.json, usage.jsonl
reportingdo_report원인 한 줄 · 확신도 · 레벨 · 인과 체인을 본인 DM 으로 발송 + 맥 알림dm_ts

4. 신고 1건이 DM 까지 가는 시간

tick 1 · +0분new → fetching
tick 2 · +10분→ classifying
tick 3 · +20분→ investigating
tick 4 · +30분조사 실행 (수십 분) → reporting
tick 5 · 이후DM 발송 → awaiting_approval

정상 경로 기준 약 40분~1시간. 조사가 길면 그 사이 tick 은 잠금에 막혀 바로 끝납니다.

5. 격리 · 실패 처리

격리 · 안전장치

  • 조사: --restricted --strict-mcp-config — Bash · MCP 없음, 쓰기는 run_dir 안만
  • 읽기 허용: repro-path 스킬, 판별법 메모리, ppi-docs, ppi 코드
  • Slack 전송: PreToolUse 훅 slack_guard.py 가 채널 · 스레드 검사, 다르면 차단
  • 신고 원문 · 로그 본문은 데이터로만 취급 (지시로 따르지 않음), DM 에 원문 미포함
  • 단계마다 멱등 — 재시도해도 비용 반복 없음

실패 시

  • AWS SSO 만료 → 대기열 일시정지 + DM. 재로그인하면 다음 tick 에 자동 재개
  • Slack 채널 불일치 → 하드 정지. incident-agent resume 으로만 해제
  • 그 외 예외 → 해당 건만 실패 기록, 3회면 needs_human + DM
  • watch 실패 → 대기열은 계속, 3회 연속이면 맥 알림

관련 문서

재현 경로 파악 흐름 시각화 — 조사 단계(investigating)가 따르는 repro-path 절차

재현 경로 파악 에이전트 설계 — repro-path 에이전트 구조

소스: Dobraindev/ppi-incident-agent (47188ac 기준) · src/incident_agent/tick.py, steps.py, state.py