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.

ContestedHandoff

A review hand-off the panel did not agree to: findings that hold the merge are still open and at least one seat’s final vote was reject. Recorded on RunState::contested_handoff so land can name them in its question.

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.

FollowupRecord

One follow-up task filed from a merged run. See RunState::followups.

GateFixRecord

One fix round spent on a failing verify.gate: which fixer, what it did to the tree, and the gate output it was shown.

Handover

A seat handed from one roster agent to the next after the first failed it (rate limit, timeout or an ordinary failure), recorded so the answer’s author is never a mystery and a run that recovered on its second agent still says what it cost.

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.

LandApproval

A merge-approval question and the head commit it was asked about.

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.

Origin

Where a run came from, and the task it was meant to finish, if any.

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.

RebaseFixRecord

One fixer round spent on a rebase that stopped on a conflict: which fixer, what it was shown and whether git says the rebase then finished.

ReleaseBump

What the post-merge release-bump step did, and whether it needs a human.

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.

SeatHistory

One reviewer seat’s record across review rounds, so a round does not ask an agent that already failed the seat while another one is answering.

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.

Withheld

A newly created lockfile of a package manager the directory does not use, which a rescue commit left untracked instead of committing. Recorded so the omission is visible: the file may be one the task really wanted.

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.

FailClass

What kind of failure ended an agent’s turn on a seat, for deciding whether the seat is worth handing to the next roster agent.

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.

StartedBy

Who started a run. Legibility only: nothing branches on it, the same rule as agent::Invocation::run / node.

Constants

ORIGIN_UNKNOWN

What an unrecorded origin reads as, wherever one is shown.

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.

list_ids_in

list_ids against an explicit runs root, for callers (and tests) that must not depend on the process-global home.

origin_label

Origin::label for a run that may predate origins.

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.

try_home

home without the test panic: None in a test that never pinned a home, so best-effort writers (see crate::notices::raise) skip the write instead of touching the operator’s real state or aborting the test.

write_artifact

Write an artifact, creating the directory if needed.