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 /// Acquisition was cancelled, possibly by a known park request.
1948 Cancelled {
1949 /// Available only when the caller retained the park request.
1950 park: Option<ParkCause>,
1951 },
1952 /// An infrastructure error, rather than an elapsed wait.
1953 Other,
1954}
1955
1956/// A resumable resource stop; earlier nodes or peers may already have run.
1957#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1958pub struct ResourceBlock {
1959 /// Node whose operation was blocked or interrupted.
1960 pub node: String,
1961 /// What stayed busy.
1962 pub kind: String,
1963 /// Structured evidence from the point where acquisition ended.
1964 #[serde(default)]
1965 pub cause: ResourceBlockCause,
1966 /// Why the operation ended, in words.
1967 pub detail: String,
1968 /// When it ended.
1969 pub at: Timestamp,
1970}
1971
1972impl ResourceBlock {
1973 /// Shared CLI, queue-hold and Web wording. Never infer a timeout from a
1974 /// resource kind or a legacy record's configured budget.
1975 #[must_use]
1976 pub fn description(&self) -> String {
1977 let reason = match &self.cause {
1978 ResourceBlockCause::Timeout {
1979 waited_secs,
1980 limit_secs,
1981 } => format!("resource wait timed out after {waited_secs}s (limit {limit_secs}s)"),
1982 ResourceBlockCause::Cancelled { park: Some(cause) } => {
1983 format!("resource wait cancelled for parking ({})", cause.label())
1984 }
1985 ResourceBlockCause::Cancelled { park: None } => "resource wait cancelled".into(),
1986 ResourceBlockCause::Other => "resource operation blocked".into(),
1987 ResourceBlockCause::Unrecorded if self.detail == "the run is parking" => {
1988 "resource wait cancelled for parking (request source unrecorded)".into()
1989 }
1990 ResourceBlockCause::Unrecorded
1991 if self.detail == "the wait for the build cache was cancelled" =>
1992 {
1993 "resource wait cancelled (request source unrecorded)".into()
1994 }
1995 ResourceBlockCause::Unrecorded => "resource stop cause unrecorded".into(),
1996 };
1997 format!("{}: {}: {reason} ({})", self.node, self.kind, self.detail)
1998 }
1999}
2000
2001impl ActiveSeat {
2002 /// Seconds since this attempt was sent.
2003 #[must_use]
2004 pub fn elapsed_secs(&self, now: Timestamp) -> i64 {
2005 (now.as_second() - self.started_at.as_second()).max(0)
2006 }
2007
2008 /// Seconds left before this attempt's own timeout fires, floored at zero
2009 /// rather than going negative once the CLI has overrun its budget.
2010 #[must_use]
2011 pub fn remaining_secs(&self, now: Timestamp) -> i64 {
2012 (self.timeout_secs as i64 - self.elapsed_secs(now)).max(0)
2013 }
2014}
2015
2016/// Whether a process is provably still driving a run, provably not, or
2017/// neither — see [`RunState::liveness`]. Serialized as a lowercase string
2018/// (`"live"` / `"dead"` / `"unknown"`) rather than a bool: a bool has no room
2019/// for "could not tell", and folding that case into either `true` or `false`
2020/// is exactly the wrong call for a display an operator uses to decide
2021/// whether to wait or to act — see the schema-10 field doc on
2022/// [`RunState::driver_pid`] for the report it used to produce instead.
2023#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
2024#[serde(rename_all = "lowercase")]
2025pub enum Liveness {
2026 /// Proven: a daemon's heartbeat or a matching held execution lease claims
2027 /// the run, or (for legacy records) `driver_pid` answers
2028 /// alive under the same identity (`driver_started_at`) this run recorded
2029 /// for it.
2030 Live,
2031 /// Proven: no daemon claim, and an explicit exit or matching free execution
2032 /// lease, or `driver_pid` answers dead outright
2033 /// or it answers alive under a *different* identity than recorded — a
2034 /// pid the OS has since handed to an unrelated process is exactly as
2035 /// good as proof the original driver is gone (see
2036 /// [`RunState::driver_started_at`]'s own doc).
2037 Dead,
2038 /// Neither proven — no daemon claim, and either no `driver_pid` to ask,
2039 /// the platform could not answer for it, or a live pid with nothing (or
2040 /// nothing queryable) to corroborate its identity against. Never treated
2041 /// as `Dead`: see [`RunState::liveness_with`].
2042 Unknown,
2043}
2044
2045/// A timestamped note about a node.
2046#[derive(Debug, Clone, Serialize, Deserialize)]
2047pub struct Event {
2048 /// When.
2049 pub at: Timestamp,
2050 /// Node name.
2051 pub node: String,
2052 /// What happened.
2053 pub message: String,
2054}
2055
2056/// How far the winner's tree trailed the landing base, last time it was
2057/// checked, and what came of trying to close that gap.
2058///
2059/// Set by `graph::Runner::sync_to_base`, which runs before the review loop and
2060/// again before the gate: verifying against a tree that does not yet contain
2061/// the base's tip answers "green on the commit this run branched from", not
2062/// "green on what is about to land", and a merge on that answer can revert
2063/// whatever landed elsewhere while the run was thinking.
2064#[derive(Debug, Clone, Serialize, Deserialize)]
2065pub struct BaseSync {
2066 /// `<remote>/<base>` tip the tree was last checked against.
2067 pub tip: String,
2068 /// Commits `tip` was ahead of the tree at that check, before any rebase
2069 /// this round tried to close the gap. Zero means the tree already
2070 /// contained `tip`.
2071 pub behind: usize,
2072 /// Lifetime synchronization reservations, never reset. The active interval
2073 /// in `base_sync_recovery` enforces `graph::BASE_SYNC_ROUNDS`.
2074 pub attempts: usize,
2075 /// What git said, if the most recent rebase attempt conflicted or could
2076 /// not be pushed. `Some` here is what makes a `Blocked` run read as
2077 /// "stopped on the base, not on review or the gate" - the rebase is not
2078 /// retried again while this is set; a person has to look.
2079 #[serde(default)]
2080 pub conflict: Option<String>,
2081 /// Set when the winner's whole change turned out to be on the base already
2082 /// under other commit ids (see [`crate::already`]). Present exactly when the
2083 /// run ended as [`RunStatus::AlreadyInBase`].
2084 #[serde(default)]
2085 pub already_in: Option<crate::already::Evidence>,
2086}
2087
2088/// What the land loop saw last time it looked at the pull request.
2089///
2090/// Strings for `state` and `checks` on purpose: they are `gh`'s vocabulary, and
2091/// pinning them into an enum here would mean a new GitHub check conclusion
2092/// turns a readable status into a deserialisation error on a run someone is
2093/// trying to look at.
2094#[derive(Debug, Clone, Serialize, Deserialize)]
2095pub struct PrRecord {
2096 /// Pull request url.
2097 pub url: String,
2098 /// Pull request number.
2099 pub number: u64,
2100 /// `open`, `merged` or `closed`.
2101 pub state: String,
2102 /// `pending`, `green`, `red` or `unknown`.
2103 pub checks: String,
2104 /// Land round, 1-based, or 0 before the first fix.
2105 pub round: usize,
2106 /// Land round budget.
2107 pub rounds: usize,
2108 /// Checks that were red when the pull request merged anyway (the forge
2109 /// said they do not block it). Empty for a green merge, and for any run
2110 /// recorded before this field existed - so empty is not proof nothing was
2111 /// red.
2112 #[serde(default, skip_serializing_if = "Vec::is_empty")]
2113 pub red_at_merge: Vec<String>,
2114}
2115
2116/// What the post-merge release-bump step did, and whether it needs a human.
2117///
2118/// Recorded next to the `bump` events rather than instead of them: the events
2119/// are the narrative, this is what `magi show`, the status word and the
2120/// notification read without parsing prose. `status` stays `Merged` - the
2121/// merge did happen - so [`RunState::needs_attention`] is the one place that
2122/// says a merged run is not fully done.
2123#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
2124pub struct ReleaseBump {
2125 /// The release pull request, when one was opened.
2126 #[serde(default)]
2127 pub pr_url: Option<String>,
2128 /// The version it releases.
2129 #[serde(default)]
2130 pub version: Option<String>,
2131 /// Did enabling automerge on `pr_url` succeed?
2132 #[serde(default)]
2133 pub automerge_enabled: bool,
2134 /// GitHub refused automerge because CI had already finished (the pull
2135 /// request was in clean status), so magi merged it directly. Kept apart
2136 /// from `automerge_enabled`, which stays the plain fact it says it is.
2137 #[serde(default)]
2138 pub merged_directly: bool,
2139 /// `[release] mode = "local"`: no automerge was armed; the pull request is
2140 /// merged on the owner's approval and released by `magi serve`
2141 /// ([`crate::release_local`]).
2142 #[serde(default)]
2143 pub local: bool,
2144 /// What the local release did (tag, commit, each command's exit code and
2145 /// output tail), kept here because the watcher's own record is deleted
2146 /// once the release is done.
2147 #[serde(default)]
2148 pub release: Option<crate::release_local::Job>,
2149 /// What went wrong, verbatim from the tool that said it.
2150 #[serde(default)]
2151 pub problem: Option<String>,
2152 /// What the operator has to do about it. `Some` is what makes a merged run
2153 /// read as needing attention.
2154 #[serde(default)]
2155 pub action_required: Option<String>,
2156 /// Why no release bump was made. A skipped bump is not a completed
2157 /// release: the report and the web page say SKIPPED with this reason.
2158 #[serde(default)]
2159 pub skipped: Option<String>,
2160}
2161
2162/// The workflow runs `land` reran on one head, with when (unix seconds).
2163#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
2164pub struct LandReruns {
2165 /// The commit the reruns were made on.
2166 pub head: String,
2167 /// Workflow run id to the unix second it was rerun.
2168 pub runs: BTreeMap<String, i64>,
2169}
2170
2171/// Successful launcher fetch, persisted independently of moving tracking refs.
2172#[derive(Debug, Clone, Serialize, Deserialize)]
2173pub struct FetchedBase {
2174 /// Remote fetched by the launcher.
2175 pub remote: String,
2176 /// Remote branch selected as the run base.
2177 pub branch: String,
2178 /// Resolved commit immediately after the successful fetch.
2179 pub commit: String,
2180 /// Time the launcher observed the successful fetch.
2181 pub fetched_at: Timestamp,
2182}
2183
2184/// Durable evidence recorded before startup can acquire repository assets.
2185#[derive(Debug, Clone, Serialize, Deserialize)]
2186pub struct Startup {
2187 /// Implementation, review, or public-head recovery.
2188 pub kind: String,
2189 /// Requested review branch, before any checkout or ref changes.
2190 pub branch: Option<String>,
2191 /// Last durable startup boundary.
2192 pub stage: String,
2193 /// Construction finished successfully; false forbids graph resumption.
2194 pub complete: bool,
2195 /// Original startup error, or an interruption requiring inspection.
2196 pub failure: Option<String>,
2197}
2198
2199/// Error context preserves the underlying typed refusal/resource error.
2200#[derive(Debug, Clone, Serialize, Deserialize)]
2201pub struct StartupFailure {
2202 /// Reserved run retained for audit.
2203 pub run: String,
2204 /// Boundary that failed.
2205 pub stage: String,
2206}
2207
2208impl std::fmt::Display for StartupFailure {
2209 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2210 write!(f, "run {} startup failed at {}", self.run, self.stage)
2211 }
2212}
2213
2214/// The whole run.
2215#[derive(Debug, Clone, Serialize, Deserialize)]
2216pub struct RunState {
2217 /// On-disk format version.
2218 pub schema: u32,
2219 /// Run id, e.g. `20260830-153012-a1b2`.
2220 pub id: String,
2221 /// Repository the run operates on.
2222 pub repo: PathBuf,
2223 /// Branch the run started from.
2224 pub base_branch: String,
2225 /// Commit the run started from.
2226 pub base_commit: String,
2227 /// Absent in older runs; never infer fetch evidence from a tracking ref.
2228 #[serde(default)]
2229 pub fetched_base: Option<FetchedBase>,
2230 /// Guarded destination for an isolated review of a foreign checkout.
2231 #[serde(default)]
2232 pub foreign_checkout: Option<crate::foreign_checkout::ForeignCheckout>,
2233 /// Reservation lifecycle; incomplete startups must never execute as fresh work.
2234 #[serde(default)]
2235 pub startup: Option<Startup>,
2236 /// The task, verbatim.
2237 pub instruction: String,
2238 /// Authored task criteria before review scaffolding was generated.
2239 #[serde(default)]
2240 pub task_instruction: Option<String>,
2241 /// When the run was created.
2242 pub created_at: Timestamp,
2243 /// Last state flush.
2244 pub updated_at: Timestamp,
2245 /// Execution activity for artifact reclamation; bookkeeping saves do not refresh it.
2246 #[serde(default)]
2247 pub output_activity_at: Option<Timestamp>,
2248 /// Current status.
2249 pub status: RunStatus,
2250 /// Seed for labels and session ids.
2251 pub seed: u64,
2252 /// Config snapshot, so a resumed run behaves like the original.
2253 pub config: Config,
2254 /// Applied explicit repair authorizations and crash checkpoints.
2255 #[serde(default)]
2256 pub repair_grants: Vec<crate::repair_budget::Applied>,
2257 /// Additive approval policy; retained even if a later head removes it.
2258 #[serde(default)]
2259 pub branch_owner_holds: Vec<BranchOwnerHold>,
2260 /// Did this run take a reference on `extensions.worktreeConfig` being on
2261 /// (see [`crate::git::acquire_worktree_config`])? If so, cleanup releases
2262 /// it - which only actually turns the setting back off once every other
2263 /// run sharing this repository has released its own reference too.
2264 #[serde(default)]
2265 pub enabled_worktree_config: bool,
2266 /// Public pull request head, separate from competition branches.
2267 #[serde(default)]
2268 pub pr_head: Option<String>,
2269 /// Operator-selected source and original public lease, distinct from repaired HEAD.
2270 #[serde(default)]
2271 pub pr_recovery: Option<crate::pr_recovery::Selection>,
2272 /// Actual ordered load inputs (remote-layer paths contain their source commit).
2273 /// The resolved commands are retained in `config`, without re-rendering provenance.
2274 #[serde(default)]
2275 pub recovery_config: Option<crate::pr_recovery::ConfigEvidence>,
2276 /// Last head successfully pushed by this run; never an observed remote tip.
2277 #[serde(default)]
2278 pub pr_pushed_head: Option<String>,
2279 /// Public PR head observed when the forge confirmed its merge; absent on old records.
2280 #[serde(default)]
2281 pub pr_merged_head: Option<String>,
2282 /// Last title posted by this run, used to preserve human title edits.
2283 #[serde(default)]
2284 pub pr_posted_title: Option<String>,
2285 /// Publication has not completed; resume retries it without competing again.
2286 #[serde(default)]
2287 pub pr_publication_pending: bool,
2288 /// Successor that owns this run's pull request; this record is historical.
2289 #[serde(default)]
2290 pub pr_taken_over_by: Option<String>,
2291 /// Empty attempt retired to a recovery authority; reports and refs remain.
2292 /// Separate from Superseded: this never settles questions or closes PRs.
2293 #[serde(default)]
2294 pub retired_to: Option<String>,
2295 /// Candidates.
2296 #[serde(default)]
2297 pub candidates: Vec<Candidate>,
2298 /// Initial blind rankings.
2299 #[serde(default)]
2300 pub judgements: Vec<Judgement>,
2301 /// `judge` decided a solo candidate needs no panel and only logged it.
2302 ///
2303 /// `judgements` stays empty in that case — nothing to distinguish from
2304 /// "not yet judged" — so this is the record that makes the skip
2305 /// idempotent: without it, every reentry re-ran `judge`, re-logged the
2306 /// same event, and rewrote `status` to `Judging` over whatever a later
2307 /// node had already concluded.
2308 #[serde(default)]
2309 pub judge_skipped: bool,
2310 /// Deliberation, if it happened.
2311 #[serde(default)]
2312 pub deliberation: Vec<DeliberationRound>,
2313 /// Private final votes.
2314 #[serde(default)]
2315 pub votes: Vec<VoteRecord>,
2316 /// The count.
2317 #[serde(default)]
2318 pub tally: Option<Tally>,
2319 /// Review rounds.
2320 #[serde(default)]
2321 pub reviews: Vec<ReviewRound>,
2322 /// Final gate.
2323 ///
2324 /// Never derive whether the gate has run from `gate.is_empty()` alone —
2325 /// use [`Self::gate_status`] instead. An empty list is ambiguous on its
2326 /// own: it is what an unattempted gate looks like, what a
2327 /// resource-blocked attempt leaves behind (see `graph::Runner::gate`'s
2328 /// own doc), and also what a repo with no `verify.gate` commands
2329 /// configured produces once it *has* run. [`Self::gate_ran`] is what
2330 /// tells the third case apart from the first two.
2331 #[serde(default)]
2332 pub gate: Vec<CommandOutcome>,
2333 /// Did `gate()` actually record an attempt — zero commands configured
2334 /// (not configured), or one or more commands that ran to
2335 /// completion — as opposed to never having run, or having last hit a
2336 /// resource-blocked retry?
2337 ///
2338 /// `gate.is_empty()` cannot tell those apart by itself: a repo with no
2339 /// `verify.gate` commands leaves `gate` empty exactly like an
2340 /// unattempted or resource-blocked one does, and reading that empty list
2341 /// as "not yet run" is what stranded a review-only run in
2342 /// `RunStatus::Gating` forever on such a repo — see `SCHEMA`'s doc for
2343 /// schema 7. A record written before this field existed defaults to
2344 /// `false` and is migrated in [`migrate_schema`].
2345 #[serde(default)]
2346 pub gate_ran: bool,
2347 /// The winner's commit the recorded `gate` ran against. `None` on a record
2348 /// from before this existed, which reads as "commit unknown".
2349 #[serde(default)]
2350 pub gate_head: Option<String>,
2351 /// Verification on a changed head, separate from the review judgment.
2352 #[serde(default)]
2353 pub head_e2e: Option<GateRepairE2e>,
2354 /// Append-only evidence replaced when the winner moves to another head.
2355 #[serde(default)]
2356 pub verification_history: Vec<VerificationEvidence>,
2357 /// Resume must reconcile, sync, gate and publish the existing PR head before CI.
2358 #[serde(default)]
2359 pub land_sync_pending: bool,
2360 /// Base synchronization attempts spent, including across landing resumes.
2361 #[serde(default)]
2362 pub land_sync_attempts: usize,
2363 /// Pinned base of a charged landing synchronization that has not completed.
2364 #[serde(default)]
2365 pub land_sync_target: Option<String>,
2366 /// Winner tip before a landing rebase, retained until worktree setup finishes.
2367 #[serde(default)]
2368 pub land_rebase_from: Option<String>,
2369 /// Fix rounds a failing gate has already spent, oldest first. Persisted
2370 /// right after each fixer call so a resumed run spends only what is left
2371 /// of `graph.gate_fix_rounds` instead of starting the budget over.
2372 #[serde(default)]
2373 pub gate_fixes: Vec<GateFixRecord>,
2374 /// Publication after gate repair requires successful e2e on the final SHA.
2375 #[serde(default)]
2376 pub gate_repair_e2e: Option<GateRepairE2e>,
2377 /// Fixer rounds spent on a rebase conflict (base sync and land share one
2378 /// budget, `graph.review_rounds`), oldest first. Persisted right before
2379 /// each fixer call, so a resumed run spends only what is left.
2380 #[serde(default)]
2381 pub rebase_fixes: Vec<RebaseFixRecord>,
2382 /// The graft phase's record, once it started or was skipped for a
2383 /// reason worth keeping. `None` for a run that never reached it.
2384 #[serde(default)]
2385 pub graft: Option<GraftRecord>,
2386 /// What this run inherited from the attempt it took over, and why (see
2387 /// [`crate::recovery`]). `None` for a run that took nothing over.
2388 /// Additive and `#[serde(default)]`, so `SCHEMA` stays put.
2389 #[serde(default)]
2390 pub recovery: Option<crate::recovery::RecoveryRecord>,
2391 /// Set at the review loop's hand-off when the last round ended with a
2392 /// blocking finding still open *and* a reviewer's final vote was reject
2393 /// (see [`ReviewRound::contested_handoff`]). `land` reads it to ask the
2394 /// owner before merging even with `graph.land_approval` off. A snapshot
2395 /// taken at hand-off, never recomputed later.
2396 #[serde(default)]
2397 pub contested_handoff: Option<ContestedHandoff>,
2398 /// The head commit `land` has armed (or is about to arm) GitHub auto-merge
2399 /// on. Saved *before* the arm call, so a crash right after it still tells
2400 /// a resume that the forge may be holding an armed merge. Cleared the
2401 /// moment auto-merge is disabled or the pull request is done.
2402 #[serde(default)]
2403 pub land_armed_head: Option<String>,
2404 /// Workflow runs `land` has rerun for the head it is bound to. Saved
2405 /// *before* each `gh run rerun`, so a restart never reruns twice; replaced
2406 /// when the head moves.
2407 #[serde(default)]
2408 pub land_reruns: Option<LandReruns>,
2409 /// First unreadable merge-state observation per head, independent of reruns.
2410 #[serde(default)]
2411 pub land_unsaid: Option<(String, i64)>,
2412 /// Structured CI evidence and owner question for a machine hold.
2413 #[serde(default)]
2414 pub land_unrelated: Option<crate::land::CiHold>,
2415 /// The merge-approval question `land` last filed, and the head commit its
2416 /// panel showed. An answer is only honoured for that exact commit: a fix
2417 /// or rebase push makes a new head the owner has not seen.
2418 #[serde(default)]
2419 pub land_approval: Option<LandApproval>,
2420 /// Repair history on this same PR and run; no second task owns the branch.
2421 #[serde(default)]
2422 pub merge_repairs: Vec<MergeRepair>,
2423 /// Owner stop/withdraw/replacement checkpoint, independent of PR head movement.
2424 #[serde(default)]
2425 pub merge_decision: Option<crate::merge_decision::Decision>,
2426 /// Exact owner requests committed atomically with abandonment.
2427 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
2428 pub abandonment_receipts: BTreeMap<String, String>,
2429 /// Previous attempt replaced by this run; its PR is never reused.
2430 #[serde(default)]
2431 pub replaces: Option<crate::merge_decision::Replacement>,
2432 /// The posting-gate question for this run's pull request text, if the gate
2433 /// withheld any. While `resolved` is `None` the run is parked on it.
2434 #[serde(default)]
2435 pub github_text: Option<GithubTextAsk>,
2436 /// The whole-change description of a review-only run, tied to the final
2437 /// commit and base it was written from. `None` until one was produced.
2438 #[serde(default)]
2439 pub change_summary: Option<ChangeSummary>,
2440 /// Outcomes of the `verify.pre_gate` commands from the latest time they
2441 /// ran on the winner. Informational only: a failure here never blocks the
2442 /// run, the gate stays the single arbiter. Overwritten on each pass.
2443 #[serde(default)]
2444 pub pre_gate: Vec<CommandOutcome>,
2445 /// The latest commit a `pre_gate` pass made, if any pass left changes.
2446 #[serde(default)]
2447 pub pre_gate_commit: Option<String>,
2448 /// Merge outcome.
2449 #[serde(default)]
2450 pub merge: Option<MergeOutcome>,
2451 /// Vendor tokens seen in judged material.
2452 #[serde(default)]
2453 pub leaks: Vec<Leak>,
2454 /// Seats lost to a CLI rate limit / quota, in the order they hit.
2455 #[serde(default)]
2456 pub quota: Vec<QuotaLoss>,
2457 /// Seats handed to the next roster agent after a failure, in order.
2458 /// Additive, so `SCHEMA` is not bumped.
2459 #[serde(default)]
2460 pub handovers: Vec<Handover>,
2461 /// How many agent-change seats this run has minted; mixed into their
2462 /// session ids so re-handing a seat to an agent it already had never
2463 /// reuses that agent's earlier uuid. Additive.
2464 #[serde(default)]
2465 pub seat_epoch: u64,
2466 /// Per reviewer seat, which roster agents already failed it and which one
2467 /// last answered, carried across review rounds. Additive, so `SCHEMA` is
2468 /// not bumped. See [`SeatHistory`].
2469 #[serde(default)]
2470 pub seat_history: BTreeMap<String, SeatHistory>,
2471 /// Stray foreign lockfiles a rescue commit left out, one entry per path.
2472 #[serde(default)]
2473 pub withheld: Vec<Withheld>,
2474 /// One entry per time a process took this run over (`Runner::execute`),
2475 /// oldest first. Append-only: a later resume closes the pass before it
2476 /// and never rewrites what that pass recorded. A run from before this
2477 /// existed has none for its earlier passes, which stay "not recorded".
2478 /// Additive, so `SCHEMA` is not bumped.
2479 #[serde(default)]
2480 pub passes: Vec<RunPass>,
2481 /// Inquiry-to-pass receipts, persisted only after the execution lease and
2482 /// owner claim have been acquired. Later completion/holds retain them.
2483 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
2484 pub decision_starts: BTreeMap<String, usize>,
2485 /// Inquiries whose dispatched resumes this upcoming execution will consume.
2486 #[serde(skip)]
2487 pub next_pass_inquiries: Vec<String>,
2488 /// Set by whoever is about to execute this run on a task's behalf, read
2489 /// and cleared by the next [`RunState::begin_pass`]. Never persisted.
2490 #[serde(skip)]
2491 pub next_pass_task_entry: bool,
2492 /// Parked at a node boundary, waiting to be resumed.
2493 ///
2494 /// A run that is neither finished nor being worked on is otherwise
2495 /// indistinguishable from one whose daemon was killed, and the two want
2496 /// opposite things from an operator: the first is expected to be resumed,
2497 /// the second is a leftover. Cleared by the resume that carries it on.
2498 #[serde(default)]
2499 pub parked: bool,
2500 /// Seats of `node` are waiting, before any agent is spawned, for a shared
2501 /// resource (the build cache's lease). While this is `Some` the seats in
2502 /// [`Self::active`] are *not* running: their countdown has not started.
2503 /// Cleared the moment the wait ends, whichever way.
2504 #[serde(default, skip_serializing_if = "Option::is_none")]
2505 pub resource_wait: Option<ResourceWait>,
2506 /// The run stopped on a resource operation. This does not establish a timeout.
2507 /// Pre-spawn acquisition failures do not spend the affected agent's budget,
2508 /// alter its seat history or cause fallback. Earlier operations may have
2509 /// completed; resource interruption can also stop a running operation.
2510 /// Cleared by resume.
2511 #[serde(default, skip_serializing_if = "Option::is_none")]
2512 pub resource_block: Option<ResourceBlock>,
2513 /// The run that took this run's worktree over, when one did — see
2514 /// [`crate::handover`]. `Some` means the worktree is gone on purpose and
2515 /// the run can no longer be resumed from it ([`Self::released`]).
2516 #[serde(default)]
2517 pub released_to: Option<String>,
2518 /// Branches that outlived this run's released worktree and now belong to
2519 /// the run in [`Self::released_to`] (and to its pull request). A later
2520 /// fold must leave them alone.
2521 #[serde(default)]
2522 pub released_branches: Vec<String>,
2523 /// Turns whose Git/artifact preservation is not confirmed. A resume retries
2524 /// persistence before deciding whether an interrupted turn needs execution.
2525 #[serde(default)]
2526 pub candidate_preservation: BTreeMap<char, String>,
2527 /// Interrupted turns whose empty trees must remain eligible for execution.
2528 /// Kept separately from preservation errors so failed rescue retries retain
2529 /// the distinction between an unfinished turn and a completed empty reply.
2530 #[serde(default)]
2531 pub interrupted_implementations: BTreeSet<char>,
2532 /// Legacy automatically inferred references, retained only for audit.
2533 /// These are never explicit authorization and never seed preparation.
2534 #[serde(default)]
2535 pub seeds: Vec<crate::refs::Seed>,
2536 /// Explicit, SHA-pinned implementation imports; separate from instruction text.
2537 #[serde(default, skip_serializing_if = "crate::refs::Sources::is_empty")]
2538 pub sources: crate::refs::Sources,
2539 /// Candidate preparation stopped before agents ran; requires an explicit source correction.
2540 #[serde(default)]
2541 pub prep_failure: Option<String>,
2542 /// None identifies legacy records; new runs persist preparation completion explicitly.
2543 #[serde(default)]
2544 pub prep_complete: Option<bool>,
2545 /// Per-seat conversation state.
2546 #[serde(default)]
2547 pub seats: BTreeMap<String, SeatState>,
2548 /// Seats currently mid-answer, keyed by seat.
2549 ///
2550 /// An entry exists from the moment a prompt is sent until a reply (of any
2551 /// kind — success, failure, quota, drop) comes back, so its keys are
2552 /// exactly "who hasn't answered yet" for whichever node populated it. See
2553 /// [`ActiveSeat`] for why a reader still has to check a live daemon
2554 /// before trusting one of these as "running" rather than "abandoned".
2555 #[serde(default)]
2556 pub active: BTreeMap<String, ActiveSeat>,
2557 /// Process id of whichever `execute()` call last drove this run —
2558 /// written at the very top of that method, the same place
2559 /// [`Self::clear_active`] runs, so a fresh reentry always overwrites the
2560 /// pid a previous, possibly-dead process left behind.
2561 ///
2562 /// A daemon-claimed run already has a stronger signal
2563 /// (`daemon::is_working_on`), but a `magi run` / `magi review` typed
2564 /// straight into a terminal claims nothing there — before this field
2565 /// existed, [`report::active_seats`] had no way to tell that run apart
2566 /// from one a killed process abandoned, and printed the same "no live
2567 /// daemon claims this run" warning over a run that was, in fact, still
2568 /// answering. See [`Liveness`] for how this and the daemon claim combine.
2569 /// Released ownership clears this field together with `driver_started_at`;
2570 /// legacy records may retain the old pid with `driver_exited = true`.
2571 #[serde(default)]
2572 pub driver_pid: Option<u32>,
2573 /// Whether execution has ever claimed this record. New runs persist false
2574 /// before exposure, then true atomically with their first pass and PID.
2575 /// None is legacy/unknown, never evidence that execution did not start.
2576 #[serde(default, skip_serializing_if = "Option::is_none")]
2577 pub driver_claimed: Option<bool>,
2578 /// The OS-reported moment [`Self::driver_pid`] started, recorded in the
2579 /// same breath as the pid itself — an opaque marker
2580 /// (`crate::proc::process_started_at`, epoch seconds as an integer
2581 /// string), compared only for equality. Older runs hold a locale-dependent
2582 /// string here; those read as `Unknown`, never `Dead`.
2583 ///
2584 /// A pid alone never proves a live process is *this run's* driver: pids
2585 /// get reused, sometimes within minutes on a busy machine, and a killed
2586 /// manual `magi run` whose pid a later, wholly unrelated process happens
2587 /// to receive would otherwise read back as `Liveness::Live` from that
2588 /// coincidence alone. [`Self::liveness`] re-queries the current holder
2589 /// of `driver_pid` and requires this marker to still match before
2590 /// trusting a live answer — a mismatch means a different process now
2591 /// answers to that number, and no marker to compare (an old run, or a
2592 /// platform this build could not ask at record time) means neither
2593 /// extreme can be proven.
2594 #[serde(default)]
2595 pub driver_started_at: Option<String>,
2596 /// The process named by [`Self::driver_pid`] has stopped driving this run:
2597 /// its graph walk returned, whatever the outcome. Cleared at the start of
2598 /// every walk, set as the last write of one.
2599 ///
2600 /// A long-lived `magi serve` outlives its individual graph walks. The
2601 /// execution guard sets this and clears the pid/start marker when a walk
2602 /// returns, is cancelled or unwinds. A kill or failed save instead leaves
2603 /// a free pass-bound execution lease or a lost process identity for
2604 /// startup reconciliation. Older exited records may retain a historical pid.
2605 #[serde(default)]
2606 pub driver_exited: bool,
2607 /// Last observation of the winner's pull request, when a land loop ran.
2608 ///
2609 /// Persisted rather than derived from the event log because the phone asks
2610 /// two questions about a run that has opened a PR - how are its checks and
2611 /// which round is it on - and parsing prose out of events to answer them
2612 /// would break the first time an event message was reworded.
2613 #[serde(default)]
2614 pub pr: Option<PrRecord>,
2615 /// The post-merge release-bump step's outcome, when it got as far as
2616 /// having one to report. See [`ReleaseBump`].
2617 #[serde(default)]
2618 pub release_bump: Option<ReleaseBump>,
2619 /// Decision history also survives failures before a release outcome exists.
2620 #[serde(default)]
2621 pub bump_decision_attempts: Vec<crate::bump::DecisionAttempt>,
2622 /// The last look at how far the winner's tree trailed the landing base,
2623 /// and the rebase(s) tried to close that gap. `None` until the tree has a
2624 /// winner to check.
2625 #[serde(default)]
2626 pub base_sync: Option<BaseSync>,
2627 /// Stable stop identity and single-use owner authorizations, with prior evidence.
2628 #[serde(default)]
2629 pub base_sync_recovery: crate::base_sync_recovery::Recovery,
2630 /// The design-deliberation stage's output, when `[graph] advise` ran it:
2631 /// one record per advisor seat, plus the synthesis blended into the
2632 /// implementer's prompt. `None` when the stage is off, has not run yet,
2633 /// or could not even resolve its seats - see
2634 /// [`crate::graph::Runner::advise`].
2635 #[serde(default)]
2636 pub advice: Option<crate::advise::Advice>,
2637 /// Whether the design-deliberation stage has already been attempted this
2638 /// run, whatever it produced. The idempotency marker `Runner::advise`
2639 /// checks on reentry, the same role [`Self::judge_skipped`] plays for
2640 /// `judge` - without it a resumed run whose stage failed (a misconfigured
2641 /// `[roles] advisors`, every seat quota'd) would re-run it, and re-spend
2642 /// the agent calls, on every single reentry before `implement`.
2643 #[serde(default)]
2644 pub advise_attempted: bool,
2645 /// Node log.
2646 #[serde(default)]
2647 pub events: Vec<Event>,
2648 /// Commands seats' own CLIs reported running, across every node — see
2649 /// [`JobRecord`]. Populated in [`crate::graph::wave`] as each seat
2650 /// answers, so a resumed run keeps what earlier waves already collected
2651 /// rather than losing it to a reentry. Empty on a record written before
2652 /// this existed, or wherever no adapter reads structured job events for
2653 /// the backend a seat used — both read as "no evidence", not "nothing
2654 /// ran".
2655 #[serde(default)]
2656 pub jobs: Vec<JobRecord>,
2657 /// Operator-triggered targeted fixes — see [`OperatorFixRequest`] and
2658 /// `SCHEMA`'s doc for schema 9. Empty on every record written before
2659 /// this existed, which reads correctly as "no operator fix ever
2660 /// requested".
2661 #[serde(default)]
2662 pub operator_fixes: Vec<OperatorFixRequest>,
2663 /// Absolute paths of the files the task was filed with (see
2664 /// `crate::queue::Task::attachments`), listed in the implementers' prompt
2665 /// and made readable to their seats. Refreshed from the task on every
2666 /// start and resume, so a file attached while the task was held reaches a
2667 /// resumed run. Additive and `#[serde(default)]`, so `SCHEMA` stays put.
2668 #[serde(default)]
2669 pub attachments: Vec<PathBuf>,
2670 /// Subjects of the commits a review-only run examines, oldest first, as
2671 /// they stood when the run opened. `Some` marks the run as reviewing
2672 /// existing work: the pull request title is taken from these rather than
2673 /// from the review prompt in `instruction`. Additive and
2674 /// `#[serde(default)]`, so `SCHEMA` stays put.
2675 #[serde(default)]
2676 pub reviewed_commits: Option<Vec<String>>,
2677 /// Who started this run and which task it serves — see [`Origin`] and
2678 /// `SCHEMA`'s doc for schema 13. `None` is a run recorded before origins
2679 /// existed, and is reported as unknown, never as an operator's.
2680 #[serde(default)]
2681 pub origin: Option<Origin>,
2682 /// Repository assignment generation captured before startup; legacy runs use zero.
2683 #[serde(default)]
2684 pub task_assignment: usize,
2685 /// Follow-up tasks filed from this run's open findings after it merged
2686 /// (`crate::followup`). Additive and `#[serde(default)]`, so `SCHEMA`
2687 /// stays put.
2688 #[serde(default)]
2689 pub followups: Vec<FollowupRecord>,
2690 /// Follow-up depth of the task this run served, remembered the first
2691 /// time it was read so deleting that task cannot reset the cap.
2692 #[serde(default)]
2693 pub followup_generation: Option<u32>,
2694 /// Chat the task this run served descends from, fixed at start like
2695 /// `followup_generation` so deleting the task cannot lose it.
2696 #[serde(default)]
2697 pub origin_chat: Option<String>,
2698 /// The pull-request comment naming the filed follow-ups was posted.
2699 #[serde(default)]
2700 pub followup_commented: bool,
2701 /// Held tasks the merge approval's deputy filed for this run that were
2702 /// released after the merge (`crate::followup::settle_deputy_tasks`).
2703 /// Additive and `#[serde(default)]`, so `SCHEMA` stays put; the task
2704 /// record is the source of truth and this is rebuilt from the queue.
2705 #[serde(default)]
2706 pub deputy_followups: Vec<String>,
2707}
2708
2709/// One follow-up task filed from a merged run. See [`RunState::followups`].
2710#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2711pub struct FollowupRecord {
2712 /// Queue task id.
2713 pub task: String,
2714 /// Finding ids it covers.
2715 pub findings: Vec<String>,
2716}
2717
2718/// A monotonic owner hold observed in a reviewed commit.
2719#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2720pub struct BranchOwnerHold {
2721 /// Approval switch enabled by the branch.
2722 pub control: crate::config::OwnerHold,
2723 /// Repository-relative configuration file.
2724 pub file: String,
2725 /// Pinned commit where the hold was first observed.
2726 pub head: String,
2727}
2728
2729/// Keep legacy heads stable while separating later repository assignments.
2730pub(crate) fn task_pr_branch_name(task: &str, assignment: usize) -> String {
2731 if assignment == 0 {
2732 format!("magi/task-{task}")
2733 } else {
2734 format!("magi/task-{task}-assignment-{assignment}")
2735 }
2736}
2737
2738/// Origin-only legacy callers have no queue record. A present but unreadable
2739/// record must never silently reset publication to the initial assignment.
2740pub(crate) fn task_assignment_for(task: &str) -> Result<usize> {
2741 let queue = crate::queue::Queue::open();
2742 match queue.get(task) {
2743 Ok(task) => Ok(task.reassignments.len()),
2744 Err(error) if queue.path_of(task).try_exists()? => {
2745 Err(error).context("cannot capture task repository assignment")
2746 }
2747 Err(_) => Ok(0),
2748 }
2749}
2750
2751impl RunState {
2752 /// Effective policy is the OR of trusted config and observed branch holds.
2753 pub fn owner_hold(&self, control: crate::config::OwnerHold) -> bool {
2754 control.base_value(&self.config.graph)
2755 || self.branch_owner_holds.iter().any(|h| h.control == control)
2756 }
2757
2758 /// Read only pinned commits of existing-branch reviews, never candidates.
2759 pub async fn observe_branch_owner_holds(&mut self, head: &str) {
2760 if !crate::graph::is_review_run(self) {
2761 return;
2762 }
2763 let (holds, diagnostics) = crate::config::branch_owner_holds(&self.repo, head).await;
2764 for message in diagnostics {
2765 tracing::warn!("{message}");
2766 self.event("approval-policy", message);
2767 }
2768 for (control, file) in holds {
2769 if self
2770 .branch_owner_holds
2771 .iter()
2772 .any(|h| h.control == control && h.file == file)
2773 {
2774 continue;
2775 }
2776 let message = format!(
2777 "{}=true from the reviewed branch's {file} at {head}",
2778 control.key()
2779 );
2780 tracing::info!("{message}");
2781 self.event("approval-policy", message);
2782 self.branch_owner_holds.push(BranchOwnerHold {
2783 control,
2784 file,
2785 head: head.to_owned(),
2786 });
2787 }
2788 }
2789
2790 /// A fresh, unreserved run. Production callers must call [`Self::reserve`]
2791 /// before using its id, deriving branches, or saving it. Resumes load instead.
2792 pub fn new(
2793 repo: PathBuf,
2794 base_branch: String,
2795 base_commit: String,
2796 instruction: String,
2797 config: Config,
2798 ) -> Self {
2799 let now = Timestamp::now();
2800 let seed = config.blind.seed.unwrap_or_else(crate::rng::entropy);
2801 Self {
2802 schema: SCHEMA,
2803 id: new_id(),
2804 repo,
2805 base_branch,
2806 base_commit,
2807 fetched_base: None,
2808 instruction,
2809 task_instruction: None,
2810 created_at: now,
2811 updated_at: now,
2812 output_activity_at: Some(now),
2813 status: RunStatus::Prep,
2814 seed,
2815 config,
2816 branch_owner_holds: Vec::new(),
2817 repair_grants: Vec::new(),
2818 enabled_worktree_config: false,
2819 foreign_checkout: None,
2820 pr_head: None,
2821 pr_recovery: None,
2822 recovery_config: None,
2823 pr_pushed_head: None,
2824 pr_merged_head: None,
2825 pr_posted_title: None,
2826 pr_publication_pending: false,
2827 pr_taken_over_by: None,
2828 retired_to: None,
2829 candidates: Vec::new(),
2830 judgements: Vec::new(),
2831 judge_skipped: false,
2832 deliberation: Vec::new(),
2833 votes: Vec::new(),
2834 tally: None,
2835 reviews: Vec::new(),
2836 gate: Vec::new(),
2837 gate_ran: false,
2838 gate_head: None,
2839 head_e2e: None,
2840 verification_history: Vec::new(),
2841 land_sync_pending: false,
2842 land_sync_attempts: 0,
2843 land_sync_target: None,
2844 land_rebase_from: None,
2845 gate_fixes: Vec::new(),
2846 gate_repair_e2e: None,
2847 rebase_fixes: Vec::new(),
2848 graft: None,
2849 recovery: None,
2850 contested_handoff: None,
2851 land_armed_head: None,
2852 land_reruns: None,
2853 land_unsaid: None,
2854 land_unrelated: None,
2855 land_approval: None,
2856 merge_repairs: Vec::new(),
2857 merge_decision: None,
2858 abandonment_receipts: BTreeMap::new(),
2859 replaces: None,
2860 github_text: None,
2861 change_summary: None,
2862 pre_gate: Vec::new(),
2863 pre_gate_commit: None,
2864 merge: None,
2865 leaks: Vec::new(),
2866 quota: Vec::new(),
2867 handovers: Vec::new(),
2868 seat_epoch: 0,
2869 seat_history: BTreeMap::new(),
2870 withheld: Vec::new(),
2871 passes: Vec::new(),
2872 decision_starts: BTreeMap::new(),
2873 next_pass_inquiries: Vec::new(),
2874 next_pass_task_entry: false,
2875 parked: false,
2876 resource_wait: None,
2877 resource_block: None,
2878 released_to: None,
2879 released_branches: Vec::new(),
2880 candidate_preservation: BTreeMap::new(),
2881 interrupted_implementations: BTreeSet::new(),
2882 seeds: Vec::new(),
2883 sources: crate::refs::Sources::default(),
2884 prep_failure: None,
2885 startup: None,
2886 prep_complete: Some(false),
2887 seats: BTreeMap::new(),
2888 active: BTreeMap::new(),
2889 driver_pid: None,
2890 driver_claimed: Some(false),
2891 driver_started_at: None,
2892 driver_exited: false,
2893 pr: None,
2894 release_bump: None,
2895 bump_decision_attempts: Vec::new(),
2896 base_sync: None,
2897 base_sync_recovery: Default::default(),
2898 advice: None,
2899 advise_attempted: false,
2900 attachments: Vec::new(),
2901 reviewed_commits: None,
2902 origin: None,
2903 task_assignment: 0,
2904 followups: Vec::new(),
2905 followup_generation: None,
2906 deputy_followups: Vec::new(),
2907 origin_chat: None,
2908 followup_commented: false,
2909 events: Vec::new(),
2910 jobs: Vec::new(),
2911 operator_fixes: Vec::new(),
2912 }
2913 }
2914
2915 /// Directory holding this run's state and artifacts.
2916 pub fn dir(&self) -> PathBuf {
2917 run_dir(&self.id)
2918 }
2919
2920 /// Short form used in branch names and reports.
2921 pub fn short(&self) -> &str {
2922 short_of(&self.id)
2923 }
2924
2925 /// Branch name for a label.
2926 pub fn branch_for(&self, label: char) -> String {
2927 format!("magi/{}/{}", self.short(), label)
2928 }
2929
2930 /// Capture task publication scope once, before reserving a new execution.
2931 pub(crate) fn set_origin(&mut self, origin: Origin) -> Result<()> {
2932 self.task_assignment = match origin.task.as_deref() {
2933 Some(task) => task_assignment_for(task)?,
2934 None => 0,
2935 };
2936 self.origin = Some(origin);
2937 Ok(())
2938 }
2939
2940 /// Public head for a queue competition. Review-only and standalone runs
2941 /// keep their existing branch. Invalid task ids cannot become git refs.
2942 pub fn task_pr_branch(&self) -> Option<String> {
2943 if self.reviewed_commits.is_some()
2944 || self
2945 .candidates
2946 .iter()
2947 .any(|c| c.agent == "(existing branch)")
2948 {
2949 // A review-only run continues the task's pull request only when
2950 // it inherited that head from an earlier attempt (see
2951 // `Runner::review_taking_over`). A legacy `magi/<run>/<label>`
2952 // PR or a hand-named branch keeps its own head.
2953 let inherited = self.pr_head.is_some();
2954 if !inherited {
2955 return None;
2956 }
2957 }
2958 let task = self.origin.as_ref()?.task.as_ref()?;
2959 let branch = task_pr_branch_name(task, self.task_assignment);
2960 let branch = if let Some(replaces) = &self.replaces {
2961 format!("{branch}-{}", replaces.question)
2962 } else {
2963 branch
2964 };
2965 std::process::Command::new("git")
2966 .quiet()
2967 .args(["check-ref-format", "--branch", &branch])
2968 .stdout(std::process::Stdio::null())
2969 .stderr(std::process::Stdio::null())
2970 .status()
2971 .ok()
2972 .filter(|s| s.success())?;
2973 if (self.reviewed_commits.is_some()
2974 || self
2975 .candidates
2976 .iter()
2977 .any(|c| c.agent == "(existing branch)"))
2978 && self.pr_head.as_deref() != Some(branch.as_str())
2979 {
2980 return None;
2981 }
2982 Some(branch)
2983 }
2984
2985 /// Recorded public head, falling back to the winner for older runs.
2986 pub fn pr_branch(&self) -> Option<&str> {
2987 self.pr_head
2988 .as_deref()
2989 .or_else(|| self.winner().map(|w| w.branch.as_str()))
2990 }
2991
2992 /// Root of this run's worktrees.
2993 pub fn worktree_root(&self) -> PathBuf {
2994 self.config
2995 .graph
2996 .worktree_root
2997 .clone()
2998 .unwrap_or_else(default_worktree_root)
2999 .join(self.short())
3000 }
3001
3002 /// Record lockfiles a rescue commit withheld; a path already recorded by an
3003 /// earlier round is not repeated.
3004 pub fn note_withheld(&mut self, node: &str, strays: &[crate::git::Stray]) {
3005 for s in strays {
3006 if self.withheld.iter().any(|w| w.path == s.path) {
3007 continue;
3008 }
3009 self.event(
3010 node,
3011 format!(
3012 "withheld stray lockfile {} ({}; the directory uses {})",
3013 s.path, s.manager, s.kept_by
3014 ),
3015 );
3016 self.withheld.push(Withheld {
3017 path: s.path.clone(),
3018 manager: s.manager.clone(),
3019 kept_by: s.kept_by.clone(),
3020 node: node.to_owned(),
3021 at: Timestamp::now(),
3022 });
3023 }
3024 }
3025
3026 /// A prepared fallback on timeout is not an owner's request to replace
3027 /// an existing human-edited payload. Explicit selections keep their source.
3028 pub(crate) fn explicit_github_text_selection(&self) -> bool {
3029 self.github_text.as_ref().is_some_and(|gate| {
3030 gate.resolved
3031 && gate.question.as_ref().is_some_and(|id| {
3032 crate::ask::Questions::open()
3033 .get_for_effects(id)
3034 .is_ok_and(|q| q.run == self.id && q.resolution().is_some())
3035 })
3036 })
3037 }
3038
3039 /// Save this marker together with the forge operation's successful checkpoint.
3040 /// Selecting a payload, accepting a reply and queuing a post do not call it.
3041 pub(crate) fn record_github_text_publication(&mut self, url: &str) {
3042 if let Some(gate) = &mut self.github_text
3043 && gate.resolved
3044 && let Some(inquiry) = &gate.question
3045 && let Some(choice) = gate.choice
3046 {
3047 gate.publication = Some(GithubTextPublication {
3048 inquiry: inquiry.clone(),
3049 fingerprint: gate.fingerprint.clone(),
3050 choice,
3051 url: url.to_owned(),
3052 });
3053 }
3054 }
3055
3056 /// Carry durable dispatch ownership into driver admission without treating
3057 /// dispatch itself as a receipt or replaying the owner's command.
3058 pub(crate) fn carry_dispatched_resumes(&mut self, task: &crate::queue::Task) {
3059 self.next_pass_inquiries = task
3060 .dispatched_resumes
3061 .iter()
3062 .filter(|(inquiry, run)| {
3063 **run == self.id && !self.decision_starts.contains_key(*inquiry)
3064 })
3065 .map(|(inquiry, _)| inquiry.clone())
3066 .collect();
3067 }
3068
3069 /// Open a pass for the process that is about to drive this run. A pass
3070 /// left open by an earlier process is closed as [`PassEnd::Unrecorded`];
3071 /// one that recorded its own end is never touched.
3072 pub fn begin_pass(&mut self) {
3073 let now = Timestamp::now();
3074 self.note_output_activity(now);
3075 if let Some(last) = self.passes.last_mut()
3076 && last.end.is_none()
3077 {
3078 last.end = Some(PassEnd::Unrecorded);
3079 last.ended_at = Some(now);
3080 }
3081 for inquiry in std::mem::take(&mut self.next_pass_inquiries) {
3082 self.decision_starts
3083 .entry(inquiry)
3084 .or_insert(self.passes.len());
3085 }
3086 let resumed = !self.passes.is_empty() || !self.candidates.is_empty();
3087 self.passes.push(RunPass {
3088 index: self.passes.len(),
3089 started_at: now,
3090 resumed,
3091 ended_at: None,
3092 end: None,
3093 task_entry: std::mem::take(&mut self.next_pass_task_entry),
3094 });
3095 }
3096
3097 /// Close the open pass as parked for `cause`. A pass that already has an
3098 /// end keeps it (the first reason wins).
3099 pub fn end_pass_parked(&mut self, cause: ParkCause) {
3100 if let Some(last) = self.passes.last_mut()
3101 && last.end.is_none()
3102 {
3103 last.end = Some(PassEnd::Parked { cause });
3104 last.ended_at = Some(Timestamp::now());
3105 }
3106 }
3107
3108 /// Resolve legacy delivery intent only from an already published PR and approval binding.
3109 fn recovery_disposition(&self) -> Option<crate::pr_recovery::Disposition> {
3110 let selected = self.pr_recovery.as_ref()?;
3111 selected.disposition.or_else(|| {
3112 (self.config.merge.mode == MergeMode::Pr
3113 && self.land_approval.is_some()
3114 && self.pr.as_ref().is_some_and(|pr| pr.url == selected.url))
3115 .then_some(crate::pr_recovery::Disposition::Land)
3116 })
3117 }
3118
3119 /// Validate a resumed recovery against its own durable configuration and landing records.
3120 pub fn configure_recovery_resume(&mut self) -> anyhow::Result<()> {
3121 if let Some(mut selected) = self.pr_recovery.clone() {
3122 selected.disposition = self.recovery_disposition();
3123 selected.configure(&mut self.config)?;
3124 }
3125 Ok(())
3126 }
3127
3128 /// Only a confirmed merge of the selected public PR completes a delivery task.
3129 pub fn public_delivery_complete(&self) -> bool {
3130 self.status == RunStatus::Merged
3131 && self.config.merge.mode == MergeMode::Pr
3132 && self
3133 .merge
3134 .as_ref()
3135 .is_some_and(|m| m.ok && !m.empty && m.mode == MergeMode::Pr)
3136 && self.pr.as_ref().is_some_and(|p| {
3137 p.state.eq_ignore_ascii_case("merged")
3138 && self.pr_recovery.as_ref().is_some_and(|s| {
3139 s.url == p.url
3140 && self.recovery_disposition()
3141 == Some(crate::pr_recovery::Disposition::Land)
3142 })
3143 })
3144 && self.pr_pushed_head.as_deref().is_some_and(|head| {
3145 self.pr_merged_head.as_deref() == Some(head)
3146 && self.check_delivery_evidence(head).is_ok()
3147 && self.land_approval.as_ref().is_some_and(|a| {
3148 a.head == head
3149 && crate::ask::Questions::open()
3150 .get_for_effects(&a.question)
3151 .is_ok_and(|q| {
3152 q.run == self.id
3153 && q.node == crate::land::APPROVAL_NODE
3154 && crate::land::approval(q.resolution().as_deref())
3155 == crate::land::Approval::Merge
3156 && q.merge_target.as_ref().is_some_and(|t| {
3157 t.head == head
3158 && self.pr.as_ref().is_some_and(|p| t.pr == p.url)
3159 })
3160 })
3161 })
3162 })
3163 }
3164
3165 /// Validate evidence for exactly the head about to be published or merged.
3166 pub fn check_delivery_evidence(&self, head: &str) -> anyhow::Result<()> {
3167 if self.recovery_disposition() != Some(crate::pr_recovery::Disposition::Land) {
3168 return Ok(());
3169 }
3170 let commands_match = |outcomes: &[CommandOutcome], commands: &[String]| {
3171 !commands.is_empty()
3172 && outcomes.len() == commands.len()
3173 && outcomes
3174 .iter()
3175 .zip(commands)
3176 .all(|(o, c)| o.ok() && &o.command == c)
3177 };
3178 anyhow::ensure!(
3179 self.gate_ran
3180 && self.gate_head.as_deref() == Some(head)
3181 && commands_match(&self.gate, &self.config.verify.gate),
3182 "delivery requires successful configured gate commands on the exact final head; request a fresh recovery review"
3183 );
3184 anyhow::ensure!(
3185 self.reviews.last().is_some_and(|r| r.clean
3186 && r.expected > 0
3187 && r.answered == r.expected
3188 && r.head == head
3189 && r.verified_head.as_deref() == Some(head)
3190 && commands_match(&r.e2e, &self.config.verify.e2e)),
3191 "delivery requires complete clean review and configured e2e commands on the exact final head; request a fresh recovery review"
3192 );
3193 Ok(())
3194 }
3195
3196 /// Reconcile after Git updates as well as on reentry after an interrupted save.
3197 /// Unknown legacy heads cannot establish current verification.
3198 pub fn reconcile_verification_head(&mut self, head: &str) {
3199 let stale_gate = self.gate_ran && self.gate_head.as_deref() != Some(head);
3200 let stale_e2e = self.head_e2e.as_ref().is_some_and(|e| e.head != head);
3201 if stale_gate || stale_e2e {
3202 self.verification_history.push(VerificationEvidence {
3203 superseded_by: Some(head.to_owned()),
3204 archived_at: Some(Timestamp::now()),
3205 fixes_spent: Some(self.gate_fixes.len()),
3206 gate_head: self.gate_head.clone(),
3207 gate_ran: self.gate_ran,
3208 gate: self.gate.clone(),
3209 e2e: self.head_e2e.clone(),
3210 });
3211 if stale_gate {
3212 let previous = self
3213 .gate_head
3214 .as_deref()
3215 .map(short)
3216 .unwrap_or_else(|| "unknown".into());
3217 self.event(
3218 "gate",
3219 format!(
3220 "archived gate on {previous}, superseded by {}; {} gate-fix round(s) already spent stay spent",
3221 short(head),
3222 self.gate_fixes.len()
3223 ),
3224 );
3225 self.gate.clear();
3226 self.gate_ran = false;
3227 self.gate_head = None;
3228 self.pre_gate.clear();
3229 self.pre_gate_commit = None;
3230 }
3231 if stale_e2e {
3232 self.head_e2e = None;
3233 }
3234 }
3235 }
3236
3237 /// Structured current failures take precedence over successful progress events.
3238 pub fn verification_blocking_cause(&self) -> Option<String> {
3239 if self.base_sync_blocked() {
3240 return self
3241 .base_sync
3242 .as_ref()
3243 .and_then(|s| s.conflict.as_ref())
3244 .map(|detail| format!("Base-sync conflict: {detail}"));
3245 }
3246 if let Some(resource) = &self.resource_block {
3247 return Some(resource.detail.clone());
3248 }
3249 if self.status != RunStatus::Blocked {
3250 return None;
3251 }
3252 if crate::graph::review_conclusion(&self.reviews, self.config.graph.review_rounds)
3253 == Some(RunStatus::Blocked)
3254 {
3255 return self.reviews.last().map(|r| format!(
3256 "review blocked on reviewed head {} ({} blocking finding(s), {}/{} reviewers answered)",
3257 r.head, r.blocking, r.answered, r.expected
3258 ));
3259 }
3260 if let Some(e) = &self.head_e2e
3261 && !e.passed
3262 && e.outcomes.iter().any(|o| !o.ok())
3263 {
3264 return Some(format!(
3265 "verify.e2e failed on head {}; nothing published",
3266 e.head
3267 ));
3268 }
3269 if let Some(e) = &self.gate_repair_e2e
3270 && !e.passed
3271 && e.outcomes.iter().any(|o| !o.ok())
3272 {
3273 return Some(format!(
3274 "verify.e2e failed on head {} after gate repair; nothing published",
3275 e.head
3276 ));
3277 }
3278 if self.gate_ran && self.gate.iter().any(|o| !o.ok()) {
3279 return Some(format!(
3280 "{} on head {} after {} gate-fix round(s); nothing published",
3281 crate::stop_reason::command_failure(
3282 "gate",
3283 self.gate.iter().find(|o| !o.ok()).unwrap()
3284 ),
3285 self.gate_head.as_deref().unwrap_or("unknown"),
3286 self.gate_fixes.len()
3287 ));
3288 }
3289 None
3290 }
3291
3292 /// Whether the configured gate commands completed successfully, independent of e2e.
3293 pub(crate) fn gate_commands_allow_progress(&self) -> bool {
3294 self.gate_status().ok()
3295 || (self
3296 .pr_recovery
3297 .as_ref()
3298 .is_none_or(|s| s.disposition == Some(crate::pr_recovery::Disposition::Review))
3299 && self.gate_ran
3300 && self.gate_status() == GateStatus::NotConfigured)
3301 }
3302
3303 /// Empty verification can finish an intentional workflow, without claiming a test pass.
3304 pub fn gate_allows_progress(&self) -> bool {
3305 self.gate_commands_allow_progress()
3306 && self
3307 .head_e2e
3308 .as_ref()
3309 .is_none_or(|e| e.passed && self.gate_head.as_deref() == Some(e.head.as_str()))
3310 }
3311
3312 /// Note something in the run log and on the tracing stream.
3313 pub fn event(&mut self, node: &str, message: impl Into<String>) {
3314 let message = message.into();
3315 tracing::info!(node, "{message}");
3316 self.events.push(Event {
3317 at: Timestamp::now(),
3318 node: node.to_owned(),
3319 message,
3320 });
3321 }
3322
3323 /// The honest state of the final gate.
3324 ///
3325 /// Never derive this from `gate.is_empty()` alone anywhere else in the
3326 /// codebase — `NotRun` and `NotConfigured` both leave `gate`
3327 /// empty, and only this method (backed by [`Self::gate_ran`]) tells them
3328 /// apart. An empty attempt is never verification evidence.
3329 pub fn gate_status(&self) -> GateStatus {
3330 if !self.gate_ran {
3331 GateStatus::NotRun
3332 } else if self.gate.is_empty() {
3333 GateStatus::NotConfigured
3334 } else if self.gate.iter().all(CommandOutcome::ok) {
3335 GateStatus::Passed
3336 } else {
3337 GateStatus::Failed
3338 }
3339 }
3340
3341 /// Record that `seat` was just sent a prompt for `node`, with the given
3342 /// wall-clock budget. `attempt` is 0 for the first ask and N for the Nth
3343 /// nudge or resume, purely for display — it does not change how the seat
3344 /// is treated.
3345 pub fn seat_started(
3346 &mut self,
3347 node: &str,
3348 seat: &str,
3349 timeout: std::time::Duration,
3350 attempt: usize,
3351 ) {
3352 self.active.insert(
3353 seat.to_owned(),
3354 ActiveSeat {
3355 node: node.to_owned(),
3356 started_at: Timestamp::now(),
3357 timeout_secs: timeout.as_secs(),
3358 attempt,
3359 task: None,
3360 command: None,
3361 index: None,
3362 total: None,
3363 },
3364 );
3365 }
3366
3367 /// The wave's pre-spawn wait is over: restart the clock of every seat of
3368 /// this batch so `started_at` means "the CLI is being spawned now".
3369 pub fn seats_spawning(&mut self, node: &str, attempt: usize) {
3370 self.resource_wait = None;
3371 let now = Timestamp::now();
3372 for a in self.active.values_mut() {
3373 if a.task.is_none() && a.node == node && a.attempt == attempt {
3374 a.started_at = now;
3375 }
3376 }
3377 }
3378
3379 /// `seat` holds its parallelism permit and its CLI is being spawned now.
3380 pub fn seat_spawned(&mut self, seat: &str) {
3381 if let Some(a) = self.active.get_mut(seat) {
3382 a.started_at = Timestamp::now();
3383 }
3384 }
3385
3386 /// Record that `seat` has answered, whatever the answer was.
3387 pub fn seat_finished(&mut self, seat: &str) {
3388 self.active.remove(seat);
3389 }
3390
3391 /// Record that `task` (`"e2e"` or `"gate"` — a shell-command list run
3392 /// outside any seat) has just started `command`, the `index`-th of
3393 /// `total`. Called at every command boundary, not once for the whole
3394 /// list: `verify.e2e` / `verify.gate` apply `timeout` per command, so
3395 /// this is the only way a reader can tell "how long is left" for
3396 /// whichever command is actually running right now, rather than a stale
3397 /// budget left over from the first one.
3398 #[allow(clippy::too_many_arguments)]
3399 pub fn task_command(
3400 &mut self,
3401 task: &str,
3402 node: &str,
3403 attempt: usize,
3404 command: &str,
3405 index: usize,
3406 total: usize,
3407 timeout: std::time::Duration,
3408 ) {
3409 self.active.insert(
3410 task.to_owned(),
3411 ActiveSeat {
3412 node: node.to_owned(),
3413 started_at: Timestamp::now(),
3414 timeout_secs: timeout.as_secs(),
3415 attempt,
3416 task: Some(task.to_owned()),
3417 command: Some(command.to_owned()),
3418 index: Some(index),
3419 total: Some(total),
3420 },
3421 );
3422 }
3423
3424 /// Record that `task` has finished its whole command list for this
3425 /// attempt.
3426 pub fn task_finished(&mut self, task: &str) {
3427 self.active.remove(task);
3428 }
3429
3430 /// The seats — never task entries — currently mid-answer. What
3431 /// `report::active_seats` and the phone's "who has not answered yet"
3432 /// note need: a seat's identifier is safe to show ([`ActiveSeat`]'s doc),
3433 /// so nothing here filters anything out beyond the type tag itself.
3434 pub fn seats_active(&self) -> impl Iterator<Item = (&String, &ActiveSeat)> {
3435 self.active.iter().filter(|(_, a)| a.task.is_none())
3436 }
3437
3438 /// The command-list tasks — never seat entries — currently running.
3439 /// Counterpart to [`Self::seats_active`]; see [`ActiveSeat::task`] for
3440 /// the tag both read.
3441 pub fn tasks_active(&self) -> impl Iterator<Item = (&String, &ActiveSeat)> {
3442 self.active.iter().filter(|(_, a)| a.task.is_some())
3443 }
3444
3445 /// Drop every seat this state still lists as answering, reporting whether
3446 /// anything was dropped.
3447 ///
3448 /// Called first thing in `execute`, on every entry — fresh, resumed, or
3449 /// recovering a stall — because an entry here only means something while
3450 /// the process that wrote it is still asking that seat something. A
3451 /// process killed mid-wave leaves its last batch of seats here with
3452 /// nobody left to clear them, and the next process to touch this run must
3453 /// not let that leftover read as "still going" before it has asked
3454 /// anyone anything.
3455 pub fn clear_active(&mut self) -> bool {
3456 if self.active.is_empty() {
3457 return false;
3458 }
3459 self.active.clear();
3460 true
3461 }
3462
3463 /// Does every seat this run still lists as [`Self::active`] sit past its
3464 /// own [`ActiveSeat::timeout_secs`]? `false` when nothing is active at
3465 /// all — an empty map is not evidence of anything overrunning.
3466 ///
3467 /// This alone is not proof the run is dead: a seat's own attempt can
3468 /// legitimately run a little past its budget while the process driving it
3469 /// is still tearing the attempt down. Every caller pairs this with its own
3470 /// `!live` reading (`daemon::is_working_on`) before treating the run as
3471 /// abandoned — this module cannot check that itself without depending on
3472 /// `crate::daemon`, and callers already have to ask that question anyway.
3473 #[must_use]
3474 pub fn active_all_overrun(&self, now: Timestamp) -> bool {
3475 !self.active.is_empty()
3476 && self
3477 .active
3478 .values()
3479 .all(|a| a.elapsed_secs(now) > a.timeout_secs as i64)
3480 }
3481
3482 /// Whether a process is actually still driving this run, given whether a
3483 /// daemon's heartbeat claims it and process-liveness/identity queries for
3484 /// [`Self::driver_pid`].
3485 ///
3486 /// A daemon claim wins outright when present — it is the stronger,
3487 /// independently-heartbeating signal. Absent that (every manual `magi
3488 /// run` / `magi review`, and every daemon-driven run whose daemon has
3489 /// since exited cleanly), `driver_pid` is asked directly. A live answer
3490 /// alone is not enough to trust, though: pids get reused, so `identity`
3491 /// re-queries whoever currently holds that pid and the result must still
3492 /// match [`Self::driver_started_at`] — the marker recorded at the same
3493 /// moment `driver_pid` was — before this reads `Live`. A mismatch means
3494 /// a *different* process now answers to that number, which is exactly as
3495 /// good as proof the original driver is gone, so that reads `Dead`. The
3496 /// marker is an epoch-seconds integer string; one that is not (a run
3497 /// recorded when it was a locale-dependent `ps` string) reads
3498 /// [`Liveness::Unknown`], never `Dead`. No
3499 /// marker to compare against (an old run, or a platform this build could
3500 /// not ask at record time) or a `None` from either query, and this
3501 /// cannot tell either way, so it reads [`Liveness::Unknown`] — never
3502 /// guessed as [`Liveness::Dead`] out of mere silence. A display that
3503 /// guessed "dead" out of missing information would be exactly the
3504 /// mtime-and-task-manager guessing this type exists to replace.
3505 ///
3506 /// Kept generic over `query` and `identity` so a test can inject answers
3507 /// without spawning a real process query — production code goes through
3508 /// [`Self::liveness`], which supplies [`crate::proc::pid_status`] and
3509 /// [`crate::proc::process_started_at`].
3510 #[must_use]
3511 pub fn liveness_with<F, G>(&self, daemon_claims: bool, query: F, identity: G) -> Liveness
3512 where
3513 F: FnOnce(u32) -> Option<bool>,
3514 G: FnOnce(u32) -> Option<String>,
3515 {
3516 if daemon_claims {
3517 return Liveness::Live;
3518 }
3519 // The driver said itself that it stopped; its pid may well be alive
3520 // (a daemon outlives the runs it drives), so it is not asked.
3521 if self.driver_exited {
3522 return Liveness::Dead;
3523 }
3524 let Some(pid) = self.driver_pid else {
3525 return Liveness::Unknown;
3526 };
3527 match query(pid) {
3528 Some(false) => Liveness::Dead,
3529 None => Liveness::Unknown,
3530 Some(true) => {
3531 let Some(recorded) = &self.driver_started_at else {
3532 return Liveness::Unknown;
3533 };
3534 // A marker in the old locale-dependent format can never be
3535 // compared reliably, so it proves nothing either way.
3536 if !crate::proc::is_identity_marker(recorded) {
3537 return Liveness::Unknown;
3538 }
3539 match identity(pid) {
3540 Some(current) if !crate::proc::is_identity_marker(¤t) => {
3541 Liveness::Unknown
3542 }
3543 Some(current) if *recorded == current => Liveness::Live,
3544 Some(_) => Liveness::Dead,
3545 None => Liveness::Unknown,
3546 }
3547 }
3548 }
3549 }
3550
3551 /// [`Self::liveness_with`], backed by the real process-liveness and
3552 /// identity queries.
3553 #[must_use]
3554 pub fn liveness(&self, daemon_claims: bool) -> Liveness {
3555 self.liveness_under(&home(), daemon_claims)
3556 }
3557
3558 /// The same judge, rooted at the caller's run store.
3559 #[must_use]
3560 pub fn liveness_under(&self, home: &Path, daemon_claims: bool) -> Liveness {
3561 self.liveness_under_with(
3562 home,
3563 daemon_claims,
3564 crate::proc::pid_status,
3565 crate::proc::process_started_at,
3566 )
3567 }
3568
3569 pub(crate) fn liveness_under_with<F, G>(
3570 &self,
3571 home: &Path,
3572 daemon_claims: bool,
3573 query: F,
3574 identity: G,
3575 ) -> Liveness
3576 where
3577 F: FnOnce(u32) -> Option<bool>,
3578 G: FnOnce(u32) -> Option<String>,
3579 {
3580 if daemon_claims {
3581 return Liveness::Live;
3582 }
3583 let process = self.liveness_with(false, query, identity);
3584 crate::driver::judge(self, home, process)
3585 }
3586
3587 /// Clear every seat this run still lists as active and fail it, unless it
3588 /// had already reached a terminal status some other way.
3589 ///
3590 /// Callers must already have proven this run is dead — [`Self::active_all_overrun`]
3591 /// plus their own `!live` reading — before calling this; it does not
3592 /// check either itself. Unlike [`Self::clear_active`] (dropping a resumed
3593 /// run's own stale wave before repopulating it, called unconditionally at
3594 /// the top of every `execute()`), this is a verdict: a run left this way
3595 /// has nothing left to repopulate the wave, ever, and must stop reading as
3596 /// `implementing` (or whichever node) forever.
3597 pub fn abandon(&mut self, by: &str) {
3598 let seats: Vec<String> = self.active.keys().cloned().collect();
3599 self.clear_active();
3600 if !self.status.done() {
3601 self.status = RunStatus::Failed;
3602 }
3603 self.event(
3604 by,
3605 format!(
3606 "abandoned: seat(s) {} left behind by a killed process, past their own \
3607 timeout with no live daemon claiming this run",
3608 seats.join(", ")
3609 ),
3610 );
3611 }
3612
3613 /// Reserve a fresh run's identity and persist its initial record.
3614 /// Call exactly once, before exposing the id; never call on a loaded run.
3615 pub fn reserve(&mut self) -> Result<()> {
3616 self.reserve_under(&home())
3617 }
3618
3619 /// [`Self::reserve`] with an explicit store home.
3620 pub fn reserve_under(&mut self, home: &Path) -> Result<()> {
3621 self.reserve_with(home, &crate::id_reserve::IdSource::new(new_id))
3622 }
3623
3624 fn reserve_with(&mut self, home: &Path, ids: &crate::id_reserve::IdSource) -> Result<()> {
3625 let root = home.join("runs");
3626 std::fs::create_dir_all(&root).context("create runs root")?;
3627 let initial = self.id.clone();
3628 ids.reserve(
3629 (!ids.is_custom()).then_some(initial.as_str()),
3630 "run",
3631 |id| {
3632 let dir = root.join(id);
3633 if !crate::id_reserve::create_dir(&dir)? {
3634 return Ok(false);
3635 }
3636 // Branches and worktrees use only the suffix. Publish our directory
3637 // before scanning: concurrent contenders either see each other and
3638 // retry, or the later one sees the earlier reservation and retries.
3639 for entry in std::fs::read_dir(&root).context("scan reserved run ids")? {
3640 let name = entry?.file_name();
3641 let Some(other) = name.to_str() else { continue };
3642 if other != id && is_run_id(other) && short_of(other) == short_of(id) {
3643 // Only remove our own empty directory, never existing data.
3644 std::fs::remove_dir(&dir).context("release colliding run suffix")?;
3645 return Ok(false);
3646 }
3647 }
3648 self.id = id.to_owned();
3649 // A failed first write rolls back only our own directory:
3650 // `remove_dir` refuses anything with contents, so a partial
3651 // record or another run's data is never deleted.
3652 if let Err(e) = self.save_under(home) {
3653 let _ = std::fs::remove_dir(&dir);
3654 return Err(e);
3655 }
3656 Ok(true)
3657 },
3658 )?;
3659 Ok(())
3660 }
3661
3662 pub(crate) fn note_output_activity(&mut self, at: Timestamp) {
3663 self.output_activity_at = Some(self.output_activity_at.unwrap_or(self.updated_at).max(at));
3664 }
3665
3666 pub(crate) fn output_activity(&self) -> Timestamp {
3667 self.passes.iter().fold(
3668 self.output_activity_at.unwrap_or(self.updated_at),
3669 |at, pass| {
3670 at.max(pass.started_at)
3671 .max(pass.ended_at.unwrap_or(pass.started_at))
3672 },
3673 )
3674 }
3675
3676 /// Flush to `run.json`, atomically, under the process-global [`home`].
3677 pub fn save(&mut self) -> Result<()> {
3678 let home = home();
3679 self.save_under(&home)
3680 }
3681
3682 /// [`Self::save`], rooted at an explicit `home` instead of the
3683 /// process-global one.
3684 ///
3685 /// For a caller that was already handed its own `home` explicitly — a
3686 /// housekeeping pass, mainly, for the same reason `Queue::at` and the
3687 /// daemon status path are parameters rather than resolved here (see
3688 /// `daemon::drive`'s own doc) — falling through to the global would write
3689 /// back through whichever directory some *other* process or test pinned
3690 /// into that `OnceLock` first, not the one this call was actually handed.
3691 pub fn save_under(&mut self, home: &Path) -> Result<()> {
3692 self.save_under_at(home, Timestamp::now())
3693 }
3694
3695 pub(crate) fn save_under_at(&mut self, home: &Path, at: Timestamp) -> Result<()> {
3696 // Freeze legacy age before a bookkeeping flush changes updated_at.
3697 self.output_activity_at.get_or_insert(self.updated_at);
3698 self.record_base_interruption();
3699 self.updated_at = at;
3700 let dir = home.join("runs").join(&self.id);
3701 std::fs::create_dir_all(&dir).with_context(|| format!("create {}", dir.display()))?;
3702 let body = serde_json::to_string_pretty(self).context("serialize run state")?;
3703 let tmp = dir.join("run.json.tmp");
3704 std::fs::write(&tmp, &body).with_context(|| format!("write {}", tmp.display()))?;
3705 std::fs::rename(&tmp, dir.join("run.json")).with_context(|| "replace run.json")?;
3706 Ok(())
3707 }
3708
3709 /// Load a run by id or unambiguous id prefix.
3710 pub fn load(id: &str) -> Result<Self> {
3711 let resolved = resolve_id(id)?;
3712 let path = run_dir(&resolved).join("run.json");
3713 let body =
3714 std::fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
3715 let state: Self =
3716 serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
3717 migrate_schema(state)
3718 }
3719
3720 /// [`Self::load`], rooted at an explicit `home` instead of the
3721 /// process-global one, and for a full id rather than a prefix — a caller
3722 /// with its own `home` already has the exact id (from a `RunState` it
3723 /// already read, or from `Task::runs`) and has no `runs_root` to search
3724 /// for a prefix against in the first place. Same reasoning as
3725 /// [`Self::save_under`]: a caller holding its own `home` explicitly must
3726 /// not read back through whichever directory some *other* process or
3727 /// test pinned into the global [`home`] `OnceLock` first.
3728 pub fn load_under(id: &str, home: &Path) -> Result<Self> {
3729 let path = home.join("runs").join(id).join("run.json");
3730 let body =
3731 std::fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
3732 let state: Self =
3733 serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
3734 migrate_schema(state)
3735 }
3736}
3737
3738pub(crate) fn migrate_schema(mut state: RunState) -> Result<RunState> {
3739 state.output_activity_at.get_or_insert(state.updated_at);
3740 // Schema 5 predates deferred e2e. Its empty e2e lists therefore mean
3741 // "not configured", never "deferred"; serde's field defaults retain
3742 // exactly that representation while this migration permits resumes.
3743 if state.schema == 5 {
3744 state.schema = 6;
3745 }
3746 // Schema 6 predates `gate_ran` and could not tell "never attempted or
3747 // resource-blocked" apart from "ran with zero commands configured" — see
3748 // `SCHEMA`'s doc for schema 7. A non-empty `gate` is a real recorded
3749 // attempt either way, so it is trusted as `gate_ran = true` rather than
3750 // spent again; an empty one is simply handed back to the next `gate()`
3751 // call, which re-attempts it and, for the zero-commands case, resolves
3752 // instantly.
3753 if state.schema == 6 {
3754 state.gate_ran = !state.gate.is_empty();
3755 state.schema = 7;
3756 }
3757 // Schema 7's main review loop always checked `e2e` against the round's
3758 // own `head`, it just never wrote that fact into `verified_head` unless
3759 // a catch-up run had checked a *different* commit — see `SCHEMA`'s doc
3760 // for schema 8. Reconstructing `Some(head)` for a round whose `e2e` held
3761 // a real attempt restores a fact that was always true; `verified_at` has
3762 // no historical value to recover and stays `None`.
3763 if state.schema == 7 {
3764 for round in &mut state.reviews {
3765 if round.verified_head.is_none()
3766 && matches!(round.e2e_status(), E2eStatus::Passed | E2eStatus::Failed)
3767 {
3768 round.verified_head = Some(round.head.clone());
3769 }
3770 }
3771 state.schema = 8;
3772 }
3773 // Schema 8 predates `operator_fixes`. There is nothing to reconstruct —
3774 // an old run simply never had one requested — so `#[serde(default)]`
3775 // already left it as the correct empty `Vec`; this only advances the
3776 // version number.
3777 if state.schema == 8 {
3778 state.schema = 9;
3779 }
3780 // Schema 9 predates `RunStatus::VerifiedNoop` and
3781 // `Candidate::verified_noop`. Nothing to reconstruct: an old record never
3782 // made the claim, `#[serde(default)]` already reads `verified_noop` as
3783 // `None` on every candidate, and a `VerifiedNoop` status cannot appear in
3784 // a schema-9 record at all — see `SCHEMA`'s doc for schema 10. This only
3785 // advances the version number.
3786 if state.schema == 9 {
3787 state.schema = 10;
3788 }
3789 // Schema 10 predates `released_to`: no old run ever had its worktree
3790 // handed over, and `#[serde(default)]` reads exactly that. Only the
3791 // version number advances.
3792 if state.schema == 10 {
3793 state.schema = 11;
3794 }
3795 // Schema 11 predates `driver_exited`. A run that had already ended
3796 // Blocked / Failed / Stalled, or was parked in Landing (which hands its
3797 // daemon slot back), stopped walking the graph, but its recorded
3798 // pid may belong to a daemon still alive doing other work, which would pin
3799 // it as running for good; those are marked exited. Any other status keeps
3800 // `false`, and its pid is asked as before. This is an inference from
3801 // status, sound because a schema-11 record was written by a build that is
3802 // gone once this one is installed (and a daemon claim, which wins
3803 // regardless, still protects a run a live daemon is driving).
3804 if state.schema == 11 {
3805 if matches!(
3806 state.status,
3807 RunStatus::Blocked | RunStatus::Failed | RunStatus::Stalled | RunStatus::Landing
3808 ) {
3809 state.driver_exited = true;
3810 }
3811 state.schema = 12;
3812 }
3813 // Schema 12 predates `origin`. Nothing is reconstructed: `None` already
3814 // says "unknown", which is the truth for a run nobody recorded. Only the
3815 // version number advances.
3816 if state.schema == 12 {
3817 state.schema = 13;
3818 }
3819 // Schema 13 predates `task_instruction`. Its `instruction` may include
3820 // generated review context, so it cannot supply authored criteria.
3821 // `#[serde(default)]` leaves the missing field as `None`; only the
3822 // version number advances, preserving origin and execution state.
3823 if state.schema == 13 {
3824 state.schema = 14;
3825 }
3826 // Only legacy, unfolded empty candidates lack a confirmed preservation
3827 // result, even if their CLI failed: failure never proves edits were saved.
3828 // Native schema-15 records and intentionally folded candidates
3829 // must not be re-flagged on every resume.
3830 if state.schema == 14 {
3831 for c in &state.candidates {
3832 if !c.folded && c.empty && c.verified_noop.is_none() {
3833 state
3834 .candidate_preservation
3835 .entry(c.label)
3836 .or_insert_with(|| "legacy empty candidate requires inspection".to_owned());
3837 }
3838 }
3839 state.schema = 15;
3840 }
3841 // Native schema-15 preservation outcomes remain unchanged. Retirement
3842 // adds an execution fence without inferring any new preservation result.
3843 if state.schema == 15 {
3844 state.schema = 16;
3845 }
3846 // Legacy runs belong to the initial assignment unless a generation was
3847 // explicitly captured. Do not derive it from the task's current state.
3848 if state.schema == 16 {
3849 state.schema = SCHEMA;
3850 }
3851 if state.schema != SCHEMA {
3852 bail!(
3853 "run {} was written by a different magi (schema {}, this build \
3854 speaks {SCHEMA})",
3855 state.id,
3856 state.schema
3857 );
3858 }
3859 Ok(state)
3860}
3861
3862impl RunState {
3863 /// Whether a later attempt took this run's worktree over, so a resume has
3864 /// nothing left to continue from.
3865 pub fn released(&self) -> bool {
3866 self.released_to.is_some()
3867 }
3868
3869 /// The winning candidate, once the tally has run.
3870 pub fn winner(&self) -> Option<&Candidate> {
3871 let label = self.tally.as_ref()?.winner;
3872 self.candidates.iter().find(|c| c.label == label)
3873 }
3874
3875 /// Candidates eligible for judging.
3876 pub fn viable(&self) -> Vec<&Candidate> {
3877 self.candidates.iter().filter(|c| c.viable()).collect()
3878 }
3879
3880 /// Did every candidate write nothing, and every one of them back it with
3881 /// evidence [`crate::graph`]'s adoption guard accepted?
3882 ///
3883 /// All-or-nothing on purpose: one candidate declaring `NO CHANGE NEEDED`
3884 /// while another simply failed to produce anything is not agreement, it
3885 /// is one candidate's unverified claim next to an ordinary loss, and the
3886 /// run must still read as the `Failed` it is. Only ever meaningful when
3887 /// [`Self::viable`] is already empty — a run with any real patch to judge
3888 /// never reaches the caller that asks this.
3889 pub fn all_candidates_verified_noop(&self) -> bool {
3890 !self.candidates.is_empty()
3891 && self
3892 .candidates
3893 .iter()
3894 .all(|c| c.empty && c.verified_noop.is_some())
3895 }
3896
3897 /// Findings still open when the review loop stopped trying: the last
3898 /// round's, exactly when that round was not clean. Empty on a run that
3899 /// never reviewed, or whose last round was clean.
3900 ///
3901 /// This is the last round's findings regardless of what the fixer claims
3902 /// to have addressed in that same round: a round that stopped the loop
3903 /// (round budget spent, or no tree progress for
3904 /// [`crate::graph::STAGNANT_LIMIT`] rounds) never had a *following* round
3905 /// to confirm the fix actually landed, and the self-reported adoption
3906 /// count is not trusted for that judgement either — see
3907 /// [`ReviewRound::progressed`].
3908 pub fn open_findings(&self) -> Vec<&Finding> {
3909 match self.reviews.last() {
3910 Some(r) if !r.clean => r
3911 .reviews
3912 .iter()
3913 .flat_map(|rec| rec.findings.iter())
3914 .collect(),
3915 _ => Vec::new(),
3916 }
3917 }
3918
3919 /// Every finding raised in the most recent review round, regardless of
3920 /// that round's own severity mix — unlike [`Self::open_findings`], not
3921 /// filtered to a round that was not clean. This is the pool `magi fix`
3922 /// reports as available to pick from: a round can conclude clean (no
3923 /// finding blocked merge) while still carrying minor findings nobody
3924 /// has acted on.
3925 pub fn last_round_findings(&self) -> Vec<&Finding> {
3926 self.reviews
3927 .last()
3928 .into_iter()
3929 .flat_map(|r| r.reviews.iter())
3930 .flat_map(|rec| rec.findings.iter())
3931 .collect()
3932 }
3933
3934 /// Look up a finding by id anywhere in this run's review history,
3935 /// together with the round and reviewer record that raised it — the
3936 /// provenance `magi fix` snapshots onto [`OperatorFixFinding`].
3937 pub fn finding(&self, id: &str) -> Option<(&ReviewRound, &ReviewRecord, &Finding)> {
3938 self.reviews.iter().find_map(|round| {
3939 round.reviews.iter().find_map(|rec| {
3940 rec.findings
3941 .iter()
3942 .find(|f| f.id == id)
3943 .map(|f| (round, rec, f))
3944 })
3945 })
3946 }
3947
3948 /// Did this run reach a mergeable status (`Ready` or `Merged`) with
3949 /// review findings still open?
3950 ///
3951 /// That combination is the point of the review hand-off: the review
3952 /// round budget (or an unproductive round, see [`ReviewRound::progressed`])
3953 /// was spent while gate and e2e stayed green, so the run was handed off
3954 /// rather than blocked — but the findings did not disappear, and whoever
3955 /// reads the result should be told they are still there.
3956 pub fn handed_off_with_open_findings(&self) -> bool {
3957 matches!(self.status, RunStatus::Ready | RunStatus::Merged)
3958 && self.reviews.last().is_some_and(|r| !r.clean)
3959 }
3960
3961 /// Reached `Ready` because `[merge] mode = "none"` left it there by
3962 /// design, never to be picked up by the PR-polling merge watcher — as
3963 /// opposed to a `Ready` that is still a plausible landing candidate (a
3964 /// PR closed without merging, or a re-entry onto an already-concluded
3965 /// node). Both leave `status` at `Ready`; only this one leaves the
3966 /// winning branch permanently unwatched, which is what a caller needs to
3967 /// know before labelling the run in a listing.
3968 pub fn unmerged_by_design(&self) -> bool {
3969 self.status == RunStatus::Ready
3970 && self
3971 .merge
3972 .as_ref()
3973 .is_some_and(|m| m.mode == MergeMode::None)
3974 }
3975
3976 /// Did a step after the merge leave something only a human can finish?
3977 ///
3978 /// Derived, not a status: the merge happened, so `status` stays `Merged`
3979 /// and everything that branches on it keeps working. Display code asks
3980 /// this so a merged run with an unmerged release PR does not read as
3981 /// plain green.
3982 pub fn needs_attention(&self) -> bool {
3983 self.status == RunStatus::Merged
3984 && self
3985 .release_bump
3986 .as_ref()
3987 .is_some_and(|b| b.action_required.is_some())
3988 }
3989
3990 /// Local-time creation stamp for reports.
3991 pub fn created_local(&self) -> String {
3992 self.created_at
3993 .to_zoned(jiff::tz::TimeZone::system())
3994 .strftime("%Y-%m-%d %H:%M:%S")
3995 .to_string()
3996 }
3997
3998 /// Assert that this run is safe to delete.
3999 ///
4000 /// Refuses a run a live daemon is working on, and refuses any run whose
4001 /// candidate worktrees and branches have not been folded away with `magi
4002 /// fold`. The fold requirement is the real protection: it is what makes
4003 /// "delete" mean "remove a record" rather than "throw away a worktree
4004 /// somebody may still be editing".
4005 ///
4006 /// `in_flight` has to come from the caller, because a run's own status
4007 /// cannot answer the question. A daemon killed mid-run leaves its status at
4008 /// `implementing` forever, and a guard that trusted that would make every
4009 /// interrupted run permanently undeletable - the operator's only recourse
4010 /// being to edit `run.json` by hand, which is exactly the sort of thing
4011 /// this command exists to avoid. The queue already treats an orphaned
4012 /// `.lock` from a `SIGKILL`ed daemon the same way; this is that rule for
4013 /// runs.
4014 pub fn ensure_can_delete(&self, in_flight: bool) -> Result<()> {
4015 if in_flight {
4016 bail!(
4017 "run {} is being worked on by a live daemon right now",
4018 self.short()
4019 );
4020 }
4021 if self.candidates.iter().any(|c| !c.folded) {
4022 bail!(
4023 "run {} has unfolded candidates; fold first with `magi fold`",
4024 self.short()
4025 );
4026 }
4027 Ok(())
4028 }
4029}
4030
4031/// The short form of a commit, for a label a human or an LLM reads.
4032fn short(commit: &str) -> String {
4033 commit.chars().take(7).collect()
4034}
4035
4036/// The short form of a run id: the trailing block after the last `-`.
4037///
4038/// A free function as well as [`RunState::short`], because callers that have
4039/// only an id - an error message, a daemon status, a route handler - were
4040/// otherwise reimplementing the split, and two spellings of "short id" is one
4041/// rename away from branch names that no longer match their run.
4042pub fn short_of(id: &str) -> &str {
4043 id.split('-').next_back().unwrap_or(id)
4044}
4045
4046/// Where magi keeps its runs.
4047///
4048/// `MAGI_HOME` overrides the default, and [`set_home`] overrides both — which
4049/// is what lets the integration tests drive a whole graph without writing into
4050/// the operator's real history.
4051///
4052/// In a unit test build (`cfg(test)`), falling through to the real
4053/// `<data_local>/magi` is not a fallback worth having: it is exactly how
4054/// three broken fixture runs ended up in the operator's actual history and
4055/// were counted as `unreadable` by the deck. A test that reaches this point
4056/// forgot to call [`set_home`] (or set `MAGI_HOME`) - that is a bug in the
4057/// test, not a case to serve, so it panics instead of writing anywhere.
4058pub fn home() -> PathBuf {
4059 resolve_home(HOME.get().cloned(), std::env::var_os("MAGI_HOME"))
4060}
4061
4062/// The decision `home` makes, taking its two overrides as plain values
4063/// instead of reading the `OnceLock` and the environment itself.
4064///
4065/// Pulled out so the `cfg(test)` panic is asserted directly against a
4066/// `None, None` input, rather than racing every other unit test in the
4067/// binary for who touches the process-global `HOME` first.
4068fn resolve_home(pinned: Option<PathBuf>, magi_home_env: Option<std::ffi::OsString>) -> PathBuf {
4069 if let Some(dir) = pinned {
4070 return dir;
4071 }
4072 if let Some(dir) = magi_home_env {
4073 return PathBuf::from(dir);
4074 }
4075 #[cfg(test)]
4076 {
4077 panic!(
4078 "run::home() was reached in a test without run::set_home() or \
4079 MAGI_HOME; this would write into the operator's real \
4080 <data_local>/magi. Call `run::set_home(temp_dir)` before any \
4081 code path that touches a RunState."
4082 );
4083 }
4084 #[cfg(not(test))]
4085 {
4086 dirs::data_local_dir()
4087 .unwrap_or_else(|| PathBuf::from("."))
4088 .join("magi")
4089 }
4090}
4091
4092/// [`home`] without the test panic: `None` in a test that never pinned a
4093/// home, so best-effort writers (see [`crate::notices::raise`]) skip the write
4094/// instead of touching the operator's real state or aborting the test.
4095pub fn try_home() -> Option<PathBuf> {
4096 if cfg!(test) {
4097 HOME.get()
4098 .cloned()
4099 .or_else(|| std::env::var_os("MAGI_HOME").map(PathBuf::from))
4100 } else {
4101 Some(home())
4102 }
4103}
4104
4105/// Pin the run home for this process. The first call wins.
4106pub fn set_home(dir: PathBuf) {
4107 let _ = HOME.set(dir);
4108}
4109
4110/// A temp directory unique to this test process, created once and kept.
4111/// `set_home` is a first-wins `OnceLock`, so a fixed `temp_dir().join(..)`
4112/// would be shared by every concurrent `cargo test` process on the machine.
4113#[cfg(test)]
4114pub(crate) fn test_home() -> PathBuf {
4115 static DIR: std::sync::OnceLock<PathBuf> = std::sync::OnceLock::new();
4116 DIR.get_or_init(|| {
4117 tempfile::Builder::new()
4118 .prefix("magi-unit-home-")
4119 .tempdir()
4120 .expect("create the unit-test home")
4121 .keep()
4122 })
4123 .clone()
4124}
4125
4126/// [`set_home`] on [`test_home`]; the one way a unit test pins the home.
4127#[cfg(test)]
4128pub(crate) fn pin_test_home() {
4129 set_home(test_home());
4130}
4131
4132static HOME: std::sync::OnceLock<PathBuf> = std::sync::OnceLock::new();
4133
4134/// `<home>/runs`.
4135pub fn runs_root() -> PathBuf {
4136 home().join("runs")
4137}
4138
4139/// The worktree root a run uses when the config sets none: `~/wt/magi`.
4140///
4141/// One definition of the default, so the folder the janitor folds and the
4142/// folder the health view sizes cannot drift apart: a run with no configured
4143/// [`crate::config::Graph::worktree_root`] lays its worktrees exactly here.
4144pub fn default_worktree_root() -> PathBuf {
4145 dirs::home_dir()
4146 .unwrap_or_else(|| PathBuf::from("."))
4147 .join("wt")
4148 .join("magi")
4149}
4150
4151/// Directory for one run id.
4152pub fn run_dir(id: &str) -> PathBuf {
4153 runs_root().join(id)
4154}
4155
4156/// Every run id on disk, newest first.
4157///
4158/// A directory is a run because of its **name**, not because it holds a
4159/// readable `run.json`. A run whose very first save lost the machine's last
4160/// free bytes leaves `<id>/run.json.tmp` and nothing else, and filtering on
4161/// `run.json` made that run invisible everywhere: not in `magi list`, not in
4162/// `runs_unreadable`, not on the phone, so nothing could report it and no
4163/// route could clear it. `88c0` sat like that for two days. Unreadable is
4164/// counted, never hidden - the readers already say why each one cannot be
4165/// read, and `fold_unreadable` is how a record like this leaves.
4166pub fn list_ids() -> Vec<String> {
4167 list_ids_in(&runs_root())
4168}
4169
4170/// [`list_ids`] against an explicit runs root, for callers (and tests) that
4171/// must not depend on the process-global home.
4172pub fn list_ids_in(root: &Path) -> Vec<String> {
4173 let mut ids: Vec<String> = std::fs::read_dir(root)
4174 .into_iter()
4175 .flatten()
4176 .flatten()
4177 .filter(|e| e.path().is_dir())
4178 .map(|e| e.file_name().to_string_lossy().into_owned())
4179 .filter(|name| is_run_id(name))
4180 .collect();
4181 // Ids start with a sortable timestamp.
4182 ids.sort_unstable_by(|a, b| b.cmp(a));
4183 ids
4184}
4185
4186/// Does `name` have the shape [`new_id`] mints: `YYYYMMDD-HHMMSS-xxxx`?
4187///
4188/// The test for "this directory is a run", so a stray folder under
4189/// `<home>/runs` is not reported as a broken run.
4190///
4191/// The tag is checked for length and for being alphanumeric, not for being
4192/// hex: real ids are hex, but fixtures across this crate name runs
4193/// `...-dead` / `...-gone` / `...-once`, and a predicate that disowned those
4194/// would be asserting the fixtures' spelling rather than the shape.
4195pub fn is_run_id(name: &str) -> bool {
4196 let mut parts = name.split('-');
4197 let (Some(day), Some(time), Some(tag), None) =
4198 (parts.next(), parts.next(), parts.next(), parts.next())
4199 else {
4200 return false;
4201 };
4202 day.len() == 8
4203 && day.bytes().all(|b| b.is_ascii_digit())
4204 && time.len() == 6
4205 && time.bytes().all(|b| b.is_ascii_digit())
4206 && tag.len() == 4
4207 && tag.bytes().all(|b| b.is_ascii_alphanumeric())
4208}
4209
4210/// Expand an id prefix to exactly one run id.
4211pub fn resolve_id(prefix: &str) -> Result<String> {
4212 // A whole id names its directory, readable state or not: the run whose
4213 // `run.json` never landed still has to be reachable by `magi show` and
4214 // by the fold route, which is the only way its record ever leaves.
4215 if is_run_id(prefix) && run_dir(prefix).is_dir() {
4216 return Ok(prefix.to_owned());
4217 }
4218 let hits: Vec<String> = list_ids()
4219 .into_iter()
4220 .filter(|id| id.starts_with(prefix) || id.ends_with(prefix))
4221 .collect();
4222 match hits.len() {
4223 1 => Ok(hits.into_iter().next().expect("exactly one hit")),
4224 0 => bail!("no run matches `{prefix}`"),
4225 _ => bail!(
4226 "`{prefix}` matches {} runs: {}",
4227 hits.len(),
4228 hits.join(", ")
4229 ),
4230 }
4231}
4232
4233/// The most recent run, if any.
4234pub fn latest_id() -> Option<String> {
4235 list_ids().into_iter().next()
4236}
4237
4238/// An unreserved `YYYYMMDD-HHMMSS-xxxx` candidate, sortable and branch-safe.
4239/// Fresh entropy is independent of the blind seed. Entropy alone cannot prevent
4240/// collisions: production creation must use `RunState::reserve` before the id
4241/// escapes, reserving both the full id and its branch/worktree suffix on disk.
4242fn new_id() -> String {
4243 let stamp = Zoned::now().strftime("%Y%m%d-%H%M%S");
4244 let entropy = crate::rng::entropy();
4245 format!("{stamp}-{:04x}", (entropy ^ (entropy >> 32)) & 0xffff)
4246}
4247
4248/// Keep the last `max` bytes of `text`, on a line boundary.
4249pub fn tail(text: &str, max: usize) -> String {
4250 if text.len() <= max {
4251 return text.to_owned();
4252 }
4253 let mut cut = text.len() - max;
4254 while cut < text.len() && !text.is_char_boundary(cut) {
4255 cut += 1;
4256 }
4257 let slice = &text[cut..];
4258 let start = slice.find('\n').map_or(0, |i| i + 1);
4259 format!(
4260 "[... {} earlier bytes omitted ...]\n{}",
4261 cut,
4262 &slice[start..]
4263 )
4264}
4265
4266/// Bytes of verification output recorded and handed to fixers/reviewers.
4267pub const VERIFY_SUMMARY: usize = 32_768;
4268
4269/// A backtrace frame line (` 41: 0x102e80de0 - <path>::{closure#0}` or
4270/// ` 3: std::panicking::begin_panic`), or the `at file:line` line under one.
4271/// Deliberately narrow: a frame needs a number, a colon and either an address
4272/// or a path, so ordinary `12: something` output is never dropped.
4273fn is_frame(line: &str, after_frame: bool) -> bool {
4274 let t = line.trim_start();
4275 if after_frame && t.starts_with("at ") {
4276 return true;
4277 }
4278 let digits = t.bytes().take_while(u8::is_ascii_digit).count();
4279 if digits == 0 || !t[digits..].starts_with(": ") {
4280 return false;
4281 }
4282 let rest = t[digits + 2..].trim_start();
4283 rest.starts_with("0x") || rest.contains("::")
4284}
4285
4286/// Priority (lower first) and following context (assertion text, `left`/`right`).
4287fn trigger_context(line: &str) -> Option<(u8, usize)> {
4288 // Match colored nextest markers without changing the stored evidence.
4289 let mut plain = String::new();
4290 let mut chars = line.chars();
4291 while let Some(c) = chars.next() {
4292 if c == '\x1b' && chars.clone().next() == Some('[') {
4293 chars.next();
4294 for c in chars.by_ref() {
4295 if ('@'..='~').contains(&c) {
4296 break;
4297 }
4298 }
4299 } else {
4300 plain.push(c);
4301 }
4302 }
4303 let t = plain.trim();
4304 if t.starts_with("[full output:") || t.starts_with("[full output could not be saved:") {
4305 Some((0, 0))
4306 } else if t.contains("panicked at") {
4307 Some((0, 6))
4308 } else if (t.starts_with("---- ") && t.ends_with(" ----"))
4309 || t.starts_with("--- STDERR:")
4310 || t.starts_with("--- STDOUT:")
4311 {
4312 Some((1, 3))
4313 } else if t.starts_with("FAIL ") || t.contains("FAIL [") {
4314 Some((1, 4))
4315 } else if t.starts_with("error:")
4316 || t.starts_with("error[")
4317 || t.starts_with("failures:")
4318 || t.contains("test result: FAILED")
4319 {
4320 Some((2, 4))
4321 } else {
4322 None
4323 }
4324}
4325
4326fn clip_line(line: &str, max: usize) -> &str {
4327 if line.len() <= max {
4328 return line;
4329 }
4330 let mut cut = max;
4331 while !line.is_char_boundary(cut) {
4332 cut -= 1;
4333 }
4334 &line[..cut]
4335}
4336
4337/// Summarise verification output to roughly `max` bytes, keeping the reason a
4338/// command failed. A plain tail is useless for a failing test: the panic
4339/// message sits hundreds of KB before the end, behind a backtrace. So:
4340///
4341/// 1. backtrace frame lines are dropped (counted in the header);
4342/// 2. if that already fits, the rest is returned whole;
4343/// 3. otherwise keep excerpts, each from a failure marker (`panicked at`,
4344/// `---- test stdout ----`, nextest `FAIL`/`STDERR`, `error:`, ...) through
4345/// a few following lines (the assertion and `left`/`right`), share the
4346/// budget evenly between selected excerpts. Select panics first, then test
4347/// stdout/stderr and nextest failure blocks, then generic diagnostics: noisy
4348/// compiler errors must not crowd out the test failure reason. Within each
4349/// priority keep earlier excerpts, then render in original order and append
4350/// the final tail (where `test result:` lives).
4351///
4352/// Adjacent excerpts merge only within the same priority and while small:
4353/// a long stdout line must not
4354/// consume the budget of a following panic anchor. Short output is returned
4355/// unchanged. The full text belongs in an artifact.
4356pub fn summarize_verify(text: &str, max: usize) -> String {
4357 if text.len() <= max {
4358 return text.to_owned();
4359 }
4360 // Tiny callers cannot fit the explanatory header. Respect their exact
4361 // byte bound, including UTF-8 boundaries, without a larger tail marker.
4362 if max < 256 {
4363 return clip_line(text, max).to_owned();
4364 }
4365 let mut kept: Vec<&str> = Vec::new();
4366 let mut dropped = 0usize;
4367 let mut prev_frame = false;
4368 for line in text.lines() {
4369 let frame = is_frame(line, prev_frame);
4370 if frame {
4371 dropped += 1;
4372 } else {
4373 kept.push(line);
4374 }
4375 prev_frame = frame;
4376 }
4377 let total: usize = kept.iter().map(|l| l.len() + 1).sum();
4378 let note = if dropped > 0 {
4379 format!(" ({dropped} backtrace frame line(s) dropped)")
4380 } else {
4381 String::new()
4382 };
4383 let overhead = 300;
4384 if total + overhead <= max {
4385 return format!("[... output reduced{note} ...]\n{}\n", kept.join("\n"));
4386 }
4387 // The tail comes first so that excerpts never repeat it.
4388 let tail_budget = (max / 4).min(4_096);
4389 let mut tail_start = kept.len();
4390 let mut used = 0usize;
4391 while tail_start > 0 && used + kept[tail_start - 1].len() < tail_budget {
4392 tail_start -= 1;
4393 used += kept[tail_start].len() + 1;
4394 }
4395 // Excerpts as merged half-open line ranges.
4396 let mut ranges: Vec<(usize, usize, u8)> = Vec::new();
4397 for (i, line) in kept[..tail_start].iter().enumerate() {
4398 if let Some((priority, after)) = trigger_context(line) {
4399 let end = (i + 1 + after).min(tail_start);
4400 match ranges.last_mut() {
4401 Some(last)
4402 if priority == last.2
4403 && i <= last.1
4404 && end - last.0 <= 20
4405 && kept[last.0..end].iter().map(|l| l.len() + 1).sum::<usize>() <= 1024 =>
4406 {
4407 last.1 = last.1.max(end);
4408 }
4409 _ => ranges.push((i, end, priority)),
4410 }
4411 }
4412 }
4413 let budget = max.saturating_sub(used + overhead);
4414 let shown = ranges.len().min((budget / 240).max(1));
4415 ranges.sort_by_key(|&(start, _, priority)| (priority, start));
4416 let mut selected = ranges[..shown].to_vec();
4417 selected.sort_by_key(|&(start, _, _)| start);
4418 let per = budget / shown.max(1);
4419 let mut body = String::new();
4420 for &(a, b, _) in &selected {
4421 let mut block = String::new();
4422 for line in &kept[a..b] {
4423 let remaining = per.saturating_sub(block.len() + 1);
4424 if remaining == 0 {
4425 break;
4426 }
4427 let line = clip_line(line, 600.min(remaining));
4428 block.push_str(line);
4429 block.push('\n');
4430 }
4431 body.push_str(&block);
4432 body.push_str("[...]\n");
4433 }
4434 let hidden = ranges.len() - shown;
4435 let more = if hidden > 0 {
4436 format!("; {hidden} more excerpt(s) not shown")
4437 } else {
4438 String::new()
4439 };
4440 let tail_text: String = kept[tail_start..].iter().flat_map(|l| [*l, "\n"]).collect();
4441 let out = format!(
4442 "[... output reduced from {} bytes{note}; {shown} failure excerpt(s) kept{more}, then the end ...]\n{body}{tail_text}",
4443 text.len(),
4444 );
4445 if out.len() > max {
4446 return clip_line(&out, max).to_owned();
4447 }
4448 out
4449}
4450
4451/// Reserve a fresh verification artifact atomically, so concurrent writes,
4452/// retries and resumes cannot overwrite earlier evidence.
4453pub fn write_verification_artifact(run: &RunState, stem: &str, body: &str) -> Result<String> {
4454 use std::io::Write as _;
4455 let dir = run.dir().join("artifacts");
4456 std::fs::create_dir_all(&dir)?;
4457 for sequence in 1.. {
4458 let name = format!("{stem}-{sequence}.out");
4459 match std::fs::OpenOptions::new()
4460 .write(true)
4461 .create_new(true)
4462 .open(dir.join(&name))
4463 {
4464 Ok(mut file) => {
4465 file.write_all(body.as_bytes())
4466 .with_context(|| format!("write artifacts/{name}"))?;
4467 return Ok(name);
4468 }
4469 Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
4470 Err(e) => return Err(e).with_context(|| format!("create artifacts/{name}")),
4471 }
4472 }
4473 unreachable!()
4474}
4475
4476/// Path of a run artifact.
4477pub fn artifact_path(run: &RunState, name: &str) -> PathBuf {
4478 run.dir().join("artifacts").join(name)
4479}
4480
4481/// Write an artifact, creating the directory if needed.
4482pub fn write_artifact(run: &RunState, name: &str, body: &str) -> Result<PathBuf> {
4483 let path = artifact_path(run, name);
4484 if let Some(parent) = path.parent() {
4485 std::fs::create_dir_all(parent).with_context(|| format!("create {}", parent.display()))?;
4486 }
4487 std::fs::write(&path, body).with_context(|| format!("write {}", path.display()))?;
4488 Ok(path)
4489}
4490
4491/// Read an artifact back, e.g. a stored patch on resume.
4492pub fn read_artifact(run: &RunState, name: &str) -> Option<String> {
4493 std::fs::read_to_string(artifact_path(run, name)).ok()
4494}
4495
4496#[cfg(test)]
4497mod tests {
4498 #[test]
4499 fn summarize_verify_preserves_failure_context_and_bounds() {
4500 let mut text = String::from("[full output: artifacts/gate-1.out]\n");
4501 for name in ["first", "second"] {
4502 text.push_str(&format!("---- {name} stdout ----\nmy test output\n"));
4503 text.push_str(&format!("thread '{name}' panicked at tests/check.rs:42:9:\nassertion `left == right` failed\n left: 1\n right: 2\n"));
4504 for frame in 0..4000 {
4505 text.push_str(&format!(
4506 " {frame}: 0x102e80de0 - backtrace frame with 日本語\n"
4507 ));
4508 }
4509 }
4510 text.push_str("---- second stderr ----\nsecond test stderr\n");
4511 text.push_str(&"unrelated output\n".repeat(1000));
4512 text.push_str(
4513 "\x1b[31mFAIL [0.01s] suite third\x1b[0m\n--- STDOUT: ---\nthird test stdout\n",
4514 );
4515 text.push_str(&"stdout noise\n".repeat(10000));
4516 text.push_str("--- STDERR: ---\nthird test stderr\n");
4517 text.push_str("thread 'third' panicked at test.rs:1:\nthird assertion\n");
4518 text.push_str(&"backtrace noise\n".repeat(10000));
4519 text.push_str("test result: FAILED. 0 passed; 3 failed\n");
4520 let summary = summarize_verify(&text, 32 * 1024);
4521 assert!(summary.len() <= 32 * 1024);
4522 for expected in [
4523 "thread 'first' panicked at",
4524 "thread 'second' panicked at",
4525 "thread 'third' panicked at",
4526 "my test output",
4527 "second test stderr",
4528 "FAIL [0.01s] suite third",
4529 "third test stdout",
4530 "third test stderr",
4531 "panicked at tests/check.rs:42:9",
4532 "left: 1",
4533 "right: 2",
4534 "third assertion",
4535 "test result: FAILED",
4536 "artifacts/gate-1.out",
4537 ] {
4538 assert!(summary.contains(expected), "missing {expected}: {summary}");
4539 }
4540 assert_eq!(summarize_verify(&summary, 32 * 1024), summary);
4541 let compact = summarize_verify(&summary, 2000);
4542 assert!(compact.len() <= 2000);
4543 assert!(compact.contains("panicked at"));
4544 assert!(compact.contains("artifacts/gate-1.out"));
4545 assert_eq!(summarize_verify("short 日本語\n", 1024), "short 日本語\n");
4546 }
4547
4548 #[test]
4549 fn summarize_verify_prioritizes_late_test_failures_over_diagnostics() {
4550 let mut text = String::new();
4551 for _ in 0..130 {
4552 text.push_str("error: diagnostic\n");
4553 text.push_str(&"ordinary build log\n".repeat(21));
4554 }
4555 text.push_str("---- late_test stdout ----\ntest stdout summary\n");
4556 text.push_str("thread 'late_test' panicked at tests/late.rs:42:9:\nassertion `left == right` failed\n left: 1\n right: 2\n");
4557 text.push_str("--- STDERR: ---\ntest stderr summary\n");
4558 text.push_str(&"ordinary test log\n".repeat(4000));
4559 text.push_str("test result: FAILED\n");
4560
4561 let summary = summarize_verify(&text, 32 * 1024);
4562 assert!(summary.len() <= 32 * 1024);
4563 for expected in [
4564 "---- late_test stdout ----",
4565 "test stdout summary",
4566 "panicked at tests/late.rs:42:9:",
4567 "assertion `left == right` failed",
4568 "left: 1",
4569 "right: 2",
4570 "test stderr summary",
4571 "test result: FAILED",
4572 ] {
4573 assert!(summary.contains(expected), "missing {expected}");
4574 }
4575 }
4576
4577 #[test]
4578 fn summarize_verify_reports_overflow_and_handles_long_utf8_lines() {
4579 let text = (0..1000)
4580 .map(|i| {
4581 format!(
4582 "thread '{i}' panicked at test.rs:1:\n{}\n",
4583 "あ".repeat(2000)
4584 )
4585 })
4586 .collect::<String>();
4587 for max in (0..=256).chain([800, 2000, 32 * 1024]) {
4588 let summary = summarize_verify(&text, max);
4589 assert!(summary.len() <= max);
4590 if max >= 256 {
4591 assert!(summary.contains("more excerpt(s) not shown"));
4592 }
4593 }
4594 let compiler = format!(
4595 "error[E0063]: missing field\n{}done",
4596 "noise\n".repeat(20000)
4597 );
4598 assert!(summarize_verify(&compiler, 2000).contains("error[E0063]"));
4599 }
4600
4601 #[test]
4602 fn verification_artifacts_reserve_names_atomically() {
4603 pin_test_home();
4604 let state = pass_state();
4605 let names = std::thread::scope(|scope| {
4606 let handles: Vec<_> = (0..8)
4607 .map(|i| {
4608 let state = &state;
4609 scope.spawn(move || {
4610 let body = format!("output {i}");
4611 let name = write_verification_artifact(state, "gate", &body).unwrap();
4612 (name, body)
4613 })
4614 })
4615 .collect();
4616 handles
4617 .into_iter()
4618 .map(|h| h.join().unwrap())
4619 .collect::<Vec<_>>()
4620 });
4621 let unique: BTreeSet<_> = names.iter().map(|(name, _)| name).collect();
4622 assert_eq!(unique.len(), names.len());
4623 for (name, body) in names {
4624 assert_eq!(read_artifact(&state, &name).unwrap(), body);
4625 }
4626 }
4627
4628 #[test]
4629 fn quota_loss_from_report_preserves_machine_failure_details() {
4630 let report = crate::agent::Quota {
4631 reset: Some("in 1h".into()),
4632 cause: crate::agent::QuotaCause::Authentication,
4633 agent: "alpha".into(),
4634 };
4635 let loss = QuotaLoss::from_report("advisor-1".into(), "advise", Some(&report));
4636 assert_eq!(loss.seat, "advisor-1");
4637 assert_eq!(loss.node, "advise");
4638 assert_eq!(loss.reset, report.reset);
4639 assert_eq!(loss.cause, report.cause);
4640 assert_eq!(loss.agent, report.agent);
4641
4642 let absent = QuotaLoss::from_report("advisor-2".into(), "advise", None);
4643 assert_eq!(absent.reset, None);
4644 assert_eq!(absent.cause, crate::agent::QuotaCause::UsageLimit);
4645 assert!(absent.agent.is_empty());
4646 }
4647
4648 fn pass_state() -> RunState {
4649 RunState::new(
4650 PathBuf::from("/repo"),
4651 "main".to_owned(),
4652 "0123456789abcdef".to_owned(),
4653 "Do it".to_owned(),
4654 Config::default(),
4655 )
4656 }
4657
4658 #[test]
4659 fn reserving_runs_retries_full_and_short_collisions_without_touching_the_first() {
4660 let home = tempfile::tempdir().unwrap();
4661 let first_id = "20260101-000000-abcd";
4662 let ids = crate::id_reserve::sequence(&[
4663 first_id,
4664 first_id,
4665 "20260102-000000-abcd",
4666 "20260101-000000-1234",
4667 ]);
4668 let mut first = pass_state();
4669 first.reserve_with(home.path(), &ids).unwrap();
4670 let first_dir = home.path().join("runs").join(&first.id);
4671 std::fs::create_dir(first_dir.join("artifacts")).unwrap();
4672 std::fs::write(first_dir.join("artifacts/keep"), b"original artifact").unwrap();
4673 let before = std::fs::read(first_dir.join("run.json")).unwrap();
4674 let mut second = pass_state();
4675 second.instruction = "independent".into();
4676 second.reserve_with(home.path(), &ids).unwrap();
4677 assert_eq!(first.id, first_id);
4678 assert_eq!(second.id, "20260101-000000-1234");
4679 assert_ne!(first.branch_for('A'), second.branch_for('A'));
4680 assert_eq!(std::fs::read(first_dir.join("run.json")).unwrap(), before);
4681 assert_eq!(
4682 std::fs::read(first_dir.join("artifacts/keep")).unwrap(),
4683 b"original artifact"
4684 );
4685 assert_eq!(
4686 RunState::load_under(&second.id, home.path())
4687 .unwrap()
4688 .instruction,
4689 "independent"
4690 );
4691 assert!(!home.path().join("runs/20260102-000000-abcd").exists());
4692 let stuck = crate::id_reserve::IdSource::custom(|| "20260101-000000-abcd".into());
4693 assert!(
4694 pass_state()
4695 .reserve_with(home.path(), &stuck)
4696 .unwrap_err()
4697 .to_string()
4698 .contains("256 attempts")
4699 );
4700 assert_eq!(std::fs::read(first_dir.join("run.json")).unwrap(), before);
4701 }
4702
4703 #[test]
4704 fn reserving_a_run_fails_when_the_store_cannot_be_created() {
4705 let home = tempfile::tempdir().unwrap();
4706 std::fs::write(home.path().join("runs"), "not a directory").unwrap();
4707 assert!(pass_state().reserve_under(home.path()).is_err());
4708 }
4709
4710 #[test]
4711 fn passes_append_and_a_resume_never_rewrites_an_earlier_cause() {
4712 let mut s = pass_state();
4713 s.begin_pass();
4714 assert!(!s.passes[0].resumed);
4715 s.end_pass_parked(ParkCause::Upgrade {
4716 from: "0.1.0".to_owned(),
4717 to: Some("0.1.1".to_owned()),
4718 });
4719 s.begin_pass();
4720 s.end_pass_parked(ParkCause::Operator);
4721 // A second request for the same boundary does not relabel it.
4722 s.end_pass_parked(ParkCause::Question);
4723 s.begin_pass();
4724 assert_eq!(s.passes.len(), 3);
4725 assert!(s.passes[1].resumed);
4726 assert_eq!(
4727 s.passes[0].end,
4728 Some(PassEnd::Parked {
4729 cause: ParkCause::Upgrade {
4730 from: "0.1.0".to_owned(),
4731 to: Some("0.1.1".to_owned()),
4732 }
4733 })
4734 );
4735 assert_eq!(
4736 s.passes[1].end,
4737 Some(PassEnd::Parked {
4738 cause: ParkCause::Operator
4739 })
4740 );
4741 assert_eq!(s.passes[2].end, None);
4742 }
4743
4744 #[test]
4745 fn a_pass_left_open_is_closed_as_unrecorded_by_the_next() {
4746 let mut s = pass_state();
4747 s.begin_pass();
4748 s.begin_pass();
4749 assert_eq!(s.passes[0].end, Some(PassEnd::Unrecorded));
4750 assert!(s.passes[0].ended_at.is_some());
4751 assert_eq!(s.passes[1].end, None);
4752 }
4753
4754 #[test]
4755 fn a_state_written_before_passes_loads_with_none() {
4756 let s = pass_state();
4757 let mut v = serde_json::to_value(&s).unwrap();
4758 v.as_object_mut().unwrap().remove("passes");
4759 let back: RunState = serde_json::from_value(v).unwrap();
4760 assert!(back.passes.is_empty());
4761 }
4762 #[test]
4763 fn test_home_is_private_stable_and_unique_per_process() {
4764 // Child mode: report this process's home and stop.
4765 if std::env::var_os("MAGI_HOME_PROBE").is_some() {
4766 println!("HOME={}", super::test_home().display());
4767 return;
4768 }
4769 let a = super::test_home();
4770 assert_eq!(a, super::test_home());
4771 assert!(a.is_dir() && a.starts_with(std::env::temp_dir()));
4772 let probe = || {
4773 let out = std::process::Command::new(std::env::current_exe().unwrap())
4774 .args([
4775 "--exact",
4776 "run::tests::test_home_is_private_stable_and_unique_per_process",
4777 "--nocapture",
4778 "--test-threads=1",
4779 ])
4780 .env("MAGI_HOME_PROBE", "1")
4781 .quiet()
4782 .output()
4783 .unwrap();
4784 String::from_utf8_lossy(&out.stdout)
4785 .lines()
4786 .find_map(|l| l.split_once("HOME=").map(|(_, h)| h.to_owned()))
4787 .expect("child reported a home")
4788 };
4789 let (b, c) = (probe(), probe());
4790 assert_ne!(b, c, "two processes must never share a unit-test home");
4791 assert_ne!(b, a.display().to_string());
4792 }
4793
4794 #[test]
4795 fn no_test_pins_a_fixed_temp_path_as_the_home() {
4796 let root = std::env::var_os("CARGO_MANIFEST_DIR")
4797 .map(PathBuf::from)
4798 .unwrap_or_else(|| PathBuf::from(env!("CARGO_MANIFEST_DIR")));
4799 let needle = ["set_home(std::env::temp_dir()", ".join(\"magi-"].concat();
4800 for e in std::fs::read_dir(root.join("src")).unwrap() {
4801 let p = e.unwrap().path();
4802 if p.extension().and_then(|x| x.to_str()) != Some("rs") {
4803 continue;
4804 }
4805 let text = std::fs::read_to_string(&p).unwrap();
4806 assert!(
4807 !text.contains(&needle),
4808 "{} pins a fixed temp home; use run::pin_test_home()",
4809 p.display()
4810 );
4811 }
4812 }
4813
4814 use super::*;
4815
4816 fn state() -> RunState {
4817 RunState::new(
4818 PathBuf::from("/repo"),
4819 "main".to_owned(),
4820 "abc1234def".to_owned(),
4821 "add retries".to_owned(),
4822 Config::default(),
4823 )
4824 }
4825
4826 #[test]
4827 fn task_public_head_contains_only_the_task_identity() {
4828 let mut run = state();
4829 run.origin = Some(Origin::queue("abcd-1234"));
4830 assert_eq!(run.task_pr_branch().as_deref(), Some("magi/task-abcd-1234"));
4831 assert_ne!(run.task_pr_branch().unwrap(), run.branch_for('A'));
4832 run.origin = Some(Origin::queue("bad..task"));
4833 assert!(run.task_pr_branch().is_none());
4834 run.origin = Some(Origin::queue("abcd-1234"));
4835 run.reviewed_commits = Some(Vec::new());
4836 assert!(run.task_pr_branch().is_none());
4837 run.reviewed_commits = None;
4838 run.origin = Some(Origin::operator());
4839 assert!(run.task_pr_branch().is_none());
4840 }
4841
4842 #[test]
4843 fn task_public_head_keeps_its_saved_repository_assignment() {
4844 let mut run = state();
4845 run.origin = Some(Origin::queue("task-id"));
4846 assert_eq!(run.task_pr_branch().as_deref(), Some("magi/task-task-id"));
4847 run.task_assignment = 1;
4848 assert_eq!(
4849 run.task_pr_branch().as_deref(),
4850 Some("magi/task-task-id-assignment-1")
4851 );
4852 run.task_assignment = 2;
4853 let saved = serde_json::to_value(&run).unwrap();
4854 let restored: RunState = serde_json::from_value(saved.clone()).unwrap();
4855 assert_eq!(
4856 restored.task_pr_branch().as_deref(),
4857 Some("magi/task-task-id-assignment-2")
4858 );
4859 let mut legacy = saved;
4860 legacy["schema"] = serde_json::json!(16);
4861 legacy.as_object_mut().unwrap().remove("task_assignment");
4862 let legacy: RunState = migrate_schema(serde_json::from_value(legacy).unwrap()).unwrap();
4863 assert_eq!(
4864 legacy.task_pr_branch().as_deref(),
4865 Some("magi/task-task-id")
4866 );
4867 }
4868
4869 #[test]
4870 fn review_run_keeps_the_task_public_head_only_when_inherited() {
4871 let mut run = state();
4872 run.origin = Some(Origin::queue("abcd-1234"));
4873 run.reviewed_commits = Some(Vec::new());
4874 let mut cand = |branch: &str| {
4875 run.candidates = vec![Candidate {
4876 index: 0,
4877 label: 'A',
4878 agent: "(existing branch)".to_owned(),
4879 branch: branch.to_owned(),
4880 worktree: PathBuf::from("/w"),
4881 summary: String::new(),
4882 stat: String::new(),
4883 files: 1,
4884 commits: 1,
4885 empty: false,
4886 failed: None,
4887 verified_noop: None,
4888 duration_ms: 0,
4889 folded: false,
4890 }];
4891 };
4892 cand("magi/ab12/A");
4893 run.tally = Some(Tally {
4894 first_choice: BTreeMap::from([('A', 0)]),
4895 borda: BTreeMap::new(),
4896 winner: 'A',
4897 rankings: 0,
4898 unanimous_initial: false,
4899 deliberated: false,
4900 changed_votes: 0,
4901 unanimous_final: false,
4902 tie_break: None,
4903 judges: 0,
4904 present: 0,
4905 quorum: 0,
4906 met_quorum: true,
4907 uncontested: None,
4908 });
4909 // A legacy candidate-branch PR: nothing inherited, keep its own head.
4910 assert!(run.task_pr_branch().is_none());
4911 run.pr_head = Some("magi/task-abcd-1234".to_owned());
4912 assert_eq!(run.task_pr_branch().as_deref(), Some("magi/task-abcd-1234"));
4913 // A head that is not this task's is never followed.
4914 run.pr_head = Some("magi/task-other".to_owned());
4915 assert!(run.task_pr_branch().is_none());
4916 }
4917
4918 #[test]
4919 fn superseded_is_terminal_but_not_resumable() {
4920 assert!(RunStatus::Superseded.done());
4921 assert!(!RunStatus::Superseded.resumable());
4922 assert_eq!(RunStatus::Superseded.as_str(), "superseded");
4923 assert!(RunStatus::AlreadyInBase.done());
4924 assert!(!RunStatus::AlreadyInBase.resumable());
4925 assert_eq!(RunStatus::AlreadyInBase.as_str(), "already_in_base");
4926 }
4927
4928 #[test]
4929 fn load_under_reads_back_exactly_what_save_under_wrote_at_an_explicit_home() {
4930 // Both rooted at an explicit `home` rather than the process-global
4931 // one - a caller with its own `home` (a test fixture, a housekeeping
4932 // pass) must round-trip through exactly that directory, never
4933 // through whichever home some other test in the same binary pinned
4934 // into the global `OnceLock` first.
4935 let dir = tempfile::tempdir().unwrap();
4936 let mut original = state();
4937 original.id = "20260101-000000-load".to_owned();
4938 original.status = RunStatus::Blocked;
4939 original.save_under(dir.path()).unwrap();
4940
4941 let reloaded = RunState::load_under(&original.id, dir.path()).unwrap();
4942 assert_eq!(reloaded.id, original.id);
4943 assert_eq!(reloaded.status, RunStatus::Blocked);
4944
4945 assert!(
4946 RunState::load_under("20260101-000000-none", dir.path()).is_err(),
4947 "an id with nothing saved under this home must not silently read something else"
4948 );
4949 }
4950
4951 #[test]
4952 fn verification_history_legacy_metadata_remains_unknown() {
4953 let history: VerificationEvidence = serde_json::from_value(serde_json::json!({
4954 "gate_head": "old-head",
4955 "gate_ran": true,
4956 "gate": [],
4957 "e2e": null
4958 }))
4959 .unwrap();
4960 assert!(history.superseded_by.is_none());
4961 assert!(history.archived_at.is_none());
4962 assert!(history.fixes_spent.is_none());
4963 assert_eq!(history.gate_head.as_deref(), Some("old-head"));
4964 assert!(history.gate_ran);
4965 }
4966
4967 #[test]
4968 fn resolve_home_prefers_the_pin_then_the_env_var() {
4969 let pinned = PathBuf::from("/pinned");
4970 assert_eq!(
4971 resolve_home(Some(pinned.clone()), Some("/env".into())),
4972 pinned,
4973 "a pin wins even over MAGI_HOME"
4974 );
4975 assert_eq!(
4976 resolve_home(None, Some("/env".into())),
4977 PathBuf::from("/env")
4978 );
4979 }
4980
4981 #[test]
4982 #[should_panic(expected = "run::set_home()")]
4983 fn resolve_home_refuses_to_fall_back_to_the_operators_real_home() {
4984 // Neither override present is exactly the state a test reaches by
4985 // forgetting `set_home`/`MAGI_HOME` - the accident that put three
4986 // broken fixture runs into the operator's real history. Asserted
4987 // against the pure decision directly, not `home()` itself, because
4988 // `HOME` is a process-wide `OnceLock` another test may have already
4989 // set - this must not depend on test execution order.
4990 resolve_home(None, None);
4991 }
4992
4993 #[test]
4994 fn a_run_is_named_by_shape_so_a_state_less_directory_is_still_a_run() {
4995 // The shape `new_id` mints. A directory answering to it is a run even
4996 // with no readable `run.json`: that is how a save that ran out of
4997 // disk stays visible instead of vanishing from every listing.
4998 assert!(is_run_id(&new_id()));
4999 assert!(is_run_id("20260904-014540-88c0"));
5000 // Not runs: a stray folder, a truncated id, a non-hex tag, and an id
5001 // with an extra segment (a worktree label, say).
5002 assert!(!is_run_id("scratch"));
5003 assert!(!is_run_id("20260904-014540"));
5004 assert!(!is_run_id("20260904-014540-88c0f"));
5005 assert!(!is_run_id("2026090x-014540-88c0"));
5006 assert!(!is_run_id("20260904-014540-88c0-A"));
5007 }
5008
5009 #[test]
5010 fn ids_are_sortable_and_short_suffixed() {
5011 let s = state();
5012 let parts: Vec<&str> = s.id.split('-').collect();
5013 assert_eq!(parts.len(), 3);
5014 assert_eq!(parts[0].len(), 8);
5015 assert_eq!(parts[1].len(), 6);
5016 assert_eq!(parts[2].len(), 4);
5017 assert_eq!(s.short(), parts[2]);
5018 }
5019
5020 #[test]
5021 fn branch_names_carry_the_label_not_the_author() {
5022 let s = state();
5023 let b = s.branch_for('B');
5024 assert_eq!(b, format!("magi/{}/B", s.short()));
5025 assert!(!b.contains("claude"));
5026 }
5027
5028 /// A pinned seed reproduces the blind decisions. It must **not** reproduce
5029 /// the run's identity.
5030 ///
5031 /// `assert_eq!(a.short(), b.short())` used to stand where the last
5032 /// assertion is now, and it was pinning the defect: with the id's suffix
5033 /// derived from the seed, two runs started in the same second were the
5034 /// same run as far as the filesystem was concerned - one directory, one
5035 /// `artifacts/`, one set of candidate worktrees. `tests/common` pins a
5036 /// seed for every integration test, so on Linux, where the suite is fast,
5037 /// two tests in `graph_dropped_stream` shared a directory and one read the
5038 /// other's artifact.
5039 #[test]
5040 fn a_pinned_seed_is_reproducible_but_never_the_run_id() {
5041 let mut cfg = Config::default();
5042 cfg.blind.seed = Some(1234);
5043 let a = RunState::new(
5044 PathBuf::from("/r"),
5045 "main".to_owned(),
5046 "c".to_owned(),
5047 "t".to_owned(),
5048 cfg.clone(),
5049 );
5050 let b = RunState::new(
5051 PathBuf::from("/r"),
5052 "main".to_owned(),
5053 "c".to_owned(),
5054 "t".to_owned(),
5055 cfg,
5056 );
5057 // What the seed is for: the same shuffles, run after run.
5058 assert_eq!(a.seed, 1234);
5059 assert_eq!(a.seed, b.seed);
5060 // What it is not for. Two runs are two runs, in the same second or
5061 // not, and everything keyed on the id depends on that.
5062 assert_ne!(
5063 a.id, b.id,
5064 "two runs sharing an id share a directory, artifacts and worktrees"
5065 );
5066 }
5067
5068 #[test]
5069 fn status_terminality() {
5070 assert!(RunStatus::Merged.done());
5071 assert!(RunStatus::Blocked.done());
5072 assert!(!RunStatus::Reviewing.done());
5073 }
5074
5075 fn overrun_seat(now: Timestamp, elapsed_secs: i64, timeout_secs: u64) -> ActiveSeat {
5076 ActiveSeat {
5077 node: "implement".to_owned(),
5078 started_at: now - jiff::SignedDuration::new(elapsed_secs, 0),
5079 timeout_secs,
5080 attempt: 0,
5081 task: None,
5082 command: None,
5083 index: None,
5084 total: None,
5085 }
5086 }
5087
5088 #[test]
5089 fn active_all_overrun_requires_every_seat_past_its_own_timeout() {
5090 let mut s = state();
5091 let now = Timestamp::now();
5092 assert!(
5093 !s.active_all_overrun(now),
5094 "nothing active is not evidence of anything"
5095 );
5096
5097 s.active
5098 .insert("impl-A".to_owned(), overrun_seat(now, 21_000, 3_600));
5099 assert!(
5100 s.active_all_overrun(now),
5101 "21000s elapsed against a 3600s budget"
5102 );
5103
5104 // A seat still well within its own budget means the run is not
5105 // provably dead, however far its sibling has overrun.
5106 s.active
5107 .insert("impl-B".to_owned(), overrun_seat(now, 0, 3_600));
5108 assert!(!s.active_all_overrun(now));
5109 }
5110
5111 /// A schema-11 run that ended Blocked cannot be pinned by a daemon pid
5112 /// that is still alive; one still mid-walk keeps asking the pid.
5113 #[test]
5114 fn migrating_schema_11_marks_only_ended_runs_as_exited() {
5115 for (status, exited) in [
5116 (RunStatus::Blocked, true),
5117 (RunStatus::Failed, true),
5118 (RunStatus::Stalled, true),
5119 (RunStatus::Landing, true),
5120 (RunStatus::Reviewing, false),
5121 ] {
5122 let mut s = state();
5123 s.schema = 11;
5124 s.status = status;
5125 let m = migrate_schema(s).unwrap();
5126 assert_eq!(m.schema, SCHEMA);
5127 assert_eq!(m.driver_exited, exited, "{status:?}");
5128 }
5129 }
5130
5131 /// A driver that recorded its own exit reads dead without its pid being
5132 /// asked: a daemon's pid outlives the runs it drove.
5133 #[test]
5134 fn an_exited_driver_is_dead_even_when_its_pid_answers_alive() {
5135 let mut s = state();
5136 s.driver_pid = Some(4242);
5137 s.driver_started_at = Some("1790000000".to_owned());
5138 s.driver_exited = true;
5139 let never = |_| -> Option<bool> { panic!("the pid must not be asked") };
5140 assert_eq!(
5141 s.liveness_with(false, never, |_| panic!("nor its identity")),
5142 Liveness::Dead
5143 );
5144 assert_eq!(s.liveness_with(true, never, |_| None), Liveness::Live);
5145 }
5146
5147 /// A daemon claim wins outright, whatever `driver_pid` or either query
5148 /// says — the stronger, independently-heartbeating signal. Neither query
5149 /// closure is even called: a daemon claim short-circuits before either
5150 /// one, which panicking closures here prove.
5151 #[test]
5152 fn liveness_reads_live_from_a_daemon_claim_alone() {
5153 let mut s = state();
5154 s.driver_pid = None;
5155 assert_eq!(
5156 s.liveness_with(
5157 true,
5158 |_| panic!("a daemon claim needs no pid query"),
5159 |_| panic!("a daemon claim needs no identity query")
5160 ),
5161 Liveness::Live,
5162 "a daemon claim needs no pid to back it up"
5163 );
5164 }
5165
5166 /// The gap `driver_pid` closes: no daemon claim (every manual `magi run`
5167 /// / `magi review`), but the recorded pid answers alive *and* the
5168 /// process currently holding it still carries the same start-time
5169 /// marker this run recorded — proof it is genuinely the same process,
5170 /// not merely the same number.
5171 #[test]
5172 fn liveness_reads_live_from_a_confirmed_pid_with_a_matching_identity() {
5173 let mut s = state();
5174 s.driver_pid = Some(4242);
5175 s.driver_started_at = Some("1790000000".to_owned());
5176 assert_eq!(
5177 s.liveness_with(
5178 false,
5179 |pid| {
5180 assert_eq!(pid, 4242);
5181 Some(true)
5182 },
5183 |pid| {
5184 assert_eq!(pid, 4242);
5185 Some("1790000000".to_owned())
5186 }
5187 ),
5188 Liveness::Live
5189 );
5190 }
5191
5192 /// No daemon claim and the recorded pid confirmed gone by the OS itself
5193 /// — dead outright, and the identity query is never even reached (a
5194 /// panicking closure proves it), since there is nothing left to
5195 /// corroborate.
5196 #[test]
5197 fn liveness_reads_dead_from_a_confirmed_dead_pid() {
5198 let mut s = state();
5199 s.driver_pid = Some(4242);
5200 assert_eq!(
5201 s.liveness_with(
5202 false,
5203 |_| Some(false),
5204 |_| panic!("a confirmed-dead pid needs no identity query")
5205 ),
5206 Liveness::Dead
5207 );
5208 }
5209
5210 /// The gap this task's review round exists to close: a killed manual
5211 /// run's pid gets handed to a wholly unrelated later process. `pid_status`
5212 /// alone would read that as `Live` — the reused pid really is alive —
5213 /// but the process now holding it started at a different moment than the
5214 /// one this run recorded, so this must read `Dead`, not `Live`: a
5215 /// mismatch is exactly as good as proof the original driver is gone.
5216 #[test]
5217 fn liveness_reads_dead_when_a_live_pid_no_longer_matches_the_recorded_start_time() {
5218 let mut s = state();
5219 s.driver_pid = Some(4242);
5220 s.driver_started_at = Some("1790000000".to_owned());
5221 assert_eq!(
5222 s.liveness_with(false, |_| Some(true), |_| Some("1790005400".to_owned())),
5223 Liveness::Dead,
5224 "the pid is alive, but under a different process than the one this run recorded"
5225 );
5226 }
5227
5228 /// Missing information never collapses to `Dead`: an old run with no
5229 /// `driver_pid` at all, a `driver_pid` this build could not query, a live
5230 /// pid with no recorded start time to compare (an even older run, before
5231 /// that field existed), and a live pid whose current identity this build
5232 /// could not re-query, all read as `Unknown` — never a guess in either
5233 /// direction.
5234 #[test]
5235 fn a_locale_format_marker_on_a_live_pid_reads_unknown_never_dead() {
5236 let mut s = state();
5237 s.driver_pid = Some(4242);
5238 for old in ["日 10/ 4 17:27:03 2026", "Sun Oct 4 17:27:03 2026"] {
5239 s.driver_started_at = Some(old.to_owned());
5240 assert_eq!(
5241 s.liveness_with(
5242 false,
5243 |_| Some(true),
5244 |_| panic!("an old-format marker needs no identity query")
5245 ),
5246 Liveness::Unknown,
5247 "{old}"
5248 );
5249 }
5250 }
5251
5252 #[test]
5253 fn integer_markers_compare_live_on_match_and_dead_on_difference() {
5254 let mut s = state();
5255 s.driver_pid = Some(4242);
5256 s.driver_started_at = Some("1790000000".to_owned());
5257 assert_eq!(
5258 s.liveness_with(false, |_| Some(true), |_| Some("1790000000".to_owned())),
5259 Liveness::Live
5260 );
5261 assert_eq!(
5262 s.liveness_with(false, |_| Some(true), |_| Some("1790000001".to_owned())),
5263 Liveness::Dead
5264 );
5265 }
5266
5267 #[test]
5268 fn liveness_never_guesses_out_of_missing_information() {
5269 let mut s = state();
5270 s.driver_pid = None;
5271 assert_eq!(
5272 s.liveness_with(
5273 false,
5274 |_| panic!("no pid to query"),
5275 |_| panic!("no pid to query")
5276 ),
5277 Liveness::Unknown,
5278 "no driver_pid recorded at all — an old run predating this field"
5279 );
5280
5281 s.driver_pid = Some(4242);
5282 assert_eq!(
5283 s.liveness_with(false, |_| None, |_| panic!("inconclusive already")),
5284 Liveness::Unknown,
5285 "a pid to ask, but the platform could not answer for it"
5286 );
5287
5288 s.driver_started_at = None;
5289 assert_eq!(
5290 s.liveness_with(false, |_| Some(true), |_| Some("anything".to_owned())),
5291 Liveness::Unknown,
5292 "a live pid, but no recorded marker to corroborate it against — an old run \
5293 predating `driver_started_at`"
5294 );
5295
5296 s.driver_started_at = Some("1790000000".to_owned());
5297 assert_eq!(
5298 s.liveness_with(false, |_| Some(true), |_| None),
5299 Liveness::Unknown,
5300 "a live pid and a recorded marker, but the identity re-query itself failed"
5301 );
5302 }
5303
5304 #[test]
5305 fn abandon_clears_active_and_fails_a_non_terminal_run() {
5306 let mut s = state();
5307 s.status = RunStatus::Implementing;
5308 let now = Timestamp::now();
5309 s.active
5310 .insert("impl-A".to_owned(), overrun_seat(now, 21_000, 3_600));
5311
5312 s.abandon("daemon");
5313
5314 assert!(s.active.is_empty());
5315 assert_eq!(s.status, RunStatus::Failed);
5316 assert!(
5317 s.events
5318 .last()
5319 .expect("an event was logged")
5320 .message
5321 .contains("impl-A"),
5322 "the event names the abandoned seat"
5323 );
5324 }
5325
5326 #[test]
5327 fn abandon_never_overwrites_a_status_already_terminal() {
5328 let mut s = state();
5329 s.status = RunStatus::Ready;
5330 let now = Timestamp::now();
5331 s.active
5332 .insert("impl-A".to_owned(), overrun_seat(now, 21_000, 3_600));
5333
5334 s.abandon("daemon");
5335
5336 assert!(s.active.is_empty());
5337 assert_eq!(
5338 s.status,
5339 RunStatus::Ready,
5340 "a run already done must not be relabelled Failed"
5341 );
5342 }
5343
5344 #[test]
5345 fn candidate_viability_excludes_empty_and_failed() {
5346 let mut c = Candidate {
5347 index: 0,
5348 label: 'A',
5349 agent: "a".to_owned(),
5350 branch: "b".to_owned(),
5351 worktree: PathBuf::from("/w"),
5352 summary: String::new(),
5353 stat: String::new(),
5354 files: 1,
5355 commits: 1,
5356 empty: false,
5357 failed: None,
5358 verified_noop: None,
5359 duration_ms: 0,
5360 folded: false,
5361 };
5362 assert!(c.viable());
5363 c.empty = true;
5364 assert!(!c.viable());
5365 c.empty = false;
5366 c.failed = Some("timeout".to_owned());
5367 assert!(!c.viable());
5368 }
5369
5370 #[test]
5371 fn build_failure_is_distinguished_from_a_failing_test() {
5372 let link_race = CommandOutcome {
5373 command: "cargo test".to_owned(),
5374 code: Some(1),
5375 output_tail: "LINK : fatal error LNK1104: cannot open file \
5376 'graph_dirty_tree-71d4dc8e.exe'\n\
5377 error: could not compile `magi-cli` (test \"graph_dirty_tree\")"
5378 .to_owned(),
5379 duration_ms: 500,
5380 resource_blocked: false,
5381 };
5382 assert!(!link_race.ok());
5383 assert!(link_race.build_failed());
5384 let mut resource_hold = link_race.clone();
5385 resource_hold.resource_blocked = true;
5386 assert!(
5387 !resource_hold.build_failed(),
5388 "disk admission must not spend a build retry"
5389 );
5390
5391 let failing_test = CommandOutcome {
5392 command: "cargo test".to_owned(),
5393 code: Some(101),
5394 output_tail: "thread 'it_works' panicked at 'assertion failed'".to_owned(),
5395 duration_ms: 500,
5396 resource_blocked: false,
5397 };
5398 assert!(!failing_test.ok());
5399 assert!(
5400 !failing_test.build_failed(),
5401 "a real test failure must not be classed as a build failure"
5402 );
5403
5404 let passing = CommandOutcome {
5405 command: "cargo test".to_owned(),
5406 code: Some(0),
5407 output_tail: String::new(),
5408 duration_ms: 500,
5409 resource_blocked: false,
5410 };
5411 assert!(passing.ok());
5412 assert!(!passing.build_failed());
5413 }
5414
5415 #[test]
5416 fn tail_keeps_the_end_on_a_line_boundary() {
5417 let text = (0..100).map(|i| format!("line {i}\n")).collect::<String>();
5418 let t = tail(&text, 40);
5419 assert!(t.starts_with("[..."));
5420 assert!(t.ends_with("line 99\n"));
5421 assert!(t.len() < 120);
5422 assert_eq!(tail("short", 40), "short");
5423 }
5424
5425 #[test]
5426 fn summarize_verify_keeps_panics_behind_a_huge_backtrace() {
5427 let mut text =
5428 String::from("running 1 test\ntest a ... FAILED\n\nfailures:\n\n---- a stdout ----\n");
5429 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");
5430 for i in 0..6000 {
5431 text.push_str(&format!(" {i}: 0x102e80de0 - <web_render::x::{{closure#0}}>\n at /rustc/abc/library/core/src/ops/function.rs:250:5\n"));
5432 }
5433 text.push_str("\nfailures:\n a\n\ntest result: FAILED. 0 passed; 1 failed\n");
5434 assert!(text.len() > 400_000);
5435 let s = summarize_verify(&text, VERIFY_SUMMARY);
5436 assert!(s.contains("panicked at tests/a.rs:9:5"));
5437 assert!(s.contains("left: 1") && s.contains("right: 2"));
5438 assert!(s.contains("---- a stdout ----"));
5439 assert!(s.contains("test result: FAILED"));
5440 assert!(!s.contains("0x102e80de0"));
5441 assert!(s.len() <= VERIFY_SUMMARY);
5442 // Re-summarising to a smaller budget still keeps the panic.
5443 assert!(summarize_verify(&s, 1_500).contains("panicked at tests/a.rs:9:5"));
5444 assert_eq!(summarize_verify("short", 100), "short");
5445 }
5446
5447 #[test]
5448 fn summarize_verify_keeps_panics_when_the_noise_is_not_frames() {
5449 let mut text = String::from("---- t stdout ----\nthread 't' panicked at x.rs:1:1:\nboom\n");
5450 text.push_str(&"noise line\n".repeat(50_000));
5451 text.push_str("test result: FAILED\n");
5452 let s = summarize_verify(&text, 8_000);
5453 assert!(s.contains("panicked at x.rs:1:1"));
5454 assert!(s.contains("boom"));
5455 assert!(s.contains("test result: FAILED"));
5456 assert!(s.len() <= 8_000);
5457 }
5458
5459 #[test]
5460 fn tail_survives_multibyte_cuts() {
5461 let text = "あ".repeat(50);
5462 let t = tail(&text, 10);
5463 assert!(t.contains("earlier bytes omitted"));
5464 assert!(t.ends_with('あ'));
5465 }
5466
5467 fn finding(id: &str, severity: crate::verdict::Severity) -> crate::verdict::Finding {
5468 crate::verdict::Finding {
5469 id: id.to_owned(),
5470 severity,
5471 file: None,
5472 line: None,
5473 title: "x".to_owned(),
5474 detail: String::new(),
5475 }
5476 }
5477
5478 fn round(clean: bool, findings: Vec<crate::verdict::Finding>) -> ReviewRound {
5479 ReviewRound {
5480 round: 1,
5481 head: "h".to_owned(),
5482 verified_head: None,
5483 verified_at: None,
5484 reviews: vec![ReviewRecord {
5485 attempts: 0,
5486 reviewer: 1,
5487 agent: "a".to_owned(),
5488 summary: String::new(),
5489 findings,
5490 vote: None,
5491 failed: None,
5492 duration_ms: 0,
5493 }],
5494 e2e: Vec::new(),
5495 verify_retried: false,
5496 e2e_deferred: false,
5497 e2e_defer_reason: None,
5498 fix: None,
5499 blocking: 0,
5500 answered: 1,
5501 expected: 1,
5502 clean,
5503 progressed: false,
5504 vote_split: false,
5505 reconsideration: Vec::new(),
5506 verdict: None,
5507 }
5508 }
5509
5510 fn voted(
5511 findings: Vec<crate::verdict::Finding>,
5512 votes: &[ReviewVote],
5513 revotes: &[Option<ReviewVote>],
5514 ) -> ReviewRound {
5515 let mut r = round(false, findings);
5516 r.reviews = votes
5517 .iter()
5518 .enumerate()
5519 .map(|(i, v)| {
5520 let mut rec = r.reviews[0].clone();
5521 rec.reviewer = i + 1;
5522 rec.vote = Some(*v);
5523 if i > 0 {
5524 rec.findings = Vec::new();
5525 }
5526 rec
5527 })
5528 .collect();
5529 r.reconsideration = revotes
5530 .iter()
5531 .enumerate()
5532 .map(|(i, v)| ReviewRevoteRecord {
5533 reviewer: i + 1,
5534 agent: "a".to_owned(),
5535 vote: *v,
5536 reason: String::new(),
5537 failed: None,
5538 })
5539 .collect();
5540 r
5541 }
5542
5543 #[test]
5544 fn a_hand_off_is_contested_only_by_a_blocking_finding_and_a_reject_vote() {
5545 use crate::verdict::Severity::{Major, Minor};
5546 use ReviewVote::{Approve, Reject};
5547 let major = || vec![finding("R1-1-1", Major)];
5548 let minor = || vec![finding("R1-1-1", Minor)];
5549
5550 let c = voted(major(), &[Reject, Approve], &[])
5551 .contested_handoff()
5552 .expect("major + reject");
5553 assert_eq!(c.findings.len(), 1);
5554 assert_eq!(c.rejecters, vec![(1, "a".to_owned())]);
5555
5556 assert!(
5557 voted(minor(), &[Reject, Approve], &[])
5558 .contested_handoff()
5559 .is_none()
5560 );
5561 assert!(
5562 voted(major(), &[Approve, Approve], &[])
5563 .contested_handoff()
5564 .is_none()
5565 );
5566 assert!(
5567 voted(Vec::new(), &[Reject], &[])
5568 .contested_handoff()
5569 .is_none()
5570 );
5571 }
5572
5573 #[test]
5574 fn a_reject_withdrawn_in_the_revote_does_not_contest_and_an_unanswered_one_stands() {
5575 use crate::verdict::Severity::Major;
5576 use ReviewVote::{Approve, Reject};
5577 let major = || vec![finding("R1-1-1", Major)];
5578
5579 let withdrawn = voted(major(), &[Reject, Approve], &[Some(Approve), Some(Approve)]);
5580 assert!(withdrawn.contested_handoff().is_none());
5581
5582 let unanswered = voted(major(), &[Reject, Approve], &[None, Some(Approve)]);
5583 assert!(
5584 unanswered.contested_handoff().is_some(),
5585 "no revote falls back to the initial reject"
5586 );
5587
5588 let raised = voted(major(), &[Approve, Approve], &[Some(Reject), Some(Approve)]);
5589 assert!(raised.contested_handoff().is_some());
5590 }
5591
5592 #[test]
5593 fn e2e_status_tells_deferred_apart_from_not_configured() {
5594 let mut r = round(false, Vec::new());
5595 assert_eq!(r.e2e_status(), E2eStatus::NotConfigured);
5596
5597 r.e2e_deferred = true;
5598 assert_eq!(
5599 r.e2e_status(),
5600 E2eStatus::Deferred,
5601 "an empty e2e must not read as unconfigured once it was deferred on purpose"
5602 );
5603
5604 r.e2e = vec![CommandOutcome {
5605 command: "test".to_owned(),
5606 code: Some(0),
5607 output_tail: String::new(),
5608 duration_ms: 0,
5609 resource_blocked: false,
5610 }];
5611 assert_eq!(
5612 r.e2e_status(),
5613 E2eStatus::Passed,
5614 "a round with real outcomes is never read as deferred, even if the flag is still set"
5615 );
5616 }
5617
5618 #[test]
5619 fn e2e_status_reports_a_real_failure_as_failed_not_deferred() {
5620 let mut r = round(false, Vec::new());
5621 r.e2e = vec![CommandOutcome {
5622 command: "test".to_owned(),
5623 code: Some(1),
5624 output_tail: "boom".to_owned(),
5625 duration_ms: 0,
5626 resource_blocked: false,
5627 }];
5628 assert_eq!(r.e2e_status(), E2eStatus::Failed);
5629 }
5630
5631 #[test]
5632 fn e2e_status_never_reads_a_resource_block_as_a_failure() {
5633 // The exact shape of contention on the shared build cache: `e2e`
5634 // holds one outcome, and it is `resource_blocked`, never a command
5635 // that actually ran and produced a red exit code.
5636 let mut r = round(false, Vec::new());
5637 r.e2e = vec![CommandOutcome {
5638 command: "(waiting for the shared build cache)".to_owned(),
5639 code: None,
5640 output_tail: "contended".to_owned(),
5641 duration_ms: 0,
5642 resource_blocked: true,
5643 }];
5644 assert_eq!(
5645 r.e2e_status(),
5646 E2eStatus::ResourceBlocked,
5647 "magi's own inability to get a command to run must not read as a verdict on the \
5648 patch"
5649 );
5650 }
5651
5652 #[test]
5653 fn verification_summary_is_silent_when_there_is_nothing_worth_saying() {
5654 let mut r = round(true, Vec::new());
5655 assert!(
5656 r.verification_summary("h").is_none(),
5657 "no verify.e2e configured: nothing to surface"
5658 );
5659 r.e2e = vec![CommandOutcome {
5660 command: "test".to_owned(),
5661 code: Some(0),
5662 output_tail: String::new(),
5663 duration_ms: 0,
5664 resource_blocked: false,
5665 }];
5666 assert!(
5667 r.verification_summary("h").is_none(),
5668 "a green result needs no skepticism attached to it"
5669 );
5670 }
5671
5672 #[test]
5673 fn verification_summary_tells_the_current_head_apart_from_an_earlier_one() {
5674 let mut r = round(false, Vec::new());
5675 r.head = "h1".to_owned();
5676 r.e2e = vec![CommandOutcome {
5677 command: "test".to_owned(),
5678 code: Some(1),
5679 output_tail: "boom".to_owned(),
5680 duration_ms: 0,
5681 resource_blocked: false,
5682 }];
5683 r.verified_head = Some("h1".to_owned());
5684 r.verified_at = Some(Timestamp::now());
5685
5686 let fresh = r.verification_summary("h1").expect("a failure is surfaced");
5687 assert!(
5688 fresh.label.contains("this is the head being looked at now"),
5689 "{}",
5690 fresh.label
5691 );
5692 assert_eq!(fresh.tail.as_deref(), Some("$ test\nboom\n"));
5693
5694 let stale = r.verification_summary("h2").expect("still surfaced");
5695 assert!(
5696 stale.label.contains("an earlier head, since superseded"),
5697 "a result about a different commit than the one being looked at now must say so, \
5698 not read as current: {}",
5699 stale.label
5700 );
5701 }
5702
5703 #[test]
5704 fn verification_summary_marks_a_resource_block_and_a_deferral_distinctly_from_a_failure() {
5705 let mut r = round(false, Vec::new());
5706 r.e2e = vec![CommandOutcome {
5707 command: "(waiting for the shared build cache)".to_owned(),
5708 code: None,
5709 output_tail: "contended".to_owned(),
5710 duration_ms: 0,
5711 resource_blocked: true,
5712 }];
5713 let blocked = r
5714 .verification_summary("h")
5715 .expect("a resource block is still surfaced, never silent");
5716 assert!(blocked.label.contains("could not run"));
5717 // No command actually ran, but which operation was attempted is
5718 // still a fact worth showing — never silent past the label either.
5719 let tail = blocked
5720 .tail
5721 .expect("the attempted operation is still named");
5722 assert!(tail.contains("(waiting for the shared build cache)"));
5723 assert!(tail.contains("contended"));
5724
5725 let mut d = round(false, Vec::new());
5726 d.e2e_deferred = true;
5727 d.e2e_defer_reason = Some("2 blocking finding(s) already required a fix".to_owned());
5728 let deferred = d.verification_summary("h").expect("deferred is surfaced");
5729 assert!(deferred.label.contains("deferred to the fixer"));
5730 assert!(deferred.label.contains("2 blocking finding(s)"));
5731 assert!(deferred.tail.is_none());
5732 }
5733
5734 #[test]
5735 fn verification_summary_says_unknown_rather_than_guessing_a_time_or_a_commit() {
5736 let mut r = round(false, Vec::new());
5737 r.e2e = vec![CommandOutcome {
5738 command: "test".to_owned(),
5739 code: Some(1),
5740 output_tail: "boom".to_owned(),
5741 duration_ms: 0,
5742 resource_blocked: false,
5743 }];
5744 // verified_head/verified_at left at their default `None` — exactly
5745 // the shape a schema-7 round with no reconstructable timestamp has.
5746 let summary = r.verification_summary("h").expect("a failure is surfaced");
5747 assert!(summary.label.contains("commit unknown"));
5748 assert!(summary.label.contains("checked at: unknown"));
5749 }
5750
5751 #[test]
5752 fn gate_status_tells_not_run_apart_from_not_configured() {
5753 let mut s = state();
5754 assert_eq!(s.gate_status(), GateStatus::NotRun);
5755
5756 s.gate_ran = true;
5757 assert_eq!(
5758 s.gate_status(),
5759 GateStatus::NotConfigured,
5760 "an empty gate is not configured even when gate_ran records an attempt"
5761 );
5762
5763 s.gate = vec![CommandOutcome {
5764 command: "cargo make check".to_owned(),
5765 code: Some(0),
5766 output_tail: String::new(),
5767 duration_ms: 0,
5768 resource_blocked: false,
5769 }];
5770 assert_eq!(s.gate_status(), GateStatus::Passed);
5771
5772 s.gate[0].code = Some(1);
5773 assert_eq!(s.gate_status(), GateStatus::Failed);
5774
5775 s.gate_ran = false;
5776 assert_eq!(
5777 s.gate_status(),
5778 GateStatus::NotRun,
5779 "gate_ran false must win even over a non-empty gate left from a stale record"
5780 );
5781 }
5782
5783 #[test]
5784 fn open_findings_is_empty_when_the_last_round_was_clean() {
5785 let mut s = state();
5786 s.reviews = vec![round(
5787 true,
5788 vec![finding("R1-1-1", crate::verdict::Severity::Minor)],
5789 )];
5790 assert!(s.open_findings().is_empty());
5791 }
5792
5793 #[test]
5794 fn open_findings_reads_the_last_non_clean_round() {
5795 let mut s = state();
5796 s.reviews = vec![round(
5797 false,
5798 vec![finding("R1-1-1", crate::verdict::Severity::Major)],
5799 )];
5800 let open = s.open_findings();
5801 assert_eq!(open.len(), 1);
5802 assert_eq!(open[0].id, "R1-1-1");
5803 }
5804
5805 #[test]
5806 fn handed_off_with_open_findings_needs_a_mergeable_status_and_an_open_round() {
5807 let mut s = state();
5808 s.reviews = vec![round(
5809 false,
5810 vec![finding("R1-1-1", crate::verdict::Severity::Major)],
5811 )];
5812
5813 s.status = RunStatus::Blocked;
5814 assert!(
5815 !s.handed_off_with_open_findings(),
5816 "a blocked run is not a hand-off"
5817 );
5818
5819 s.status = RunStatus::Ready;
5820 assert!(s.handed_off_with_open_findings());
5821
5822 s.reviews = vec![round(true, Vec::new())];
5823 assert!(
5824 !s.handed_off_with_open_findings(),
5825 "a clean last round has nothing to hand off"
5826 );
5827 }
5828
5829 #[test]
5830 fn unmerged_by_design_is_only_ready_reached_via_merge_mode_none() {
5831 let mut s = state();
5832
5833 s.status = RunStatus::Ready;
5834 assert!(
5835 !s.unmerged_by_design(),
5836 "no merge outcome recorded at all must not be flagged"
5837 );
5838
5839 s.merge = Some(MergeOutcome {
5840 mode: MergeMode::None,
5841 ok: true,
5842 detail: "git merge --no-ff magi/x/A".to_owned(),
5843 empty: false,
5844 });
5845 assert!(
5846 s.unmerged_by_design(),
5847 "Ready reached through mode none is the case this exists to flag"
5848 );
5849
5850 // A PR closed without merging also leaves `status` at `Ready`, but
5851 // through `mode = "pr"` — a run that may still have been landable by
5852 // a person watching the PR, unlike the honest mode-none no-op.
5853 s.merge = Some(MergeOutcome {
5854 mode: MergeMode::Pr,
5855 ok: false,
5856 detail: "https://example.com/pr/1 was closed without merging".to_owned(),
5857 empty: false,
5858 });
5859 assert!(
5860 !s.unmerged_by_design(),
5861 "a closed pull request is a different Ready and must not be relabelled"
5862 );
5863
5864 // Same signal must not fire before the run actually got there.
5865 s.status = RunStatus::Gating;
5866 s.merge = Some(MergeOutcome {
5867 mode: MergeMode::None,
5868 ok: true,
5869 detail: "git merge --no-ff magi/x/A".to_owned(),
5870 empty: false,
5871 });
5872 assert!(
5873 !s.unmerged_by_design(),
5874 "status must actually be Ready, not merely have a stale mode-none merge record"
5875 );
5876 }
5877
5878 #[test]
5879 fn state_round_trips_through_json() {
5880 let s = state();
5881 let body = serde_json::to_string(&s).unwrap();
5882 let back: RunState = serde_json::from_str(&body).unwrap();
5883 assert_eq!(back.id, s.id);
5884 assert_eq!(back.instruction, "add retries");
5885 assert_eq!(back.status, RunStatus::Prep);
5886 }
5887
5888 #[test]
5889 fn a_round_recorded_before_e2e_deferral_existed_still_loads() {
5890 // Exactly the shape a pre-existing `run.json` has for a round: no
5891 // `e2e_deferred`, no `e2e_defer_reason`. Every round used to run e2e
5892 // unconditionally, so the honest reading of an old record's silence
5893 // on this is "it was not deferred" — `false`/`None`, not a load
5894 // failure and not a schema bump (see the `SCHEMA` doc comment: a
5895 // purely additive field whose absence has one unambiguous meaning
5896 // does not need one).
5897 let body = r#"{
5898 "round": 1,
5899 "head": "deadbeef",
5900 "reviews": [],
5901 "e2e": [],
5902 "verify_retried": false,
5903 "fix": null,
5904 "blocking": 0,
5905 "answered": 1,
5906 "expected": 1,
5907 "clean": true
5908 }"#;
5909 let r: ReviewRound = serde_json::from_str(body).expect("an old-shaped round must load");
5910 assert!(!r.e2e_deferred);
5911 assert!(r.e2e_defer_reason.is_none());
5912 assert_eq!(r.e2e_status(), E2eStatus::NotConfigured);
5913 }
5914
5915 #[test]
5916 fn schema_five_state_migrates_old_empty_e2e_and_legacy_verify_budget() {
5917 let mut value = serde_json::to_value(state()).expect("serialize state");
5918 let object = value.as_object_mut().expect("state object");
5919 object.insert("schema".to_owned(), serde_json::json!(5));
5920 let graph = object["config"]["graph"]
5921 .as_object_mut()
5922 .expect("graph object");
5923 graph.insert("timeout_review".to_owned(), serde_json::json!(3600));
5924 graph.remove("timeout_verify");
5925 let review = object["reviews"].as_array_mut().expect("reviews");
5926 review.push(serde_json::json!({
5927 "round": 1, "head": "old", "reviews": [], "e2e": [],
5928 "verify_retried": false, "blocking": 0, "answered": 1,
5929 "expected": 1, "clean": true
5930 }));
5931 let old: RunState = serde_json::from_value(value).expect("schema-5 shape parses");
5932 let migrated = migrate_schema(old).expect("schema 5 migrates");
5933 assert_eq!(migrated.schema, SCHEMA);
5934 assert_eq!(migrated.config.graph.verify_timeout(), 3600);
5935 assert_eq!(migrated.reviews[0].e2e_status(), E2eStatus::NotConfigured);
5936 }
5937
5938 #[test]
5939 fn schema_six_state_with_a_recorded_gate_migrates_to_gate_ran_true() {
5940 let mut value = serde_json::to_value(state()).expect("serialize state");
5941 let object = value.as_object_mut().expect("state object");
5942 object.insert("schema".to_owned(), serde_json::json!(6));
5943 object.insert(
5944 "gate".to_owned(),
5945 serde_json::json!([{
5946 "command": "cargo make check",
5947 "code": 0,
5948 "output_tail": "",
5949 "duration_ms": 0,
5950 "resource_blocked": false
5951 }]),
5952 );
5953 let old: RunState = serde_json::from_value(value).expect("schema-6 shape parses");
5954 let migrated = migrate_schema(old).expect("schema 6 migrates");
5955 assert_eq!(migrated.schema, SCHEMA);
5956 assert!(
5957 migrated.gate_ran,
5958 "a non-empty recorded gate is a real attempt, not an unrun one"
5959 );
5960 assert_eq!(migrated.gate_status(), GateStatus::Passed);
5961 }
5962
5963 #[test]
5964 fn schema_six_state_with_an_empty_gate_migrates_to_gate_ran_false_and_is_retried() {
5965 // The exact shape of the stuck `shoka` run this schema bump fixes:
5966 // `verify.gate` empty, `gate` empty, schema 6. It must come back as
5967 // "not yet run" so the next `gate()` call re-attempts it — and for a
5968 // repo with no gate commands configured, that resolves instantly to
5969 // `NotConfigured` instead of staying stuck forever.
5970 let mut value = serde_json::to_value(state()).expect("serialize state");
5971 let object = value.as_object_mut().expect("state object");
5972 object.insert("schema".to_owned(), serde_json::json!(6));
5973 object.insert("gate".to_owned(), serde_json::json!([]));
5974 let old: RunState = serde_json::from_value(value).expect("schema-6 shape parses");
5975 let migrated = migrate_schema(old).expect("schema 6 migrates");
5976 assert_eq!(migrated.schema, SCHEMA);
5977 assert!(
5978 !migrated.gate_ran,
5979 "an empty gate on schema 6 is ambiguous and must be treated as unrun"
5980 );
5981 assert_eq!(migrated.gate_status(), GateStatus::NotRun);
5982 }
5983
5984 #[test]
5985 fn schema_seven_state_reconstructs_verified_head_for_a_round_that_actually_ran_e2e() {
5986 // Schema 7's main review loop always checked `e2e` against the
5987 // round's own `head` — it just never wrote that into `verified_head`
5988 // unless a catch-up run had checked a *different* commit. Migrating
5989 // to schema 8 restores that always-true fact instead of leaving a
5990 // reader to assume it.
5991 let mut value = serde_json::to_value(state()).expect("serialize state");
5992 let object = value.as_object_mut().expect("state object");
5993 object.insert("schema".to_owned(), serde_json::json!(7));
5994 let reviews = object["reviews"].as_array_mut().expect("reviews");
5995 reviews.push(serde_json::json!({
5996 "round": 1, "head": "deadbeef", "reviews": [],
5997 "e2e": [{
5998 "command": "cargo test", "code": 0, "output_tail": "",
5999 "duration_ms": 0, "resource_blocked": false
6000 }],
6001 "verify_retried": false, "blocking": 0, "answered": 1,
6002 "expected": 1, "clean": true
6003 }));
6004 let old: RunState = serde_json::from_value(value).expect("schema-7 shape parses");
6005 let migrated = migrate_schema(old).expect("schema 7 migrates");
6006 assert_eq!(migrated.schema, SCHEMA);
6007 assert_eq!(
6008 migrated.reviews[0].verified_head.as_deref(),
6009 Some("deadbeef"),
6010 "a schema-7 round's main-loop e2e was always against its own head, even though the \
6011 field never said so"
6012 );
6013 assert!(
6014 migrated.reviews[0].verified_at.is_none(),
6015 "no historical timestamp exists to reconstruct; unknown stays unknown, not a \
6016 guessed 'now'"
6017 );
6018 }
6019
6020 #[test]
6021 fn schema_seven_state_leaves_a_deferred_round_with_no_verified_head() {
6022 let mut value = serde_json::to_value(state()).expect("serialize state");
6023 let object = value.as_object_mut().expect("state object");
6024 object.insert("schema".to_owned(), serde_json::json!(7));
6025 let reviews = object["reviews"].as_array_mut().expect("reviews");
6026 reviews.push(serde_json::json!({
6027 "round": 1, "head": "deadbeef", "reviews": [],
6028 "e2e": [], "e2e_deferred": true,
6029 "verify_retried": false, "blocking": 1, "answered": 1,
6030 "expected": 1, "clean": false
6031 }));
6032 let old: RunState = serde_json::from_value(value).expect("schema-7 shape parses");
6033 let migrated = migrate_schema(old).expect("schema 7 migrates");
6034 assert!(
6035 migrated.reviews[0].verified_head.is_none(),
6036 "a deferred round never ran e2e; there is nothing to reconstruct"
6037 );
6038 }
6039
6040 #[test]
6041 fn origin_round_trips_through_the_run_state() {
6042 let mut s = state();
6043 s.origin = Some(Origin::from_agent_env(
6044 Some(("4a7b".to_owned(), "chat".to_owned())),
6045 Some("20260930-092817-4f6f".to_owned()),
6046 ));
6047 let back: RunState =
6048 serde_json::from_str(&serde_json::to_string(&s).unwrap()).expect("parse back");
6049 assert_eq!(back.origin, s.origin);
6050 assert_eq!(
6051 back.origin.as_ref().unwrap().by,
6052 StartedBy::Chat {
6053 talk: "4a7b".to_owned()
6054 }
6055 );
6056 assert_eq!(
6057 origin_label(back.origin.as_ref()),
6058 "chat 4a7b, for task 4f6f"
6059 );
6060 }
6061
6062 #[test]
6063 fn a_schema_twelve_record_without_an_origin_loads_and_reads_as_unknown() {
6064 let mut value = serde_json::to_value(state()).expect("serialize state");
6065 let object = value.as_object_mut().expect("state object");
6066 object.insert("schema".to_owned(), serde_json::json!(12));
6067 object.remove("origin");
6068 let old: RunState = serde_json::from_value(value).expect("schema-12 shape parses");
6069 assert!(old.origin.is_none());
6070 let migrated = migrate_schema(old).expect("schema 12 migrates");
6071 assert_eq!(migrated.schema, SCHEMA);
6072 assert!(
6073 migrated.origin.is_none(),
6074 "an origin nobody recorded is not invented"
6075 );
6076 assert_eq!(
6077 origin_label(migrated.origin.as_ref()),
6078 "origin unknown (started before origins were recorded)"
6079 );
6080 }
6081
6082 #[test]
6083 fn schema_supported_versions_all_reach_current() {
6084 for schema in 5..=SCHEMA {
6085 let mut value = serde_json::to_value(state()).expect("serialize state");
6086 value["schema"] = serde_json::json!(schema);
6087 if schema < 14 {
6088 value.as_object_mut().unwrap().remove("task_instruction");
6089 }
6090 if schema < 13 {
6091 value.as_object_mut().unwrap().remove("origin");
6092 }
6093 let old: RunState = serde_json::from_value(value).expect("legacy shape parses");
6094 let migrated = migrate_schema(old)
6095 .unwrap_or_else(|error| panic!("schema {schema} must migrate: {error}"));
6096 assert_eq!(migrated.schema, SCHEMA, "schema {schema}");
6097 assert!(migrated.task_instruction.is_none(), "schema {schema}");
6098 assert!(migrated.origin.is_none(), "schema {schema}");
6099 }
6100 }
6101
6102 #[test]
6103 fn schema_unsupported_versions_remain_rejected() {
6104 for schema in [1, 2, 3, 4, SCHEMA + 1] {
6105 let mut old = state();
6106 old.schema = schema;
6107 assert!(migrate_schema(old).is_err(), "schema {schema}");
6108 }
6109 }
6110
6111 #[test]
6112 fn origin_attributes_agents_by_node_and_never_by_guesswork() {
6113 let chat = Origin::from_agent_env(Some(("4a7b".to_owned(), "chat".to_owned())), None);
6114 assert_eq!(
6115 chat.by,
6116 StartedBy::Chat {
6117 talk: "4a7b".into()
6118 }
6119 );
6120 let seat = Origin::from_agent_env(
6121 Some(("20260930-092817-ec34".to_owned(), "implement".to_owned())),
6122 None,
6123 );
6124 assert_eq!(seat.label(), "implement@ec34");
6125 assert_eq!(Origin::from_agent_env(None, None), Origin::operator());
6126 assert_eq!(Origin::operator().label(), "operator");
6127 assert_eq!(Origin::queue("20260930-000000-4f6f").label(), "task 4f6f");
6128 assert_eq!(
6129 Origin::operator()
6130 .serving(Some("20260930-000000-4f6f".to_owned()))
6131 .label(),
6132 "operator, for task 4f6f"
6133 );
6134 }
6135
6136 #[test]
6137 fn schema_six_serialization_is_rejected_by_a_schema_five_reader() {
6138 let body = serde_json::to_value(state()).expect("serialize state");
6139 assert_eq!(body["schema"], serde_json::json!(SCHEMA));
6140 assert_ne!(body["schema"], serde_json::json!(5));
6141 }
6142
6143 #[test]
6144 fn seat_started_and_finished_track_who_has_not_answered_yet() {
6145 let mut s = state();
6146 s.seat_started("judge", "judge-1", std::time::Duration::from_secs(60), 0);
6147 s.seat_started("judge", "judge-2", std::time::Duration::from_secs(60), 0);
6148 assert_eq!(s.active.len(), 2, "both seats are still out");
6149
6150 s.seat_finished("judge-1");
6151 assert_eq!(
6152 s.active.keys().collect::<Vec<_>>(),
6153 vec!["judge-2"],
6154 "only the seat that answered drops out; judge-2 is still waited on"
6155 );
6156 }
6157
6158 /// `seats_active` / `tasks_active` are the accessors report/web read
6159 /// instead of `active` directly, so neither ever counts the other kind of
6160 /// entry as a seat — a `verify.e2e` task must never inflate a quorum or
6161 /// seat count, and a seat must never show up in a task listing.
6162 #[test]
6163 fn seats_active_and_tasks_active_never_cross_over() {
6164 let mut s = state();
6165 s.seat_started("judge", "judge-1", std::time::Duration::from_secs(60), 0);
6166 s.task_command(
6167 "e2e",
6168 "verify",
6169 0,
6170 "cargo test",
6171 1,
6172 2,
6173 std::time::Duration::from_secs(600),
6174 );
6175
6176 assert_eq!(
6177 s.seats_active()
6178 .map(|(k, _)| k.as_str())
6179 .collect::<Vec<_>>(),
6180 vec!["judge-1"]
6181 );
6182 assert_eq!(
6183 s.tasks_active()
6184 .map(|(k, _)| k.as_str())
6185 .collect::<Vec<_>>(),
6186 vec!["e2e"]
6187 );
6188
6189 // A command boundary updates the same entry in place — still one
6190 // task, never a second one accumulating alongside it.
6191 s.task_command(
6192 "e2e",
6193 "verify",
6194 0,
6195 "cargo clippy",
6196 2,
6197 2,
6198 std::time::Duration::from_secs(600),
6199 );
6200 assert_eq!(s.tasks_active().count(), 1);
6201 assert_eq!(s.active["e2e"].command.as_deref(), Some("cargo clippy"));
6202
6203 s.task_finished("e2e");
6204 assert!(s.tasks_active().next().is_none());
6205 assert_eq!(
6206 s.seats_active()
6207 .map(|(k, _)| k.as_str())
6208 .collect::<Vec<_>>(),
6209 vec!["judge-1"],
6210 "clearing the task must not touch the seat entry"
6211 );
6212 }
6213
6214 #[test]
6215 fn a_retry_is_recorded_as_a_later_attempt_on_the_same_seat() {
6216 let mut s = state();
6217 s.seat_started("review", "review-2", std::time::Duration::from_secs(30), 0);
6218 s.seat_finished("review-2");
6219 // A nudge re-asks the same seat; attempt says this is not the first
6220 // time, which is the only trace a nudge otherwise leaves behind.
6221 s.seat_started("review", "review-2", std::time::Duration::from_secs(30), 1);
6222 assert_eq!(s.active["review-2"].attempt, 1);
6223 }
6224
6225 #[test]
6226 fn active_seat_reports_elapsed_and_remaining_time() {
6227 let now = Timestamp::now();
6228 let started = now - jiff::SignedDuration::from_secs(30);
6229 let seat = ActiveSeat {
6230 node: "judge".to_owned(),
6231 started_at: started,
6232 timeout_secs: 100,
6233 attempt: 0,
6234 task: None,
6235 command: None,
6236 index: None,
6237 total: None,
6238 };
6239 assert_eq!(seat.elapsed_secs(now), 30);
6240 assert_eq!(seat.remaining_secs(now), 70);
6241 }
6242
6243 #[test]
6244 fn remaining_time_never_goes_negative_past_the_timeout() {
6245 // `agy`'s own print-timeout occasionally overruns by a hair before the
6246 // kill lands; a naive subtraction would print a negative "time left".
6247 let now = Timestamp::now();
6248 let started = now - jiff::SignedDuration::from_secs(200);
6249 let seat = ActiveSeat {
6250 node: "implement".to_owned(),
6251 started_at: started,
6252 timeout_secs: 100,
6253 attempt: 1,
6254 task: None,
6255 command: None,
6256 index: None,
6257 total: None,
6258 };
6259 assert_eq!(seat.remaining_secs(now), 0);
6260 }
6261
6262 #[test]
6263 fn clear_active_drops_stale_seats_and_reports_whether_it_did() {
6264 let mut s = state();
6265 assert!(!s.clear_active(), "nothing to clear on a fresh run");
6266 s.seat_started(
6267 "implement",
6268 "impl-B",
6269 std::time::Duration::from_secs(3600),
6270 0,
6271 );
6272 assert!(s.clear_active(), "a leftover entry is reported as cleared");
6273 assert!(s.active.is_empty());
6274 }
6275
6276 #[test]
6277 fn active_seat_carries_nothing_that_could_be_read_as_output_bytes() {
6278 // `agy` prints exactly one JSON object, at the very end (see
6279 // `agent::dropped_stream`'s doc comment) — a seat can sit at zero
6280 // captured bytes for its whole timeout while working normally. So
6281 // `ActiveSeat` records only the wall-clock facts (when it started,
6282 // its budget, which attempt), never a byte count, which is what
6283 // keeps a reader from being able to build "0 bytes => dead" out of
6284 // it even by accident.
6285 let seat = ActiveSeat {
6286 node: "implement".to_owned(),
6287 started_at: Timestamp::now(),
6288 timeout_secs: 60,
6289 attempt: 0,
6290 task: None,
6291 command: None,
6292 index: None,
6293 total: None,
6294 };
6295 let value = serde_json::to_value(&seat).unwrap();
6296 let keys: std::collections::BTreeSet<String> =
6297 value.as_object().unwrap().keys().cloned().collect();
6298 assert_eq!(
6299 keys,
6300 std::collections::BTreeSet::from([
6301 "node".to_owned(),
6302 "started_at".to_owned(),
6303 "timeout_secs".to_owned(),
6304 "attempt".to_owned(),
6305 ]),
6306 "a byte count here would be a lever to declare a silent-but-healthy seat dead, and \
6307 the task-only fields must stay absent (not null) on an ordinary seat entry"
6308 );
6309 }
6310
6311 /// The same guarantee as
6312 /// [`active_seat_carries_nothing_that_could_be_read_as_output_bytes`],
6313 /// extended to a task entry: `verify.e2e` / `verify.gate` are exactly as
6314 /// silent as `agy` between commands, so a running command-list task must
6315 /// never carry anything a reader could mistake for output-byte evidence
6316 /// either.
6317 #[test]
6318 fn task_active_seat_carries_nothing_that_could_be_read_as_output_bytes() {
6319 let seat = ActiveSeat {
6320 node: "verify".to_owned(),
6321 started_at: Timestamp::now(),
6322 timeout_secs: 600,
6323 attempt: 0,
6324 task: Some("e2e".to_owned()),
6325 command: Some("cargo test".to_owned()),
6326 index: Some(1),
6327 total: Some(3),
6328 };
6329 let value = serde_json::to_value(&seat).unwrap();
6330 let keys: std::collections::BTreeSet<String> =
6331 value.as_object().unwrap().keys().cloned().collect();
6332 assert_eq!(
6333 keys,
6334 std::collections::BTreeSet::from([
6335 "node".to_owned(),
6336 "started_at".to_owned(),
6337 "timeout_secs".to_owned(),
6338 "attempt".to_owned(),
6339 "task".to_owned(),
6340 "command".to_owned(),
6341 "index".to_owned(),
6342 "total".to_owned(),
6343 ]),
6344 );
6345 }
6346
6347 #[test]
6348 fn an_old_run_json_without_active_seats_still_loads() {
6349 // Schema did not bump for this field: an already-written run.json
6350 // simply lacks the key, and `#[serde(default)]` must fill it in
6351 // rather than fail the whole read.
6352 let s = state();
6353 let mut value = serde_json::to_value(&s).unwrap();
6354 value.as_object_mut().unwrap().remove("active");
6355 let back: RunState = serde_json::from_value(value).unwrap();
6356 assert!(back.active.is_empty());
6357 assert_eq!(back.schema, SCHEMA);
6358 }
6359
6360 #[test]
6361 fn an_old_run_json_without_jobs_still_loads() {
6362 // No schema bump for this field either, for the same reason: an
6363 // empty `jobs` list on an old record means exactly what it always
6364 // meant for that record — no adapter existed yet to report one —
6365 // and `#[serde(default)]` fills it in rather than failing the read.
6366 let s = state();
6367 let mut value = serde_json::to_value(&s).unwrap();
6368 value.as_object_mut().unwrap().remove("jobs");
6369 let back: RunState = serde_json::from_value(value).unwrap();
6370 assert!(back.jobs.is_empty());
6371 assert_eq!(back.schema, SCHEMA);
6372 }
6373
6374 #[test]
6375 fn ensure_can_delete_guards_live_and_unfolded_runs() {
6376 let mut s = state();
6377 // 1. A daemon is working on it right now.
6378 s.status = RunStatus::Prep;
6379 let err = s.ensure_can_delete(true).unwrap_err().to_string();
6380 assert!(err.contains("live daemon"), "{err}");
6381
6382 // 2. The same unfinished run with no daemon behind it is a leftover
6383 // from a killed process, and deletable. Without this an interrupted
6384 // run could never be removed: its status stays `prep` forever.
6385 assert!(s.ensure_can_delete(false).is_ok());
6386
6387 // 3. Unfolded candidates are refused either way — that is the guard
6388 // that stops a delete from discarding a worktree.
6389 s.status = RunStatus::Merged;
6390 s.candidates.push(Candidate {
6391 index: 0,
6392 label: 'A',
6393 agent: "a".to_owned(),
6394 branch: "b".to_owned(),
6395 worktree: PathBuf::from("/w"),
6396 summary: String::new(),
6397 stat: String::new(),
6398 files: 1,
6399 commits: 1,
6400 empty: false,
6401 failed: None,
6402 verified_noop: None,
6403 duration_ms: 0,
6404 folded: false,
6405 });
6406 let err = s.ensure_can_delete(false).unwrap_err().to_string();
6407 assert!(
6408 err.contains("magi fold"),
6409 "error must suggest `magi fold`: {err}"
6410 );
6411
6412 // 4. Folded and nobody working on it.
6413 s.candidates[0].folded = true;
6414 assert!(s.ensure_can_delete(false).is_ok());
6415 }
6416}
6417
6418impl RunState {
6419 /// A seed for a seat that changes agent, distinct on every call.
6420 pub fn next_seat_seed(&mut self) -> u64 {
6421 self.seat_epoch += 1;
6422 self.seed ^ self.seat_epoch.wrapping_mul(0x9E37_79B9_7F4A_7C15)
6423 }
6424}
6425
6426/// What kind of failure ended an agent's turn on a seat, for deciding whether
6427/// the seat is worth handing to the next roster agent.
6428#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
6429pub enum FailClass {
6430 /// A CLI rate limit.
6431 Quota,
6432 /// The turn outlived its budget.
6433 Timeout,
6434 /// Any other failure, with the message's shape (`failure_signature`,
6435 /// capped at 120 characters).
6436 Other(String),
6437}
6438
6439/// One reviewer seat's record across review rounds, so a round does not ask
6440/// an agent that already failed the seat while another one is answering.
6441///
6442/// `failed` is a *priority* set, not a bound: the per-round `tried` set in
6443/// `ask_json_wave` starts empty every round, so an agent that answered is
6444/// never locked out. A failed id is only asked again once nothing else on the
6445/// roster is left (once per round, and the rounds are `review_rounds`).
6446#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
6447pub struct SeatHistory {
6448 /// Roster ids that failed this seat and have not answered it since.
6449 #[serde(default)]
6450 pub failed: BTreeSet<String>,
6451 /// The agent that last answered this seat.
6452 #[serde(default)]
6453 pub last_ok: Option<String>,
6454 /// The class of the seat's most recent failure; cleared by an answer.
6455 #[serde(default)]
6456 pub last_fail: Option<FailClass>,
6457}