Skip to main content

magi/
clean.rs

1//! The disk janitor: finished runs get their worktrees folded, worktrees whose
2//! run record is already gone get reclaimed too, and the shared build cache is
3//! pruned to its cap.
4//!
5//! A run's state being written by an older schema is not the same thing as it
6//! being unreadable, and this module used to conflate the two: [`fold_due`]
7//! treated any `run.json` its version check rejected exactly like one that
8//! failed to parse at all, so a single schema bump silently stopped every
9//! automatic fold in the fleet the moment it shipped, and did so with no
10//! counter and no log line to say so. A record magi genuinely cannot parse —
11//! missing fields, broken JSON, a schema newer than this build has ever heard
12//! of — is still left alone here, still counted in
13//! [`Housekeeping::unreadable`], and still only ever removed by an explicit
14//! operator action (`magi fold`, or the equivalent phone route). One written
15//! by a schema this build merely disagrees with the *meaning* of is not that:
16//! as long as it still parses, folding proceeds regardless of the number in
17//! its `schema` field.
18//!
19//! Everything policy-shaped — which statuses are foldable, how long a finished
20//! run is left alone, whether the cache is over its limit — is a pure function
21//! injected with numbers, so nothing here has to ask the operating system to
22//! be testable. The only I/O is the removal itself.
23
24use std::collections::BTreeSet;
25use std::path::{Path, PathBuf};
26
27use anyhow::{Context as _, Result, bail};
28use jiff::{SignedDuration, Timestamp};
29use serde::Deserialize;
30
31use crate::ask::Questions;
32use crate::config::Disk;
33use crate::run::{RunState, RunStatus, SCHEMA, short_of};
34
35use crate::disk::{Prune, dir_size};
36
37/// What one janitor pass did, for the caller's log line.
38#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
39pub struct Housekeeping {
40    /// Runs folded (worktrees dropped).
41    pub folded: usize,
42    /// Runs [`fold_due`] left alone because their `run.json` genuinely could
43    /// not be read - missing, broken JSON, a schema this build has never
44    /// heard of - as opposed to one merely written by a different schema
45    /// number, which is folded like any other (see the module docs). This was
46    /// defined but never incremented for a long stretch of this module's
47    /// history, which is exactly how 90 of 93 runs sat unfolded on one
48    /// operator's machine with nothing anywhere saying why: every one of them
49    /// was misclassified as unreadable by a schema check that has since been
50    /// narrowed to only the runs that actually are.
51    pub unreadable: usize,
52    /// Worktrees under the worktree bay reclaimed because no run record in
53    /// `runs/` claims them anymore (see [`fold_orphaned_worktrees`]).
54    pub orphaned_worktrees: usize,
55    /// Files dropped from the shared cache.
56    pub cache_files: usize,
57    /// Bytes freed from the shared cache.
58    pub cache_freed: u64,
59    /// Open questions abandoned because the run that asked them has already
60    /// settled where nothing is coming back to read an answer.
61    pub questions_abandoned: usize,
62    /// Runs found blocked on a merge magi never recorded — a pull request the
63    /// operator merged by hand while `land::land` never got as far as
64    /// opening one itself — and corrected automatically. See
65    /// [`reconcile_external_merges`].
66    pub external_merges_recorded: usize,
67    /// Run records that still called their pull request open after it was
68    /// merged or closed, and were rewritten (see
69    /// [`crate::land::repair_stale_pr_states`]).
70    pub stale_pr_states_repaired: usize,
71}
72
73/// Run the janitor: fold due runs, reclaim orphaned worktrees, prune stale
74/// worktree registrations, then prune the cache if it is over its cap.
75///
76/// Every part is best-effort; a jammed cache lock or a run whose worktree
77/// another borrower holds must not stop the rest. Errors are reported through
78/// `tracing::warn` - this is housekeeping, and the daemon keeps serving
79/// either way.
80pub async fn housekeep(
81    cfg: &crate::config::Config,
82    home: &Path,
83    worktrees_root: &Path,
84    repo: &Path,
85    now: Timestamp,
86) -> Housekeeping {
87    let mut out = Housekeeping::default();
88    crate::retention::sweep(home, &cfg.disk, now).await;
89    if cfg.disk.auto_fold {
90        let runs = home.join("runs");
91        match fold_due(&runs, home, worktrees_root, &cfg.disk, now).await {
92            Ok((folded, unreadable)) => {
93                out.folded = folded;
94                out.unreadable = unreadable;
95            }
96            Err(e) => {
97                tracing::warn!("housekeep: fold due runs: {e:#}");
98                // Stable wording: the reason varies per pass, and a changed
99                // message would relight the bell on every retry.
100                crate::notices::raise_in(
101                    home,
102                    crate::notices::Notice::warn(
103                        "housekeep:fold",
104                        "Automatic cleanup of finished runs failed; disk usage may keep growing.",
105                    ),
106                );
107            }
108        }
109        out.orphaned_worktrees =
110            fold_orphaned_worktrees(&runs, worktrees_root, home, cfg.disk.fold_grace_secs, now)
111                .await;
112        // Best-effort in the same sense as everything else here: a repository
113        // this janitor pass has nothing to do with (or none at all, in a unit
114        // test) must not turn a `warn` into a reason to skip the rest.
115        if let Err(e) = crate::git::worktree_prune(repo).await {
116            tracing::warn!("housekeep: prune worktree registrations: {e:#}");
117        }
118        out.external_merges_recorded = reconcile_external_merges(&runs, home, &cfg.disk, now).await;
119        // Bounded: a handful of forge lookups a pass keeps this cheap, and the
120        // pass is idempotent, so a backlog drains over several passes.
121        out.stale_pr_states_repaired = crate::land::repair_stale_pr_states(home, 5).await.0;
122    }
123    match prune_cache_if_over_limit(cfg, home) {
124        Ok(Some(pruned)) => {
125            out.cache_files = pruned.files;
126            out.cache_freed = pruned.freed;
127        }
128        Ok(None) => {}
129        Err(e) => tracing::warn!("housekeep: prune cache: {e:#}"),
130    }
131    // Unconditional, unlike the two passes above: this is not a disk policy
132    // with a cap or an opt-out, it is closing a gap `graph::Runner` itself
133    // cannot - a run that reached `Merged`/`Ready`/`Failed` before this
134    // cleanup existed, or whose process died between saving that status and
135    // abandoning the question it leaves behind (see `Runner::settle_questions`).
136    // Left alone, that question sits `open` forever: the owner's badge,
137    // banner and title all keep counting a decision nobody is left to read.
138    out.questions_abandoned =
139        abandon_settled_questions(&Questions::at(home.join("questions")), &home.join("runs"));
140    out
141}
142
143/// Abandon every open question whose run has already settled into a status
144/// nothing comes back from, worded with what the run became - the same
145/// cleanup `graph::Runner::settle_questions` runs the moment `status` lands
146/// there, for questions that missed it.
147///
148/// Scans questions rather than runs: the open list is normally short, and a
149/// run that never asked anything costs nothing here. A run this cannot read,
150/// deleted or written by a schema this build does not speak, is left alone
151/// the same as everywhere else in this module; the question stays open
152/// rather than guessed at.
153pub fn abandon_settled_questions(store: &Questions, runs: &Path) -> usize {
154    let waiting_on: BTreeSet<String> = store
155        .list()
156        .into_iter()
157        .filter(|q| q.status.open())
158        .map(|q| q.run)
159        .collect();
160    let mut abandoned = 0;
161    for run in waiting_on {
162        let Ok(meta) = read_meta(runs, &run) else {
163            continue;
164        };
165        match store.settle_run(&run, meta.status) {
166            Ok(n) => abandoned += n,
167            Err(e) => tracing::warn!("housekeep: abandon questions for {run}: {e:#}"),
168        }
169    }
170    abandoned
171}
172
173/// Fold every run that is finished, older than the grace period, and not being
174/// worked on; return `(folded, unreadable)`.
175///
176/// A run whose `run.json` genuinely cannot be parsed — missing fields, broken
177/// JSON, a schema newer than this build has ever heard of — is left exactly
178/// as it is. Automatic housekeeping cannot tell a mid-write file from one that
179/// will never parse again, and `<home>/runs/<id>/` is the evidence `magi
180/// stats` and the deck read; when unsure whether it is safe to touch, the
181/// janitor keeps rather than deletes (see the module docs). Discarding a
182/// record this unreadable is an explicit operator action (`magi fold`, or the
183/// equivalent phone route), never something that happens unattended. Every
184/// such skip is counted in the returned `unreadable` and logged through
185/// `tracing::warn` with the parse failure that caused it - silence here is
186/// exactly the failure mode that let 90 of 93 runs sit unfolded with nothing
187/// to show for it.
188///
189/// A run merely written by a *different* schema number is not unreadable: as
190/// long as `run.json` still parses, it folds like any other terminal run (see
191/// the module docs for why the two are different questions).
192///
193/// Runnable statuses and runs newer than the grace period are also left
194/// alone; folding them would throw away work that is still the answer to
195/// somebody's question. `Merged` runs forget their winner's worktree (the
196/// merge already landed it); `Ready` and `Failed` runs keep it.
197pub async fn fold_due(
198    runs: &Path,
199    home: &Path,
200    _worktrees_root: &Path,
201    disk: &Disk,
202    now: Timestamp,
203) -> Result<(usize, usize)> {
204    let mut folded = 0usize;
205    let mut unreadable = 0usize;
206    let mut ids: Vec<String> = std::fs::read_dir(runs)
207        .into_iter()
208        .flatten()
209        .flatten()
210        .filter(|e| e.path().join("run.json").is_file())
211        .map(|e| e.file_name().to_string_lossy().into_owned())
212        .collect();
213    ids.sort_unstable();
214    for id in ids {
215        if crate::daemon::is_working_on(home, &id, now) {
216            continue;
217        }
218        let meta = match read_meta(runs, &id) {
219            Ok(meta) => meta,
220            Err(e) => {
221                unreadable += 1;
222                tracing::warn!("housekeep: run {id} unreadable, left alone: {e:#}");
223                continue;
224            }
225        };
226        if meta.status.resumable() || !due(now, meta.updated_at, disk.fold_grace_secs) {
227            continue;
228        }
229        // `read_meta` already proved the file parses; `read_state` asks for
230        // the rest of the fields `graph::fold_run` needs (worktree paths,
231        // candidates, tally). A schema mismatch alone does not fail this -
232        // see the module docs - so reaching `Err` here means the JSON itself
233        // is broken in a way `read_meta` did not exercise, which is rare but
234        // not impossible (a body truncated between the two fields it reads
235        // and the rest). That must not cost every other run its turn through
236        // this loop, so it is a skip, not a `?`.
237        let mut state = match read_state(runs, &id) {
238            Ok(state) => state,
239            Err(e) => {
240                unreadable += 1;
241                tracing::warn!("housekeep: run {id} unreadable, left alone: {e:#}");
242                continue;
243            }
244        };
245        if state.startup.as_ref().is_some_and(|s| !s.complete) {
246            continue;
247        }
248        if let Some(reason) = crate::pr_recovery::source_retention_reason(home, &state) {
249            tracing::info!(%id, %reason, "housekeep: source retained; fold refused");
250            continue;
251        }
252        if state.schema != SCHEMA {
253            tracing::info!(
254                "housekeep: run {id} was written by schema {} (this build speaks {SCHEMA}); \
255                 folding it anyway",
256                state.schema
257            );
258        }
259        // `Merged`'s winner branch is safe to drop because it already landed
260        // in the real target branch; `Superseded`'s winner branch is safe to
261        // drop for a different reason - a later attempt at the same task is
262        // what actually landed (or didn't), so *this* run's own winner is
263        // never going to be merged by anyone. Every other terminal status
264        // keeps the winner: `Ready`/`Blocked`/`Stalled`/`Failed`/`VerifiedNoop`
265        // may still have a human's decision pending on that exact branch.
266        // `AlreadyInBase` is the same: the change is on the base under other
267        // commit ids, so the branch holds nothing anyone still needs.
268        let drop_winner = matches!(
269            state.status,
270            RunStatus::Merged | RunStatus::Superseded | RunStatus::AlreadyInBase
271        );
272        // One run's fold must not cost every later run its turn. A worktree
273        // another borrower holds, a branch git refuses to delete, a repository
274        // that has since moved: each is a reason this run cannot be folded
275        // now, and none is a reason to stop the pass. Left unfolded, it is
276        // simply due again next time; a `?` here stopped automatic folding
277        // permanently at the first such run (finding R3-1-1 of run 51a3).
278        match crate::graph::fold_run(&mut state, drop_winner, home).await {
279            Ok(_) => folded += 1,
280            Err(e) => tracing::warn!("housekeep: fold {id}: {e:#}"),
281        }
282    }
283    Ok((folded, unreadable))
284}
285
286/// What one [`fetch_origins`] pass did.
287#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
288pub struct FetchReport {
289    /// Repos whose fetch succeeded.
290    pub fetched: usize,
291    /// Repos with no `origin` remote, skipped.
292    pub no_origin: usize,
293    /// Repos whose fetch failed or timed out.
294    pub failed: usize,
295}
296
297/// Run `git fetch origin` in every checkout under `roots` (the set `magi
298/// repos` lists), so `origin/main` stays current.
299///
300/// Fetch only: never a checkout, merge or fast-forward, so no HEAD, branch or
301/// working tree moves. Best-effort like [`fold_due`]: a repo with no `origin`
302/// is skipped silently, a failure or timeout is a warning, and the pass never
303/// errors. `stop` is checked between repos.
304pub async fn fetch_origins(
305    roots: &[PathBuf],
306    per_repo: std::time::Duration,
307    stop: impl Fn() -> bool,
308) -> FetchReport {
309    let mut report = FetchReport::default();
310    for repo in crate::repos::scan(roots) {
311        if stop() {
312            break;
313        }
314        match crate::git::git_raw(&repo.path, &["remote", "get-url", "origin"]).await {
315            Ok(out) if out.ok() => {}
316            _ => {
317                report.no_origin += 1;
318                continue;
319            }
320        }
321        match crate::git::fetch_origin(&repo.path, per_repo).await {
322            Ok(()) => report.fetched += 1,
323            Err(e) => {
324                tracing::warn!("fetch origin in {}: {e:#}", repo.name);
325                report.failed += 1;
326            }
327        }
328    }
329    report
330}
331
332/// Is `updated` old enough, measured against `now`, that the run may fold?
333///
334/// Pure; the janitor compares against wallclock, tests inject both sides. The
335/// comparison is strict, so a run exactly at the edge of its grace period is
336/// left alone one more pass — the same convention as [`crate::disk::over_limit`].
337pub fn due(now: Timestamp, updated: Timestamp, grace_secs: u64) -> bool {
338    now.duration_since(updated) > SignedDuration::new(grace_secs as i64, 0)
339}
340
341/// The two fields the janitor decides on, read with a serde that tolerates
342/// everything else about the run being unreadable.
343#[derive(Deserialize)]
344struct Meta {
345    status: RunStatus,
346    updated_at: Timestamp,
347}
348
349/// Read `status` and `updated_at` straight off the state file, asking for
350/// nothing else. `Err` when the file is missing, not parseable, or a status in
351/// a version this build does not speak - all of which mean "unreadable".
352fn read_meta(runs: &Path, id: &str) -> Result<Meta> {
353    let path = runs.join(id).join("run.json");
354    let body =
355        std::fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
356    let meta: Meta =
357        serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
358    Ok(meta)
359}
360
361/// Runs checked against GitHub in one janitor pass, at most.
362///
363/// A fleet with many stuck runs must not turn every idle tick into a burst of
364/// `gh pr list` calls; a run left unchecked this pass is checked again next
365/// pass, same as an unfolded due run is.
366const MAX_EXTERNAL_MERGE_CHECKS_PER_PASS: usize = 5;
367
368/// The fields [`reconcile_external_merges`] filters on before paying for a
369/// full [`RunState`] parse or a `gh` round trip.
370#[derive(Deserialize)]
371struct ExternalMergeMeta {
372    status: RunStatus,
373    updated_at: Timestamp,
374    #[serde(default)]
375    merge: Option<crate::run::MergeOutcome>,
376}
377
378fn read_external_merge_meta(runs: &Path, id: &str) -> Result<ExternalMergeMeta> {
379    let path = runs.join(id).join("run.json");
380    let body =
381        std::fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
382    let meta: ExternalMergeMeta =
383        serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
384    Ok(meta)
385}
386
387/// Is a run worth asking GitHub about?
388///
389/// Pure, so the filter itself is assertable without a fixture that writes
390/// `run.json` files or spawns `gh`. Narrower than "blocked": `merge_recorded`
391/// excludes a run `land::land` already finished landing (successfully or
392/// not) - that path already carries its own record of what happened - and
393/// `due` gives an operator who is about to fix a run by hand a grace window
394/// before the janitor starts asking the same question about it.
395pub fn eligible_for_external_merge_check(
396    status: RunStatus,
397    merge_recorded: bool,
398    updated_at: Timestamp,
399    now: Timestamp,
400    grace_secs: u64,
401) -> bool {
402    status == RunStatus::Blocked && !merge_recorded && due(now, updated_at, grace_secs)
403}
404
405/// Rotate `ids` so a fixed per-pass cap does not always land on the same
406/// prefix of the list, starting at `start` (already reduced modulo nothing -
407/// callers pass whatever a persisted cursor last recorded, and this takes it
408/// modulo `ids.len()` itself).
409///
410/// Pure: the offset is the caller's problem, not wall-clock time. An earlier
411/// version derived `start` from `now.as_second() % ids.len()`, which looked
412/// independent of any state to persist but is not actually independent of
413/// how often the janitor runs - a poll interval and a pass's own duration
414/// that alias onto the same handful of `now.as_second()` values (say, a
415/// ten-second poll and a pass that finishes in under a second) revisit only
416/// those same few residues forever and never advance into the rest of the
417/// list at all. [`reconcile_external_merges`] instead persists a cursor
418/// across passes ([`read_external_merge_cursor`] /
419/// [`write_external_merge_cursor`]) and advances it by exactly how many ids
420/// this pass actually looked at, which is the only quantity that is
421/// guaranteed to move forward pass over pass regardless of timing.
422fn rotate_from(ids: &[String], start: usize) -> Vec<String> {
423    if ids.is_empty() {
424        return Vec::new();
425    }
426    let start = start % ids.len();
427    ids[start..]
428        .iter()
429        .chain(ids[..start].iter())
430        .cloned()
431        .collect()
432}
433
434/// Where [`reconcile_external_merges`] remembers how far it got, so a fixed
435/// per-pass cap advances through a fleet's eligible runs pass over pass
436/// instead of camping on whichever ones happen to sort first.
437const EXTERNAL_MERGE_CURSOR_FILE: &str = "external-merge-cursor";
438
439/// `0` for anything this cannot read as a plain number - a first run, a
440/// corrupt or missing file, a build that has never written one - which is
441/// exactly as good a starting point as any: the cursor's whole job is to
442/// keep moving, not to encode any particular position as meaningful.
443fn read_external_merge_cursor(home: &Path) -> usize {
444    std::fs::read_to_string(home.join(EXTERNAL_MERGE_CURSOR_FILE))
445        .ok()
446        .and_then(|s| s.trim().parse().ok())
447        .unwrap_or(0)
448}
449
450/// Best-effort, like every other write in this module's sweep: a failure to
451/// persist the cursor costs the fleet one pass's worth of forward progress
452/// on this sweep, never the run whose housekeeping it is racing to keep up
453/// with.
454fn write_external_merge_cursor(home: &Path, cursor: usize) {
455    if let Err(e) = std::fs::write(home.join(EXTERNAL_MERGE_CURSOR_FILE), cursor.to_string()) {
456        tracing::warn!("housekeep: persist the external-merge sweep's cursor: {e:#}");
457    }
458}
459
460/// Close the gap `magi fold --merged` exists for, without waiting for an
461/// operator to notice and go find the pull request URL: a run that stopped
462/// `Blocked` with no `merge` recorded may have been merged anyway, by hand,
463/// on a pull request `land::land` never opened or never got to observe as
464/// merged. `land::find_external_merge` asks GitHub about the run's own
465/// winning branch, and only a pull request it can uniquely tie back to this
466/// run is ever acted on - see that function's own doc for what "uniquely"
467/// excludes.
468///
469/// A run this finds and fixes goes through
470/// [`crate::land::correct_confirmed_external_merge`] - the same correction
471/// `magi fold --merged` performs, minus the same-repo guard that command
472/// needs and this loop doesn't (see that function's own doc: the URL here
473/// was never operator-supplied, it came from asking `state.repo`'s own
474/// remote) - then through [`crate::graph::fold_run`] so it stops holding
475/// worktrees the moment it stops needing them. A run this cannot decide
476/// about - `gh` unreachable, more than one candidate pull
477/// request, nothing found at all - is left exactly as it is; only an error
478/// asking GitHub raises a notice, since "nothing found" is the ordinary,
479/// expected shape of a run that really is just blocked.
480async fn reconcile_external_merges(runs: &Path, home: &Path, disk: &Disk, now: Timestamp) -> usize {
481    reconcile_external_merges_with(runs, home, disk, now, |state| async move {
482        crate::land::find_external_merge(&state).await
483    })
484    .await
485}
486
487async fn reconcile_external_merges_with<F, Fut>(
488    runs: &Path,
489    home: &Path,
490    disk: &Disk,
491    now: Timestamp,
492    check: F,
493) -> usize
494where
495    F: Fn(RunState) -> Fut,
496    Fut: std::future::Future<Output = Result<Option<crate::land::ExternalMerge>>>,
497{
498    let mut ids: Vec<String> = std::fs::read_dir(runs)
499        .into_iter()
500        .flatten()
501        .flatten()
502        .filter(|e| e.path().join("run.json").is_file())
503        .map(|e| e.file_name().to_string_lossy().into_owned())
504        .collect();
505    ids.sort_unstable();
506
507    // Every eligible id first, cheaply (a `Meta` read, no `gh`), then rotated
508    // before the cap is applied. Capping the sorted order directly would
509    // always land on the same lexicographic prefix - a fleet's oldest run ids
510    // - so a handful of long-blocked runs that never turn out to be merged
511    // would starve every id after them of a `gh` check, forever.
512    let mut eligible: Vec<String> = Vec::new();
513    for id in ids {
514        if crate::daemon::is_working_on(home, &id, now) {
515            continue;
516        }
517        let meta = match read_external_merge_meta(runs, &id) {
518            Ok(meta) => meta,
519            // Already counted as unreadable by `fold_due`'s own pass; not
520            // worth a second warning for the same file.
521            Err(_) => continue,
522        };
523        if eligible_for_external_merge_check(
524            meta.status,
525            meta.merge.is_some(),
526            meta.updated_at,
527            now,
528            disk.fold_grace_secs,
529        ) {
530            eligible.push(id);
531        }
532    }
533
534    if eligible.is_empty() {
535        return 0;
536    }
537    let cursor = read_external_merge_cursor(home);
538    let window: Vec<String> = rotate_from(&eligible, cursor)
539        .into_iter()
540        .take(MAX_EXTERNAL_MERGE_CHECKS_PER_PASS)
541        .collect();
542    // Advances by exactly how many ids this pass looked at, regardless of
543    // what came of looking - a run that turned out not to be merged after
544    // all must not be revisited before every other eligible run has had its
545    // own turn.
546    write_external_merge_cursor(home, (cursor + window.len()) % eligible.len());
547
548    let mut reconciled = 0usize;
549    for id in window {
550        let mut state = match read_state(runs, &id) {
551            Ok(state) => state,
552            Err(_) => continue,
553        };
554        if let Ok(record) = serde_json::to_value(&state)
555            && let Some(reason) =
556                crate::external_merge_attention::historical_reason(home, &id, &record)
557        {
558            tracing::info!("housekeep: external merge for {id}: {reason}");
559            continue;
560        }
561        match check(state.clone()).await {
562            Ok(Some(found)) => {
563                match crate::land::correct_confirmed_external_merge(&mut state, &found.url).await {
564                    Ok(_) => {
565                        if let Err(e) = crate::graph::fold_run(&mut state, true, home).await {
566                            tracing::warn!(
567                                "housekeep: fold {id} after recording its external merge: {e:#}"
568                            );
569                        }
570                        reconciled += 1;
571                    }
572                    Err(e) => tracing::warn!(
573                        "housekeep: record external merge {} for {id}: {e:#}",
574                        found.url
575                    ),
576                }
577            }
578            Ok(None) => {}
579            Err(e) => {
580                tracing::warn!("housekeep: check external merge for {id}: {e:#}");
581                crate::notices::raise_in(
582                    home,
583                    crate::notices::Notice::warn(
584                        &format!("merged-unrecorded:{id}"),
585                        format!(
586                            "Run {id} is blocked with no recorded merge, and checking GitHub \
587                             for a merge failed; check by hand."
588                        ),
589                    )
590                    .link(crate::notices::Link::Run { id: id.clone() }),
591                );
592            }
593        }
594    }
595    reconciled
596}
597
598/// Read a whole run state from a runs directory, for folding only.
599///
600/// Deliberately more permissive than [`RunState::load`], which this does not
601/// call: `load` backs `--resume` and every hand-driven command, where a
602/// schema this build disagrees with the *meaning* of must refuse outright
603/// rather than resume a review round or a tally against stale semantics
604/// (`RunState::SCHEMA`'s own docs list what has changed meaning at each
605/// bump). Folding recomputes nothing - it only reads worktree paths, branch
606/// names and a tally winner off the struct to remove them - so an old
607/// schema's values are exactly as good here as a current one's; every schema
608/// bump so far has only ever added a field or a variant, never repurposed an
609/// existing one, and serde already fills an added field's default when an
610/// older record has nothing to say about it. What this cannot tolerate, and
611/// what still surfaces as an `Err`, is `run.json` failing to parse at all.
612fn read_state(runs: &Path, id: &str) -> Result<RunState> {
613    let path = runs.join(id).join("run.json");
614    let body =
615        std::fs::read_to_string(&path).with_context(|| format!("read {}", path.display()))?;
616    let state: RunState =
617        serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
618    Ok(state)
619}
620
621/// Remove only verified clean Git worktrees and empty directory scaffolding.
622/// Unknown files or unreadable Git state require recovery, never recursive deletion.
623async fn remove_clean_bay(root: &Path) -> Result<()> {
624    let mut pending = vec![root.to_path_buf()];
625    let mut directories = Vec::new();
626    let mut worktrees = Vec::new();
627    while let Some(path) = pending.pop() {
628        if path.join(".git").exists() {
629            if !crate::git::is_clean(&path).await? {
630                anyhow::bail!("uncommitted work in {}; recovery required", path.display());
631            }
632            worktrees.push(path);
633        } else {
634            for entry in std::fs::read_dir(&path)? {
635                let entry = entry?;
636                if !entry.file_type()?.is_dir() {
637                    anyhow::bail!(
638                        "unknown worktree content in {}; recovery required",
639                        path.display()
640                    );
641                }
642                pending.push(entry.path());
643            }
644            directories.push(path);
645        }
646    }
647    for path in worktrees {
648        if !crate::git::worktree_remove_clean(&path, &path).await? {
649            anyhow::bail!("clean worktree removal refused: {}", path.display());
650        }
651    }
652    for path in directories.into_iter().rev() {
653        std::fs::remove_dir(path)?;
654    }
655    Ok(())
656}
657
658/// Remove a run that cannot be read: its state directory under `runs` and its
659/// worktree directory under `worktrees_root`.
660///
661/// Inspect worktrees before deleting any state or artifacts. Only clean registered
662/// worktrees and empty directory scaffolding can be reclaimed; unknown or dirty
663/// content remains available for recovery. Nonstandard worktree roots remain the
664/// operator's responsibility when the state file cannot identify them.
665pub async fn fold_unreadable(runs: &Path, worktrees_root: &Path, id: &str) -> Result<Vec<String>> {
666    let resolved = resolve_id_path(runs, id)?;
667    let mut removed = Vec::new();
668    let run_dir = runs.join(&resolved);
669    let wt = worktrees_root.join(short_of(&resolved));
670    if wt.exists() {
671        remove_clean_bay(&wt).await?;
672        removed.push(wt.to_string_lossy().into_owned());
673    }
674    // Keep the recovery artifacts if any worktree could not be removed safely.
675    if run_dir.exists() {
676        std::fs::remove_dir_all(&run_dir)
677            .with_context(|| format!("remove {}", run_dir.display()))?;
678        removed.push(format!("runs/{resolved}"));
679    }
680    Ok(removed)
681}
682
683/// Reclaim worktrees under `worktrees_root` that no run record in `runs`
684/// claims anymore, and return how many were removed.
685///
686/// [`fold_due`] only ever sees a worktree by walking `runs/` first, so a
687/// worktree whose run record is already gone — `magi run rm`, or a record
688/// deleted before its worktree — never enters that loop at all: nothing there
689/// is looking for it. This walks the worktree bay directly instead, and
690/// removes any `<short>` directory that no run id maps to.
691///
692/// Two things must never happen, and this checks both before ever touching a
693/// directory:
694///
695/// - **A worktree bay is never the only kind of thing under `worktrees_root`,
696///   and this must not assume it is.** A hand-placed scratch directory, or
697///   anything else an operator or another tool left in the same bay, has the
698///   same "no run claims it" shape as a genuine orphan but is not one -
699///   [`looks_like_a_worktree_bay`] is the same tag shape [`crate::run::is_run_id`]
700///   already requires of a real run's short id, and anything else is left
701///   alone regardless of what else is true about it.
702/// - **A worktree that was only just created might not have a `run.json` yet
703///   for a reason that has nothing to do with being orphaned.** `Runner::start`
704///   and `Runner::review` both create the worktree before the first
705///   `RunState::save` lands, and that gap - several `git` subprocesses wide -
706///   is invisible to [`crate::daemon::is_working_on_short`] whenever the run
707///   is not being driven through this daemon's own `poll` loop at all (a
708///   `magi review` invocation, for one). A directory whose own modification
709///   time is within `grace_secs` of `now` is left alone on that basis alone,
710///   the same margin [`fold_due`] gives a run before treating it as truly
711///   finished - long enough that no realistic gap between a `worktree add`
712///   and its `run.json` could ever be mistaken for one.
713///
714/// The one failure this must never cause is deleting the worktree of a run
715/// that is genuinely in flight. [`crate::daemon::is_working_on_short`] is the
716/// same liveness check [`fold_due`] trusts everywhere else in this module,
717/// checked by short id because there is no full id to compare here; when it
718/// cannot tell, this leaves the directory alone. Best-effort like the rest of
719/// housekeeping: one directory git or the filesystem refuses to give up is a
720/// `tracing::warn`, not a reason to abandon the rest of the pass.
721pub async fn fold_orphaned_worktrees(
722    runs: &Path,
723    worktrees_root: &Path,
724    home: &Path,
725    grace_secs: u64,
726    now: Timestamp,
727) -> usize {
728    let known: std::collections::HashSet<String> = std::fs::read_dir(runs)
729        .into_iter()
730        .flatten()
731        .flatten()
732        .map(|e| e.file_name().to_string_lossy().into_owned())
733        .filter(|name| crate::run::is_run_id(name))
734        .map(|id| short_of(&id).to_owned())
735        .collect();
736
737    let mut folded = 0usize;
738    for entry in std::fs::read_dir(worktrees_root)
739        .into_iter()
740        .flatten()
741        .flatten()
742    {
743        if !entry.path().is_dir() {
744            continue;
745        }
746        let short = entry.file_name().to_string_lossy().into_owned();
747        if !looks_like_a_worktree_bay(&short) {
748            continue;
749        }
750        if known.contains(&short) || crate::daemon::is_working_on_short(home, &short, now) {
751            continue;
752        }
753        let wt = entry.path();
754        if !stale_enough(&wt, grace_secs, now) {
755            continue;
756        }
757        match remove_clean_bay(&wt).await {
758            Ok(()) => folded += 1,
759            Err(e) => tracing::warn!(
760                "housekeep: remove orphaned worktree {}: {e:#}",
761                wt.display()
762            ),
763        }
764    }
765    folded
766}
767
768/// Does `name` have the shape a run's own worktree bay is named with: the
769/// same 4-character alphanumeric tag [`crate::run::is_run_id`] requires of a
770/// full id's trailing block (see [`short_of`])?
771///
772/// Anything else under `worktrees_root` is not a bay this function reclaims
773/// at all, claimed or not - answering "does a run claim this?" about a
774/// directory that was never a run's worktree in the first place is exactly
775/// the wrong question to ask before deleting it.
776fn looks_like_a_worktree_bay(name: &str) -> bool {
777    name.len() == 4 && name.bytes().all(|b| b.is_ascii_alphanumeric())
778}
779
780/// Is `dir`'s own modification time old enough, against `grace_secs` and
781/// `now`, that its emptiness of a run record can be trusted rather than
782/// caught mid-creation?
783///
784/// A directory this pass cannot stat at all - a race with its own removal, a
785/// permission error - is treated as not yet stale: unreadable metadata is not
786/// evidence of anything, and the janitor already keeps rather than deletes
787/// whenever it cannot tell (see the module docs).
788///
789/// `grace_secs` is floored at [`MIN_ORPHAN_AGE_SECS`] regardless of what the
790/// caller passes: `0` is a documented, legitimate value for
791/// [`crate::config::Disk::fold_grace_secs`] (`due`'s own "always due" case),
792/// because that grace answers a policy question the operator owns - how long
793/// a *known, finished* run's worktree lingers before cleanup. Whether an
794/// orphan worktree is actually a race with `Runner::review`'s `git worktree
795/// add` landing before its `run.json` is not a policy question, and must not
796/// collapse to zero just because the operator turned the other grace off -
797/// that would defeat the very check meant to catch it.
798fn stale_enough(dir: &Path, grace_secs: u64, now: Timestamp) -> bool {
799    let Ok(modified) = std::fs::metadata(dir).and_then(|m| m.modified()) else {
800        return false;
801    };
802    let Ok(ts) = Timestamp::try_from(modified) else {
803        return false;
804    };
805    due(now, ts, grace_secs.max(MIN_ORPHAN_AGE_SECS))
806}
807
808/// The floor under [`stale_enough`]'s grace, independent of
809/// [`crate::config::Disk::fold_grace_secs`].
810///
811/// Ample next to the race it guards: the gap between `Runner::start` or
812/// `Runner::review` creating a worktree and the first `RunState::save`
813/// landing is a handful of `git` subprocess calls, not minutes - but the
814/// janitor cannot tell "still mid-setup" from "orphaned" by any other signal
815/// for a run that never registers with `daemon::Status` at all (a `magi
816/// review` invocation, for one), so this is generous on purpose rather than
817/// tuned to the observed case.
818const MIN_ORPHAN_AGE_SECS: u64 = 5 * 60;
819
820/// Resolve an id or prefix against an explicit runs directory, exactly the way
821/// [`crate::run::resolve_id`] does against the global home.
822fn resolve_id_path(runs: &Path, prefix: &str) -> Result<String> {
823    // Keyed on the directory, not on a readable state file: the record this
824    // route exists to remove may be a lone `run.json.tmp` from a save that
825    // ran out of disk, and that is precisely the one a human needs a way to
826    // clear (see `crate::run::list_ids`).
827    if runs.join(prefix).is_dir() && crate::run::is_run_id(prefix) {
828        return Ok(prefix.to_owned());
829    }
830    let mut hits: Vec<String> = Vec::new();
831    for e in std::fs::read_dir(runs).into_iter().flatten().flatten() {
832        if !e.path().is_dir() {
833            continue;
834        }
835        let id = e.file_name().to_string_lossy().into_owned();
836        if crate::run::is_run_id(&id) && (id.starts_with(prefix) || id.ends_with(prefix)) {
837            hits.push(id);
838        }
839    }
840    match hits.len() {
841        1 => Ok(hits.into_iter().next().expect("exactly one hit")),
842        0 => bail!("no run matches `{prefix}`"),
843        _ => bail!(
844            "`{prefix}` matches {} runs: {}",
845            hits.len(),
846            hits.join(", ")
847        ),
848    }
849}
850
851/// `magi fold`'s recovery path for a run whose worktrees are already gone —
852/// so [`crate::graph::fold_run`] removed nothing — but whose `run.json` still
853/// lists active seats nobody is left to answer for: no live daemon claims the
854/// run, and every one of those seats has overrun its own timeout (see
855/// [`RunState::active_all_overrun`]). Clearing them and failing the run is
856/// what lets it be deleted afterward — [`RunState::ensure_can_delete`] only
857/// ever checks whether a live daemon is working on the run and whether its
858/// candidates are folded, not `status`, but a run stuck `implementing`
859/// forever with an empty worktree still reads as unresolved everywhere else
860/// (`magi show`, the deck, the phone) until this runs.
861///
862/// Returns `false` without changing anything when a live daemon still claims
863/// the run, or when some active seat has not actually overrun its budget yet
864/// — a run that is merely between waves must never be guessed at.
865pub fn clear_abandoned_active(state: &mut RunState, home: &Path, now: Timestamp) -> Result<bool> {
866    if crate::daemon::is_working_on(home, &state.id, now) || !state.active_all_overrun(now) {
867        return Ok(false);
868    }
869    state.abandon("fold");
870    state.save_under(home)?;
871    // The seat that asked is gone for good now - the same door
872    // `graph::Runner::settle_questions` closes the moment `status` lands
873    // somewhere non-resumable, see that method's own doc. Without this, an
874    // open question the abandoned seat left behind would keep badging the
875    // operator until the next daemon startup's `abandon_settled_questions`
876    // pass happened to notice it, or forever if nothing is running `magi
877    // serve` at all.
878    if let Err(e) = Questions::at(home.join("questions")).settle_run(&state.id, state.status) {
879        tracing::warn!("abandon questions for {}: {e:#}", state.id);
880    }
881    Ok(true)
882}
883
884/// Delete files from the shared build cache until it fits its cap — but only
885/// while nobody live is registered as using it. [`crate::cache::maintenance_prune`]
886/// takes out the same lease a build would, so a prune can never race a
887/// compile in flight (this run's own, another run's, or a human's `magi
888/// review`) into deleting a file that build still needs. `Ok(None)` when the
889/// cache is in use right now; the next pass catches it once the borrower
890/// releases it, the same way a cap of `0` or a missing `CARGO_TARGET_DIR`
891/// already meant "nothing to do this time" here.
892pub fn prune_cache(home: &Path, cache: &Path, limit_bytes: u64) -> Result<Option<Prune>> {
893    crate::cache::maintenance_prune(home, cache, limit_bytes)
894}
895
896/// [`prune_cache`], but resolving the operator's opt-out and missing
897/// `CARGO_TARGET_DIR` first — the same two checks [`housekeep`]'s idle pass
898/// makes before ever measuring the cache, factored out so
899/// [`crate::daemon`]'s between-runs check (see the module's own doc for why
900/// congestion can make "idle" arrive too rarely to matter) makes them
901/// identically rather than growing its own copy that could drift. `Ok(None)`
902/// covers a cap of `0` (see the module docs on `cache_limit_bytes`), a config
903/// that renders no `CARGO_TARGET_DIR` to aggregate at all, and a cache
904/// currently in use (see [`prune_cache`]).
905pub fn prune_cache_if_over_limit(
906    cfg: &crate::config::Config,
907    home: &Path,
908) -> Result<Option<Prune>> {
909    if cfg.disk.cache_limit_bytes == 0 {
910        return Ok(None);
911    }
912    let Some(cache) = cfg.cache_dir() else {
913        return Ok(None);
914    };
915    let limit = crate::disk::free_bytes(&cache)
916        .ok()
917        .map_or(cfg.disk.cache_limit_bytes, |free| {
918            crate::disk::pressure_limit(
919                dir_size(&cache),
920                cfg.disk.cache_limit_bytes,
921                cfg.disk.min_free_bytes,
922                free,
923            )
924        });
925    prune_cache(home, &cache, limit)
926}
927
928/// The cache's path, size and cap, for `magi cache show` and the health view.
929/// `None` when the config declares no `CARGO_TARGET_DIR` to aggregate.
930///
931/// A cap of `0` means the operator opted out of pruning; the size is then
932/// reported but never acted on.
933pub fn cache_report(cfg: &crate::config::Config) -> Option<(PathBuf, u64, u64)> {
934    let cache = cfg.cache_dir()?;
935    Some((
936        cache.clone(),
937        cache_size(&cache),
938        cfg.disk.cache_limit_bytes,
939    ))
940}
941
942/// Size in bytes of the shared build cache.
943pub fn cache_size(cache: &Path) -> u64 {
944    dir_size(cache)
945}
946
947#[cfg(test)]
948mod tests {
949
950    async fn sh(cwd: &Path, args: &[&str]) {
951        let out = crate::git::git_raw(cwd, args).await.expect("spawn git");
952        assert!(out.ok(), "git {args:?}: {}", out.stderr);
953    }
954
955    async fn commit(cwd: &Path, file: &str, body: &str) {
956        std::fs::write(cwd.join(file), body).unwrap();
957        sh(cwd, &["add", file]).await;
958        sh(
959            cwd,
960            &[
961                "-c",
962                "user.name=t",
963                "-c",
964                "user.email=t@example.com",
965                "commit",
966                "-q",
967                "-m",
968                body,
969            ],
970        )
971        .await;
972    }
973
974    const LONG: std::time::Duration = std::time::Duration::from_secs(30);
975
976    #[tokio::test]
977    async fn fetch_advances_origin_main_and_leaves_the_checkout_alone() {
978        let tmp = tempfile::tempdir().unwrap();
979        let t = tmp.path();
980        let bare = t.join("remote.git");
981        sh(
982            t,
983            &["init", "-q", "--bare", "-b", "main", bare.to_str().unwrap()],
984        )
985        .await;
986        let dir = t.join("root/h/o/r");
987        std::fs::create_dir_all(dir.parent().unwrap()).unwrap();
988        sh(
989            t,
990            &["clone", "-q", bare.to_str().unwrap(), dir.to_str().unwrap()],
991        )
992        .await;
993        sh(&dir, &["checkout", "-q", "-b", "main"]).await;
994        commit(&dir, "a.txt", "one").await;
995        sh(&dir, &["push", "-q", "origin", "main"]).await;
996        sh(&dir, &["checkout", "-q", "--detach"]).await;
997        std::fs::write(dir.join("a.txt"), "dirty").unwrap();
998
999        let other = t.join("other");
1000        sh(
1001            t,
1002            &[
1003                "clone",
1004                "-q",
1005                bare.to_str().unwrap(),
1006                other.to_str().unwrap(),
1007            ],
1008        )
1009        .await;
1010        commit(&other, "b.txt", "two").await;
1011        sh(&other, &["push", "-q", "origin", "HEAD:main"]).await;
1012
1013        let rev = |d: PathBuf, r: &'static str| async move {
1014            crate::git::git(&d, &["rev-parse", r]).await.unwrap()
1015        };
1016        let head = rev(dir.clone(), "HEAD").await;
1017        let before = rev(dir.clone(), "origin/main").await;
1018        let status = crate::git::git(&dir, &["status", "--porcelain"])
1019            .await
1020            .unwrap();
1021
1022        let r = fetch_origins(&[t.join("root")], LONG, || false).await;
1023        assert_eq!(
1024            r,
1025            FetchReport {
1026                fetched: 1,
1027                no_origin: 0,
1028                failed: 0
1029            }
1030        );
1031
1032        assert_ne!(rev(dir.clone(), "origin/main").await, before);
1033        assert_eq!(rev(dir.clone(), "HEAD").await, head);
1034        assert_eq!(
1035            crate::git::git(&dir, &["status", "--porcelain"])
1036                .await
1037                .unwrap(),
1038            status
1039        );
1040        assert_eq!(std::fs::read_to_string(dir.join("a.txt")).unwrap(), "dirty");
1041    }
1042
1043    #[tokio::test]
1044    async fn fetch_never_writes_a_local_branch_whatever_the_configured_refspec() {
1045        let tmp = tempfile::tempdir().unwrap();
1046        let t = tmp.path();
1047        let bare = t.join("remote.git");
1048        sh(
1049            t,
1050            &["init", "-q", "--bare", "-b", "main", bare.to_str().unwrap()],
1051        )
1052        .await;
1053        let dir = t.join("root/h/o/r");
1054        std::fs::create_dir_all(dir.parent().unwrap()).unwrap();
1055        sh(
1056            t,
1057            &["clone", "-q", bare.to_str().unwrap(), dir.to_str().unwrap()],
1058        )
1059        .await;
1060        sh(&dir, &["checkout", "-q", "-b", "main"]).await;
1061        commit(&dir, "a.txt", "one").await;
1062        sh(&dir, &["push", "-q", "origin", "main"]).await;
1063        sh(&dir, &["checkout", "-q", "--detach"]).await;
1064        // A hostile mapping onto the local branch, and no origin/* at all.
1065        sh(
1066            &dir,
1067            &[
1068                "config",
1069                "remote.origin.fetch",
1070                "+refs/heads/main:refs/heads/main",
1071            ],
1072        )
1073        .await;
1074        let _ = crate::git::git_raw(&dir, &["update-ref", "-d", "refs/remotes/origin/main"]).await;
1075
1076        let other = t.join("other");
1077        sh(
1078            t,
1079            &[
1080                "clone",
1081                "-q",
1082                bare.to_str().unwrap(),
1083                other.to_str().unwrap(),
1084            ],
1085        )
1086        .await;
1087        commit(&other, "b.txt", "two").await;
1088        sh(&other, &["push", "-q", "origin", "HEAD:main"]).await;
1089        let remote_tip = crate::git::git(&other, &["rev-parse", "HEAD"])
1090            .await
1091            .unwrap();
1092        let local_main = crate::git::git(&dir, &["rev-parse", "refs/heads/main"])
1093            .await
1094            .unwrap();
1095
1096        let r = fetch_origins(&[t.join("root")], LONG, || false).await;
1097        assert_eq!(r.fetched, 1);
1098        assert_eq!(
1099            crate::git::git(&dir, &["rev-parse", "refs/remotes/origin/main"])
1100                .await
1101                .unwrap(),
1102            remote_tip
1103        );
1104        assert_eq!(
1105            crate::git::git(&dir, &["rev-parse", "refs/heads/main"])
1106                .await
1107                .unwrap(),
1108            local_main
1109        );
1110    }
1111
1112    #[tokio::test]
1113    async fn fetch_skips_no_origin_and_survives_an_unreachable_origin() {
1114        let tmp = tempfile::tempdir().unwrap();
1115        let t = tmp.path();
1116        let root = t.join("root");
1117        let bare = t.join("remote.git");
1118        sh(t, &["init", "-q", "--bare", bare.to_str().unwrap()]).await;
1119
1120        let none = root.join("h/o/none");
1121        let dead = root.join("h/o/dead");
1122        let good = root.join("h/o/good");
1123        for d in [&none, &dead, &good] {
1124            std::fs::create_dir_all(d).unwrap();
1125            sh(d, &["init", "-q"]).await;
1126        }
1127        sh(
1128            &dead,
1129            &[
1130                "remote",
1131                "add",
1132                "origin",
1133                t.join("missing").to_str().unwrap(),
1134            ],
1135        )
1136        .await;
1137        sh(&good, &["remote", "add", "origin", bare.to_str().unwrap()]).await;
1138
1139        let r = fetch_origins(&[root], LONG, || false).await;
1140        assert_eq!(
1141            r,
1142            FetchReport {
1143                fetched: 1,
1144                no_origin: 1,
1145                failed: 1
1146            }
1147        );
1148    }
1149    use super::*;
1150    use crate::config::Disk;
1151    use std::fs;
1152
1153    fn ts(s: &str) -> Timestamp {
1154        s.parse().expect("rfc3339")
1155    }
1156
1157    fn block_on<F: std::future::Future>(f: F) -> F::Output {
1158        tokio::runtime::Runtime::new().expect("runtime").block_on(f)
1159    }
1160
1161    #[test]
1162    fn a_run_is_due_after_its_grace_and_not_before() {
1163        let now = ts("2026-09-05T00:00:00Z");
1164        let grace = 600;
1165        let old = now - SignedDuration::new(601, 0);
1166        let fresh = now - SignedDuration::new(599, 0);
1167        assert!(due(now, old, grace));
1168        assert!(!due(now, fresh, grace));
1169        // Exactly at the edge: not yet due.
1170        let edge = now - SignedDuration::new(600, 0);
1171        assert!(!due(now, edge, grace));
1172        // A zero grace folds everything, ever.
1173        assert!(due(now, old, 0));
1174    }
1175
1176    #[test]
1177    fn rotate_from_moves_the_starting_point_as_the_cursor_advances() {
1178        let ids: Vec<String> = ["a", "b", "c", "d", "e"]
1179            .iter()
1180            .map(|s| s.to_string())
1181            .collect();
1182
1183        // A cursor of 0 starts at the front, same as an unrotated list.
1184        assert_eq!(rotate_from(&ids, 0), ids);
1185
1186        // A cursor of 2 starts two ids further along, with the skipped
1187        // front wrapping to the tail rather than being dropped.
1188        let at_2 = rotate_from(&ids, 2);
1189        assert_eq!(at_2, vec!["c", "d", "e", "a", "b"]);
1190        for id in &ids {
1191            assert!(at_2.contains(id));
1192        }
1193
1194        // A cursor past the list's own length wraps rather than panicking -
1195        // the caller never has to reduce it modulo anything itself.
1196        assert_eq!(rotate_from(&ids, 7), rotate_from(&ids, 2));
1197
1198        // An empty list has no start point to compute and must not panic.
1199        assert_eq!(rotate_from(&[], 0), Vec::<String>::new());
1200    }
1201
1202    /// A fleet with more eligible runs than one pass can check must not park
1203    /// the same handful at the front of the window forever: advancing the
1204    /// cursor by exactly how many ids one pass actually looked at - the
1205    /// arithmetic [`reconcile_external_merges`] itself does - walks every id
1206    /// to the front within one full rotation, with no reliance on how often
1207    /// or how regularly passes happen to run.
1208    #[test]
1209    fn advancing_the_cursor_by_the_window_size_gives_every_id_a_turn() {
1210        let ids: Vec<String> = (0..12).map(|n| format!("run-{n}")).collect();
1211        let cap = 5usize;
1212        let mut cursor = 0usize;
1213        let mut ever_seen: std::collections::HashSet<String> = std::collections::HashSet::new();
1214        for _ in 0..ids.len() {
1215            let window: Vec<String> = rotate_from(&ids, cursor).into_iter().take(cap).collect();
1216            ever_seen.extend(window.iter().cloned());
1217            cursor = (cursor + window.len()) % ids.len();
1218        }
1219        assert_eq!(
1220            ever_seen.len(),
1221            ids.len(),
1222            "every id must be checked at least once across a full rotation, whatever \
1223             the cadence between passes"
1224        );
1225    }
1226
1227    #[test]
1228    fn the_external_merge_cursor_round_trips_through_a_files_absence() {
1229        let dir = tempfile::tempdir().unwrap();
1230        let home = dir.path();
1231
1232        // Nothing written yet: starts at 0, not an error.
1233        assert_eq!(read_external_merge_cursor(home), 0);
1234
1235        write_external_merge_cursor(home, 7);
1236        assert_eq!(read_external_merge_cursor(home), 7);
1237
1238        // Anything unreadable as a plain number falls back to 0 rather than
1239        // wedging the sweep on a corrupt file.
1240        std::fs::write(home.join(EXTERNAL_MERGE_CURSOR_FILE), "not a number").unwrap();
1241        assert_eq!(read_external_merge_cursor(home), 0);
1242    }
1243
1244    #[test]
1245    fn a_run_qualifies_for_an_external_merge_check_only_when_blocked_unmerged_and_due() {
1246        let now = ts("2026-09-05T00:00:00Z");
1247        let grace = 600;
1248        let old = now - SignedDuration::new(601, 0);
1249        let fresh = now - SignedDuration::new(599, 0);
1250
1251        assert!(
1252            eligible_for_external_merge_check(RunStatus::Blocked, false, old, now, grace),
1253            "blocked, unmerged, and past its grace period is exactly the run this exists for"
1254        );
1255        assert!(
1256            !eligible_for_external_merge_check(RunStatus::Blocked, false, fresh, now, grace),
1257            "an operator mid-fix deserves the same grace window `fold_due` gives before \
1258             the janitor starts asking GitHub about it"
1259        );
1260        assert!(
1261            !eligible_for_external_merge_check(RunStatus::Blocked, true, old, now, grace),
1262            "a run `land::land` already recorded a merge outcome for has its own answer \
1263             already; this check is only for a run with nothing recorded at all"
1264        );
1265        assert!(
1266            !eligible_for_external_merge_check(RunStatus::Stalled, false, old, now, grace),
1267            "stalled is not blocked - it means the tally never reached quorum, which a \
1268             pull request cannot fix"
1269        );
1270        assert!(
1271            !eligible_for_external_merge_check(RunStatus::Ready, false, old, now, grace),
1272            "ready has nothing to correct - it was never landed by design"
1273        );
1274        assert!(
1275            !eligible_for_external_merge_check(RunStatus::Superseded, false, old, now, grace),
1276            "a superseded run's task already has its answer from a later attempt; \
1277             there is nothing left for GitHub to confirm here"
1278        );
1279    }
1280
1281    /// A blocked run with a winner in an isolated repository directory.
1282    /// Consumer tests inject forge results without invoking a real CLI.
1283    fn write_blocked_run(runs: &Path, id: &str, updated_at: Timestamp) {
1284        use crate::run::{Candidate, Tally};
1285        use std::collections::BTreeMap;
1286
1287        let mut state = RunState::new(
1288            runs.parent().unwrap().to_path_buf(),
1289            "main".to_owned(),
1290            "0000000000000000000000000000000000000000".to_owned(),
1291            String::new(),
1292            crate::config::Config::default(),
1293        );
1294        state.id = id.to_owned();
1295        state.status = RunStatus::Blocked;
1296        state.updated_at = updated_at;
1297        state.candidates.push(Candidate {
1298            index: 0,
1299            label: 'A',
1300            agent: "agent".to_owned(),
1301            branch: format!("magi/{id}/A"),
1302            worktree: runs.parent().unwrap().join("candidate"),
1303            summary: String::new(),
1304            stat: String::new(),
1305            files: 0,
1306            commits: 0,
1307            empty: false,
1308            failed: None,
1309            verified_noop: None,
1310            duration_ms: 0,
1311            folded: false,
1312        });
1313        state.tally = Some(Tally {
1314            first_choice: BTreeMap::from([('A', 1)]),
1315            borda: BTreeMap::new(),
1316            winner: 'A',
1317            rankings: 1,
1318            unanimous_initial: true,
1319            deliberated: false,
1320            changed_votes: 0,
1321            unanimous_final: true,
1322            tie_break: None,
1323            judges: 1,
1324            present: 1,
1325            quorum: 1,
1326            met_quorum: true,
1327            uncontested: None,
1328        });
1329        std::fs::create_dir_all(runs.join(id)).unwrap();
1330        std::fs::write(
1331            runs.join(id).join("run.json"),
1332            serde_json::to_string_pretty(&state).unwrap(),
1333        )
1334        .unwrap();
1335    }
1336
1337    /// No run here can be confirmed merged - one has a forge error,
1338    /// one has not sat blocked long enough, and one is
1339    /// claimed by a live daemon - so the sweep must leave every one of them
1340    /// exactly as it found them and never panic on the failures in between.
1341    #[tokio::test]
1342    async fn reconcile_external_merges_leaves_ineligible_and_unconfirmable_runs_alone() {
1343        let dir = tempfile::tempdir().unwrap();
1344        let runs = dir.path().join("runs");
1345        let home = dir.path().to_path_buf();
1346        std::fs::create_dir_all(&runs).unwrap();
1347
1348        let now = ts("2026-09-05T00:00:00Z");
1349        let disk = Disk {
1350            fold_grace_secs: 600,
1351            ..Disk::default()
1352        };
1353
1354        let due_id = "20260905-000000-blkd";
1355        write_blocked_run(&runs, due_id, ts("2026-08-01T00:00:00Z"));
1356
1357        let fresh_id = "20260905-000000-fres";
1358        write_blocked_run(&runs, fresh_id, now);
1359
1360        let live_id = "20260905-000000-live";
1361        write_blocked_run(&runs, live_id, ts("2026-08-01T00:00:00Z"));
1362        let mut status = crate::daemon::Status::new();
1363        status.current = vec![crate::daemon::Current {
1364            worker: None,
1365            task: "20260905-000000-task".to_owned(),
1366            run: live_id.to_owned(),
1367        }];
1368        status.updated_at = now;
1369        crate::daemon::write_status_to(&home.join("daemon.json"), &status).unwrap();
1370
1371        let reconciled = reconcile_external_merges_with(&runs, &home, &disk, now, |_| async {
1372            anyhow::bail!("injected forge authentication failure")
1373        })
1374        .await;
1375        assert_eq!(reconciled, 0, "a forge failure can never confirm a merge");
1376        for id in [due_id, fresh_id, live_id] {
1377            assert_eq!(
1378                read_meta(&runs, id).unwrap().status,
1379                RunStatus::Blocked,
1380                "{id} must be left exactly as it was found"
1381            );
1382        }
1383        let notices = crate::notices::Notices::at(home.join("notifications")).list();
1384        let due_notice = notices
1385            .iter()
1386            .find(|n| n.key == format!("merged-unrecorded:{due_id}"))
1387            .expect("notice for due_id must be raised");
1388        assert_eq!(
1389            due_notice.link,
1390            Some(crate::notices::Link::Run {
1391                id: due_id.to_owned(),
1392            })
1393        );
1394    }
1395
1396    #[tokio::test]
1397    async fn historical_external_merge_check_preserves_unknown_history() {
1398        let home = tempfile::tempdir().unwrap();
1399        let runs = home.path().join("runs");
1400        let id = "legacy";
1401        write_blocked_run(&runs, id, ts("2026-08-01T00:00:00Z"));
1402        let path = runs.join(id).join("run.json");
1403        let mut state = read_state(&runs, id).unwrap();
1404        state.repo = home.path().join("removed");
1405        state.candidates[0].folded = true;
1406        let original = serde_json::to_vec(&state).unwrap();
1407        std::fs::write(&path, &original).unwrap();
1408        let count = reconcile_external_merges_with(
1409            &runs,
1410            home.path(),
1411            &Disk::default(),
1412            ts("2026-11-14T00:00:00Z"),
1413            |_| async { panic!("historical unavailable checkout must not invoke the forge") },
1414        )
1415        .await;
1416        assert_eq!(count, 0);
1417        assert_eq!(std::fs::read(&path).unwrap(), original);
1418        assert!(
1419            crate::notices::Notices::at(home.path().join("notifications"))
1420                .all()
1421                .is_empty()
1422        );
1423
1424        // The same folded run is actionable when a current task owns it.
1425        let queue = crate::queue::Queue::at(home.path().join("queue"));
1426        let mut task = crate::queue::Task::new(
1427            "current".into(),
1428            "current".into(),
1429            state.repo.clone(),
1430            crate::queue::Source::Human,
1431        );
1432        task.runs.push(id.into());
1433        queue.put(&mut task).unwrap();
1434        reconcile_external_merges_with(
1435            &runs,
1436            home.path(),
1437            &Disk::default(),
1438            ts("2026-11-14T00:00:00Z"),
1439            |_| async { anyhow::bail!("current checkout unavailable") },
1440        )
1441        .await;
1442        assert_eq!(
1443            crate::notices::Notices::at(home.path().join("notifications"))
1444                .list()
1445                .len(),
1446            1
1447        );
1448        assert_eq!(std::fs::read(&path).unwrap(), original);
1449    }
1450
1451    /// The bug this exists to pin: a first version rotated on
1452    /// `now.as_second() % len`, which is fully determined by wall-clock time
1453    /// and nothing else. Two passes seconds apart - as they would be when a
1454    /// short poll interval and a fast pass alias onto the same handful of
1455    /// `now.as_second()` residues - landed on the *same* starting point and
1456    /// never covered a fleet bigger than the per-pass cap, however many
1457    /// times housekeeping ran. Persisting a cursor makes forward progress a
1458    /// function of how many ids got looked at, not of when the clock reads
1459    /// this pass happened to run.
1460    #[tokio::test]
1461    async fn reconcile_external_merges_covers_a_larger_fleet_across_repeated_passes_at_one_instant()
1462    {
1463        let dir = tempfile::tempdir().unwrap();
1464        let runs = dir.path().join("runs");
1465        let home = dir.path().to_path_buf();
1466        std::fs::create_dir_all(&runs).unwrap();
1467
1468        let now = ts("2026-09-05T00:00:00Z");
1469        let disk = Disk {
1470            fold_grace_secs: 600,
1471            ..Disk::default()
1472        };
1473        let old = ts("2026-08-01T00:00:00Z");
1474
1475        let ids: Vec<String> = (0..8).map(|n| format!("20260905-000000-r{n:03}")).collect();
1476        for id in &ids {
1477            write_blocked_run(&runs, id, old);
1478        }
1479
1480        let notices = crate::notices::Notices::at(home.join("notifications"));
1481
1482        // Two passes at the exact same `now`, exactly what a fast pass on a
1483        // short poll interval looks like. Each of the 8 injected forge-failure
1484        // runs raises its own notice the first time it is looked at, so the
1485        // count of distinct notices is a direct readout of how many distinct
1486        // ids have been checked so far.
1487        reconcile_external_merges_with(&runs, &home, &disk, now, |_| async {
1488            anyhow::bail!("injected forge authentication failure")
1489        })
1490        .await;
1491        let after_first = notices.list().len();
1492        assert_eq!(
1493            after_first, MAX_EXTERNAL_MERGE_CHECKS_PER_PASS,
1494            "the first pass checks exactly one cap's worth"
1495        );
1496
1497        reconcile_external_merges_with(&runs, &home, &disk, now, |_| async {
1498            anyhow::bail!("injected forge authentication failure")
1499        })
1500        .await;
1501        let after_second = notices.list().len();
1502        assert_eq!(
1503            after_second,
1504            ids.len(),
1505            "a second pass at the same instant must still reach every id the \
1506             first pass had no room for, not repeat the same cap's worth"
1507        );
1508    }
1509
1510    #[test]
1511    fn the_meta_reader_is_tolerant_of_everything_except_the_deciders() {
1512        let dir = tempfile::tempdir().unwrap();
1513        let runs = dir.path().join("runs");
1514        let id = "20260905-000000-abcd";
1515        std::fs::create_dir_all(runs.join(id)).unwrap();
1516        std::fs::write(
1517            runs.join(id).join("run.json"),
1518            r#"{"schema": 99, "id": "20260905-000000-abcd", "updated_at": "2026-09-05T00:00:00Z", "status": "ready", "junk_from_another_build": [1, 2, 3]}"#,
1519        )
1520        .unwrap();
1521        let meta = read_meta(&runs, id).expect("readable");
1522        assert_eq!(meta.status, RunStatus::Ready);
1523        assert_eq!(meta.updated_at, ts("2026-09-05T00:00:00Z"));
1524        assert!(read_meta(&runs, "nope").is_err(), "missing file unreadable");
1525        std::fs::write(runs.join(id).join("run.json"), "not json at all").unwrap();
1526        assert!(read_meta(&runs, id).is_err(), "garbage unreadable");
1527    }
1528
1529    #[test]
1530    fn fold_unreadable_preserves_unknown_content_and_recovery_artifacts() {
1531        let dir = tempfile::tempdir().unwrap();
1532        let runs = dir.path().join("runs");
1533        let wt = dir.path().join("wt");
1534        let id = "20260905-000000-abcd";
1535        std::fs::create_dir_all(runs.join(id).join("artifacts")).unwrap();
1536        std::fs::write(runs.join(id).join("run.json"), "garbage").unwrap();
1537        std::fs::create_dir_all(wt.join("abcd")).unwrap();
1538        std::fs::write(wt.join("abcd/leftover"), "owned edits").unwrap();
1539        assert!(block_on(fold_unreadable(&runs, &wt, id)).is_err());
1540        assert!(runs.join(id).join("artifacts").exists());
1541        assert_eq!(
1542            std::fs::read_to_string(wt.join("abcd/leftover")).unwrap(),
1543            "owned edits"
1544        );
1545    }
1546
1547    #[test]
1548    fn fold_unreadable_releases_run_dir_and_worktrees() {
1549        let dir = tempfile::tempdir().unwrap();
1550        let runs = dir.path().join("runs");
1551        let wt = dir.path().join("wt");
1552        let id = "20260905-000000-abcd";
1553        std::fs::create_dir_all(runs.join(id)).unwrap();
1554        std::fs::write(runs.join(id).join("run.json"), "garbage").unwrap();
1555        std::fs::create_dir_all(wt.join("abcd")).unwrap();
1556
1557        let removed = block_on(fold_unreadable(&runs, &wt, id)).expect("fold");
1558        assert_eq!(removed.len(), 2);
1559        assert!(!runs.join(id).exists(), "run dir gone");
1560        assert!(!wt.join("abcd").exists(), "worktrees gone");
1561
1562        // A prefix resolves like `run::resolve_id` does.
1563        std::fs::create_dir_all(runs.join(id)).unwrap();
1564        std::fs::write(runs.join(id).join("run.json"), "garbage").unwrap();
1565        std::fs::create_dir_all(wt.join("abcd")).unwrap();
1566        let removed = block_on(fold_unreadable(&runs, &wt, "20260905")).expect("by prefix");
1567        assert_eq!(removed.len(), 2);
1568        // Once gone, `id` cannot be resolved at all - same as `run::resolve_id`
1569        // on an id nothing on disk matches - so a repeat pass errors rather
1570        // than silently reporting nothing removed.
1571        assert!(
1572            block_on(fold_unreadable(&runs, &wt, id)).is_err(),
1573            "a run already gone cannot be resolved again"
1574        );
1575    }
1576
1577    #[test]
1578    fn prune_cache_sheds_the_oldest_generation_until_it_fits() {
1579        let home = tempfile::tempdir().unwrap();
1580        let dir = tempfile::tempdir().unwrap();
1581        // Same size, different age: only the age decides, and the newest
1582        // generation - the one the next build reuses - is what survives.
1583        fs::write(dir.path().join("old"), b"xx").unwrap();
1584        fs::write(dir.path().join("new"), b"yy").unwrap();
1585        touch(&dir.path().join("old"), 1_000_000);
1586        touch(&dir.path().join("new"), 2_000_000);
1587
1588        let out = prune_cache(home.path(), dir.path(), 2)
1589            .expect("prune")
1590            .expect("the cache is free");
1591        assert_eq!(out.files, 1, "one deletion is enough to reach the cap");
1592        assert_eq!(out.remaining, 2);
1593        assert!(!dir.path().join("old").exists(), "the older file went");
1594        assert!(dir.path().join("new").exists(), "the newer one stayed");
1595
1596        // A whole generation shares one timestamp tick, so the tie has to be
1597        // decided too: largest first, which reaches the cap in the fewest
1598        // deletions. Left to `read_dir` and an unstable sort this deleted
1599        // both files on Linux and one on Windows.
1600        let tied = tempfile::tempdir().unwrap();
1601        fs::write(tied.path().join("big"), b"xxxx").unwrap();
1602        fs::write(tied.path().join("small"), b"yy").unwrap();
1603        touch(&tied.path().join("big"), 1_000_000);
1604        touch(&tied.path().join("small"), 1_000_000);
1605        let out = prune_cache(home.path(), tied.path(), 2)
1606            .expect("prune")
1607            .expect("the cache is free");
1608        assert_eq!(out.files, 1, "the big one alone gets under the cap");
1609        assert_eq!(out.remaining, 2);
1610        assert!(tied.path().join("small").exists());
1611    }
1612
1613    #[test]
1614    fn prune_cache_if_over_limit_resolves_the_opt_outs_before_ever_measuring() {
1615        let home = tempfile::tempdir().unwrap();
1616        let dir = tempfile::tempdir().unwrap();
1617        fs::write(dir.path().join("big"), vec![0u8; 10]).unwrap();
1618
1619        let mut cfg = crate::config::Config::default();
1620        cfg.verify.gate = vec![format!(
1621            "CARGO_TARGET_DIR={} cargo make check",
1622            dir.path().display()
1623        )];
1624
1625        // A cap of `0` is the operator's opt-out: never measured, never
1626        // pruned, regardless of what is actually on disk.
1627        cfg.disk.cache_limit_bytes = 0;
1628        assert_eq!(
1629            prune_cache_if_over_limit(&cfg, home.path()).unwrap(),
1630            None,
1631            "a zero cap must not even look at the directory"
1632        );
1633        assert!(dir.path().join("big").exists());
1634
1635        // No `CARGO_TARGET_DIR` in either verify command: nothing to
1636        // aggregate, so there is nothing to prune either.
1637        let mut no_cache = crate::config::Config::default();
1638        no_cache.disk.cache_limit_bytes = 1;
1639        assert_eq!(
1640            prune_cache_if_over_limit(&no_cache, home.path()).unwrap(),
1641            None
1642        );
1643
1644        // Over the cap and configured: pruned exactly like `prune_cache`
1645        // itself would.
1646        cfg.disk.cache_limit_bytes = 1;
1647        let pruned = prune_cache_if_over_limit(&cfg, home.path())
1648            .unwrap()
1649            .expect("a real cache dir over its cap prunes");
1650        assert_eq!(pruned.files, 1);
1651        assert!(!dir.path().join("big").exists());
1652    }
1653
1654    /// Pin a file's mtime, so a test asserts the policy and not the runner's
1655    /// timestamp granularity.
1656    fn touch(path: &Path, secs: u64) {
1657        let f = fs::File::options().write(true).open(path).unwrap();
1658        f.set_times(fs::FileTimes::new().set_modified(
1659            std::time::SystemTime::UNIX_EPOCH + std::time::Duration::from_secs(secs),
1660        ))
1661        .unwrap();
1662    }
1663
1664    /// The disk-full casualty: a run whose first save left `run.json.tmp` and
1665    /// nothing else. It has to be clearable, or the record is permanent.
1666    #[test]
1667    fn fold_unreadable_clears_a_run_whose_state_never_landed() {
1668        let dir = tempfile::tempdir().unwrap();
1669        let runs = dir.path().join("runs");
1670        let wt = dir.path().join("wt");
1671        let id = "20260904-014540-88c0";
1672        std::fs::create_dir_all(runs.join(id)).unwrap();
1673        std::fs::write(runs.join(id).join("run.json.tmp"), b"").unwrap();
1674
1675        let removed = block_on(fold_unreadable(&runs, &wt, id)).expect("fold by id");
1676        assert_eq!(removed, vec![format!("runs/{id}")]);
1677        assert!(!runs.join(id).exists(), "record gone");
1678
1679        // And by prefix, the way the deck and the phone address a run.
1680        std::fs::create_dir_all(runs.join(id)).unwrap();
1681        std::fs::write(runs.join(id).join("run.json.tmp"), b"").unwrap();
1682        assert!(
1683            block_on(fold_unreadable(&runs, &wt, "88c0")).is_ok(),
1684            "by prefix"
1685        );
1686
1687        // A directory under `runs` that is not a run is never a fold target.
1688        std::fs::create_dir_all(runs.join("scratch")).unwrap();
1689        assert!(
1690            block_on(fold_unreadable(&runs, &wt, "scratch")).is_err(),
1691            "a stray directory is not a run"
1692        );
1693    }
1694
1695    #[test]
1696    fn fold_due_folds_terminal_runs_of_any_schema_but_leaves_genuinely_unreadable_ones() {
1697        let dir = tempfile::tempdir().unwrap();
1698        let runs = dir.path().join("runs");
1699        let wt = dir.path().join("wt");
1700        let home = dir.path().to_path_buf();
1701        let disk = Disk::default();
1702        let now = ts("2026-09-05T00:00:00Z");
1703
1704        // 1. Runnable (judging): never folded, however old.
1705        let judging = "20260801-000000-0001";
1706        write_meta(&runs, judging, "judging", "2026-08-01T00:00:00Z");
1707
1708        // 2. Finished but fresh: grace not elapsed. Within the default 6h
1709        //    grace of `now`, so `fold_due` must stop at the freshness check
1710        //    and never even reach `read_state` - `write_meta`'s minimal JSON
1711        //    would fail that full parse anyway, and this case exists to
1712        //    prove freshness is why the run survives, not an accident of the
1713        //    fixture being unparseable as a whole `RunState`.
1714        let ready_fresh = "20260904-220000-0002";
1715        write_meta(&runs, ready_fresh, "ready", "2026-09-04T22:00:00Z");
1716
1717        // 3. Genuinely unreadable: broken JSON, not merely an unfamiliar
1718        //    schema number. Left alone and counted - this is the one case
1719        //    automatic housekeeping must never touch (see `fold_due`'s docs);
1720        //    discarding it is an explicit operator action, not something a
1721        //    background pass does.
1722        let garbage = "20260901-000000-0004";
1723        std::fs::create_dir_all(runs.join(garbage)).unwrap();
1724        std::fs::write(runs.join(garbage).join("run.json"), "not json").unwrap();
1725        std::fs::create_dir_all(wt.join("0004")).unwrap();
1726
1727        // 4. Finished, well past grace, current schema: the ordinary case
1728        //    `fold_due` has always acted on.
1729        let due_ready = due_run(&runs, &wt, "20260801-000000-ffff", SCHEMA);
1730
1731        // 5. Finished, well past grace, but written by a schema number this
1732        //    build no longer matches - the defect this task exists to fix.
1733        //    It still parses cleanly, so only the version number differs, and
1734        //    that alone must not block folding.
1735        let due_old_schema = due_run(&runs, &wt, "20260801-000000-eeee", SCHEMA - 1);
1736
1737        let (folded, unreadable) =
1738            block_on(fold_due(&runs, &home, &wt, &disk, now)).expect("fold_due");
1739        assert_eq!(
1740            folded, 2,
1741            "both due, parseable runs fold regardless of their schema number"
1742        );
1743        assert_eq!(
1744            unreadable, 1,
1745            "only the run with broken JSON counts as unreadable"
1746        );
1747        assert!(runs.join(judging).exists(), "runnable never folded");
1748        assert!(runs.join(ready_fresh).exists(), "fresh never folded");
1749        assert!(runs.join(garbage).exists(), "unreadable record kept");
1750        assert!(wt.join("0004").exists(), "unreadable worktree kept");
1751        assert!(
1752            runs.join(&due_ready).exists(),
1753            "folding drops worktrees, not the record"
1754        );
1755        assert!(
1756            runs.join(&due_old_schema).exists(),
1757            "an old-schema record survives its fold exactly like a current one"
1758        );
1759        // `graph::fold_run` saves the state it just folded back to disk. That
1760        // write must land under this test's own `runs` - the argument it
1761        // passed to `fold_due`, not the process-global `run::home` - or a
1762        // fold that landed somewhere else entirely would still be counted
1763        // above as one of the two `folded` runs.
1764        for id in [&due_ready, &due_old_schema] {
1765            let saved = read_meta(&runs, id).expect("folded run still parses");
1766            assert_ne!(
1767                saved.updated_at,
1768                ts("2026-08-01T00:00:00Z"),
1769                "fold_run must have saved the updated state back through the \
1770                 `runs` directory this test passed to fold_due"
1771            );
1772        }
1773    }
1774
1775    /// `[disk] auto_fold = false` must leave the janitor's fold-and-reclaim
1776    /// passes completely inert - a due run's worktree and record both
1777    /// survive exactly as if `housekeep` had never run at all. Cache pruning
1778    /// is a separate opt-out (`cache_limit_bytes`) and stays disabled here
1779    /// too, so this test is only ever about `auto_fold`.
1780    #[tokio::test]
1781    async fn housekeep_leaves_everything_alone_when_auto_fold_is_disabled() {
1782        let dir = tempfile::tempdir().unwrap();
1783        let runs = dir.path().join("runs");
1784        let wt = dir.path().join("wt");
1785        let home = dir.path().to_path_buf();
1786        crate::run::set_home(dir.path().to_path_buf());
1787
1788        let due_id = due_run(&runs, &wt, "20260801-000000-abcd", SCHEMA);
1789        std::fs::create_dir_all(wt.join("orphan").join("cand-A")).unwrap();
1790
1791        let mut cfg = crate::config::Config::default();
1792        cfg.disk.auto_fold = false;
1793        cfg.disk.cache_limit_bytes = 0;
1794
1795        let out = housekeep(&cfg, &home, &wt, &dir.path().join("repo"), Timestamp::now()).await;
1796
1797        assert_eq!(out.folded, 0);
1798        assert_eq!(out.unreadable, 0);
1799        assert_eq!(out.orphaned_worktrees, 0);
1800        assert!(
1801            runs.join(&due_id).exists(),
1802            "a due run's record survives untouched"
1803        );
1804        assert!(
1805            wt.join("orphan").exists(),
1806            "an orphaned worktree survives untouched: the reclaim pass never ran"
1807        );
1808    }
1809
1810    #[test]
1811    fn fold_orphaned_worktrees_removes_only_worktrees_no_run_claims_and_none_in_flight() {
1812        let dir = tempfile::tempdir().unwrap();
1813        let runs = dir.path().join("runs");
1814        let wt = dir.path().join("wt");
1815        let home = dir.path().to_path_buf();
1816
1817        // A run record exists for this one: its worktree is claimed, not
1818        // orphaned, however old the record.
1819        write_meta(
1820            &runs,
1821            "20260801-000000-aaaa",
1822            "ready",
1823            "2026-08-01T00:00:00Z",
1824        );
1825        std::fs::create_dir_all(wt.join("aaaa").join("cand-A")).unwrap();
1826
1827        // No run record at all, and nobody is working on it: this is the
1828        // leftover `fold_due` can never see, because it only ever walks
1829        // `runs/`.
1830        std::fs::create_dir_all(wt.join("bbbb").join("cand-A")).unwrap();
1831
1832        // No run record either, but a live daemon status names a run with
1833        // this short id - the save-timing gap between the daemon claiming a
1834        // task and `RunState::new` writing its first `run.json`. Must survive
1835        // untouched.
1836        std::fs::create_dir_all(wt.join("cccc")).unwrap();
1837
1838        // Not shaped like a run's short id at all - a scratch directory an
1839        // operator or another tool left in the same bay - so it is never a
1840        // reclaim target regardless of what runs claim it or not.
1841        std::fs::create_dir_all(wt.join("scratch")).unwrap();
1842
1843        // `now` pushed comfortably past `MIN_ORPHAN_AGE_SECS`, so a zero
1844        // grace - the same "always due" escape hatch `due` itself documents
1845        // - still reclaims once a worktree is genuinely old, without faking
1846        // an mtime: real directory creation just above is already in the
1847        // past relative to this `now`, by design rather than by timing.
1848        let now = Timestamp::now() + SignedDuration::new((MIN_ORPHAN_AGE_SECS + 1) as i64, 0);
1849        let mut status = crate::daemon::Status::new();
1850        status.current = vec![crate::daemon::Current {
1851            worker: None,
1852            task: "20260905-000000-t111".to_owned(),
1853            run: "20260905-000000-cccc".to_owned(),
1854        }];
1855        status.updated_at = now;
1856        crate::daemon::write_status_to(&home.join("daemon.json"), &status).unwrap();
1857
1858        let folded = block_on(fold_orphaned_worktrees(&runs, &wt, &home, 0, now));
1859        assert_eq!(
1860            folded, 1,
1861            "only the truly orphaned, idle, bay-shaped worktree is removed"
1862        );
1863        assert!(wt.join("aaaa").exists(), "claimed by a run record");
1864        assert!(!wt.join("bbbb").exists(), "orphaned and idle: reclaimed");
1865        assert!(wt.join("cccc").exists(), "a run in flight is never touched");
1866        assert!(
1867            wt.join("scratch").exists(),
1868            "not shaped like a worktree bay, so never a reclaim target"
1869        );
1870    }
1871
1872    /// The gap this closes: `Runner::review` (`magi review`) creates the
1873    /// worktree with `git worktree add` before `RunState::save` ever writes a
1874    /// `run.json`, and that path never runs through the daemon's own `poll`
1875    /// loop at all, so `daemon::Status` never names it either. Without a
1876    /// grace window, a janitor pass landing in that gap would read the
1877    /// worktree as an orphan nothing is waiting on and delete a review still
1878    /// being set up.
1879    #[test]
1880    fn fold_orphaned_worktrees_leaves_a_freshly_created_bay_alone() {
1881        let dir = tempfile::tempdir().unwrap();
1882        let runs = dir.path().join("runs");
1883        let wt = dir.path().join("wt");
1884        let home = dir.path().to_path_buf();
1885
1886        std::fs::create_dir_all(wt.join("dddd").join("under-review")).unwrap();
1887
1888        let now = Timestamp::now();
1889        let folded = block_on(fold_orphaned_worktrees(&runs, &wt, &home, 6 * 60 * 60, now));
1890        assert_eq!(
1891            folded, 0,
1892            "too fresh to tell apart from a run still being set up"
1893        );
1894        assert!(wt.join("dddd").exists());
1895    }
1896
1897    /// A fresh open question on `run`, stored and handed back for assertions.
1898    fn open_question(store: &Questions, run: &str) -> crate::ask::Question {
1899        let mut q = crate::ask::Question::new(
1900            run.to_owned(),
1901            "implement".to_owned(),
1902            "impl-A".to_owned(),
1903            "Which storage backend should the cache use?".to_owned(),
1904            String::new(),
1905            vec!["SQLite".to_owned(), "Redis".to_owned()],
1906        );
1907        store.put(&mut q).unwrap();
1908        q
1909    }
1910
1911    /// The exact ghost the phone showed: a run that already finished, with a
1912    /// question its dead seat asked still sitting `open` because it reached
1913    /// that status before `graph::Runner::settle_questions` existed (or
1914    /// missed it in the crash window `daemon::reclaim_orphaned_running`
1915    /// covers). This sweep is the second door to the same fact.
1916    #[test]
1917    fn a_finished_runs_open_question_is_swept_up() {
1918        let dir = tempfile::tempdir().unwrap();
1919        let runs = dir.path().join("runs");
1920        let store = Questions::at(dir.path().join("questions"));
1921
1922        let failed = "20260908-205802-c9eb";
1923        write_meta(&runs, failed, "failed", "2026-09-08T20:58:02Z");
1924        let failed_q = open_question(&store, failed);
1925
1926        let merged = "20260908-205501-ca67";
1927        write_meta(&runs, merged, "merged", "2026-09-08T20:55:01Z");
1928        let merged_q = open_question(&store, merged);
1929
1930        let n = abandon_settled_questions(&store, &runs);
1931        assert_eq!(n, 2, "both dead runs' questions are swept in one pass");
1932
1933        for (id, run) in [(&failed_q.id, failed), (&merged_q.id, merged)] {
1934            let back = store.get(id).unwrap();
1935            assert!(!back.status.open(), "{run} is done; nobody reads an answer");
1936            assert!(back.detail.contains(run), "{}", back.detail);
1937        }
1938    }
1939
1940    #[test]
1941    fn a_still_alive_runs_open_question_survives_the_sweep() {
1942        let dir = tempfile::tempdir().unwrap();
1943        let runs = dir.path().join("runs");
1944        let store = Questions::at(dir.path().join("questions"));
1945
1946        // `Blocked` and `Stalled` are `RunStatus::resumable`: the run can
1947        // still be picked back up, so its question may yet get a real
1948        // answer. A run still mid-competition is even more obviously alive.
1949        for (id, status) in [
1950            ("20260908-000000-b10c", "blocked"),
1951            ("20260908-000000-5ta1", "stalled"),
1952            ("20260908-000000-jud6", "judging"),
1953        ] {
1954            write_meta(&runs, id, status, "2026-09-08T00:00:00Z");
1955            let q = open_question(&store, id);
1956
1957            let n = abandon_settled_questions(&store, &runs);
1958            assert_eq!(n, 0, "{status} run is not done; nothing to sweep");
1959            assert!(
1960                store.get(&q.id).unwrap().status.open(),
1961                "{status} run's question must still be waiting"
1962            );
1963        }
1964    }
1965
1966    #[test]
1967    fn the_sweep_leaves_an_answered_question_and_an_unreadable_run_alone() {
1968        let dir = tempfile::tempdir().unwrap();
1969        let runs = dir.path().join("runs");
1970        let store = Questions::at(dir.path().join("questions"));
1971
1972        // Already decided: a sweep must never revisit it, whatever the run
1973        // that asked went on to become.
1974        let done = "20260908-000000-answ";
1975        write_meta(&runs, done, "failed", "2026-09-08T00:00:00Z");
1976        let mut answered = open_question(&store, done);
1977        answered
1978            .answer(crate::ask::Answer::Choice("SQLite".to_owned()))
1979            .unwrap();
1980        store.put(&mut answered).unwrap();
1981
1982        // No `run.json` at all for this one - deleted, or never landed.
1983        let gone = "20260908-000000-gone";
1984        let orphan = open_question(&store, gone);
1985
1986        assert_eq!(abandon_settled_questions(&store, &runs), 0);
1987        assert_eq!(
1988            store.get(&answered.id).unwrap().status,
1989            crate::ask::QuestionStatus::Answered,
1990            "a real answer is never overwritten by a sweep"
1991        );
1992        assert!(
1993            store.get(&orphan.id).unwrap().status.open(),
1994            "a run this sweep cannot read is left exactly as it was, not guessed at"
1995        );
1996    }
1997
1998    /// A grace of `0` is a legitimate, documented value for the operator's
1999    /// own `Disk::fold_grace_secs` - `due`'s "always due" case - but the
2000    /// freshness check this guards is not that policy, and must not collapse
2001    /// to it: a `0` handed straight through would reclaim a worktree the
2002    /// instant it exists, exactly the race `fold_orphaned_worktrees_leaves_a_
2003    /// freshly_created_bay_alone` exists to rule out, just with the operator
2004    /// having turned the other grace off instead of leaving it at its
2005    /// default.
2006    #[test]
2007    fn fold_orphaned_worktrees_floors_a_zero_grace_at_the_race_safe_minimum() {
2008        let dir = tempfile::tempdir().unwrap();
2009        let runs = dir.path().join("runs");
2010        let wt = dir.path().join("wt");
2011        let home = dir.path().to_path_buf();
2012
2013        std::fs::create_dir_all(wt.join("eeee").join("under-review")).unwrap();
2014
2015        // Too fresh, even with the grace argument at zero.
2016        let now = Timestamp::now();
2017        let folded = block_on(fold_orphaned_worktrees(&runs, &wt, &home, 0, now));
2018        assert_eq!(
2019            folded, 0,
2020            "a zero grace must not defeat the race-safety floor"
2021        );
2022        assert!(wt.join("eeee").exists());
2023
2024        // Once genuinely past the floor, a zero grace reclaims it - the
2025        // floor is a minimum, not a replacement policy that never fires.
2026        let later = now + SignedDuration::new((MIN_ORPHAN_AGE_SECS + 1) as i64, 0);
2027        let folded = block_on(fold_orphaned_worktrees(&runs, &wt, &home, 0, later));
2028        assert_eq!(folded, 1, "old enough now, regardless of the zero grace");
2029        assert!(!wt.join("eeee").exists());
2030    }
2031
2032    #[test]
2033    fn clear_abandoned_active_only_acts_once_dead_and_overrun() {
2034        let dir = tempfile::tempdir().unwrap();
2035        // Harmless if another test in this binary already pinned the global
2036        // home first (see `run::set_home`'s own doc): this test only checks
2037        // the in-memory mutation `clear_abandoned_active` makes, never a
2038        // write that landed under this exact directory.
2039        crate::run::set_home(dir.path().to_path_buf());
2040        let home = dir.path().to_path_buf();
2041        let now = ts("2026-09-14T12:00:00Z");
2042        let overrun_seat = || crate::run::ActiveSeat {
2043            node: "implement".to_owned(),
2044            started_at: now - SignedDuration::new(21_000, 0),
2045            timeout_secs: 3_600,
2046            attempt: 0,
2047            task: None,
2048            command: None,
2049            index: None,
2050            total: None,
2051        };
2052
2053        let mut state = RunState::new(
2054            PathBuf::from("/repo"),
2055            "main".to_owned(),
2056            "abc1234".to_owned(),
2057            "fixture".to_owned(),
2058            crate::config::Config::default(),
2059        );
2060        state.status = RunStatus::Implementing;
2061        state.active.insert("impl-A".to_owned(), overrun_seat());
2062
2063        // A seat still within its own budget: not provably dead yet, so this
2064        // must change nothing.
2065        let mut fresh = state.clone();
2066        fresh.active.insert(
2067            "impl-B".to_owned(),
2068            crate::run::ActiveSeat {
2069                node: "implement".to_owned(),
2070                started_at: now,
2071                timeout_secs: 3_600,
2072                attempt: 0,
2073                task: None,
2074                command: None,
2075                index: None,
2076                total: None,
2077            },
2078        );
2079        assert!(!clear_abandoned_active(&mut fresh, &home, now).unwrap());
2080        assert!(!fresh.active.is_empty());
2081        assert_eq!(fresh.status, RunStatus::Implementing);
2082
2083        let store = Questions::at(home.join("questions"));
2084        let q = open_question(&store, &state.id);
2085
2086        assert!(clear_abandoned_active(&mut state, &home, now).unwrap());
2087        assert!(state.active.is_empty());
2088        assert_eq!(state.status, RunStatus::Failed);
2089        assert!(
2090            !store.get(&q.id).unwrap().status.open(),
2091            "the abandoned seat's own open question must not keep badging the \
2092             operator until some later daemon startup notices it"
2093        );
2094    }
2095
2096    /// Write a whole `run.json` that magi can read, over the given state.
2097    fn write_meta(runs: &Path, id: &str, status: &str, updated_at: &str) {
2098        let day = &updated_at[..10];
2099        std::fs::create_dir_all(runs.join(id)).unwrap();
2100        let body = format!(
2101            r#"{{"schema": {SCHEMA}, "id": "{id}", "repo": "/nonexistent/repo", "base_branch": "main", "base_commit": "0000000000000000000000000000000000000000", "instruction": "", "created_at": "{day}T00:00:00Z", "updated_at": "{updated_at}", "status": "{status}", "seed": 1}}"#
2102        );
2103        std::fs::write(runs.join(id).join("run.json"), body).unwrap();
2104    }
2105
2106    /// Write a fully-formed, `Ready`, well-past-grace `run.json` tagged with
2107    /// an arbitrary schema number - so a test can write one this build's own
2108    /// `RunState::new` could never produce on its own. Returns the id.
2109    ///
2110    /// `wt` becomes this run's `graph.worktree_root`: left at the config
2111    /// default, `RunState::worktree_root` falls through to
2112    /// `run::default_worktree_root` - the operator's real `~/wt/magi` - and
2113    /// `graph::fold_run`'s second sweep would then `read_dir` and remove
2114    /// worktrees there instead of anything this test owns.
2115    fn due_run(runs: &Path, wt: &Path, id: &str, schema: u32) -> String {
2116        due_run_with_status(runs, wt, id, schema, RunStatus::Ready)
2117    }
2118
2119    /// [`due_run`], with the terminal status a caller wants instead of the
2120    /// `Ready` every other caller here happens to want.
2121    fn due_run_with_status(
2122        runs: &Path,
2123        wt: &Path,
2124        id: &str,
2125        schema: u32,
2126        status: RunStatus,
2127    ) -> String {
2128        let mut config = crate::config::Config::default();
2129        config.graph.worktree_root = Some(wt.to_path_buf());
2130        let mut state = RunState::new(
2131            PathBuf::from("/nonexistent/repo"),
2132            "main".to_owned(),
2133            "0000000000000000000000000000000000000000".to_owned(),
2134            String::new(),
2135            config,
2136        );
2137        state.id = id.to_owned();
2138        state.status = status;
2139        state.updated_at = ts("2026-08-01T00:00:00Z");
2140        let mut value = serde_json::to_value(&state).unwrap();
2141        value["schema"] = serde_json::json!(schema);
2142        std::fs::create_dir_all(runs.join(id)).unwrap();
2143        std::fs::write(
2144            runs.join(id).join("run.json"),
2145            serde_json::to_string_pretty(&value).unwrap(),
2146        )
2147        .unwrap();
2148        id.to_owned()
2149    }
2150
2151    #[test]
2152    fn fold_due_folds_a_superseded_run_same_as_any_other_terminal_one() {
2153        let dir = tempfile::tempdir().unwrap();
2154        let runs = dir.path().join("runs");
2155        let wt = dir.path().join("wt");
2156        let home = dir.path().to_path_buf();
2157        let disk = Disk::default();
2158        let now = ts("2026-09-05T00:00:00Z");
2159
2160        let superseded = due_run_with_status(
2161            &runs,
2162            &wt,
2163            "20260801-000000-cccc",
2164            SCHEMA,
2165            RunStatus::Superseded,
2166        );
2167
2168        let (folded, unreadable) =
2169            block_on(fold_due(&runs, &home, &wt, &disk, now)).expect("fold_due");
2170        assert_eq!(
2171            folded, 1,
2172            "a superseded run has nothing left for a human to check, so it folds \
2173             exactly like a merged one"
2174        );
2175        assert_eq!(unreadable, 0);
2176        assert!(
2177            read_meta(&runs, &superseded).is_ok(),
2178            "folding drops the worktree, not the record"
2179        );
2180    }
2181
2182    /// A throwaway repo with one commit on `main`, for a test that needs a
2183    /// real winner worktree `fold_run` can actually remove.
2184    fn init_repo(dir: &Path) {
2185        use crate::proc::Quiet as _;
2186        let run = |args: &[&str]| {
2187            let out = std::process::Command::new("git")
2188                .args(args)
2189                .current_dir(dir)
2190                .quiet()
2191                .output()
2192                .expect("spawn git");
2193            assert!(
2194                out.status.success(),
2195                "git {args:?} failed: {}",
2196                String::from_utf8_lossy(&out.stderr)
2197            );
2198        };
2199        run(&["init", "-b", "main"]);
2200        run(&["config", "user.name", "magi test"]);
2201        run(&["config", "user.email", "magi@example.com"]);
2202        std::fs::write(dir.join("README.md"), "# fixture\n").unwrap();
2203        run(&["add", "-A"]);
2204        run(&["commit", "-m", "init"]);
2205    }
2206
2207    /// A due, terminal run with a decided winner that still has a real
2208    /// worktree and branch on disk - so a test can tell whether folding it
2209    /// actually removed the winner or only left it registered as folded.
2210    async fn due_run_with_winner_worktree(
2211        runs: &Path,
2212        wt: &Path,
2213        repo: &Path,
2214        id: &str,
2215        status: RunStatus,
2216    ) -> (String, PathBuf) {
2217        use crate::run::{Candidate, Tally};
2218        use std::collections::BTreeMap;
2219
2220        let mut config = crate::config::Config::default();
2221        config.graph.worktree_root = Some(wt.to_path_buf());
2222        let mut state = RunState::new(
2223            repo.to_path_buf(),
2224            "main".to_owned(),
2225            "0000000000000000000000000000000000000000".to_owned(),
2226            String::new(),
2227            config,
2228        );
2229        state.id = id.to_owned();
2230        state.status = status;
2231        state.updated_at = ts("2026-08-01T00:00:00Z");
2232
2233        let winner_wt = state.worktree_root().join("cand-A");
2234        crate::git::worktree_add_branch(repo, &winner_wt, &format!("magi/{id}/A"), "main")
2235            .await
2236            .expect("winner worktree");
2237
2238        state.candidates.push(Candidate {
2239            index: 0,
2240            label: 'A',
2241            agent: "agent".to_owned(),
2242            branch: format!("magi/{id}/A"),
2243            worktree: winner_wt.clone(),
2244            summary: String::new(),
2245            stat: String::new(),
2246            files: 0,
2247            commits: 0,
2248            empty: false,
2249            failed: None,
2250            verified_noop: None,
2251            duration_ms: 0,
2252            folded: false,
2253        });
2254        state.tally = Some(Tally {
2255            first_choice: BTreeMap::from([('A', 1)]),
2256            borda: BTreeMap::new(),
2257            winner: 'A',
2258            rankings: 1,
2259            unanimous_initial: true,
2260            deliberated: false,
2261            changed_votes: 0,
2262            unanimous_final: true,
2263            tie_break: None,
2264            judges: 1,
2265            present: 1,
2266            quorum: 1,
2267            met_quorum: true,
2268            uncontested: None,
2269        });
2270        std::fs::create_dir_all(runs.join(id)).unwrap();
2271        std::fs::write(
2272            runs.join(id).join("run.json"),
2273            serde_json::to_string_pretty(&state).unwrap(),
2274        )
2275        .unwrap();
2276        (id.to_owned(), winner_wt)
2277    }
2278
2279    #[tokio::test]
2280    async fn completed_task_retains_independent_historical_sources_without_a_merge_proof() {
2281        let dir = tempfile::tempdir().unwrap();
2282        let home = dir.path();
2283        let runs = home.join("runs");
2284        let wt = home.join("wt");
2285        let repo = home.join("repo");
2286        std::fs::create_dir_all(&repo).unwrap();
2287        init_repo(&repo);
2288        let queue = crate::queue::Queue::at(home.join("queue"));
2289        let mut task = crate::queue::Task::new(
2290            "completed".into(),
2291            "retain independent historical changes".into(),
2292            repo.clone(),
2293            crate::queue::Source::Human,
2294        );
2295        let mut sources = Vec::new();
2296        for (id, status) in [
2297            ("20260801-000000-old1", RunStatus::Superseded),
2298            ("20260801-000000-old2", RunStatus::Failed),
2299        ] {
2300            let (id, worktree) = due_run_with_winner_worktree(&runs, &wt, &repo, id, status).await;
2301            std::fs::write(worktree.join("independent.txt"), &id).unwrap();
2302            crate::git::git(&worktree, &["add", "independent.txt"])
2303                .await
2304                .unwrap();
2305            crate::git::git(
2306                &worktree,
2307                &["commit", "-m", "Independent historical change"],
2308            )
2309            .await
2310            .unwrap();
2311            let head = crate::git::rev_parse(&worktree, "HEAD").await.unwrap();
2312            let mut state = RunState::load_under(&id, home).unwrap();
2313            state.driver_exited = true;
2314            if status == RunStatus::Failed {
2315                state.tally = None;
2316            }
2317            state.save_under(home).unwrap();
2318            task.link_run(&id);
2319            sources.push((id, worktree, head));
2320        }
2321        // A newer empty attempt and task completion are no proof that either
2322        // independent historical implementation was incorporated.
2323        let mut latest = RunState::new(
2324            repo.clone(),
2325            "main".into(),
2326            crate::git::rev_parse(&repo, "main").await.unwrap(),
2327            task.instruction.clone(),
2328            crate::config::Config::default(),
2329        );
2330        latest.status = RunStatus::Ready;
2331        latest.driver_exited = true;
2332        latest.save_under(home).unwrap();
2333        task.start(latest.id.clone());
2334        task.succeed();
2335        queue.put(&mut task).unwrap();
2336
2337        let (folded, unreadable) = fold_due(
2338            &runs,
2339            home,
2340            &wt,
2341            &Disk::default(),
2342            ts("2026-09-05T00:00:00Z"),
2343        )
2344        .await
2345        .unwrap();
2346        assert_eq!((folded, unreadable), (0, 0));
2347        for (id, worktree, head) in sources {
2348            assert!(worktree.exists());
2349            assert_eq!(
2350                crate::git::rev_parse(&worktree, "HEAD").await.unwrap(),
2351                head
2352            );
2353            let mut state = RunState::load_under(&id, home).unwrap();
2354            assert!(!state.candidates[0].folded);
2355            let error = crate::graph::fold_run(&mut state, true, home)
2356                .await
2357                .unwrap_err();
2358            assert!(
2359                error
2360                    .to_string()
2361                    .contains(&format!("source of task {}", task.id))
2362            );
2363            assert_eq!(
2364                crate::git::rev_parse(&repo, &state.candidates[0].branch)
2365                    .await
2366                    .unwrap(),
2367                head
2368            );
2369            assert!(worktree.exists());
2370            assert!(runs.join(&id).join("run.json").exists());
2371        }
2372    }
2373
2374    #[tokio::test]
2375    async fn recovery_retains_historical_sources_after_success_and_automatic_cleanup() {
2376        let dir = tempfile::tempdir().unwrap();
2377        let home = dir.path();
2378        let runs = home.join("runs");
2379        let wt = home.join("wt");
2380        let repo = home.join("repo");
2381        std::fs::create_dir_all(&repo).unwrap();
2382        init_repo(&repo);
2383        let mut task = crate::queue::Task::new(
2384            "recover".into(),
2385            "keep measured behavior".into(),
2386            repo.clone(),
2387            crate::queue::Source::Human,
2388        );
2389        let mut sources = Vec::new();
2390        for (id, status) in [
2391            ("20260801-000000-old1", RunStatus::Blocked),
2392            ("20260801-000000-old2", RunStatus::Stalled),
2393        ] {
2394            let (id, worktree) = due_run_with_winner_worktree(&runs, &wt, &repo, id, status).await;
2395            let mut state = RunState::load_under(&id, home).unwrap();
2396            state.driver_exited = true;
2397            state.save_under(home).unwrap();
2398            task.link_run(&id);
2399            sources.push((id, worktree));
2400        }
2401        crate::pr_recovery::retain_sources(&task, home).unwrap();
2402        let mut recovered = RunState::new(
2403            repo.clone(),
2404            "main".into(),
2405            "base".into(),
2406            task.instruction.clone(),
2407            crate::config::Config::default(),
2408        );
2409        recovered.config.graph.worktree_root = Some(wt.clone());
2410        recovered.status = RunStatus::Ready;
2411        recovered.driver_exited = true;
2412        recovered.save_under(home).unwrap();
2413        task.start(recovered.id.clone());
2414        task.succeed();
2415        crate::daemon::supersede_prior_runs(&task, home);
2416        for (id, _) in &sources {
2417            assert_eq!(
2418                RunState::load_under(id, home).unwrap().status,
2419                RunStatus::Superseded
2420            );
2421        }
2422        let disk = Disk::default();
2423        let now = Timestamp::now()
2424            .checked_add(SignedDuration::from_secs(
2425                i64::try_from(disk.fold_grace_secs + 1).unwrap(),
2426            ))
2427            .unwrap();
2428        let (_, unreadable) = fold_due(&runs, home, &wt, &disk, now).await.unwrap();
2429        assert_eq!(unreadable, 0);
2430        for (id, worktree) in sources {
2431            assert!(worktree.exists());
2432            assert!(
2433                crate::git::branch_exists(&repo, &format!("magi/{id}/A"))
2434                    .await
2435                    .unwrap()
2436            );
2437            let mut historical = RunState::load_under(&id, home).unwrap();
2438            assert!(!historical.candidates[0].folded);
2439            let error = crate::graph::fold_run(&mut historical, true, home)
2440                .await
2441                .unwrap_err();
2442            assert!(
2443                error
2444                    .to_string()
2445                    .contains("explicitly retained recovery source")
2446            );
2447            assert!(!historical.candidates[0].folded);
2448            assert!(
2449                worktree.exists(),
2450                "every automatic fold entry preserves retained sources"
2451            );
2452        }
2453    }
2454
2455    #[tokio::test]
2456    async fn fold_due_drops_a_superseded_runs_own_winner_worktree_but_keeps_a_readys() {
2457        let dir = tempfile::tempdir().unwrap();
2458        let runs = dir.path().join("runs");
2459        let wt = dir.path().join("wt");
2460        let repo = dir.path().join("repo");
2461        let home = dir.path().to_path_buf();
2462        let disk = Disk::default();
2463        let now = ts("2026-09-05T00:00:00Z");
2464        std::fs::create_dir_all(&repo).unwrap();
2465        init_repo(&repo);
2466
2467        let (superseded_id, superseded_wt) = due_run_with_winner_worktree(
2468            &runs,
2469            &wt,
2470            &repo,
2471            "20260801-000000-supw",
2472            RunStatus::Superseded,
2473        )
2474        .await;
2475        // `Ready` is auto-folded exactly like `Superseded` (both terminal and
2476        // non-resumable), but never landed anywhere - its own winner is
2477        // deliberately kept, which is what makes it the right contrast here.
2478        // `Blocked`/`Stalled` are `resumable()` and so never even reach
2479        // `fold_run` in the first place; they would not exercise the
2480        // `drop_winner` choice this test is about.
2481        let (ready_id, ready_wt) = due_run_with_winner_worktree(
2482            &runs,
2483            &wt,
2484            &repo,
2485            "20260801-000000-rdyw",
2486            RunStatus::Ready,
2487        )
2488        .await;
2489
2490        let (folded, unreadable) = fold_due(&runs, &home, &wt, &disk, now)
2491            .await
2492            .expect("fold_due");
2493        assert_eq!(folded, 2);
2494        assert_eq!(unreadable, 0);
2495
2496        assert!(
2497            !superseded_wt.exists(),
2498            "a superseded run's own winner never lands anywhere else, so its worktree \
2499             must be dropped exactly like a merged run's"
2500        );
2501        assert!(
2502            ready_wt.exists(),
2503            "a still-ready run's winner may yet be merged by hand - folding must not \
2504             touch it"
2505        );
2506
2507        // Both records survive the fold; only the worktrees differ.
2508        assert!(read_meta(&runs, &superseded_id).is_ok());
2509        assert!(read_meta(&runs, &ready_id).is_ok());
2510    }
2511}