magi/

daemon.rs

//! The unattended loop: take the next task, run the graph, record what
//! happened, take the next one.
//!
//! This is what turns magi from a command a human types into something an
//! agent can hand work to. [`crate::queue`] is the mailbox; this module is the
//! thing that empties it. Nothing here decides *how* a task is implemented —
//! that is [`crate::graph`] — it only decides which task runs next, and what a
//! finished run means for the task that produced it.
//!
//! # One run at a time, on purpose
//!
//! There is no `--jobs` flag and there will not be one. A single run is
//! already internally parallel: candidates implement concurrently and judges
//! rank concurrently, so the machine is not idle while one task is in flight.
//! The real constraint is not CPU but the agent CLIs' quota, and two graphs at
//! once doubles the burn rate on exactly the resource whose exhaustion produces
//! [`RunStatus::Stalled`]. Serialising the loop is what keeps a full backlog
//! from converting the whole day's quota into a pile of untrustworthy verdicts.
//!
//! # A crash is legible, and the loop notices on its own
//!
//! The task is written as [`crate::queue::TaskStatus::Running`], with its run
//! id, *before* the graph starts, and is only rewritten once the run reaches a
//! terminal status. A daemon killed mid-run therefore leaves the task
//! `Running` and pointing at the run that was in flight. The alternative —
//! reverting the task to `Queued` on the way out — would hide the abandoned
//! run and re-spend its quota on the next poll.
//!
//! A task left `Running` forever is not the point, though:
//! [`crate::queue::TaskStatus::runnable`] never offers it again, so a daemon
//! that died mid-run would otherwise strand its task for good.
//! [`reclaim_orphaned_running`] runs on every poll and settles exactly the
//! tasks no live process is actually driving — proven by [`Queue::claim`]
//! succeeding rather than by a staleness guess — against whatever their last
//! run actually became, through the same [`settle`] a live finish uses. A run
//! that genuinely cannot be read still holds its task for a human; the run's
//! own report explains how far it got.
//!
//! # Retries are bounded
//!
//! Every attempt at a task consumes one of [`Opts::max_attempts`], after which
//! the task is [`crate::queue::TaskStatus::Held`] for a human. The one
//! exception is a run that ended `Stalled`: the panel collapsed because the
//! agent CLIs hit their quota, which is a fact about the machine and not about
//! the task, so it must not spend an attempt. Without that exception a quota
//! outage would quietly hold the entire backlog, and the operator would come
//! back to a reset quota and nothing left that the loop is willing to run.

use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Mutex, MutexGuard};
use std::time::Duration;

use anyhow::{Context, Result, bail};
use jiff::Timestamp;
use serde::{Deserialize, Serialize};
use tokio::sync::Notify;

use crate::ask;
use crate::clean;
use crate::config::{Config, MergeMode};
use crate::graph::Runner;
use crate::land;
use crate::queue::{Queue, Task, TaskStatus};
use crate::run::{QuotaLoss, RunState, RunStatus};

/// On-disk format for [`Status`]. Bumped when a field's meaning changes.
pub const SCHEMA: u32 = 1;

/// How often the status file is refreshed. A reader treats a status file older
/// than [`STALE_SECS`] as "no daemon", so the heartbeat has to be brisk enough
/// that a busy daemon is never mistaken for a dead one.
pub const HEARTBEAT: Duration = Duration::from_secs(5);

/// How old a heartbeat may be before a reader calls the daemon dead. Six
/// missed beats: long enough to survive a slow filesystem, short enough that
/// a crashed daemon is not still reported as running a task.
///
/// The single threshold every reader shares — the web UI's `/api/health` and
/// `magi doctor` both call [`Reading::running`] rather than each comparing
/// against their own copy of this number, so a crashed daemon cannot look
/// alive on one screen and dead on another.
pub const STALE_SECS: i64 = 30;

/// Default queue poll interval.
pub const POLL: Duration = Duration::from_secs(5);

/// How old a claim has to be before startup sweeps it. Longer than any run
/// this graph plausibly takes, so a sweep cannot pull a task out from under a
/// daemon that is merely slow.
pub const STALE_CLAIM: Duration = Duration::from_secs(6 * 60 * 60);

/// What the loop is working on, for the status file.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct Current {
    /// Task id being run.
    pub task: String,
    /// Run id the task produced.
    pub run: String,
}

/// The daemon's liveness, published to `<home>/daemon.json`.
///
/// This is the only interface between the loop and the web UI, which is why it
/// carries `updated_at` as well as `started_at`: a reader cannot tell a
/// running daemon from a `SIGKILL`ed one by the file's existence alone, but it
/// can compare the heartbeat against the clock.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Status {
    /// On-disk format version.
    pub schema: u32,
    /// Process id, so a human can find or kill the daemon.
    pub pid: u32,
    /// When this process started.
    pub started_at: Timestamp,
    /// Last heartbeat.
    pub updated_at: Timestamp,
    /// True when the queue has nothing runnable.
    pub idle: bool,
    /// Every task and run currently in flight. More than one entry means the
    /// loop is driving more than one run at once — see
    /// [`crate::config::Daemon::max_concurrent_runs`]. Empty, not absent, when
    /// nothing is running, so a reader never has to treat "no field" and "an
    /// empty list" as two different kinds of idle.
    pub current: Vec<Current>,
    /// Tasks that reached a terminal status in this process.
    pub completed: usize,
    /// Queue polls since start, so a wedged loop shows up as a frozen count.
    pub polls: u64,
}

impl Status {
    /// A fresh, idle status for this process.
    #[must_use]
    pub fn new() -> Self {
        let now = Timestamp::now();
        Self {
            schema: SCHEMA,
            pid: std::process::id(),
            started_at: now,
            updated_at: now,
            idle: true,
            current: Vec::new(),
            completed: 0,
            polls: 0,
        }
    }
}

impl Default for Status {
    fn default() -> Self {
        Self::new()
    }
}

/// How the loop should behave.
#[derive(Debug, Clone)]
pub struct Opts {
    /// Repository used by tasks that name none.
    pub repo: PathBuf,
    /// Explicit `magi.toml`, instead of the discovered layer stack.
    pub config: Option<PathBuf>,
    /// Queue poll interval.
    pub poll: Duration,
    /// Attempts a task gets before it is held for a human.
    pub max_attempts: usize,
    /// Drain what is runnable now, then return, instead of waiting for more.
    pub once: bool,
    /// Merge mode override (`none`, `local`, `pr`); `None` keeps the config's.
    pub merge: Option<String>,
}

impl Default for Opts {
    fn default() -> Self {
        Self {
            repo: PathBuf::from("."),
            config: None,
            poll: POLL,
            max_attempts: 2,
            once: false,
            merge: None,
        }
    }
}

/// How many runs a plain `usize` from config may drive concurrently, floored
/// at one. A `0` in a config file would otherwise stall the loop entirely -
/// no runnable task could ever start - which is never what an operator who
/// wrote `0` meant.
fn max_concurrent(n: usize) -> usize {
    n.max(1)
}

/// Where the status file lives.
#[must_use]
pub fn status_path() -> PathBuf {
    crate::run::home().join("daemon.json")
}

/// Publish the status file for this process.
pub fn write_status(status: &Status) -> Result<()> {
    write_status_to(&status_path(), status)
}

/// Publish a status to an explicit path.
///
/// Written to a sibling `.tmp` and renamed, because the web UI reads this file
/// on every health poll and must never see a half-written one.
pub fn write_status_to(path: &Path, status: &Status) -> Result<()> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent).with_context(|| format!("create {}", parent.display()))?;
    }
    let body = serde_json::to_string_pretty(status).context("serialize daemon status")?;
    let tmp = path.with_extension("json.tmp");
    std::fs::write(&tmp, &body).with_context(|| format!("write {}", tmp.display()))?;
    std::fs::rename(&tmp, path).with_context(|| format!("replace {}", path.display()))?;
    Ok(())
}

/// Delete the status file. Called on the way out so a clean exit reads as
/// "no daemon" rather than as a daemon whose heartbeat merely stopped.
pub fn clear_status() {
    clear_status_at(&status_path());
}

/// Delete a status file at an explicit path, so the loop's teardown and
/// [`clear_status`] cannot drift apart: the loop is handed the path it
/// published to, and a test can watch a temp file disappear.
fn clear_status_at(path: &Path) {
    let _ = std::fs::remove_file(path);
}

/// A cooperative stop, shared with whoever asked the loop to run.
///
/// Cloning is how the request travels: [`serve_until`] keeps one handle, the
/// Ctrl-C listener and the web UI keep others, and every clone points at the
/// same flag. There is no channel because there is nothing to send — the only
/// message is "stop", it is idempotent, and a flag cannot be missed by a
/// receiver that was not listening yet.
///
/// The handle also answers the question the operator's screen asks next: a
/// stop does not take effect until the run in flight has finished, so
/// [`Stop::finishing`] reports "asked to stop, still working" rather than
/// leaving a caller to infer it from a heartbeat and hope.
#[derive(Debug, Clone, Default)]
pub struct Stop {
    /// Set once, never cleared: a stop is not something an operator takes back
    /// half way through, and a clearable flag would let a start racing a stop
    /// resurrect a loop that is already unwinding.
    stopped: Arc<AtomicBool>,
    /// How many runs are in flight, so `finishing` can distinguish a stop
    /// that has landed from one that is waiting on `execute`. A count, not a
    /// flag, because more than one run can be in flight at once - see
    /// [`crate::config::Daemon::max_concurrent_runs`] - and the last one to
    /// finish is the one that should turn "finishing" off.
    busy: Arc<std::sync::atomic::AtomicUsize>,
    /// Wakes the idle wait. Without this a stop would not be seen until the
    /// poll interval elapsed, and an operator tapping stop on a phone would
    /// watch a button do nothing for five seconds.
    wake: Arc<Notify>,
    /// Handed to the run in flight, so a stop can also mean "park at the next
    /// node boundary" instead of "finish the whole competition first".
    pause: crate::graph::Pause,
}

impl Stop {
    /// A stop nobody has asked for yet.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Ask the loop to stop. Idempotent, and safe to call before the loop
    /// starts: the flag is checked before the first poll.
    pub fn stop(&self) {
        self.stopped.store(true, Ordering::SeqCst);
        // `notify_one` rather than `notify_waiters` because the loop may not be
        // parked yet: this stores a permit, so a wait that registers a moment
        // later returns at once instead of sleeping out the whole interval.
        self.wake.notify_one();
    }

    /// Has a stop been asked for?
    #[must_use]
    pub fn stopped(&self) -> bool {
        self.stopped.load(Ordering::SeqCst)
    }

    /// Has a stop been asked for that has not taken effect yet, because a run
    /// is still in flight?
    ///
    /// This is the state a screen has to be able to show. A stop never abandons
    /// a run — see [`serve_until`] — so between the tap and the loop's return
    /// there is a window of tens of minutes in which "running" and "stopped"
    /// are both misleading answers.
    #[must_use]
    pub fn finishing(&self) -> bool {
        self.stopped() && self.busy_now()
    }

    /// Ask the loop to stop *and* the run in flight to park at its next node
    /// boundary.
    ///
    /// The plain [`Stop::stop`] never abandons a run, which is right when the
    /// operator only wants the queue to drain: a competition is tens of
    /// minutes and its worktrees are paid for. But an operator who wants to
    /// replace the binary cannot wait out a run that has an hour left, and
    /// killing the process loses whatever the seats in flight had not written.
    /// Parking costs at most the node in progress and leaves the run
    /// resumable.
    pub fn park(&self) {
        self.pause.park();
        self.stop();
    }

    /// Has a park been asked for?
    #[must_use]
    pub fn parking(&self) -> bool {
        self.pause.parked()
    }

    /// The pause handle to give a runner.
    #[must_use]
    pub fn pause(&self) -> crate::graph::Pause {
        self.pause.clone()
    }

    /// Is any run in flight right now?
    ///
    /// `finishing` answers "a stop is waiting on a run", which is false until
    /// someone asks to stop. An upgrade needs the plain question, because it
    /// is about to be the one asking.
    #[must_use]
    pub fn busy_now(&self) -> bool {
        self.busy.load(Ordering::SeqCst) > 0
    }

    /// Mark one more run as in flight, for [`Stop::finishing`].
    fn enter(&self) {
        self.busy.fetch_add(1, Ordering::SeqCst);
    }

    /// Mark one run as finished. The last one out is what makes
    /// [`Stop::busy_now`] false again.
    fn exit(&self) {
        self.busy.fetch_sub(1, Ordering::SeqCst);
    }

    /// Wait out one poll interval, returning early once a stop is asked for.
    async fn idle(&self, poll: Duration) {
        tokio::select! {
            () = tokio::time::sleep(poll) => {}
            () = self.wake.notified() => {}
        }
    }
}

/// The daemon's published state, read permissively.
///
/// This mirrors [`Status`], but is a separate declaration on purpose: every
/// field defaults, so a status file from an older or newer magi still yields
/// a usable reading — one this build has never heard of — instead of a parse
/// error that hides the daemon entirely.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct Reading {
    /// Format version the daemon claims.
    pub schema: u32,
    /// Daemon process id, for an operator who wants to stop it.
    pub pid: Option<u32>,
    /// When that process started.
    pub started_at: Option<Timestamp>,
    /// Last heartbeat. Absent means the file is unusable, hence not running.
    pub updated_at: Option<Timestamp>,
    /// True when the queue had nothing runnable at the last poll.
    pub idle: bool,
    /// What the daemon is working on. Empty means idle; more than one entry
    /// means more than one run is in flight at once.
    ///
    /// `deserialize_with` rather than the plain derive: a daemon started
    /// before this field became a list is still out there writing the old
    /// shape — a single `{"task":...,"run":...}` object, or its absence —
    /// on every heartbeat until it is restarted, and a live process reading
    /// that file during the rollout must still see it as running rather than
    /// as absent. A bare type change here would fail the whole struct's
    /// deserialization on a type mismatch, defeating the permissiveness this
    /// type exists for.
    #[serde(deserialize_with = "de_current")]
    pub current: Vec<Current>,
    /// Tasks this daemon process has finished.
    pub completed: u64,
    /// Queue polls this daemon process has made.
    pub polls: u64,
}

/// Accept the old single-`Current`-or-absent shape as well as the current
/// list, so a reader never has to know which build wrote the file.
fn de_current<'de, D>(deserializer: D) -> std::result::Result<Vec<Current>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum Shape {
        Many(Vec<Current>),
        One(Current),
    }
    Ok(
        Option::<Shape>::deserialize(deserializer)?.map_or_else(Vec::new, |shape| match shape {
            Shape::Many(v) => v,
            Shape::One(c) => vec![c],
        }),
    )
}

impl Reading {
    /// Seconds since the last heartbeat, or `None` when there has never been
    /// one.
    #[must_use]
    pub fn age_secs(&self, now: Timestamp) -> Option<i64> {
        self.updated_at
            .map(|at| (now.as_second() - at.as_second()).max(0))
    }

    /// Whether the loop counts as running: a heartbeat no older than
    /// [`STALE_SECS`]. The alternative is a reader that claims a task is in
    /// progress hours after the daemon that owned it was killed.
    #[must_use]
    pub fn running(&self, now: Timestamp) -> bool {
        self.age_secs(now).is_some_and(|secs| secs <= STALE_SECS)
    }
}

/// Read `<home>/daemon.json` permissively, or `None` when there is nothing
/// usable there.
///
/// Missing, half-written and unparseable all collapse to `None`, because the
/// only question a reader asks is whether a daemon is alive, and a file it
/// cannot read is not evidence that one is.
#[must_use]
pub fn read_status(home: &Path) -> Option<Reading> {
    let body = std::fs::read_to_string(home.join("daemon.json")).ok()?;
    serde_json::from_str(&body).ok()
}

/// Every run a live daemon is working on right now.
///
/// One definition of liveness, because deleting a task and deleting a run are
/// both gated on it from both the CLI and the web UI - four callers that must
/// never disagree about whether the same thing is in flight. A stale heartbeat
/// reads as "no daemon": that is [`Reading::running`]'s judgement, and a task
/// left at `running` or a run left at `implementing` by a killed daemon is a
/// leftover record rather than work in progress. More than one entry once
/// [`crate::config::Daemon::max_concurrent_runs`] is more than one - a caller
/// after "the one thing in flight" wants [`is_working_on`] or
/// [`is_working_on_task`], not this directly.
#[must_use]
pub fn current_work(home: &Path, now: Timestamp) -> Vec<Current> {
    read_status(home)
        .filter(|reading| reading.running(now))
        .map(|reading| reading.current)
        .unwrap_or_default()
}

/// Whether a live daemon is working on this run at this moment.
#[must_use]
pub fn is_working_on(home: &Path, run: &str, now: Timestamp) -> bool {
    current_work(home, now).iter().any(|c| c.run == run)
}

/// Whether a live daemon is working on this task at this moment.
#[must_use]
pub fn is_working_on_task(home: &Path, task: &str, now: Timestamp) -> bool {
    current_work(home, now).iter().any(|c| c.task == task)
}

/// Remove claim files whose owner is provably dead, or that have simply
/// outlived `older_than`, and return the task ids swept.
///
/// A daemon killed with `SIGKILL` never runs [`crate::queue::Claim`]'s
/// destructor, and the orphaned `.lock` file would make its task permanently
/// unclaimable — the backlog would stop for good at exactly the task that was
/// in flight when the machine went down.
///
/// The pid recorded in the lock is the authority whenever it can be read at
/// all; age is only a fallback for when it cannot be.
///
/// - **A parseable pid wins outright.** [`crate::proc::pid_alive`] decides,
///   full stop — dead sweeps the lock immediately, regardless of age; alive
///   protects it, regardless of age. This is what lets a lock be reclaimed in
///   seconds instead of waiting out [`STALE_CLAIM`]: a lock made 33 minutes
///   before this daemon even started, next to a `queued` task, no longer has
///   to sit for six hours before anything notices its owner is gone.
/// - **A pid that cannot be parsed at all** — an empty or corrupt lock file —
///   falls back to `older_than`, since there is nothing else to check.
///
/// Age must never override a *positive* liveness confirmation. `sweep`
/// [`poll`]s concurrently with every attempt this daemon itself has spawned —
/// see [`InFlightGuard`] — not only between them the way a single sequential
/// loop once did, so a run that legitimately runs longer than `older_than`
/// (a multi-round review, a long land wait carried across several resumed
/// attempts) still has this very process's own live pid sitting in its own
/// lock file on every later sweep. Deciding by age alone in that case would
/// delete this daemon's own still-valid claim on its own in-flight task,
/// which [`reclaim_orphaned_running`] would then read as abandoned and hand
/// to a second attempt — two `Runner`s writing the same `run.json` and the
/// same worktree at once. `pid_alive` answering "alive" for anything it
/// cannot determine (a live process, a pid this build cannot check, one
/// under another account) is exactly what keeps that path from ever
/// firing on a guess.
///
/// [`STALE_CLAIM`] itself stays large: a helper program missing or its
/// output unreadable must not be license to guess, and the risk of an
/// unparseable lock outliving a genuinely dead owner is bounded by an order
/// of magnitude above any plausible run rather than by a positive check.
///
/// Runs on every poll, not only at startup — a daemon up for days must keep
/// noticing a lock some other, now-dead, daemon left behind just as readily
/// as one it trips over on the way up.
pub fn sweep_stale_claims(queue: &Queue, older_than: Duration) -> Vec<String> {
    let this_process = std::process::id();
    let mut swept: Vec<String> = std::fs::read_dir(queue.root())
        .into_iter()
        .flatten()
        .flatten()
        .map(|e| e.path())
        .filter(|p| p.extension().is_some_and(|x| x == "lock"))
        .filter(|p| {
            match std::fs::read_to_string(p)
                .ok()
                .and_then(|body| body.trim().parse::<u32>().ok())
            {
                // This process wrote it and is asking the question right
                // now, so it is definitionally still alive - settled without
                // spawning a helper process at all.
                Some(pid) if pid == this_process => false,
                Some(pid) => !crate::proc::pid_alive(pid),
                None => p
                    .metadata()
                    .and_then(|m| m.modified())
                    .and_then(|t| t.elapsed().map_err(std::io::Error::other))
                    .is_ok_and(|age| age >= older_than),
            }
        })
        .filter(|p| std::fs::remove_file(p).is_ok())
        .filter_map(|p| {
            p.file_stem()
                .and_then(|s| s.to_str())
                .map(std::borrow::ToOwned::to_owned)
        })
        .collect();
    swept.sort_unstable();
    swept
}

/// What a finished run tells the queue about the task it came from.
///
/// A struct rather than a fourth and fifth boolean argument: the two flags
/// answer different questions about the same run, and a call site passing
/// `(…, true, false)` is one transposition away from refunding attempts
/// forever.
#[derive(Debug, Clone, Copy)]
pub struct Verdict {
    /// Where the graph stopped.
    pub status: RunStatus,
    /// The run opened a pull request.
    pub left_pr: bool,
    /// At least one seat was lost to a rate limit.
    pub quota_hit: bool,
    /// The run parked at a node boundary because it was asked to.
    pub parked: bool,
    /// The run never produced a single candidate a judge could look at.
    ///
    /// Distinct from `quota_hit`: a run can lose a seat to a rate limit and
    /// still have another candidate worth judging, in which case the loss was
    /// not the reason nothing came of the run. This is `true` only when the
    /// implement wave ended with nothing viable at all.
    pub no_viable_candidates: bool,
}

/// Record a finished run against the task it came from.
///
/// Kept pure and separate from the loop because this mapping *is* the retry
/// policy, and a policy that can only be exercised by spawning a graph is a
/// policy nobody checks. The table:
///
/// | run status                           | task becomes        | attempt spent |
/// |---------------------------------------|---------------------|---------------|
/// | parked at a boundary                  | `Failed` (requeued) | **no**        |
/// | `Merged`, `Ready`                      | `Done`               | yes          |
/// | `Stalled`, quota hit                   | `Failed` (requeued) | **no**        |
/// | `Failed`, quota hit, no viable cand.   | `Failed` (requeued) | **no**        |
/// | `Stalled`, no quota                    | `Failed`, or `Held`  | yes          |
/// | `Blocked` with a PR                    | `Held`               | yes          |
/// | `Blocked`, `Failed` otherwise          | `Failed`, or `Held`  | yes          |
/// | anything non-terminal                  | `Failed`, or `Held`  | yes          |
///
/// The `Stalled`-quota and `Failed`-quota rows are the ones worth reading
/// twice, together. A quorum lost to rate limits is a property of the machine
/// and not of the task, so the attempt is refunded and a reset quota picks
/// the work up where it stopped — and that is just as true when every
/// implement seat lost the same race and `after_implement` bails with nothing
/// to judge, which surfaces as `Failed` rather than `Stalled` but is the same
/// machine fact. The `no_viable_candidates` guard is what keeps that row
/// narrow: a `Failed` run that produced a real candidate which then lost for
/// some other reason still spends the attempt, exactly like the quorum lost
/// to judges that answered with the wrong shape is ordinary flakiness, and
/// refunding *that* takes the bound off the retry loop entirely: run e633
/// stalled with `quota: []` after two judges wrote unusable JSON, was
/// refunded, and the next attempt paid for a fresh hour-long implement wave
/// before it could fail the same way. `max_attempts` exists precisely so
/// that cannot repeat forever.
///
/// A non-terminal status means `execute` returned while the graph was still
/// mid-flight, which is a bug rather than a verdict; it is treated as a
/// failure so that a task cannot loop on it either.
///
/// `left_pr` splits the `Blocked` row, and it is the difference between a run
/// that failed and a run that finished into a gate. See [`Task::handed_off`].
pub fn settle(task: &mut Task, verdict: Verdict, detail: &str, max_attempts: usize) {
    // A parked run is the operator's own doing, and its work is intact on
    // disk. The task goes back in line with its attempt refunded so the next
    // loop resumes the same run - which `one_task` prefers over competing
    // again - and so that swapping the binary a few times cannot exhaust a
    // budget meant for agents that actually misbehaved.
    if verdict.parked {
        task.stall(detail);
        return;
    }
    match verdict.status {
        RunStatus::Merged | RunStatus::Ready => task.succeed(),
        RunStatus::Stalled if verdict.quota_hit => task.stall(detail),
        RunStatus::Failed if verdict.quota_hit && verdict.no_viable_candidates => {
            task.stall(detail)
        }
        RunStatus::Stalled | RunStatus::Failed => task.fail(detail, max_attempts),
        RunStatus::Blocked if verdict.left_pr => task.handed_off(detail),
        RunStatus::Blocked => task.fail(detail, max_attempts),
        other => task.fail(
            format!(
                "the graph stopped at `{}` without reaching a terminal status: {detail}",
                label(other)
            ),
            max_attempts,
        ),
    }
}

/// Reconcile a task left at [`TaskStatus::Running`] by a daemon that never
/// got back to [`settle`] for it — a crash, a `SIGKILL`, or a run carried on
/// by some other means entirely, like a manual `magi run` resume that
/// finishes the graph outside the queue's bookkeeping.
///
/// Pure and separate from [`reclaim_orphaned_running`] for the same reason
/// `settle` is separate from `attempt`: a task recovered this way must land
/// exactly where a live daemon would have put it — the same policy table,
/// not a second one that quietly drifts from it — and that is only checkable
/// without spawning a real run.
fn reclaim(task: &mut Task, last_run: Option<RunState>, max_attempts: usize) {
    match last_run {
        Some(state) => {
            let verdict = Verdict {
                status: state.status,
                left_pr: state.pr.is_some(),
                quota_hit: !state.quota.is_empty(),
                parked: state.parked,
                no_viable_candidates: state.viable().is_empty(),
            };
            let detail = format!(
                "recovered a `running` task whose daemon never recorded the outcome: {}",
                describe(&state)
            );
            settle(task, verdict, &detail, max_attempts);
        }
        None => {
            let why = "task was `running` with no live daemon and no readable \
                       run to recover; held for a human to check what happened";
            task.last_error = Some(why.to_owned());
            // The phone shows `hold_reason`, so a task held by the machine
            // says why there too and not only in `last_error`.
            task.hold(Some(why.to_owned()));
        }
    }
}

/// Find every task left at `running` that no live process is actually
/// driving, and settle each one against whatever its last run became.
///
/// # Why a claim is proof, not a guess
///
/// [`poll`] takes a task's [`Queue::claim`] *before* [`Task::start`] writes
/// `running`, and the guard is held for the task's whole time in that status:
/// `attempt` does not return, and the loop does not move past the scope
/// holding the claim, until the run has settled. So a `running` task whose
/// lock is gone cannot have a live owner — this process or any other —
/// without needing a staleness threshold or a pid check the way
/// [`sweep_stale_claims`] does for the narrower case of a lock left next to a
/// task that never got as far as `running` at all. Taking the claim here is
/// the whole test: it either fails, because something really does hold it
/// and the task is left alone, or it succeeds, which is the proof — and it is
/// kept for the rest of the decision so nothing else can start a competing
/// run while this one is being written.
///
/// Called on every poll, not only at startup, for the reason
/// [`sweep_stale_claims`] now is too: a daemon that has been up for days must
/// keep noticing this, not only on the one morning it happened to restart.
fn reclaim_orphaned_running(queue: &Queue, max_attempts: usize) -> Vec<String> {
    let mut reclaimed = Vec::new();
    for listed in queue.list() {
        if listed.status != TaskStatus::Running {
            continue;
        }
        let Ok(_claim) = queue.claim(&listed.id) else {
            continue;
        };
        // Re-read under the claim: a release or an edit landed by a human
        // between the listing above and the claim just taken must not be
        // clobbered by a decision based on the stale copy.
        let Ok(mut task) = queue.get(&listed.id) else {
            continue;
        };
        if task.status != TaskStatus::Running {
            continue;
        }
        let last_run = task.runs.last().and_then(|id| RunState::load(id).ok());
        reclaim(&mut task, last_run, max_attempts);
        record(queue, &mut task);
        reclaimed.push(task.id.clone());
    }
    reclaimed
}

/// Run the loop until Ctrl-C, or until the queue drains with [`Opts::once`].
///
/// A thin wrapper over [`serve_until`] with a stop nothing but Ctrl-C ever
/// sets, so there is one loop body rather than two that drift apart the first
/// time the retry policy changes on only one of them.
pub async fn serve(opts: Opts) -> Result<()> {
    serve_until(opts, Stop::new()).await
}

/// [`serve`], but stopping when `stop` is set as well as on Ctrl-C.
///
/// Neither a signal nor a `stop` abandons a run in flight. Killing the graph
/// mid-node leaves worktrees, branches and agent sessions behind, and every
/// agent call already paid for is lost; finishing the run costs the operator a
/// wait and saves them a cleanup. A stop therefore only sets a flag: the
/// current `execute` runs to its terminal status, the task's outcome is
/// recorded, and only then does the loop return. That window is what
/// [`Stop::finishing`] is for. An operator who genuinely wants the run dead
/// still has a second Ctrl-C, which the runtime turns into a process kill —
/// and the task left `Running` then tells the next daemon, and the next human,
/// where to look.
///
/// While the queue is empty the stop is honoured within one wakeup rather than
/// one poll interval: the wait is a `select!` against [`Stop`]'s notify, so a
/// caller that taps stop does not sit through the remainder of a sleep.
pub async fn serve_until(opts: Opts, stop: Stop) -> Result<()> {
    let signal = {
        let stop = stop.clone();
        tokio::spawn(async move {
            if tokio::signal::ctrl_c().await.is_ok() {
                stop.stop();
                tracing::info!("shutdown requested; a run in flight will be finished first");
            }
        })
    };

    let outcome = drive(
        &opts,
        &Queue::open(),
        &status_path(),
        &crate::run::home(),
        &stop,
    )
    .await;

    signal.abort();
    outcome
}

/// The loop proper: setup, poll, teardown, with the queue and the status file
/// supplied rather than discovered.
///
/// Both are parameters because [`crate::run::home`] is process-global and its
/// override is a `OnceLock`, so a unit test that pinned it would fight every
/// other test in the binary — and a loop that resolved the home itself could
/// only be exercised against the operator's real one, publishing over a live
/// daemon's status file and claiming tasks out of a live backlog.
async fn drive(
    opts: &Opts,
    queue: &Queue,
    status_file: &Path,
    home: &Path,
    stop: &Stop,
) -> Result<()> {
    janitor(&opts.repo, opts, home).await;

    // The status file is a *snapshot*, not a stream of events: a reader only
    // ever wants the latest values, and every tick rewrites the whole file
    // anyway. A shared `Mutex<Status>` therefore says exactly what is meant,
    // while an mpsc channel would force the loop to re-send unchanged fields on
    // every heartbeat — or the heartbeat to keep its own shadow copy of them —
    // for no gain. The lock is only ever held across a field assignment, never
    // across an await.
    let status = Arc::new(Mutex::new(Status::new()));
    write_status_to(status_file, &lock(&status)).context("publish the daemon status file")?;
    let beat = tokio::spawn(heartbeat(Arc::clone(&status), status_file.to_path_buf()));

    // Read once at startup, not per task: how many runs this loop drives at
    // once is a property of the machine running it, not of whichever
    // repository a given task happens to name - see
    // `Config::daemon.max_concurrent_runs`'s doc for why that is a machine
    // fact in the same sense the agent roster is.
    let concurrency = max_concurrent(
        prepare(&opts.repo, opts)
            .map(|c| c.daemon.max_concurrent_runs)
            .unwrap_or(1),
    );

    tracing::info!(
        "magi serve: queue {} (poll {}s, {} attempts per task, {} run(s) at once)",
        queue.root().display(),
        opts.poll.as_secs(),
        opts.max_attempts,
        concurrency
    );

    let outcome = poll(opts, queue, &status, home, stop, concurrency).await;

    beat.abort();
    clear_status_at(status_file);
    outcome
}

/// Refresh the status file on a fixed tick.
///
/// Separate from the loop because a run takes tens of minutes: a status file
/// written only between tasks would look stale for the whole of every run, and
/// a reader would report the daemon dead exactly while it was busiest.
async fn heartbeat(status: Arc<Mutex<Status>>, path: PathBuf) {
    loop {
        tokio::time::sleep(HEARTBEAT).await;
        let snapshot = {
            let mut guard = lock(&status);
            guard.updated_at = Timestamp::now();
            guard.clone()
        };
        if let Err(e) = write_status_to(&path, &snapshot) {
            // A failed heartbeat must not take the daemon down: the loop is the
            // product, the status file is only the window onto it.
            tracing::warn!("could not refresh the daemon status file: {e:#}");
        }
    }
}

/// Whether a task's last run is sitting in `land`'s merge-approval wait, and
/// if so, whether that wait is over.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum LandResume {
    /// The task's last run is not parked on a land approval; schedule it
    /// like any other candidate.
    NotLanding,
    /// Parked in `land`, waiting on a question nobody has answered yet.
    /// Left alone: attempting it now would only re-observe the same pull
    /// request and park again, spending a `gh` call on a decision that has
    /// not changed since the last time this was checked.
    StillWaiting,
    /// Parked in `land`, and the question is settled - answered or
    /// abandoned. Resuming this is the one kind of candidate that must not
    /// wait on a free [`Config::daemon`] concurrency slot: see [`poll`].
    Ready,
}

/// Classify a runnable candidate by whether it is parked on a land-merge
/// approval. Read-only - no claim taken, nothing written - so it is cheap
/// enough to call on every candidate, every poll.
fn land_resume_state(task: &Task) -> LandResume {
    let Some(run_id) = task.runs.last() else {
        return LandResume::NotLanding;
    };
    let Ok(state) = RunState::load(run_id) else {
        return LandResume::NotLanding;
    };
    if state.status != RunStatus::Landing || !state.parked {
        return LandResume::NotLanding;
    }
    let store = ask::Questions::open();
    let waiting = store
        .list()
        .into_iter()
        .filter(|q| &q.run == run_id && q.node == land::APPROVAL_NODE)
        .max_by(|a, b| a.id.cmp(&b.id));
    let Some(mut q) = waiting else {
        return LandResume::Ready;
    };
    if !q.status.open() {
        return LandResume::Ready;
    }
    // `ask::ask_and_wait`'s own deadline is what used to retire a question
    // nobody ever answered; land's approval bypasses that wait entirely (see
    // `land::approval_gate`), so the same deadline has to be enforced here
    // instead, or `graph.answer_timeout` silently stops meaning anything for
    // a land approval and a run can sit `StillWaiting` forever with nobody
    // told to look at it.
    let timeout = Duration::from_secs(state.config.graph.answer_timeout);
    let elapsed = Timestamp::now().as_second() - q.asked_at.as_second();
    if elapsed >= 0 && elapsed as u64 >= timeout.as_secs() {
        q.abandon(format!(
            "no answer within {}s of asking",
            timeout.as_secs().max(1)
        ));
        // If this can't be persisted, do not treat the wait as settled on a
        // guess: fall through and try again next poll.
        if store.put(&mut q).is_ok() {
            return LandResume::Ready;
        }
    }
    LandResume::StillWaiting
}

/// How often the loop rechecks for new work while something it already
/// started is still running, rather than sleeping out the whole
/// [`Opts::poll`] interval.
///
/// Short on purpose: this is what lets a land-merge approval that comes back
/// while another task is mid-competition be noticed and resumed within a
/// fraction of a second, not within the next multi-second poll.
const RECHECK_WHILE_BUSY: Duration = Duration::from_millis(200);

/// Frees one attempt's concurrency slot - `Stop`'s busy count and its entry
/// in `Status::current` - on drop, so both are released even if the attempt
/// panics rather than returning.
///
/// A `Drop` impl rather than statements written after the `.await` it
/// guards: a panic unwinds straight past code placed "after" a call, and
/// `Runner::execute`'s chain reaches deep enough into agent-output parsing
/// that ruling a panic out there is not a bet this loop can make. Without
/// this, one panicking run would leave [`Stop::busy_now`] stuck `true`
/// forever - the idle branch in [`poll`], and with it the janitor, would
/// never run again - and a ghost entry in `Status::current` naming a task
/// nothing is still working on.
struct InFlightGuard<'a> {
    status: &'a Arc<Mutex<Status>>,
    stop: &'a Stop,
    task_id: &'a str,
}

impl Drop for InFlightGuard<'_> {
    fn drop(&mut self) {
        lock(self.status).current.retain(|c| c.task != self.task_id);
        self.stop.exit();
    }
}

/// Poll the queue until stopped, factored out so [`drive`] owns only setup and
/// teardown and cannot skip the teardown on an early return.
///
/// `max_concurrent` bounds how many *ordinary* candidates run at once - see
/// [`crate::config::Daemon::max_concurrent_runs`]. A run parked on a land
/// approval that has since been answered is dispatched outside that bound
/// the moment [`land_resume_state`] reports it [`LandResume::Ready`]: the
/// whole point of parking there is that it must not queue behind whatever
/// else the loop happens to be running, even at the default of one.
async fn poll(
    opts: &Opts,
    queue: &Queue,
    status: &Arc<Mutex<Status>>,
    home: &Path,
    stop: &Stop,
    max_concurrent: usize,
) -> Result<()> {
    // Only consulted by `once`, where a task that just failed is still
    // `runnable` and would otherwise be picked up again inside the same drain.
    // In the long-running mode a later poll retrying a failed task is the point,
    // and the attempt counter is what bounds it.
    let mut attempted: Vec<String> = Vec::new();
    let sem = Arc::new(tokio::sync::Semaphore::new(max_concurrent));
    // A quota hit is a fact about the machine, not the task that happened to
    // surface it, and every other *ordinary* candidate is no less likely to
    // hit the same wall - see the warning below. A land-merge resume is
    // exempt: it is a human decision finishing, not a fresh competition, and
    // must not sit out a quota cooldown it did not cause.
    let quota_cooldown_until: Arc<Mutex<Option<Timestamp>>> = Arc::new(Mutex::new(None));
    let mut inflight: tokio::task::JoinSet<()> = tokio::task::JoinSet::new();

    while !stop.stopped() {
        lock(status).polls += 1;

        // Reap whatever finished since the last tick without blocking on
        // anything still running. `InFlightGuard` already released the slot
        // even if the spawned attempt panicked; this only surfaces that it
        // happened, since a panic swallowed here otherwise leaves no trace.
        while let Some(result) = inflight.try_join_next() {
            if let Err(e) = result {
                tracing::error!("a spawned attempt did not finish cleanly: {e}");
            }
        }

        let swept = sweep_stale_claims(queue, STALE_CLAIM);
        if !swept.is_empty() {
            tracing::warn!(
                "swept {} stale claim(s) left behind by an earlier daemon: {}",
                swept.len(),
                swept.join(", ")
            );
        }
        let reclaimed = reclaim_orphaned_running(queue, opts.max_attempts);
        if !reclaimed.is_empty() {
            tracing::warn!(
                "reclaimed {} task(s) left `running` by a daemon that never \
                 recorded the outcome: {}",
                reclaimed.len(),
                reclaimed.join(", ")
            );
        }

        let candidates: Vec<Task> = runnable(queue)
            .into_iter()
            .filter(|t| !opts.once || !attempted.contains(&t.id))
            .collect();

        let cooling_down =
            lock(&quota_cooldown_until).is_some_and(|until| Timestamp::now() < until);

        let mut started_any = false;
        for candidate in candidates {
            if stop.stopped() {
                break;
            }

            let resume = land_resume_state(&candidate);
            if resume == LandResume::StillWaiting {
                continue;
            }
            let priority = resume == LandResume::Ready;

            if !priority && cooling_down {
                continue;
            }
            let permit = if priority {
                None
            } else {
                match Arc::clone(&sem).try_acquire_owned() {
                    Ok(p) => Some(p),
                    // No ordinary slot free right now. A later candidate in
                    // this same list might still be a priority resume, so
                    // keep looking rather than stopping here.
                    Err(_) => continue,
                }
            };

            // A claim we cannot take means another daemon, or a human running
            // `magi run`, got there first. That is not the task's fault and
            // must not spend one of its attempts: move to the next candidate
            // rather than recording a failure.
            let Ok(claim) = queue.claim(&candidate.id) else {
                tracing::info!("task {} is claimed elsewhere; skipping", candidate.short());
                continue;
            };
            // Re-read under the claim: the task on disk may have been held or
            // edited between the listing and the lock.
            let mut task = match queue.get(&candidate.id) {
                Ok(t) if t.status.runnable() => t,
                Ok(_) => continue,
                Err(e) => {
                    tracing::warn!("could not re-read task {}: {e:#}", candidate.short());
                    continue;
                }
            };
            let task_id = task.id.clone();
            attempted.push(task_id.clone());
            lock(status).idle = false;
            // A stop asked for from here on is "finishing", not "stopped": the
            // run gets to reach a terminal status before the loop returns.
            stop.enter();
            started_any = true;

            let opts = opts.clone();
            let queue = queue.clone();
            let status = Arc::clone(status);
            let stop = stop.clone();
            let quota_cooldown_until = Arc::clone(&quota_cooldown_until);
            inflight.spawn(async move {
                // Held for the whole attempt: dropping either at the end of
                // this task is what releases the claim and, for an ordinary
                // candidate, frees its concurrency slot back to the loop.
                let _claim = claim;
                let _permit = permit;
                // See `InFlightGuard`: this must survive a panic inside `attempt`.
                let _inflight = InFlightGuard {
                    status: &status,
                    stop: &stop,
                    task_id: &task_id,
                };
                let quota = attempt(&opts, &queue, &status, &stop, &mut task).await;
                lock(&status).completed += 1;
                // A quota loss is a fact about the machine, not this task, and
                // the next ordinary candidate the loop offers is no less
                // likely to hit the same wall: without a cooldown here a
                // whole backlog can be run - and failed - in the seconds it
                // takes each attempt to notice the CLI is out of quota.
                if !quota.is_empty() {
                    let hint = quota.iter().find_map(|q| q.reset.as_deref());
                    let reset_at = hint.and_then(|h| parse_reset_hint(h, Timestamp::now()));
                    let wait = quota_wait(
                        reset_at,
                        Timestamp::now(),
                        QUOTA_WAIT_FALLBACK,
                        QUOTA_WAIT_CAP,
                    );
                    let secs = i64::try_from(wait.as_secs()).unwrap_or(i64::MAX);
                    let until = Timestamp::now()
                        .checked_add(jiff::SignedDuration::from_secs(secs))
                        .unwrap_or(Timestamp::MAX);
                    *lock(&quota_cooldown_until) = Some(until);
                    match hint {
                        Some(h) => tracing::warn!(
                            "quota hit; waiting {}s before taking another ordinary task \
                             (CLI reported reset: {h})",
                            wait.as_secs()
                        ),
                        None => tracing::warn!(
                            "quota hit; waiting {}s before taking another ordinary task \
                             (no reset hint reported)",
                            wait.as_secs()
                        ),
                    }
                }
            });
        }

        if started_any {
            continue;
        }

        if stop.busy_now() {
            // Something started on an earlier tick is still running. Recheck
            // soon rather than sleeping out the whole poll interval - a freed
            // slot, or a land approval answered mid-run, must not sit idle
            // for it.
            stop.idle(RECHECK_WHILE_BUSY.min(opts.poll)).await;
            continue;
        }

        // Truly idle: nothing new to start and nothing still running. The
        // disk is quiet, so this is the point for the janitor - folding
        // worktrees and pruning a cache while a sibling run is still
        // building would race the very compile the prune exists to keep,
        // which concurrent runs make possible in a way the old one-at-a-time
        // loop never had to guard against.
        janitor(&opts.repo, opts, home).await;
        lock(status).idle = true;
        if opts.once {
            break;
        }
        stop.idle(opts.poll).await;
    }

    // Never return while a run is still in flight, whichever way the loop
    // above exited: a stop only sets a flag - see `serve_until` - and
    // returning here while `inflight` still holds spawned work would abandon
    // it exactly as a mid-node kill would.
    while let Some(result) = inflight.join_next().await {
        if let Err(e) = result {
            tracing::error!("a spawned attempt did not finish cleanly: {e}");
        }
    }
    Ok(())
}

/// Run one claimed task to a terminal status and record the outcome.
///
/// Every transition is flushed to the queue as it happens, so the state on disk
/// is what actually occurred rather than what this process still intends to
/// write.
async fn attempt(
    opts: &Opts,
    queue: &Queue,
    status: &Arc<Mutex<Status>>,
    stop: &Stop,
    task: &mut Task,
) -> Vec<QuotaLoss> {
    let repo = repo_for(task, &opts.repo);
    tracing::info!(
        "task {} — {} (repo {})",
        task.short(),
        task.title,
        repo.display()
    );

    let mut config = match prepare(&repo, opts) {
        Ok(c) => c,
        Err(e) => {
            // A setup failure spends an attempt even though no run was minted.
            // Without that, a task naming a repository that does not exist
            // would be retried at every poll for as long as the daemon lives.
            task.attempts += 1;
            task.fail(format!("config: {e:#}"), opts.max_attempts);
            record(queue, task);
            return Vec::new();
        }
    };
    apply_solo(&mut config, task);

    // The free-space gate, checked *before* anything is minted: a task that
    // waits out a full disk costs nothing yet, and must not spend an attempt
    // or start a run the machine cannot finish. Held tasks stay in the list
    // for the human to see, and `magi task release` re-queues them when space
    // comes back - the same recovery as any other hold. A volume whose free
    // space cannot be measured closes the gate too: starting a run blind on a
    // disk that may be full is how the machine ends up with 6.7 GB free.
    if let Some(reason) = disk_gate(&repo, &config) {
        task.last_error = Some(reason.clone());
        task.hold(Some(reason.clone()));
        record(queue, task);
        tracing::warn!("holding {} for want of disk space: {reason}", task.short());
        return Vec::new();
    }

    // A resumable run of this task is carried on, never re-competed. The
    // candidates are built and paid for, and a fresh competition races a
    // second implementation against them.
    //
    // Two runs paid for that lesson. Run 01c2 was blocked and the loop
    // started 3cbf on the same task a moment later, duplicating two and a
    // half hours of agent work. Then b25f stalled on a judge that timed out
    // and one that answered with no JSON - `quota: 0`, so nothing the machine
    // was to blame for - and 4043 started **one second** later, buying three
    // fresh implementations to reach the same panel. `RunStatus::resumable`
    // rather than `!done()` is what catches the second case: a stall is
    // terminal, and its cheap recovery re-asks only the absent seats.
    let unfinished = task
        .runs
        .iter()
        .rev()
        .find(|id| {
            RunState::load(id)
                .map(|s| s.status.resumable())
                .unwrap_or(false)
        })
        .cloned();
    let started = match &unfinished {
        Some(id) => {
            tracing::info!("resuming run {id} rather than competing again");
            Runner::resume(id)
        }
        None => Runner::start(&repo, task.instruction.clone(), config).await,
    };
    let mut runner = match started {
        Ok(r) => r,
        Err(e) => {
            task.attempts += 1;
            task.fail(format!("could not start the run: {e:#}"), opts.max_attempts);
            record(queue, task);
            return Vec::new();
        }
    };
    // A stop that means "park" reaches the graph through this handle.
    runner.on_pause(stop.pause());

    // `start` has minted the run, so the task can now point at it. Persisting
    // `Running` before `execute` is what makes a crash mid-run legible.
    let run = runner.state.id.clone();
    task.start(run.clone());
    record(queue, task);
    lock(status).current.push(Current {
        task: task.id.clone(),
        run,
    });

    let detail = match runner.execute().await {
        Ok(()) => describe(&runner.state),
        Err(e) => format!("{e:#}"),
    };
    let verdict = Verdict {
        status: runner.state.status,
        // A run that opened a pull request handed its work over, whatever the
        // gate then decided about merging it.
        left_pr: runner.state.pr.is_some(),
        // Only a rate limit earns the task its attempt back.
        quota_hit: !runner.state.quota.is_empty(),
        // A run that parked was asked to stop; that is not a failure and must
        // not spend an attempt, or replacing the binary a few times would
        // exhaust a task's budget without an agent ever misbehaving.
        parked: runner.state.parked,
        // A quota loss that left nothing viable is the same machine fact as a
        // `Stalled` quota loss; see `settle`'s doc table.
        no_viable_candidates: runner.state.viable().is_empty(),
    };
    settle(task, verdict, &detail, opts.max_attempts);
    record(queue, task);
    tracing::info!(
        "task {} is {} after run {} ({})",
        task.short(),
        task.status.as_str(),
        runner.state.short(),
        label(runner.state.status)
    );
    runner.state.quota
}

/// Cut this attempt's candidate count to one when the task asked to run
/// alone.
///
/// Pure and separate from [`attempt`] so the one thing this feature changes -
/// which `candidates` a `solo` task's run is built with - can be asserted
/// without minting a run: `attempt` drives `graph::Runner`, which spawns real
/// agent CLIs, and no test may do that. `config` is mutated in place, taken by
/// value from the caller's own copy, so a repository's `magi.toml` on disk is
/// never touched - only the `Config` this one attempt hands to `Runner::start`.
fn apply_solo(config: &mut Config, task: &Task) {
    if task.solo {
        config.graph.candidates = 1;
    }
}

/// Load the config for a task's repository, with the merge override applied.
fn prepare(repo: &Path, opts: &Opts) -> Result<Config> {
    let (mut config, _layers) = Config::discover(repo, opts.config.as_deref())?;
    if let Some(mode) = &opts.merge {
        config.merge.mode = merge_mode(mode)?;
    }
    Ok(config)
}

/// The disk janitor, with its housekeeping logged rather than fatal.
///
/// Called only at the loop's idle points, for the reason the caller documents:
/// a prune racing a live compile would delete files mid-build. The config is
/// re-read on every call because the repository that just ran may not be the
/// daemon's own default, and the cache directory is a repository fact.
///
/// `home` is a parameter rather than [`crate::run::home`] read here, for the
/// same reason [`drive`] takes its queue and status file rather than
/// resolving them: a test driving the loop must not reach through to the
/// operator's real home just because the janitor runs on every idle tick.
async fn janitor(repo: &Path, opts: &Opts, home: &Path) {
    let cfg = match prepare(repo, opts) {
        Ok(cfg) => cfg,
        Err(e) => {
            tracing::warn!("housekeep: no config: {e:#}");
            return;
        }
    };
    let out = clean::housekeep(
        &cfg,
        home,
        &crate::run::default_worktree_root(),
        Timestamp::now(),
    )
    .await;
    if out.folded > 0 {
        let unreadable = if out.unreadable > 0 {
            format!(" ({} unreadable)", out.unreadable)
        } else {
            String::new()
        };
        tracing::info!("housekeep: folded {} run(s){unreadable}", out.folded);
    }
    if out.cache_files > 0 {
        tracing::info!(
            "housekeep: pruned {} file(s) ({} bytes) from the shared cache",
            out.cache_files,
            out.cache_freed
        );
    }
}

/// The free-space gate: what stands between this task and a new run, if
/// anything. `Some(reason)` holds the task; `None` lets it start.
///
/// A zero [`Config::disk::min_free_bytes`] opens the gate unconditionally -
/// the operator opted out. A measurement failure is a gate, not a pass: both
/// sides of "cannot tell" are served by not starting.
fn disk_gate(repo: &Path, config: &Config) -> Option<String> {
    let min = config.disk.min_free_bytes;
    if min == 0 {
        return None;
    }
    match crate::disk::free_bytes(repo) {
        Ok(free) => crate::disk::gate(free, min),
        Err(e) => Some(format!(
            "could not measure free space on {} ({e}); the disk gate refuses \
             to let a run start blind",
            repo.display()
        )),
    }
}

/// How long to wait before offering another task when a run lost a seat to a
/// rate limit and its [`QuotaLoss::reset`] carried no hint [`parse_reset_hint`]
/// could read, or carried nothing at all. Long enough that a quota outage
/// cannot burn through a whole backlog in the few seconds each doomed attempt
/// takes to fail; short enough that a quota which clears early is not left
/// idle for the fallback's sake.
const QUOTA_WAIT_FALLBACK: Duration = Duration::from_secs(5 * 60);

/// Longest a parsed reset hint may push the wait out to. The hint comes from
/// the CLI's own words, not a contract, so a parsing slip that lands a day
/// away must not leave the loop asleep for a day.
const QUOTA_WAIT_CAP: Duration = Duration::from_secs(30 * 60);

/// How long [`poll`] should wait before offering the next task, after a run
/// lost at least one seat to a rate limit.
///
/// Pure and separate from the loop so the policy can be exercised without a
/// real quota outage. `reset_at` is the time [`parse_reset_hint`] made of the
/// CLI's free-text hint, if it could; `fallback` is what to wait when there is
/// nothing to parse, or the parsed time has already passed; `cap` bounds how
/// far a parsed hint is trusted to push the wait out.
fn quota_wait(
    reset_at: Option<Timestamp>,
    now: Timestamp,
    fallback: Duration,
    cap: Duration,
) -> Duration {
    match reset_at {
        Some(at) if at > now => {
            let secs = u64::try_from(at.as_second() - now.as_second()).unwrap_or(0);
            Duration::from_secs(secs).min(cap)
        }
        _ => fallback,
    }
}

/// Best-effort reading of a [`QuotaLoss::reset`] hint into a concrete time.
///
/// `reset` is deliberately free text — see [`crate::agent::Quota`], which
/// explains why parsing it exactly "would be a bug factory" — so this only
/// recognises the one shape actually observed in the wild, `"H:MMam/pm
/// (Zone)"`, and returns `None` for anything else rather than guess at a
/// format nobody has seen. A clock reading already past today is read as
/// tomorrow's: a CLI naming a same-day reset that has already gone by means
/// the window rolled over while nothing was watching.
fn parse_reset_hint(text: &str, now: Timestamp) -> Option<Timestamp> {
    let open = text.find('(')?;
    let close = text.rfind(')')?;
    if close <= open {
        return None;
    }
    let zone = text[open + 1..close].trim();
    let clock = text[..open].trim().to_lowercase();
    let (digits, pm) = clock
        .strip_suffix("am")
        .map(|d| (d, false))
        .or_else(|| clock.strip_suffix("pm").map(|d| (d, true)))?;
    let (h, m) = digits.trim().split_once(':')?;
    let mut hour: i8 = h.trim().parse().ok()?;
    let minute: i8 = m.trim().parse().ok()?;
    if !(1..=12).contains(&hour) || !(0..=59).contains(&minute) {
        return None;
    }
    if pm && hour != 12 {
        hour += 12;
    } else if !pm && hour == 12 {
        hour = 0;
    }
    let tz = jiff::tz::TimeZone::get(zone).ok()?;
    let candidate = now
        .to_zoned(tz)
        .with()
        .hour(hour)
        .minute(minute)
        .second(0)
        .millisecond(0)
        .microsecond(0)
        .nanosecond(0)
        .build()
        .ok()?;
    let mut at = candidate.timestamp();
    if at <= now {
        at += jiff::SignedDuration::from_hours(24);
    }
    Some(at)
}

/// Which repository a task runs in. A task that names none — the normal case
/// for one filed from a phone — runs in the daemon's own default.
fn repo_for(task: &Task, fallback: &Path) -> PathBuf {
    if task.repo.as_os_str().is_empty() || task.repo == Path::new(".") {
        return fallback.to_path_buf();
    }
    task.repo.clone()
}

/// Persist a transition. A queue write failure is logged rather than fatal: the
/// run already happened, and taking the daemon down would only add a lost
/// backlog to a full disk.
fn record(queue: &Queue, task: &mut Task) {
    if let Err(e) = queue.put(task) {
        tracing::error!("could not record task {}: {e:#}", task.short());
    }
}

/// Every runnable task, in the order the loop should try them.
///
/// The head of this list is exactly what [`Queue::next_runnable`] offers; the
/// tail exists so that a claim somebody else holds costs the loop the next
/// candidate rather than a whole poll interval of idleness.
fn runnable(queue: &Queue) -> Vec<Task> {
    let mut tasks: Vec<Task> = queue
        .list()
        .into_iter()
        .filter(|t| t.status.runnable())
        .collect();
    tasks.sort_unstable_by(|a, b| b.priority.cmp(&a.priority).then(a.id.cmp(&b.id)));
    tasks
}

/// Why a run ended where it did, in one line, for [`Task::last_error`].
///
/// A stalled run names the seats the quota took out: "out of quota" is not
/// actionable, while "judge-2, judge-3 hit a limit" tells the operator which
/// agent to replace or which plan to top up.
fn describe(state: &RunState) -> String {
    let mut detail = if state.status == RunStatus::Stalled {
        let mut seats: Vec<&str> = state.quota.iter().map(|q| q.seat.as_str()).collect();
        seats.sort_unstable();
        seats.dedup();
        if seats.is_empty() {
            "the judging panel lost its quorum".to_owned()
        } else {
            format!(
                "the judging panel lost its quorum; quota took out {}",
                seats.join(", ")
            )
        }
    } else {
        format!("run ended {}", label(state.status))
    };
    if let Some(last) = state.events.last() {
        detail.push_str(&format!(" ({}: {})", last.node, last.message));
    }
    detail.push_str(&format!(" [run {}]", state.id));
    detail
}

/// Stable lower-case name for a run status, for logs and task errors.
/// One definition of a status's name, on the type that owns it: this table
/// used to live here as a second copy, and a status renamed in one place would
/// have gone on reading correctly in the other.
fn label(status: RunStatus) -> &'static str {
    status.as_str()
}

/// Parse a merge mode override.
fn merge_mode(mode: &str) -> Result<MergeMode> {
    match mode {
        "none" => Ok(MergeMode::None),
        "local" => Ok(MergeMode::Local),
        "pr" => Ok(MergeMode::Pr),
        other => bail!("unknown merge mode `{other}`; expected none, local or pr"),
    }
}

/// Take the status lock, recovering from a poisoned one.
///
/// A panic elsewhere must not silently stop the heartbeat: the status is plain
/// data, and the worst a poisoned lock can hold is a stale timestamp.
fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
    mutex
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::queue::{Source, TaskStatus};
    use pretty_assertions::assert_eq;

    fn task() -> Task {
        Task::new(
            "add retries".to_owned(),
            "add retries".to_owned(),
            PathBuf::from("/repo"),
            Source::Human,
        )
    }

    #[test]
    fn every_run_status_settles_the_task_it_came_from() {
        // run status, resulting task status, attempts still standing after one
        let table = [
            (RunStatus::Merged, TaskStatus::Done, 1),
            (RunStatus::Ready, TaskStatus::Done, 1),
            (RunStatus::Stalled, TaskStatus::Failed, 0),
            (RunStatus::Blocked, TaskStatus::Failed, 1),
            (RunStatus::Failed, TaskStatus::Failed, 1),
            (RunStatus::Prep, TaskStatus::Failed, 1),
            (RunStatus::Implementing, TaskStatus::Failed, 1),
            (RunStatus::Judging, TaskStatus::Failed, 1),
            (RunStatus::Deliberating, TaskStatus::Failed, 1),
            (RunStatus::Voting, TaskStatus::Failed, 1),
            (RunStatus::Reviewing, TaskStatus::Failed, 1),
            (RunStatus::Gating, TaskStatus::Failed, 1),
        ];
        for (run, want, attempts) in table {
            let mut t = task();
            t.start("20260902-000000-aaaa".to_owned());
            settle(
                &mut t,
                Verdict {
                    status: run,
                    left_pr: false,
                    parked: false,
                    quota_hit: matches!(run, RunStatus::Stalled),
                    no_viable_candidates: false,
                },
                "why",
                2,
            );
            assert_eq!(t.status, want, "task status after {}", label(run));
            assert_eq!(t.attempts, attempts, "attempts after {}", label(run));
        }
    }

    #[test]
    fn a_quota_stall_costs_the_task_no_attempt_but_a_block_does() {
        let mut stalled = task();
        stalled.start("20260902-000000-aaaa".to_owned());
        settle(
            &mut stalled,
            Verdict {
                status: RunStatus::Stalled,
                left_pr: false,
                parked: false,
                quota_hit: true,
                no_viable_candidates: false,
            },
            "quota",
            1,
        );
        assert_eq!(stalled.attempts, 0);
        assert!(
            stalled.status.runnable(),
            "a machine problem must leave the task in line"
        );

        let mut blocked = task();
        blocked.start("20260902-000000-aaaa".to_owned());
        settle(
            &mut blocked,
            Verdict {
                status: RunStatus::Blocked,
                left_pr: false,
                parked: false,
                quota_hit: false,
                no_viable_candidates: false,
            },
            "findings open",
            1,
        );
        assert_eq!(blocked.attempts, 1);
        assert_eq!(
            blocked.status,
            TaskStatus::Held,
            "the last attempt hands the task to a human"
        );
    }

    #[test]
    fn a_run_that_opened_a_pull_request_is_never_re_competed() {
        // Attempts to spare: without the pull request this task would go
        // straight back in line and run the whole competition again.
        let mut delivered = task();
        delivered.start("20260903-080619-01c2".to_owned());
        settle(
            &mut delivered,
            Verdict {
                status: RunStatus::Blocked,
                left_pr: true,
                parked: false,
                quota_hit: false,
                no_viable_candidates: false,
            },
            "no check status",
            4,
        );
        assert_eq!(
            delivered.status,
            TaskStatus::Held,
            "a pull request waiting on CI or a person is not a retryable failure"
        );
        assert!(
            !delivered.status.runnable(),
            "the loop must not pick this task up again"
        );
        assert_eq!(
            delivered.last_error.as_deref(),
            Some("no check status"),
            "the operator needs to be told what the gate was waiting for"
        );

        // The same status without a pull request is a plain failure, and with
        // attempts left it is retried.
        let mut empty_handed = task();
        empty_handed.start("20260903-080619-01c2".to_owned());
        settle(
            &mut empty_handed,
            Verdict {
                status: RunStatus::Blocked,
                left_pr: false,
                parked: false,
                quota_hit: false,
                no_viable_candidates: false,
            },
            "findings open",
            4,
        );
        assert_eq!(empty_handed.status, TaskStatus::Failed);
        assert!(empty_handed.status.runnable());
    }

    #[test]
    fn parking_costs_the_task_no_attempt_and_leaves_it_in_line() {
        // Parking is the operator asking for the process back - to replace the
        // binary, most of all. The run's work is intact on disk, so this is
        // not a failed attempt, and charging for it would mean a few upgrades
        // could exhaust a budget meant for agents that misbehaved.
        let mut parked = task();
        parked.start("20260903-183634-2d98".to_owned());
        settle(
            &mut parked,
            Verdict {
                status: RunStatus::Implementing,
                left_pr: false,
                quota_hit: false,
                parked: true,
                no_viable_candidates: false,
            },
            "parked after `implementing`",
            2,
        );
        assert_eq!(parked.attempts, 0, "a park is refunded");
        assert!(
            parked.status.runnable(),
            "and the task stays in line so the next loop resumes its run"
        );
        assert_eq!(
            parked.last_error.as_deref(),
            Some("parked after `implementing`"),
            "the card says where it stopped"
        );

        // Without the park flag the same non-terminal status is what it always
        // was: `execute` returning mid-flight, which is a bug and spends an
        // attempt so a task cannot loop on it forever.
        let mut broken = task();
        broken.start("20260903-183634-2d98".to_owned());
        settle(
            &mut broken,
            Verdict {
                status: RunStatus::Implementing,
                left_pr: false,
                quota_hit: false,
                parked: false,
                no_viable_candidates: false,
            },
            "returned mid-flight",
            2,
        );
        assert_eq!(broken.attempts, 1);
    }

    #[test]
    fn only_a_rate_limit_buys_the_task_its_attempt_back() {
        // Run e633: quorum lost because two judges answered with the wrong
        // JSON shape, `quota: []`. Refunding that takes the bound off the
        // retry loop, and each retry pays for a fresh hour-long implement
        // wave before it can fail the same way.
        let mut flaky = task();
        flaky.start("20260903-123023-e633".to_owned());
        settle(
            &mut flaky,
            Verdict {
                status: RunStatus::Stalled,
                left_pr: false,
                parked: false,
                quota_hit: false,
                no_viable_candidates: false,
            },
            "verdict rests on 1 of 3 judges",
            2,
        );
        assert_eq!(
            flaky.attempts, 1,
            "flakiness spends an attempt, so `max_attempts` still bounds it"
        );
        assert!(flaky.status.runnable(), "and it is still worth retrying");

        // The same status, lost to a rate limit, is the machine's fault.
        let mut limited = task();
        limited.start("20260903-123023-e633".to_owned());
        settle(
            &mut limited,
            Verdict {
                status: RunStatus::Stalled,
                left_pr: false,
                parked: false,
                quota_hit: true,
                no_viable_candidates: false,
            },
            "judge-2, judge-3 out of quota",
            2,
        );
        assert_eq!(limited.attempts, 0, "a quota window is refunded");
        assert!(limited.status.runnable());

        // And the bound really binds: a task that keeps stalling on flakiness
        // reaches a human instead of running the roster forever.
        let mut worn = task();
        for _ in 0..2 {
            worn.release();
        }
        worn.start("20260903-123023-e633".to_owned());
        worn.attempts = 2;
        settle(
            &mut worn,
            Verdict {
                status: RunStatus::Stalled,
                left_pr: false,
                parked: false,
                quota_hit: false,
                no_viable_candidates: false,
            },
            "no quorum again",
            2,
        );
        assert_eq!(worn.status, TaskStatus::Held);
        assert!(!worn.status.runnable());
    }

    #[test]
    fn a_quota_wipeout_that_leaves_nothing_to_judge_also_costs_no_attempt() {
        // The implement wave loses every seat to the same rate limit and
        // `after_implement` bails with nothing viable, which surfaces as
        // `Failed` rather than `Stalled`. That is the same machine fact the
        // `Stalled`-quota row already refunds, and must be refunded the same
        // way, or a quota outage quietly holds every task it touches instead
        // of leaving them in line for the reset.
        let mut wiped_out = task();
        wiped_out.start("20260907-025000-a1b2".to_owned());
        settle(
            &mut wiped_out,
            Verdict {
                status: RunStatus::Failed,
                left_pr: false,
                parked: false,
                quota_hit: true,
                no_viable_candidates: true,
            },
            "no candidate produced a change; nothing to judge",
            2,
        );
        assert_eq!(wiped_out.attempts, 0, "a total quota wipeout is refunded");
        assert!(
            wiped_out.status.runnable(),
            "a machine problem must leave the task in line"
        );

        // This is the exemption that must stay narrow: a candidate that did
        // produce a change, and then failed for some other reason, still
        // spends the attempt even though a seat elsewhere hit its quota.
        // Otherwise every ordinary failure that happens to share a run with
        // an unrelated rate limit would be refunded for free.
        let mut partial_progress = task();
        partial_progress.start("20260907-025500-c3d4".to_owned());
        settle(
            &mut partial_progress,
            Verdict {
                status: RunStatus::Failed,
                left_pr: false,
                parked: false,
                quota_hit: true,
                no_viable_candidates: false,
            },
            "gate failed on the winning candidate",
            2,
        );
        assert_eq!(
            partial_progress.attempts, 1,
            "a candidate that actually produced a change spends the attempt \
             even though some other seat hit its quota"
        );
        assert!(partial_progress.status.runnable());
    }

    #[test]
    fn reclaim_refunds_a_recovered_quota_wipeout_the_same_way_a_live_settle_does() {
        // `reclaim` builds its own `Verdict` from a `RunState` it loads off
        // disk, and that construction must reach the same conclusion as the
        // one `attempt` builds from a live run, or a crash at exactly the
        // wrong moment gives a recovered task a different policy than one a
        // daemon finished settling itself.
        let mut t = task();
        t.start("20260907-025000-a1b2".to_owned());
        let mut state = run_state(RunStatus::Failed);
        state.quota.push(QuotaLoss {
            seat: "cand-a".to_owned(),
            node: "implement".to_owned(),
            at: Timestamp::now(),
            reset: None,
        });
        assert!(
            state.viable().is_empty(),
            "no candidate was added, so nothing is viable"
        );
        reclaim(&mut t, Some(state), 2);
        assert_eq!(t.attempts, 0, "a recovered quota wipeout is refunded");
        assert!(t.status.runnable());
    }

    #[test]
    fn a_held_task_is_never_offered_to_the_loop() {
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());
        for (n, priority) in [(1, 0), (2, 5), (3, 5)] {
            let mut t = task();
            t.id = format!("2026090{n}-000000-000{n}");
            t.priority = priority;
            queue.put(&mut t).unwrap();
        }
        let mut held = task();
        held.id = "20260909-000000-9999".to_owned();
        held.priority = 99;
        held.hold(None);
        queue.put(&mut held).unwrap();

        let order: Vec<String> = runnable(&queue).into_iter().map(|t| t.id).collect();
        assert_eq!(order.len(), 3);
        assert!(!order.contains(&held.id));
        assert_eq!(
            order.first().cloned(),
            queue.next_runnable().map(|t| t.id),
            "the loop's first candidate is exactly what the queue offers"
        );
        assert_eq!(
            order,
            vec![
                "20260902-000000-0002".to_owned(),
                "20260903-000000-0003".to_owned(),
                "20260901-000000-0001".to_owned(),
            ],
            "priority first, then oldest, so nothing starves"
        );
    }

    #[test]
    fn sweep_removes_an_old_unparseable_lock_and_keeps_a_live_one() {
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());
        let mut old = task();
        old.id = "20260101-000000-old0".to_owned();
        queue.put(&mut old).unwrap();
        let mut fresh = task();
        fresh.id = "20260101-000000-new0".to_owned();
        queue.put(&mut fresh).unwrap();

        // No parseable pid at all, so age is the only signal there is to
        // check - unlike a real `Queue::claim`, which always names a real,
        // and therefore alive, pid this test cannot fake as dead.
        std::fs::write(dir.path().join(format!("{}.lock", old.id)), "not a pid").unwrap();
        std::thread::sleep(Duration::from_millis(60));
        let live = queue.claim(&fresh.id).unwrap();

        let swept = sweep_stale_claims(&queue, Duration::from_millis(50));
        assert_eq!(swept, vec![old.id.clone()]);
        assert!(
            queue.claim(&old.id).is_ok(),
            "an unparseable lock older than the threshold is swept"
        );
        assert!(
            queue.claim(&fresh.id).is_err(),
            "a live pid protects its lock regardless of age"
        );
        drop(live);
    }

    #[test]
    fn an_old_lock_whose_pid_is_still_alive_is_never_swept_by_age_alone() {
        // The regression this guards: `sweep` now runs concurrently with
        // every attempt this daemon itself has spawned (see
        // `InFlightGuard`), not only between them the way a single
        // sequential loop once did. A run that legitimately outlives
        // `older_than` still has this very process's own live pid sitting in
        // its own lock file on every later sweep, and deciding by age alone
        // would delete that still-valid claim out from under the attempt
        // that holds it - which `reclaim_orphaned_running` would then read
        // as abandoned and hand to a second, competing attempt.
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());
        let mut t = task();
        t.id = "20260101-000000-live".to_owned();
        queue.put(&mut t).unwrap();

        let claim = queue.claim(&t.id).unwrap();
        std::thread::sleep(Duration::from_millis(60));

        let swept = sweep_stale_claims(&queue, Duration::from_millis(50));
        assert!(
            swept.is_empty(),
            "a lock naming a live pid must never be swept by age, no matter how old: {swept:?}"
        );
        assert!(
            queue.claim(&t.id).is_err(),
            "the lock still protects its task"
        );
        drop(claim);
    }

    /// A pid past any real process table, but not `u32::MAX`: Windows'
    /// `tasklist` answers that one with "invalid query" rather than "no such
    /// process", which [`crate::proc::pid_alive`] - correctly - cannot tell
    /// apart from a check it simply could not run, so it would read as
    /// alive. See `proc::tests` for the same choice made for the same
    /// reason.
    const DEAD_PID: u32 = 999_999_999;

    #[test]
    fn a_lock_naming_a_dead_pid_is_swept_at_once_regardless_of_age() {
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());
        let mut t = task();
        t.id = "20260101-000000-dead".to_owned();
        queue.put(&mut t).unwrap();

        // Written directly rather than through `Queue::claim`, which would
        // stamp this test process's own very much alive pid and defeat the
        // point: this is what a `.lock` left by a `SIGKILL`ed daemon looks
        // like moments after it died, not six hours later.
        std::fs::write(
            dir.path().join(format!("{}.lock", t.id)),
            DEAD_PID.to_string(),
        )
        .unwrap();

        let swept = sweep_stale_claims(&queue, Duration::from_secs(6 * 60 * 60));
        assert_eq!(
            swept,
            vec![t.id.clone()],
            "a dead owner is reclaimed immediately, not after STALE_CLAIM"
        );
        assert!(queue.claim(&t.id).is_ok(), "the task is claimable again");
    }

    #[test]
    fn sweeping_on_every_poll_catches_a_lock_that_appears_after_the_first_sweep() {
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());
        let mut t = task();
        t.id = "20260101-000000-late".to_owned();
        queue.put(&mut t).unwrap();

        // Tick one, standing in for the sweep `poll` already runs at
        // startup: nothing to find yet.
        assert!(
            sweep_stale_claims(&queue, Duration::from_secs(6 * 60 * 60)).is_empty(),
            "nothing has claimed the task yet"
        );

        // A second daemon claims the task and dies before it ever writes
        // `running`, well after this loop's own startup sweep already ran.
        std::fs::write(
            dir.path().join(format!("{}.lock", t.id)),
            DEAD_PID.to_string(),
        )
        .unwrap();

        // Tick two, standing in for a poll long into this daemon's uptime:
        // the same function, called again, notices what only just appeared -
        // proving the sweep is not a one-shot startup check.
        let swept = sweep_stale_claims(&queue, Duration::from_secs(6 * 60 * 60));
        assert_eq!(swept, vec![t.id.clone()]);
    }

    #[test]
    fn a_running_task_behind_a_dead_daemons_lock_recovers_once_swept_and_keeps_its_history() {
        // `reclaim_orphaned_running` looks up the task's last run, which
        // touches `run::home()`; the first call anywhere in this binary wins,
        // so this is a no-op if another test already pinned one, and either
        // way the run id below is never written under it.
        crate::run::set_home(std::env::temp_dir().join("magi-daemon-test-home"));
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());
        let mut t = task();
        t.id = "20260101-000000-crsh".to_owned();
        t.status = TaskStatus::Running;
        t.attempts = 1;
        // No `run.json` behind this id: standing in for a run this test does
        // not need to make readable, since the point is the lock, not the
        // recovery table `reclaim` already has its own tests for.
        t.runs.push("20260904-000000-4043".to_owned());
        queue.put(&mut t).unwrap();

        // The crashed daemon's own claim, naming a pid nothing on the
        // machine holds anymore.
        std::fs::write(
            dir.path().join(format!("{}.lock", t.id)),
            DEAD_PID.to_string(),
        )
        .unwrap();

        // Before the lock is swept the task looks claimed, and
        // `reclaim_orphaned_running` must leave it alone - this is exactly
        // the bug: a `running` task stranded behind a dead daemon's lock,
        // invisible to the claim-as-proof check because the lock outlived
        // the process that wrote it.
        assert!(reclaim_orphaned_running(&queue, 2).is_empty());
        assert_eq!(queue.get(&t.id).unwrap().status, TaskStatus::Running);

        let swept = sweep_stale_claims(&queue, Duration::from_secs(6 * 60 * 60));
        assert_eq!(swept, vec![t.id.clone()]);

        let reclaimed = reclaim_orphaned_running(&queue, 2);
        assert_eq!(reclaimed, vec![t.id.clone()]);
        let after = queue.get(&t.id).unwrap();
        assert_eq!(
            after.status,
            TaskStatus::Held,
            "no run.json to recover from, so a human is asked"
        );
        assert_eq!(
            after.runs,
            vec!["20260904-000000-4043".to_owned()],
            "the crashed run's id is kept as evidence, not discarded"
        );
    }

    fn run_state(status: RunStatus) -> RunState {
        let mut state = RunState::new(
            PathBuf::from("/repo"),
            "main".to_owned(),
            "abc1234def".to_owned(),
            "add retries".to_owned(),
            Config::default(),
        );
        state.status = status;
        state
    }

    fn approval_question(run: &str) -> ask::Question {
        ask::Question::new(
            run.to_owned(),
            land::APPROVAL_NODE.to_owned(),
            "land".to_owned(),
            "merge?".to_owned(),
            String::new(),
            vec!["merge".to_owned(), "hold".to_owned()],
        )
    }

    #[test]
    fn land_resume_state_leaves_a_fresh_open_question_waiting() {
        crate::run::set_home(std::env::temp_dir().join("magi-daemon-test-home"));
        let mut state = run_state(RunStatus::Landing);
        state.id = "20260101-000000-fre1".to_owned();
        state.parked = true;
        state.save().unwrap();
        ask::Questions::open()
            .put(&mut approval_question(&state.id))
            .unwrap();

        let mut t = task();
        t.runs.push(state.id.clone());
        assert_eq!(
            land_resume_state(&t),
            LandResume::StillWaiting,
            "nobody has answered and the timeout has not passed"
        );
    }

    #[test]
    fn land_resume_state_abandons_a_question_that_outlived_answer_timeout() {
        // `ask::ask_and_wait`'s own deadline used to retire a question
        // nobody answered; land's approval bypasses that wait (see
        // `land::approval_gate`), so this is now the only place
        // `graph.answer_timeout` is enforced for a land approval at all.
        crate::run::set_home(std::env::temp_dir().join("magi-daemon-test-home"));
        let mut state = run_state(RunStatus::Landing);
        state.id = "20260101-000000-exp1".to_owned();
        state.parked = true;
        state.config.graph.answer_timeout = 60;
        state.save().unwrap();

        let store = ask::Questions::open();
        let mut q = approval_question(&state.id);
        q.asked_at = Timestamp::now() - jiff::SignedDuration::from_secs(120);
        store.put(&mut q).unwrap();

        let mut t = task();
        t.runs.push(state.id.clone());
        assert_eq!(
            land_resume_state(&t),
            LandResume::Ready,
            "an expired question must not be waited on forever"
        );

        let after = store.get(&q.id).unwrap();
        assert!(
            !after.status.open(),
            "the question is abandoned, not silently ignored"
        );
        assert!(
            after.resolution().is_none(),
            "an abandoned question is not read as a decision"
        );
    }

    #[test]
    fn reclaim_settles_a_running_task_against_its_last_run() {
        let mut t = task();
        t.start("20260904-000000-4043".to_owned());
        reclaim(&mut t, Some(run_state(RunStatus::Ready)), 2);
        assert_eq!(
            t.status,
            TaskStatus::Done,
            "a run that actually finished must not stay `running` forever"
        );
    }

    #[test]
    fn reclaim_reuses_the_same_retry_policy_as_a_live_settle() {
        // A blocked run with attempts left goes back to `Failed`, exactly as
        // it would from `attempt` itself - `reclaim` must not invent a second
        // policy for a task a daemon merely stopped without reporting.
        let mut t = task();
        t.start("20260904-000000-4043".to_owned());
        reclaim(&mut t, Some(run_state(RunStatus::Blocked)), 2);
        assert_eq!(t.status, TaskStatus::Failed);
        assert!(t.status.runnable());
    }

    #[test]
    fn reclaim_holds_a_running_task_whose_run_cannot_be_found() {
        let mut t = task();
        t.start("20260904-000000-4043".to_owned());
        reclaim(&mut t, None, 2);
        assert_eq!(t.status, TaskStatus::Held);
        assert!(
            t.last_error
                .as_deref()
                .is_some_and(|e| e.contains("running")),
            "the operator needs to know why this task was held"
        );
    }

    #[test]
    fn orphaned_running_tasks_are_reclaimed_but_live_ones_are_left_alone() {
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());

        // No run recorded, so this never has to touch `RunState::load`.
        let mut orphaned = task();
        orphaned.id = "20260904-000000-orph".to_owned();
        orphaned.status = TaskStatus::Running;
        orphaned.attempts = 1;
        queue.put(&mut orphaned).unwrap();

        let mut alive = task();
        alive.id = "20260904-000000-live".to_owned();
        alive.status = TaskStatus::Running;
        alive.attempts = 1;
        queue.put(&mut alive).unwrap();
        let _held_by_a_live_daemon = queue.claim(&alive.id).unwrap();

        let mut queued = task();
        queued.id = "20260904-000000-wait".to_owned();
        queue.put(&mut queued).unwrap();

        let reclaimed = reclaim_orphaned_running(&queue, 2);
        assert_eq!(reclaimed, vec![orphaned.id.clone()]);

        assert_eq!(
            queue.get(&orphaned.id).unwrap().status,
            TaskStatus::Held,
            "nothing was driving it and there was no run to recover"
        );
        assert_eq!(
            queue.get(&alive.id).unwrap().status,
            TaskStatus::Running,
            "a live claim must protect the task it belongs to"
        );
        assert_eq!(queue.get(&queued.id).unwrap().status, TaskStatus::Queued);
    }

    #[test]
    fn an_already_claimed_task_is_skipped_rather_than_failed() {
        let dir = tempfile::tempdir().unwrap();
        let queue = Queue::at(dir.path().to_path_buf());
        let mut only = task();
        queue.put(&mut only).unwrap();

        let _elsewhere = queue.claim(&only.id).unwrap();
        let candidates = runnable(&queue);
        assert_eq!(candidates.len(), 1, "the task is still runnable");
        assert!(
            queue.claim(&candidates[0].id).is_err(),
            "the loop cannot take a claim somebody else holds"
        );

        let after = queue.get(&only.id).unwrap();
        assert_eq!(after.status, TaskStatus::Queued);
        assert_eq!(
            after.attempts, 0,
            "losing the race is not an attempt at the task"
        );
        assert_eq!(after.last_error, None);
    }

    #[test]
    fn the_status_file_round_trips_and_its_heartbeat_advances() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("daemon.json");

        let mut status = Status::new();
        status.idle = false;
        status.completed = 7;
        status.current = vec![Current {
            task: "20260902-000000-t111".to_owned(),
            run: "20260902-000001-r111".to_owned(),
        }];
        write_status_to(&path, &status).unwrap();
        let first: Status = serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
        assert_eq!(first.schema, SCHEMA);
        assert_eq!(first.pid, std::process::id());
        assert!(!first.idle);
        assert_eq!(first.completed, 7);
        assert_eq!(first.current, status.current);
        assert!(
            !path.with_extension("json.tmp").exists(),
            "the temp file is renamed, not left behind"
        );

        std::thread::sleep(Duration::from_millis(5));
        status.updated_at = Timestamp::now();
        status.polls = 3;
        write_status_to(&path, &status).unwrap();
        let second: Status =
            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
        assert!(
            second.updated_at > first.updated_at,
            "a reader can only detect staleness if the heartbeat moves"
        );
        assert_eq!(
            second.started_at, first.started_at,
            "the start time is not a heartbeat"
        );
        assert_eq!(second.polls, 3);
    }

    #[test]
    fn reading_counts_as_running_only_while_its_heartbeat_is_fresh() {
        let dir = tempfile::tempdir().unwrap();

        assert!(read_status(dir.path()).is_none(), "no file, no daemon");

        let mut status = Status::new();
        status.updated_at = Timestamp::now() - jiff::SignedDuration::from_secs(60);
        write_status_to(&dir.path().join("daemon.json"), &status).unwrap();
        let stale = read_status(dir.path()).unwrap();
        assert!(
            !stale.running(Timestamp::now()),
            "a minute without a heartbeat is a dead daemon, not a busy one"
        );
        assert!(stale.age_secs(Timestamp::now()).is_some_and(|s| s >= 55));

        status.updated_at = Timestamp::now();
        write_status_to(&dir.path().join("daemon.json"), &status).unwrap();
        let fresh = read_status(dir.path()).unwrap();
        assert!(fresh.running(Timestamp::now()));
    }

    #[test]
    fn only_a_live_daemon_on_this_very_run_counts_as_working_on_it() {
        let dir = tempfile::tempdir().unwrap();
        let now = Timestamp::now();
        let mine = "20260903-080619-01c2";

        assert!(
            !is_working_on(dir.path(), mine, now),
            "no status file means nobody is working on anything"
        );

        let mut status = Status::new();
        status.current = vec![Current {
            task: "20260903-080340-0167".to_owned(),
            run: mine.to_owned(),
        }];
        status.updated_at = now;
        write_status_to(&dir.path().join("daemon.json"), &status).unwrap();
        assert!(is_working_on(dir.path(), mine, now));
        assert!(
            !is_working_on(dir.path(), "20260903-105039-3cbf", now),
            "a daemon busy with one run is not working on another"
        );

        // A killed daemon stops writing heartbeats but leaves the file behind
        // naming the run it died in. That run must not be undeletable forever.
        status.updated_at = now - jiff::SignedDuration::from_secs(600);
        write_status_to(&dir.path().join("daemon.json"), &status).unwrap();
        assert!(
            !is_working_on(dir.path(), mine, now),
            "a stale heartbeat is a dead daemon, so its run is a leftover"
        );
    }

    #[test]
    fn a_newer_status_file_still_yields_a_reading() {
        let dir = tempfile::tempdir().unwrap();
        // A field this build has never heard of must not turn the reading into
        // nothing at all; that is the whole reason the reader is permissive.
        std::fs::write(
            dir.path().join("daemon.json"),
            serde_json::json!({
                "schema": 2,
                "updated_at": Timestamp::now().to_string(),
                "idle": true,
                "surprise": { "nested": [1, 2, 3] },
            })
            .to_string(),
        )
        .unwrap();

        let reading = read_status(dir.path()).expect("a forward-compatible read");
        assert!(reading.running(Timestamp::now()));
        assert!(reading.idle);
        assert!(reading.current.is_empty());
    }

    #[test]
    fn an_older_daemons_single_object_current_still_reads_as_a_one_item_list() {
        // A daemon started before `current` became a list keeps writing this
        // shape on every heartbeat until it is restarted. A rolling upgrade
        // - a newer `magi web` or `magi doctor` reading an older `magi
        // serve`'s heartbeat - must still see the run it is on, not "no
        // daemon" from a type mismatch failing the whole struct.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("daemon.json"),
            serde_json::json!({
                "schema": 1,
                "pid": 4242,
                "updated_at": Timestamp::now().to_string(),
                "idle": false,
                "current": {"task": "20260902-140501-aaaa", "run": "20260902-140502-bbbb"},
                "completed": 3,
                "polls": 9,
            })
            .to_string(),
        )
        .unwrap();

        let reading = read_status(dir.path()).expect("an older shape must still parse");
        assert!(reading.running(Timestamp::now()));
        assert_eq!(
            reading.current,
            vec![Current {
                task: "20260902-140501-aaaa".to_owned(),
                run: "20260902-140502-bbbb".to_owned(),
            }]
        );
    }

    #[test]
    fn an_absent_or_null_current_reads_as_idle_not_a_parse_failure() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("daemon.json"),
            serde_json::json!({
                "schema": 1,
                "updated_at": Timestamp::now().to_string(),
                "idle": true,
                "current": null,
            })
            .to_string(),
        )
        .unwrap();
        let with_null = read_status(dir.path()).expect("null must still parse");
        assert!(with_null.current.is_empty());

        std::fs::write(
            dir.path().join("daemon.json"),
            serde_json::json!({
                "schema": 1,
                "updated_at": Timestamp::now().to_string(),
                "idle": true,
            })
            .to_string(),
        )
        .unwrap();
        let absent = read_status(dir.path()).expect("a missing field must still parse");
        assert!(absent.current.is_empty());
    }

    #[test]
    fn a_task_without_a_repository_runs_in_the_daemons_default() {
        let fallback = Path::new("/default");
        let mut blank = task();
        blank.repo = PathBuf::new();
        assert_eq!(repo_for(&blank, fallback), PathBuf::from("/default"));
        let mut dot = task();
        dot.repo = PathBuf::from(".");
        assert_eq!(repo_for(&dot, fallback), PathBuf::from("/default"));
        assert_eq!(
            repo_for(&task(), fallback),
            PathBuf::from("/repo"),
            "a task that names a repository keeps it"
        );
    }

    #[test]
    fn a_solo_task_runs_with_one_candidate_and_a_plain_task_keeps_the_configs() {
        // Three seats said out loud. What `solo` promises is one candidate
        // *whatever the config asks for*, so the contrast has to be a number
        // this test owns - it used to be `Config::default()`'s, which became
        // 1 when one implementation became the default and left the two
        // halves of this test asserting the same thing.
        let mut solo_cfg = Config::default();
        solo_cfg.graph.candidates = 3;
        let mut solo_task = task();
        solo_task.solo = true;
        apply_solo(&mut solo_cfg, &solo_task);
        assert_eq!(solo_cfg.graph.candidates, 1);

        let mut plain_cfg = Config::default();
        plain_cfg.graph.candidates = 3;
        let plain_task = task();
        assert!(!plain_task.solo);
        apply_solo(&mut plain_cfg, &plain_task);
        assert_eq!(
            plain_cfg.graph.candidates, 3,
            "a task that did not ask to run alone keeps the config's candidates"
        );
    }

    #[test]
    fn merge_overrides_are_parsed_or_refused() {
        assert_eq!(merge_mode("none").unwrap(), MergeMode::None);
        assert_eq!(merge_mode("local").unwrap(), MergeMode::Local);
        assert_eq!(merge_mode("pr").unwrap(), MergeMode::Pr);
        assert!(merge_mode("squash").is_err());
    }

    #[test]
    fn quota_wait_uses_a_future_reset_time_capped_and_falls_back_otherwise() {
        let now = Timestamp::now();
        let fallback = Duration::from_secs(300);
        let cap = Duration::from_secs(1800);

        // No reset hint at all: the fallback.
        assert_eq!(quota_wait(None, now, fallback, cap), fallback);

        // A reset ten minutes out, well inside the cap: waited for exactly.
        let soon = now + jiff::SignedDuration::from_secs(600);
        assert_eq!(
            quota_wait(Some(soon), now, fallback, cap),
            Duration::from_secs(600)
        );

        // A reset already in the past is not trusted: the fallback, not a
        // zero or negative wait that would spin the loop right back around.
        let past = now - jiff::SignedDuration::from_secs(60);
        assert_eq!(quota_wait(Some(past), now, fallback, cap), fallback);

        // A reset further out than the cap is trusted for direction but not
        // for magnitude: a parsing slip must not sleep the loop for a day.
        let far = now + jiff::SignedDuration::from_secs(3 * 3600);
        assert_eq!(quota_wait(Some(far), now, fallback, cap), cap);
    }

    #[test]
    fn parse_reset_hint_reads_the_claude_cli_shape_and_rolls_a_past_clock_to_tomorrow() {
        let now = "2026-09-07T02:50:00Z".parse::<Timestamp>().unwrap();

        let at = parse_reset_hint("4:50am (UTC)", now).expect("a recognised shape parses");
        assert_eq!(at.to_string(), "2026-09-07T04:50:00Z");

        // Same clock reading, but it has already gone by today: read as
        // tomorrow's, since the CLI would not still be reporting a limit past
        // its own stated reset.
        let already_past =
            parse_reset_hint("1:00am (UTC)", now).expect("a recognised shape parses");
        assert_eq!(already_past.to_string(), "2026-09-08T01:00:00Z");

        assert!(
            parse_reset_hint("session limit reached", now).is_none(),
            "free text with no recognised shape is not guessed at"
        );
        assert!(
            parse_reset_hint("4:50am (Nowhere/Fake)", now).is_none(),
            "an unresolvable zone name is not guessed at either"
        );
    }

    /// A loop whose queue lives in a temp tree and whose poll interval is far
    /// longer than the test's patience, so anything that waits out a poll
    /// instead of noticing the stop fails rather than merely being slow.
    fn idle_loop(dir: &Path) -> (Opts, Queue, PathBuf, PathBuf) {
        let opts = Opts {
            poll: Duration::from_secs(30),
            ..Opts::default()
        };
        // The status file goes in a directory that does not exist yet, so its
        // creation is itself evidence the loop published one.
        let home = dir.join("home");
        (
            opts,
            Queue::at(dir.join("queue")),
            home.join("daemon.json"),
            home,
        )
    }

    #[test]
    fn a_stop_is_idempotent_and_once_set_stays_set() {
        let stop = Stop::new();
        assert!(!stop.stopped());

        stop.stop();
        assert!(stop.stopped());
        stop.stop();
        assert!(stop.stopped(), "a second stop is not a toggle");

        let shared = stop.clone();
        assert!(
            shared.stopped(),
            "a clone is the same stop; that is how the loop and its caller share one"
        );
    }

    #[test]
    fn only_a_stop_with_a_run_in_flight_reads_as_finishing() {
        let stop = Stop::new();
        stop.enter();
        assert!(
            !stop.finishing(),
            "a busy loop nobody has asked to stop is just running"
        );

        stop.stop();
        assert!(
            stop.finishing(),
            "a stop asked for mid-run has not landed until the run is settled"
        );

        stop.exit();
        assert!(
            !stop.finishing(),
            "once the run is settled the stop has landed and there is nothing to finish"
        );
    }

    #[test]
    fn finishing_stays_true_until_the_last_of_several_runs_exits() {
        let stop = Stop::new();
        stop.enter();
        stop.enter();
        stop.stop();
        assert!(stop.finishing(), "two runs still in flight");

        stop.exit();
        assert!(
            stop.finishing(),
            "one run finished, but a sibling is still working"
        );

        stop.exit();
        assert!(
            !stop.finishing(),
            "the last run out is what actually lands the stop"
        );
    }

    #[tokio::test]
    async fn a_loop_already_asked_to_stop_returns_without_waiting_out_a_poll() {
        let dir = tempfile::tempdir().unwrap();
        let (opts, queue, status_file, home) = idle_loop(dir.path());
        let stop = Stop::new();
        stop.stop();

        let began = std::time::Instant::now();
        tokio::time::timeout(
            Duration::from_secs(2),
            drive(&opts, &queue, &status_file, &home, &stop),
        )
        .await
        .expect("a stopped loop must return, not sit out its poll interval")
        .expect("the loop's own setup and teardown must not fail");
        assert!(
            began.elapsed() < opts.poll,
            "returned only after {:?}, which is a poll interval, not a stop",
            began.elapsed()
        );
    }

    #[tokio::test]
    async fn a_stop_while_idle_wakes_the_wait_instead_of_sleeping_it_out() {
        let dir = tempfile::tempdir().unwrap();
        let (opts, queue, status_file, home) = idle_loop(dir.path());
        let stop = Stop::new();

        // Asked for after the loop is already parked on its empty queue, which
        // is the case an operator tapping stop on a phone actually hits.
        let asker = {
            let stop = stop.clone();
            tokio::spawn(async move {
                tokio::time::sleep(Duration::from_millis(20)).await;
                stop.stop();
            })
        };

        let began = std::time::Instant::now();
        tokio::time::timeout(
            Duration::from_secs(2),
            drive(&opts, &queue, &status_file, &home, &stop),
        )
        .await
        .expect("a stop asked for while idle must wake the wait")
        .expect("the loop's own setup and teardown must not fail");
        asker.await.unwrap();
        assert!(
            began.elapsed() < opts.poll,
            "returned only after {:?}, so the stop waited on the sleep",
            began.elapsed()
        );
    }

    #[tokio::test]
    async fn a_stopped_loop_leaves_no_status_file_claiming_it_is_running() {
        let dir = tempfile::tempdir().unwrap();
        let (opts, queue, status_file, home) = idle_loop(dir.path());
        let stop = Stop::new();
        stop.stop();

        tokio::time::timeout(
            Duration::from_secs(2),
            drive(&opts, &queue, &status_file, &home, &stop),
        )
        .await
        .expect("a stopped loop must return")
        .expect("the loop's own setup and teardown must not fail");

        assert!(
            home.is_dir(),
            "the loop did publish a status file, so its removal is the teardown and not an absence"
        );
        assert!(
            !status_file.exists(),
            "a stopped loop clears its status file"
        );
        assert!(
            read_status(&home).is_none(),
            "a reader must see no daemon at all, not a heartbeat that merely stopped"
        );
    }
}