Module runner 

Spawn-one-session-and-stream-it plumbing (plan §4.6) shared by workers and validators, and reused for orchestrator turns in Phase C.

run_session is the single choke point: it opens the run transcript, emits worker.spawned, pumps every AgentEvent through a RunSink (raw line → transcript, selected events → worker.message), aggregates Result events, parses the role’s report from the final text, computes the RunResult, and emits worker.completed. run_worker and run_validator are thin wrappers that render the role prompt, build the SessionSpec (permissions via permissions::for_role, report schema via --json-schema), and delegate.

Cancellation: callers may pass an Arc<tokio::sync::Notify>; when it fires, the session is aborted and the run finishes as Partial/Aborted.

Buffered runs (roadmap M3 — wall-clock overlap)

The default path writes each event to the shared single-writer EventLog as the stream arrives (LogTarget::Live). That is incompatible with running N worker sessions concurrently: two live sessions would race the one &mut EventLog. So a run may instead target an in-memory buffer (LogTarget::Buffer): every EventKind the run would have appended (worker.spawned, throttled worker.message deltas, durable worker.egress.denied records, any folded hook.gate.fired records — KRZ-302, crate::hook_gates, worker.completed) is collected in order into a Vec and returned alongside the RunOutcome, and NOTHING touches the EventLog. The engine then replays those buffered kinds through its own single-writer emit serially, in a deterministic order, AFTER the concurrent sessions finish — so the single-writer / monotonic-seq invariant is preserved while the claude sessions themselves overlapped in wall-clock (see run_worker_in_buffered). Per-run transcripts (runs/<id>.jsonl) are separate files, not the single-writer log, so they are written live in both modes.

Structs

RunMeta

Identity of one run, decided by the caller before the session starts.

RunOutcome

Everything the engine learns from one completed session.

RunSink

Where a run’s event stream lands: every event’s raw JSON goes to the transcript (one line each, scrubbed); selected events are recorded to the LogTarget as worker.message deltas (scrubbed + truncated).

Enums

LogTarget

Where the event KINDS a run produces are sent.

Functions

contract_env

The environment every contract-command execution context must carry, so worker, validator, and the engine’s final gate can never diverge. Adds KRANZ_BASE_SHA only when a non-empty base SHA was pinned at approval.

parse_decision

Parse a JSON decision — a reply that decides something the operator would otherwise decide (a verdict, a completion, an unblock).

parse_report

Parse a report from a session’s final text: strict whole-text parse, then the first-{-to-last-} substring, then a fenced ```json block.

parse_validator_report

parse_report for ValidatorReport.

parse_worker_report

parse_report for WorkerReport.

run_session

Spawn one session and stream it to completion.

run_session_to

run_session over an explicit LogTarget.

run_validator

Run one validator session for a milestone (plan §4.4/§4.6).

run_validator_in

run_validator with an explicit session working directory (mirrors run_worker_in).

run_worker

Run one worker session for a feature (plan §4.6).

run_worker_in

run_worker with an explicit session working directory (roadmap M3).

run_worker_in_buffered

run_worker_in that BUFFERS its event kinds instead of appending them to the shared log (roadmap M3 wall-clock overlap).

validator_report_schema

JSON Schema matching ValidatorReport (camelCase, closed objects).

worker_report_schema

JSON Schema matching WorkerReport (camelCase, closed object).