KjyUdZddlmZddlmZddlmZddlmZm Z m Z ddl m Z m Z mZmZmZmZmZddlmZmZmZmZmZmZmZdZd ed <d Zd ed <d Zd ed<eeeehZ ded<dZ!d ed<dZ"d ed<dZ#d ed<dZ$d ed<ee!e"e#e$hZ%ded<dZ&d ed<dZ'd ed<dZ(d ed<d Z)d ed!<d"Z*d ed#<d$Z+d ed%<d&Z,d ed'<d(Z-d ed)<d*Z.d+ed,<d-Z/d+ed.<d/Z0d ed0<d1Z1d ed2<Gd3d4e2Z3 dDd5Z4ed67Gd8d9Z5ed67Gd:d;Z6ed67Gd<d=Z7ed67Gd>d?Z8Gd@dAZ9gdBZ:yC)Eu utils.ci_watch_handoff_runner — task-2642 CI_WATCH_HANDOFF state machine. 회장 verbatim (2026-05-23 19:38 KST) 1:1 박제: 'ANU 는 CI/Gemini 를 직접 기다리지 않는다. PR open 이후 대기/감시/자동수렴은 반드시 bot 또는 watcher task 에 위임한다.' 본 runner 책임 (spec §4 state machine): PR_OPEN (handoff received) ↓ poll loop · interval=poll_interval_seconds · timeout=max_watch_minutes ├─ CI 미완료 (PENDING) → polling continue ├─ CI FAIL 자동수렴 가능 → AUTO_REMEDIATE → re-push → re-poll ├─ CI FAIL 자동수렴 불가 → CI_FAILED_NON_REMEDIABLE ├─ forbidden_path 수정 감지 → CHAIR_REQUIRED (Critical7) └─ CI PASS → router 호출 (Gemini freshness) ├─ FRESH → MERGE_READY ├─ NUDGE_POSTED → polling continue (fresh review 대기) ├─ NUDGE_DEDUPED → polling continue (직전 nudge active) ├─ GEMINI_EXTERNAL_TRIGGER_STALE → terminal 동명 enum ├─ NUDGE_PERMISSION_DENIED / │ CHAIR_UI_FALLBACK_REQUIRED / │ NUDGE_FAILED / │ NOT_GEMINI_TRIGGER → CHAIR_REQUIRED (NUDGE_403 / permission) ↓ TERMINAL_REACHED → CALLBACK_FIRE (envelope UTF-8 ≤3900 bytes) ↓ WATCHER_EXIT PR #144 OWNER_GEMINI_TRIGGER_ROUTER stack 재사용 (gemini_router_call_fn 으로 inject). forbidden 15종 + owner_trigger 4종 + owner_gemini_trigger_router 3종 무수정. one-way isolation: utils/ 외부 import 0 (PR #144 router 는 caller 가 inject). live cokacdir / gh CLI / merge / push 호출 0 (regression mock 가능). frozen anchor: ANCHOR-1: state machine 1 차 — handoff 정규화 후 poll loop 진입 ANCHOR-2: router final_state 8종 → terminal_states 5종 매핑 (CHAIR_UI_FALLBACK / NUDGE_PERMISSION_DENIED / NUDGE_FAILED / NOT_GEMINI_TRIGGER → CHAIR_REQUIRED) ANCHOR-3: auto_remediation_fn 반환 enum 4종 (APPLIED / NON_REMEDIABLE / FORBIDDEN_HIT / LOOP_BOUNDARY) → terminal classification ANCHOR-4: callback envelope UTF-8 ≤3900 bytes hard limit (task-2612+3 박제) — 초과 시 RunnerContractError fail-closed ANCHOR-5: handoff.terminal_states subset 외부의 분류는 CHAIR_REQUIRED 로 escalate ANCHOR-6: real auto-merge 0 / push 0 / PR open 0 / live cokacdir 0 — caller 가 inject 한 callable 만 호출 ) annotations) dataclass)Path)AnyCallableFinal)CiWatchHandoffAuditEVENT_AUTO_REMEDIATEEVENT_CALLBACK_FIREDEVENT_HANDOFF_RECEIVEDEVENT_OWNER_NUDGEEVENT_POLL_TICKEVENT_TERMINAL_REACHED)ALL_TERMINAL_STATESTERMINAL_CHAIR_REQUIRED!TERMINAL_CI_FAILED_NON_REMEDIABLE&TERMINAL_GEMINI_EXTERNAL_TRIGGER_STALETERMINAL_LOOP_BOUNDARYTERMINAL_MERGE_READYvalidate_handoffPENDINGz Final[str]CI_STATUS_PENDINGPASSCI_STATUS_PASSFAILCI_STATUS_FAILzFinal[frozenset[str]]ALL_CI_STATUSESAPPLIEDREMEDIATE_APPLIEDNON_REMEDIABLEREMEDIATE_NON_REMEDIABLE FORBIDDEN_HITREMEDIATE_FORBIDDEN_HIT LOOP_BOUNDARYREMEDIATE_LOOP_BOUNDARYALL_REMEDIATE_OUTCOMESFRESH ROUTER_FRESH NUDGE_POSTEDROUTER_NUDGE_POSTED NUDGE_DEDUPEDROUTER_NUDGE_DEDUPEDGEMINI_EXTERNAL_TRIGGER_STALE ROUTER_STALECHAIR_UI_FALLBACK_REQUIREDROUTER_CHAIR_UI_FALLBACKNUDGE_PERMISSION_DENIEDROUTER_NUDGE_PERMISSION_DENIED NUDGE_FAILEDROUTER_NUDGE_FAILEDNOT_GEMINI_TRIGGERROUTER_NOT_GEMINI_TRIGGERz Final[int]DEFAULT_LOOP_BOUNDARY_ATTEMPTSi<CALLBACK_ENVELOPE_BYTE_LIMITc119085addb0f8b7ANU_COLLECTOR_KEYz/home/jay/workspaceCANONICAL_ROOTceZdZdZy)RunnerContractErroru2runner 입력 / inject callable / envelope 위반.N)__name__ __module__ __qualname____doc__4/home/jay/workspace/utils/ci_watch_handoff_runner.pyr>r>wsctS)u=fallback auto_remediation_fn — 항상 NON_REMEDIABLE (회장 verbatim §8 보호). caller 가 explicit 하게 auto_remediation_fn 을 inject 하지 않으면 watcher 는 어떤 자동수렴도 하지 않고 CI_FAILED_NON_REMEDIABLE 로 분류 (회장 verbatim §8 watcher 책임 명시화 보호). )r!)_handoff_ci_snaps rE_default_no_op_remediationrI{s  $#rDT)frozenc8eZdZUdZded<dZded<dZded<y ) RouterCallResultu?gemini_router_call_fn 반환 (PR #144 RouterResult 의 subset).str final_stateFboolpermission_diagnostics_presentreasonN)r?r@rArB__annotations__rPrRrCrDrErLrLs I+0"D0FCrDrLcTeZdZUdZded<dZded<dZded<d Zd ed <d Zd ed <y )CIStatusSnapshotuIci_status_fn 반환 — caller 가 한 poll tick 의 CI 상태를 집약.rMstatusrCztuple[str, ...]failing_checksrQseverityFrOforbidden_path_touchedsame_function_high_repeatedN) r?r@rArBrSrWrXrYrZrCrDrErUrUs4S K&(NO(Hc#(D((--rDrUc^eZdZUdZded<ded<dZded<dZded<d Zd ed <d Zd ed <y) TerminalDecisionu3terminal state 분류 결과 + 진단 컨텍스트.rMterminal_staterRN str | Nonerouter_final_state ci_statusrintauto_remediation_attemptsloop_iterations) r?r@rArBrSr_r`rbrcrCrDrEr\r\s:= K%) ) Iz %&s&OSrDr\c0eZdZUdZded<ded<ded<y) RunResultuGrunner.run() 의 최종 반환 — terminal decision + callback 결과.r\decisionrOcallback_firedracallback_prompt_bytesN)r?r@rArBrSrCrDrEreresQrDreceZdZdZdddddded d dZddd ddZedd Zedd Z dd Z e dd Z y)CiWatchHandoffRunneruCI_WATCH_HANDOFF state machine 단일 진입점 (spec §4). side-effect 추상화 (test injection 가능): - ``ci_status_fn``: ``Callable[[dict], CIStatusSnapshot]`` — 한 poll tick 에서 caller 가 CI 상태를 회수해서 반환. regression 은 sequence 형태로 호출되어 PENDING → PASS / FAIL 등을 차례대로 반환. - ``gemini_router_call_fn``: ``Callable[[dict], RouterCallResult]`` — PR #144 OWNER_GEMINI_TRIGGER_ROUTER stack 호출 wrapper (재사용만). 본 runner 는 router 자체를 import 하지 않고 wrapper 시그니처로 inject. - ``auto_remediation_fn``: ``Callable[[dict, CIStatusSnapshot], str]`` — expected_files 내부 medium/style/quality/non-critical HIGH 자동수렴. 반환은 REMEDIATE_* enum. dev bot 위임 (ANU 직접 코드 0). - ``callback_send_fn``: ``Callable[[str], int]`` — envelope text 를 받아 실제 cokacdir --cron 호출 (또는 mock). 반환 무관 (audit 는 byte 수만 기록). runner 자체는 sleep 0 / live shell 0. cadence 는 caller 가 흉내내고 본 클래스는 state classification 만 책임. 회귀는 ci_status_fn 을 generator 스타일로 시퀀스 반환하도록 만들어 검증. N<) ci_status_fngemini_router_call_fnauto_remediation_fncallback_send_fnaudit max_pollsloop_boundary_attemptsc| td| tdt|tr|dkr tdt|tr|dkr tdt|j |_||_||_|xst|_ ||_ ||nt|j |_ ||_ ||_y)Nz&ci_status_fn callable must be injectedz]gemini_router_call_fn callable must be injected (PR #144 OWNER_GEMINI_TRIGGER_ROUTER wrapper)rzmax_polls must be positive intz+loop_boundary_attempts must be positive int)r> isinstancerarresolve_workspace_root _ci_status_fn_gemini_router_call_fnrI_auto_remediation_fn_callback_send_fnr _audit _max_polls_loop_boundary_attempts) selfworkspace_rootrlrmrnrorprqrrs rE__init__zCiWatchHandoffRunner.__init__s  %&NO O (%@ )S)Y!^%&FG G137%*%&ST T#N3;;=)&;#$7$U;U!!1&E,?@T@T,U $'=$rDrQ)task_idwatcher_schedule_idc t|}|d}|d}|d}t|d}t|d} |jj |||||xsdt d|d|d |d d d } d } t |jD]} | d z} |j|} t| ts!tdt| j| jtvr(td| jdt!t|jj |||||xsdt"| j| d| d| jd| j$xsdd| j&d | j&r5|j)t+t,d| j| | ||||| cS| jt.k(r@| jt0k(r| j2rU| |j4k\rF|j)t+t6d| d|j4d| j| | ||||| cS|j9|| }|t:vrtd|dt!t:| d z } |jj |||||xsdt<| j| | d|d| j$xsdd d! |t>k(rJ|t@k(r5|j)t+t,d"| j| | ||||| cS|tBk(r5|j)t+t6d#| j| | ||||| cS|j)t+tDd$| j$d%tG| jHd&| j| | ||||| cS|jK|}t|tLs!td't|j|jj |||||xsdtN|jP| j| d(|jPd)|jRd*|jTd+ |jW|jP}|U|jPtXk(r@|j)t+tZd,|jP| j| | -||||| cS<|j)t+||j]|jP|jP| j| | -||||| cS|j)t+t,d.|jd/| | 0||||| S)1uIstate machine 한 번 실행. terminal decision + callback 결과 반환. pr_numberhead_sha watcher_ownerterminal_statescallback_on_terminal_staterQzPR #z! handoff received; watcher_owner=z ; branch=branch)rrrrreventrRrz/ci_status_fn must return CIStatusSnapshot, got z%ci_status_fn returned invalid status z ; allowed=z poll tick z: CI=z ; severity=n/az; forbidden_touched=) rrrrrrr`rcrRuPforbidden_paths 수정 감지 — Critical7 (spec §3.2 / 회장 verbatim §3.2))r]rRr`rbrc)rfhandoffrrterminal_subsetcallback_on_terminalzauto_remediation attempts=z >= u; + same-function HIGH 반복 — LOOP_BOUNDARY (spec §3.5)z-auto_remediation_fn returned invalid outcome zauto_remediation outcome=z (severity=)) rrrrrrr`rbrcrRuTauto_remediation refused — forbidden_paths hit / Critical7 escalation (spec §3.2)uRauto_remediation declared LOOP_BOUNDARY (same-function HIGH 반복) — spec §3.5u'CI failure non-remediable — severity=z failing_checks=u (spec §3.4)z8gemini_router_call_fn must return RouterCallResult, got u router → z ; perm_diag=z; ) rrrrrrr_r`rcrRuJCI PASS + Gemini fresh + 0 unresolved + CLEAN — MERGE_READY (spec §3.1)r]rRr_r`rbrcz max_polls (uG) 도달 — terminal 미분류 (max_watch_minutes hard timeout 정합))r]rRrbrc)/rsetrOr{appendr ranger|rwrtrUr>typer?rVrsortedrrXrY _finalizer\rrrrZr}rryr&r rr#r%rlistrWrxrLr rNrPrR_map_router_stater(r_terminal_reason_for_router)r~rrr normalizedprheadrrrrbrctickci_snapoutcome router_resultmappeds rErunzCiWatchHandoffRunner.runs~&g.  $*%"?3 j):;<#J/K$LM " !.':'@b/2$? O(235  %&!$//*m D"QhO((4Gg'78)EG}--.0~~_4);GNN;MN%o679 KK  &!# $%2+>+D",!('6$_$5U7>>:JK$$+$4$4$=#>?--4-K-K,LN &--~~-'>C#*..2K(7 '#(;$3)=&$~~!22~~/771T5Q5QQ>>!1+A"<#<"=T#'#?#?"@AM!M '.nn6O,; "!+ ',?(7-A#*(33JH"88-G"+Z7M0N/OQ*Q.) ""#*%'$()6/B/Hb!5%,^^5N+:7yA))0)9)9)BU(C1F$//55>>!1+B!F'.nn6O,; "!+ ',?(7-A*$55>>!1+A!M'.nn6O,; "!+ ',?(7-A*&~~-'H((/(8(8';<..273I3I.J-KL++ #*..2K(7 '#(;$3)=#&*!77 CMm-=>)NM*3346 KK  &!# $%2+>+D".*7*C*C!('6%m&?&?%@A%%2%Q%Q$RRT(//02 &++M,E,EFF~!,, <>>!1+?!?0=/H/H&-nn6O,; "!+ ',?(7-A!*&>>)#);;%11(5'@'@%nn.G$3 #$7 /%9" {m `~~%6!$//!23>>+D / 3+!5  rDc|tttfvry|tk(rtS|t t ttfvrtStS)urouter final_state → CI_WATCH_HANDOFF terminal_state 매핑. 반환 None 이면 polling continue 또는 MERGE_READY (caller 분기). N) r(r*r,r.rr0r2r4r6rstates rErz&CiWatchHandoffRunner._map_router_statesM \#68LM M L 9 9  $ *  %   + *&&rDc||tk(r y|tk(r y|tk(r y|tk(r y|tk(r yd|dS)NueOWNER nudge 1회 hard limit 후 fresh review 미도착 — GEMINI_EXTERNAL_TRIGGER_STALE (spec §3.3)urouter NUDGE_PERMISSION_DENIED (403 X-Accepted-* headers 기록) — CHAIR_REQUIRED (회장 verbatim §8 / NUDGE_403=permission)ugrouter CHAIR_UI_FALLBACK_REQUIRED — CHAIR_REQUIRED (회장 UI 최후수단 회피, 본 정책 §2.10)u_router NUDGE_FAILED (transient/unknown) — CHAIR_REQUIRED (자동 retry 회피, 회장 보고)u[router NOT_GEMINI_TRIGGER (PR Review 오인 차단 — task-2640 박제) — CHAIR_REQUIREDzunknown router state u! — CHAIR_REQUIRED (fail-closed))r.r2r0r4r6rs rErz0CiWatchHandoffRunner._terminal_reason_for_router$s| L =  2 2R  , ,E  ' '7  - -% 'ui/PQQrDc|jtvrtd|jd|j|vrWttd|jdt |d|j |j|j|j}|jj||d|d|d |xsd t|j|j |j|j|j|jd d }d }|r|j||||} t| j!d} | t"kDrtdt"d| d| }|j$|j%| d}|jj||d|d|d |xsd t&|j|d|dt"dd t)|||S)u:terminal 도달 audit + (옵션) callback envelope 발사.zterminal_state z not in enumzcomputed terminal=u$ 이 handoff terminal_states subset u. 외부 — CHAIR_REQUIRED escalate (ANCHOR-5)rrrrrQ) rrrrrrr]r_r`rbrcrRFr)rrfrrzutf-8zcallback envelope exceeds z bytes (u#) — task-2612+3 박제 hard limitTzANU normal callback fired (z bytes UTF-8 <= r) rrrrrrr]rhrR)rfrgrh)r]rr>r\rrr_r`rbrcr{rrrR_build_callback_envelopelenencoder9rzr re) r~rfrrrrrrgcallback_bytesenvelope byte_counts rErzCiWatchHandoffRunner._finalizeAs-  " "*= =%!("9"9!#>",,*2*L*L ( 8 8 H "$[1#J/!(!9':'@b/"*"9"9&.&A&A%//-5-O-O#+#;#;"//  " 44!$7 5H X__W56J88)01M0NO(\)LN(N%%1&&x0!N KK  &!(!5 ' 3%,_%=+>+D"1&.&=&=-;5n5EF:;1>  ")"0  rDc`|ddd}d|xsdd|dd|d |d d |d d |xsdd|jd|jxsdd|jxsdd|jd|jdt dt d|jg }dj|S)u#ANU normal callback envelope (spec §4.3). envelope 5축 + canonical_root + terminal_state + watcher_owner + schedule_id 명시. UTF-8 ≤3900 bytes hard limit (caller wc -c 검증). 상세 보고는 result.json / report.md 에 위임 (envelope 만 포함). rN z![CI_WATCH_HANDOFF_TERMINAL] task=rzpr=#rz head=zbranch=rzwatcher_owner=rzwatcher_schedule_id=rQzterminal_state=zrouter_final_state=z ci_status=zauto_remediation_attempts=zloop_iterations=zcanonical_root=zcollector_role=ANU owner_key=zreason= ) r]r_r`rbrcr<r;rRjoin)rrfrr head_prefixliness rErz-CiWatchHandoffRunner._build_callback_envelopes j)#2. /0@5/A B7;'({m <gh'( )W_56 7"#6#<""= >h556 7!("="="F!G H++4u5 6()K)K(L Mx778 9n- .+,=+> ?hoo& ' yyrD)rz str | Pathrlz)Callable[[dict], CIStatusSnapshot] | Nonermz)Callable[[dict], RouterCallResult] | Nonernz.Callable[[dict, CIStatusSnapshot], str] | NonerozCallable[[str], Any] | NonerpzCiWatchHandoffAudit | NonerqrarrrareturnNone)rdictrrMrr^rre)rrMrr^)rrMrrM)rfr\rrrrMrr^rrrrOrre) rrrfr\rrMrr^rrM) r?r@rArBr8rr staticmethodrrrrrCrDrErjrjs~0CGKONR8<,0&D$>#$>@ $> I $> L $>6$>*$>$>!$$> $>X*. ` `  ` ( `  ` H ''$RR8Z #Z  Z  Z ( Z Z #Z  Z x  #   (    rDrj)rrrrrr!r#r%r&r(r*r,r.r0r2r4r6r8r9r;r<r>rLrUr\rerjN)rGrrHz'CIStatusSnapshot'rrM);rB __future__r dataclassesrpathlibrtypingrrrutils.ci_watch_handoff_auditr r r r r rrutils.ci_watch_handoff_schemarrrrrrrrrSrr frozensetrrr!r#r%r&r(r*r,r.r0r2r4r6r8r9r;r< RuntimeErrorr>rIrLrUr\rerj__all__rCrDrErs.^#!''!*:)# ## #)27*& !*:)'7*7&55&5509  1-# j""0Z0#2j2: j:'C*C-F F"0Z0(<:<-. .,0j/!3:22 2=,= $ $0 $ $ $ $... $ $K K \ rD