[chowon442]

📌 관련 이슈

• Closes [Feat] 내부 단절·stale 실행과 deadline의 bounded 결과 회수 [1.85] #225

🏷️ PR 타입

• ✨ 기능 추가 (Feature)
• 🐛 버그 수정 (Bug Fix)
• ♻️ 리팩토링 (Refactoring)
• 📝 문서 수정 (Documentation)
• 🎨 스타일 변경 (Style)
• ✅ 테스트 추가 (Test)

📝 작업 내용

Task 1.85 — 내부 단절·Server 재시작·stale heartbeat·deadline에서 저장 결과를 한 번만 회수하거나 실행 소실을 bounded 실패로 수습한다. 대상 브랜치 feat/s07-run-coordination.

• stale 회수 (RunCoordinator.recoverStale, recovery.interval): leader만, RUNNING|RETRYING + attempt >= 1 + lease 만료 + deadline 전 + isExecuting=false인 run을 같은 attempt·fence로 조건부 인수(RunClaimStore.takeOver, 동시 인수는 하나만 이김). 인수 worker도 로컬 permit을 잡는다. CANCELING은 고르지 않는다(1.84 소유).
• status 우선 수습 (RunExecution RECOVER): terminal → 1.82 settle(StoredTerminal)(새 stream·provider 실행 없음, snapshot 복원 없음, 대조값 ai_runs.request_fingerprint) / 같은 epoch executing → 같은 요청으로 OBSERVE / canceling·run.canceled·다른 epoch → OBSOLETE / fingerprint 불일치 → INTERNAL_ERROR.
• 미시작 vs 실행 소실: Brain record는 Postgres 영속이라 absent = 등록된 적 없음. 단 이 worker가 frame을 받았거나 이 attempt의 Brain source event가 저장돼 있으면 실행 소실 → 재전송 없이 failByServer(PROVIDER_ERROR)(1.82가 한 번 보상). 1.83 worker status 수습에도 같은 규칙을 적용했다(frame을 받은 뒤의 absent에 같은 요청을 보내면 새 graph가 START됐다).
• 누적 한도: 재전달 한도는 run 행 retry_count부터 이어서 센다. 인수 횟수는 V5 ai_runs.recovery_count(단조 trigger)로 누적, max-recoveries(3) 초과 인수는 FINAL_CHECK(status 한 번으로 저장 terminal만 회수, 아니면 실패). deadline·max-status-checks는 기존대로.
• 관측: recoveries{result}·recoveries.finished{result}(permit 반환)·execution_lost, 로그는 runId·attempt·mode·state·reason만.
• 문서: docs/contracts/run-coordinator.md "stale 회수" 절(결정표·한도·경합·1.87/S13 인계).

📸 스크린샷

로컬(격리 Postgres postgres-t185:25432 tmpfs, eclipse-temurin:21-jdk 컨테이너, flock):

• ./gradlew test --tests 'com.proovy.domain.run.coordinator.*' — RunRecoveryPostgresTest 11, RunCoordinatorPostgresTest 15, Properties 6, WorkerPool 1: 33 통과, skip 0
• ./gradlew test --tests 'com.proovy.db.*' --tests 'com.proovy.domain.run.terminal.*' — 통과(skip 0, V5 migration 포함)
• 전체 ./gradlew test는 CI 결과로 확인

✅ 체크리스트

• 코드 리뷰를 받을 준비가 완료되었습니다
• 테스트를 작성하고 모두 통과했습니다
• 문서를 업데이트했습니다 (필요한 경우)
• 코드 스타일 가이드를 준수했습니다
• 셀프 리뷰를 완료했습니다

📎 기타 참고사항

fault injection (실제 Postgres + 실제 BrainRunClient + loopback 가짜 Brain): Server 재시작(stop()→Brain 상태 주입→start()) 뒤 저장 terminal 회수(delivery 1, 완료·보상 1회) / Brain 실행 중 재부착(같은 attempt·fence·deadline) / terminal 저장 전 소실(absent+저장 activity → 재전송 없이 실패·보상 1회) / 보내기 전 사라진 이전 프로세스(absent·증거 없음 → 첫 START 1회) / status 500 유실 뒤 회수 / 조회 한도 소진(실패·보상 1회, 재전송 없음) / 인수 한도 초과(FINAL_CHECK, OBSERVE 없음) / 동시 인수 6개 중 1개 승리·CANCELING·살아 있는 lease·비leader 인수 거부 / deadline 지난 stale은 sweep timeout(조회 0) / heartbeat만 늦은 로컬 worker는 인수 안 함 / recovery_count 단조.

후속 계약 메모

• migration V5 점유(V5__run_recovery_count.sql, 추가형). 1.84가 V5를 쓰면 뒤 merge가 재번호.
• 1.83 테스트 조정: 만료 lease 고아 run은 이제 회수되므로 슬롯 테스트는 다른 인스턴스의 살아 있는 lease로 바꿨고, "absent → 재전송" 테스트는 frame 없는 단절(Step.DROP)로 바꿨다(frame 뒤 absent는 실행 소실).
• RunTerminalService·BrowserRunController·cancel 경로는 바꾸지 않았다. coordinator 공개 hook 시그니처 불변.
• FINAL_CHECK가 executing 상태에서 실패시킨 run은 Brain record가 executing으로 남을 수 있다 → S13 cleanup·Brain lease sweep과 함께.
• 미검증(S14): 실제 Brain crash 뒤 Brain status 응답, Cloud Run SIGTERM·다중 인스턴스 인수 실측, 회수 주기·한도 수치.
• 로컬 환경 메모: 호스트 디스크가 가득 차(여유 ~6MB, 공용 이미지·볼륨) Postgres를 tmpfs로 띄웠다. 다른 세션 자원은 지우지 않았다.

🤖 Generated with Claude Code