Skip to main content

magi/
run.rs

1//! Run state: what happened, where it is stored, and how a run is resumed.
2//!
3//! Every node writes its result into [`RunState`] and the whole struct is
4//! flushed to `run.json` before the next node starts. That is what makes a run
5//! resumable: a competition can take an hour, and dying in review round four
6//! should not throw away three implementations, nine judge reads and a
7//! deliberation.
8//!
9//! Patches and raw agent transcripts are *not* in `run.json` — they live beside
10//! it under `artifacts/`, so the state file stays small enough to read by hand.
11use std::collections::{BTreeMap, BTreeSet};
12use std::path::{Path, PathBuf};
13
14use anyhow::{Context as _, Result, bail};
15use jiff::{Timestamp, Zoned};
16use serde::{Deserialize, Serialize};
17
18use crate::agent::SeatState;
19use crate::blind::Leak;
20use crate::config::{Config, MergeMode};
21use crate::proc::Quiet as _;
22use crate::verdict::{Finding, Rejection, ReviewVote, Severity};
23
24/// On-disk format version. Bumped when a field changes meaning, so a resumed
25/// run never half-reads a state file written by a different magi.
26///
27/// 2: added `RunStatus::Stalled`, `RunState::quota` (rate-limit losses), and
28/// the quorum fields on `Tally`. `RunState::load` already fails loudly and
29/// clearly on a schema mismatch; an old `run.json` from schema 1 now says so
30/// instead of silently half-reading.
31///
32/// 3: added `RunState::judge_skipped`. A solo candidate makes `judge` write
33/// only an event, leaving `judgements` empty forever — indistinguishable from
34/// "not yet judged" on every later reentry, which is what let `judge` re-run
35/// on a finished run and clobber its status back to `Judging`. The flag is
36/// the missing record of the fact that judging was skipped on purpose.
37///
38/// Also 3: a single-viable-candidate tally records `Tally::judges` as `0` and
39/// fills `Tally::uncontested`, instead of leaving the full roster size sitting
40/// next to a panel that never sat. A schema-2 record keeps reading as "0 of 3
41/// judges present" forever, because a tally is computed once and never
42/// recomputed on resume; the bump keeps that stale reading from being mixed
43/// with the new meaning.
44///
45/// 4: added `ReviewRound::progressed`. `graph::STAGNANT_LIMIT` counts
46/// consecutive rounds with `progressed == false` to decide whether the
47/// review loop should give up early, and a schema-3 record's default
48/// `false` would misreport a round that, at the time, actually committed a
49/// real diff — the field simply did not exist yet to say so. Without the
50/// bump, resuming an old multi-round review could spuriously trip the
51/// stagnation check on rounds that were never stagnant.
52///
53/// 5: added `RunStatus::Landing`. A run inside [`crate::land`]'s post-merge
54/// loop used to carry whatever status `merge` set before calling it forward
55/// unchanged - `Merged`, even while still watching CI or waiting on the
56/// owner's approval - which is also the one status [`RunStatus::resumable`]
57/// treats as finished. A daemon that gave this run's slot back to poll
58/// something else while an approval was outstanding, or one that simply
59/// crashed mid-land, had no way to tell "still landing" from "actually
60/// merged" and would either restart the whole competition or leave the run
61/// stuck reading as done. A schema-4 record has no notion of `Landing` at
62/// all, so this is a meaning a resumed old run cannot be guessed into rather
63/// than a value it can default to - hence the bump, not a `#[serde(default)]`.
64///
65/// 6: a deferred e2e is represented by an empty outcome list plus
66/// `ReviewRound::e2e_deferred`. Schema 5 treated that same empty list as an
67/// unconfigured, successful check, so schema-5 records are migrated with the
68/// old (not-deferred) meaning while older binaries reject schema-6 records.
69///
70/// 7: added `RunState::gate_ran`. An empty `RunState::gate` used to carry two
71/// meanings at once — "never attempted, or the last attempt was
72/// resource-blocked" (`graph::Runner::gate`'s retry case) and "attempted,
73/// zero commands configured, vacuously passed" (a repo with no
74/// `verify.gate`) — and nothing told them apart. `graph::Runner::merge`
75/// therefore read the second case as the first and refused forever: a
76/// review-only run with no gate commands configured reached `Gating` and
77/// then could never leave it. A schema-6 record's non-empty `gate` is
78/// migrated to `gate_ran = true` (a recorded attempt, real or historical,
79/// should not be spent again); an empty one migrates to `gate_ran = false`
80/// and is simply re-attempted by the next `gate()` call, which self-heals
81/// instantly for the zero-commands case.
82///
83/// 8: `ReviewRound::verified_head` used to be `None` for the overwhelming
84/// majority of rounds — every ordinary round that ran e2e against its own
85/// `head` in the main review loop never set it at all, leaving only the
86/// rare catch-up-on-a-different-commit case populated. A reader (a review
87/// prompt, `magi show`, the web UI) had no field to ask "which commit did
88/// this round's `e2e` actually check" and fell back to assuming it was
89/// always `head`, which is also what let a stale round's red output get
90/// quoted to a later round's reviewers as if it were about their patch, not
91/// an earlier one (see `ReviewRound::verification_summary`, which now exists
92/// so nowhere else has to guess). `verified_head` is now set whenever `e2e`
93/// held a real attempt (`E2eStatus::Passed`/`Failed`), always naming the
94/// commit actually checked instead of only the divergent case, and
95/// `ReviewRound::verified_at` is new alongside it. A schema-7 round's own
96/// unconditional main-loop check was always against `head` whether or not
97/// this field said so, so a `None` with a non-empty `e2e` migrates to
98/// `Some(head)` — a reconstruction of a fact that was always true, not a
99/// guess. `verified_at` has no historical value to reconstruct and stays
100/// `None`, which reads through `verification_summary` as "checked at:
101/// unknown" — an honest gap, not a fabricated time.
102/// 9: added [`RunState::operator_fixes`] — one record per `magi fix`
103/// invocation, routing specific, already-recorded findings to a fixer as a
104/// targeted, out-of-band fix outside the normal round sequence. Kept in a
105/// channel of its own rather than folded into [`ReviewRound`], because a
106/// reviewer's own severity and vote (copied verbatim onto
107/// [`OperatorFixFinding`]) must never be rewritten to look like the operator
108/// manufactured a blocking verdict — see `graph::Runner::fix_selected`. A
109/// schema-8 record has no operator-fix history at all, and
110/// `#[serde(default)]` reads an empty list as exactly that: "none happened",
111/// not an unknown gap. Nothing about an existing field's meaning changes.
112///
113/// 10: added `RunStatus::VerifiedNoop` and `Candidate::verified_noop`. Before
114/// this, an implementer that correctly concluded (with evidence) that a
115/// task's request was already satisfied elsewhere had no way to say so: the
116/// run ended the same way as one where every candidate simply failed to
117/// write anything — `after_implement` bailing with "no candidate produced a
118/// change; nothing to judge" and the run settling as a plain `Failed`. That
119/// conflated two very different facts (investigation run 391f's audit is
120/// what surfaced it: two attempts that had, correctly, found their fix
121/// already on `main`). A schema-9 record has no notion of either the new
122/// status or field, so a `VerifiedNoop` value is a meaning that cannot be
123/// reconstructed from an old record — hence the bump, not a
124/// `#[serde(default)]` for the status. `Candidate::verified_noop` alone
125/// *does* default-read as `None` on an old record, which is the honest
126/// reading: a run written before this schema never made the claim.
127///
128/// The report task 391f itself was raised from also named `6c5e`, `8df3` and
129/// `e9ce` as three more tasks whose implement wave ended the same
130/// diff-zero way, and the investigation traced all three — they do not
131/// share one cause.
132///
133/// `6c5e` and `8df3` are the same already-landed pattern as `391f`, not a
134/// coincidence: all three were re-queued together by a same-day audit of
135/// `done`-but-unlanded magi tasks (queue talk `20260912-115153-7216`,
136/// 2026-09-12 02:51–04:24), which found 17 magi tasks marked `done` with no
137/// merge to show for it and re-queued 16 of them, `6c5e` (a fix for the
138/// owner's `magi ask --thread` back-and-forth) and `8df3` (release
139/// automation) included. A second, same-day audit (talk
140/// `20260912-222053-07fe`, 13:20–13:36) then found 12 of those re-queued
141/// tasks — `391f`, `6c5e` and `8df3` among them — already merged by another
142/// route, and the owner had them deleted (`magi task rm`); `391f` alone
143/// survived because a daemon still held its run at the moment of deletion,
144/// which is the only reason any record of this group still exists to audit.
145/// Quoted directly from that second audit's own turn (talk `07fe`, so this
146/// reads without needing access to that talk store), naming both by id:
147///
148/// > 12件がマージ済み(対応不要)、3件が未実装(妥当)、2件が部分実装(要確認)でした。
149/// > **マージ済み → hold/rmを推奨:** 6c5e, 1ddc, fcf5, e25b, cea2, 391f, 3202,
150/// > b0a1, 5365, af85, 9f26, 8df3
151///
152/// — followed by the owner answering "削除!" and the agent confirming "11件
153/// 削除完了。391f はいま実行中のdaemonが掴んでいて削除できませんでした."
154/// `git log` independently confirms both fixes: the ask-back feature `6c5e`
155/// wanted landed as `f0df474` ("let the owner ask back on a question...",
156/// #93) on 2026-09-06, and the release-bump automation `8df3` wanted landed
157/// as `61005dd`/`bedd925` (open a release-bump PR on merge) on 2026-09-07
158/// and `116fcdc` (proportional version bump, #108) on 2026-09-08 — all
159/// before the 09-12 requeue. No run record survives the deletion for either
160/// task, so this schema's evidence is the audit transcript plus the
161/// independently re-checked `git log`, not a `run.json`.
162///
163/// `e9ce` is not that pattern at all, and is the reason the adoption guard
164/// below is all-or-nothing rather than "any candidate said so": its task
165/// asked an implementer to merge the real repository's `main` and cut a
166/// GitHub release — a destructive, out-of-worktree operation `AGENTS.md`
167/// names explicitly as not something to hand to an unattended candidate.
168/// Both of its runs (`20260912-053352-49ad`, `20260912-062629-bab1`)
169/// correctly refused, filed `magi ask` (questions `6196`, `6c9a`), and ended
170/// with an empty diff only because no answer arrived before the implement
171/// node's timeout — `49ad` looped `magi ask --wait` in the foreground for
172/// roughly 50 minutes as instructed before the timeout cut it off; `bab1`
173/// ended its turn moments after filing its question without ever actually
174/// blocking on the wait, a separate protocol slip this schema change does
175/// not attempt to fix. `49ad`'s own `candidates[0].summary` (quoted here
176/// because both records predate schema 10 and, separately, predate a
177/// still-unrelated struct change that already makes today's `magi show`
178/// refuse to parse either of them — `unknown field 'planner'` — so this is
179/// read straight from `run.json` on disk, not through that command):
180///
181/// > タスクの内容(READY 状態の run を実リポジトリの main に `merge --no-ff`
182/// > する、GitHub Release を作る)を精査した結果、これは全てこのワーカーの
183/// > worktree の外にある実リポジトリと GitHub 上の共有状態に対する不可逆な
184/// > 操作であり […] 私自身の運用ルール「Work only inside this worktree.
185/// > Nothing outside it is yours.」と正面から矛盾すると判断しました。
186///
187/// Neither candidate's reply carries the
188/// `NO CHANGE NEEDED` marker below, so both runs correctly stay `Failed`
189/// under this schema, not `VerifiedNoop`: a run blocked on an unanswered
190/// authorization question is not a verified no-op, and reading the two
191/// alike is exactly the misclassification the guard's per-candidate and
192/// whole-run conditions exist to refuse.
193///
194/// `RunStatus::Superseded` (added without a bump, still schema 10) is
195/// additive in the ordinary sense — an old build reading a run written under
196/// a newer one only had `RunStatus` variants to worry about before this, and
197/// a record already on disk never contained the new variant to begin with —
198/// but it is not additive in the sense every earlier schema bump on this
199/// constant was: `daemon::supersede_prior_runs` now rewrites a `Blocked` or
200/// `Stalled` run's `status` field *after* it was first written, once a later
201/// attempt at the same task lands. Any tooling outside magi that reads
202/// `run.json` and assumes a terminal `status` is permanent once set — a
203/// monitoring script polling for `blocked`, say — needs to know that
204/// `superseded` is where some of those records now go instead of staying put
205/// forever; see that function's own doc for exactly when.
206///
207/// Schema 11 adds [`RunState::released_to`] / [`RunState::released_branches`]:
208/// a run whose worktree a later attempt at the same task took over
209/// (`crate::handover`) can no longer be resumed from where it was. The fields
210/// are additive, but an older build would happily resume such a run into a
211/// worktree that no longer exists, which is the one thing the bump is for.
212///
213/// Schema 12 adds [`RunState::driver_exited`]: the driver records that it
214/// stopped walking the graph. Additive, but an older build would keep reading
215/// a long-lived daemon's pid as a live driver of a run that ended long ago.
216///
217/// Schema 13 adds [`RunState::origin`]: who started the run and which task it
218/// stood in for. Additive, and an older record is deliberately left with
219/// `None` ("origin unknown") rather than guessed at — a run from before this
220/// existed must not read as an operator's when nobody knows. The bump exists
221/// so a run is never mistaken for one whose origin was known and empty.
222///
223/// Schema 14 records [`RunState::task_instruction`], authored task criteria
224/// separately from generated review context. Older records retain `None`:
225/// `instruction` may contain generated context and cannot establish authorship.
226///
227/// Schema 15 records pending candidate preservation independently of an empty
228/// implementation. Older drivers must refuse to resume these records rather
229/// than judge without honoring the preservation barrier.
230///
231/// Schema 16 records empty-attempt retirement. Older executors must reject
232/// retired runs rather than ignoring the new execution fence.
233///
234/// Schema 17 pins task repository assignments for publication. Older executors
235/// must not derive an initial-assignment head for a reassigned run.
236pub const SCHEMA: u32 = 17;
237
238/// Why a pass over a run stopped at a node boundary, recorded when it
239/// happened. Never inferred afterwards: `upgrade.json` is overwritten by the
240/// next upgrade and an event line is prose.
241#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
242#[serde(tag = "kind", rename_all = "snake_case")]
243pub enum ParkCause {
244    /// `magi web` / `magi serve` replaced its own binary. `to` is `None` when
245    /// the target release was not known at the time.
246    Upgrade {
247        /// The version that was running.
248        from: String,
249        /// The release it was replaced with, when known.
250        #[serde(default)]
251        to: Option<String>,
252    },
253    /// The operator asked the loop to park (`/api/loop`).
254    Operator,
255    /// The interrupt scheduler parked this run so another task runs first.
256    Interrupt {
257        /// What the scheduler gave as the reason.
258        reason: String,
259    },
260    /// The run waits for the owner's answer (merge approval, withheld text).
261    Question,
262    /// A park whose requester did not say why.
263    Unspecified,
264}
265
266impl ParkCause {
267    /// One line for an event or the UI.
268    #[must_use]
269    pub fn label(&self) -> String {
270        match self {
271            Self::Upgrade { from, to: Some(to) } => format!("upgrade {from} \u{2192} {to}"),
272            Self::Upgrade { from, to: None } => format!("upgrade from {from}"),
273            Self::Operator => "operator asked the loop to park".to_owned(),
274            Self::Interrupt { reason } => reason.clone(),
275            Self::Question => "waiting for the owner's answer".to_owned(),
276            Self::Unspecified => "park requested, reason not stated".to_owned(),
277        }
278    }
279}
280
281/// How a pass ended, when the process that drove it said so.
282#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
283#[serde(tag = "how", rename_all = "snake_case")]
284pub enum PassEnd {
285    /// Parked at a node boundary on purpose.
286    Parked {
287        /// Why it parked.
288        cause: ParkCause,
289    },
290    /// The next pass found this one still open: it stopped without saying so
291    /// (a crash, a kill). Says nothing about why.
292    Unrecorded,
293}
294
295/// One pass over a run: the run is the same, the process driving it is not.
296#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
297pub struct RunPass {
298    /// Position in [`RunState::passes`].
299    pub index: usize,
300    /// When the process took the run over.
301    pub started_at: Timestamp,
302    /// The run already had work on disk when this pass began.
303    pub resumed: bool,
304    /// When the pass ended, if it did.
305    #[serde(default)]
306    pub ended_at: Option<Timestamp>,
307    /// `None` while open (or still driving).
308    #[serde(default)]
309    pub end: Option<PassEnd>,
310    /// The task loop (or `magi run` for a task) counted this pass as a task
311    /// attempt. Resumes keep one distinct id in `Task::runs`, while each
312    /// counted pass belongs in task history. A resume without a task does not.
313    #[serde(default)]
314    pub task_entry: bool,
315}
316
317/// What an unrecorded origin reads as, wherever one is shown.
318pub const ORIGIN_UNKNOWN: &str = "origin unknown (started before origins were recorded)";
319
320/// Who started a run. Legibility only: nothing branches on it, the same rule
321/// as `agent::Invocation::run` / `node`.
322#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
323#[serde(tag = "kind", rename_all = "snake_case")]
324pub enum StartedBy {
325    /// The daemon, minting an attempt for a queue task.
326    Queue {
327        /// The task the attempt belongs to.
328        task: String,
329    },
330    /// An agent inside a talk (chat) conversation, via `magi run` / `magi review`.
331    Chat {
332        /// Talk id, e.g. `4a7b`.
333        talk: String,
334    },
335    /// An agent seat inside another run, identified by the `MAGI_RUN` /
336    /// `MAGI_NODE` it was spawned with.
337    Seat {
338        /// Run the seat belonged to.
339        run: String,
340        /// Node it was working in.
341        node: String,
342    },
343    /// A person at a terminal (or anything that carries no attribution).
344    Operator,
345}
346
347/// Where a run came from, and the task it was meant to finish, if any.
348///
349/// Kept as two facts because they vary independently: a chat agent may start a
350/// run on behalf of a queue task.
351#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
352pub struct Origin {
353    /// Who started it.
354    pub by: StartedBy,
355    /// The queue task this run serves, when it names one.
356    #[serde(default)]
357    pub task: Option<String>,
358}
359
360impl Origin {
361    /// A run a person started with no task attached.
362    pub fn operator() -> Self {
363        Self {
364            by: StartedBy::Operator,
365            task: None,
366        }
367    }
368
369    /// An attempt the daemon mints for `task`.
370    pub fn queue(task: &str) -> Self {
371        Self {
372            by: StartedBy::Queue {
373                task: task.to_owned(),
374            },
375            task: Some(task.to_owned()),
376        }
377    }
378
379    /// Attribute from the `MAGI_RUN` / `MAGI_NODE` pair `agent::invoke`
380    /// exports, as `(run, node)`; `None` for no (or blank) `run` is an
381    /// operator. A node of `chat` is the talk layer, whose run is the talk id.
382    pub fn from_agent_env(env: Option<(String, String)>, task: Option<String>) -> Self {
383        let by = match env {
384            Some((run, node)) if node == crate::queue::CHAT_NODE => StartedBy::Chat { talk: run },
385            Some((run, node)) => StartedBy::Seat { run, node },
386            None => StartedBy::Operator,
387        };
388        Self { by, task }
389    }
390
391    /// The same origin, naming `task` as the one it serves.
392    pub fn serving(mut self, task: Option<String>) -> Self {
393        if task.is_some() {
394            self.task = task;
395        }
396        self
397    }
398
399    /// One short label for lists, reports and the web UI.
400    pub fn label(&self) -> String {
401        let by = match &self.by {
402            StartedBy::Queue { task } => format!("task {}", short_of(task)),
403            StartedBy::Chat { talk } => format!("chat {}", short_of(talk)),
404            StartedBy::Seat { run, node } => format!("{node}@{}", short_of(run)),
405            StartedBy::Operator => "operator".to_owned(),
406        };
407        match (&self.by, &self.task) {
408            (StartedBy::Queue { task: a }, Some(b)) if a == b => by,
409            (_, Some(t)) => format!("{by}, for task {}", short_of(t)),
410            _ => by,
411        }
412    }
413}
414
415/// [`Origin::label`] for a run that may predate origins.
416pub fn origin_label(origin: Option<&Origin>) -> String {
417    origin.map_or_else(|| ORIGIN_UNKNOWN.to_owned(), Origin::label)
418}
419
420/// Where a run got to.
421#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
422#[serde(rename_all = "snake_case")]
423pub enum RunStatus {
424    /// Worktrees being prepared.
425    Prep,
426    /// Candidates being implemented.
427    Implementing,
428    /// Judges ranking blind.
429    Judging,
430    /// Judges deliberating after a split.
431    Deliberating,
432    /// Final votes being collected privately.
433    Voting,
434    /// Winner in the review + verification loop.
435    Reviewing,
436    /// Gate commands running. Transient: `graph::Runner::gate` and
437    /// `graph::Runner::merge` always move a run on from here, whether or not
438    /// any gate commands are configured — see [`RunState::gate_status`] and
439    /// `SCHEMA`'s doc for schema 7, which fixed a repo with an empty
440    /// `verify.gate` stranding a review-only run in `Gating` forever.
441    Gating,
442    /// Inside [`crate::land`]'s post-merge loop: watching CI, running a fix
443    /// round, rebasing onto a moved base, or waiting on the owner's merge
444    /// approval. A run parked here while an approval is outstanding has
445    /// handed its daemon slot back — see [`crate::daemon`] — and resumes
446    /// through exactly this status, not a fresh competition.
447    Landing,
448    /// Winner merged.
449    Merged,
450    /// Local review or publication finished; no public merge is confirmed.
451    Ready,
452    /// The judgement did not gather enough judges (e.g. rate limiting took out
453    /// seats), so the verdict is not trustworthy. The run stopped and kept its
454    /// work so it can be resumed or folded — it must never be confused with a
455    /// healthy `Ready`.
456    Stalled,
457    /// Review rounds exhausted with findings still open, or the gate failed.
458    Blocked,
459    /// The graph could not complete.
460    Failed,
461    /// Every candidate wrote nothing, and every one of them said why in a way
462    /// that survived [`crate::graph::Runner`]'s adoption guard: a clean CLI
463    /// exit, an actually-empty tree, no command left with an unconfirmed
464    /// exit status, and non-empty evidence. Distinct from `Failed` on
465    /// purpose — see `SCHEMA`'s doc for schema 10 — because the two read
466    /// identically to an operator glancing at a card ("nothing happened")
467    /// while meaning opposite things: one is an agent that could not do the
468    /// work, the other is an agent that checked and the work was already
469    /// done. Settles the task through [`crate::queue::Task::handed_off`], not
470    /// [`crate::queue::Task::fail`]: a human still has to look — the claim is
471    /// unverified by magi itself — and `Held` (not `Failed`-and-requeued)
472    /// means nothing retries the task unattended on the same unconfirmed
473    /// claim while that look is pending.
474    VerifiedNoop,
475    /// A later attempt at the same task already finished the job — see
476    /// `crate::queue::Task::superseded_attempts` — so this run's own
477    /// `Blocked`/`Stalled` no longer means anyone has to look at it. Written
478    /// over one of those two statuses once the task itself is
479    /// `crate::queue::TaskStatus::Done`, and only onto an attempt that comes
480    /// before the one that succeeded. Publication can also retire a stopped,
481    /// non-terminal predecessor after an explicit worktree handover to its
482    /// successor leaves it nothing to resume. Unlike them, not [`Self::resumable`]:
483    /// there is nothing left to resume towards, the task already has its
484    /// answer, and a fold is free to clean this run's worktree away without
485    /// waiting on a human to confirm that first.
486    Superseded,
487    /// The winner's whole change is already on the base under other commit
488    /// ids (a cherry-pick or squash by another task) — see
489    /// [`crate::already`]. Terminal and not a failure: nothing is left to
490    /// land, so unlike `Blocked` nobody has to look, and unlike `Merged` this
491    /// run did not land anything. Never resumable; `BaseSync::already_in`
492    /// names the base commits that carry the change. Added without a schema
493    /// bump, like `Superseded`: no record on disk can contain it yet.
494    AlreadyInBase,
495}
496
497impl RunStatus {
498    /// Is this a terminal state?
499    pub fn done(self) -> bool {
500        matches!(
501            self,
502            Self::Merged
503                | Self::Ready
504                | Self::Stalled
505                | Self::Blocked
506                | Self::Failed
507                | Self::VerifiedNoop
508                | Self::Superseded
509                | Self::AlreadyInBase
510        )
511    }
512
513    /// The name this status is written and shown under, matching the
514    /// `snake_case` serde spelling so a log line, an error message and the
515    /// JSON a phone reads all say the same word.
516    pub fn as_str(self) -> &'static str {
517        match self {
518            Self::Prep => "prep",
519            Self::Implementing => "implementing",
520            Self::Judging => "judging",
521            Self::Deliberating => "deliberating",
522            Self::Voting => "voting",
523            Self::Reviewing => "reviewing",
524            Self::Gating => "gating",
525            Self::Landing => "landing",
526            Self::Merged => "merged",
527            Self::Ready => "ready",
528            Self::Stalled => "stalled",
529            Self::Blocked => "blocked",
530            Self::Failed => "failed",
531            Self::VerifiedNoop => "verified_noop",
532            Self::Superseded => "superseded",
533            Self::AlreadyInBase => "already_in_base",
534        }
535    }
536
537    /// Label for a human-facing listing or report — the same word as
538    /// [`Self::as_str`] except where the machine spelling would read harsher
539    /// than the state actually is. `VerifiedNoop` is the one case: its own
540    /// `as_str` exists for logs, JSON and event messages, none of which
541    /// should quietly grow a second vocabulary, but a bare "verified_noop" in
542    /// a report reads like an error code, not the qualified, evidence-backed
543    /// claim it actually is.
544    pub fn display_label(self) -> &'static str {
545        match self {
546            Self::VerifiedNoop => "agent-verified no-op",
547            Self::AlreadyInBase => "already in base",
548            other => other.as_str(),
549        }
550    }
551
552    /// Can this run be carried on from where it stopped?
553    ///
554    /// Everything except a finished run and a failed one. `execute` skips
555    /// nodes already recorded, so re-entering is cheap wherever the run
556    /// stopped, and the alternative is always a fresh competition against
557    /// work that already exists.
558    ///
559    /// - `Stalled` re-asks only the seats whose absence collapsed the panel,
560    ///   keeping the candidates that were already paid for.
561    /// - `Blocked` re-enters the review loop against a branch that is built.
562    /// - **A non-terminal status** means the run was interrupted: a parked
563    ///   run waiting for its upgrade, or one whose daemon was killed. This
564    ///   used to be excluded, which left run 4043 stuck at `reviewing` with
565    ///   the deck telling the operator it could not be resumed - the one
566    ///   state where resuming is the only sensible answer.
567    ///
568    /// `Failed` does not qualify: the graph could not complete and there is
569    /// no established point to continue from. Nor does a finished run, whose
570    /// answer is a new competition. Nor does `VerifiedNoop`: every candidate
571    /// already agreed nothing belongs in this worktree, and resuming would
572    /// only re-ask the same question — the answer is for a human to check
573    /// the evidence, not for the graph to run again. Nor does `Superseded`:
574    /// a later attempt at the same task already finished it, so there is
575    /// nothing left this run's own answer could still contribute.
576    ///
577    /// Whether anything is *already* driving the run is a separate question,
578    /// answered by `daemon::is_working_on` at the callers that need it.
579    pub fn resumable(self) -> bool {
580        !matches!(
581            self,
582            Self::Merged
583                | Self::Ready
584                | Self::Failed
585                | Self::VerifiedNoop
586                | Self::Superseded
587                | Self::AlreadyInBase
588        )
589    }
590}
591
592/// One candidate implementation.
593#[derive(Debug, Clone, Serialize, Deserialize)]
594pub struct Candidate {
595    /// Position in the implementer list.
596    pub index: usize,
597    /// Blind label as presented to judges.
598    pub label: char,
599    /// Which agent wrote it. Recorded for the stats tables, never shown to a
600    /// judge.
601    pub agent: String,
602    /// Branch, named after the label so judges can inspect it without learning
603    /// the author.
604    pub branch: String,
605    /// Worktree path.
606    pub worktree: PathBuf,
607    /// Sanitized author summary.
608    #[serde(default)]
609    pub summary: String,
610    /// `git diff --stat`.
611    #[serde(default)]
612    pub stat: String,
613    /// Files touched.
614    #[serde(default)]
615    pub files: usize,
616    /// Commits ahead of base.
617    #[serde(default)]
618    pub commits: usize,
619    /// True when the agent produced no change at all.
620    #[serde(default)]
621    pub empty: bool,
622    /// Why this candidate is not in the running.
623    #[serde(default)]
624    pub failed: Option<String>,
625    /// The evidence this candidate gave for writing no change on purpose —
626    /// the `NO CHANGE NEEDED:` marker `prompt::implement`'s reply format
627    /// documents, verbatim. `Some` only when [`crate::graph`]'s adoption
628    /// guard accepted the claim: the CLI exited cleanly, the tree really is
629    /// empty, no command in the reply was left with an unconfirmed exit
630    /// status, and the evidence itself is non-empty. A candidate that wrote
631    /// nothing and said nothing about why — the ordinary empty loss — always
632    /// reads `None` here, same as one written before schema 10 ever existed.
633    #[serde(default)]
634    pub verified_noop: Option<String>,
635    /// Wall-clock time for the implementation.
636    #[serde(default)]
637    pub duration_ms: u64,
638    /// Whether the worktree has been folded away.
639    #[serde(default)]
640    pub folded: bool,
641}
642
643impl Candidate {
644    /// Can this candidate be judged?
645    pub fn viable(&self) -> bool {
646        self.failed.is_none() && !self.empty
647    }
648}
649
650/// One judge's independent ranking.
651#[derive(Debug, Clone, Serialize, Deserialize)]
652pub struct Judgement {
653    /// Judge seat number, 1-based.
654    pub judge: usize,
655    /// Seat key.
656    pub seat: String,
657    /// Agent occupying the seat.
658    pub agent: String,
659    /// Best-first labels.
660    #[serde(default)]
661    pub ranking: Vec<char>,
662    /// Per-label justification.
663    #[serde(default)]
664    pub reasons: BTreeMap<String, String>,
665    /// Self-reported confidence.
666    #[serde(default)]
667    pub confidence: Option<u8>,
668    /// Per-label strengths this judge attributed to candidates it did not
669    /// rank first; the only input of the graft phase.
670    #[serde(default)]
671    pub strengths: BTreeMap<String, Vec<String>>,
672    /// Order the candidates were presented in, as candidate indices.
673    #[serde(default)]
674    pub order: Vec<usize>,
675    /// Why this judge has no ranking.
676    #[serde(default)]
677    pub failed: Option<String>,
678    /// Wall-clock time.
679    #[serde(default)]
680    pub duration_ms: u64,
681}
682
683/// One judge's turn in a deliberation round.
684#[derive(Debug, Clone, Serialize, Deserialize)]
685pub struct DeliberationTurn {
686    /// Judge seat number, 1-based.
687    pub judge: usize,
688    /// Agent occupying the seat.
689    pub agent: String,
690    /// The argument, as written.
691    pub body: String,
692    /// Where the judge stood at the end of the turn.
693    #[serde(default)]
694    pub tentative: Option<char>,
695}
696
697/// A deliberation round.
698#[derive(Debug, Clone, Serialize, Deserialize)]
699pub struct DeliberationRound {
700    /// 1-based round number.
701    pub round: usize,
702    /// Turns, in the order they were taken.
703    pub turns: Vec<DeliberationTurn>,
704}
705
706/// A final vote, collected privately.
707#[derive(Debug, Clone, Serialize, Deserialize)]
708pub struct VoteRecord {
709    /// Judge seat number, 1-based.
710    pub judge: usize,
711    /// Agent occupying the seat.
712    pub agent: String,
713    /// The vote.
714    #[serde(default)]
715    pub vote: Option<char>,
716    /// Why.
717    #[serde(default)]
718    pub reason: String,
719    /// Did this judge move from its initial first choice?
720    #[serde(default)]
721    pub changed: bool,
722}
723
724/// A seat that was taken out by a CLI rate limit / quota, recorded so a run
725/// whose panel collapsed does not masquerade as a healthy one.
726#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
727pub struct QuotaLoss {
728    /// Machine-side cause; legacy losses are usage limits.
729    #[serde(default)]
730    pub cause: crate::agent::QuotaCause,
731    /// Agent that needs recovery (empty in legacy records).
732    #[serde(default)]
733    pub agent: String,
734    /// Seat key, e.g. `judge-1` or `review-2`.
735    pub seat: String,
736    /// Node that was running, e.g. `judge`, `vote`, `review`.
737    pub node: String,
738    /// When the CLI reported the limit.
739    pub at: Timestamp,
740    /// Reset hint if the CLI printed one, free text.
741    #[serde(default)]
742    pub reset: Option<String>,
743}
744
745impl QuotaLoss {
746    /// Preserve the cause and agent alongside the seat at every loss site.
747    pub fn from_report(seat: String, node: &str, quota: Option<&crate::agent::Quota>) -> Self {
748        Self {
749            seat,
750            node: node.to_owned(),
751            at: Timestamp::now(),
752            reset: quota.and_then(|q| q.reset.clone()),
753            cause: quota.map(|q| q.cause).unwrap_or_default(),
754            agent: quota.map(|q| q.agent.clone()).unwrap_or_default(),
755        }
756    }
757}
758
759/// A seat handed from one roster agent to the next after the first failed it
760/// (rate limit, timeout or an ordinary failure), recorded so the answer's
761/// author is never a mystery and a run that recovered on its second agent
762/// still says what it cost.
763#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
764pub struct Handover {
765    /// When the seat changed hands.
766    pub at: Timestamp,
767    /// Node that was running, e.g. `implement`, `judge`, `review`.
768    pub node: String,
769    /// Seat key, e.g. `impl-A` or `judge-2`.
770    pub seat: String,
771    /// Agent id that failed the seat.
772    pub from: String,
773    /// Agent id that took it over.
774    pub to: String,
775    /// Why: `rate limited (quota)`, `timed out`, or the failure's own message.
776    pub reason: String,
777}
778
779/// A newly created lockfile of a package manager the directory does not use,
780/// which a rescue commit left untracked instead of committing. Recorded so the
781/// omission is visible: the file may be one the task really wanted.
782#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
783pub struct Withheld {
784    /// Repo-relative path.
785    pub path: String,
786    /// The manager the file belongs to.
787    pub manager: String,
788    /// The tracked file (or missing manifest) that made it foreign.
789    pub kept_by: String,
790    /// Node whose rescue commit withheld it.
791    pub node: String,
792    /// When.
793    pub at: Timestamp,
794}
795
796/// The mechanical count.
797#[derive(Debug, Clone, Serialize, Deserialize)]
798pub struct Tally {
799    /// First-choice votes per label.
800    pub first_choice: BTreeMap<char, usize>,
801    /// Borda points from the initial rankings, used only to break a tie.
802    pub borda: BTreeMap<char, usize>,
803    /// The winning label.
804    pub winner: char,
805    /// How many judges produced a usable ranking. A panel of one is not a
806    /// consensus and must not be reported as a split.
807    #[serde(default)]
808    pub rankings: usize,
809    /// Did every judge's *initial* first choice agree?
810    pub unanimous_initial: bool,
811    /// Was deliberation run?
812    pub deliberated: bool,
813    /// Judges who moved between their initial ranking and their final vote.
814    pub changed_votes: usize,
815    /// Did the final votes agree?
816    pub unanimous_final: bool,
817    /// How the tie was broken, when it had to be.
818    #[serde(default)]
819    pub tie_break: Option<String>,
820    /// Configured judge count — the size of the full panel. `0` when no
821    /// panel was asked (see `uncontested`), not the roster size a panel that
822    /// never sat would have had.
823    #[serde(default)]
824    pub judges: usize,
825    /// Judges who actually contributed to the decision (not taken out by a
826    /// rate limit and producing a usable rank or vote).
827    #[serde(default)]
828    pub present: usize,
829    /// How many judges are required for a trustworthy verdict. Chosen as a
830    /// strict majority (`judges / 2 + 1`): a verdict backed by a minority must
831    /// never be presented as a healthy one, while a bare majority is still
832    /// real signal. A one-candidate run needs no quorum.
833    #[serde(default)]
834    pub quorum: usize,
835    /// `present >= quorum`, or no quorum was required.
836    #[serde(default)]
837    pub met_quorum: bool,
838    /// Why no panel was asked, when none was: a single viable candidate, or
839    /// a review-only run that never competed. `None` when judges actually
840    /// ranked and voted — including when too few of them survived to reach
841    /// quorum, which is a collapse and must keep reading as one.
842    #[serde(default)]
843    pub uncontested: Option<String>,
844}
845
846/// One reviewer's report in a round.
847#[derive(Debug, Clone, Serialize, Deserialize)]
848pub struct ReviewRecord {
849    /// Reviewer seat number, 1-based.
850    pub reviewer: usize,
851    /// Agent occupying the seat.
852    pub agent: String,
853    /// Reviewer prose.
854    #[serde(default)]
855    pub summary: String,
856    /// Findings, with magi-assigned ids.
857    #[serde(default)]
858    pub findings: Vec<Finding>,
859    /// This seat's initial vote. `None` on a record predating votes, exactly
860    /// like a round that genuinely had none cast — never a stand-in for a
861    /// vote that was lost.
862    #[serde(default)]
863    pub vote: Option<ReviewVote>,
864    /// Why this reviewer produced nothing.
865    #[serde(default)]
866    pub failed: Option<String>,
867    /// Wall-clock time.
868    #[serde(default)]
869    pub duration_ms: u64,
870    /// How many times this seat was asked before it settled — 0 for a first
871    /// answer, N after N nudges (`ask_json_wave`'s retry loop). Read this
872    /// together with [`Self::failed`], never `failed` alone: `failed: Some(_)`
873    /// with `attempts == 0` is a seat that never answered at all, while
874    /// `failed: None` with `attempts > 0` is one that only came back after a
875    /// nudge — recovered, not silent — and the two must not look the same in
876    /// history. A record written before this field existed defaults to `0`,
877    /// which under-reports a pre-existing retry rather than inventing one;
878    /// see `ask_json_wave`'s own doc for where this is filled in.
879    #[serde(default)]
880    pub attempts: usize,
881}
882
883/// One seat's revote during a round's reconsideration (see
884/// [`ReviewRound::reconsideration`]).
885#[derive(Debug, Clone, Serialize, Deserialize)]
886pub struct ReviewRevoteRecord {
887    /// Reviewer seat number, 1-based.
888    pub reviewer: usize,
889    /// Agent occupying the seat.
890    pub agent: String,
891    /// The revote. `None` when the seat did not answer.
892    #[serde(default)]
893    pub vote: Option<ReviewVote>,
894    /// Why.
895    #[serde(default)]
896    pub reason: String,
897    /// Why this seat produced no revote.
898    #[serde(default)]
899    pub failed: Option<String>,
900}
901
902/// Post-repair e2e evidence. An empty, unsuccessful record is a durable
903/// requirement saved before the fixer can change the winner.
904#[derive(Debug, Clone, Serialize, Deserialize)]
905pub struct GateRepairE2e {
906    /// Exact winner SHA requiring or receiving post-repair verification.
907    pub head: String,
908    /// All configured commands completed successfully on this SHA.
909    pub passed: bool,
910    /// Last command results; empty before verification starts.
911    pub outcomes: Vec<CommandOutcome>,
912}
913
914/// Superseded head-specific evidence; repair budgets remain on the run.
915#[derive(Debug, Clone, Serialize, Deserialize)]
916pub struct VerificationEvidence {
917    /// Replacement SHA, unknown when archived without a head change.
918    #[serde(default)]
919    pub superseded_by: Option<String>,
920    /// Archive time, unknown for records written before this field existed.
921    #[serde(default)]
922    pub archived_at: Option<Timestamp>,
923    /// Run-wide gate-fix rounds spent at archival, unknown for legacy records.
924    #[serde(default)]
925    pub fixes_spent: Option<usize>,
926    /// SHA of the superseded gate, unknown for legacy records.
927    pub gate_head: Option<String>,
928    /// Whether the superseded gate completed.
929    pub gate_ran: bool,
930    /// Original command results, including failures.
931    pub gate: Vec<CommandOutcome>,
932    /// Superseded verification independent of the review judgment.
933    pub e2e: Option<GateRepairE2e>,
934}
935
936/// One fix round spent on a failing `verify.gate`: which fixer, what it did to
937/// the tree, and the gate output it was shown.
938#[derive(Debug, Clone, Serialize, Deserialize)]
939pub struct GateFixRecord {
940    /// Agent that applied the fix.
941    pub agent: String,
942    /// The gate output the fixer was handed, tail-truncated.
943    pub failed: Vec<CommandOutcome>,
944    /// What the fixer said it changed.
945    #[serde(default)]
946    pub notes: String,
947    /// Did the fix produce a commit?
948    #[serde(default)]
949    pub committed: bool,
950    /// Why the fix step produced nothing.
951    #[serde(default)]
952    pub error: Option<String>,
953}
954
955/// One fixer round spent on a rebase that stopped on a conflict: which fixer,
956/// what it was shown and whether git says the rebase then finished.
957///
958/// The records at each sequencer stop count against `graph.review_rounds`,
959/// written to disk *before* the fixer runs so a park or crash cannot hand the
960/// round back.
961#[derive(Debug, Clone, Serialize, Deserialize)]
962pub struct RebaseFixRecord {
963    /// A machine outage deferred this call without spending a conflict round.
964    /// The record retains the original index baseline for safe resumption.
965    #[serde(default, skip_serializing_if = "Option::is_none")]
966    pub outage: Option<crate::agent::QuotaCause>,
967    /// Agent asked to resolve the conflict.
968    pub agent: String,
969    /// Paths git reported unmerged when the round started.
970    pub paths: Vec<String>,
971    /// The branch tip the rebase started from, so a resumed run can tell a
972    /// worktree still holding those files from one with edits of its own.
973    #[serde(default)]
974    pub from: Option<String>,
975    /// Did git report the rebase finished after the round?
976    #[serde(default)]
977    pub finished: bool,
978    /// Why the round produced nothing (agent failure, quota).
979    #[serde(default)]
980    pub error: Option<String>,
981    /// The commit the sequencer was replaying (`REBASE_HEAD`) when the round
982    /// started: which stop point the round belongs to. A record without it
983    /// predates launcher staging.
984    #[serde(default)]
985    pub stop: Option<String>,
986    /// Staged changes outside `paths` when the round started (Git's own
987    /// clean applications), so edits made behind them can be told apart. Retries
988    /// retain the first baseline for the stop; legacy baselines are rebuilt
989    /// from the original three-way merge and verified before being saved.
990    #[serde(default)]
991    pub index_outside: Option<String>,
992    /// How far the launcher got with staging and continuing this stop point.
993    #[serde(default)]
994    pub launcher: Option<LauncherStep>,
995    /// A denied or failed Git metadata write: infrastructure, not a conflict.
996    /// The rebase is kept standing and no further round is spent.
997    #[serde(default)]
998    pub infra: Option<String>,
999}
1000
1001/// Where launcher-owned staging of a resolved conflict stopped.
1002#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
1003#[serde(rename_all = "snake_case")]
1004pub enum LauncherStep {
1005    /// About to stage the validated paths (or doing it).
1006    Staging,
1007    /// Every conflicted path is staged; the sequencer was not continued yet.
1008    Staged,
1009    /// `rebase --continue` was started.
1010    Continuing,
1011}
1012
1013/// How the graft phase ended (see `graph::Runner::graft`).
1014#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1015#[serde(rename_all = "snake_case")]
1016pub enum GraftOutcome {
1017    /// The fixer's result was kept.
1018    Applied,
1019    /// Started but not finished: a record in this state on load means the
1020    /// process stopped mid-round and the winner is restored on resume.
1021    Running,
1022    /// The seat could not start; restore `pre` under coordination, then retry.
1023    WaitingForRestore,
1024    /// The winner's pre-graft commit was restored, with the reason.
1025    RolledBack(String),
1026}
1027
1028impl GraftOutcome {
1029    /// Is the record final, i.e. must a resume leave it alone?
1030    pub fn settled(&self) -> bool {
1031        !matches!(
1032            self,
1033            GraftOutcome::Running | GraftOutcome::WaitingForRestore
1034        )
1035    }
1036}
1037
1038/// The graft phase's record: what ran, on which commits, and how it ended.
1039/// `pre` and a `Running` outcome are saved before the fixer is called.
1040#[derive(Debug, Clone, Serialize, Deserialize)]
1041pub struct GraftRecord {
1042    /// The winner's commit before the graft; restored on a rollback.
1043    pub pre: String,
1044    /// The winner's commit after an applied graft.
1045    #[serde(default)]
1046    pub post: Option<String>,
1047    /// Changed lines (added + removed) the graft introduced, when measured.
1048    #[serde(default)]
1049    pub lines: Option<usize>,
1050    /// Historical size limit, retained for old records only. New grafts use `None`.
1051    #[serde(default)]
1052    pub limit: Option<usize>,
1053    /// Agent that answered the round.
1054    #[serde(default)]
1055    pub agent: Option<String>,
1056    /// How it ended.
1057    pub outcome: GraftOutcome,
1058    /// The strengths the fixer was asked to port, with the ids the prompt
1059    /// gave them. Empty on a record written before they were kept.
1060    #[serde(default)]
1061    pub requested: Vec<GraftStrength>,
1062    /// What the fixer reported it did with them; `None` when it gave no usable
1063    /// report (see `adoption_error`) or the record predates this field.
1064    #[serde(default)]
1065    pub adoption: Option<GraftAdoption>,
1066    /// Why `adoption` is absent although the fixer answered.
1067    #[serde(default)]
1068    pub adoption_error: Option<String>,
1069}
1070
1071/// One strength a judge attributed to a losing candidate, as the graft
1072/// prompt listed it.
1073#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1074pub struct GraftStrength {
1075    /// Id in the prompt, e.g. `A1`.
1076    pub id: String,
1077    /// The candidate it was observed in.
1078    pub source: char,
1079    /// The strength, already blind-sanitized.
1080    pub text: String,
1081}
1082
1083/// The fixer's own account of a graft round. It is a claim, not a check: the
1084/// diff is what actually changed.
1085#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
1086pub struct GraftAdoption {
1087    /// Ids (or texts) the fixer says it ported.
1088    #[serde(default)]
1089    pub addressed: Vec<String>,
1090    /// Ids (or texts) it declined, with the reason.
1091    #[serde(default)]
1092    pub rejected: Vec<GraftRejection>,
1093    /// The report's `notes`.
1094    #[serde(default)]
1095    pub notes: String,
1096    /// The reasoning that preceded the report.
1097    #[serde(default)]
1098    pub reasoning: String,
1099}
1100
1101/// A strength the fixer declined.
1102#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1103pub struct GraftRejection {
1104    /// Id or text as the fixer wrote it.
1105    pub id: String,
1106    /// Its argument.
1107    #[serde(default)]
1108    pub why: String,
1109}
1110
1111/// The fixer's response to a round.
1112#[derive(Debug, Clone, Serialize, Deserialize)]
1113pub struct FixRecord {
1114    /// Agent that applied the fixes.
1115    pub agent: String,
1116    /// Finding ids acted on.
1117    #[serde(default)]
1118    pub addressed: Vec<String>,
1119    /// Findings declined, with reasons.
1120    #[serde(default)]
1121    pub rejected: Vec<Rejection>,
1122    /// What changed.
1123    #[serde(default)]
1124    pub notes: String,
1125    /// Did the fix produce a commit?
1126    #[serde(default)]
1127    pub committed: bool,
1128    /// Why the fix step produced nothing.
1129    #[serde(default)]
1130    pub failed: Option<String>,
1131    /// Wall-clock time.
1132    #[serde(default)]
1133    pub duration_ms: u64,
1134    /// How the fixer's own seat was made to answer when its CLI turn ended
1135    /// cleanly but without an addressed/rejected report — see
1136    /// [`graph::Runner::continue_fix_report`]. `None` for a record written
1137    /// before this existed, which must read as "unknown", not as
1138    /// [`ContinuationOutcome::NotNeeded`]: an old run really may have hit
1139    /// this exact gap and simply had no mechanism to say so.
1140    #[serde(default)]
1141    pub continuation: Option<ContinuationRecord>,
1142}
1143
1144/// How a node recovered — or failed to recover — a structured report after
1145/// the CLI's own turn ended cleanly (a usable, non-empty, exit-0 reply)
1146/// without it. A clean CLI turn is not the same fact as the node's own work
1147/// being done — see the `fix` node's `continue_fix_report`, which is what
1148/// produces this.
1149#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1150pub enum ContinuationOutcome {
1151    /// The first reply already carried the report; nothing was resumed.
1152    NotNeeded,
1153    /// A follow-up call in the same session recovered the report.
1154    Resumed,
1155    /// The continuation budget was spent without ever recovering it.
1156    Exhausted,
1157    /// A continuation attempt hit the CLI's rate limit; not retried further
1158    /// — a quota fails the same way again immediately.
1159    QuotaLost,
1160    /// No session was left to resume into, so nothing was attempted.
1161    NoSession,
1162}
1163
1164/// Cost and outcome of one node's attempt to recover a missing report by
1165/// resuming its own seat.
1166#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
1167pub struct ContinuationRecord {
1168    /// Follow-up calls made to the same seat. `0` when the outcome is
1169    /// [`ContinuationOutcome::NotNeeded`] or [`ContinuationOutcome::NoSession`].
1170    pub attempts: usize,
1171    /// Wall-clock time spent on those follow-up calls, summed — not counting
1172    /// the original call whose reply this is recovering from.
1173    pub cumulative_wait_ms: u64,
1174    /// What ended the loop.
1175    pub outcome: ContinuationOutcome,
1176}
1177
1178impl ContinuationRecord {
1179    /// The report was already there on the first try.
1180    pub fn not_needed() -> Self {
1181        Self {
1182            attempts: 0,
1183            cumulative_wait_ms: 0,
1184            outcome: ContinuationOutcome::NotNeeded,
1185        }
1186    }
1187}
1188
1189/// What happened to one operator-selected finding after the fixer ran, as
1190/// part of an [`OperatorFixRequest`].
1191#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
1192#[serde(rename_all = "snake_case")]
1193pub enum OperatorFixOutcome {
1194    /// The request has not run yet, or never got far enough to report.
1195    #[default]
1196    Pending,
1197    /// The fixer's adoption report named this finding as addressed.
1198    Addressed,
1199    /// The fixer's adoption report declined it, with an argument.
1200    Rejected {
1201        /// The fixer's own reason.
1202        why: String,
1203    },
1204    /// The fixer never delivered a usable adoption report at all — a
1205    /// dropped stream, a quota hit, or a continuation budget spent without
1206    /// recovering one (see `graph::Runner::continue_fix_report`). Distinct
1207    /// from `Rejected`, which needs an argument this never produced, and
1208    /// never written back as "addressed" or silently left `Pending` — a
1209    /// gap in the report is its own outcome, not evidence either way about
1210    /// the finding.
1211    Unreported,
1212}
1213
1214/// One finding an operator selected for [`OperatorFixRequest`], with the
1215/// provenance a reviewer originally gave it, copied here verbatim.
1216///
1217/// Severity and vote are snapshots, never recomputed and never treated as
1218/// blocking just because an operator picked the finding — only
1219/// [`Severity::blocks`] on the original [`ReviewRecord`] decides that. This
1220/// type exists so an operator's selection is an auditable *addition* to the
1221/// record, not a rewrite of what a reviewer actually said.
1222#[derive(Debug, Clone, Serialize, Deserialize)]
1223pub struct OperatorFixFinding {
1224    /// Finding id, e.g. `R2-1-3`.
1225    pub id: String,
1226    /// Severity as the reviewer recorded it.
1227    pub severity: Severity,
1228    /// The reviewer seat's overall vote for the round this finding came
1229    /// from, if one was cast.
1230    #[serde(default)]
1231    pub reviewer_vote: Option<ReviewVote>,
1232    /// Review round the finding was raised in.
1233    pub round: usize,
1234    /// That round's own head — the commit the finding was actually raised
1235    /// against, used for the freshness check against the branch's current
1236    /// head at request time.
1237    pub round_head: String,
1238    /// Reviewer seat number, 1-based.
1239    pub reviewer: usize,
1240    /// Agent occupying that seat.
1241    pub agent: String,
1242    /// File the finding concerns.
1243    #[serde(default)]
1244    pub file: Option<String>,
1245    /// Line the finding concerns.
1246    #[serde(default)]
1247    pub line: Option<u32>,
1248    /// One-line summary.
1249    pub title: String,
1250    /// The argument.
1251    #[serde(default)]
1252    pub detail: String,
1253    /// What happened to this finding after the fixer ran.
1254    #[serde(default)]
1255    pub outcome: OperatorFixOutcome,
1256}
1257
1258/// One `magi fix` invocation: the operator's own record of which
1259/// already-recorded findings they routed to a fixer, why, and what came
1260/// back. See [`SCHEMA`]'s doc for schema 9 on why this is a channel of its
1261/// own rather than a field on [`ReviewRound`].
1262#[derive(Debug, Clone, Serialize, Deserialize)]
1263pub struct OperatorFixRequest {
1264    /// When `magi fix` was invoked.
1265    pub requested_at: Timestamp,
1266    /// The operator's own reasoning. Required and never empty at the CLI —
1267    /// the audit trail this feature exists for.
1268    pub reason: String,
1269    /// The findings selected, each with its own provenance and outcome.
1270    pub findings: Vec<OperatorFixFinding>,
1271    /// The branch's head at the moment this request started executing.
1272    pub head_at_request: String,
1273    /// Did the operator pass `--allow-stale`?
1274    pub allow_stale: bool,
1275    /// Did any selected finding's own `round_head` differ from
1276    /// `head_at_request`? Kept distinct from `allow_stale` — flipping that
1277    /// flag does not retroactively make a request that was actually fresh
1278    /// read as stale, or the reverse.
1279    pub stale: bool,
1280    /// The fixer's own attempt, once dispatched.
1281    #[serde(default)]
1282    pub fix: Option<FixRecord>,
1283    /// Head after the fixer's commit, when it produced one.
1284    #[serde(default)]
1285    pub result_head: Option<String>,
1286    /// The review-only run opened to re-verify the change, when one was
1287    /// actually committed. `None` when nothing changed, so there was
1288    /// nothing new to re-review — never left implicit as "not gotten to
1289    /// yet".
1290    #[serde(default)]
1291    pub follow_up_review_run: Option<String>,
1292}
1293
1294/// A command a seat's own CLI reported running, kept for `magi show` and for
1295/// telling "this seat's turn ended" apart from "the process it started is
1296/// done" — see `agent::CommandEvidence`, which is the only source this is
1297/// ever built from. Never something magi polled or supervised; a command the
1298/// CLI never reported finishing (or a CLI this crate has no adapter for at
1299/// all) simply has no entry here, which must read as "unknown", not as
1300/// "nothing ran".
1301#[derive(Debug, Clone, Serialize, Deserialize)]
1302pub struct JobRecord {
1303    /// Graph node the seat belongs to, e.g. `"implement"`, `"fix"`.
1304    pub node: String,
1305    /// Review round this job belongs to, for a `"review"`/`"fix"` node —
1306    /// `None` for every other node, where rounds do not apply, and for every
1307    /// record written before this was tracked. Lets a reader ask "what did
1308    /// this seat itself actually run this round", distinct from and never
1309    /// substituted for magi's own recorded `ReviewRound::e2e` — an absent
1310    /// entry here means unobserved, not that nothing ran (see this type's
1311    /// own doc).
1312    #[serde(default)]
1313    pub round: Option<usize>,
1314    /// Seat key, e.g. `"impl-A"`.
1315    pub seat: String,
1316    /// The CLI's own id for this command.
1317    pub id: String,
1318    /// The command itself, as the CLI reported it.
1319    pub description: String,
1320    /// When this evidence was captured — the moment this seat's reply
1321    /// carrying it was read, not the command's own start time, which no
1322    /// adapter here currently has. A lower bound on staleness only.
1323    pub checked_at: Timestamp,
1324    /// What the CLI reported for it.
1325    pub status: JobStatus,
1326    /// Exit code the CLI reported.
1327    pub exit_code: Option<i32>,
1328    /// Tail of the command's own output, when reported.
1329    #[serde(default)]
1330    pub result_summary: String,
1331    /// Which CLI/event stream this came from, e.g. `"codex"`.
1332    pub source: String,
1333}
1334
1335/// What a [`JobRecord`]'s own CLI reported for it. There is no `Running`
1336/// variant: nothing here is ever polled live, so "still running" and
1337/// "finished but never reported" are the same absence of evidence, not a
1338/// state this type can name — see [`JobRecord`]'s own doc.
1339#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
1340pub enum JobStatus {
1341    /// The command's own reported exit code was `0`.
1342    Completed,
1343    /// The command's own reported exit code was non-zero.
1344    Failed,
1345    /// The CLI reported this command but not a readable exit code.
1346    Unknown,
1347}
1348
1349/// Outcome of one shell command.
1350#[derive(Debug, Clone, Serialize, Deserialize)]
1351pub struct CommandOutcome {
1352    /// The command, as configured.
1353    pub command: String,
1354    /// Exit code, `None` on timeout or signal.
1355    pub code: Option<i32>,
1356    /// Tail of the combined output, for the report and the fix prompt.
1357    #[serde(default)]
1358    pub output_tail: String,
1359    /// Wall-clock time.
1360    #[serde(default)]
1361    pub duration_ms: u64,
1362    /// Set only by magi itself, never inferred from `output_tail`: the
1363    /// configured command was never actually run because a resource it
1364    /// needs — right now, only the shared build cache's lease or the
1365    /// freshness check that must precede using it — was not available
1366    /// within budget. Distinct from an ordinary failure or timeout (both of
1367    /// which *did* run something and are evidence about the patch); this is
1368    /// evidence about the machine, and must never be read as a verdict on
1369    /// the tree it named. `#[serde(default)]` so every record written
1370    /// before this field existed keeps reading as `false` — exactly what it
1371    /// was.
1372    #[serde(default)]
1373    pub resource_blocked: bool,
1374}
1375
1376/// Substrings that mark a Cargo/rustc/link failure: the toolchain could not
1377/// produce a binary to run at all, as opposed to producing one that ran and
1378/// failed. A Windows link race against a shared `CARGO_TARGET_DIR` (see
1379/// AGENTS.md, "Running magi on magi") looks exactly like a red command
1380/// otherwise, and a run has concluded `Blocked` on nothing but that race.
1381const BUILD_FAILURE_MARKERS: &[&str] = &[
1382    "error: could not compile",
1383    "error: linking with",
1384    "LINK : fatal error",
1385    "fatal error LNK",
1386];
1387
1388impl CommandOutcome {
1389    /// Did it pass?
1390    pub fn ok(&self) -> bool {
1391        self.code == Some(0)
1392    }
1393
1394    /// Did this command fail because the code could not be built or linked,
1395    /// rather than because it ran and produced a wrong result? A failure here
1396    /// is not a verdict on the patch under review.
1397    pub fn build_failed(&self) -> bool {
1398        !self.ok()
1399            && !self.resource_blocked
1400            && BUILD_FAILURE_MARKERS
1401                .iter()
1402                .any(|m| self.output_tail.contains(m))
1403    }
1404}
1405
1406/// One review + verify + fix round.
1407#[derive(Debug, Clone, Serialize, Deserialize)]
1408pub struct ReviewRound {
1409    /// 1-based round number.
1410    pub round: usize,
1411    /// Commit the round reviewed.
1412    pub head: String,
1413    /// The commit `e2e` was actually attempted against. Set whenever an
1414    /// attempt was dispatched (`e2e_status()` reads `Passed`, `Failed`, or
1415    /// `ResourceBlocked`), naming that commit even when it equals `head` —
1416    /// never left implicit, because an implicit "must have been `head`" is
1417    /// exactly what let a later round quote an earlier round's result
1418    /// without saying which commit it came from. A resource-blocked attempt
1419    /// still targeted a specific commit even though no command finished, and
1420    /// leaving that unrecorded is exactly what made a *fresh* blocked
1421    /// attempt read the same as an untracked one from before schema 8.
1422    /// `None` only when nothing was attempted at all (`NotConfigured`,
1423    /// `Deferred`). See `SCHEMA`'s doc for schema 8 for why this broadened
1424    /// from only the catch-up-on-a-different-commit case.
1425    #[serde(default)]
1426    pub verified_head: Option<String>,
1427    /// When the attempt behind `verified_head` actually ran. `None` on
1428    /// every record written before schema 8, and on a round where nothing
1429    /// ran —
1430    /// both read as "unknown", not as "now" or "never asked".
1431    #[serde(default)]
1432    pub verified_at: Option<Timestamp>,
1433    /// Reviewer reports.
1434    pub reviews: Vec<ReviewRecord>,
1435    /// E2E command outcomes for this round.
1436    #[serde(default)]
1437    pub e2e: Vec<CommandOutcome>,
1438    /// True when the first verify attempt this round could not build or
1439    /// link, and `e2e` above holds a second attempt run before concluding.
1440    /// A run must never be decided on a red it could not tell from an
1441    /// unrelated build race.
1442    #[serde(default)]
1443    pub verify_retried: bool,
1444    /// True when `e2e` was intentionally left empty this round: the round
1445    /// already had blocking findings and another round was available, so
1446    /// `graph::Runner::review_loop` sent the fixer straight at them instead
1447    /// of spending a full verify run on a head it already knew would need
1448    /// another fix. Distinct from an `e2e` that is simply empty because
1449    /// `verify.e2e` has no commands configured — `e2e.is_empty()` alone
1450    /// cannot tell those apart, and conflating them is exactly how a
1451    /// deferred check would get painted green. A record written before this
1452    /// field existed defaults to `false`, which is the truth for it: every
1453    /// round used to run e2e unconditionally.
1454    #[serde(default)]
1455    pub e2e_deferred: bool,
1456    /// Why `e2e` was deferred, set only when [`Self::e2e_deferred`] is true.
1457    /// Carried to the fixer's prompt and shown in the report so "deferred"
1458    /// never reads as silence.
1459    #[serde(default)]
1460    pub e2e_defer_reason: Option<String>,
1461    /// Fixer response, absent when the round was already clean.
1462    #[serde(default)]
1463    pub fix: Option<FixRecord>,
1464    /// Findings that hold the merge.
1465    #[serde(default)]
1466    pub blocking: usize,
1467    /// Reviewer seats that answered (did not time out, crash, or return
1468    /// something unparsable).
1469    #[serde(default)]
1470    pub answered: usize,
1471    /// Reviewer seats the round expected an answer from — normally
1472    /// `graph.reviewers`, but recorded per round so a config change between
1473    /// runs never has to be inferred from history.
1474    #[serde(default)]
1475    pub expected: usize,
1476    /// Round ended with no blocking findings and green verification, judged
1477    /// against the seats that answered. See [`Self::incomplete`] for whether
1478    /// that verdict is missing input.
1479    #[serde(default)]
1480    pub clean: bool,
1481    /// Did the tree actually move against `base` this round, comparing the
1482    /// diff after the fix to the diff the reviewers saw at the start of the
1483    /// round?
1484    ///
1485    /// Never derived from the fixer's own `addressed`/`rejected` count: that
1486    /// self-report has been caught lying twice on this workload (runs `b455`
1487    /// and `6218`, both of which committed a real, substantial diff while
1488    /// reporting `0 addressed`). `git` does not lie about whether the tree
1489    /// changed, so this is what `graph::Runner::review_loop` counts rounds of
1490    /// no progress against. Absent on a round with no fix attempt (already
1491    /// clean, or the round the budget ran out on), where it defaults to
1492    /// `false` and is not consulted.
1493    #[serde(default)]
1494    pub progressed: bool,
1495    /// Did the seats' initial votes ([`ReviewRecord::vote`]) disagree?
1496    #[serde(default)]
1497    pub vote_split: bool,
1498    /// One round of revoting, run only when `vote_split`: each seat that cast
1499    /// an initial vote reads every seat's findings and votes, then revotes.
1500    /// Empty when the initial votes already agreed, the same as a solo
1501    /// candidate leaving `deliberation` empty.
1502    #[serde(default)]
1503    pub reconsideration: Vec<ReviewRevoteRecord>,
1504    /// The round's verdict: the most cautious vote among the seats that
1505    /// answered, using each seat's revote where reconsideration ran and its
1506    /// initial vote otherwise. `None` when no seat produced a usable vote —
1507    /// including every record written before votes existed, which is the
1508    /// truth for those rounds, not a gap in this one.
1509    #[serde(default)]
1510    pub verdict: Option<ReviewVote>,
1511}
1512
1513/// A merge-approval question and the head commit it was asked about.
1514#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1515pub struct LandApproval {
1516    /// Id of the question that was filed for `head`.
1517    pub question: String,
1518    /// The commit the question's panel was built from.
1519    pub head: String,
1520}
1521
1522/// Independent public description of a run's whole change from the final diff.
1523/// Valid only for its (`head`, `base`, `evidence`) snapshot; a changed commit,
1524/// generation policy, verification result or finding requires regeneration.
1525#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1526pub struct ChangeSummary {
1527    /// The final commit the diff was read at.
1528    pub head: String,
1529    /// The merge base of the resolved remote base and `head`.
1530    pub base: String,
1531    /// Generation specification and verification/finding evidence fingerprint.
1532    /// Missing on older records, which must be regenerated.
1533    #[serde(default)]
1534    pub evidence: String,
1535    /// Title, sanitized.
1536    pub title: String,
1537    /// Body, sanitized, without the run marker.
1538    pub body: String,
1539}
1540
1541/// The owner question filed when the posting gate withheld a pull request
1542/// title or description, and how it ended. One record per rejected text
1543/// (`fingerprint`); see `github_text` for the flow.
1544#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1545pub struct GithubTextAsk {
1546    /// Hash of the rejected original title and body.
1547    pub fingerprint: String,
1548    /// The title is withheld.
1549    pub title: bool,
1550    /// The description is withheld.
1551    pub body: bool,
1552    /// Rule categories that fired.
1553    pub categories: Vec<String>,
1554    /// The question currently standing, if one was filed.
1555    #[serde(default)]
1556    pub question: Option<String>,
1557    /// Questions filed so far (at most 2: the second follows a bad reply).
1558    #[serde(default)]
1559    pub asks: u32,
1560    /// The decision has been made (saved before the pull request is opened,
1561    /// so it is applied once and survives a restart).
1562    #[serde(default)]
1563    pub resolved: bool,
1564    /// With `resolved`: the owner's vetted replacement title; `None` means the
1565    /// neutral text for every withheld field.
1566    #[serde(default)]
1567    pub chosen_title: Option<String>,
1568    /// With `resolved`: which way the question was settled. `None` on a record
1569    /// written before this field existed (read as the neutral text).
1570    #[serde(default)]
1571    pub choice: Option<GithubTextChoice>,
1572    /// Final rejected rewrite, kept locally for display and an explicit override.
1573    #[serde(default)]
1574    pub rewrite: Option<GithubTextRewrite>,
1575    /// Set only after the selected text was successfully published to the forge.
1576    #[serde(default, skip_serializing_if = "Option::is_none")]
1577    pub publication: Option<GithubTextPublication>,
1578}
1579
1580/// Durable application proof, distinct from choosing a publication payload.
1581#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1582pub struct GithubTextPublication {
1583    /// Exact source inquiry whose selected text was posted.
1584    pub inquiry: String,
1585    /// Original withheld text identity.
1586    pub fingerprint: String,
1587    /// Applied selection.
1588    pub choice: GithubTextChoice,
1589    /// Confirmed publication destination.
1590    pub url: String,
1591}
1592
1593/// A usable rewrite that still failed the posting gate.
1594#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1595pub struct GithubTextRewrite {
1596    /// Final title after redaction.
1597    pub title: String,
1598    /// Final description after redaction and run marker insertion.
1599    pub body: String,
1600    /// Stable rule categories, never sensitive values.
1601    pub failed: Vec<String>,
1602}
1603
1604/// How a withheld pull request text was settled.
1605#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
1606#[serde(rename_all = "kebab-case")]
1607pub enum GithubTextChoice {
1608    /// The changed text: neutral for language, redacted for sensitive data
1609    /// (also silence, abandonment and an unknown answer).
1610    Fallback,
1611    /// The owner's vetted replacement title (`chosen_title`).
1612    MyTitle,
1613    /// The original text of every withheld field, past the posting gate.
1614    Original,
1615    /// The saved rewrite title and body, unmodified, past the posting gate.
1616    Rewrite,
1617}
1618
1619/// A review hand-off the panel did not agree to: findings that hold the merge
1620/// are still open and at least one seat's final vote was reject. Recorded on
1621/// [`RunState::contested_handoff`] so `land` can name them in its question.
1622#[derive(Debug, Clone, Serialize, Deserialize)]
1623pub struct ContestedHandoff {
1624    /// Open findings of severity Major or above, in report order.
1625    pub findings: Vec<Finding>,
1626    /// Seats (1-based) whose final vote was reject, with the agent in the seat.
1627    pub rejecters: Vec<(usize, String)>,
1628}
1629
1630pub use crate::review_repair::{Phase as MergeRepairPhase, Request as MergeRepair};
1631
1632impl ReviewRound {
1633    /// Each answering seat's final vote: its revote where reconsideration ran
1634    /// and answered, its initial vote otherwise. The single place this is
1635    /// decided, shared by the round's verdict and [`Self::contested_handoff`].
1636    pub fn final_votes(&self) -> Vec<(usize, String, ReviewVote)> {
1637        self.reviews
1638            .iter()
1639            .filter_map(|r| {
1640                self.reconsideration
1641                    .iter()
1642                    .find(|rv| rv.reviewer == r.reviewer)
1643                    .and_then(|rv| rv.vote)
1644                    .or(r.vote)
1645                    .map(|v| (r.reviewer, r.agent.clone(), v))
1646            })
1647            .collect()
1648    }
1649
1650    /// Is this round's hand-off contested: a Major-or-above finding open and
1651    /// at least one final vote of reject? `None` otherwise. Kept as one small
1652    /// function so anything deciding on it reads the same answer.
1653    pub fn contested_handoff(&self) -> Option<ContestedHandoff> {
1654        let findings: Vec<Finding> = self
1655            .reviews
1656            .iter()
1657            .flat_map(|r| r.findings.iter())
1658            .filter(|f| f.severity.blocks())
1659            .cloned()
1660            .collect();
1661        if findings.is_empty() {
1662            return None;
1663        }
1664        let rejecters: Vec<(usize, String)> = self
1665            .final_votes()
1666            .into_iter()
1667            .filter(|(_, _, v)| *v == ReviewVote::Reject)
1668            .map(|(seat, agent, _)| (seat, agent))
1669            .collect();
1670        if rejecters.is_empty() {
1671            return None;
1672        }
1673        Some(ContestedHandoff {
1674            findings,
1675            rejecters,
1676        })
1677    }
1678
1679    /// Did at least one reviewer seat fail to answer this round?
1680    pub fn incomplete(&self) -> bool {
1681        self.answered < self.expected
1682    }
1683
1684    /// The honest state of this round's e2e leg.
1685    ///
1686    /// Never derive this from `e2e.is_empty()` alone anywhere else in the
1687    /// codebase — `NotConfigured` and `Deferred` both leave it empty, and
1688    /// only this method (backed by [`Self::e2e_deferred`]) tells them apart.
1689    /// A resource-blocked attempt is checked first and ahead of both: `e2e`
1690    /// is non-empty for it too, but `CommandOutcome::resource_blocked` says
1691    /// no command actually ran, and reading that as `Failed` is exactly how
1692    /// shared build-cache contention gets misreported as a verdict on the
1693    /// patch (see `CommandOutcome::resource_blocked`'s own doc).
1694    pub fn e2e_status(&self) -> E2eStatus {
1695        if self.e2e.iter().any(|o| o.resource_blocked) {
1696            E2eStatus::ResourceBlocked
1697        } else if !self.e2e.is_empty() {
1698            if self.e2e.iter().all(CommandOutcome::ok) {
1699                E2eStatus::Passed
1700            } else {
1701                E2eStatus::Failed
1702            }
1703        } else if self.e2e_deferred {
1704            E2eStatus::Deferred
1705        } else {
1706            E2eStatus::NotConfigured
1707        }
1708    }
1709
1710    /// Facts about this round's verification leg, judged against
1711    /// `current_head` — the commit whoever is asking is actually looking at
1712    /// right now. `None` when there is nothing worth surfacing: no
1713    /// `verify.e2e` configured, or the round's own check came back green (a
1714    /// passing result needs no skepticism attached to it, and an unread
1715    /// `None` is exactly what keeps a quiet round quiet instead of padding
1716    /// every prompt with "everything was fine").
1717    ///
1718    /// This is the single place that turns `e2e`/`e2e_deferred`/
1719    /// `verified_head`/`verified_at` into text. Every prompt and report that
1720    /// shows a round's verification result must build its wording from this,
1721    /// not re-derive its own summary at the call site — a hand-rolled
1722    /// version at one more place is exactly how "an old red read as today's
1723    /// answer" comes back through a different door (see the incident this
1724    /// type exists to prevent, recorded alongside `SCHEMA`'s doc for schema
1725    /// 8).
1726    pub fn verification_summary(&self, current_head: &str) -> Option<VerificationSummary> {
1727        let status = self.e2e_status();
1728        if matches!(status, E2eStatus::NotConfigured | E2eStatus::Passed) {
1729            return None;
1730        }
1731        let commit = match &self.verified_head {
1732            Some(h) if h == current_head => {
1733                format!("commit {} (this is the head being looked at now)", short(h))
1734            }
1735            Some(h) => format!("commit {} (an earlier head, since superseded)", short(h)),
1736            None => "commit unknown (no command finished checking one)".to_owned(),
1737        };
1738        let checked_at = match self.verified_at {
1739            Some(t) => format!("checked at {t}"),
1740            None => "checked at: unknown (recorded before this was tracked)".to_owned(),
1741        };
1742        let result = match status {
1743            E2eStatus::NotConfigured | E2eStatus::Passed => unreachable!("checked above"),
1744            E2eStatus::Failed => "result: FAILED".to_owned(),
1745            E2eStatus::Deferred => format!(
1746                "result: not run this round yet — deferred to the fixer{}. Not passed, not \
1747                 failed.",
1748                self.e2e_defer_reason
1749                    .as_deref()
1750                    .map(|why| format!(" ({why})"))
1751                    .unwrap_or_default()
1752            ),
1753            E2eStatus::ResourceBlocked => "result: could not run — a required resource was \
1754                                            not available. This is evidence about the machine, \
1755                                            not about the patch."
1756                .to_owned(),
1757        };
1758        let label = format!("round {}, {commit}, {checked_at}\n{result}", self.round);
1759        // `Failed` names the command that actually ran and failed;
1760        // `ResourceBlocked` names the operation magi was waiting on (or the
1761        // freshness check it could not confirm) — `command` still says what
1762        // was attempted even though nothing finished, and leaving it out is
1763        // exactly how a reviewer or fixer lost the one thing this leg *can*
1764        // still tell them: what was being checked, not whether it passed.
1765        let tail = matches!(status, E2eStatus::Failed | E2eStatus::ResourceBlocked).then(|| {
1766            self.e2e
1767                .iter()
1768                .filter(|o| !o.ok())
1769                .map(|o| format!("$ {}\n{}\n", o.command, o.output_tail))
1770                .collect::<String>()
1771        });
1772        Some(VerificationSummary { label, tail })
1773    }
1774}
1775
1776/// The honest state of a round's e2e leg. See [`ReviewRound::e2e_status`].
1777#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1778pub enum E2eStatus {
1779    /// `verify.e2e` has no commands configured.
1780    NotConfigured,
1781    /// Skipped this round on purpose: blocking findings already required a
1782    /// fix, so the round went straight to the fixer instead of spending a
1783    /// full verify run on a head it already knew would need another pass.
1784    Deferred,
1785    /// Ran, and every command exited 0.
1786    Passed,
1787    /// Ran, and at least one command did not exit 0.
1788    Failed,
1789    /// Magi could not even get a command to run — the shared build cache's
1790    /// lease or freshness check was not available within budget. Evidence
1791    /// about the machine, never a verdict on the tree it named; must not be
1792    /// shown or counted the same as [`Self::Failed`].
1793    ResourceBlocked,
1794}
1795
1796/// [`ReviewRound::verification_summary`]'s output: the facts, pre-worded, for
1797/// a prompt or report to place under its own heading. Kept as two pieces
1798/// rather than one pre-joined string so a caller that wants to insert its own
1799/// note between the label and the raw command tail (see `prompt::review`) can
1800/// do so without re-parsing text back apart.
1801#[derive(Debug, Clone)]
1802pub struct VerificationSummary {
1803    /// Round, commit, freshness and result — always present.
1804    pub label: String,
1805    /// Raw `$ command` / output tail, present for `result: FAILED` and for
1806    /// a resource-blocked attempt (naming the operation magi was waiting on,
1807    /// even though nothing finished) — absent for every other result, which
1808    /// has nothing to add past the label.
1809    pub tail: Option<String>,
1810}
1811
1812/// The honest state of a run's final gate. See [`RunState::gate_status`].
1813#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1814pub enum GateStatus {
1815    /// Never attempted, or the last attempt was resource-blocked (the shared
1816    /// build cache could not be acquired or confirmed fresh in time) and
1817    /// needs a retry.
1818    NotRun,
1819    /// No gate commands were configured. This is not successful verification.
1820    NotConfigured,
1821    /// Ran one or more commands, and every one of them exited 0.
1822    Passed,
1823    /// Ran one or more commands, and at least one did not exit 0.
1824    Failed,
1825}
1826
1827impl GateStatus {
1828    /// May a run in this state proceed to merge?
1829    pub fn ok(self) -> bool {
1830        matches!(self, Self::Passed)
1831    }
1832}
1833
1834/// What happened to the winning branch.
1835#[derive(Debug, Clone, Serialize, Deserialize)]
1836pub struct MergeOutcome {
1837    /// Requested mode.
1838    pub mode: MergeMode,
1839    /// Did the requested operation succeed? Publication and no-op success do not prove a merge.
1840    pub ok: bool,
1841    /// Command output, or the command the operator should run.
1842    #[serde(default)]
1843    pub detail: String,
1844    /// The winner had no commits ahead of the base, so no pull request was
1845    /// attempted. Distinct from a `gh` failure: nothing was wrong with the
1846    /// tooling, there was simply nothing to land.
1847    #[serde(default)]
1848    pub empty: bool,
1849}
1850
1851/// A seat currently mid-answer: a prompt was sent and no reply has landed yet.
1852///
1853/// This is not the whole story of "is it alive" — a daemon killed mid-wave
1854/// leaves its last wave's entries here forever, since nothing ran to clear
1855/// them. A reader must cross-check a live daemon's heartbeat
1856/// (`daemon::is_working_on`) before trusting one of these as "still running"
1857/// rather than "abandoned". [`RunState::clear_active`] is what keeps that
1858/// leftover from surviving into the next attempt at this run: `execute` calls
1859/// it before doing anything else, so a resumed run never carries a stale
1860/// entry into its own report before the next wave repopulates it.
1861///
1862/// Deliberately carries no agent id: an implementer's agent is no secret, but
1863/// a judge or reviewer seat is blind (`SeatState::key` is keyed by seat, never
1864/// agent, for exactly this reason), and this struct has no way to tell which
1865/// kind of seat it describes. The seat key alone — already in the map this
1866/// lives under — is what every caller needs to say which seat is running.
1867///
1868/// The same map also carries entries for shell-command work that runs
1869/// outside any seat — `verify.e2e`, `verify.gate` — keyed by the task's own
1870/// name (`"e2e"`, `"gate"`) rather than a seat key. [`Self::task`] is `Some`
1871/// only for those; it is how a reader tells the two kinds of entry apart
1872/// without a second map, a second route, or a second SSE reason to poll for
1873/// — see [`RunState::seats_active`] / [`RunState::tasks_active`] for the
1874/// accessors that split them back apart. A task entry is exactly as blind as
1875/// a seat entry: no agent runs it, so there is nothing to leak, and
1876/// [`Self::command`] carries only the shell command being run, never
1877/// anything about who is running it.
1878#[derive(Debug, Clone, Serialize, Deserialize)]
1879pub struct ActiveSeat {
1880    /// Node the seat is answering for, e.g. `implement`, `judge`, `review`.
1881    /// For a task entry, the node the command list runs under (`verify`,
1882    /// `gate`).
1883    pub node: String,
1884    /// When this attempt — or, for a task entry, this one command — was
1885    /// started. A task entry's timer resets at every command boundary,
1886    /// because `verify.e2e` / `verify.gate` apply their timeout per command,
1887    /// not once across the whole list — see [`RunState::task_command`].
1888    pub started_at: Timestamp,
1889    /// The wall-clock budget for this attempt (a seat) or this one command
1890    /// (a task entry).
1891    pub timeout_secs: u64,
1892    /// 0 for the first ask, N for the Nth nudge or resume. For a task entry,
1893    /// 0 for the first pass over the command list, N for the Nth retry (see
1894    /// `run_e2e_with_retry`'s build/link retry).
1895    #[serde(default)]
1896    pub attempt: usize,
1897    /// `None` for a seat; `Some("e2e")` / `Some("gate")` for a running
1898    /// command-list task. This is the type tag that lets both kinds of entry
1899    /// share one map without a task ever being mistaken for a (blind) seat —
1900    /// see this struct's own doc. Omitted from JSON when absent (the common,
1901    /// seat case), rather than written out as a literal `null` on every one
1902    /// of a run's seat entries.
1903    #[serde(default, skip_serializing_if = "Option::is_none")]
1904    pub task: Option<String>,
1905    /// The command currently running, task entries only. Never set on a
1906    /// seat entry — a seat has no command, only a prompt, and a prompt is
1907    /// not safe to show mid-run (see this struct's blindness note).
1908    #[serde(default, skip_serializing_if = "Option::is_none")]
1909    pub command: Option<String>,
1910    /// 1-based position of [`Self::command`] within the task's command list.
1911    #[serde(default, skip_serializing_if = "Option::is_none")]
1912    pub index: Option<usize>,
1913    /// Number of commands in the task's list.
1914    #[serde(default, skip_serializing_if = "Option::is_none")]
1915    pub total: Option<usize>,
1916}
1917
1918/// What a wave is waiting for before it may spawn its agents.
1919#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1920pub struct ResourceWait {
1921    /// Node whose seats wait.
1922    pub node: String,
1923    /// What is awaited, e.g. `shared build cache`.
1924    pub kind: String,
1925    /// Who holds it, as far as known.
1926    pub holder: String,
1927    /// When the wait began.
1928    pub since: Timestamp,
1929    /// The wait's own bound, seconds (`[graph] timeout_resource_wait`).
1930    pub limit_secs: u64,
1931}
1932
1933/// Why a resource operation stopped. Older records did not retain this evidence.
1934#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
1935#[serde(tag = "kind", rename_all = "snake_case")]
1936pub enum ResourceBlockCause {
1937    /// No structured evidence was saved.
1938    #[default]
1939    Unrecorded,
1940    /// The resource wait actually exhausted its own budget.
1941    Timeout {
1942        /// Measured wait duration.
1943        waited_secs: u64,
1944        /// Configured resource wait budget.
1945        limit_secs: u64,
1946    },
1947    /// Isolation waits bind recovery to the exact managed target.
1948    IsolatedCacheTimeout {
1949        /// Target whose lease blocked this execution.
1950        target: PathBuf,
1951        /// Measured wait duration.
1952        waited_secs: u64,
1953        /// Configured resource wait budget.
1954        limit_secs: u64,
1955    },
1956    /// Acquisition was cancelled, possibly by a known park request.
1957    Cancelled {
1958        /// Available only when the caller retained the park request.
1959        park: Option<ParkCause>,
1960    },
1961    /// An infrastructure error, rather than an elapsed wait.
1962    Other,
1963}
1964
1965/// A resumable resource stop; earlier nodes or peers may already have run.
1966#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1967pub struct ResourceBlock {
1968    /// Node whose operation was blocked or interrupted.
1969    pub node: String,
1970    /// What stayed busy.
1971    pub kind: String,
1972    /// Structured evidence from the point where acquisition ended.
1973    #[serde(default)]
1974    pub cause: ResourceBlockCause,
1975    /// Why the operation ended, in words.
1976    pub detail: String,
1977    /// When it ended.
1978    pub at: Timestamp,
1979}
1980
1981impl ResourceBlock {
1982    /// Shared CLI, queue-hold and Web wording. Never infer a timeout from a
1983    /// resource kind or a legacy record's configured budget.
1984    #[must_use]
1985    pub fn description(&self) -> String {
1986        let reason = match &self.cause {
1987            ResourceBlockCause::Timeout {
1988                waited_secs,
1989                limit_secs,
1990            }
1991            | ResourceBlockCause::IsolatedCacheTimeout {
1992                waited_secs,
1993                limit_secs,
1994                ..
1995            } => format!("resource wait timed out after {waited_secs}s (limit {limit_secs}s)"),
1996            ResourceBlockCause::Cancelled { park: Some(cause) } => {
1997                format!("resource wait cancelled for parking ({})", cause.label())
1998            }
1999            ResourceBlockCause::Cancelled { park: None } => "resource wait cancelled".into(),
2000            ResourceBlockCause::Other => "resource operation blocked".into(),
2001            ResourceBlockCause::Unrecorded if self.detail == "the run is parking" => {
2002                "resource wait cancelled for parking (request source unrecorded)".into()
2003            }
2004            ResourceBlockCause::Unrecorded
2005                if self.detail == "the wait for the build cache was cancelled" =>
2006            {
2007                "resource wait cancelled (request source unrecorded)".into()
2008            }
2009            ResourceBlockCause::Unrecorded => "resource stop cause unrecorded".into(),
2010        };
2011        format!("{}: {}: {reason} ({})", self.node, self.kind, self.detail)
2012    }
2013}
2014
2015impl ActiveSeat {
2016    /// Seconds since this attempt was sent.
2017    #[must_use]
2018    pub fn elapsed_secs(&self, now: Timestamp) -> i64 {
2019        (now.as_second() - self.started_at.as_second()).max(0)
2020    }
2021
2022    /// Seconds left before this attempt's own timeout fires, floored at zero
2023    /// rather than going negative once the CLI has overrun its budget.
2024    #[must_use]
2025    pub fn remaining_secs(&self, now: Timestamp) -> i64 {
2026        (self.timeout_secs as i64 - self.elapsed_secs(now)).max(0)
2027    }
2028}
2029
2030/// Whether a process is provably still driving a run, provably not, or
2031/// neither — see [`RunState::liveness`]. Serialized as a lowercase string
2032/// (`"live"` / `"dead"` / `"unknown"`) rather than a bool: a bool has no room
2033/// for "could not tell", and folding that case into either `true` or `false`
2034/// is exactly the wrong call for a display an operator uses to decide
2035/// whether to wait or to act — see the schema-10 field doc on
2036/// [`RunState::driver_pid`] for the report it used to produce instead.
2037#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
2038#[serde(rename_all = "lowercase")]
2039pub enum Liveness {
2040    /// Proven: a daemon's heartbeat or a matching held execution lease claims
2041    /// the run, or (for legacy records) `driver_pid` answers
2042    /// alive under the same identity (`driver_started_at`) this run recorded
2043    /// for it.
2044    Live,
2045    /// Proven: no daemon claim, and an explicit exit or matching free execution
2046    /// lease, or `driver_pid` answers dead outright
2047    /// or it answers alive under a *different* identity than recorded — a
2048    /// pid the OS has since handed to an unrelated process is exactly as
2049    /// good as proof the original driver is gone (see
2050    /// [`RunState::driver_started_at`]'s own doc).
2051    Dead,
2052    /// Neither proven — no daemon claim, and either no `driver_pid` to ask,
2053    /// the platform could not answer for it, or a live pid with nothing (or
2054    /// nothing queryable) to corroborate its identity against. Never treated
2055    /// as `Dead`: see [`RunState::liveness_with`].
2056    Unknown,
2057}
2058
2059/// A timestamped note about a node.
2060#[derive(Debug, Clone, Serialize, Deserialize)]
2061pub struct Event {
2062    /// When.
2063    pub at: Timestamp,
2064    /// Node name.
2065    pub node: String,
2066    /// What happened.
2067    pub message: String,
2068}
2069
2070/// How far the winner's tree trailed the landing base, last time it was
2071/// checked, and what came of trying to close that gap.
2072///
2073/// Set by `graph::Runner::sync_to_base`, which runs before the review loop and
2074/// again before the gate: verifying against a tree that does not yet contain
2075/// the base's tip answers "green on the commit this run branched from", not
2076/// "green on what is about to land", and a merge on that answer can revert
2077/// whatever landed elsewhere while the run was thinking.
2078#[derive(Debug, Clone, Serialize, Deserialize)]
2079pub struct BaseSync {
2080    /// `<remote>/<base>` tip the tree was last checked against.
2081    pub tip: String,
2082    /// Commits `tip` was ahead of the tree at that check, before any rebase
2083    /// this round tried to close the gap. Zero means the tree already
2084    /// contained `tip`.
2085    pub behind: usize,
2086    /// Lifetime synchronization reservations, never reset. The active interval
2087    /// in `base_sync_recovery` enforces `graph::BASE_SYNC_ROUNDS`.
2088    pub attempts: usize,
2089    /// What git said, if the most recent rebase attempt conflicted or could
2090    /// not be pushed. `Some` here is what makes a `Blocked` run read as
2091    /// "stopped on the base, not on review or the gate" - the rebase is not
2092    /// retried again while this is set; a person has to look.
2093    #[serde(default)]
2094    pub conflict: Option<String>,
2095    /// Set when the winner's whole change turned out to be on the base already
2096    /// under other commit ids (see [`crate::already`]). Present exactly when the
2097    /// run ended as [`RunStatus::AlreadyInBase`].
2098    #[serde(default)]
2099    pub already_in: Option<crate::already::Evidence>,
2100}
2101
2102/// What the land loop saw last time it looked at the pull request.
2103///
2104/// Strings for `state` and `checks` on purpose: they are `gh`'s vocabulary, and
2105/// pinning them into an enum here would mean a new GitHub check conclusion
2106/// turns a readable status into a deserialisation error on a run someone is
2107/// trying to look at.
2108#[derive(Debug, Clone, Serialize, Deserialize)]
2109pub struct PrRecord {
2110    /// Pull request url.
2111    pub url: String,
2112    /// Pull request number.
2113    pub number: u64,
2114    /// `open`, `merged` or `closed`.
2115    pub state: String,
2116    /// `pending`, `green`, `red` or `unknown`.
2117    pub checks: String,
2118    /// Land round, 1-based, or 0 before the first fix.
2119    pub round: usize,
2120    /// Land round budget.
2121    pub rounds: usize,
2122    /// Checks that were red when the pull request merged anyway (the forge
2123    /// said they do not block it). Empty for a green merge, and for any run
2124    /// recorded before this field existed - so empty is not proof nothing was
2125    /// red.
2126    #[serde(default, skip_serializing_if = "Vec::is_empty")]
2127    pub red_at_merge: Vec<String>,
2128}
2129
2130/// What the post-merge release-bump step did, and whether it needs a human.
2131///
2132/// Recorded next to the `bump` events rather than instead of them: the events
2133/// are the narrative, this is what `magi show`, the status word and the
2134/// notification read without parsing prose. `status` stays `Merged` - the
2135/// merge did happen - so [`RunState::needs_attention`] is the one place that
2136/// says a merged run is not fully done.
2137#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
2138pub struct ReleaseBump {
2139    /// The release pull request, when one was opened.
2140    #[serde(default)]
2141    pub pr_url: Option<String>,
2142    /// The version it releases.
2143    #[serde(default)]
2144    pub version: Option<String>,
2145    /// Did enabling automerge on `pr_url` succeed?
2146    #[serde(default)]
2147    pub automerge_enabled: bool,
2148    /// GitHub refused automerge because CI had already finished (the pull
2149    /// request was in clean status), so magi merged it directly. Kept apart
2150    /// from `automerge_enabled`, which stays the plain fact it says it is.
2151    #[serde(default)]
2152    pub merged_directly: bool,
2153    /// `[release] mode = "local"`: no automerge was armed; the pull request is
2154    /// merged on the owner's approval and released by `magi serve`
2155    /// ([`crate::release_local`]).
2156    #[serde(default)]
2157    pub local: bool,
2158    /// What the local release did (tag, commit, each command's exit code and
2159    /// output tail), kept here because the watcher's own record is deleted
2160    /// once the release is done.
2161    #[serde(default)]
2162    pub release: Option<crate::release_local::Job>,
2163    /// What went wrong, verbatim from the tool that said it.
2164    #[serde(default)]
2165    pub problem: Option<String>,
2166    /// What the operator has to do about it. `Some` is what makes a merged run
2167    /// read as needing attention.
2168    #[serde(default)]
2169    pub action_required: Option<String>,
2170    /// Why no release bump was made. A skipped bump is not a completed
2171    /// release: the report and the web page say SKIPPED with this reason.
2172    #[serde(default)]
2173    pub skipped: Option<String>,
2174}
2175
2176/// The workflow runs `land` reran on one head, with when (unix seconds).
2177#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
2178pub struct LandReruns {
2179    /// The commit the reruns were made on.
2180    pub head: String,
2181    /// Workflow run id to the unix second it was rerun.
2182    pub runs: BTreeMap<String, i64>,
2183}
2184
2185/// Successful launcher fetch, persisted independently of moving tracking refs.
2186#[derive(Debug, Clone, Serialize, Deserialize)]
2187pub struct FetchedBase {
2188    /// Remote fetched by the launcher.
2189    pub remote: String,
2190    /// Remote branch selected as the run base.
2191    pub branch: String,
2192    /// Resolved commit immediately after the successful fetch.
2193    pub commit: String,
2194    /// Time the launcher observed the successful fetch.
2195    pub fetched_at: Timestamp,
2196}
2197
2198/// Durable evidence recorded before startup can acquire repository assets.
2199#[derive(Debug, Clone, Serialize, Deserialize)]
2200pub struct Startup {
2201    /// Implementation, review, or public-head recovery.
2202    pub kind: String,
2203    /// Requested review branch, before any checkout or ref changes.
2204    pub branch: Option<String>,
2205    /// Last durable startup boundary.
2206    pub stage: String,
2207    /// Construction finished successfully; false forbids graph resumption.
2208    pub complete: bool,
2209    /// Original startup error, or an interruption requiring inspection.
2210    pub failure: Option<String>,
2211}
2212
2213/// Error context preserves the underlying typed refusal/resource error.
2214#[derive(Debug, Clone, Serialize, Deserialize)]
2215pub struct StartupFailure {
2216    /// Reserved run retained for audit.
2217    pub run: String,
2218    /// Boundary that failed.
2219    pub stage: String,
2220}
2221
2222impl std::fmt::Display for StartupFailure {
2223    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2224        write!(f, "run {} startup failed at {}", self.run, self.stage)
2225    }
2226}
2227
2228/// The whole run.
2229#[derive(Debug, Clone, Serialize, Deserialize)]
2230pub struct RunState {
2231    /// On-disk format version.
2232    pub schema: u32,
2233    /// Run id, e.g. `20260830-153012-a1b2`.
2234    pub id: String,
2235    /// Repository the run operates on.
2236    pub repo: PathBuf,
2237    /// Branch the run started from.
2238    pub base_branch: String,
2239    /// Commit the run started from.
2240    pub base_commit: String,
2241    /// Absent in older runs; never infer fetch evidence from a tracking ref.
2242    #[serde(default)]
2243    pub fetched_base: Option<FetchedBase>,
2244    /// Guarded destination for an isolated review of a foreign checkout.
2245    #[serde(default)]
2246    pub foreign_checkout: Option<crate::foreign_checkout::ForeignCheckout>,
2247    /// Reservation lifecycle; incomplete startups must never execute as fresh work.
2248    #[serde(default)]
2249    pub startup: Option<Startup>,
2250    /// The task, verbatim.
2251    pub instruction: String,
2252    /// Authored task criteria before review scaffolding was generated.
2253    #[serde(default)]
2254    pub task_instruction: Option<String>,
2255    /// When the run was created.
2256    pub created_at: Timestamp,
2257    /// Last state flush.
2258    pub updated_at: Timestamp,
2259    /// Execution activity for artifact reclamation; bookkeeping saves do not refresh it.
2260    #[serde(default)]
2261    pub output_activity_at: Option<Timestamp>,
2262    /// Current status.
2263    pub status: RunStatus,
2264    /// Seed for labels and session ids.
2265    pub seed: u64,
2266    /// Config snapshot, so a resumed run behaves like the original.
2267    pub config: Config,
2268    /// Applied explicit repair authorizations and crash checkpoints.
2269    #[serde(default)]
2270    pub repair_grants: Vec<crate::repair_budget::Applied>,
2271    /// Additive approval policy; retained even if a later head removes it.
2272    #[serde(default)]
2273    pub branch_owner_holds: Vec<BranchOwnerHold>,
2274    /// Did this run take a reference on `extensions.worktreeConfig` being on
2275    /// (see [`crate::git::acquire_worktree_config`])? If so, cleanup releases
2276    /// it - which only actually turns the setting back off once every other
2277    /// run sharing this repository has released its own reference too.
2278    #[serde(default)]
2279    pub enabled_worktree_config: bool,
2280    /// Public pull request head, separate from competition branches.
2281    #[serde(default)]
2282    pub pr_head: Option<String>,
2283    /// Operator-selected source and original public lease, distinct from repaired HEAD.
2284    #[serde(default)]
2285    pub pr_recovery: Option<crate::pr_recovery::Selection>,
2286    /// Actual ordered load inputs (remote-layer paths contain their source commit).
2287    /// The resolved commands are retained in `config`, without re-rendering provenance.
2288    #[serde(default)]
2289    pub recovery_config: Option<crate::pr_recovery::ConfigEvidence>,
2290    /// Last head successfully pushed by this run; never an observed remote tip.
2291    #[serde(default)]
2292    pub pr_pushed_head: Option<String>,
2293    /// Public PR head observed when the forge confirmed its merge; absent on old records.
2294    #[serde(default)]
2295    pub pr_merged_head: Option<String>,
2296    /// Last title posted by this run, used to preserve human title edits.
2297    #[serde(default)]
2298    pub pr_posted_title: Option<String>,
2299    /// Publication has not completed; resume retries it without competing again.
2300    #[serde(default)]
2301    pub pr_publication_pending: bool,
2302    /// Successor that owns this run's pull request; this record is historical.
2303    #[serde(default)]
2304    pub pr_taken_over_by: Option<String>,
2305    /// Empty attempt retired to a recovery authority; reports and refs remain.
2306    /// Separate from Superseded: this never settles questions or closes PRs.
2307    #[serde(default)]
2308    pub retired_to: Option<String>,
2309    /// Candidates.
2310    #[serde(default)]
2311    pub candidates: Vec<Candidate>,
2312    /// Initial blind rankings.
2313    #[serde(default)]
2314    pub judgements: Vec<Judgement>,
2315    /// `judge` decided a solo candidate needs no panel and only logged it.
2316    ///
2317    /// `judgements` stays empty in that case — nothing to distinguish from
2318    /// "not yet judged" — so this is the record that makes the skip
2319    /// idempotent: without it, every reentry re-ran `judge`, re-logged the
2320    /// same event, and rewrote `status` to `Judging` over whatever a later
2321    /// node had already concluded.
2322    #[serde(default)]
2323    pub judge_skipped: bool,
2324    /// Deliberation, if it happened.
2325    #[serde(default)]
2326    pub deliberation: Vec<DeliberationRound>,
2327    /// Private final votes.
2328    #[serde(default)]
2329    pub votes: Vec<VoteRecord>,
2330    /// The count.
2331    #[serde(default)]
2332    pub tally: Option<Tally>,
2333    /// Review rounds.
2334    #[serde(default)]
2335    pub reviews: Vec<ReviewRound>,
2336    /// Final gate.
2337    ///
2338    /// Never derive whether the gate has run from `gate.is_empty()` alone —
2339    /// use [`Self::gate_status`] instead. An empty list is ambiguous on its
2340    /// own: it is what an unattempted gate looks like, what a
2341    /// resource-blocked attempt leaves behind (see `graph::Runner::gate`'s
2342    /// own doc), and also what a repo with no `verify.gate` commands
2343    /// configured produces once it *has* run. [`Self::gate_ran`] is what
2344    /// tells the third case apart from the first two.
2345    #[serde(default)]
2346    pub gate: Vec<CommandOutcome>,
2347    /// Did `gate()` actually record an attempt — zero commands configured
2348    /// (not configured), or one or more commands that ran to
2349    /// completion — as opposed to never having run, or having last hit a
2350    /// resource-blocked retry?
2351    ///
2352    /// `gate.is_empty()` cannot tell those apart by itself: a repo with no
2353    /// `verify.gate` commands leaves `gate` empty exactly like an
2354    /// unattempted or resource-blocked one does, and reading that empty list
2355    /// as "not yet run" is what stranded a review-only run in
2356    /// `RunStatus::Gating` forever on such a repo — see `SCHEMA`'s doc for
2357    /// schema 7. A record written before this field existed defaults to
2358    /// `false` and is migrated in [`migrate_schema`].
2359    #[serde(default)]
2360    pub gate_ran: bool,
2361    /// The winner's commit the recorded `gate` ran against. `None` on a record
2362    /// from before this existed, which reads as "commit unknown".
2363    #[serde(default)]
2364    pub gate_head: Option<String>,
2365    /// Verification on a changed head, separate from the review judgment.
2366    #[serde(default)]
2367    pub head_e2e: Option<GateRepairE2e>,
2368    /// Append-only evidence replaced when the winner moves to another head.
2369    #[serde(default)]
2370    pub verification_history: Vec<VerificationEvidence>,
2371    /// Resume must reconcile, sync, gate and publish the existing PR head before CI.
2372    #[serde(default)]
2373    pub land_sync_pending: bool,
2374    /// Base synchronization attempts spent, including across landing resumes.
2375    #[serde(default)]
2376    pub land_sync_attempts: usize,
2377    /// Pinned base of a charged landing synchronization that has not completed.
2378    #[serde(default)]
2379    pub land_sync_target: Option<String>,
2380    /// Winner tip before a landing rebase, retained until worktree setup finishes.
2381    #[serde(default)]
2382    pub land_rebase_from: Option<String>,
2383    /// Fix rounds a failing gate has already spent, oldest first. Persisted
2384    /// right after each fixer call so a resumed run spends only what is left
2385    /// of `graph.gate_fix_rounds` instead of starting the budget over.
2386    #[serde(default)]
2387    pub gate_fixes: Vec<GateFixRecord>,
2388    /// Publication after gate repair requires successful e2e on the final SHA.
2389    #[serde(default)]
2390    pub gate_repair_e2e: Option<GateRepairE2e>,
2391    /// Fixer rounds spent on a rebase conflict (base sync and land share one
2392    /// budget, `graph.review_rounds`), oldest first. Persisted right before
2393    /// each fixer call, so a resumed run spends only what is left.
2394    #[serde(default)]
2395    pub rebase_fixes: Vec<RebaseFixRecord>,
2396    /// The graft phase's record, once it started or was skipped for a
2397    /// reason worth keeping. `None` for a run that never reached it.
2398    #[serde(default)]
2399    pub graft: Option<GraftRecord>,
2400    /// What this run inherited from the attempt it took over, and why (see
2401    /// [`crate::recovery`]). `None` for a run that took nothing over.
2402    /// Additive and `#[serde(default)]`, so `SCHEMA` stays put.
2403    #[serde(default)]
2404    pub recovery: Option<crate::recovery::RecoveryRecord>,
2405    /// Set at the review loop's hand-off when the last round ended with a
2406    /// blocking finding still open *and* a reviewer's final vote was reject
2407    /// (see [`ReviewRound::contested_handoff`]). `land` reads it to ask the
2408    /// owner before merging even with `graph.land_approval` off. A snapshot
2409    /// taken at hand-off, never recomputed later.
2410    #[serde(default)]
2411    pub contested_handoff: Option<ContestedHandoff>,
2412    /// The head commit `land` has armed (or is about to arm) GitHub auto-merge
2413    /// on. Saved *before* the arm call, so a crash right after it still tells
2414    /// a resume that the forge may be holding an armed merge. Cleared the
2415    /// moment auto-merge is disabled or the pull request is done.
2416    #[serde(default)]
2417    pub land_armed_head: Option<String>,
2418    /// Workflow runs `land` has rerun for the head it is bound to. Saved
2419    /// *before* each `gh run rerun`, so a restart never reruns twice; replaced
2420    /// when the head moves.
2421    #[serde(default)]
2422    pub land_reruns: Option<LandReruns>,
2423    /// First unreadable merge-state observation per head, independent of reruns.
2424    #[serde(default)]
2425    pub land_unsaid: Option<(String, i64)>,
2426    /// Structured CI evidence and owner question for a machine hold.
2427    #[serde(default)]
2428    pub land_unrelated: Option<crate::land::CiHold>,
2429    /// The merge-approval question `land` last filed, and the head commit its
2430    /// panel showed. An answer is only honoured for that exact commit: a fix
2431    /// or rebase push makes a new head the owner has not seen.
2432    #[serde(default)]
2433    pub land_approval: Option<LandApproval>,
2434    /// Repair history on this same PR and run; no second task owns the branch.
2435    #[serde(default)]
2436    pub merge_repairs: Vec<MergeRepair>,
2437    /// Owner stop/withdraw/replacement checkpoint, independent of PR head movement.
2438    #[serde(default)]
2439    pub merge_decision: Option<crate::merge_decision::Decision>,
2440    /// Exact owner requests committed atomically with abandonment.
2441    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
2442    pub abandonment_receipts: BTreeMap<String, String>,
2443    /// Previous attempt replaced by this run; its PR is never reused.
2444    #[serde(default)]
2445    pub replaces: Option<crate::merge_decision::Replacement>,
2446    /// The posting-gate question for this run's pull request text, if the gate
2447    /// withheld any. While `resolved` is `None` the run is parked on it.
2448    #[serde(default)]
2449    pub github_text: Option<GithubTextAsk>,
2450    /// The whole-change description of a review-only run, tied to the final
2451    /// commit and base it was written from. `None` until one was produced.
2452    #[serde(default)]
2453    pub change_summary: Option<ChangeSummary>,
2454    /// Outcomes of the `verify.pre_gate` commands from the latest time they
2455    /// ran on the winner. Informational only: a failure here never blocks the
2456    /// run, the gate stays the single arbiter. Overwritten on each pass.
2457    #[serde(default)]
2458    pub pre_gate: Vec<CommandOutcome>,
2459    /// The latest commit a `pre_gate` pass made, if any pass left changes.
2460    #[serde(default)]
2461    pub pre_gate_commit: Option<String>,
2462    /// Merge outcome.
2463    #[serde(default)]
2464    pub merge: Option<MergeOutcome>,
2465    /// Vendor tokens seen in judged material.
2466    #[serde(default)]
2467    pub leaks: Vec<Leak>,
2468    /// Seats lost to a CLI rate limit / quota, in the order they hit.
2469    #[serde(default)]
2470    pub quota: Vec<QuotaLoss>,
2471    /// Seats handed to the next roster agent after a failure, in order.
2472    /// Additive, so `SCHEMA` is not bumped.
2473    #[serde(default)]
2474    pub handovers: Vec<Handover>,
2475    /// How many agent-change seats this run has minted; mixed into their
2476    /// session ids so re-handing a seat to an agent it already had never
2477    /// reuses that agent's earlier uuid. Additive.
2478    #[serde(default)]
2479    pub seat_epoch: u64,
2480    /// Per reviewer seat, which roster agents already failed it and which one
2481    /// last answered, carried across review rounds. Additive, so `SCHEMA` is
2482    /// not bumped. See [`SeatHistory`].
2483    #[serde(default)]
2484    pub seat_history: BTreeMap<String, SeatHistory>,
2485    /// Stray foreign lockfiles a rescue commit left out, one entry per path.
2486    #[serde(default)]
2487    pub withheld: Vec<Withheld>,
2488    /// One entry per time a process took this run over (`Runner::execute`),
2489    /// oldest first. Append-only: a later resume closes the pass before it
2490    /// and never rewrites what that pass recorded. A run from before this
2491    /// existed has none for its earlier passes, which stay "not recorded".
2492    /// Additive, so `SCHEMA` is not bumped.
2493    #[serde(default)]
2494    pub passes: Vec<RunPass>,
2495    /// Inquiry-to-pass receipts, persisted only after the execution lease and
2496    /// owner claim have been acquired. Later completion/holds retain them.
2497    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
2498    pub decision_starts: BTreeMap<String, usize>,
2499    /// Inquiries whose dispatched resumes this upcoming execution will consume.
2500    #[serde(skip)]
2501    pub next_pass_inquiries: Vec<String>,
2502    /// Set by whoever is about to execute this run on a task's behalf, read
2503    /// and cleared by the next [`RunState::begin_pass`]. Never persisted.
2504    #[serde(skip)]
2505    pub next_pass_task_entry: bool,
2506    /// Parked at a node boundary, waiting to be resumed.
2507    ///
2508    /// A run that is neither finished nor being worked on is otherwise
2509    /// indistinguishable from one whose daemon was killed, and the two want
2510    /// opposite things from an operator: the first is expected to be resumed,
2511    /// the second is a leftover. Cleared by the resume that carries it on.
2512    #[serde(default)]
2513    pub parked: bool,
2514    /// Seats of `node` are waiting, before any agent is spawned, for a shared
2515    /// resource (the build cache's lease). While this is `Some` the seats in
2516    /// [`Self::active`] are *not* running: their countdown has not started.
2517    /// Cleared the moment the wait ends, whichever way.
2518    #[serde(default, skip_serializing_if = "Option::is_none")]
2519    pub resource_wait: Option<ResourceWait>,
2520    /// The run stopped on a resource operation. This does not establish a timeout.
2521    /// Pre-spawn acquisition failures do not spend the affected agent's budget,
2522    /// alter its seat history or cause fallback. Earlier operations may have
2523    /// completed; resource interruption can also stop a running operation.
2524    /// Cleared by resume.
2525    #[serde(default, skip_serializing_if = "Option::is_none")]
2526    pub resource_block: Option<ResourceBlock>,
2527    /// The run that took this run's worktree over, when one did — see
2528    /// [`crate::handover`]. `Some` means the worktree is gone on purpose and
2529    /// the run can no longer be resumed from it ([`Self::released`]).
2530    #[serde(default)]
2531    pub released_to: Option<String>,
2532    /// Branches that outlived this run's released worktree and now belong to
2533    /// the run in [`Self::released_to`] (and to its pull request). A later
2534    /// fold must leave them alone.
2535    #[serde(default)]
2536    pub released_branches: Vec<String>,
2537    /// Turns whose Git/artifact preservation is not confirmed. A resume retries
2538    /// persistence before deciding whether an interrupted turn needs execution.
2539    #[serde(default)]
2540    pub candidate_preservation: BTreeMap<char, String>,
2541    /// Interrupted turns whose empty trees must remain eligible for execution.
2542    /// Kept separately from preservation errors so failed rescue retries retain
2543    /// the distinction between an unfinished turn and a completed empty reply.
2544    #[serde(default)]
2545    pub interrupted_implementations: BTreeSet<char>,
2546    /// Legacy automatically inferred references, retained only for audit.
2547    /// These are never explicit authorization and never seed preparation.
2548    #[serde(default)]
2549    pub seeds: Vec<crate::refs::Seed>,
2550    /// Explicit, SHA-pinned implementation imports; separate from instruction text.
2551    #[serde(default, skip_serializing_if = "crate::refs::Sources::is_empty")]
2552    pub sources: crate::refs::Sources,
2553    /// Candidate preparation stopped before agents ran; requires an explicit source correction.
2554    #[serde(default)]
2555    pub prep_failure: Option<String>,
2556    /// None identifies legacy records; new runs persist preparation completion explicitly.
2557    #[serde(default)]
2558    pub prep_complete: Option<bool>,
2559    /// Per-seat conversation state.
2560    #[serde(default)]
2561    pub seats: BTreeMap<String, SeatState>,
2562    /// Seats currently mid-answer, keyed by seat.
2563    ///
2564    /// An entry exists from the moment a prompt is sent until a reply (of any
2565    /// kind — success, failure, quota, drop) comes back, so its keys are
2566    /// exactly "who hasn't answered yet" for whichever node populated it. See
2567    /// [`ActiveSeat`] for why a reader still has to check a live daemon
2568    /// before trusting one of these as "running" rather than "abandoned".
2569    #[serde(default)]
2570    pub active: BTreeMap<String, ActiveSeat>,
2571    /// Process id of whichever `execute()` call last drove this run —
2572    /// written at the very top of that method, the same place
2573    /// [`Self::clear_active`] runs, so a fresh reentry always overwrites the
2574    /// pid a previous, possibly-dead process left behind.
2575    ///
2576    /// A daemon-claimed run already has a stronger signal
2577    /// (`daemon::is_working_on`), but a `magi run` / `magi review` typed
2578    /// straight into a terminal claims nothing there — before this field
2579    /// existed, [`report::active_seats`] had no way to tell that run apart
2580    /// from one a killed process abandoned, and printed the same "no live
2581    /// daemon claims this run" warning over a run that was, in fact, still
2582    /// answering. See [`Liveness`] for how this and the daemon claim combine.
2583    /// Released ownership clears this field together with `driver_started_at`;
2584    /// legacy records may retain the old pid with `driver_exited = true`.
2585    #[serde(default)]
2586    pub driver_pid: Option<u32>,
2587    /// Whether execution has ever claimed this record. New runs persist false
2588    /// before exposure, then true atomically with their first pass and PID.
2589    /// None is legacy/unknown, never evidence that execution did not start.
2590    #[serde(default, skip_serializing_if = "Option::is_none")]
2591    pub driver_claimed: Option<bool>,
2592    /// The OS-reported moment [`Self::driver_pid`] started, recorded in the
2593    /// same breath as the pid itself — an opaque marker
2594    /// (`crate::proc::process_started_at`, epoch seconds as an integer
2595    /// string), compared only for equality. Older runs hold a locale-dependent
2596    /// string here; those read as `Unknown`, never `Dead`.
2597    ///
2598    /// A pid alone never proves a live process is *this run's* driver: pids
2599    /// get reused, sometimes within minutes on a busy machine, and a killed
2600    /// manual `magi run` whose pid a later, wholly unrelated process happens
2601    /// to receive would otherwise read back as `Liveness::Live` from that
2602    /// coincidence alone. [`Self::liveness`] re-queries the current holder
2603    /// of `driver_pid` and requires this marker to still match before
2604    /// trusting a live answer — a mismatch means a different process now
2605    /// answers to that number, and no marker to compare (an old run, or a
2606    /// platform this build could not ask at record time) means neither
2607    /// extreme can be proven.
2608    #[serde(default)]
2609    pub driver_started_at: Option<String>,
2610    /// The process named by [`Self::driver_pid`] has stopped driving this run:
2611    /// its graph walk returned, whatever the outcome. Cleared at the start of
2612    /// every walk, set as the last write of one.
2613    ///
2614    /// A long-lived `magi serve` outlives its individual graph walks. The
2615    /// execution guard sets this and clears the pid/start marker when a walk
2616    /// returns, is cancelled or unwinds. A kill or failed save instead leaves
2617    /// a free pass-bound execution lease or a lost process identity for
2618    /// startup reconciliation. Older exited records may retain a historical pid.
2619    #[serde(default)]
2620    pub driver_exited: bool,
2621    /// Last observation of the winner's pull request, when a land loop ran.
2622    ///
2623    /// Persisted rather than derived from the event log because the phone asks
2624    /// two questions about a run that has opened a PR - how are its checks and
2625    /// which round is it on - and parsing prose out of events to answer them
2626    /// would break the first time an event message was reworded.
2627    #[serde(default)]
2628    pub pr: Option<PrRecord>,
2629    /// The post-merge release-bump step's outcome, when it got as far as
2630    /// having one to report. See [`ReleaseBump`].
2631    #[serde(default)]
2632    pub release_bump: Option<ReleaseBump>,
2633    /// Decision history also survives failures before a release outcome exists.
2634    #[serde(default)]
2635    pub bump_decision_attempts: Vec<crate::bump::DecisionAttempt>,
2636    /// The last look at how far the winner's tree trailed the landing base,
2637    /// and the rebase(s) tried to close that gap. `None` until the tree has a
2638    /// winner to check.
2639    #[serde(default)]
2640    pub base_sync: Option<BaseSync>,
2641    /// Stable stop identity and single-use owner authorizations, with prior evidence.
2642    #[serde(default)]
2643    pub base_sync_recovery: crate::base_sync_recovery::Recovery,
2644    /// The design-deliberation stage's output, when `[graph] advise` ran it:
2645    /// one record per advisor seat, plus the synthesis blended into the
2646    /// implementer's prompt. `None` when the stage is off, has not run yet,
2647    /// or could not even resolve its seats - see
2648    /// [`crate::graph::Runner::advise`].
2649    #[serde(default)]
2650    pub advice: Option<crate::advise::Advice>,
2651    /// Whether the design-deliberation stage has already been attempted this
2652    /// run, whatever it produced. The idempotency marker `Runner::advise`
2653    /// checks on reentry, the same role [`Self::judge_skipped`] plays for
2654    /// `judge` - without it a resumed run whose stage failed (a misconfigured
2655    /// `[roles] advisors`, every seat quota'd) would re-run it, and re-spend
2656    /// the agent calls, on every single reentry before `implement`.
2657    #[serde(default)]
2658    pub advise_attempted: bool,
2659    /// Node log.
2660    #[serde(default)]
2661    pub events: Vec<Event>,
2662    /// Commands seats' own CLIs reported running, across every node — see
2663    /// [`JobRecord`]. Populated in [`crate::graph::wave`] as each seat
2664    /// answers, so a resumed run keeps what earlier waves already collected
2665    /// rather than losing it to a reentry. Empty on a record written before
2666    /// this existed, or wherever no adapter reads structured job events for
2667    /// the backend a seat used — both read as "no evidence", not "nothing
2668    /// ran".
2669    #[serde(default)]
2670    pub jobs: Vec<JobRecord>,
2671    /// Operator-triggered targeted fixes — see [`OperatorFixRequest`] and
2672    /// `SCHEMA`'s doc for schema 9. Empty on every record written before
2673    /// this existed, which reads correctly as "no operator fix ever
2674    /// requested".
2675    #[serde(default)]
2676    pub operator_fixes: Vec<OperatorFixRequest>,
2677    /// Absolute paths of the files the task was filed with (see
2678    /// `crate::queue::Task::attachments`), listed in the implementers' prompt
2679    /// and made readable to their seats. Refreshed from the task on every
2680    /// start and resume, so a file attached while the task was held reaches a
2681    /// resumed run. Additive and `#[serde(default)]`, so `SCHEMA` stays put.
2682    #[serde(default)]
2683    pub attachments: Vec<PathBuf>,
2684    /// Subjects of the commits a review-only run examines, oldest first, as
2685    /// they stood when the run opened. `Some` marks the run as reviewing
2686    /// existing work: the pull request title is taken from these rather than
2687    /// from the review prompt in `instruction`. Additive and
2688    /// `#[serde(default)]`, so `SCHEMA` stays put.
2689    #[serde(default)]
2690    pub reviewed_commits: Option<Vec<String>>,
2691    /// Who started this run and which task it serves — see [`Origin`] and
2692    /// `SCHEMA`'s doc for schema 13. `None` is a run recorded before origins
2693    /// existed, and is reported as unknown, never as an operator's.
2694    #[serde(default)]
2695    pub origin: Option<Origin>,
2696    /// Repository assignment generation captured before startup; legacy runs use zero.
2697    #[serde(default)]
2698    pub task_assignment: usize,
2699    /// Follow-up tasks filed from this run's open findings after it merged
2700    /// (`crate::followup`). Additive and `#[serde(default)]`, so `SCHEMA`
2701    /// stays put.
2702    #[serde(default)]
2703    pub followups: Vec<FollowupRecord>,
2704    /// Follow-up depth of the task this run served, remembered the first
2705    /// time it was read so deleting that task cannot reset the cap.
2706    #[serde(default)]
2707    pub followup_generation: Option<u32>,
2708    /// Chat the task this run served descends from, fixed at start like
2709    /// `followup_generation` so deleting the task cannot lose it.
2710    #[serde(default)]
2711    pub origin_chat: Option<String>,
2712    /// The pull-request comment naming the filed follow-ups was posted.
2713    #[serde(default)]
2714    pub followup_commented: bool,
2715    /// Held tasks the merge approval's deputy filed for this run that were
2716    /// released after the merge (`crate::followup::settle_deputy_tasks`).
2717    /// Additive and `#[serde(default)]`, so `SCHEMA` stays put; the task
2718    /// record is the source of truth and this is rebuilt from the queue.
2719    #[serde(default)]
2720    pub deputy_followups: Vec<String>,
2721    /// `verify.e2e` commands that failed once and passed when rerun on the
2722    /// same commit (`graph::run_e2e_with_retry`, `crate::flake`). The head they
2723    /// verified is green, but a pass that needed a second run must never read
2724    /// as a plain green: reports, `magi show` and the web run page list these.
2725    /// Additive and `#[serde(default)]`, so `SCHEMA` stays put.
2726    #[serde(default)]
2727    pub verify_flakes: Vec<VerifyFlake>,
2728}
2729
2730/// One follow-up task filed from a merged run. See [`RunState::followups`].
2731#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2732pub struct FollowupRecord {
2733    /// Queue task id.
2734    pub task: String,
2735    /// Finding ids it covers.
2736    pub findings: Vec<String>,
2737}
2738
2739/// One `verify.e2e` command whose failure did not reproduce: it failed, then
2740/// passed when run again on the same commit in the same worktree. See
2741/// [`RunState::verify_flakes`].
2742#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2743pub struct VerifyFlake {
2744    /// The review round this belongs to (the per-round leg and the deferred
2745    /// catch-up); `None` for the current-head and gate-repair checks.
2746    #[serde(default)]
2747    pub round: Option<usize>,
2748    /// Where the verification ran, as in its `verify` events: `round 2`,
2749    /// `current head e2e`, `gate repair e2e`.
2750    pub context: String,
2751    /// The commit both attempts ran on.
2752    pub head: String,
2753    /// The configured command, as in [`CommandOutcome::command`].
2754    pub command: String,
2755    /// What the first attempt printed, bounded by `summarize_verify`.
2756    pub first_failure: String,
2757    /// Identifies the failure without knowing the test framework
2758    /// (`crate::flake::fingerprint`).
2759    pub fingerprint: String,
2760    /// When the rerun passed.
2761    pub at: Timestamp,
2762    /// The queue task that tracks this failure: the one this occurrence filed
2763    /// or one already filed for the same failure.
2764    #[serde(default)]
2765    pub task: Option<String>,
2766    /// This occurrence created [`Self::task`].
2767    #[serde(default)]
2768    pub filed: bool,
2769    /// Why no task could be filed; a filing failure never fails the run.
2770    #[serde(default)]
2771    pub filing_error: Option<String>,
2772}
2773
2774/// A monotonic owner hold observed in a reviewed commit.
2775#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2776pub struct BranchOwnerHold {
2777    /// Approval switch enabled by the branch.
2778    pub control: crate::config::OwnerHold,
2779    /// Repository-relative configuration file.
2780    pub file: String,
2781    /// Pinned commit where the hold was first observed.
2782    pub head: String,
2783}
2784
2785/// Keep legacy heads stable while separating later repository assignments.
2786pub(crate) fn task_pr_branch_name(task: &str, assignment: usize) -> String {
2787    if assignment == 0 {
2788        format!("magi/task-{task}")
2789    } else {
2790        format!("magi/task-{task}-assignment-{assignment}")
2791    }
2792}
2793
2794/// Origin-only legacy callers have no queue record. A present but unreadable
2795/// record must never silently reset publication to the initial assignment.
2796pub(crate) fn task_assignment_for(task: &str) -> Result<usize> {
2797    let queue = crate::queue::Queue::open();
2798    match queue.get(task) {
2799        Ok(task) => Ok(task.reassignments.len()),
2800        Err(error) if queue.path_of(task).try_exists()? => {
2801            Err(error).context("cannot capture task repository assignment")
2802        }
2803        Err(_) => Ok(0),
2804    }
2805}
2806
2807impl RunState {
2808    /// Effective policy is the OR of trusted config and observed branch holds.
2809    pub fn owner_hold(&self, control: crate::config::OwnerHold) -> bool {
2810        control.base_value(&self.config.graph)
2811            || self.branch_owner_holds.iter().any(|h| h.control == control)
2812    }
2813
2814    /// Read only pinned commits of existing-branch reviews, never candidates.
2815    pub async fn observe_branch_owner_holds(&mut self, head: &str) {
2816        if !crate::graph::is_review_run(self) {
2817            return;
2818        }
2819        let (holds, diagnostics) = crate::config::branch_owner_holds(&self.repo, head).await;
2820        for message in diagnostics {
2821            tracing::warn!("{message}");
2822            self.event("approval-policy", message);
2823        }
2824        for (control, file) in holds {
2825            if self
2826                .branch_owner_holds
2827                .iter()
2828                .any(|h| h.control == control && h.file == file)
2829            {
2830                continue;
2831            }
2832            let message = format!(
2833                "{}=true from the reviewed branch's {file} at {head}",
2834                control.key()
2835            );
2836            tracing::info!("{message}");
2837            self.event("approval-policy", message);
2838            self.branch_owner_holds.push(BranchOwnerHold {
2839                control,
2840                file,
2841                head: head.to_owned(),
2842            });
2843        }
2844    }
2845
2846    /// A fresh, unreserved run. Production callers must call [`Self::reserve`]
2847    /// before using its id, deriving branches, or saving it. Resumes load instead.
2848    pub fn new(
2849        repo: PathBuf,
2850        base_branch: String,
2851        base_commit: String,
2852        instruction: String,
2853        config: Config,
2854    ) -> Self {
2855        let now = Timestamp::now();
2856        let seed = config.blind.seed.unwrap_or_else(crate::rng::entropy);
2857        Self {
2858            schema: SCHEMA,
2859            id: new_id(),
2860            repo,
2861            base_branch,
2862            base_commit,
2863            fetched_base: None,
2864            instruction,
2865            task_instruction: None,
2866            created_at: now,
2867            updated_at: now,
2868            output_activity_at: Some(now),
2869            status: RunStatus::Prep,
2870            seed,
2871            config,
2872            branch_owner_holds: Vec::new(),
2873            repair_grants: Vec::new(),
2874            enabled_worktree_config: false,
2875            foreign_checkout: None,
2876            pr_head: None,
2877            pr_recovery: None,
2878            recovery_config: None,
2879            pr_pushed_head: None,
2880            pr_merged_head: None,
2881            pr_posted_title: None,
2882            pr_publication_pending: false,
2883            pr_taken_over_by: None,
2884            retired_to: None,
2885            candidates: Vec::new(),
2886            judgements: Vec::new(),
2887            judge_skipped: false,
2888            deliberation: Vec::new(),
2889            votes: Vec::new(),
2890            tally: None,
2891            reviews: Vec::new(),
2892            gate: Vec::new(),
2893            gate_ran: false,
2894            gate_head: None,
2895            head_e2e: None,
2896            verification_history: Vec::new(),
2897            land_sync_pending: false,
2898            land_sync_attempts: 0,
2899            land_sync_target: None,
2900            land_rebase_from: None,
2901            gate_fixes: Vec::new(),
2902            gate_repair_e2e: None,
2903            rebase_fixes: Vec::new(),
2904            graft: None,
2905            recovery: None,
2906            contested_handoff: None,
2907            land_armed_head: None,
2908            land_reruns: None,
2909            land_unsaid: None,
2910            land_unrelated: None,
2911            land_approval: None,
2912            merge_repairs: Vec::new(),
2913            merge_decision: None,
2914            abandonment_receipts: BTreeMap::new(),
2915            replaces: None,
2916            github_text: None,
2917            change_summary: None,
2918            pre_gate: Vec::new(),
2919            pre_gate_commit: None,
2920            merge: None,
2921            leaks: Vec::new(),
2922            quota: Vec::new(),
2923            handovers: Vec::new(),
2924            seat_epoch: 0,
2925            seat_history: BTreeMap::new(),
2926            withheld: Vec::new(),
2927            passes: Vec::new(),
2928            decision_starts: BTreeMap::new(),
2929            next_pass_inquiries: Vec::new(),
2930            next_pass_task_entry: false,
2931            parked: false,
2932            resource_wait: None,
2933            resource_block: None,
2934            released_to: None,
2935            released_branches: Vec::new(),
2936            candidate_preservation: BTreeMap::new(),
2937            interrupted_implementations: BTreeSet::new(),
2938            seeds: Vec::new(),
2939            sources: crate::refs::Sources::default(),
2940            prep_failure: None,
2941            startup: None,
2942            prep_complete: Some(false),
2943            seats: BTreeMap::new(),
2944            active: BTreeMap::new(),
2945            driver_pid: None,
2946            driver_claimed: Some(false),
2947            driver_started_at: None,
2948            driver_exited: false,
2949            pr: None,
2950            release_bump: None,
2951            bump_decision_attempts: Vec::new(),
2952            base_sync: None,
2953            base_sync_recovery: Default::default(),
2954            advice: None,
2955            advise_attempted: false,
2956            attachments: Vec::new(),
2957            reviewed_commits: None,
2958            origin: None,
2959            task_assignment: 0,
2960            followups: Vec::new(),
2961            followup_generation: None,
2962            deputy_followups: Vec::new(),
2963            verify_flakes: Vec::new(),
2964            origin_chat: None,
2965            followup_commented: false,
2966            events: Vec::new(),
2967            jobs: Vec::new(),
2968            operator_fixes: Vec::new(),
2969        }
2970    }
2971
2972    /// Directory holding this run's state and artifacts.
2973    pub fn dir(&self) -> PathBuf {
2974        run_dir(&self.id)
2975    }
2976
2977    /// Short form used in branch names and reports.
2978    pub fn short(&self) -> &str {
2979        short_of(&self.id)
2980    }
2981
2982    /// Branch name for a label.
2983    pub fn branch_for(&self, label: char) -> String {
2984        format!("magi/{}/{}", self.short(), label)
2985    }
2986
2987    /// Capture task publication scope once, before reserving a new execution.
2988    pub(crate) fn set_origin(&mut self, origin: Origin) -> Result<()> {
2989        self.task_assignment = match origin.task.as_deref() {
2990            Some(task) => task_assignment_for(task)?,
2991            None => 0,
2992        };
2993        self.origin = Some(origin);
2994        Ok(())
2995    }
2996
2997    /// Public head for a queue competition. Review-only and standalone runs
2998    /// keep their existing branch. Invalid task ids cannot become git refs.
2999    pub fn task_pr_branch(&self) -> Option<String> {
3000        if self.reviewed_commits.is_some()
3001            || self
3002                .candidates
3003                .iter()
3004                .any(|c| c.agent == "(existing branch)")
3005        {
3006            // A review-only run continues the task's pull request only when
3007            // it inherited that head from an earlier attempt (see
3008            // `Runner::review_taking_over`). A legacy `magi/<run>/<label>`
3009            // PR or a hand-named branch keeps its own head.
3010            let inherited = self.pr_head.is_some();
3011            if !inherited {
3012                return None;
3013            }
3014        }
3015        let task = self.origin.as_ref()?.task.as_ref()?;
3016        let branch = task_pr_branch_name(task, self.task_assignment);
3017        let branch = if let Some(replaces) = &self.replaces {
3018            format!("{branch}-{}", replaces.question)
3019        } else {
3020            branch
3021        };
3022        std::process::Command::new("git")
3023            .quiet()
3024            .args(["check-ref-format", "--branch", &branch])
3025            .stdout(std::process::Stdio::null())
3026            .stderr(std::process::Stdio::null())
3027            .status()
3028            .ok()
3029            .filter(|s| s.success())?;
3030        if (self.reviewed_commits.is_some()
3031            || self
3032                .candidates
3033                .iter()
3034                .any(|c| c.agent == "(existing branch)"))
3035            && self.pr_head.as_deref() != Some(branch.as_str())
3036        {
3037            return None;
3038        }
3039        Some(branch)
3040    }
3041
3042    /// Recorded public head, falling back to the winner for older runs.
3043    pub fn pr_branch(&self) -> Option<&str> {
3044        self.pr_head
3045            .as_deref()
3046            .or_else(|| self.winner().map(|w| w.branch.as_str()))
3047    }
3048
3049    /// Root of this run's worktrees.
3050    pub fn worktree_root(&self) -> PathBuf {
3051        self.config
3052            .graph
3053            .worktree_root
3054            .clone()
3055            .unwrap_or_else(default_worktree_root)
3056            .join(self.short())
3057    }
3058
3059    /// Record lockfiles a rescue commit withheld; a path already recorded by an
3060    /// earlier round is not repeated.
3061    pub fn note_withheld(&mut self, node: &str, strays: &[crate::git::Stray]) {
3062        for s in strays {
3063            if self.withheld.iter().any(|w| w.path == s.path) {
3064                continue;
3065            }
3066            self.event(
3067                node,
3068                format!(
3069                    "withheld stray lockfile {} ({}; the directory uses {})",
3070                    s.path, s.manager, s.kept_by
3071                ),
3072            );
3073            self.withheld.push(Withheld {
3074                path: s.path.clone(),
3075                manager: s.manager.clone(),
3076                kept_by: s.kept_by.clone(),
3077                node: node.to_owned(),
3078                at: Timestamp::now(),
3079            });
3080        }
3081    }
3082
3083    /// A prepared fallback on timeout is not an owner's request to replace
3084    /// an existing human-edited payload. Explicit selections keep their source.
3085    pub(crate) fn explicit_github_text_selection(&self) -> bool {
3086        self.github_text.as_ref().is_some_and(|gate| {
3087            gate.resolved
3088                && gate.question.as_ref().is_some_and(|id| {
3089                    crate::ask::Questions::open()
3090                        .get_for_effects(id)
3091                        .is_ok_and(|q| q.run == self.id && q.resolution().is_some())
3092                })
3093        })
3094    }
3095
3096    /// Save this marker together with the forge operation's successful checkpoint.
3097    /// Selecting a payload, accepting a reply and queuing a post do not call it.
3098    pub(crate) fn record_github_text_publication(&mut self, url: &str) {
3099        if let Some(gate) = &mut self.github_text
3100            && gate.resolved
3101            && let Some(inquiry) = &gate.question
3102            && let Some(choice) = gate.choice
3103        {
3104            gate.publication = Some(GithubTextPublication {
3105                inquiry: inquiry.clone(),
3106                fingerprint: gate.fingerprint.clone(),
3107                choice,
3108                url: url.to_owned(),
3109            });
3110        }
3111    }
3112
3113    /// Carry durable dispatch ownership into driver admission without treating
3114    /// dispatch itself as a receipt or replaying the owner's command.
3115    pub(crate) fn carry_dispatched_resumes(&mut self, task: &crate::queue::Task) {
3116        self.next_pass_inquiries = task
3117            .dispatched_resumes
3118            .iter()
3119            .filter(|(inquiry, run)| {
3120                **run == self.id && !self.decision_starts.contains_key(*inquiry)
3121            })
3122            .map(|(inquiry, _)| inquiry.clone())
3123            .collect();
3124    }
3125
3126    /// Open a pass for the process that is about to drive this run. A pass
3127    /// left open by an earlier process is closed as [`PassEnd::Unrecorded`];
3128    /// one that recorded its own end is never touched.
3129    pub fn begin_pass(&mut self) {
3130        let now = Timestamp::now();
3131        self.note_output_activity(now);
3132        if let Some(last) = self.passes.last_mut()
3133            && last.end.is_none()
3134        {
3135            last.end = Some(PassEnd::Unrecorded);
3136            last.ended_at = Some(now);
3137        }
3138        for inquiry in std::mem::take(&mut self.next_pass_inquiries) {
3139            self.decision_starts
3140                .entry(inquiry)
3141                .or_insert(self.passes.len());
3142        }
3143        let resumed = !self.passes.is_empty() || !self.candidates.is_empty();
3144        self.passes.push(RunPass {
3145            index: self.passes.len(),
3146            started_at: now,
3147            resumed,
3148            ended_at: None,
3149            end: None,
3150            task_entry: std::mem::take(&mut self.next_pass_task_entry),
3151        });
3152    }
3153
3154    /// Close the open pass as parked for `cause`. A pass that already has an
3155    /// end keeps it (the first reason wins).
3156    pub fn end_pass_parked(&mut self, cause: ParkCause) {
3157        if let Some(last) = self.passes.last_mut()
3158            && last.end.is_none()
3159        {
3160            last.end = Some(PassEnd::Parked { cause });
3161            last.ended_at = Some(Timestamp::now());
3162        }
3163    }
3164
3165    /// Resolve legacy delivery intent only from an already published PR and approval binding.
3166    fn recovery_disposition(&self) -> Option<crate::pr_recovery::Disposition> {
3167        let selected = self.pr_recovery.as_ref()?;
3168        selected.disposition.or_else(|| {
3169            (self.config.merge.mode == MergeMode::Pr
3170                && self.land_approval.is_some()
3171                && self.pr.as_ref().is_some_and(|pr| pr.url == selected.url))
3172            .then_some(crate::pr_recovery::Disposition::Land)
3173        })
3174    }
3175
3176    /// Validate a resumed recovery against its own durable configuration and landing records.
3177    pub fn configure_recovery_resume(&mut self) -> anyhow::Result<()> {
3178        if let Some(mut selected) = self.pr_recovery.clone() {
3179            selected.disposition = self.recovery_disposition();
3180            selected.configure(&mut self.config)?;
3181        }
3182        Ok(())
3183    }
3184
3185    /// Only a confirmed merge of the selected public PR completes a delivery task.
3186    pub fn public_delivery_complete(&self) -> bool {
3187        self.status == RunStatus::Merged
3188            && self.config.merge.mode == MergeMode::Pr
3189            && self
3190                .merge
3191                .as_ref()
3192                .is_some_and(|m| m.ok && !m.empty && m.mode == MergeMode::Pr)
3193            && self.pr.as_ref().is_some_and(|p| {
3194                p.state.eq_ignore_ascii_case("merged")
3195                    && self.pr_recovery.as_ref().is_some_and(|s| {
3196                        s.url == p.url
3197                            && self.recovery_disposition()
3198                                == Some(crate::pr_recovery::Disposition::Land)
3199                    })
3200            })
3201            && self.pr_pushed_head.as_deref().is_some_and(|head| {
3202                self.pr_merged_head.as_deref() == Some(head)
3203                    && self.check_delivery_evidence(head).is_ok()
3204                    && self.land_approval.as_ref().is_some_and(|a| {
3205                        a.head == head
3206                            && crate::ask::Questions::open()
3207                                .get_for_effects(&a.question)
3208                                .is_ok_and(|q| {
3209                                    q.run == self.id
3210                                        && q.node == crate::land::APPROVAL_NODE
3211                                        && crate::land::approval(q.resolution().as_deref())
3212                                            == crate::land::Approval::Merge
3213                                        && q.merge_target.as_ref().is_some_and(|t| {
3214                                            t.head == head
3215                                                && self.pr.as_ref().is_some_and(|p| t.pr == p.url)
3216                                        })
3217                                })
3218                    })
3219            })
3220    }
3221
3222    /// Validate evidence for exactly the head about to be published or merged.
3223    pub fn check_delivery_evidence(&self, head: &str) -> anyhow::Result<()> {
3224        if self.recovery_disposition() != Some(crate::pr_recovery::Disposition::Land) {
3225            return Ok(());
3226        }
3227        let commands_match = |outcomes: &[CommandOutcome], commands: &[String]| {
3228            !commands.is_empty()
3229                && outcomes.len() == commands.len()
3230                && outcomes
3231                    .iter()
3232                    .zip(commands)
3233                    .all(|(o, c)| o.ok() && &o.command == c)
3234        };
3235        anyhow::ensure!(
3236            self.gate_ran
3237                && self.gate_head.as_deref() == Some(head)
3238                && commands_match(&self.gate, &self.config.verify.gate),
3239            "delivery requires successful configured gate commands on the exact final head; request a fresh recovery review"
3240        );
3241        anyhow::ensure!(
3242            self.reviews.last().is_some_and(|r| r.clean
3243                && r.expected > 0
3244                && r.answered == r.expected
3245                && r.head == head
3246                && r.verified_head.as_deref() == Some(head)
3247                && commands_match(&r.e2e, &self.config.verify.e2e)),
3248            "delivery requires complete clean review and configured e2e commands on the exact final head; request a fresh recovery review"
3249        );
3250        Ok(())
3251    }
3252
3253    /// Reconcile after Git updates as well as on reentry after an interrupted save.
3254    /// Unknown legacy heads cannot establish current verification.
3255    pub fn reconcile_verification_head(&mut self, head: &str) {
3256        let stale_gate = self.gate_ran && self.gate_head.as_deref() != Some(head);
3257        let stale_e2e = self.head_e2e.as_ref().is_some_and(|e| e.head != head);
3258        if stale_gate || stale_e2e {
3259            self.verification_history.push(VerificationEvidence {
3260                superseded_by: Some(head.to_owned()),
3261                archived_at: Some(Timestamp::now()),
3262                fixes_spent: Some(self.gate_fixes.len()),
3263                gate_head: self.gate_head.clone(),
3264                gate_ran: self.gate_ran,
3265                gate: self.gate.clone(),
3266                e2e: self.head_e2e.clone(),
3267            });
3268            if stale_gate {
3269                let previous = self
3270                    .gate_head
3271                    .as_deref()
3272                    .map(short)
3273                    .unwrap_or_else(|| "unknown".into());
3274                self.event(
3275                    "gate",
3276                    format!(
3277                        "archived gate on {previous}, superseded by {}; {} gate-fix round(s) already spent stay spent",
3278                        short(head),
3279                        self.gate_fixes.len()
3280                    ),
3281                );
3282                self.gate.clear();
3283                self.gate_ran = false;
3284                self.gate_head = None;
3285                self.pre_gate.clear();
3286                self.pre_gate_commit = None;
3287            }
3288            if stale_e2e {
3289                self.head_e2e = None;
3290            }
3291        }
3292    }
3293
3294    /// Structured current failures take precedence over successful progress events.
3295    pub fn verification_blocking_cause(&self) -> Option<String> {
3296        if self.base_sync_blocked() {
3297            return self
3298                .base_sync
3299                .as_ref()
3300                .and_then(|s| s.conflict.as_ref())
3301                .map(|detail| format!("Base-sync conflict: {detail}"));
3302        }
3303        if let Some(resource) = &self.resource_block {
3304            return Some(resource.detail.clone());
3305        }
3306        if self.status != RunStatus::Blocked {
3307            return None;
3308        }
3309        if crate::graph::review_conclusion(&self.reviews, self.config.graph.review_rounds)
3310            == Some(RunStatus::Blocked)
3311        {
3312            return self.reviews.last().map(|r| format!(
3313                "review blocked on reviewed head {} ({} blocking finding(s), {}/{} reviewers answered)",
3314                r.head, r.blocking, r.answered, r.expected
3315            ));
3316        }
3317        if let Some(e) = &self.head_e2e
3318            && !e.passed
3319            && e.outcomes.iter().any(|o| !o.ok())
3320        {
3321            return Some(format!(
3322                "verify.e2e failed on head {}; nothing published",
3323                e.head
3324            ));
3325        }
3326        if let Some(e) = &self.gate_repair_e2e
3327            && !e.passed
3328            && e.outcomes.iter().any(|o| !o.ok())
3329        {
3330            return Some(format!(
3331                "verify.e2e failed on head {} after gate repair; nothing published",
3332                e.head
3333            ));
3334        }
3335        if self.gate_ran && self.gate.iter().any(|o| !o.ok()) {
3336            return Some(format!(
3337                "{} on head {} after {} gate-fix round(s); nothing published",
3338                crate::stop_reason::command_failure(
3339                    "gate",
3340                    self.gate.iter().find(|o| !o.ok()).unwrap()
3341                ),
3342                self.gate_head.as_deref().unwrap_or("unknown"),
3343                self.gate_fixes.len()
3344            ));
3345        }
3346        None
3347    }
3348
3349    /// Whether the configured gate commands completed successfully, independent of e2e.
3350    pub(crate) fn gate_commands_allow_progress(&self) -> bool {
3351        self.gate_status().ok()
3352            || (self
3353                .pr_recovery
3354                .as_ref()
3355                .is_none_or(|s| s.disposition == Some(crate::pr_recovery::Disposition::Review))
3356                && self.gate_ran
3357                && self.gate_status() == GateStatus::NotConfigured)
3358    }
3359
3360    /// Empty verification can finish an intentional workflow, without claiming a test pass.
3361    pub fn gate_allows_progress(&self) -> bool {
3362        self.gate_commands_allow_progress()
3363            && self
3364                .head_e2e
3365                .as_ref()
3366                .is_none_or(|e| e.passed && self.gate_head.as_deref() == Some(e.head.as_str()))
3367    }
3368
3369    /// Note something in the run log and on the tracing stream.
3370    pub fn event(&mut self, node: &str, message: impl Into<String>) {
3371        let message = message.into();
3372        tracing::info!(node, "{message}");
3373        self.events.push(Event {
3374            at: Timestamp::now(),
3375            node: node.to_owned(),
3376            message,
3377        });
3378    }
3379
3380    /// The honest state of the final gate.
3381    ///
3382    /// Never derive this from `gate.is_empty()` alone anywhere else in the
3383    /// codebase — `NotRun` and `NotConfigured` both leave `gate`
3384    /// empty, and only this method (backed by [`Self::gate_ran`]) tells them
3385    /// apart. An empty attempt is never verification evidence.
3386    pub fn gate_status(&self) -> GateStatus {
3387        if !self.gate_ran {
3388            GateStatus::NotRun
3389        } else if self.gate.is_empty() {
3390            GateStatus::NotConfigured
3391        } else if self.gate.iter().all(CommandOutcome::ok) {
3392            GateStatus::Passed
3393        } else {
3394            GateStatus::Failed
3395        }
3396    }
3397
3398    /// Record that `seat` was just sent a prompt for `node`, with the given
3399    /// wall-clock budget. `attempt` is 0 for the first ask and N for the Nth
3400    /// nudge or resume, purely for display — it does not change how the seat
3401    /// is treated.
3402    pub fn seat_started(
3403        &mut self,
3404        node: &str,
3405        seat: &str,
3406        timeout: std::time::Duration,
3407        attempt: usize,
3408    ) {
3409        self.active.insert(
3410            seat.to_owned(),
3411            ActiveSeat {
3412                node: node.to_owned(),
3413                started_at: Timestamp::now(),
3414                timeout_secs: timeout.as_secs(),
3415                attempt,
3416                task: None,
3417                command: None,
3418                index: None,
3419                total: None,
3420            },
3421        );
3422    }
3423
3424    /// The wave's pre-spawn wait is over: restart the clock of every seat of
3425    /// this batch so `started_at` means "the CLI is being spawned now".
3426    pub fn seats_spawning(&mut self, node: &str, attempt: usize) {
3427        self.resource_wait = None;
3428        let now = Timestamp::now();
3429        for a in self.active.values_mut() {
3430            if a.task.is_none() && a.node == node && a.attempt == attempt {
3431                a.started_at = now;
3432            }
3433        }
3434    }
3435
3436    /// `seat` holds its parallelism permit and its CLI is being spawned now.
3437    pub fn seat_spawned(&mut self, seat: &str) {
3438        if let Some(a) = self.active.get_mut(seat) {
3439            a.started_at = Timestamp::now();
3440        }
3441    }
3442
3443    /// Record that `seat` has answered, whatever the answer was.
3444    pub fn seat_finished(&mut self, seat: &str) {
3445        self.active.remove(seat);
3446    }
3447
3448    /// Record that `task` (`"e2e"` or `"gate"` — a shell-command list run
3449    /// outside any seat) has just started `command`, the `index`-th of
3450    /// `total`. Called at every command boundary, not once for the whole
3451    /// list: `verify.e2e` / `verify.gate` apply `timeout` per command, so
3452    /// this is the only way a reader can tell "how long is left" for
3453    /// whichever command is actually running right now, rather than a stale
3454    /// budget left over from the first one.
3455    #[allow(clippy::too_many_arguments)]
3456    pub fn task_command(
3457        &mut self,
3458        task: &str,
3459        node: &str,
3460        attempt: usize,
3461        command: &str,
3462        index: usize,
3463        total: usize,
3464        timeout: std::time::Duration,
3465    ) {
3466        self.active.insert(
3467            task.to_owned(),
3468            ActiveSeat {
3469                node: node.to_owned(),
3470                started_at: Timestamp::now(),
3471                timeout_secs: timeout.as_secs(),
3472                attempt,
3473                task: Some(task.to_owned()),
3474                command: Some(command.to_owned()),
3475                index: Some(index),
3476                total: Some(total),
3477            },
3478        );
3479    }
3480
3481    /// Record that `task` has finished its whole command list for this
3482    /// attempt.
3483    pub fn task_finished(&mut self, task: &str) {
3484        self.active.remove(task);
3485    }
3486
3487    /// The seats — never task entries — currently mid-answer. What
3488    /// `report::active_seats` and the phone's "who has not answered yet"
3489    /// note need: a seat's identifier is safe to show ([`ActiveSeat`]'s doc),
3490    /// so nothing here filters anything out beyond the type tag itself.
3491    pub fn seats_active(&self) -> impl Iterator<Item = (&String, &ActiveSeat)> {
3492        self.active.iter().filter(|(_, a)| a.task.is_none())
3493    }
3494
3495    /// The command-list tasks — never seat entries — currently running.
3496    /// Counterpart to [`Self::seats_active`]; see [`ActiveSeat::task`] for
3497    /// the tag both read.
3498    pub fn tasks_active(&self) -> impl Iterator<Item = (&String, &ActiveSeat)> {
3499        self.active.iter().filter(|(_, a)| a.task.is_some())
3500    }
3501
3502    /// Drop every seat this state still lists as answering, reporting whether
3503    /// anything was dropped.
3504    ///
3505    /// Called first thing in `execute`, on every entry — fresh, resumed, or
3506    /// recovering a stall — because an entry here only means something while
3507    /// the process that wrote it is still asking that seat something. A
3508    /// process killed mid-wave leaves its last batch of seats here with
3509    /// nobody left to clear them, and the next process to touch this run must
3510    /// not let that leftover read as "still going" before it has asked
3511    /// anyone anything.
3512    pub fn clear_active(&mut self) -> bool {
3513        if self.active.is_empty() {
3514            return false;
3515        }
3516        self.active.clear();
3517        true
3518    }
3519
3520    /// Does every seat this run still lists as [`Self::active`] sit past its
3521    /// own [`ActiveSeat::timeout_secs`]? `false` when nothing is active at
3522    /// all — an empty map is not evidence of anything overrunning.
3523    ///
3524    /// This alone is not proof the run is dead: a seat's own attempt can
3525    /// legitimately run a little past its budget while the process driving it
3526    /// is still tearing the attempt down. Every caller pairs this with its own
3527    /// `!live` reading (`daemon::is_working_on`) before treating the run as
3528    /// abandoned — this module cannot check that itself without depending on
3529    /// `crate::daemon`, and callers already have to ask that question anyway.
3530    #[must_use]
3531    pub fn active_all_overrun(&self, now: Timestamp) -> bool {
3532        !self.active.is_empty()
3533            && self
3534                .active
3535                .values()
3536                .all(|a| a.elapsed_secs(now) > a.timeout_secs as i64)
3537    }
3538
3539    /// Whether a process is actually still driving this run, given whether a
3540    /// daemon's heartbeat claims it and process-liveness/identity queries for
3541    /// [`Self::driver_pid`].
3542    ///
3543    /// A daemon claim wins outright when present — it is the stronger,
3544    /// independently-heartbeating signal. Absent that (every manual `magi
3545    /// run` / `magi review`, and every daemon-driven run whose daemon has
3546    /// since exited cleanly), `driver_pid` is asked directly. A live answer
3547    /// alone is not enough to trust, though: pids get reused, so `identity`
3548    /// re-queries whoever currently holds that pid and the result must still
3549    /// match [`Self::driver_started_at`] — the marker recorded at the same
3550    /// moment `driver_pid` was — before this reads `Live`. A mismatch means
3551    /// a *different* process now answers to that number, which is exactly as
3552    /// good as proof the original driver is gone, so that reads `Dead`. The
3553    /// marker is an epoch-seconds integer string; one that is not (a run
3554    /// recorded when it was a locale-dependent `ps` string) reads
3555    /// [`Liveness::Unknown`], never `Dead`. No
3556    /// marker to compare against (an old run, or a platform this build could
3557    /// not ask at record time) or a `None` from either query, and this
3558    /// cannot tell either way, so it reads [`Liveness::Unknown`] — never
3559    /// guessed as [`Liveness::Dead`] out of mere silence. A display that
3560    /// guessed "dead" out of missing information would be exactly the
3561    /// mtime-and-task-manager guessing this type exists to replace.
3562    ///
3563    /// Kept generic over `query` and `identity` so a test can inject answers
3564    /// without spawning a real process query — production code goes through
3565    /// [`Self::liveness`], which supplies [`crate::proc::pid_status`] and
3566    /// [`crate::proc::process_started_at`].
3567    #[must_use]
3568    pub fn liveness_with<F, G>(&self, daemon_claims: bool, query: F, identity: G) -> Liveness
3569    where
3570        F: FnOnce(u32) -> Option<bool>,
3571        G: FnOnce(u32) -> Option<String>,
3572    {
3573        if daemon_claims {
3574            return Liveness::Live;
3575        }
3576        // The driver said itself that it stopped; its pid may well be alive
3577        // (a daemon outlives the runs it drives), so it is not asked.
3578        if self.driver_exited {
3579            return Liveness::Dead;
3580        }
3581        let Some(pid) = self.driver_pid else {
3582            return Liveness::Unknown;
3583        };
3584        match query(pid) {
3585            Some(false) => Liveness::Dead,
3586            None => Liveness::Unknown,
3587            Some(true) => {
3588                let Some(recorded) = &self.driver_started_at else {
3589                    return Liveness::Unknown;
3590                };
3591                // A marker in the old locale-dependent format can never be
3592                // compared reliably, so it proves nothing either way.
3593                if !crate::proc::is_identity_marker(recorded) {
3594                    return Liveness::Unknown;
3595                }
3596                match identity(pid) {
3597                    Some(current) if !crate::proc::is_identity_marker(&current) => {
3598                        Liveness::Unknown
3599                    }
3600                    Some(current) if *recorded == current => Liveness::Live,
3601                    Some(_) => Liveness::Dead,
3602                    None => Liveness::Unknown,
3603                }
3604            }
3605        }
3606    }
3607
3608    /// [`Self::liveness_with`], backed by the real process-liveness and
3609    /// identity queries.
3610    #[must_use]
3611    pub fn liveness(&self, daemon_claims: bool) -> Liveness {
3612        self.liveness_under(&home(), daemon_claims)
3613    }
3614
3615    /// The same judge, rooted at the caller's run store.
3616    #[must_use]
3617    pub fn liveness_under(&self, home: &Path, daemon_claims: bool) -> Liveness {
3618        self.liveness_under_with(
3619            home,
3620            daemon_claims,
3621            crate::proc::pid_status,
3622            crate::proc::process_started_at,
3623        )
3624    }
3625
3626    pub(crate) fn liveness_under_with<F, G>(
3627        &self,
3628        home: &Path,
3629        daemon_claims: bool,
3630        query: F,
3631        identity: G,
3632    ) -> Liveness
3633    where
3634        F: FnOnce(u32) -> Option<bool>,
3635        G: FnOnce(u32) -> Option<String>,
3636    {
3637        if daemon_claims {
3638            return Liveness::Live;
3639        }
3640        let process = self.liveness_with(false, query, identity);
3641        crate::driver::judge(self, home, process)
3642    }
3643
3644    /// Clear every seat this run still lists as active and fail it, unless it
3645    /// had already reached a terminal status some other way.
3646    ///
3647    /// Callers must already have proven this run is dead — [`Self::active_all_overrun`]
3648    /// plus their own `!live` reading — before calling this; it does not
3649    /// check either itself. Unlike [`Self::clear_active`] (dropping a resumed
3650    /// run's own stale wave before repopulating it, called unconditionally at
3651    /// the top of every `execute()`), this is a verdict: a run left this way
3652    /// has nothing left to repopulate the wave, ever, and must stop reading as
3653    /// `implementing` (or whichever node) forever.
3654    pub fn abandon(&mut self, by: &str) {
3655        let seats: Vec<String> = self.active.keys().cloned().collect();
3656        self.clear_active();
3657        if !self.status.done() {
3658            self.status = RunStatus::Failed;
3659        }
3660        self.event(
3661            by,
3662            format!(
3663                "abandoned: seat(s) {} left behind by a killed process, past their own \
3664                 timeout with no live daemon claiming this run",
3665                seats.join(", ")
3666            ),
3667        );
3668    }
3669
3670    /// Reserve a fresh run's identity and persist its initial record.
3671    /// Call exactly once, before exposing the id; never call on a loaded run.
3672    pub fn reserve(&mut self) -> Result<()> {
3673        self.reserve_under(&home())
3674    }
3675
3676    /// [`Self::reserve`] with an explicit store home.
3677    pub fn reserve_under(&mut self, home: &Path) -> Result<()> {
3678        self.reserve_with(home, &crate::id_reserve::IdSource::new(new_id))
3679    }
3680
3681    fn reserve_with(&mut self, home: &Path, ids: &crate::id_reserve::IdSource) -> Result<()> {
3682        let root = home.join("runs");
3683        std::fs::create_dir_all(&root).context("create runs root")?;
3684        let initial = self.id.clone();
3685        ids.reserve(
3686            (!ids.is_custom()).then_some(initial.as_str()),
3687            "run",
3688            |id| {
3689                let dir = root.join(id);
3690                if !crate::id_reserve::create_dir(&dir)? {
3691                    return Ok(false);
3692                }
3693                // Branches and worktrees use only the suffix. Publish our directory
3694                // before scanning: concurrent contenders either see each other and
3695                // retry, or the later one sees the earlier reservation and retries.
3696                for entry in std::fs::read_dir(&root).context("scan reserved run ids")? {
3697                    let name = entry?.file_name();
3698                    let Some(other) = name.to_str() else { continue };
3699                    if other != id && is_run_id(other) && short_of(other) == short_of(id) {
3700                        // Only remove our own empty directory, never existing data.
3701                        std::fs::remove_dir(&dir).context("release colliding run suffix")?;
3702                        return Ok(false);
3703                    }
3704                }
3705                self.id = id.to_owned();
3706                // A failed first write rolls back only our own directory:
3707                // `remove_dir` refuses anything with contents, so a partial
3708                // record or another run's data is never deleted.
3709                if let Err(e) = self.save_under(home) {
3710                    let _ = std::fs::remove_dir(&dir);
3711                    return Err(e);
3712                }
3713                Ok(true)
3714            },
3715        )?;
3716        Ok(())
3717    }
3718
3719    pub(crate) fn note_output_activity(&mut self, at: Timestamp) {
3720        self.output_activity_at = Some(self.output_activity_at.unwrap_or(self.updated_at).max(at));
3721    }
3722
3723    pub(crate) fn output_activity(&self) -> Timestamp {
3724        self.passes.iter().fold(
3725            self.output_activity_at.unwrap_or(self.updated_at),
3726            |at, pass| {
3727                at.max(pass.started_at)
3728                    .max(pass.ended_at.unwrap_or(pass.started_at))
3729            },
3730        )
3731    }
3732
3733    /// Flush to `run.json`, atomically, under the process-global [`home`].
3734    pub fn save(&mut self) -> Result<()> {
3735        let home = home();
3736        self.save_under(&home)
3737    }
3738
3739    /// [`Self::save`], rooted at an explicit `home` instead of the
3740    /// process-global one.
3741    ///
3742    /// For a caller that was already handed its own `home` explicitly — a
3743    /// housekeeping pass, mainly, for the same reason `Queue::at` and the
3744    /// daemon status path are parameters rather than resolved here (see
3745    /// `daemon::drive`'s own doc) — falling through to the global would write
3746    /// back through whichever directory some *other* process or test pinned
3747    /// into that `OnceLock` first, not the one this call was actually handed.
3748    pub fn save_under(&mut self, home: &Path) -> Result<()> {
3749        self.save_under_at(home, Timestamp::now())
3750    }
3751
3752    pub(crate) fn save_under_at(&mut self, home: &Path, at: Timestamp) -> Result<()> {
3753        // Freeze legacy age before a bookkeeping flush changes updated_at.
3754        self.output_activity_at.get_or_insert(self.updated_at);
3755        self.record_base_interruption();
3756        self.updated_at = at;
3757        let dir = home.join("runs").join(&self.id);
3758        std::fs::create_dir_all(&dir).with_context(|| format!("create {}", dir.display()))?;
3759        let body = serde_json::to_string_pretty(self).context("serialize run state")?;
3760        let tmp = dir.join("run.json.tmp");
3761        std::fs::write(&tmp, &body).with_context(|| format!("write {}", tmp.display()))?;
3762        std::fs::rename(&tmp, dir.join("run.json")).with_context(|| "replace run.json")?;
3763        Ok(())
3764    }
3765
3766    /// Load a run by id or unambiguous id prefix.
3767    pub fn load(id: &str) -> Result<Self> {
3768        let resolved = resolve_id(id)?;
3769        let path = run_dir(&resolved).join("run.json");
3770        let body =
3771            std::fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
3772        let state: Self =
3773            serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
3774        migrate_schema(state)
3775    }
3776
3777    /// [`Self::load`], rooted at an explicit `home` instead of the
3778    /// process-global one, and for a full id rather than a prefix — a caller
3779    /// with its own `home` already has the exact id (from a `RunState` it
3780    /// already read, or from `Task::runs`) and has no `runs_root` to search
3781    /// for a prefix against in the first place. Same reasoning as
3782    /// [`Self::save_under`]: a caller holding its own `home` explicitly must
3783    /// not read back through whichever directory some *other* process or
3784    /// test pinned into the global [`home`] `OnceLock` first.
3785    pub fn load_under(id: &str, home: &Path) -> Result<Self> {
3786        let path = home.join("runs").join(id).join("run.json");
3787        let body =
3788            std::fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
3789        let state: Self =
3790            serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
3791        migrate_schema(state)
3792    }
3793}
3794
3795pub(crate) fn migrate_schema(mut state: RunState) -> Result<RunState> {
3796    state.output_activity_at.get_or_insert(state.updated_at);
3797    // Schema 5 predates deferred e2e. Its empty e2e lists therefore mean
3798    // "not configured", never "deferred"; serde's field defaults retain
3799    // exactly that representation while this migration permits resumes.
3800    if state.schema == 5 {
3801        state.schema = 6;
3802    }
3803    // Schema 6 predates `gate_ran` and could not tell "never attempted or
3804    // resource-blocked" apart from "ran with zero commands configured" — see
3805    // `SCHEMA`'s doc for schema 7. A non-empty `gate` is a real recorded
3806    // attempt either way, so it is trusted as `gate_ran = true` rather than
3807    // spent again; an empty one is simply handed back to the next `gate()`
3808    // call, which re-attempts it and, for the zero-commands case, resolves
3809    // instantly.
3810    if state.schema == 6 {
3811        state.gate_ran = !state.gate.is_empty();
3812        state.schema = 7;
3813    }
3814    // Schema 7's main review loop always checked `e2e` against the round's
3815    // own `head`, it just never wrote that fact into `verified_head` unless
3816    // a catch-up run had checked a *different* commit — see `SCHEMA`'s doc
3817    // for schema 8. Reconstructing `Some(head)` for a round whose `e2e` held
3818    // a real attempt restores a fact that was always true; `verified_at` has
3819    // no historical value to recover and stays `None`.
3820    if state.schema == 7 {
3821        for round in &mut state.reviews {
3822            if round.verified_head.is_none()
3823                && matches!(round.e2e_status(), E2eStatus::Passed | E2eStatus::Failed)
3824            {
3825                round.verified_head = Some(round.head.clone());
3826            }
3827        }
3828        state.schema = 8;
3829    }
3830    // Schema 8 predates `operator_fixes`. There is nothing to reconstruct —
3831    // an old run simply never had one requested — so `#[serde(default)]`
3832    // already left it as the correct empty `Vec`; this only advances the
3833    // version number.
3834    if state.schema == 8 {
3835        state.schema = 9;
3836    }
3837    // Schema 9 predates `RunStatus::VerifiedNoop` and
3838    // `Candidate::verified_noop`. Nothing to reconstruct: an old record never
3839    // made the claim, `#[serde(default)]` already reads `verified_noop` as
3840    // `None` on every candidate, and a `VerifiedNoop` status cannot appear in
3841    // a schema-9 record at all — see `SCHEMA`'s doc for schema 10. This only
3842    // advances the version number.
3843    if state.schema == 9 {
3844        state.schema = 10;
3845    }
3846    // Schema 10 predates `released_to`: no old run ever had its worktree
3847    // handed over, and `#[serde(default)]` reads exactly that. Only the
3848    // version number advances.
3849    if state.schema == 10 {
3850        state.schema = 11;
3851    }
3852    // Schema 11 predates `driver_exited`. A run that had already ended
3853    // Blocked / Failed / Stalled, or was parked in Landing (which hands its
3854    // daemon slot back), stopped walking the graph, but its recorded
3855    // pid may belong to a daemon still alive doing other work, which would pin
3856    // it as running for good; those are marked exited. Any other status keeps
3857    // `false`, and its pid is asked as before. This is an inference from
3858    // status, sound because a schema-11 record was written by a build that is
3859    // gone once this one is installed (and a daemon claim, which wins
3860    // regardless, still protects a run a live daemon is driving).
3861    if state.schema == 11 {
3862        if matches!(
3863            state.status,
3864            RunStatus::Blocked | RunStatus::Failed | RunStatus::Stalled | RunStatus::Landing
3865        ) {
3866            state.driver_exited = true;
3867        }
3868        state.schema = 12;
3869    }
3870    // Schema 12 predates `origin`. Nothing is reconstructed: `None` already
3871    // says "unknown", which is the truth for a run nobody recorded. Only the
3872    // version number advances.
3873    if state.schema == 12 {
3874        state.schema = 13;
3875    }
3876    // Schema 13 predates `task_instruction`. Its `instruction` may include
3877    // generated review context, so it cannot supply authored criteria.
3878    // `#[serde(default)]` leaves the missing field as `None`; only the
3879    // version number advances, preserving origin and execution state.
3880    if state.schema == 13 {
3881        state.schema = 14;
3882    }
3883    // Only legacy, unfolded empty candidates lack a confirmed preservation
3884    // result, even if their CLI failed: failure never proves edits were saved.
3885    // Native schema-15 records and intentionally folded candidates
3886    // must not be re-flagged on every resume.
3887    if state.schema == 14 {
3888        for c in &state.candidates {
3889            if !c.folded && c.empty && c.verified_noop.is_none() {
3890                state
3891                    .candidate_preservation
3892                    .entry(c.label)
3893                    .or_insert_with(|| "legacy empty candidate requires inspection".to_owned());
3894            }
3895        }
3896        state.schema = 15;
3897    }
3898    // Native schema-15 preservation outcomes remain unchanged. Retirement
3899    // adds an execution fence without inferring any new preservation result.
3900    if state.schema == 15 {
3901        state.schema = 16;
3902    }
3903    // Legacy runs belong to the initial assignment unless a generation was
3904    // explicitly captured. Do not derive it from the task's current state.
3905    if state.schema == 16 {
3906        state.schema = SCHEMA;
3907    }
3908    if state.schema != SCHEMA {
3909        bail!(
3910            "run {} was written by a different magi (schema {}, this build \
3911                 speaks {SCHEMA})",
3912            state.id,
3913            state.schema
3914        );
3915    }
3916    Ok(state)
3917}
3918
3919impl RunState {
3920    /// Whether a later attempt took this run's worktree over, so a resume has
3921    /// nothing left to continue from.
3922    pub fn released(&self) -> bool {
3923        self.released_to.is_some()
3924    }
3925
3926    /// The winning candidate, once the tally has run.
3927    pub fn winner(&self) -> Option<&Candidate> {
3928        let label = self.tally.as_ref()?.winner;
3929        self.candidates.iter().find(|c| c.label == label)
3930    }
3931
3932    /// Candidates eligible for judging.
3933    pub fn viable(&self) -> Vec<&Candidate> {
3934        self.candidates.iter().filter(|c| c.viable()).collect()
3935    }
3936
3937    /// Did every candidate write nothing, and every one of them back it with
3938    /// evidence [`crate::graph`]'s adoption guard accepted?
3939    ///
3940    /// All-or-nothing on purpose: one candidate declaring `NO CHANGE NEEDED`
3941    /// while another simply failed to produce anything is not agreement, it
3942    /// is one candidate's unverified claim next to an ordinary loss, and the
3943    /// run must still read as the `Failed` it is. Only ever meaningful when
3944    /// [`Self::viable`] is already empty — a run with any real patch to judge
3945    /// never reaches the caller that asks this.
3946    pub fn all_candidates_verified_noop(&self) -> bool {
3947        !self.candidates.is_empty()
3948            && self
3949                .candidates
3950                .iter()
3951                .all(|c| c.empty && c.verified_noop.is_some())
3952    }
3953
3954    /// Findings still open when the review loop stopped trying: the last
3955    /// round's, exactly when that round was not clean. Empty on a run that
3956    /// never reviewed, or whose last round was clean.
3957    ///
3958    /// This is the last round's findings regardless of what the fixer claims
3959    /// to have addressed in that same round: a round that stopped the loop
3960    /// (round budget spent, or no tree progress for
3961    /// [`crate::graph::STAGNANT_LIMIT`] rounds) never had a *following* round
3962    /// to confirm the fix actually landed, and the self-reported adoption
3963    /// count is not trusted for that judgement either — see
3964    /// [`ReviewRound::progressed`].
3965    pub fn open_findings(&self) -> Vec<&Finding> {
3966        match self.reviews.last() {
3967            Some(r) if !r.clean => r
3968                .reviews
3969                .iter()
3970                .flat_map(|rec| rec.findings.iter())
3971                .collect(),
3972            _ => Vec::new(),
3973        }
3974    }
3975
3976    /// Every finding raised in the most recent review round, regardless of
3977    /// that round's own severity mix — unlike [`Self::open_findings`], not
3978    /// filtered to a round that was not clean. This is the pool `magi fix`
3979    /// reports as available to pick from: a round can conclude clean (no
3980    /// finding blocked merge) while still carrying minor findings nobody
3981    /// has acted on.
3982    pub fn last_round_findings(&self) -> Vec<&Finding> {
3983        self.reviews
3984            .last()
3985            .into_iter()
3986            .flat_map(|r| r.reviews.iter())
3987            .flat_map(|rec| rec.findings.iter())
3988            .collect()
3989    }
3990
3991    /// Look up a finding by id anywhere in this run's review history,
3992    /// together with the round and reviewer record that raised it — the
3993    /// provenance `magi fix` snapshots onto [`OperatorFixFinding`].
3994    pub fn finding(&self, id: &str) -> Option<(&ReviewRound, &ReviewRecord, &Finding)> {
3995        self.reviews.iter().find_map(|round| {
3996            round.reviews.iter().find_map(|rec| {
3997                rec.findings
3998                    .iter()
3999                    .find(|f| f.id == id)
4000                    .map(|f| (round, rec, f))
4001            })
4002        })
4003    }
4004
4005    /// Did this run reach a mergeable status (`Ready` or `Merged`) with
4006    /// review findings still open?
4007    ///
4008    /// That combination is the point of the review hand-off: the review
4009    /// round budget (or an unproductive round, see [`ReviewRound::progressed`])
4010    /// was spent while gate and e2e stayed green, so the run was handed off
4011    /// rather than blocked — but the findings did not disappear, and whoever
4012    /// reads the result should be told they are still there.
4013    pub fn handed_off_with_open_findings(&self) -> bool {
4014        matches!(self.status, RunStatus::Ready | RunStatus::Merged)
4015            && self.reviews.last().is_some_and(|r| !r.clean)
4016    }
4017
4018    /// Reached `Ready` because `[merge] mode = "none"` left it there by
4019    /// design, never to be picked up by the PR-polling merge watcher — as
4020    /// opposed to a `Ready` that is still a plausible landing candidate (a
4021    /// PR closed without merging, or a re-entry onto an already-concluded
4022    /// node). Both leave `status` at `Ready`; only this one leaves the
4023    /// winning branch permanently unwatched, which is what a caller needs to
4024    /// know before labelling the run in a listing.
4025    pub fn unmerged_by_design(&self) -> bool {
4026        self.status == RunStatus::Ready
4027            && self
4028                .merge
4029                .as_ref()
4030                .is_some_and(|m| m.mode == MergeMode::None)
4031    }
4032
4033    /// Did a step after the merge leave something only a human can finish?
4034    ///
4035    /// Derived, not a status: the merge happened, so `status` stays `Merged`
4036    /// and everything that branches on it keeps working. Display code asks
4037    /// this so a merged run with an unmerged release PR does not read as
4038    /// plain green.
4039    pub fn needs_attention(&self) -> bool {
4040        self.status == RunStatus::Merged
4041            && self
4042                .release_bump
4043                .as_ref()
4044                .is_some_and(|b| b.action_required.is_some())
4045    }
4046
4047    /// Local-time creation stamp for reports.
4048    pub fn created_local(&self) -> String {
4049        self.created_at
4050            .to_zoned(jiff::tz::TimeZone::system())
4051            .strftime("%Y-%m-%d %H:%M:%S")
4052            .to_string()
4053    }
4054
4055    /// Assert that this run is safe to delete.
4056    ///
4057    /// Refuses a run a live daemon is working on, and refuses any run whose
4058    /// candidate worktrees and branches have not been folded away with `magi
4059    /// fold`. The fold requirement is the real protection: it is what makes
4060    /// "delete" mean "remove a record" rather than "throw away a worktree
4061    /// somebody may still be editing".
4062    ///
4063    /// `in_flight` has to come from the caller, because a run's own status
4064    /// cannot answer the question. A daemon killed mid-run leaves its status at
4065    /// `implementing` forever, and a guard that trusted that would make every
4066    /// interrupted run permanently undeletable - the operator's only recourse
4067    /// being to edit `run.json` by hand, which is exactly the sort of thing
4068    /// this command exists to avoid. The queue already treats an orphaned
4069    /// `.lock` from a `SIGKILL`ed daemon the same way; this is that rule for
4070    /// runs.
4071    pub fn ensure_can_delete(&self, in_flight: bool) -> Result<()> {
4072        if in_flight {
4073            bail!(
4074                "run {} is being worked on by a live daemon right now",
4075                self.short()
4076            );
4077        }
4078        if self.candidates.iter().any(|c| !c.folded) {
4079            bail!(
4080                "run {} has unfolded candidates; fold first with `magi fold`",
4081                self.short()
4082            );
4083        }
4084        Ok(())
4085    }
4086}
4087
4088/// The short form of a commit, for a label a human or an LLM reads.
4089fn short(commit: &str) -> String {
4090    commit.chars().take(7).collect()
4091}
4092
4093/// The short form of a run id: the trailing block after the last `-`.
4094///
4095/// A free function as well as [`RunState::short`], because callers that have
4096/// only an id - an error message, a daemon status, a route handler - were
4097/// otherwise reimplementing the split, and two spellings of "short id" is one
4098/// rename away from branch names that no longer match their run.
4099pub fn short_of(id: &str) -> &str {
4100    id.split('-').next_back().unwrap_or(id)
4101}
4102
4103/// Where magi keeps its runs.
4104///
4105/// `MAGI_HOME` overrides the default, and [`set_home`] overrides both — which
4106/// is what lets the integration tests drive a whole graph without writing into
4107/// the operator's real history.
4108///
4109/// In a unit test build (`cfg(test)`), falling through to the real
4110/// `<data_local>/magi` is not a fallback worth having: it is exactly how
4111/// three broken fixture runs ended up in the operator's actual history and
4112/// were counted as `unreadable` by the deck. So a unit test that reaches this
4113/// point without [`set_home`] or `MAGI_HOME` gets this process's own temp
4114/// home (`test_home`) pinned for it.
4115///
4116/// It used to panic instead, to flag the test. But the home is process-global
4117/// and first-wins, so that panic fired only when no earlier test in the same
4118/// process had pinned one: the same test passed or failed by test order, and
4119/// the panic, raised from deep inside nested futures, showed up on Windows as
4120/// a stack overflow that took the whole test binary down. The protection the
4121/// panic was for - never the operator's real home - is kept either way.
4122pub fn home() -> PathBuf {
4123    #[cfg(test)]
4124    if HOME.get().is_none() && std::env::var_os("MAGI_HOME").is_none() {
4125        pin_test_home();
4126    }
4127    resolve_home(HOME.get().cloned(), std::env::var_os("MAGI_HOME"))
4128}
4129
4130/// The decision `home` makes, taking its two overrides as plain values
4131/// instead of reading the `OnceLock` and the environment itself.
4132///
4133/// Pulled out so the `cfg(test)` panic is asserted directly against a
4134/// `None, None` input, rather than racing every other unit test in the
4135/// binary for who touches the process-global `HOME` first.
4136fn resolve_home(pinned: Option<PathBuf>, magi_home_env: Option<std::ffi::OsString>) -> PathBuf {
4137    if let Some(dir) = pinned {
4138        return dir;
4139    }
4140    if let Some(dir) = magi_home_env {
4141        return PathBuf::from(dir);
4142    }
4143    #[cfg(test)]
4144    {
4145        panic!(
4146            "run::home() was reached in a test without run::set_home() or \
4147             MAGI_HOME; this would write into the operator's real \
4148             <data_local>/magi. Call `run::set_home(temp_dir)` before any \
4149             code path that touches a RunState."
4150        );
4151    }
4152    #[cfg(not(test))]
4153    {
4154        dirs::data_local_dir()
4155            .unwrap_or_else(|| PathBuf::from("."))
4156            .join("magi")
4157    }
4158}
4159
4160/// [`home`] without the test panic: `None` in a test that never pinned a
4161/// home, so best-effort writers (see [`crate::notices::raise`]) skip the write
4162/// instead of touching the operator's real state or aborting the test.
4163pub fn try_home() -> Option<PathBuf> {
4164    if cfg!(test) {
4165        HOME.get()
4166            .cloned()
4167            .or_else(|| std::env::var_os("MAGI_HOME").map(PathBuf::from))
4168    } else {
4169        Some(home())
4170    }
4171}
4172
4173/// Pin the run home for this process. The first call wins.
4174pub fn set_home(dir: PathBuf) {
4175    let _ = HOME.set(dir);
4176}
4177
4178/// A temp directory unique to this test process, created once and kept.
4179/// `set_home` is a first-wins `OnceLock`, so a fixed `temp_dir().join(..)`
4180/// would be shared by every concurrent `cargo test` process on the machine.
4181#[cfg(test)]
4182pub(crate) fn test_home() -> PathBuf {
4183    static DIR: std::sync::OnceLock<PathBuf> = std::sync::OnceLock::new();
4184    DIR.get_or_init(|| {
4185        tempfile::Builder::new()
4186            .prefix("magi-unit-home-")
4187            .tempdir()
4188            .expect("create the unit-test home")
4189            .keep()
4190    })
4191    .clone()
4192}
4193
4194/// [`set_home`] on [`test_home`]; the one way a unit test pins the home.
4195#[cfg(test)]
4196pub(crate) fn pin_test_home() {
4197    set_home(test_home());
4198}
4199
4200static HOME: std::sync::OnceLock<PathBuf> = std::sync::OnceLock::new();
4201
4202/// `<home>/runs`.
4203pub fn runs_root() -> PathBuf {
4204    home().join("runs")
4205}
4206
4207/// The worktree root a run uses when the config sets none: `~/wt/magi`.
4208///
4209/// One definition of the default, so the folder the janitor folds and the
4210/// folder the health view sizes cannot drift apart: a run with no configured
4211/// [`crate::config::Graph::worktree_root`] lays its worktrees exactly here.
4212pub fn default_worktree_root() -> PathBuf {
4213    dirs::home_dir()
4214        .unwrap_or_else(|| PathBuf::from("."))
4215        .join("wt")
4216        .join("magi")
4217}
4218
4219/// Directory for one run id.
4220pub fn run_dir(id: &str) -> PathBuf {
4221    runs_root().join(id)
4222}
4223
4224/// Every run id on disk, newest first.
4225///
4226/// A directory is a run because of its **name**, not because it holds a
4227/// readable `run.json`. A run whose very first save lost the machine's last
4228/// free bytes leaves `<id>/run.json.tmp` and nothing else, and filtering on
4229/// `run.json` made that run invisible everywhere: not in `magi list`, not in
4230/// `runs_unreadable`, not on the phone, so nothing could report it and no
4231/// route could clear it. `88c0` sat like that for two days. Unreadable is
4232/// counted, never hidden - the readers already say why each one cannot be
4233/// read, and `fold_unreadable` is how a record like this leaves.
4234pub fn list_ids() -> Vec<String> {
4235    list_ids_in(&runs_root())
4236}
4237
4238/// [`list_ids`] against an explicit runs root, for callers (and tests) that
4239/// must not depend on the process-global home.
4240pub fn list_ids_in(root: &Path) -> Vec<String> {
4241    let mut ids: Vec<String> = std::fs::read_dir(root)
4242        .into_iter()
4243        .flatten()
4244        .flatten()
4245        .filter(|e| e.path().is_dir())
4246        .map(|e| e.file_name().to_string_lossy().into_owned())
4247        .filter(|name| is_run_id(name))
4248        .collect();
4249    // Ids start with a sortable timestamp.
4250    ids.sort_unstable_by(|a, b| b.cmp(a));
4251    ids
4252}
4253
4254/// Does `name` have the shape [`new_id`] mints: `YYYYMMDD-HHMMSS-xxxx`?
4255///
4256/// The test for "this directory is a run", so a stray folder under
4257/// `<home>/runs` is not reported as a broken run.
4258///
4259/// The tag is checked for length and for being alphanumeric, not for being
4260/// hex: real ids are hex, but fixtures across this crate name runs
4261/// `...-dead` / `...-gone` / `...-once`, and a predicate that disowned those
4262/// would be asserting the fixtures' spelling rather than the shape.
4263pub fn is_run_id(name: &str) -> bool {
4264    let mut parts = name.split('-');
4265    let (Some(day), Some(time), Some(tag), None) =
4266        (parts.next(), parts.next(), parts.next(), parts.next())
4267    else {
4268        return false;
4269    };
4270    day.len() == 8
4271        && day.bytes().all(|b| b.is_ascii_digit())
4272        && time.len() == 6
4273        && time.bytes().all(|b| b.is_ascii_digit())
4274        && tag.len() == 4
4275        && tag.bytes().all(|b| b.is_ascii_alphanumeric())
4276}
4277
4278/// Expand an id prefix to exactly one run id.
4279pub fn resolve_id(prefix: &str) -> Result<String> {
4280    // A whole id names its directory, readable state or not: the run whose
4281    // `run.json` never landed still has to be reachable by `magi show` and
4282    // by the fold route, which is the only way its record ever leaves.
4283    if is_run_id(prefix) && run_dir(prefix).is_dir() {
4284        return Ok(prefix.to_owned());
4285    }
4286    let hits: Vec<String> = list_ids()
4287        .into_iter()
4288        .filter(|id| id.starts_with(prefix) || id.ends_with(prefix))
4289        .collect();
4290    match hits.len() {
4291        1 => Ok(hits.into_iter().next().expect("exactly one hit")),
4292        0 => bail!("no run matches `{prefix}`"),
4293        _ => bail!(
4294            "`{prefix}` matches {} runs: {}",
4295            hits.len(),
4296            hits.join(", ")
4297        ),
4298    }
4299}
4300
4301/// The most recent run, if any.
4302pub fn latest_id() -> Option<String> {
4303    list_ids().into_iter().next()
4304}
4305
4306/// An unreserved `YYYYMMDD-HHMMSS-xxxx` candidate, sortable and branch-safe.
4307/// Fresh entropy is independent of the blind seed. Entropy alone cannot prevent
4308/// collisions: production creation must use `RunState::reserve` before the id
4309/// escapes, reserving both the full id and its branch/worktree suffix on disk.
4310fn new_id() -> String {
4311    let stamp = Zoned::now().strftime("%Y%m%d-%H%M%S");
4312    let entropy = crate::rng::entropy();
4313    format!("{stamp}-{:04x}", (entropy ^ (entropy >> 32)) & 0xffff)
4314}
4315
4316/// Keep the last `max` bytes of `text`, on a line boundary.
4317pub fn tail(text: &str, max: usize) -> String {
4318    if text.len() <= max {
4319        return text.to_owned();
4320    }
4321    let mut cut = text.len() - max;
4322    while cut < text.len() && !text.is_char_boundary(cut) {
4323        cut += 1;
4324    }
4325    let slice = &text[cut..];
4326    let start = slice.find('\n').map_or(0, |i| i + 1);
4327    format!(
4328        "[... {} earlier bytes omitted ...]\n{}",
4329        cut,
4330        &slice[start..]
4331    )
4332}
4333
4334/// Bytes of verification output recorded and handed to fixers/reviewers.
4335pub const VERIFY_SUMMARY: usize = 32_768;
4336
4337/// A backtrace frame line (`  41: 0x102e80de0 - <path>::{closure#0}` or
4338/// `  3: std::panicking::begin_panic`), or the `at file:line` line under one.
4339/// Deliberately narrow: a frame needs a number, a colon and either an address
4340/// or a path, so ordinary `12: something` output is never dropped.
4341fn is_frame(line: &str, after_frame: bool) -> bool {
4342    let t = line.trim_start();
4343    if after_frame && t.starts_with("at ") {
4344        return true;
4345    }
4346    let digits = t.bytes().take_while(u8::is_ascii_digit).count();
4347    if digits == 0 || !t[digits..].starts_with(": ") {
4348        return false;
4349    }
4350    let rest = t[digits + 2..].trim_start();
4351    rest.starts_with("0x") || rest.contains("::")
4352}
4353
4354/// Priority (lower first) and following context (assertion text, `left`/`right`).
4355fn trigger_context(line: &str) -> Option<(u8, usize)> {
4356    // Match colored nextest markers without changing the stored evidence.
4357    let mut plain = String::new();
4358    let mut chars = line.chars();
4359    while let Some(c) = chars.next() {
4360        if c == '\x1b' && chars.clone().next() == Some('[') {
4361            chars.next();
4362            for c in chars.by_ref() {
4363                if ('@'..='~').contains(&c) {
4364                    break;
4365                }
4366            }
4367        } else {
4368            plain.push(c);
4369        }
4370    }
4371    let t = plain.trim();
4372    if t.starts_with("[full output:") || t.starts_with("[full output could not be saved:") {
4373        Some((0, 0))
4374    } else if t.contains("panicked at") {
4375        Some((0, 6))
4376    } else if (t.starts_with("---- ") && t.ends_with(" ----"))
4377        || t.starts_with("--- STDERR:")
4378        || t.starts_with("--- STDOUT:")
4379    {
4380        Some((1, 3))
4381    } else if t.starts_with("FAIL ") || t.contains("FAIL [") {
4382        Some((1, 4))
4383    } else if t.starts_with("error:")
4384        || t.starts_with("error[")
4385        || t.starts_with("failures:")
4386        || t.contains("test result: FAILED")
4387    {
4388        Some((2, 4))
4389    } else {
4390        None
4391    }
4392}
4393
4394fn clip_line(line: &str, max: usize) -> &str {
4395    if line.len() <= max {
4396        return line;
4397    }
4398    let mut cut = max;
4399    while !line.is_char_boundary(cut) {
4400        cut -= 1;
4401    }
4402    &line[..cut]
4403}
4404
4405/// Summarise verification output to roughly `max` bytes, keeping the reason a
4406/// command failed. A plain tail is useless for a failing test: the panic
4407/// message sits hundreds of KB before the end, behind a backtrace. So:
4408///
4409/// 1. backtrace frame lines are dropped (counted in the header);
4410/// 2. if that already fits, the rest is returned whole;
4411/// 3. otherwise keep excerpts, each from a failure marker (`panicked at`,
4412///    `---- test stdout ----`, nextest `FAIL`/`STDERR`, `error:`, ...) through
4413///    a few following lines (the assertion and `left`/`right`), share the
4414///    budget evenly between selected excerpts. Select panics first, then test
4415///    stdout/stderr and nextest failure blocks, then generic diagnostics: noisy
4416///    compiler errors must not crowd out the test failure reason. Within each
4417///    priority keep earlier excerpts, then render in original order and append
4418///    the final tail (where `test result:` lives).
4419///
4420/// Adjacent excerpts merge only within the same priority and while small:
4421/// a long stdout line must not
4422/// consume the budget of a following panic anchor. Short output is returned
4423/// unchanged. The full text belongs in an artifact.
4424pub fn summarize_verify(text: &str, max: usize) -> String {
4425    if text.len() <= max {
4426        return text.to_owned();
4427    }
4428    // Tiny callers cannot fit the explanatory header. Respect their exact
4429    // byte bound, including UTF-8 boundaries, without a larger tail marker.
4430    if max < 256 {
4431        return clip_line(text, max).to_owned();
4432    }
4433    let mut kept: Vec<&str> = Vec::new();
4434    let mut dropped = 0usize;
4435    let mut prev_frame = false;
4436    for line in text.lines() {
4437        let frame = is_frame(line, prev_frame);
4438        if frame {
4439            dropped += 1;
4440        } else {
4441            kept.push(line);
4442        }
4443        prev_frame = frame;
4444    }
4445    let total: usize = kept.iter().map(|l| l.len() + 1).sum();
4446    let note = if dropped > 0 {
4447        format!(" ({dropped} backtrace frame line(s) dropped)")
4448    } else {
4449        String::new()
4450    };
4451    let overhead = 300;
4452    if total + overhead <= max {
4453        return format!("[... output reduced{note} ...]\n{}\n", kept.join("\n"));
4454    }
4455    // The tail comes first so that excerpts never repeat it.
4456    let tail_budget = (max / 4).min(4_096);
4457    let mut tail_start = kept.len();
4458    let mut used = 0usize;
4459    while tail_start > 0 && used + kept[tail_start - 1].len() < tail_budget {
4460        tail_start -= 1;
4461        used += kept[tail_start].len() + 1;
4462    }
4463    // Excerpts as merged half-open line ranges.
4464    let mut ranges: Vec<(usize, usize, u8)> = Vec::new();
4465    for (i, line) in kept[..tail_start].iter().enumerate() {
4466        if let Some((priority, after)) = trigger_context(line) {
4467            let end = (i + 1 + after).min(tail_start);
4468            match ranges.last_mut() {
4469                Some(last)
4470                    if priority == last.2
4471                        && i <= last.1
4472                        && end - last.0 <= 20
4473                        && kept[last.0..end].iter().map(|l| l.len() + 1).sum::<usize>() <= 1024 =>
4474                {
4475                    last.1 = last.1.max(end);
4476                }
4477                _ => ranges.push((i, end, priority)),
4478            }
4479        }
4480    }
4481    let budget = max.saturating_sub(used + overhead);
4482    let shown = ranges.len().min((budget / 240).max(1));
4483    ranges.sort_by_key(|&(start, _, priority)| (priority, start));
4484    let mut selected = ranges[..shown].to_vec();
4485    selected.sort_by_key(|&(start, _, _)| start);
4486    let per = budget / shown.max(1);
4487    let mut body = String::new();
4488    for &(a, b, _) in &selected {
4489        let mut block = String::new();
4490        for line in &kept[a..b] {
4491            let remaining = per.saturating_sub(block.len() + 1);
4492            if remaining == 0 {
4493                break;
4494            }
4495            let line = clip_line(line, 600.min(remaining));
4496            block.push_str(line);
4497            block.push('\n');
4498        }
4499        body.push_str(&block);
4500        body.push_str("[...]\n");
4501    }
4502    let hidden = ranges.len() - shown;
4503    let more = if hidden > 0 {
4504        format!("; {hidden} more excerpt(s) not shown")
4505    } else {
4506        String::new()
4507    };
4508    let tail_text: String = kept[tail_start..].iter().flat_map(|l| [*l, "\n"]).collect();
4509    let out = format!(
4510        "[... output reduced from {} bytes{note}; {shown} failure excerpt(s) kept{more}, then the end ...]\n{body}{tail_text}",
4511        text.len(),
4512    );
4513    if out.len() > max {
4514        return clip_line(&out, max).to_owned();
4515    }
4516    out
4517}
4518
4519/// Reserve a fresh verification artifact atomically, so concurrent writes,
4520/// retries and resumes cannot overwrite earlier evidence.
4521pub fn write_verification_artifact(run: &RunState, stem: &str, body: &str) -> Result<String> {
4522    use std::io::Write as _;
4523    let dir = run.dir().join("artifacts");
4524    std::fs::create_dir_all(&dir)?;
4525    for sequence in 1.. {
4526        let name = format!("{stem}-{sequence}.out");
4527        match std::fs::OpenOptions::new()
4528            .write(true)
4529            .create_new(true)
4530            .open(dir.join(&name))
4531        {
4532            Ok(mut file) => {
4533                file.write_all(body.as_bytes())
4534                    .with_context(|| format!("write artifacts/{name}"))?;
4535                return Ok(name);
4536            }
4537            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
4538            Err(e) => return Err(e).with_context(|| format!("create artifacts/{name}")),
4539        }
4540    }
4541    unreachable!()
4542}
4543
4544/// Path of a run artifact.
4545pub fn artifact_path(run: &RunState, name: &str) -> PathBuf {
4546    run.dir().join("artifacts").join(name)
4547}
4548
4549/// Write an artifact, creating the directory if needed.
4550pub fn write_artifact(run: &RunState, name: &str, body: &str) -> Result<PathBuf> {
4551    let path = artifact_path(run, name);
4552    if let Some(parent) = path.parent() {
4553        std::fs::create_dir_all(parent).with_context(|| format!("create {}", parent.display()))?;
4554    }
4555    std::fs::write(&path, body).with_context(|| format!("write {}", path.display()))?;
4556    Ok(path)
4557}
4558
4559/// Read an artifact back, e.g. a stored patch on resume.
4560pub fn read_artifact(run: &RunState, name: &str) -> Option<String> {
4561    std::fs::read_to_string(artifact_path(run, name)).ok()
4562}
4563
4564#[cfg(test)]
4565mod tests {
4566    #[test]
4567    fn summarize_verify_preserves_failure_context_and_bounds() {
4568        let mut text = String::from("[full output: artifacts/gate-1.out]\n");
4569        for name in ["first", "second"] {
4570            text.push_str(&format!("---- {name} stdout ----\nmy test output\n"));
4571            text.push_str(&format!("thread '{name}' panicked at tests/check.rs:42:9:\nassertion `left == right` failed\n  left: 1\n right: 2\n"));
4572            for frame in 0..4000 {
4573                text.push_str(&format!(
4574                    "  {frame}: 0x102e80de0 - backtrace frame with 日本語\n"
4575                ));
4576            }
4577        }
4578        text.push_str("---- second stderr ----\nsecond test stderr\n");
4579        text.push_str(&"unrelated output\n".repeat(1000));
4580        text.push_str(
4581            "\x1b[31mFAIL [0.01s] suite third\x1b[0m\n--- STDOUT: ---\nthird test stdout\n",
4582        );
4583        text.push_str(&"stdout noise\n".repeat(10000));
4584        text.push_str("--- STDERR: ---\nthird test stderr\n");
4585        text.push_str("thread 'third' panicked at test.rs:1:\nthird assertion\n");
4586        text.push_str(&"backtrace noise\n".repeat(10000));
4587        text.push_str("test result: FAILED. 0 passed; 3 failed\n");
4588        let summary = summarize_verify(&text, 32 * 1024);
4589        assert!(summary.len() <= 32 * 1024);
4590        for expected in [
4591            "thread 'first' panicked at",
4592            "thread 'second' panicked at",
4593            "thread 'third' panicked at",
4594            "my test output",
4595            "second test stderr",
4596            "FAIL [0.01s] suite third",
4597            "third test stdout",
4598            "third test stderr",
4599            "panicked at tests/check.rs:42:9",
4600            "left: 1",
4601            "right: 2",
4602            "third assertion",
4603            "test result: FAILED",
4604            "artifacts/gate-1.out",
4605        ] {
4606            assert!(summary.contains(expected), "missing {expected}: {summary}");
4607        }
4608        assert_eq!(summarize_verify(&summary, 32 * 1024), summary);
4609        let compact = summarize_verify(&summary, 2000);
4610        assert!(compact.len() <= 2000);
4611        assert!(compact.contains("panicked at"));
4612        assert!(compact.contains("artifacts/gate-1.out"));
4613        assert_eq!(summarize_verify("short 日本語\n", 1024), "short 日本語\n");
4614    }
4615
4616    #[test]
4617    fn summarize_verify_prioritizes_late_test_failures_over_diagnostics() {
4618        let mut text = String::new();
4619        for _ in 0..130 {
4620            text.push_str("error: diagnostic\n");
4621            text.push_str(&"ordinary build log\n".repeat(21));
4622        }
4623        text.push_str("---- late_test stdout ----\ntest stdout summary\n");
4624        text.push_str("thread 'late_test' panicked at tests/late.rs:42:9:\nassertion `left == right` failed\n  left: 1\n right: 2\n");
4625        text.push_str("--- STDERR: ---\ntest stderr summary\n");
4626        text.push_str(&"ordinary test log\n".repeat(4000));
4627        text.push_str("test result: FAILED\n");
4628
4629        let summary = summarize_verify(&text, 32 * 1024);
4630        assert!(summary.len() <= 32 * 1024);
4631        for expected in [
4632            "---- late_test stdout ----",
4633            "test stdout summary",
4634            "panicked at tests/late.rs:42:9:",
4635            "assertion `left == right` failed",
4636            "left: 1",
4637            "right: 2",
4638            "test stderr summary",
4639            "test result: FAILED",
4640        ] {
4641            assert!(summary.contains(expected), "missing {expected}");
4642        }
4643    }
4644
4645    #[test]
4646    fn summarize_verify_reports_overflow_and_handles_long_utf8_lines() {
4647        let text = (0..1000)
4648            .map(|i| {
4649                format!(
4650                    "thread '{i}' panicked at test.rs:1:\n{}\n",
4651                    "あ".repeat(2000)
4652                )
4653            })
4654            .collect::<String>();
4655        for max in (0..=256).chain([800, 2000, 32 * 1024]) {
4656            let summary = summarize_verify(&text, max);
4657            assert!(summary.len() <= max);
4658            if max >= 256 {
4659                assert!(summary.contains("more excerpt(s) not shown"));
4660            }
4661        }
4662        let compiler = format!(
4663            "error[E0063]: missing field\n{}done",
4664            "noise\n".repeat(20000)
4665        );
4666        assert!(summarize_verify(&compiler, 2000).contains("error[E0063]"));
4667    }
4668
4669    #[test]
4670    fn verification_artifacts_reserve_names_atomically() {
4671        pin_test_home();
4672        let state = pass_state();
4673        let names = std::thread::scope(|scope| {
4674            let handles: Vec<_> = (0..8)
4675                .map(|i| {
4676                    let state = &state;
4677                    scope.spawn(move || {
4678                        let body = format!("output {i}");
4679                        let name = write_verification_artifact(state, "gate", &body).unwrap();
4680                        (name, body)
4681                    })
4682                })
4683                .collect();
4684            handles
4685                .into_iter()
4686                .map(|h| h.join().unwrap())
4687                .collect::<Vec<_>>()
4688        });
4689        let unique: BTreeSet<_> = names.iter().map(|(name, _)| name).collect();
4690        assert_eq!(unique.len(), names.len());
4691        for (name, body) in names {
4692            assert_eq!(read_artifact(&state, &name).unwrap(), body);
4693        }
4694    }
4695
4696    #[test]
4697    fn quota_loss_from_report_preserves_machine_failure_details() {
4698        let report = crate::agent::Quota {
4699            reset: Some("in 1h".into()),
4700            cause: crate::agent::QuotaCause::Authentication,
4701            agent: "alpha".into(),
4702        };
4703        let loss = QuotaLoss::from_report("advisor-1".into(), "advise", Some(&report));
4704        assert_eq!(loss.seat, "advisor-1");
4705        assert_eq!(loss.node, "advise");
4706        assert_eq!(loss.reset, report.reset);
4707        assert_eq!(loss.cause, report.cause);
4708        assert_eq!(loss.agent, report.agent);
4709
4710        let absent = QuotaLoss::from_report("advisor-2".into(), "advise", None);
4711        assert_eq!(absent.reset, None);
4712        assert_eq!(absent.cause, crate::agent::QuotaCause::UsageLimit);
4713        assert!(absent.agent.is_empty());
4714    }
4715
4716    fn pass_state() -> RunState {
4717        RunState::new(
4718            PathBuf::from("/repo"),
4719            "main".to_owned(),
4720            "0123456789abcdef".to_owned(),
4721            "Do it".to_owned(),
4722            Config::default(),
4723        )
4724    }
4725
4726    #[test]
4727    fn reserving_runs_retries_full_and_short_collisions_without_touching_the_first() {
4728        let home = tempfile::tempdir().unwrap();
4729        let first_id = "20260101-000000-abcd";
4730        let ids = crate::id_reserve::sequence(&[
4731            first_id,
4732            first_id,
4733            "20260102-000000-abcd",
4734            "20260101-000000-1234",
4735        ]);
4736        let mut first = pass_state();
4737        first.reserve_with(home.path(), &ids).unwrap();
4738        let first_dir = home.path().join("runs").join(&first.id);
4739        std::fs::create_dir(first_dir.join("artifacts")).unwrap();
4740        std::fs::write(first_dir.join("artifacts/keep"), b"original artifact").unwrap();
4741        let before = std::fs::read(first_dir.join("run.json")).unwrap();
4742        let mut second = pass_state();
4743        second.instruction = "independent".into();
4744        second.reserve_with(home.path(), &ids).unwrap();
4745        assert_eq!(first.id, first_id);
4746        assert_eq!(second.id, "20260101-000000-1234");
4747        assert_ne!(first.branch_for('A'), second.branch_for('A'));
4748        assert_eq!(std::fs::read(first_dir.join("run.json")).unwrap(), before);
4749        assert_eq!(
4750            std::fs::read(first_dir.join("artifacts/keep")).unwrap(),
4751            b"original artifact"
4752        );
4753        assert_eq!(
4754            RunState::load_under(&second.id, home.path())
4755                .unwrap()
4756                .instruction,
4757            "independent"
4758        );
4759        assert!(!home.path().join("runs/20260102-000000-abcd").exists());
4760        let stuck = crate::id_reserve::IdSource::custom(|| "20260101-000000-abcd".into());
4761        assert!(
4762            pass_state()
4763                .reserve_with(home.path(), &stuck)
4764                .unwrap_err()
4765                .to_string()
4766                .contains("256 attempts")
4767        );
4768        assert_eq!(std::fs::read(first_dir.join("run.json")).unwrap(), before);
4769    }
4770
4771    #[test]
4772    fn reserving_a_run_fails_when_the_store_cannot_be_created() {
4773        let home = tempfile::tempdir().unwrap();
4774        std::fs::write(home.path().join("runs"), "not a directory").unwrap();
4775        assert!(pass_state().reserve_under(home.path()).is_err());
4776    }
4777
4778    #[test]
4779    fn passes_append_and_a_resume_never_rewrites_an_earlier_cause() {
4780        let mut s = pass_state();
4781        s.begin_pass();
4782        assert!(!s.passes[0].resumed);
4783        s.end_pass_parked(ParkCause::Upgrade {
4784            from: "0.1.0".to_owned(),
4785            to: Some("0.1.1".to_owned()),
4786        });
4787        s.begin_pass();
4788        s.end_pass_parked(ParkCause::Operator);
4789        // A second request for the same boundary does not relabel it.
4790        s.end_pass_parked(ParkCause::Question);
4791        s.begin_pass();
4792        assert_eq!(s.passes.len(), 3);
4793        assert!(s.passes[1].resumed);
4794        assert_eq!(
4795            s.passes[0].end,
4796            Some(PassEnd::Parked {
4797                cause: ParkCause::Upgrade {
4798                    from: "0.1.0".to_owned(),
4799                    to: Some("0.1.1".to_owned()),
4800                }
4801            })
4802        );
4803        assert_eq!(
4804            s.passes[1].end,
4805            Some(PassEnd::Parked {
4806                cause: ParkCause::Operator
4807            })
4808        );
4809        assert_eq!(s.passes[2].end, None);
4810    }
4811
4812    #[test]
4813    fn a_pass_left_open_is_closed_as_unrecorded_by_the_next() {
4814        let mut s = pass_state();
4815        s.begin_pass();
4816        s.begin_pass();
4817        assert_eq!(s.passes[0].end, Some(PassEnd::Unrecorded));
4818        assert!(s.passes[0].ended_at.is_some());
4819        assert_eq!(s.passes[1].end, None);
4820    }
4821
4822    #[test]
4823    fn a_state_written_before_passes_loads_with_none() {
4824        let s = pass_state();
4825        let mut v = serde_json::to_value(&s).unwrap();
4826        v.as_object_mut().unwrap().remove("passes");
4827        let back: RunState = serde_json::from_value(v).unwrap();
4828        assert!(back.passes.is_empty());
4829    }
4830    #[test]
4831    fn test_home_is_private_stable_and_unique_per_process() {
4832        // Child mode: report this process's home and stop.
4833        if std::env::var_os("MAGI_HOME_PROBE").is_some() {
4834            println!("HOME={}", super::test_home().display());
4835            return;
4836        }
4837        let a = super::test_home();
4838        assert_eq!(a, super::test_home());
4839        assert!(a.is_dir() && a.starts_with(std::env::temp_dir()));
4840        let probe = || {
4841            let out = std::process::Command::new(std::env::current_exe().unwrap())
4842                .args([
4843                    "--exact",
4844                    "run::tests::test_home_is_private_stable_and_unique_per_process",
4845                    "--nocapture",
4846                    "--test-threads=1",
4847                ])
4848                .env("MAGI_HOME_PROBE", "1")
4849                .quiet()
4850                .output()
4851                .unwrap();
4852            String::from_utf8_lossy(&out.stdout)
4853                .lines()
4854                .find_map(|l| l.split_once("HOME=").map(|(_, h)| h.to_owned()))
4855                .expect("child reported a home")
4856        };
4857        let (b, c) = (probe(), probe());
4858        assert_ne!(b, c, "two processes must never share a unit-test home");
4859        assert_ne!(b, a.display().to_string());
4860    }
4861
4862    #[test]
4863    fn no_test_pins_a_fixed_temp_path_as_the_home() {
4864        let root = std::env::var_os("CARGO_MANIFEST_DIR")
4865            .map(PathBuf::from)
4866            .unwrap_or_else(|| PathBuf::from(env!("CARGO_MANIFEST_DIR")));
4867        let needle = ["set_home(std::env::temp_dir()", ".join(\"magi-"].concat();
4868        for e in std::fs::read_dir(root.join("src")).unwrap() {
4869            let p = e.unwrap().path();
4870            if p.extension().and_then(|x| x.to_str()) != Some("rs") {
4871                continue;
4872            }
4873            let text = std::fs::read_to_string(&p).unwrap();
4874            assert!(
4875                !text.contains(&needle),
4876                "{} pins a fixed temp home; use run::pin_test_home()",
4877                p.display()
4878            );
4879        }
4880    }
4881
4882    use super::*;
4883
4884    fn state() -> RunState {
4885        RunState::new(
4886            PathBuf::from("/repo"),
4887            "main".to_owned(),
4888            "abc1234def".to_owned(),
4889            "add retries".to_owned(),
4890            Config::default(),
4891        )
4892    }
4893
4894    #[test]
4895    fn task_public_head_contains_only_the_task_identity() {
4896        let mut run = state();
4897        run.origin = Some(Origin::queue("abcd-1234"));
4898        assert_eq!(run.task_pr_branch().as_deref(), Some("magi/task-abcd-1234"));
4899        assert_ne!(run.task_pr_branch().unwrap(), run.branch_for('A'));
4900        run.origin = Some(Origin::queue("bad..task"));
4901        assert!(run.task_pr_branch().is_none());
4902        run.origin = Some(Origin::queue("abcd-1234"));
4903        run.reviewed_commits = Some(Vec::new());
4904        assert!(run.task_pr_branch().is_none());
4905        run.reviewed_commits = None;
4906        run.origin = Some(Origin::operator());
4907        assert!(run.task_pr_branch().is_none());
4908    }
4909
4910    #[test]
4911    fn task_public_head_keeps_its_saved_repository_assignment() {
4912        let mut run = state();
4913        run.origin = Some(Origin::queue("task-id"));
4914        assert_eq!(run.task_pr_branch().as_deref(), Some("magi/task-task-id"));
4915        run.task_assignment = 1;
4916        assert_eq!(
4917            run.task_pr_branch().as_deref(),
4918            Some("magi/task-task-id-assignment-1")
4919        );
4920        run.task_assignment = 2;
4921        let saved = serde_json::to_value(&run).unwrap();
4922        let restored: RunState = serde_json::from_value(saved.clone()).unwrap();
4923        assert_eq!(
4924            restored.task_pr_branch().as_deref(),
4925            Some("magi/task-task-id-assignment-2")
4926        );
4927        let mut legacy = saved;
4928        legacy["schema"] = serde_json::json!(16);
4929        legacy.as_object_mut().unwrap().remove("task_assignment");
4930        let legacy: RunState = migrate_schema(serde_json::from_value(legacy).unwrap()).unwrap();
4931        assert_eq!(
4932            legacy.task_pr_branch().as_deref(),
4933            Some("magi/task-task-id")
4934        );
4935    }
4936
4937    #[test]
4938    fn review_run_keeps_the_task_public_head_only_when_inherited() {
4939        let mut run = state();
4940        run.origin = Some(Origin::queue("abcd-1234"));
4941        run.reviewed_commits = Some(Vec::new());
4942        let mut cand = |branch: &str| {
4943            run.candidates = vec![Candidate {
4944                index: 0,
4945                label: 'A',
4946                agent: "(existing branch)".to_owned(),
4947                branch: branch.to_owned(),
4948                worktree: PathBuf::from("/w"),
4949                summary: String::new(),
4950                stat: String::new(),
4951                files: 1,
4952                commits: 1,
4953                empty: false,
4954                failed: None,
4955                verified_noop: None,
4956                duration_ms: 0,
4957                folded: false,
4958            }];
4959        };
4960        cand("magi/ab12/A");
4961        run.tally = Some(Tally {
4962            first_choice: BTreeMap::from([('A', 0)]),
4963            borda: BTreeMap::new(),
4964            winner: 'A',
4965            rankings: 0,
4966            unanimous_initial: false,
4967            deliberated: false,
4968            changed_votes: 0,
4969            unanimous_final: false,
4970            tie_break: None,
4971            judges: 0,
4972            present: 0,
4973            quorum: 0,
4974            met_quorum: true,
4975            uncontested: None,
4976        });
4977        // A legacy candidate-branch PR: nothing inherited, keep its own head.
4978        assert!(run.task_pr_branch().is_none());
4979        run.pr_head = Some("magi/task-abcd-1234".to_owned());
4980        assert_eq!(run.task_pr_branch().as_deref(), Some("magi/task-abcd-1234"));
4981        // A head that is not this task's is never followed.
4982        run.pr_head = Some("magi/task-other".to_owned());
4983        assert!(run.task_pr_branch().is_none());
4984    }
4985
4986    #[test]
4987    fn superseded_is_terminal_but_not_resumable() {
4988        assert!(RunStatus::Superseded.done());
4989        assert!(!RunStatus::Superseded.resumable());
4990        assert_eq!(RunStatus::Superseded.as_str(), "superseded");
4991        assert!(RunStatus::AlreadyInBase.done());
4992        assert!(!RunStatus::AlreadyInBase.resumable());
4993        assert_eq!(RunStatus::AlreadyInBase.as_str(), "already_in_base");
4994    }
4995
4996    #[test]
4997    fn load_under_reads_back_exactly_what_save_under_wrote_at_an_explicit_home() {
4998        // Both rooted at an explicit `home` rather than the process-global
4999        // one - a caller with its own `home` (a test fixture, a housekeeping
5000        // pass) must round-trip through exactly that directory, never
5001        // through whichever home some other test in the same binary pinned
5002        // into the global `OnceLock` first.
5003        let dir = tempfile::tempdir().unwrap();
5004        let mut original = state();
5005        original.id = "20260101-000000-load".to_owned();
5006        original.status = RunStatus::Blocked;
5007        original.save_under(dir.path()).unwrap();
5008
5009        let reloaded = RunState::load_under(&original.id, dir.path()).unwrap();
5010        assert_eq!(reloaded.id, original.id);
5011        assert_eq!(reloaded.status, RunStatus::Blocked);
5012
5013        assert!(
5014            RunState::load_under("20260101-000000-none", dir.path()).is_err(),
5015            "an id with nothing saved under this home must not silently read something else"
5016        );
5017    }
5018
5019    #[test]
5020    fn verification_history_legacy_metadata_remains_unknown() {
5021        let history: VerificationEvidence = serde_json::from_value(serde_json::json!({
5022            "gate_head": "old-head",
5023            "gate_ran": true,
5024            "gate": [],
5025            "e2e": null
5026        }))
5027        .unwrap();
5028        assert!(history.superseded_by.is_none());
5029        assert!(history.archived_at.is_none());
5030        assert!(history.fixes_spent.is_none());
5031        assert_eq!(history.gate_head.as_deref(), Some("old-head"));
5032        assert!(history.gate_ran);
5033    }
5034
5035    #[test]
5036    fn resolve_home_prefers_the_pin_then_the_env_var() {
5037        let pinned = PathBuf::from("/pinned");
5038        assert_eq!(
5039            resolve_home(Some(pinned.clone()), Some("/env".into())),
5040            pinned,
5041            "a pin wins even over MAGI_HOME"
5042        );
5043        assert_eq!(
5044            resolve_home(None, Some("/env".into())),
5045            PathBuf::from("/env")
5046        );
5047    }
5048
5049    #[test]
5050    #[should_panic(expected = "run::set_home()")]
5051    fn resolve_home_refuses_to_fall_back_to_the_operators_real_home() {
5052        // Neither override present is exactly the state a test reaches by
5053        // forgetting `set_home`/`MAGI_HOME` - the accident that put three
5054        // broken fixture runs into the operator's real history. Asserted
5055        // against the pure decision directly, not `home()` itself, because
5056        // `HOME` is a process-wide `OnceLock` another test may have already
5057        // set - this must not depend on test execution order.
5058        resolve_home(None, None);
5059    }
5060
5061    #[test]
5062    fn a_run_is_named_by_shape_so_a_state_less_directory_is_still_a_run() {
5063        // The shape `new_id` mints. A directory answering to it is a run even
5064        // with no readable `run.json`: that is how a save that ran out of
5065        // disk stays visible instead of vanishing from every listing.
5066        assert!(is_run_id(&new_id()));
5067        assert!(is_run_id("20260904-014540-88c0"));
5068        // Not runs: a stray folder, a truncated id, a non-hex tag, and an id
5069        // with an extra segment (a worktree label, say).
5070        assert!(!is_run_id("scratch"));
5071        assert!(!is_run_id("20260904-014540"));
5072        assert!(!is_run_id("20260904-014540-88c0f"));
5073        assert!(!is_run_id("2026090x-014540-88c0"));
5074        assert!(!is_run_id("20260904-014540-88c0-A"));
5075    }
5076
5077    #[test]
5078    fn ids_are_sortable_and_short_suffixed() {
5079        let s = state();
5080        let parts: Vec<&str> = s.id.split('-').collect();
5081        assert_eq!(parts.len(), 3);
5082        assert_eq!(parts[0].len(), 8);
5083        assert_eq!(parts[1].len(), 6);
5084        assert_eq!(parts[2].len(), 4);
5085        assert_eq!(s.short(), parts[2]);
5086    }
5087
5088    #[test]
5089    fn branch_names_carry_the_label_not_the_author() {
5090        let s = state();
5091        let b = s.branch_for('B');
5092        assert_eq!(b, format!("magi/{}/B", s.short()));
5093        assert!(!b.contains("claude"));
5094    }
5095
5096    /// A pinned seed reproduces the blind decisions. It must **not** reproduce
5097    /// the run's identity.
5098    ///
5099    /// `assert_eq!(a.short(), b.short())` used to stand where the last
5100    /// assertion is now, and it was pinning the defect: with the id's suffix
5101    /// derived from the seed, two runs started in the same second were the
5102    /// same run as far as the filesystem was concerned - one directory, one
5103    /// `artifacts/`, one set of candidate worktrees. `tests/common` pins a
5104    /// seed for every integration test, so on Linux, where the suite is fast,
5105    /// two tests in `graph_dropped_stream` shared a directory and one read the
5106    /// other's artifact.
5107    #[test]
5108    fn a_pinned_seed_is_reproducible_but_never_the_run_id() {
5109        let mut cfg = Config::default();
5110        cfg.blind.seed = Some(1234);
5111        let a = RunState::new(
5112            PathBuf::from("/r"),
5113            "main".to_owned(),
5114            "c".to_owned(),
5115            "t".to_owned(),
5116            cfg.clone(),
5117        );
5118        let b = RunState::new(
5119            PathBuf::from("/r"),
5120            "main".to_owned(),
5121            "c".to_owned(),
5122            "t".to_owned(),
5123            cfg,
5124        );
5125        // What the seed is for: the same shuffles, run after run.
5126        assert_eq!(a.seed, 1234);
5127        assert_eq!(a.seed, b.seed);
5128        // What it is not for. Two runs are two runs, in the same second or
5129        // not, and everything keyed on the id depends on that.
5130        assert_ne!(
5131            a.id, b.id,
5132            "two runs sharing an id share a directory, artifacts and worktrees"
5133        );
5134    }
5135
5136    #[test]
5137    fn status_terminality() {
5138        assert!(RunStatus::Merged.done());
5139        assert!(RunStatus::Blocked.done());
5140        assert!(!RunStatus::Reviewing.done());
5141    }
5142
5143    fn overrun_seat(now: Timestamp, elapsed_secs: i64, timeout_secs: u64) -> ActiveSeat {
5144        ActiveSeat {
5145            node: "implement".to_owned(),
5146            started_at: now - jiff::SignedDuration::new(elapsed_secs, 0),
5147            timeout_secs,
5148            attempt: 0,
5149            task: None,
5150            command: None,
5151            index: None,
5152            total: None,
5153        }
5154    }
5155
5156    #[test]
5157    fn active_all_overrun_requires_every_seat_past_its_own_timeout() {
5158        let mut s = state();
5159        let now = Timestamp::now();
5160        assert!(
5161            !s.active_all_overrun(now),
5162            "nothing active is not evidence of anything"
5163        );
5164
5165        s.active
5166            .insert("impl-A".to_owned(), overrun_seat(now, 21_000, 3_600));
5167        assert!(
5168            s.active_all_overrun(now),
5169            "21000s elapsed against a 3600s budget"
5170        );
5171
5172        // A seat still well within its own budget means the run is not
5173        // provably dead, however far its sibling has overrun.
5174        s.active
5175            .insert("impl-B".to_owned(), overrun_seat(now, 0, 3_600));
5176        assert!(!s.active_all_overrun(now));
5177    }
5178
5179    /// A schema-11 run that ended Blocked cannot be pinned by a daemon pid
5180    /// that is still alive; one still mid-walk keeps asking the pid.
5181    #[test]
5182    fn migrating_schema_11_marks_only_ended_runs_as_exited() {
5183        for (status, exited) in [
5184            (RunStatus::Blocked, true),
5185            (RunStatus::Failed, true),
5186            (RunStatus::Stalled, true),
5187            (RunStatus::Landing, true),
5188            (RunStatus::Reviewing, false),
5189        ] {
5190            let mut s = state();
5191            s.schema = 11;
5192            s.status = status;
5193            let m = migrate_schema(s).unwrap();
5194            assert_eq!(m.schema, SCHEMA);
5195            assert_eq!(m.driver_exited, exited, "{status:?}");
5196        }
5197    }
5198
5199    /// A driver that recorded its own exit reads dead without its pid being
5200    /// asked: a daemon's pid outlives the runs it drove.
5201    #[test]
5202    fn an_exited_driver_is_dead_even_when_its_pid_answers_alive() {
5203        let mut s = state();
5204        s.driver_pid = Some(4242);
5205        s.driver_started_at = Some("1790000000".to_owned());
5206        s.driver_exited = true;
5207        let never = |_| -> Option<bool> { panic!("the pid must not be asked") };
5208        assert_eq!(
5209            s.liveness_with(false, never, |_| panic!("nor its identity")),
5210            Liveness::Dead
5211        );
5212        assert_eq!(s.liveness_with(true, never, |_| None), Liveness::Live);
5213    }
5214
5215    /// A daemon claim wins outright, whatever `driver_pid` or either query
5216    /// says — the stronger, independently-heartbeating signal. Neither query
5217    /// closure is even called: a daemon claim short-circuits before either
5218    /// one, which panicking closures here prove.
5219    #[test]
5220    fn liveness_reads_live_from_a_daemon_claim_alone() {
5221        let mut s = state();
5222        s.driver_pid = None;
5223        assert_eq!(
5224            s.liveness_with(
5225                true,
5226                |_| panic!("a daemon claim needs no pid query"),
5227                |_| panic!("a daemon claim needs no identity query")
5228            ),
5229            Liveness::Live,
5230            "a daemon claim needs no pid to back it up"
5231        );
5232    }
5233
5234    /// The gap `driver_pid` closes: no daemon claim (every manual `magi run`
5235    /// / `magi review`), but the recorded pid answers alive *and* the
5236    /// process currently holding it still carries the same start-time
5237    /// marker this run recorded — proof it is genuinely the same process,
5238    /// not merely the same number.
5239    #[test]
5240    fn liveness_reads_live_from_a_confirmed_pid_with_a_matching_identity() {
5241        let mut s = state();
5242        s.driver_pid = Some(4242);
5243        s.driver_started_at = Some("1790000000".to_owned());
5244        assert_eq!(
5245            s.liveness_with(
5246                false,
5247                |pid| {
5248                    assert_eq!(pid, 4242);
5249                    Some(true)
5250                },
5251                |pid| {
5252                    assert_eq!(pid, 4242);
5253                    Some("1790000000".to_owned())
5254                }
5255            ),
5256            Liveness::Live
5257        );
5258    }
5259
5260    /// No daemon claim and the recorded pid confirmed gone by the OS itself
5261    /// — dead outright, and the identity query is never even reached (a
5262    /// panicking closure proves it), since there is nothing left to
5263    /// corroborate.
5264    #[test]
5265    fn liveness_reads_dead_from_a_confirmed_dead_pid() {
5266        let mut s = state();
5267        s.driver_pid = Some(4242);
5268        assert_eq!(
5269            s.liveness_with(
5270                false,
5271                |_| Some(false),
5272                |_| panic!("a confirmed-dead pid needs no identity query")
5273            ),
5274            Liveness::Dead
5275        );
5276    }
5277
5278    /// The gap this task's review round exists to close: a killed manual
5279    /// run's pid gets handed to a wholly unrelated later process. `pid_status`
5280    /// alone would read that as `Live` — the reused pid really is alive —
5281    /// but the process now holding it started at a different moment than the
5282    /// one this run recorded, so this must read `Dead`, not `Live`: a
5283    /// mismatch is exactly as good as proof the original driver is gone.
5284    #[test]
5285    fn liveness_reads_dead_when_a_live_pid_no_longer_matches_the_recorded_start_time() {
5286        let mut s = state();
5287        s.driver_pid = Some(4242);
5288        s.driver_started_at = Some("1790000000".to_owned());
5289        assert_eq!(
5290            s.liveness_with(false, |_| Some(true), |_| Some("1790005400".to_owned())),
5291            Liveness::Dead,
5292            "the pid is alive, but under a different process than the one this run recorded"
5293        );
5294    }
5295
5296    /// Missing information never collapses to `Dead`: an old run with no
5297    /// `driver_pid` at all, a `driver_pid` this build could not query, a live
5298    /// pid with no recorded start time to compare (an even older run, before
5299    /// that field existed), and a live pid whose current identity this build
5300    /// could not re-query, all read as `Unknown` — never a guess in either
5301    /// direction.
5302    #[test]
5303    fn a_locale_format_marker_on_a_live_pid_reads_unknown_never_dead() {
5304        let mut s = state();
5305        s.driver_pid = Some(4242);
5306        for old in ["日 10/ 4 17:27:03 2026", "Sun Oct  4 17:27:03 2026"] {
5307            s.driver_started_at = Some(old.to_owned());
5308            assert_eq!(
5309                s.liveness_with(
5310                    false,
5311                    |_| Some(true),
5312                    |_| panic!("an old-format marker needs no identity query")
5313                ),
5314                Liveness::Unknown,
5315                "{old}"
5316            );
5317        }
5318    }
5319
5320    #[test]
5321    fn integer_markers_compare_live_on_match_and_dead_on_difference() {
5322        let mut s = state();
5323        s.driver_pid = Some(4242);
5324        s.driver_started_at = Some("1790000000".to_owned());
5325        assert_eq!(
5326            s.liveness_with(false, |_| Some(true), |_| Some("1790000000".to_owned())),
5327            Liveness::Live
5328        );
5329        assert_eq!(
5330            s.liveness_with(false, |_| Some(true), |_| Some("1790000001".to_owned())),
5331            Liveness::Dead
5332        );
5333    }
5334
5335    #[test]
5336    fn liveness_never_guesses_out_of_missing_information() {
5337        let mut s = state();
5338        s.driver_pid = None;
5339        assert_eq!(
5340            s.liveness_with(
5341                false,
5342                |_| panic!("no pid to query"),
5343                |_| panic!("no pid to query")
5344            ),
5345            Liveness::Unknown,
5346            "no driver_pid recorded at all — an old run predating this field"
5347        );
5348
5349        s.driver_pid = Some(4242);
5350        assert_eq!(
5351            s.liveness_with(false, |_| None, |_| panic!("inconclusive already")),
5352            Liveness::Unknown,
5353            "a pid to ask, but the platform could not answer for it"
5354        );
5355
5356        s.driver_started_at = None;
5357        assert_eq!(
5358            s.liveness_with(false, |_| Some(true), |_| Some("anything".to_owned())),
5359            Liveness::Unknown,
5360            "a live pid, but no recorded marker to corroborate it against — an old run \
5361             predating `driver_started_at`"
5362        );
5363
5364        s.driver_started_at = Some("1790000000".to_owned());
5365        assert_eq!(
5366            s.liveness_with(false, |_| Some(true), |_| None),
5367            Liveness::Unknown,
5368            "a live pid and a recorded marker, but the identity re-query itself failed"
5369        );
5370    }
5371
5372    #[test]
5373    fn abandon_clears_active_and_fails_a_non_terminal_run() {
5374        let mut s = state();
5375        s.status = RunStatus::Implementing;
5376        let now = Timestamp::now();
5377        s.active
5378            .insert("impl-A".to_owned(), overrun_seat(now, 21_000, 3_600));
5379
5380        s.abandon("daemon");
5381
5382        assert!(s.active.is_empty());
5383        assert_eq!(s.status, RunStatus::Failed);
5384        assert!(
5385            s.events
5386                .last()
5387                .expect("an event was logged")
5388                .message
5389                .contains("impl-A"),
5390            "the event names the abandoned seat"
5391        );
5392    }
5393
5394    #[test]
5395    fn abandon_never_overwrites_a_status_already_terminal() {
5396        let mut s = state();
5397        s.status = RunStatus::Ready;
5398        let now = Timestamp::now();
5399        s.active
5400            .insert("impl-A".to_owned(), overrun_seat(now, 21_000, 3_600));
5401
5402        s.abandon("daemon");
5403
5404        assert!(s.active.is_empty());
5405        assert_eq!(
5406            s.status,
5407            RunStatus::Ready,
5408            "a run already done must not be relabelled Failed"
5409        );
5410    }
5411
5412    #[test]
5413    fn candidate_viability_excludes_empty_and_failed() {
5414        let mut c = Candidate {
5415            index: 0,
5416            label: 'A',
5417            agent: "a".to_owned(),
5418            branch: "b".to_owned(),
5419            worktree: PathBuf::from("/w"),
5420            summary: String::new(),
5421            stat: String::new(),
5422            files: 1,
5423            commits: 1,
5424            empty: false,
5425            failed: None,
5426            verified_noop: None,
5427            duration_ms: 0,
5428            folded: false,
5429        };
5430        assert!(c.viable());
5431        c.empty = true;
5432        assert!(!c.viable());
5433        c.empty = false;
5434        c.failed = Some("timeout".to_owned());
5435        assert!(!c.viable());
5436    }
5437
5438    #[test]
5439    fn build_failure_is_distinguished_from_a_failing_test() {
5440        let link_race = CommandOutcome {
5441            command: "cargo test".to_owned(),
5442            code: Some(1),
5443            output_tail: "LINK : fatal error LNK1104: cannot open file \
5444                          'graph_dirty_tree-71d4dc8e.exe'\n\
5445                          error: could not compile `magi-cli` (test \"graph_dirty_tree\")"
5446                .to_owned(),
5447            duration_ms: 500,
5448            resource_blocked: false,
5449        };
5450        assert!(!link_race.ok());
5451        assert!(link_race.build_failed());
5452        let mut resource_hold = link_race.clone();
5453        resource_hold.resource_blocked = true;
5454        assert!(
5455            !resource_hold.build_failed(),
5456            "disk admission must not spend a build retry"
5457        );
5458
5459        let failing_test = CommandOutcome {
5460            command: "cargo test".to_owned(),
5461            code: Some(101),
5462            output_tail: "thread 'it_works' panicked at 'assertion failed'".to_owned(),
5463            duration_ms: 500,
5464            resource_blocked: false,
5465        };
5466        assert!(!failing_test.ok());
5467        assert!(
5468            !failing_test.build_failed(),
5469            "a real test failure must not be classed as a build failure"
5470        );
5471
5472        let passing = CommandOutcome {
5473            command: "cargo test".to_owned(),
5474            code: Some(0),
5475            output_tail: String::new(),
5476            duration_ms: 500,
5477            resource_blocked: false,
5478        };
5479        assert!(passing.ok());
5480        assert!(!passing.build_failed());
5481    }
5482
5483    #[test]
5484    fn tail_keeps_the_end_on_a_line_boundary() {
5485        let text = (0..100).map(|i| format!("line {i}\n")).collect::<String>();
5486        let t = tail(&text, 40);
5487        assert!(t.starts_with("[..."));
5488        assert!(t.ends_with("line 99\n"));
5489        assert!(t.len() < 120);
5490        assert_eq!(tail("short", 40), "short");
5491    }
5492
5493    #[test]
5494    fn summarize_verify_keeps_panics_behind_a_huge_backtrace() {
5495        let mut text =
5496            String::from("running 1 test\ntest a ... FAILED\n\nfailures:\n\n---- a stdout ----\n");
5497        text.push_str("thread 'a' panicked at tests/a.rs:9:5:\nassertion `left == right` failed\n  left: 1\n right: 2\nstack backtrace:\n");
5498        for i in 0..6000 {
5499            text.push_str(&format!("  {i}: 0x102e80de0 - <web_render::x::{{closure#0}}>\n             at /rustc/abc/library/core/src/ops/function.rs:250:5\n"));
5500        }
5501        text.push_str("\nfailures:\n    a\n\ntest result: FAILED. 0 passed; 1 failed\n");
5502        assert!(text.len() > 400_000);
5503        let s = summarize_verify(&text, VERIFY_SUMMARY);
5504        assert!(s.contains("panicked at tests/a.rs:9:5"));
5505        assert!(s.contains("left: 1") && s.contains("right: 2"));
5506        assert!(s.contains("---- a stdout ----"));
5507        assert!(s.contains("test result: FAILED"));
5508        assert!(!s.contains("0x102e80de0"));
5509        assert!(s.len() <= VERIFY_SUMMARY);
5510        // Re-summarising to a smaller budget still keeps the panic.
5511        assert!(summarize_verify(&s, 1_500).contains("panicked at tests/a.rs:9:5"));
5512        assert_eq!(summarize_verify("short", 100), "short");
5513    }
5514
5515    #[test]
5516    fn summarize_verify_keeps_panics_when_the_noise_is_not_frames() {
5517        let mut text = String::from("---- t stdout ----\nthread 't' panicked at x.rs:1:1:\nboom\n");
5518        text.push_str(&"noise line\n".repeat(50_000));
5519        text.push_str("test result: FAILED\n");
5520        let s = summarize_verify(&text, 8_000);
5521        assert!(s.contains("panicked at x.rs:1:1"));
5522        assert!(s.contains("boom"));
5523        assert!(s.contains("test result: FAILED"));
5524        assert!(s.len() <= 8_000);
5525    }
5526
5527    #[test]
5528    fn tail_survives_multibyte_cuts() {
5529        let text = "あ".repeat(50);
5530        let t = tail(&text, 10);
5531        assert!(t.contains("earlier bytes omitted"));
5532        assert!(t.ends_with('あ'));
5533    }
5534
5535    fn finding(id: &str, severity: crate::verdict::Severity) -> crate::verdict::Finding {
5536        crate::verdict::Finding {
5537            id: id.to_owned(),
5538            severity,
5539            file: None,
5540            line: None,
5541            title: "x".to_owned(),
5542            detail: String::new(),
5543        }
5544    }
5545
5546    fn round(clean: bool, findings: Vec<crate::verdict::Finding>) -> ReviewRound {
5547        ReviewRound {
5548            round: 1,
5549            head: "h".to_owned(),
5550            verified_head: None,
5551            verified_at: None,
5552            reviews: vec![ReviewRecord {
5553                attempts: 0,
5554                reviewer: 1,
5555                agent: "a".to_owned(),
5556                summary: String::new(),
5557                findings,
5558                vote: None,
5559                failed: None,
5560                duration_ms: 0,
5561            }],
5562            e2e: Vec::new(),
5563            verify_retried: false,
5564            e2e_deferred: false,
5565            e2e_defer_reason: None,
5566            fix: None,
5567            blocking: 0,
5568            answered: 1,
5569            expected: 1,
5570            clean,
5571            progressed: false,
5572            vote_split: false,
5573            reconsideration: Vec::new(),
5574            verdict: None,
5575        }
5576    }
5577
5578    fn voted(
5579        findings: Vec<crate::verdict::Finding>,
5580        votes: &[ReviewVote],
5581        revotes: &[Option<ReviewVote>],
5582    ) -> ReviewRound {
5583        let mut r = round(false, findings);
5584        r.reviews = votes
5585            .iter()
5586            .enumerate()
5587            .map(|(i, v)| {
5588                let mut rec = r.reviews[0].clone();
5589                rec.reviewer = i + 1;
5590                rec.vote = Some(*v);
5591                if i > 0 {
5592                    rec.findings = Vec::new();
5593                }
5594                rec
5595            })
5596            .collect();
5597        r.reconsideration = revotes
5598            .iter()
5599            .enumerate()
5600            .map(|(i, v)| ReviewRevoteRecord {
5601                reviewer: i + 1,
5602                agent: "a".to_owned(),
5603                vote: *v,
5604                reason: String::new(),
5605                failed: None,
5606            })
5607            .collect();
5608        r
5609    }
5610
5611    #[test]
5612    fn a_hand_off_is_contested_only_by_a_blocking_finding_and_a_reject_vote() {
5613        use crate::verdict::Severity::{Major, Minor};
5614        use ReviewVote::{Approve, Reject};
5615        let major = || vec![finding("R1-1-1", Major)];
5616        let minor = || vec![finding("R1-1-1", Minor)];
5617
5618        let c = voted(major(), &[Reject, Approve], &[])
5619            .contested_handoff()
5620            .expect("major + reject");
5621        assert_eq!(c.findings.len(), 1);
5622        assert_eq!(c.rejecters, vec![(1, "a".to_owned())]);
5623
5624        assert!(
5625            voted(minor(), &[Reject, Approve], &[])
5626                .contested_handoff()
5627                .is_none()
5628        );
5629        assert!(
5630            voted(major(), &[Approve, Approve], &[])
5631                .contested_handoff()
5632                .is_none()
5633        );
5634        assert!(
5635            voted(Vec::new(), &[Reject], &[])
5636                .contested_handoff()
5637                .is_none()
5638        );
5639    }
5640
5641    #[test]
5642    fn a_reject_withdrawn_in_the_revote_does_not_contest_and_an_unanswered_one_stands() {
5643        use crate::verdict::Severity::Major;
5644        use ReviewVote::{Approve, Reject};
5645        let major = || vec![finding("R1-1-1", Major)];
5646
5647        let withdrawn = voted(major(), &[Reject, Approve], &[Some(Approve), Some(Approve)]);
5648        assert!(withdrawn.contested_handoff().is_none());
5649
5650        let unanswered = voted(major(), &[Reject, Approve], &[None, Some(Approve)]);
5651        assert!(
5652            unanswered.contested_handoff().is_some(),
5653            "no revote falls back to the initial reject"
5654        );
5655
5656        let raised = voted(major(), &[Approve, Approve], &[Some(Reject), Some(Approve)]);
5657        assert!(raised.contested_handoff().is_some());
5658    }
5659
5660    #[test]
5661    fn e2e_status_tells_deferred_apart_from_not_configured() {
5662        let mut r = round(false, Vec::new());
5663        assert_eq!(r.e2e_status(), E2eStatus::NotConfigured);
5664
5665        r.e2e_deferred = true;
5666        assert_eq!(
5667            r.e2e_status(),
5668            E2eStatus::Deferred,
5669            "an empty e2e must not read as unconfigured once it was deferred on purpose"
5670        );
5671
5672        r.e2e = vec![CommandOutcome {
5673            command: "test".to_owned(),
5674            code: Some(0),
5675            output_tail: String::new(),
5676            duration_ms: 0,
5677            resource_blocked: false,
5678        }];
5679        assert_eq!(
5680            r.e2e_status(),
5681            E2eStatus::Passed,
5682            "a round with real outcomes is never read as deferred, even if the flag is still set"
5683        );
5684    }
5685
5686    #[test]
5687    fn e2e_status_reports_a_real_failure_as_failed_not_deferred() {
5688        let mut r = round(false, Vec::new());
5689        r.e2e = vec![CommandOutcome {
5690            command: "test".to_owned(),
5691            code: Some(1),
5692            output_tail: "boom".to_owned(),
5693            duration_ms: 0,
5694            resource_blocked: false,
5695        }];
5696        assert_eq!(r.e2e_status(), E2eStatus::Failed);
5697    }
5698
5699    #[test]
5700    fn e2e_status_never_reads_a_resource_block_as_a_failure() {
5701        // The exact shape of contention on the shared build cache: `e2e`
5702        // holds one outcome, and it is `resource_blocked`, never a command
5703        // that actually ran and produced a red exit code.
5704        let mut r = round(false, Vec::new());
5705        r.e2e = vec![CommandOutcome {
5706            command: "(waiting for the shared build cache)".to_owned(),
5707            code: None,
5708            output_tail: "contended".to_owned(),
5709            duration_ms: 0,
5710            resource_blocked: true,
5711        }];
5712        assert_eq!(
5713            r.e2e_status(),
5714            E2eStatus::ResourceBlocked,
5715            "magi's own inability to get a command to run must not read as a verdict on the \
5716             patch"
5717        );
5718    }
5719
5720    #[test]
5721    fn verification_summary_is_silent_when_there_is_nothing_worth_saying() {
5722        let mut r = round(true, Vec::new());
5723        assert!(
5724            r.verification_summary("h").is_none(),
5725            "no verify.e2e configured: nothing to surface"
5726        );
5727        r.e2e = vec![CommandOutcome {
5728            command: "test".to_owned(),
5729            code: Some(0),
5730            output_tail: String::new(),
5731            duration_ms: 0,
5732            resource_blocked: false,
5733        }];
5734        assert!(
5735            r.verification_summary("h").is_none(),
5736            "a green result needs no skepticism attached to it"
5737        );
5738    }
5739
5740    #[test]
5741    fn verification_summary_tells_the_current_head_apart_from_an_earlier_one() {
5742        let mut r = round(false, Vec::new());
5743        r.head = "h1".to_owned();
5744        r.e2e = vec![CommandOutcome {
5745            command: "test".to_owned(),
5746            code: Some(1),
5747            output_tail: "boom".to_owned(),
5748            duration_ms: 0,
5749            resource_blocked: false,
5750        }];
5751        r.verified_head = Some("h1".to_owned());
5752        r.verified_at = Some(Timestamp::now());
5753
5754        let fresh = r.verification_summary("h1").expect("a failure is surfaced");
5755        assert!(
5756            fresh.label.contains("this is the head being looked at now"),
5757            "{}",
5758            fresh.label
5759        );
5760        assert_eq!(fresh.tail.as_deref(), Some("$ test\nboom\n"));
5761
5762        let stale = r.verification_summary("h2").expect("still surfaced");
5763        assert!(
5764            stale.label.contains("an earlier head, since superseded"),
5765            "a result about a different commit than the one being looked at now must say so, \
5766             not read as current: {}",
5767            stale.label
5768        );
5769    }
5770
5771    #[test]
5772    fn verification_summary_marks_a_resource_block_and_a_deferral_distinctly_from_a_failure() {
5773        let mut r = round(false, Vec::new());
5774        r.e2e = vec![CommandOutcome {
5775            command: "(waiting for the shared build cache)".to_owned(),
5776            code: None,
5777            output_tail: "contended".to_owned(),
5778            duration_ms: 0,
5779            resource_blocked: true,
5780        }];
5781        let blocked = r
5782            .verification_summary("h")
5783            .expect("a resource block is still surfaced, never silent");
5784        assert!(blocked.label.contains("could not run"));
5785        // No command actually ran, but which operation was attempted is
5786        // still a fact worth showing — never silent past the label either.
5787        let tail = blocked
5788            .tail
5789            .expect("the attempted operation is still named");
5790        assert!(tail.contains("(waiting for the shared build cache)"));
5791        assert!(tail.contains("contended"));
5792
5793        let mut d = round(false, Vec::new());
5794        d.e2e_deferred = true;
5795        d.e2e_defer_reason = Some("2 blocking finding(s) already required a fix".to_owned());
5796        let deferred = d.verification_summary("h").expect("deferred is surfaced");
5797        assert!(deferred.label.contains("deferred to the fixer"));
5798        assert!(deferred.label.contains("2 blocking finding(s)"));
5799        assert!(deferred.tail.is_none());
5800    }
5801
5802    #[test]
5803    fn verification_summary_says_unknown_rather_than_guessing_a_time_or_a_commit() {
5804        let mut r = round(false, Vec::new());
5805        r.e2e = vec![CommandOutcome {
5806            command: "test".to_owned(),
5807            code: Some(1),
5808            output_tail: "boom".to_owned(),
5809            duration_ms: 0,
5810            resource_blocked: false,
5811        }];
5812        // verified_head/verified_at left at their default `None` — exactly
5813        // the shape a schema-7 round with no reconstructable timestamp has.
5814        let summary = r.verification_summary("h").expect("a failure is surfaced");
5815        assert!(summary.label.contains("commit unknown"));
5816        assert!(summary.label.contains("checked at: unknown"));
5817    }
5818
5819    #[test]
5820    fn gate_status_tells_not_run_apart_from_not_configured() {
5821        let mut s = state();
5822        assert_eq!(s.gate_status(), GateStatus::NotRun);
5823
5824        s.gate_ran = true;
5825        assert_eq!(
5826            s.gate_status(),
5827            GateStatus::NotConfigured,
5828            "an empty gate is not configured even when gate_ran records an attempt"
5829        );
5830
5831        s.gate = vec![CommandOutcome {
5832            command: "cargo make check".to_owned(),
5833            code: Some(0),
5834            output_tail: String::new(),
5835            duration_ms: 0,
5836            resource_blocked: false,
5837        }];
5838        assert_eq!(s.gate_status(), GateStatus::Passed);
5839
5840        s.gate[0].code = Some(1);
5841        assert_eq!(s.gate_status(), GateStatus::Failed);
5842
5843        s.gate_ran = false;
5844        assert_eq!(
5845            s.gate_status(),
5846            GateStatus::NotRun,
5847            "gate_ran false must win even over a non-empty gate left from a stale record"
5848        );
5849    }
5850
5851    #[test]
5852    fn open_findings_is_empty_when_the_last_round_was_clean() {
5853        let mut s = state();
5854        s.reviews = vec![round(
5855            true,
5856            vec![finding("R1-1-1", crate::verdict::Severity::Minor)],
5857        )];
5858        assert!(s.open_findings().is_empty());
5859    }
5860
5861    #[test]
5862    fn open_findings_reads_the_last_non_clean_round() {
5863        let mut s = state();
5864        s.reviews = vec![round(
5865            false,
5866            vec![finding("R1-1-1", crate::verdict::Severity::Major)],
5867        )];
5868        let open = s.open_findings();
5869        assert_eq!(open.len(), 1);
5870        assert_eq!(open[0].id, "R1-1-1");
5871    }
5872
5873    #[test]
5874    fn handed_off_with_open_findings_needs_a_mergeable_status_and_an_open_round() {
5875        let mut s = state();
5876        s.reviews = vec![round(
5877            false,
5878            vec![finding("R1-1-1", crate::verdict::Severity::Major)],
5879        )];
5880
5881        s.status = RunStatus::Blocked;
5882        assert!(
5883            !s.handed_off_with_open_findings(),
5884            "a blocked run is not a hand-off"
5885        );
5886
5887        s.status = RunStatus::Ready;
5888        assert!(s.handed_off_with_open_findings());
5889
5890        s.reviews = vec![round(true, Vec::new())];
5891        assert!(
5892            !s.handed_off_with_open_findings(),
5893            "a clean last round has nothing to hand off"
5894        );
5895    }
5896
5897    #[test]
5898    fn unmerged_by_design_is_only_ready_reached_via_merge_mode_none() {
5899        let mut s = state();
5900
5901        s.status = RunStatus::Ready;
5902        assert!(
5903            !s.unmerged_by_design(),
5904            "no merge outcome recorded at all must not be flagged"
5905        );
5906
5907        s.merge = Some(MergeOutcome {
5908            mode: MergeMode::None,
5909            ok: true,
5910            detail: "git merge --no-ff magi/x/A".to_owned(),
5911            empty: false,
5912        });
5913        assert!(
5914            s.unmerged_by_design(),
5915            "Ready reached through mode none is the case this exists to flag"
5916        );
5917
5918        // A PR closed without merging also leaves `status` at `Ready`, but
5919        // through `mode = "pr"` — a run that may still have been landable by
5920        // a person watching the PR, unlike the honest mode-none no-op.
5921        s.merge = Some(MergeOutcome {
5922            mode: MergeMode::Pr,
5923            ok: false,
5924            detail: "https://example.com/pr/1 was closed without merging".to_owned(),
5925            empty: false,
5926        });
5927        assert!(
5928            !s.unmerged_by_design(),
5929            "a closed pull request is a different Ready and must not be relabelled"
5930        );
5931
5932        // Same signal must not fire before the run actually got there.
5933        s.status = RunStatus::Gating;
5934        s.merge = Some(MergeOutcome {
5935            mode: MergeMode::None,
5936            ok: true,
5937            detail: "git merge --no-ff magi/x/A".to_owned(),
5938            empty: false,
5939        });
5940        assert!(
5941            !s.unmerged_by_design(),
5942            "status must actually be Ready, not merely have a stale mode-none merge record"
5943        );
5944    }
5945
5946    #[test]
5947    fn state_round_trips_through_json() {
5948        let s = state();
5949        let body = serde_json::to_string(&s).unwrap();
5950        let back: RunState = serde_json::from_str(&body).unwrap();
5951        assert_eq!(back.id, s.id);
5952        assert_eq!(back.instruction, "add retries");
5953        assert_eq!(back.status, RunStatus::Prep);
5954    }
5955
5956    #[test]
5957    fn a_round_recorded_before_e2e_deferral_existed_still_loads() {
5958        // Exactly the shape a pre-existing `run.json` has for a round: no
5959        // `e2e_deferred`, no `e2e_defer_reason`. Every round used to run e2e
5960        // unconditionally, so the honest reading of an old record's silence
5961        // on this is "it was not deferred" — `false`/`None`, not a load
5962        // failure and not a schema bump (see the `SCHEMA` doc comment: a
5963        // purely additive field whose absence has one unambiguous meaning
5964        // does not need one).
5965        let body = r#"{
5966            "round": 1,
5967            "head": "deadbeef",
5968            "reviews": [],
5969            "e2e": [],
5970            "verify_retried": false,
5971            "fix": null,
5972            "blocking": 0,
5973            "answered": 1,
5974            "expected": 1,
5975            "clean": true
5976        }"#;
5977        let r: ReviewRound = serde_json::from_str(body).expect("an old-shaped round must load");
5978        assert!(!r.e2e_deferred);
5979        assert!(r.e2e_defer_reason.is_none());
5980        assert_eq!(r.e2e_status(), E2eStatus::NotConfigured);
5981    }
5982
5983    #[test]
5984    fn schema_five_state_migrates_old_empty_e2e_and_legacy_verify_budget() {
5985        let mut value = serde_json::to_value(state()).expect("serialize state");
5986        let object = value.as_object_mut().expect("state object");
5987        object.insert("schema".to_owned(), serde_json::json!(5));
5988        let graph = object["config"]["graph"]
5989            .as_object_mut()
5990            .expect("graph object");
5991        graph.insert("timeout_review".to_owned(), serde_json::json!(3600));
5992        graph.remove("timeout_verify");
5993        let review = object["reviews"].as_array_mut().expect("reviews");
5994        review.push(serde_json::json!({
5995            "round": 1, "head": "old", "reviews": [], "e2e": [],
5996            "verify_retried": false, "blocking": 0, "answered": 1,
5997            "expected": 1, "clean": true
5998        }));
5999        let old: RunState = serde_json::from_value(value).expect("schema-5 shape parses");
6000        let migrated = migrate_schema(old).expect("schema 5 migrates");
6001        assert_eq!(migrated.schema, SCHEMA);
6002        assert_eq!(migrated.config.graph.verify_timeout(), 3600);
6003        assert_eq!(migrated.reviews[0].e2e_status(), E2eStatus::NotConfigured);
6004    }
6005
6006    #[test]
6007    fn schema_six_state_with_a_recorded_gate_migrates_to_gate_ran_true() {
6008        let mut value = serde_json::to_value(state()).expect("serialize state");
6009        let object = value.as_object_mut().expect("state object");
6010        object.insert("schema".to_owned(), serde_json::json!(6));
6011        object.insert(
6012            "gate".to_owned(),
6013            serde_json::json!([{
6014                "command": "cargo make check",
6015                "code": 0,
6016                "output_tail": "",
6017                "duration_ms": 0,
6018                "resource_blocked": false
6019            }]),
6020        );
6021        let old: RunState = serde_json::from_value(value).expect("schema-6 shape parses");
6022        let migrated = migrate_schema(old).expect("schema 6 migrates");
6023        assert_eq!(migrated.schema, SCHEMA);
6024        assert!(
6025            migrated.gate_ran,
6026            "a non-empty recorded gate is a real attempt, not an unrun one"
6027        );
6028        assert_eq!(migrated.gate_status(), GateStatus::Passed);
6029    }
6030
6031    #[test]
6032    fn schema_six_state_with_an_empty_gate_migrates_to_gate_ran_false_and_is_retried() {
6033        // The exact shape of the stuck `shoka` run this schema bump fixes:
6034        // `verify.gate` empty, `gate` empty, schema 6. It must come back as
6035        // "not yet run" so the next `gate()` call re-attempts it — and for a
6036        // repo with no gate commands configured, that resolves instantly to
6037        // `NotConfigured` instead of staying stuck forever.
6038        let mut value = serde_json::to_value(state()).expect("serialize state");
6039        let object = value.as_object_mut().expect("state object");
6040        object.insert("schema".to_owned(), serde_json::json!(6));
6041        object.insert("gate".to_owned(), serde_json::json!([]));
6042        let old: RunState = serde_json::from_value(value).expect("schema-6 shape parses");
6043        let migrated = migrate_schema(old).expect("schema 6 migrates");
6044        assert_eq!(migrated.schema, SCHEMA);
6045        assert!(
6046            !migrated.gate_ran,
6047            "an empty gate on schema 6 is ambiguous and must be treated as unrun"
6048        );
6049        assert_eq!(migrated.gate_status(), GateStatus::NotRun);
6050    }
6051
6052    #[test]
6053    fn schema_seven_state_reconstructs_verified_head_for_a_round_that_actually_ran_e2e() {
6054        // Schema 7's main review loop always checked `e2e` against the
6055        // round's own `head` — it just never wrote that into `verified_head`
6056        // unless a catch-up run had checked a *different* commit. Migrating
6057        // to schema 8 restores that always-true fact instead of leaving a
6058        // reader to assume it.
6059        let mut value = serde_json::to_value(state()).expect("serialize state");
6060        let object = value.as_object_mut().expect("state object");
6061        object.insert("schema".to_owned(), serde_json::json!(7));
6062        let reviews = object["reviews"].as_array_mut().expect("reviews");
6063        reviews.push(serde_json::json!({
6064            "round": 1, "head": "deadbeef", "reviews": [],
6065            "e2e": [{
6066                "command": "cargo test", "code": 0, "output_tail": "",
6067                "duration_ms": 0, "resource_blocked": false
6068            }],
6069            "verify_retried": false, "blocking": 0, "answered": 1,
6070            "expected": 1, "clean": true
6071        }));
6072        let old: RunState = serde_json::from_value(value).expect("schema-7 shape parses");
6073        let migrated = migrate_schema(old).expect("schema 7 migrates");
6074        assert_eq!(migrated.schema, SCHEMA);
6075        assert_eq!(
6076            migrated.reviews[0].verified_head.as_deref(),
6077            Some("deadbeef"),
6078            "a schema-7 round's main-loop e2e was always against its own head, even though the \
6079             field never said so"
6080        );
6081        assert!(
6082            migrated.reviews[0].verified_at.is_none(),
6083            "no historical timestamp exists to reconstruct; unknown stays unknown, not a \
6084             guessed 'now'"
6085        );
6086    }
6087
6088    #[test]
6089    fn schema_seven_state_leaves_a_deferred_round_with_no_verified_head() {
6090        let mut value = serde_json::to_value(state()).expect("serialize state");
6091        let object = value.as_object_mut().expect("state object");
6092        object.insert("schema".to_owned(), serde_json::json!(7));
6093        let reviews = object["reviews"].as_array_mut().expect("reviews");
6094        reviews.push(serde_json::json!({
6095            "round": 1, "head": "deadbeef", "reviews": [],
6096            "e2e": [], "e2e_deferred": true,
6097            "verify_retried": false, "blocking": 1, "answered": 1,
6098            "expected": 1, "clean": false
6099        }));
6100        let old: RunState = serde_json::from_value(value).expect("schema-7 shape parses");
6101        let migrated = migrate_schema(old).expect("schema 7 migrates");
6102        assert!(
6103            migrated.reviews[0].verified_head.is_none(),
6104            "a deferred round never ran e2e; there is nothing to reconstruct"
6105        );
6106    }
6107
6108    #[test]
6109    fn origin_round_trips_through_the_run_state() {
6110        let mut s = state();
6111        s.origin = Some(Origin::from_agent_env(
6112            Some(("4a7b".to_owned(), "chat".to_owned())),
6113            Some("20260930-092817-4f6f".to_owned()),
6114        ));
6115        let back: RunState =
6116            serde_json::from_str(&serde_json::to_string(&s).unwrap()).expect("parse back");
6117        assert_eq!(back.origin, s.origin);
6118        assert_eq!(
6119            back.origin.as_ref().unwrap().by,
6120            StartedBy::Chat {
6121                talk: "4a7b".to_owned()
6122            }
6123        );
6124        assert_eq!(
6125            origin_label(back.origin.as_ref()),
6126            "chat 4a7b, for task 4f6f"
6127        );
6128    }
6129
6130    #[test]
6131    fn a_schema_twelve_record_without_an_origin_loads_and_reads_as_unknown() {
6132        let mut value = serde_json::to_value(state()).expect("serialize state");
6133        let object = value.as_object_mut().expect("state object");
6134        object.insert("schema".to_owned(), serde_json::json!(12));
6135        object.remove("origin");
6136        let old: RunState = serde_json::from_value(value).expect("schema-12 shape parses");
6137        assert!(old.origin.is_none());
6138        let migrated = migrate_schema(old).expect("schema 12 migrates");
6139        assert_eq!(migrated.schema, SCHEMA);
6140        assert!(
6141            migrated.origin.is_none(),
6142            "an origin nobody recorded is not invented"
6143        );
6144        assert_eq!(
6145            origin_label(migrated.origin.as_ref()),
6146            "origin unknown (started before origins were recorded)"
6147        );
6148    }
6149
6150    #[test]
6151    fn schema_supported_versions_all_reach_current() {
6152        for schema in 5..=SCHEMA {
6153            let mut value = serde_json::to_value(state()).expect("serialize state");
6154            value["schema"] = serde_json::json!(schema);
6155            if schema < 14 {
6156                value.as_object_mut().unwrap().remove("task_instruction");
6157            }
6158            if schema < 13 {
6159                value.as_object_mut().unwrap().remove("origin");
6160            }
6161            let old: RunState = serde_json::from_value(value).expect("legacy shape parses");
6162            let migrated = migrate_schema(old)
6163                .unwrap_or_else(|error| panic!("schema {schema} must migrate: {error}"));
6164            assert_eq!(migrated.schema, SCHEMA, "schema {schema}");
6165            assert!(migrated.task_instruction.is_none(), "schema {schema}");
6166            assert!(migrated.origin.is_none(), "schema {schema}");
6167        }
6168    }
6169
6170    #[test]
6171    fn schema_unsupported_versions_remain_rejected() {
6172        for schema in [1, 2, 3, 4, SCHEMA + 1] {
6173            let mut old = state();
6174            old.schema = schema;
6175            assert!(migrate_schema(old).is_err(), "schema {schema}");
6176        }
6177    }
6178
6179    #[test]
6180    fn origin_attributes_agents_by_node_and_never_by_guesswork() {
6181        let chat = Origin::from_agent_env(Some(("4a7b".to_owned(), "chat".to_owned())), None);
6182        assert_eq!(
6183            chat.by,
6184            StartedBy::Chat {
6185                talk: "4a7b".into()
6186            }
6187        );
6188        let seat = Origin::from_agent_env(
6189            Some(("20260930-092817-ec34".to_owned(), "implement".to_owned())),
6190            None,
6191        );
6192        assert_eq!(seat.label(), "implement@ec34");
6193        assert_eq!(Origin::from_agent_env(None, None), Origin::operator());
6194        assert_eq!(Origin::operator().label(), "operator");
6195        assert_eq!(Origin::queue("20260930-000000-4f6f").label(), "task 4f6f");
6196        assert_eq!(
6197            Origin::operator()
6198                .serving(Some("20260930-000000-4f6f".to_owned()))
6199                .label(),
6200            "operator, for task 4f6f"
6201        );
6202    }
6203
6204    #[test]
6205    fn schema_six_serialization_is_rejected_by_a_schema_five_reader() {
6206        let body = serde_json::to_value(state()).expect("serialize state");
6207        assert_eq!(body["schema"], serde_json::json!(SCHEMA));
6208        assert_ne!(body["schema"], serde_json::json!(5));
6209    }
6210
6211    #[test]
6212    fn seat_started_and_finished_track_who_has_not_answered_yet() {
6213        let mut s = state();
6214        s.seat_started("judge", "judge-1", std::time::Duration::from_secs(60), 0);
6215        s.seat_started("judge", "judge-2", std::time::Duration::from_secs(60), 0);
6216        assert_eq!(s.active.len(), 2, "both seats are still out");
6217
6218        s.seat_finished("judge-1");
6219        assert_eq!(
6220            s.active.keys().collect::<Vec<_>>(),
6221            vec!["judge-2"],
6222            "only the seat that answered drops out; judge-2 is still waited on"
6223        );
6224    }
6225
6226    /// `seats_active` / `tasks_active` are the accessors report/web read
6227    /// instead of `active` directly, so neither ever counts the other kind of
6228    /// entry as a seat — a `verify.e2e` task must never inflate a quorum or
6229    /// seat count, and a seat must never show up in a task listing.
6230    #[test]
6231    fn seats_active_and_tasks_active_never_cross_over() {
6232        let mut s = state();
6233        s.seat_started("judge", "judge-1", std::time::Duration::from_secs(60), 0);
6234        s.task_command(
6235            "e2e",
6236            "verify",
6237            0,
6238            "cargo test",
6239            1,
6240            2,
6241            std::time::Duration::from_secs(600),
6242        );
6243
6244        assert_eq!(
6245            s.seats_active()
6246                .map(|(k, _)| k.as_str())
6247                .collect::<Vec<_>>(),
6248            vec!["judge-1"]
6249        );
6250        assert_eq!(
6251            s.tasks_active()
6252                .map(|(k, _)| k.as_str())
6253                .collect::<Vec<_>>(),
6254            vec!["e2e"]
6255        );
6256
6257        // A command boundary updates the same entry in place — still one
6258        // task, never a second one accumulating alongside it.
6259        s.task_command(
6260            "e2e",
6261            "verify",
6262            0,
6263            "cargo clippy",
6264            2,
6265            2,
6266            std::time::Duration::from_secs(600),
6267        );
6268        assert_eq!(s.tasks_active().count(), 1);
6269        assert_eq!(s.active["e2e"].command.as_deref(), Some("cargo clippy"));
6270
6271        s.task_finished("e2e");
6272        assert!(s.tasks_active().next().is_none());
6273        assert_eq!(
6274            s.seats_active()
6275                .map(|(k, _)| k.as_str())
6276                .collect::<Vec<_>>(),
6277            vec!["judge-1"],
6278            "clearing the task must not touch the seat entry"
6279        );
6280    }
6281
6282    #[test]
6283    fn a_retry_is_recorded_as_a_later_attempt_on_the_same_seat() {
6284        let mut s = state();
6285        s.seat_started("review", "review-2", std::time::Duration::from_secs(30), 0);
6286        s.seat_finished("review-2");
6287        // A nudge re-asks the same seat; attempt says this is not the first
6288        // time, which is the only trace a nudge otherwise leaves behind.
6289        s.seat_started("review", "review-2", std::time::Duration::from_secs(30), 1);
6290        assert_eq!(s.active["review-2"].attempt, 1);
6291    }
6292
6293    #[test]
6294    fn active_seat_reports_elapsed_and_remaining_time() {
6295        let now = Timestamp::now();
6296        let started = now - jiff::SignedDuration::from_secs(30);
6297        let seat = ActiveSeat {
6298            node: "judge".to_owned(),
6299            started_at: started,
6300            timeout_secs: 100,
6301            attempt: 0,
6302            task: None,
6303            command: None,
6304            index: None,
6305            total: None,
6306        };
6307        assert_eq!(seat.elapsed_secs(now), 30);
6308        assert_eq!(seat.remaining_secs(now), 70);
6309    }
6310
6311    #[test]
6312    fn remaining_time_never_goes_negative_past_the_timeout() {
6313        // `agy`'s own print-timeout occasionally overruns by a hair before the
6314        // kill lands; a naive subtraction would print a negative "time left".
6315        let now = Timestamp::now();
6316        let started = now - jiff::SignedDuration::from_secs(200);
6317        let seat = ActiveSeat {
6318            node: "implement".to_owned(),
6319            started_at: started,
6320            timeout_secs: 100,
6321            attempt: 1,
6322            task: None,
6323            command: None,
6324            index: None,
6325            total: None,
6326        };
6327        assert_eq!(seat.remaining_secs(now), 0);
6328    }
6329
6330    #[test]
6331    fn clear_active_drops_stale_seats_and_reports_whether_it_did() {
6332        let mut s = state();
6333        assert!(!s.clear_active(), "nothing to clear on a fresh run");
6334        s.seat_started(
6335            "implement",
6336            "impl-B",
6337            std::time::Duration::from_secs(3600),
6338            0,
6339        );
6340        assert!(s.clear_active(), "a leftover entry is reported as cleared");
6341        assert!(s.active.is_empty());
6342    }
6343
6344    #[test]
6345    fn active_seat_carries_nothing_that_could_be_read_as_output_bytes() {
6346        // `agy` prints exactly one JSON object, at the very end (see
6347        // `agent::dropped_stream`'s doc comment) — a seat can sit at zero
6348        // captured bytes for its whole timeout while working normally. So
6349        // `ActiveSeat` records only the wall-clock facts (when it started,
6350        // its budget, which attempt), never a byte count, which is what
6351        // keeps a reader from being able to build "0 bytes => dead" out of
6352        // it even by accident.
6353        let seat = ActiveSeat {
6354            node: "implement".to_owned(),
6355            started_at: Timestamp::now(),
6356            timeout_secs: 60,
6357            attempt: 0,
6358            task: None,
6359            command: None,
6360            index: None,
6361            total: None,
6362        };
6363        let value = serde_json::to_value(&seat).unwrap();
6364        let keys: std::collections::BTreeSet<String> =
6365            value.as_object().unwrap().keys().cloned().collect();
6366        assert_eq!(
6367            keys,
6368            std::collections::BTreeSet::from([
6369                "node".to_owned(),
6370                "started_at".to_owned(),
6371                "timeout_secs".to_owned(),
6372                "attempt".to_owned(),
6373            ]),
6374            "a byte count here would be a lever to declare a silent-but-healthy seat dead, and \
6375             the task-only fields must stay absent (not null) on an ordinary seat entry"
6376        );
6377    }
6378
6379    /// The same guarantee as
6380    /// [`active_seat_carries_nothing_that_could_be_read_as_output_bytes`],
6381    /// extended to a task entry: `verify.e2e` / `verify.gate` are exactly as
6382    /// silent as `agy` between commands, so a running command-list task must
6383    /// never carry anything a reader could mistake for output-byte evidence
6384    /// either.
6385    #[test]
6386    fn task_active_seat_carries_nothing_that_could_be_read_as_output_bytes() {
6387        let seat = ActiveSeat {
6388            node: "verify".to_owned(),
6389            started_at: Timestamp::now(),
6390            timeout_secs: 600,
6391            attempt: 0,
6392            task: Some("e2e".to_owned()),
6393            command: Some("cargo test".to_owned()),
6394            index: Some(1),
6395            total: Some(3),
6396        };
6397        let value = serde_json::to_value(&seat).unwrap();
6398        let keys: std::collections::BTreeSet<String> =
6399            value.as_object().unwrap().keys().cloned().collect();
6400        assert_eq!(
6401            keys,
6402            std::collections::BTreeSet::from([
6403                "node".to_owned(),
6404                "started_at".to_owned(),
6405                "timeout_secs".to_owned(),
6406                "attempt".to_owned(),
6407                "task".to_owned(),
6408                "command".to_owned(),
6409                "index".to_owned(),
6410                "total".to_owned(),
6411            ]),
6412        );
6413    }
6414
6415    #[test]
6416    fn an_old_run_json_without_active_seats_still_loads() {
6417        // Schema did not bump for this field: an already-written run.json
6418        // simply lacks the key, and `#[serde(default)]` must fill it in
6419        // rather than fail the whole read.
6420        let s = state();
6421        let mut value = serde_json::to_value(&s).unwrap();
6422        value.as_object_mut().unwrap().remove("active");
6423        let back: RunState = serde_json::from_value(value).unwrap();
6424        assert!(back.active.is_empty());
6425        assert_eq!(back.schema, SCHEMA);
6426    }
6427
6428    #[test]
6429    fn an_old_run_json_without_jobs_still_loads() {
6430        // No schema bump for this field either, for the same reason: an
6431        // empty `jobs` list on an old record means exactly what it always
6432        // meant for that record — no adapter existed yet to report one —
6433        // and `#[serde(default)]` fills it in rather than failing the read.
6434        let s = state();
6435        let mut value = serde_json::to_value(&s).unwrap();
6436        value.as_object_mut().unwrap().remove("jobs");
6437        let back: RunState = serde_json::from_value(value).unwrap();
6438        assert!(back.jobs.is_empty());
6439        assert_eq!(back.schema, SCHEMA);
6440    }
6441
6442    #[test]
6443    fn ensure_can_delete_guards_live_and_unfolded_runs() {
6444        let mut s = state();
6445        // 1. A daemon is working on it right now.
6446        s.status = RunStatus::Prep;
6447        let err = s.ensure_can_delete(true).unwrap_err().to_string();
6448        assert!(err.contains("live daemon"), "{err}");
6449
6450        // 2. The same unfinished run with no daemon behind it is a leftover
6451        // from a killed process, and deletable. Without this an interrupted
6452        // run could never be removed: its status stays `prep` forever.
6453        assert!(s.ensure_can_delete(false).is_ok());
6454
6455        // 3. Unfolded candidates are refused either way — that is the guard
6456        // that stops a delete from discarding a worktree.
6457        s.status = RunStatus::Merged;
6458        s.candidates.push(Candidate {
6459            index: 0,
6460            label: 'A',
6461            agent: "a".to_owned(),
6462            branch: "b".to_owned(),
6463            worktree: PathBuf::from("/w"),
6464            summary: String::new(),
6465            stat: String::new(),
6466            files: 1,
6467            commits: 1,
6468            empty: false,
6469            failed: None,
6470            verified_noop: None,
6471            duration_ms: 0,
6472            folded: false,
6473        });
6474        let err = s.ensure_can_delete(false).unwrap_err().to_string();
6475        assert!(
6476            err.contains("magi fold"),
6477            "error must suggest `magi fold`: {err}"
6478        );
6479
6480        // 4. Folded and nobody working on it.
6481        s.candidates[0].folded = true;
6482        assert!(s.ensure_can_delete(false).is_ok());
6483    }
6484}
6485
6486impl RunState {
6487    /// A seed for a seat that changes agent, distinct on every call.
6488    pub fn next_seat_seed(&mut self) -> u64 {
6489        self.seat_epoch += 1;
6490        self.seed ^ self.seat_epoch.wrapping_mul(0x9E37_79B9_7F4A_7C15)
6491    }
6492}
6493
6494/// What kind of failure ended an agent's turn on a seat, for deciding whether
6495/// the seat is worth handing to the next roster agent.
6496#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
6497pub enum FailClass {
6498    /// A CLI rate limit.
6499    Quota,
6500    /// The turn outlived its budget.
6501    Timeout,
6502    /// Any other failure, with the message's shape (`failure_signature`,
6503    /// capped at 120 characters).
6504    Other(String),
6505}
6506
6507/// One reviewer seat's record across review rounds, so a round does not ask
6508/// an agent that already failed the seat while another one is answering.
6509///
6510/// `failed` is a *priority* set, not a bound: the per-round `tried` set in
6511/// `ask_json_wave` starts empty every round, so an agent that answered is
6512/// never locked out. A failed id is only asked again once nothing else on the
6513/// roster is left (once per round, and the rounds are `review_rounds`).
6514#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
6515pub struct SeatHistory {
6516    /// Roster ids that failed this seat and have not answered it since.
6517    #[serde(default)]
6518    pub failed: BTreeSet<String>,
6519    /// The agent that last answered this seat.
6520    #[serde(default)]
6521    pub last_ok: Option<String>,
6522    /// The class of the seat's most recent failure; cleared by an answer.
6523    #[serde(default)]
6524    pub last_fail: Option<FailClass>,
6525}