Struct RunState 

pub struct RunState {

    pub schema: u32,
    pub id: String,
    pub repo: PathBuf,
    pub base_branch: String,
    pub base_commit: String,
    pub instruction: String,
    pub created_at: Timestamp,
    pub updated_at: Timestamp,
    pub status: RunStatus,
    pub seed: u64,
    pub config: Config,
    pub enabled_worktree_config: bool,
    pub candidates: Vec<Candidate>,
    pub judgements: Vec<Judgement>,
    pub judge_skipped: bool,
    pub deliberation: Vec<DeliberationRound>,
    pub votes: Vec<VoteRecord>,
    pub tally: Option<Tally>,
    pub reviews: Vec<ReviewRound>,
    pub gate: Vec<CommandOutcome>,
    pub merge: Option<MergeOutcome>,
    pub leaks: Vec<Leak>,
    pub quota: Vec<QuotaLoss>,
    pub parked: bool,
    pub seats: BTreeMap<String, SeatState>,
    pub active: BTreeMap<String, ActiveSeat>,
    pub pr: Option<PrRecord>,
    pub events: Vec<Event>,
}

The whole run.

Fields

schema: u32

On-disk format version.

id: String

Run id, e.g. 20260830-153012-a1b2.

repo: PathBuf

Repository the run operates on.

base_branch: String

Branch the run started from.

base_commit: String

Commit the run started from.

instruction: String

The task, verbatim.

created_at: Timestamp

When the run was created.

updated_at: Timestamp

Last state flush.

status: RunStatus

Current status.

seed: u64

Seed for labels and session ids.

config: Config

Config snapshot, so a resumed run behaves like the original.

enabled_worktree_config: bool

Did magi enable extensions.worktreeConfig? If so, cleanup turns it off.

candidates: Vec<Candidate>

Candidates.

judgements: Vec<Judgement>

Initial blind rankings.

judge_skipped: bool

judge decided a solo candidate needs no panel and only logged it.

judgements stays empty in that case — nothing to distinguish from “not yet judged” — so this is the record that makes the skip idempotent: without it, every reentry re-ran judge, re-logged the same event, and rewrote status to Judging over whatever a later node had already concluded.

deliberation: Vec<DeliberationRound>

Deliberation, if it happened.

votes: Vec<VoteRecord>

Private final votes.

tally: Option<Tally>

The count.

reviews: Vec<ReviewRound>

Review rounds.

gate: Vec<CommandOutcome>

Final gate.

merge: Option<MergeOutcome>

Merge outcome.

leaks: Vec<Leak>

Vendor tokens seen in judged material.

quota: Vec<QuotaLoss>

Seats lost to a CLI rate limit / quota, in the order they hit.

parked: bool

Parked at a node boundary, waiting to be resumed.

A run that is neither finished nor being worked on is otherwise indistinguishable from one whose daemon was killed, and the two want opposite things from an operator: the first is expected to be resumed, the second is a leftover. Cleared by the resume that carries it on.

seats: BTreeMap<String, SeatState>

Per-seat conversation state.

active: BTreeMap<String, ActiveSeat>

Seats currently mid-answer, keyed by seat.

An entry exists from the moment a prompt is sent until a reply (of any kind — success, failure, quota, drop) comes back, so its keys are exactly “who hasn’t answered yet” for whichever node populated it. See ActiveSeat for why a reader still has to check a live daemon before trusting one of these as “running” rather than “abandoned”.

pr: Option<PrRecord>

Last observation of the winner’s pull request, when a land loop ran.

Persisted rather than derived from the event log because the phone asks two questions about a run that has opened a PR - how are its checks and which round is it on - and parsing prose out of events to answer them would break the first time an event message was reworded.

events: Vec<Event>

Node log.

Implementations

impl RunState

pub fn new( repo: PathBuf, base_branch: String, base_commit: String, instruction: String, config: Config, ) -> Self

A fresh run.

pub fn dir(&self) -> PathBuf

Directory holding this run’s state and artifacts.

pub fn short(&self) -> &str

Short form used in branch names and reports.

pub fn branch_for(&self, label: char) -> String

Branch name for a label.

pub fn worktree_root(&self) -> PathBuf

Root of this run’s worktrees.

pub fn event(&mut self, node: &str, message: impl Into<String>)

Note something in the run log and on the tracing stream.

pub fn seat_started( &mut self, node: &str, seat: &str, timeout: Duration, attempt: usize, )

Record that seat was just sent a prompt for node, with the given wall-clock budget. attempt is 0 for the first ask and N for the Nth nudge or resume, purely for display — it does not change how the seat is treated.

pub fn seat_finished(&mut self, seat: &str)

Record that seat has answered, whatever the answer was.

pub fn clear_active(&mut self) -> bool

Drop every seat this state still lists as answering, reporting whether anything was dropped.

Called first thing in execute, on every entry — fresh, resumed, or recovering a stall — because an entry here only means something while the process that wrote it is still asking that seat something. A process killed mid-wave leaves its last batch of seats here with nobody left to clear them, and the next process to touch this run must not let that leftover read as “still going” before it has asked anyone anything.

pub fn save(&mut self) -> Result<()>

Flush to run.json, atomically.

pub fn load(id: &str) -> Result<Self>

Load a run by id or unambiguous id prefix.

pub fn winner(&self) -> Option<&Candidate>

The winning candidate, once the tally has run.

pub fn viable(&self) -> Vec<&Candidate>

Candidates eligible for judging.

pub fn created_local(&self) -> String

Local-time creation stamp for reports.

pub fn ensure_can_delete(&self, in_flight: bool) -> Result<()>

Assert that this run is safe to delete.

Refuses a run a live daemon is working on, and refuses any run whose candidate worktrees and branches have not been folded away with magi fold. The fold requirement is the real protection: it is what makes “delete” mean “remove a record” rather than “throw away a worktree somebody may still be editing”.

in_flight has to come from the caller, because a run’s own status cannot answer the question. A daemon killed mid-run leaves its status at implementing forever, and a guard that trusted that would make every interrupted run permanently undeletable - the operator’s only recourse being to edit run.json by hand, which is exactly the sort of thing this command exists to avoid. The queue already treats an orphaned .lock from a SIGKILLed daemon the same way; this is that rule for runs.

Trait Implementations

impl Clone for RunState

fn clone(&self) -> RunState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RunState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RunState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for RunState

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.