Module work 

Host-callable queue drain core (roadmap f-1-1): the drain/claim/skip loop that used to live only inside kranz CLI’s cmd_work, hoisted here so any surface (CLI, REST, Slack) can drain a repo’s queue.

drain_queue owns the loop — recover dead claims, then peek/claim/run one mission at a time — but does NOT run missions itself: the caller injects a run_mission closure, because each host supplies its own runner (the CLI tails events to stderr; a headless caller does not) and only the caller knows how to restore its own git checkout.

Structs

DrainReport

Outcome of a drain_queue call: the mission ids that ran to a terminal state vs. those skipped because a blocker failed.

Enums

WorkAction

The dispatcher’s next action given the queue front and repo-busy state.

Functions

drain_queue

Drain the per-repo queue one mission at a time. Recover dead claims once up front; then atomically claim the front entry with the repo-wide busy guard; on Busy either return (once) or sleep 5s and retry; on a lost claim race, retry after a brief sleep; on Claimed, run backend readiness under the claim (park → finish_claim; rate-limit → release + rotate/delay; ok → run), skip a ticket-born entry whose blocker failed, otherwise write ticket Running, invoke the injected run_mission, then finish/release the claim, write the terminal ticket state, and honor once.

drain_queue_expected

Drain with an optional atomic front-entry expectation. When expected is set and a sibling dispatcher changed the front before the claim landed, the claimed entry is released and returned in DrainReport::expected_mismatch without running it. This is the supervised-adapter guard for producers that must translate one specific queued mission’s outcome back to an external system.

drain_queue_with_probe

drain_queue with an injectable readiness probe. Engine and host tests use this seam to script proceed / park / rate-limit decisions without shelling out to whichever agent CLIs happen to be installed on the test machine.

next_work_action

Decide the dispatcher’s next step from the queue front + busy state. Pure: front is queue::peek, busy_with is queue::is_repo_busy.

reconcile_ticket_for_mission

The single authoritative reconcile helper: given a mission id, reverse- looks-up its linked ticket and, if the mission’s folded status is terminal-or-blocked, writes the mapped TicketState to the ticket’s .status sidecar. LIVE statuses (Running/Validating/Paused/Approved/ Planning) are a no-op — the ticket is still mid-flight and must not be clobbered. Every path that can drive a mission to a terminal (or blocked) state — kranz run, kranz exec, REST /start, the drain loop — should call this instead of writing the ticket state itself, so the stale- “Failed” heal case and the Blocked-to-NeedsContext mapping live in one place.

ticket_state_for_mission

Map a terminal (or blocked) mission status to the ticket state recorded after a run. Only called by reconcile_ticket_for_mission for terminal/blocked statuses — live statuses are gated out before this runs.

work_skip_for_failed_blocker

Work-time re-check for a claimed queue entry with a ticket: Some(blocker) when one of the ticket’s unsatisfied blocked-by entries is unsatisfied because that blocker’s own ticket ended up Failed (its mission reached a terminal non-Complete state — Failed/Abandoned/Blocked — after batch-approval queued this entry alongside it). The dispatcher must skip such an entry rather than run it: re-driving a mission whose dependency failed can never succeed, and retrying forever would hot-loop.