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 base_sync: Option<BaseSync>,
    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 this run take a reference on extensions.worktreeConfig being on (see crate::git::acquire_worktree_config)? If so, cleanup releases it - which only actually turns the setting back off once every other run sharing this repository has released its own reference too.

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.

base_sync: Option<BaseSync>

The last look at how far the winner’s tree trailed the landing base, and the rebase(s) tried to close that gap. None until the tree has a winner to check.

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 active_all_overrun(&self, now: Timestamp) -> bool

Does every seat this run still lists as Self::active sit past its own ActiveSeat::timeout_secs? false when nothing is active at all — an empty map is not evidence of anything overrunning.

This alone is not proof the run is dead: a seat’s own attempt can legitimately run a little past its budget while the process driving it is still tearing the attempt down. Every caller pairs this with its own !live reading (daemon::is_working_on) before treating the run as abandoned — this module cannot check that itself without depending on crate::daemon, and callers already have to ask that question anyway.

pub fn abandon(&mut self, by: &str)

Clear every seat this run still lists as active and fail it, unless it had already reached a terminal status some other way.

Callers must already have proven this run is dead — Self::active_all_overrun plus their own !live reading — before calling this; it does not check either itself. Unlike Self::clear_active (dropping a resumed run’s own stale wave before repopulating it, called unconditionally at the top of every execute()), this is a verdict: a run left this way has nothing left to repopulate the wave, ever, and must stop reading as implementing (or whichever node) forever.

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

Flush to run.json, atomically, under the process-global home.

pub fn save_under(&mut self, home: &Path) -> Result<()>

Self::save, rooted at an explicit home instead of the process-global one.

For a caller that was already handed its own home explicitly — a housekeeping pass, mainly, for the same reason Queue::at and the daemon status path are parameters rather than resolved here (see daemon::drive’s own doc) — falling through to the global would write back through whichever directory some other process or test pinned into that OnceLock first, not the one this call was actually handed.

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

Load a run by id or unambiguous id prefix.

impl RunState

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 open_findings(&self) -> Vec<&Finding>

Findings still open when the review loop stopped trying: the last round’s, exactly when that round was not clean. Empty on a run that never reviewed, or whose last round was clean.

This is the last round’s findings regardless of what the fixer claims to have addressed in that same round: a round that stopped the loop (round budget spent, or no tree progress for [crate::graph::STAGNANT_LIMIT] rounds) never had a following round to confirm the fix actually landed, and the self-reported adoption count is not trusted for that judgement either — see ReviewRound::progressed.

pub fn handed_off_with_open_findings(&self) -> bool

Did this run reach a mergeable status (Ready or Merged) with review findings still open?

That combination is the point of the review hand-off: the review round budget (or an unproductive round, see ReviewRound::progressed) was spent while gate and e2e stayed green, so the run was handed off rather than blocked — but the findings did not disappear, and whoever reads the result should be told they are still there.

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.