docs(agent-ops): 이벤트 기반 모니터링을 강제한다

This commit is contained in:
toki 2026-07-28 19:25:33 +09:00
parent 432284820e
commit 094ec20ec2

View file

@ -128,14 +128,15 @@ When recovering a KST-night `local-G07``local-G08` Laguna locator or a termin
- Treat the caller agent running this skill—not the child dispatcher process—as the lifecycle owner. The dispatcher is only an execution mechanism. Child exit, tool yield, or loss of a session/cell never ends the caller lifecycle by itself.
- Keep the caller turn active and launch the dispatcher as one persistent foreground execution. If the execution tool returns a live session/cell ID, poll the same ID. Never start a duplicate dispatcher while the child is live.
- Never wrap the dispatcher in `timeout`, a short `wait_for`, or an arbitrary cancel/terminate wrapper. Tool yield or expiration of a response window is not process termination; poll the same session/cell again.
- No dispatcher output, an empty poll, or a poll-window expiration is normal event silence. It never permits `final`, caller termination, a duplicate dispatcher, or periodic reads of `stream.log`, `heartbeat.log`, locator files, or `WORK_LOG.md`. Keep the caller turn active, wait on the same session/cell with the longest supported poll window, and inspect files only after a lifecycle banner, process exit, reconnect/recovery condition, or explicit user request.
- If the child exits unexpectedly or its session/cell is lost, re-inspect active tasks, locators, PIDs, and state, then continue every available reconnect, recovery, or rerun path. Exit code `0` is successful terminal state. Exit code `2` is a drained blocker or explicit persistent-state-error terminal state. Exit code `3` is a non-terminal tracking state, including another dispatcher's workspace lock, a live external agent, or an unexpected dispatcher interruption; inspect PID, locator, and state and continue tracking or recovery.
- **ABSOLUTE RULE — Caller monitoring is event-only.** During normal event silence, do not run a timer loop or periodically inspect `ps`, dispatcher `--dry-run`, `state.json`, locator files, `stream.log`, `heartbeat.log`, or `WORK_LOG.md`. A tool yield, empty poll, or response-window expiration is not a lost session/cell and does not permit this inspection.
- No dispatcher output, an empty poll, or a poll-window expiration is normal event silence. It never permits `final`, caller termination, a duplicate dispatcher, or a state inspection. Keep the caller turn active and wait on the same session/cell with the longest supported poll window.
- A lost session/cell exists only when the execution layer reports the tracked identifier unavailable or aborted, or reports the child process exited; a normal wait return alone is insufficient. Then perform exactly one reinspection of active tasks, locators, PIDs, and state. If that snapshot proves a live dispatcher owner, do not inspect it again until a dispatcher lifecycle event is observed. Resume event waiting from the same session/cell when available; otherwise subscribe from EOF to only newly appended START/FINISH rows in the task-group WORK_LOG.md. If the fallback observer itself ends without an event while the dispatcher remains live, reattach the same EOF-only observer without reading any prior row or inspecting state. A dispatcher exit, a new START/FINISH row, a reported recovery error, direct output from the tracked session, or an explicit user request permits the next targeted inspection. Exit code 0 is successful terminal state. Exit code 2 is a drained blocker or explicit persistent-state-error terminal state. Exit code 3 is a non-terminal tracking state, including another dispatcher workspace lock, a live external agent, or an unexpected dispatcher interruption; inspect PID, locator, and state only after that event.
- On a scheduler/control-plane exception or unexpected exception in an individual agent coroutine, do not immediately freeze it as a task blocker or let the dispatcher event loop cancel other running agents and child processes. Monitor every independent running agent until natural completion, return non-terminal exit `3`, and let the next dispatcher reconcile file and state results. Even when the original exception is a persistent-state error, do not convert it to exit `2` if any agent was running.
- In drained-blocker terminal state, persist the orchestration group as `blocked`, directly blocked tasks as `blocked`, consumers waiting on their predecessors as `waiting`, and verified independent completed tasks as `complete` in `.git/agent-task-dispatcher/state.json`. On re-entry, set incomplete observed tasks back to orchestration state `active`, then reevaluate actual task-local blockers and dependencies.
- Persist observed tasks and the complete same-name archive baseline present at startup, regardless of `complete.log`, in `.git/agent-task-dispatcher/state.json`. If an active task disappears after child restart, recover completion only when exactly one new `complete.log` archive absent from the baseline exists; block when none or multiple exist. Do not count a late `complete.log` added to an incomplete archive that existed before execution as current-run completion.
- If existing `state.json` cannot be read or validated as a JSON object, block the dispatcher. Never replace it with empty state or reset the 10-attempt budget. Repair or explicitly handle it before rerunning.
- When a new user turn arrives, continue tracking the same overall request unless it explicitly cancels the previous request.
- Send each `작업시작`, `자가검증시작`, `리뷰시작`, `리뷰재시도`, `Pi복구재시도`, `세션응답복구재시도`, `세션연결재시도`, `리뷰결과`, `작업대기`, `작업차단`, `디스패치추적대기`, and `작업완료` banner to the user through `commentary`. Do not send periodic status commentary or read logs when no new lifecycle banner exists. Event silence never grants `final`; only the two permissions in the absolute-priority section do.
- Send each `작업시작`, `자가검증시작`, `리뷰시작`, `리뷰재시도`, `Pi복구재시도`, `세션응답복구재시도`, `세션연결재시도`, `리뷰결과`, `작업대기`, `작업차단`, `디스패치추적대기`, and `작업완료` banner to the user through `commentary`. Do not send periodic status commentary or inspect logs, PIDs, dispatcher state, locators, or routes when no new lifecycle event exists. Event silence never grants `final`; only the two permissions in the absolute-priority section do.
- Determine every CLI's health/progress primarily from actual stdout/stderr in `stream.log`, plus native session events when available. Never use heartbeat mtime as progress evidence. Record dispatcher PID, agent PID, each process start token, and the per-attempt process environment marker in the locator. Another dispatcher must not start a duplicate attempt merely because the stream is quiet when the PID/start token or marker shows the same process is alive. For a locator without an agent PID, never infer stale state or duplicate recovery from elapsed time while any stream/native progress evidence exists; use only an actual terminal error or confirmed process exit as recovery evidence for every model. Run Pi with `--mode json` so `thinking_delta`, `text_delta`, and tool streams reach stdout. End an **exact** Pi toolCall-to-all-toolResult interval only when every `toolCall.id` in the preceding assistant event matches a later `toolResult.toolCallId`; never terminate the process on a time limit. If the locator lacks an agent PID during this interval, never classify it as stale or duplicate recovery based on log age; require recorded process evidence to show termination. Do not infer tool execution from `starting`, `unknown`, model reasoning, or post-toolResult state. Outside this interval, use only `stream.log` updates for Pi liveness; toolResult alone does not reset the model-response silence clock. If the stream stops for three minutes outside tool execution, store the final stream excerpt as `pi_silence_inspection` for Pi or `stream_silence_inspection` for another CLI, emit `모델응답점검`, and do not terminate the model process. Recover only from an actual terminal error or process exit.
- Detect a local-model `repetition-loop` only when the same normalized chunk repeats three consecutive times with no new tool event or file/state change. Do not infer it from similarity or semantic duplication in `thinking_delta`/`text_delta`. This signal alone must not terminate the process, block the task, trigger recovery/retry, or escalate the model; keep observing for substantive progress or an actual terminal error.
- Keep `provider-connection`, `provider-stream-disconnect`, `session-stall`, `generic-error`, `process-terminated`, context/quota/model errors, and review-control violations distinct, but make them share a budget of 10 consecutive automatic recovery failures for the same task stage. On the 10th failure, block that task and do not auto-resume after cooldown. Reset the stage counter after success.