Module run 

Run state: what happened, where it is stored, and how a run is resumed.

Every node writes its result into RunState and the whole struct is flushed to run.json before the next node starts. That is what makes a run resumable: a competition can take an hour, and dying in review round four should not throw away three implementations, nine judge reads and a deliberation.

Patches and raw agent transcripts are not in run.json — they live beside it under artifacts/, so the state file stays small enough to read by hand.

Structs

ActiveSeat

A seat currently mid-answer: a prompt was sent and no reply has landed yet.

BaseSync

How far the winner’s tree trailed the landing base, last time it was checked, and what came of trying to close that gap.

Candidate

One candidate implementation.

CommandOutcome

Outcome of one shell command.

ContinuationRecord

Cost and outcome of one node’s attempt to recover a missing report by resuming its own seat.

DeliberationRound

A deliberation round.

DeliberationTurn

One judge’s turn in a deliberation round.

Event

A timestamped note about a node.

FixRecord

The fixer’s response to a round.

JobRecord

A command a seat’s own CLI reported running, kept for magi show and for telling “this seat’s turn ended” apart from “the process it started is done” — see agent::CommandEvidence, which is the only source this is ever built from. Never something magi polled or supervised; a command the CLI never reported finishing (or a CLI this crate has no adapter for at all) simply has no entry here, which must read as “unknown”, not as “nothing ran”.

Judgement

One judge’s independent ranking.

MergeOutcome

What happened to the winning branch.

OperatorFixFinding

One finding an operator selected for OperatorFixRequest, with the provenance a reviewer originally gave it, copied here verbatim.

OperatorFixRequest

One magi fix invocation: the operator’s own record of which already-recorded findings they routed to a fixer, why, and what came back. See SCHEMA’s doc for schema 9 on why this is a channel of its own rather than a field on ReviewRound.

PrRecord

What the land loop saw last time it looked at the pull request.

QuotaLoss

A seat that was taken out by a CLI rate limit / quota, recorded so a run whose panel collapsed does not masquerade as a healthy one.

ReviewRecord

One reviewer’s report in a round.

ReviewRevoteRecord

One seat’s revote during a round’s reconsideration (see ReviewRound::reconsideration).

ReviewRound

One review + verify + fix round.

RunState

The whole run.

Tally

The mechanical count.

VerificationSummary

ReviewRound::verification_summary’s output: the facts, pre-worded, for a prompt or report to place under its own heading. Kept as two pieces rather than one pre-joined string so a caller that wants to insert its own note between the label and the raw command tail (see prompt::review) can do so without re-parsing text back apart.

VoteRecord

A final vote, collected privately.

Enums

ContinuationOutcome

How a node recovered — or failed to recover — a structured report after the CLI’s own turn ended cleanly (a usable, non-empty, exit-0 reply) without it. A clean CLI turn is not the same fact as the node’s own work being done — see the fix node’s continue_fix_report, which is what produces this.

E2eStatus

The honest state of a round’s e2e leg. See ReviewRound::e2e_status.

GateStatus

The honest state of a run’s final gate. See RunState::gate_status.

JobStatus

What a JobRecord’s own CLI reported for it. There is no Running variant: nothing here is ever polled live, so “still running” and “finished but never reported” are the same absence of evidence, not a state this type can name — see JobRecord’s own doc.

Liveness

Whether a process is provably still driving a run, provably not, or neither — see RunState::liveness. Serialized as a lowercase string ("live" / "dead" / "unknown") rather than a bool: a bool has no room for “could not tell”, and folding that case into either true or false is exactly the wrong call for a display an operator uses to decide whether to wait or to act — see the schema-10 field doc on RunState::driver_pid for the report it used to produce instead.

OperatorFixOutcome

What happened to one operator-selected finding after the fixer ran, as part of an OperatorFixRequest.

RunStatus

Where a run got to.

Constants

SCHEMA

On-disk format version. Bumped when a field changes meaning, so a resumed run never half-reads a state file written by a different magi.

Functions

artifact_path

Path of a run artifact.

default_worktree_root

The worktree root a run uses when the config sets none: ~/wt/magi.

home

Where magi keeps its runs.

is_run_id

Does name have the shape [new_id] mints: YYYYMMDD-HHMMSS-xxxx?

latest_id

The most recent run, if any.

list_ids

Every run id on disk, newest first.

read_artifact

Read an artifact back, e.g. a stored patch on resume.

resolve_id

Expand an id prefix to exactly one run id.

run_dir

Directory for one run id.

runs_root

<home>/runs.

set_home

Pin the run home for this process. The first call wins.

short_of

The short form of a run id: the trailing block after the last -.

tail

Keep the last max bytes of text, on a line boundary.

write_artifact

Write an artifact, creating the directory if needed.