magi/

config.rs

//! Run configuration: the agent roster, the shape of the graph, and the
//! blindness / verification policy.
//!
//! Layers, lowest precedence first: `<config_dir>/magi/config.toml` (machine),
//! `.magi/config.toml`, `magi.toml`. With none, built-in defaults apply, the
//! agent roster derived from the agent CLIs actually installed on this
//! machine. `--config <path>` replaces the whole stack with that one file.
//!
//! **The repository layers are read from `<remote>/<base>`, never from the
//! working tree.** A primary checkout is often stale or on a detached HEAD, so
//! a gate read from it can be older than the one the branch under review is
//! cut from (run ce6e failed on a gate step `origin/main` had already
//! dropped). `git show <sha>:magi.toml` of the remote-tracking ref's commit is
//! written to a content-addressed directory under the git common dir
//! (`<common>/magi/config/<sha>-<hash of repo>/`, temp dir when that is not
//! writable) and loaded from there.
//!
//! `remote` and `base` are themselves in the file, so they are resolved in a
//! fixed order, first hit wins:
//!
//! 1. `[merge] base` / `remote` of the machine layer, rendered as a real load
//!    would (env templates, includes);
//! 2. the same keys, read minimally (only `[merge]`, nothing deserialized into
//!    `Config`) from the checkout's `magi.toml`, then `.magi/config.toml` -
//!    only to *locate* the ref; an unreadable file is ignored;
//! 3. `remote` defaults to `origin`, `base` to what
//!    `refs/remotes/<remote>/HEAD` points at.
//!
//! [`Config::discover`] is synchronous and reads the remote-tracking ref as it
//! is (`daemon::fetch_loop` keeps it fresh); [`Config::discover_fetched`] runs
//! `git fetch` first and is what every path that starts work uses. A failed
//! fetch, a missing ref or an unresolvable base is an **error**, never a
//! silent fall back to the working tree or a local branch. Two cases are not
//! that: an explicit `--config`, and a `repo` that is not a git working tree
//! at all (no branch exists, so nothing can be stale).
//!
//! A repository layer that declares `include = [...]` gets the whole tree of
//! that commit extracted, so relative includes resolve against the same
//! commit. The directory is built beside its name and renamed in, so a
//! concurrent `discover` never reads a half-written layer.
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use anyhow::{Context as _, Result, bail};
use serde::{Deserialize, Serialize};

/// Which CLI drives an agent.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum AgentKind {
    /// Anthropic Claude Code (`claude -p`).
    Claude,
    /// opencode (`opencode run`).
    Opencode,
    /// Antigravity CLI (`agy -p`). Gemini CLI is deliberately absent: Google
    /// retired the standalone client for individual accounts in favour of this
    /// one, so an adapter for it would be dead code on a live machine.
    Antigravity,
    /// OpenAI Codex CLI (`codex exec`). The one roster member with a real
    /// read-only mode: `--sandbox read-only` is enforced by the CLI, not by
    /// the prompt.
    Codex,
    /// oh-my-pi (`omp -p --mode=json`). Another CLI with no read-only mode of
    /// its own - `--auto-approve` gates reads and writes together - so a
    /// read-only seat rests on the prompt and on the worktree discipline the
    /// other non-codex seats already rely on. It is also the roster member that
    /// reaches DeepSeek, whose models ship in `omp`'s own catalog.
    Omp,
    /// Arbitrary command. The escape hatch, and what the test suite drives.
    Command,
}

impl AgentKind {
    /// Executable that must be on `PATH` for this kind, if any.
    pub fn program(self) -> Option<&'static str> {
        match self {
            Self::Claude => Some("claude"),
            Self::Opencode => Some("opencode"),
            Self::Antigravity => Some("agy"),
            Self::Codex => Some("codex"),
            Self::Omp => Some("omp"),
            Self::Command => None,
        }
    }

    /// Lowercase name as written in the config file.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Claude => "claude",
            Self::Opencode => "opencode",
            Self::Antigravity => "antigravity",
            Self::Codex => "codex",
            Self::Omp => "omp",
            Self::Command => "command",
        }
    }

    /// Every kind the roster can name, in display order.
    ///
    /// This is what `magi doctor` lists, and it has to be one list rather than
    /// the same set typed out again wherever a kind is enumerated. The last
    /// time it was typed out twice, `omp` was added as a roster member and the
    /// doctor output went on saying the machine had four CLIs - which reads as
    /// "that agent is not installed" to the person the command exists for.
    pub const ALL: [Self; 6] = [
        Self::Claude,
        Self::Opencode,
        Self::Antigravity,
        Self::Codex,
        Self::Omp,
        Self::Command,
    ];
}

/// How the prompt reaches the agent process.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum Delivery {
    /// Piped on stdin.
    Stdin,
    /// Passed as a positional argument. Beware OS command-line limits.
    Argv,
    /// Written to a file; the agent is told to read it. No length limit.
    File,
}

/// One addressable agent in the roster.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentSpec {
    /// Stable identifier used by `[roles]` and by the stats tables.
    pub id: String,
    /// Which CLI to drive.
    pub kind: AgentKind,
    /// Model passed through to the CLI (`--model` / `-m`). CLI default if unset.
    #[serde(default)]
    pub model: Option<String>,
    /// `kind = "command"` only: argv. Supports `{prompt_file}`, `{cwd}`,
    /// `{label}`, `{session}` placeholders.
    #[serde(default)]
    pub command: Vec<String>,
    /// Extra arguments appended to the built command line.
    #[serde(default)]
    pub extra_args: Vec<String>,
    /// Extra environment variables for the child process.
    #[serde(default)]
    pub env: BTreeMap<String, String>,
    /// Override the per-kind prompt delivery default.
    #[serde(default)]
    pub prompt_delivery: Option<Delivery>,
}

impl AgentSpec {
    /// Default prompt delivery for this agent.
    ///
    /// `opencode` and `agy` take the prompt as an argument, which on Windows
    /// caps out around 32 KiB — well under a judging prompt carrying three
    /// patches — so both get a file instead.
    pub fn delivery(&self) -> Delivery {
        self.prompt_delivery.unwrap_or(match self.kind {
            AgentKind::Claude | AgentKind::Command => Delivery::Stdin,
            // `codex exec -` reads the prompt from stdin, so the whole
            // instruction arrives without an argv length limit and without a
            // tool round-trip to open a file.
            AgentKind::Codex => Delivery::Stdin,
            // `omp -p` reads the prompt from stdin too, and a judging prompt
            // carrying three patches is well past the Windows argv cap, so this
            // is the only delivery that works for every node.
            AgentKind::Omp => Delivery::Stdin,
            AgentKind::Opencode | AgentKind::Antigravity => Delivery::File,
        })
    }

    /// Human-facing label, e.g. `opus (claude:opus)`.
    pub fn display(&self) -> String {
        match &self.model {
            Some(m) => format!("{} ({}:{m})", self.id, self.kind.as_str()),
            None => format!("{} ({})", self.id, self.kind.as_str()),
        }
    }
}

/// A standalone seat's agent: one roster id, or an ordered fallback chain.
///
/// The string form is what every existing config uses and serializes back as
/// a string; the array form tries each id at most once, in order, moving on
/// when a call ends in quota or fails (see [`crate::agent::pick_chain`]).
/// An empty string or array is the same as unset.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(untagged)]
pub enum AgentChoice {
    /// One agent id.
    One(String),
    /// Ordered fallback chain of agent ids.
    Chain(Vec<String>),
}

impl AgentChoice {
    /// The ids named, in order, with blanks dropped. Empty means unset.
    pub fn ids(&self) -> Vec<&str> {
        let all: Vec<&str> = match self {
            Self::One(id) => vec![id.as_str()],
            Self::Chain(ids) => ids.iter().map(String::as_str).collect(),
        };
        all.into_iter()
            .map(str::trim)
            .filter(|id| !id.is_empty())
            .collect()
    }

    /// The first id named, if any.
    pub fn primary(&self) -> Option<&str> {
        self.ids().into_iter().next()
    }
}

impl From<&str> for AgentChoice {
    fn from(id: &str) -> Self {
        Self::One(id.to_owned())
    }
}

/// The first id of an optional choice: what a single-seat caller resolves.
pub fn primary(choice: Option<&AgentChoice>) -> Option<&str> {
    choice.and_then(AgentChoice::primary)
}

/// Explicit role assignment. Empty lists are filled in by
/// [`Config::resolve_roles`] by rotating the roster.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Roles {
    /// Agents that implement the task, one worktree each.
    pub implementers: Vec<String>,
    /// Agents that rank the candidates blind.
    pub judges: Vec<String>,
    /// Agents that review the winning patch.
    pub reviewers: Vec<String>,
    /// Agent that applies review findings. Defaults to the winner's author.
    ///
    /// Accepts one id or an ordered array of ids: a fallback chain, see
    /// [`AgentChoice`]. The review loop, the gate-fix round, `land`'s fix
    /// rounds and the rebase conflict round move to the next id when one
    /// errors, hits its quota or answers nothing usable; each id is tried at
    /// most once per call, and once a fallback answered, the rest of the run
    /// starts from it (see `crate::fixer`). Unset keeps the winner's author.
    pub fixer: Option<AgentChoice>,
    /// Agent that answers the standing chat's turns (`src/talk.rs`).
    ///
    /// Unset picks a `claude` seat, else the first runnable agent in roster
    /// order (see [`crate::agent::pick`]) - which is roster *order*, not a
    /// judgement about who converses well. Naming one here matters once an
    /// agent is also sitting as a judge: the chat is opened far more often
    /// than any single competition, and every open competes with that judge
    /// seat for the same account's concurrency. A timeout on an ordinary chat
    /// turn traced to exactly this - `opus` triple-booked as chatter and judge
    /// - is what this field exists to let an operator break apart.
    ///
    /// Accepts one id or an ordered array of ids: a fallback chain, see
    /// [`AgentChoice`].
    pub chatter: Option<AgentChoice>,
    /// Agent that arranges the queue between polls: `crate::conduct`'s single
    /// seat, called once per cycle to decide a runnable task's `blocked_by`
    /// and how a stalled or finished task recovers.
    ///
    /// The same precedent as [`Self::chatter`] for a seat that stands alone
    /// rather than rotating through the roster - resolved through
    /// [`crate::agent::pick`], so unset falls back to its own default order
    /// (a claude seat, else the first runnable agent) rather than reusing a
    /// judge or reviewer seat that the conductor's own poll-cycle cadence
    /// would otherwise compete with for the same account's concurrency.
    ///
    /// Accepts a string or a fallback chain, like [`Self::chatter`].
    pub conductor: Option<AgentChoice>,
    /// Seats for the design-deliberation stage `graph::Runner::advise` runs
    /// before `implement`: independent, read-only design proposals gathered
    /// once a run has a settled task instruction and before any implementer
    /// touches the repository.
    ///
    /// Empty falls back to `judges` rather than to the whole roster: a panel
    /// trusted to rank patches independently is exactly the panel worth
    /// asking to sketch a design independently, and an operator who has
    /// already thought about judge diversity gets advisor diversity for free
    /// instead of a fourth roster to maintain.
    pub advisors: Vec<String>,
    /// Agent that blends [`Self::advisors`]' proposals into the one design
    /// brief `graph::Runner::synthesize_brief` carries into every
    /// implementer's prompt.
    ///
    /// The same precedent as [`Self::chatter`] and [`Self::conductor`] for a
    /// seat that stands alone rather than rotating through the roster -
    /// resolved through [`crate::agent::pick`], so unset falls back to its
    /// own default order (a claude seat, else the first runnable agent in
    /// roster order) - exactly today's behavior, unchanged by leaving this
    /// field out.
    ///
    /// Accepts a string or a fallback chain, like [`Self::chatter`].
    pub synthesizer: Option<AgentChoice>,
}

/// Graph shape and limits.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Graph {
    /// Gate GitHub prose before posting. Secret redaction remains mandatory when disabled.
    pub github_text_guard: bool,
    /// Parallel implementations of the same task (the number of implementer
    /// seats; pairs with [`Roles::implementers`]). **One by default.**
    ///
    /// Formerly `candidates`, still read as a deprecated alias.
    ///
    /// Competition is the thing magi is for, and it is still here - it is just
    /// no longer what every task buys without being asked. Three days and 13
    /// runs on this repository, which is the workload these numbers are drawn
    /// from:
    ///
    /// - **0 of 13** competed runs reached a merge. Everything that landed in
    ///   that window went through `magi review` - the cheap half, no
    ///   competition - and passed on the first try.
    /// - The judges' first choices **split 73% of the time** (8 of 11
    ///   tallies). Candidates that close together make the ranking a weak
    ///   signal for what it costs to produce.
    /// - One run's own breakdown: implement 60min, judge 40min, fix 40min,
    ///   review 28min, **verify 5min** - and verify is the node that caught a
    ///   defect every reviewer had passed as clean. The cheapest step is the
    ///   one that earns its place every time.
    ///
    /// It is not worthless: `oc` won 3 of those tallies against `sonnet`, so a
    /// single-seat default would have shipped the worse implementation in
    /// roughly a quarter of them. That is exactly why this is a *default* and
    /// not a removal - `magi run --candidates N` and a per-task seat count are
    /// how a task that deserves a competition gets one.
    ///
    /// A single-candidate run needs no special case: `Runner::review`'s doc
    /// records that `execute` already degrades to implement -> review -> gate
    /// -> merge, because `judge` skips a one-candidate field, `deliberate` has
    /// no two first choices to reconcile and `vote` returns early.
    #[serde(alias = "candidates")]
    pub implementers: usize,
    /// Independent judges.
    pub judges: usize,
    /// Deliberation rounds when the judges' first choices disagree.
    pub deliberate_rounds: usize,
    /// Reviewers per review round. **Three by default** - the smallest panel
    /// a lens cycle (see [`crate::prompt::Lens`]) covers exactly once, so the
    /// default panel reads the patch for spec compliance, regressions, and
    /// simplicity without repeating an angle. Review is also the one stage
    /// [`Self::implementers`]'s doc describes as running on every task
    /// regardless of competition, which is what makes a panel worth its cost
    /// here even though `implementers` itself defaults to one.
    pub reviewers: usize,
    /// Maximum review+fix rounds before the run is declared blocked.
    pub review_rounds: usize,
    /// Fix rounds a failing `verify.gate` gets before the run is blocked. The
    /// fixer is handed the gate's own output; `0` keeps the old behaviour of
    /// blocking on the first red gate. Independent of [`Self::review_rounds`]
    /// so a run that spent its review budget can still repair a one-line gate
    /// failure.
    pub gate_fix_rounds: usize,
    /// Maximum agent processes running at once.
    pub max_parallel: usize,
    /// Language for the prose the agents write (`en` / `ja` / any language name).
    pub language: String,
    /// Keep one CLI conversation per seat, so a judge remembers its own
    /// argument across deliberation rounds and the fixer remembers its own
    /// implementation across review rounds.
    ///
    /// Sessions are scoped to a *seat*, never to an agent id: the same model
    /// sitting as implementer and as judge gets two unrelated conversations,
    /// which is what keeps blind judging blind.
    pub sessions: bool,
    /// Per-node timeouts, seconds.
    pub timeout_implement: u64,
    /// Per-node timeouts, seconds.
    pub timeout_judge: u64,
    /// Per-node timeouts, seconds.
    pub timeout_review: u64,
    /// Timeout for `verify.e2e` and `verify.gate`, seconds. Separate from
    /// [`Self::timeout_review`] so shrinking a reviewer's budget cannot
    /// silently shrink a real-machine command's budget too — the two used to
    /// share `timeout_review`, and turning a slow reviewer down cut the
    /// timeout `cargo test --all-targets` runs under along with it. When
    /// omitted, preserves legacy configurations by using
    /// [`Self::timeout_review`]. Set an explicit value to make verification
    /// independent of later review-seat budget changes.
    pub timeout_verify: Option<u64>,
    /// Per-node timeouts, seconds.
    pub timeout_fix: u64,
    /// Wall-clock limit for one turn of [`crate::talk`]'s standing
    /// conversation, seconds.
    ///
    /// An hour: the operator is not watching this turn resolve in real time,
    /// so the budget can match what the work - reading files, running
    /// commands, checking their output - actually needs rather than what a
    /// person waiting on a phone can tolerate.
    pub timeout_talk: u64,
    /// Retries for an agent invocation that fails or returns nothing usable.
    pub retries: usize,
    /// Root for candidate / judge worktrees. Defaults to `~/wt/magi`.
    pub worktree_root: Option<PathBuf>,
    /// After the pull request is open, keep going: watch its checks and
    /// reviews, run a fix round when they are unhappy, and ask to merge.
    ///
    /// On, because stopping at an open pull request left the operator doing
    /// the watching by hand - six times in the session this was built in - and
    /// that is the work the loop exists to take. It only engages for
    /// `merge = "pr"`; every other merge mode ends the run as before.
    ///
    /// Turning this on does **not** hand magi the merge button:
    /// [`Graph::land_approval`] is on too, and nothing merges without an
    /// explicit answer. Setting both to their non-defaults is the only way to
    /// get an unattended merge, and it has to be chosen twice.
    pub land: bool,
    /// Land rounds - watch, fix, push - before the run is left for a human.
    pub land_rounds: usize,
    /// Ask the owner before merging, showing what is about to land.
    ///
    /// On, and it is what makes `land` safe to have on: the question carries a
    /// rendered panel - the diffstat, the patch, the checks, the review
    /// comments that were addressed, and the subject the squash will use - so
    /// the decision is made on evidence rather than on trust, from wherever
    /// the operator happens to be.
    ///
    /// Silence is a hold. An unanswered approval never merges, and neither
    /// does any answer other than the word `merge`.
    pub land_approval: bool,
    /// Ask the owner before merging a run whose review loop handed off over a
    /// contested finding: the last round ended with a Major-or-above finding
    /// still open *and* at least one reviewer's final vote (after
    /// reconsideration) was reject. Findings raised in the last round are
    /// never fixed or re-reviewed, so this is the one case an unattended
    /// merge would land over a reviewer's explicit objection.
    ///
    /// On. Interaction with [`Self::land_approval`]: when that is on, every
    /// merge is asked about and this key changes nothing. When it is off,
    /// this key alone decides whether a contested hand-off is asked about
    /// (the question says why); every other run still merges unattended.
    /// Read at land time, so turning it off restores the unattended merge at
    /// once. The pull request is opened either way; only the merge waits.
    pub hold_contested_merge: bool,
    /// After a run's pull request merges, file the findings its last review
    /// round left open as follow-up tasks (`crate::followup`) instead of
    /// letting them vanish with the merge: every Major-or-above finding, and
    /// every finding of a seat whose final vote was reject. Other Minor/Nit
    /// findings are only listed in the pull-request comment. Does not affect
    /// whether the merge happens. On; best-effort, a failure is a run event.
    pub file_followups: bool,
    /// How long to wait for an owner to answer a question before the run is
    /// abandoned, seconds. A parked run costs nothing, so this is generous;
    /// it exists so a forgotten question cannot pin a worktree forever.
    pub answer_timeout: u64,
    /// What a round does when one or more reviewer seats never answered
    /// (timeout, crash, unparsable output).
    pub incomplete_review: IncompleteReviewPolicy,
    /// Run `verify.e2e` on every round, even one that already has blocking
    /// findings and another round left to try.
    ///
    /// Off by default: a round with a blocking finding and rounds still left
    /// is going back to the fixer regardless of what `verify.e2e` says, so
    /// running it first only spends the round's slowest step (minutes, on a
    /// Rust repo's `cargo test --all-targets`) on a head about to be
    /// rewritten anyway. `verify.e2e` still runs once a round has no
    /// blocking findings left (a round cannot go `clean` without it) and the
    /// final `verify.gate` always runs on the actual tree that would land —
    /// deferring is about *when* e2e runs mid-loop, never about skipping it.
    ///
    /// Set this to restore the old every-round diagnostic behaviour: e2e
    /// output from a round that still has blocking findings is occasionally
    /// useful on its own (a runtime failure a reviewer's panel would not
    /// have caught by reading), and this is the way back to seeing it every
    /// round instead of only once the panel has nothing left to flag.
    pub e2e_every_round: bool,
    /// Run the design-deliberation stage before `implement`: independent
    /// advisor seats each sketch a design, and (when at least one produced a
    /// usable proposal) a synthesis blends them into a brief carried in the
    /// implementer's prompt. See `graph::Runner::advise`.
    ///
    /// On by default. A design sketch is a few paragraphs an agent can write
    /// without touching the repository, where a full implementation is a
    /// tool loop that re-reads the codebase on every turn - so three
    /// sketches, gathered once before `implement` starts, cost a fraction of
    /// a fourth candidate and buy back a form of the same disagreement
    /// [`Self::implementers`]'s doc describes moving away from being the
    /// default, on every run rather than only the ones an operator remembers
    /// to ask for with `--implementers`.
    pub advise: bool,
    /// How many independent design proposals the deliberation stage gathers.
    /// **Three by default** - the same number [`Self::implementers`]'s doc
    /// names as the point where a fourth judge's first choice stopped
    /// changing the tally.
    pub advisors: usize,
}

impl Default for Graph {
    fn default() -> Self {
        Self {
            github_text_guard: true,
            implementers: 1,
            judges: 3,
            deliberate_rounds: 1,
            reviewers: 3,
            review_rounds: 6,
            gate_fix_rounds: 1,
            max_parallel: 4,
            language: "en".to_owned(),
            sessions: true,
            timeout_implement: 3600,
            timeout_judge: 1200,
            timeout_review: 1200,
            timeout_verify: None,
            timeout_fix: 1800,
            timeout_talk: 3600,
            retries: 1,
            worktree_root: None,
            land: true,
            land_rounds: 4,
            land_approval: true,
            hold_contested_merge: true,
            file_followups: true,
            answer_timeout: 86_400,
            incomplete_review: IncompleteReviewPolicy::Block,
            e2e_every_round: false,
            advise: true,
            advisors: 3,
        }
    }
}

impl Graph {
    /// Effective machine-command budget. Older configuration files had only
    /// `timeout_review`, which also governed verification, so absence is a
    /// compatibility fallback rather than a new 1200-second default.
    pub fn verify_timeout(&self) -> u64 {
        self.timeout_verify.unwrap_or(self.timeout_review)
    }
}

/// What a review round does when a reviewer seat never answered.
///
/// A round where half the panel timed out is not evidence of a clean patch —
/// it is evidence of nothing. The default refuses to call that clean; `warn`
/// exists for an operator who would rather keep a flaky seat from stalling
/// every run, and accepts that the gap is on them to read in the report.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum IncompleteReviewPolicy {
    /// A round with a missing seat is never `clean`: with nothing raised to
    /// fix, the round is re-reviewed instead of gating; with the max rounds
    /// exhausted, the run is left `Blocked` rather than declared ready.
    Block,
    /// A round with a missing seat can still gate as clean, once every seat
    /// that *did* answer raised nothing blocking and verification is green.
    /// The record keeps the gap visible (`magi show`, `magi stats`) even
    /// though the run does not wait on it.
    Warn,
}

/// What to do when vendor-identifying text is found in material shown to judges.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum LeakPolicy {
    /// Record the leak, show the patch unmodified.
    Warn,
    /// Replace the token with `[REDACTED]` in the presented patch.
    Redact,
    /// Abort the run.
    Fail,
}

/// Blindness policy.
///
/// Commit messages and candidate summaries are *always* stripped of
/// attribution trailers and redacted — that is where signatures actually
/// appear. [`Blind::on_leak`] governs the patch body only, where blanket
/// redaction would corrupt the artifact under judgement.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Blind {
    /// Install a per-worktree `commit-msg` hook that deletes attribution
    /// trailers before they can land in a candidate's history.
    pub commit_msg_hook: bool,
    /// Literal, case-insensitive substrings. A line containing any of them is
    /// dropped from commit messages and summaries; the `commit-msg` hook is
    /// generated from the same list.
    pub strip_lines: Vec<String>,
    /// Case-insensitive substrings that identify a vendor or model.
    pub vendor_tokens: Vec<String>,
    /// Policy for vendor tokens found in the patch body.
    pub on_leak: LeakPolicy,
    /// Seed for label assignment and per-judge presentation order. Derived from
    /// the run id when unset; set it to make a run reproducible.
    pub seed: Option<u64>,
}

impl Default for Blind {
    fn default() -> Self {
        Self {
            commit_msg_hook: true,
            strip_lines: [
                "Co-Authored-By:",
                "Signed-off-by:",
                "Assisted-by:",
                "Generated-by:",
                "Generated with",
                "\u{1f916}",
            ]
            .iter()
            .map(|s| (*s).to_owned())
            .collect(),
            vendor_tokens: [
                "claude",
                "anthropic",
                "codex",
                "openai",
                "chatgpt",
                "gemini",
                "grok",
                "xai",
                "copilot",
                "opencode",
                "qoder",
                "cursor",
                "\u{1f916}",
            ]
            .iter()
            .map(|s| (*s).to_owned())
            .collect(),
            on_leak: LeakPolicy::Warn,
            seed: None,
        }
    }
}

/// Shell commands that gate the winner.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Verify {
    /// Run in the winner's worktree once per review round. Its output is fed
    /// back to the fixer. This is the "real machine" leg of the review.
    pub e2e: Vec<String>,
    /// Final gate. Must all exit 0 before a merge is attempted.
    pub gate: Vec<String>,
    /// Mechanical fixers (formatters) run in the winner's worktree just before
    /// `gate`, after review is clean. Anything they change is committed as one
    /// neutral-identity commit so the gate and the PR see it. A command that
    /// fails or times out is a warning, never a failed run: the gate stays the
    /// single arbiter. Empty (the default) turns the feature off. Runs under
    /// `graph.verify_timeout()` per command, like the gate. Meant for light
    /// tools: it is not scanned for `CARGO_TARGET_DIR`, and it should be
    /// idempotent since a resumed run may repeat it.
    #[serde(default)]
    pub pre_gate: Vec<String>,
    /// Shell used to run the commands above. Defaults to `sh -c`, or
    /// `cmd /C` when `sh` is not on `PATH`.
    pub shell: Option<Vec<String>>,
}

impl Verify {
    /// The `CARGO_TARGET_DIR=` value of the first rendered command that sets
    /// one, if any. See [`crate::disk::extract_cargo_target_dir`] for the shape
    /// this reads back. One rendering is enough - they all set the same
    /// rendered `{{ vars.cache }}` path via the same shell - and the first e2e
    /// command is checked before the gate because the e2e rebuilds the crate.
    pub fn cache_dir(&self) -> Option<PathBuf> {
        self.e2e
            .iter()
            .chain(self.gate.iter())
            .find_map(|cmd| crate::disk::extract_cargo_target_dir(cmd))
    }
}

/// Disk hygiene: how hard magi is allowed to press on the machine's free space.
///
/// The numbers below come from one incident, not from theory: a machine with
/// 951.8 GB free ran a few competitions and plans and best read 6.7 GB free.
/// Three multi-gigabyte classes of junk accumulated side by side - per-run
/// worktrees that end as `Merged`/`Ready`/`Failed`, a shared build cache whose
/// each verify round and each implementation wave recompiles the derived
/// section of the project into, and the outputs of runs that were removed but
/// whose folders nobody deleted.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Disk {
    /// Free space, in bytes, below which no new run may start: the daemon and
    /// the `magi run` gate answer with "the disk is full" instead of letting
    /// the graph fill it the rest of the way. `0` turns the gate off.
    ///
    /// Default 8 GiB. The incident ran down to 6.7 GB free of 951.8 GB total
    /// before anybody noticed; 8 GiB is enough headroom for the compile a fresh
    /// competition triggers and small enough that a 1 TB disk with 100 GB free
    /// is nowhere near the threshold.
    pub min_free_bytes: u64,
    /// Fold finished runs without being asked. `Merged`, `Ready` and `Failed`
    /// runs older than [`fold_grace_secs`](Self::fold_grace_secs) have their
    /// worktrees removed. `0` turns the janitor off.
    ///
    /// Default true.
    pub auto_fold: bool,
    /// How old a finished run must be before the janitor folds it, seconds.
    ///
    /// Default 6 hours. A run that `Ready` at 8am is the operator's answer; a
    /// run that `Ready` a week ago is worktrees holding a compile each. Six
    /// hours is long enough that nobody loses an answer in the gap between
    /// reading the report and starting from it, and short enough that a backlog
    /// cannot pile up across two nights.
    pub fold_grace_secs: u64,
    /// Ceiling for the shared build cache (`CARGO_TARGET_DIR` in the rendered
    /// verify commands), in bytes. When the janitor runs and the cache is over
    /// it, files are dropped oldest-first until it is not. `0` turns pruning
    /// off - the cache then only ever grows, which is the operator's call.
    ///
    /// Default 10 GiB. This is what the incident measured: 30.61 GB sat in the
    /// shared cache on top of ~16 GB in the primary target directory and 6.7-
    /// 11.15 GB in each of four per-worktree targets. 10 GiB holds a healthy
    /// stack of prebuilt dependencies (cargo's per-file fingerprinting means
    /// pruning only costs the rebuild of the dropped files, not of the world)
    /// without letting one addled cache swallow the machine.
    pub cache_limit_bytes: u64,
}

impl Default for Disk {
    fn default() -> Self {
        Self {
            min_free_bytes: 8 * 1024 * 1024 * 1024,
            auto_fold: true,
            fold_grace_secs: 6 * 60 * 60,
            cache_limit_bytes: 10 * 1024 * 1024 * 1024,
        }
    }
}

/// What to do with the winning branch.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum MergeMode {
    /// Leave the branch alone and print the merge command matching
    /// [`Merge::style`].
    None,
    /// Merge into the base branch in the primary worktree, using
    /// [`Merge::style`].
    Local,
    /// Push the branch and open a PR with `gh pr create`. Landing this PR
    /// (`[graph] land`) always squashes — see `land`'s module doc — so
    /// [`Merge::style`] does not apply here.
    Pr,
}

/// How the winning branch is attached to the base branch: what
/// `mode = "local"` runs, and what `mode = "none"`'s printed guidance tells
/// the operator to run by hand.
///
/// Read from configuration rather than asked of the repository at run time
/// (e.g. `gh api repos/{owner}/{repo}/rulesets`) for two reasons: it keeps
/// `mode = "none"`'s guidance a pure function of `RunState`, assertable in a
/// unit test the same way `land::decide` is kept pure (see that module's
/// doc), and it works for a base branch that is not hosted on GitHub, or not
/// reachable at all, at the moment the report is rendered. An operator whose
/// base branch enforces a ruleset already knows what it allows; declaring it
/// once here is cheaper than magi re-discovering it, with a network call, on
/// every render.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum MergeStyle {
    /// `git merge --no-ff`: every candidate commit lands, plus a merge
    /// commit that records the merge as its own event in history. Rejected
    /// by a base branch whose ruleset requires linear history or forbids
    /// merge commits outright.
    #[default]
    Merge,
    /// `git merge --squash` followed by a commit under an explicit message:
    /// every candidate commit folds into one, and none of the candidate's
    /// own placeholder subjects (`magi: candidate A (uncommitted work)`)
    /// reach the base branch. No merge commit, so this satisfies a linear-
    /// history ruleset.
    Squash,
    /// A fast-forward-only merge: every candidate commit lands verbatim, in
    /// order, with no merge commit. Only succeeds because the winner was
    /// already rebased onto the tracked base tip before this runs (see
    /// `Runner::sync_to_base`) — equivalent to GitHub's "rebase and merge"
    /// once that has happened.
    Rebase,
}

/// Merge policy.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Merge {
    /// Default is [`MergeMode::None`]: magi never touches your base branch
    /// unless you ask it to.
    pub mode: MergeMode,
    /// Base branch. Defaults to the branch checked out when the run started.
    pub base: Option<String>,
    /// How the winner is attached to `base`; see [`MergeStyle`]. Ignored by
    /// `mode = "pr"`.
    pub style: MergeStyle,
    /// Remote for `mode = "pr"`.
    pub remote: String,
    /// After a `mode = "pr"` run lands, open a `chore/release-vX.Y.Z` pull
    /// request sized to the change by an agent's own judgement, so a version
    /// bump does not depend on a human remembering to cut one.
    ///
    /// Only acts on Rust repositories (a `Cargo.toml` at the root of the base
    /// branch); on any other repository it is a no-op that records one event.
    ///
    /// On by default. **Turning this off means a merge landed from the phone
    /// never becomes a release**, so `POST /api/upgrade` keeps reporting
    /// "already on the newest release" against a `main` that has moved past
    /// it - the same gap this feature exists to close. Only for a repository
    /// that wants to keep cutting releases by hand.
    pub release_bump: bool,
}

impl Default for Merge {
    fn default() -> Self {
        Self {
            mode: MergeMode::None,
            base: None,
            style: MergeStyle::default(),
            remote: "origin".to_owned(),
            release_bump: true,
        }
    }
}

/// How magi keeps itself current.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum UpdateMode {
    /// Never check.
    Off,
    /// Check in the background and print a one-line banner when a newer
    /// release exists.
    Notify,
    /// Check and install silently.
    Install,
}

/// Self-update policy.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Update {
    /// Default is [`UpdateMode::Notify`]: magi tells you, and lets you decide.
    pub mode: UpdateMode,
    /// Minimum time between checks, e.g. `24h`. kaishin's default when unset.
    pub interval: Option<String>,
}

impl Default for Update {
    fn default() -> Self {
        Self {
            mode: UpdateMode::Notify,
            interval: None,
        }
    }
}

/// Who performs the release after a `chore/release-vX.Y.Z` pull request merges.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ReleaseMode {
    /// The repository's own workflows do (`auto-tag.yml` then `release.yml`),
    /// and the release pull request merges on its checks.
    #[default]
    Actions,
    /// magi does, from this machine: no CI is awaited, the owner approves the
    /// merge, and magi then tags and runs [`Release::commands`]. See
    /// [`crate::release_local`].
    Local,
}

/// `[release]`: releasing without GitHub Actions. Opt-in per repository.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Release {
    /// [`ReleaseMode::Actions`] (default: nothing changes) or
    /// [`ReleaseMode::Local`].
    pub mode: ReleaseMode,
    /// Shell commands run in order, from a clean checkout of the merge commit,
    /// once the tag is pushed. The first failure stops the list. They see
    /// `MAGI_RELEASE_VERSION`, `MAGI_RELEASE_TAG`, `MAGI_RELEASE_COMMIT` and
    /// `MAGI_RELEASE_PR` in the environment; `{{ ... }}` cannot carry the
    /// version because teravars renders the whole file before any release
    /// exists. Only read when `mode = "local"`.
    pub commands: Vec<String>,
    /// Minutes each command may run before it is killed and counted as failed.
    pub timeout_minutes: u64,
}

impl Default for Release {
    fn default() -> Self {
        Self {
            mode: ReleaseMode::Actions,
            commands: Vec::new(),
            timeout_minutes: 30,
        }
    }
}

impl Release {
    /// Is this repository released by magi rather than by its workflows?
    pub fn is_local(&self) -> bool {
        self.mode == ReleaseMode::Local
    }
}

/// Top-level configuration.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Config {
    /// Agent roster.
    pub agents: Vec<AgentSpec>,
    /// Role assignment.
    pub roles: Roles,
    /// Graph shape.
    pub graph: Graph,
    /// Blindness policy.
    pub blind: Blind,
    /// Verification commands.
    pub verify: Verify,
    /// Disk hygiene.
    pub disk: Disk,
    /// Merge policy.
    pub merge: Merge,
    /// Self-update policy.
    pub update: Update,
    /// Project-specific text appended to the node prompts.
    pub prompts: Prompts,
    /// How the operator is told a run is waiting on them.
    pub notify: Notify,
    /// Local repositories the plan surface can start or derive a conversation
    /// against.
    pub repos: Repos,
    /// Policy for the standing conversation ([`crate::talk`]).
    pub talk: Talk,
    /// How many runs `magi serve`'s own loop drives at once.
    pub daemon: Daemon,
    /// Who tags and publishes after a release pull request merges.
    pub release: Release,
    /// Context-window sizes in tokens, keyed by model name, merged over
    /// [`BUILTIN_CONTEXT_WINDOWS`]. See [`Config::context_window`].
    pub context_windows: BTreeMap<String, u64>,
}

/// Context windows of models magi commonly drives, in tokens.
///
/// A convenience, not a source of truth: vendors resize windows and ship new
/// models faster than this table is edited, so an entry that is stale or
/// missing is fixed by `[context_windows]` in `magi.toml`, which wins. Matched
/// by [`Config::context_window`]: exact name first, then the longest key that
/// prefixes the model name (so a dated or suffixed id such as
/// `claude-sonnet-4-5-20250929` finds `claude-sonnet-4-5`). A model matching
/// nothing has no percentage - the UI shows the raw count.
const BUILTIN_CONTEXT_WINDOWS: &[(&str, u64)] = &[
    ("claude-opus-4", 200_000),
    ("claude-sonnet-4", 200_000),
    ("claude-haiku-4", 200_000),
    ("claude-3", 200_000),
    ("opus", 200_000),
    ("sonnet", 200_000),
    ("haiku", 200_000),
    ("gpt-5", 400_000),
    ("gpt-4.1", 1_000_000),
    ("gpt-4o", 128_000),
    ("o3", 200_000),
    ("o4-mini", 200_000),
    ("gemini-2.5", 1_000_000),
    ("deepseek", 128_000),
];

impl Config {
    /// Context window in tokens for `model`: `[context_windows]` first, then
    /// the built-in table; within each, an exact name beats the longest
    /// prefix. `None` for an unknown model, which is a deliberate answer -
    /// guessing a denominator would print a confident wrong percentage.
    pub fn context_window(&self, model: &str) -> Option<u64> {
        fn lookup<'a>(model: &str, entries: impl Iterator<Item = (&'a str, u64)>) -> Option<u64> {
            let mut best: Option<(usize, u64)> = None;
            for (key, window) in entries {
                if key == model {
                    return Some(window);
                }
                if model.starts_with(key) && best.is_none_or(|(len, _)| key.len() > len) {
                    best = Some((key.len(), window));
                }
            }
            best.map(|(_, w)| w)
        }
        lookup(
            model,
            self.context_windows.iter().map(|(k, w)| (k.as_str(), *w)),
        )
        .or_else(|| lookup(model, BUILTIN_CONTEXT_WINDOWS.iter().copied()))
    }
}

/// How the daemon loop itself behaves, as opposed to what one run does.
///
/// Machine-layer material in the same sense [`Repos::roots`] is: how many
/// competitions this machine's own loop is willing to babysit at once is a
/// fact about the machine running `magi serve`, not about any one
/// repository's task, so it belongs in `<config_dir>/magi/config.toml`
/// rather than a repository's own `magi.toml` - though, like `Repos::roots`,
/// nothing stops a repository from setting it too, since a scalar field
/// takes whichever layer has the highest precedence.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Daemon {
    /// How many runs `magi serve` may have actively in flight at once.
    /// **One by default** - today's behaviour, one run at a time.
    ///
    /// This is a different knob from [`Graph::max_parallel`], and the two
    /// must not be confused: `max_parallel` bounds how many agent *processes*
    /// one run starts inside itself (implementers, judges, reviewers -
    /// candidates competing on a single task); this field bounds how many
    /// *runs* - whole competitions, each with its own `max_parallel` budget -
    /// the loop drives side by side, possibly across different tasks and
    /// different repositories. Raising `max_parallel` buys a bigger panel for
    /// one task; raising this buys more tasks worked at once. A config file
    /// that meant one and wrote the other would either starve a competition
    /// of judges or leave the rest of the backlog waiting for no reason.
    ///
    /// A run parked waiting on the operator's land-merge approval - see
    /// [`crate::land`] - does not hold one of these slots while it waits: the
    /// whole point of parking there is to let the loop spend the slot on
    /// something runnable instead of sitting on a decision only a human can
    /// make. So even at the default of `1`, an approval that comes back does
    /// not queue behind whatever else the loop happens to be running.
    pub max_concurrent_runs: usize,
    /// Let a task marked [`crate::queue::Task::interrupt`] (`magi task
    /// interrupt`) cut ahead of whatever `magi serve` already has in flight,
    /// instead of waiting for it to finish.
    ///
    /// **Off by default.** When enabled, a run that is in flight and is not
    /// itself the interrupt candidate may be paused at its next safe node
    /// boundary - see [`crate::graph::Runner::park_here`] - so the marked
    /// task can run alone; the paused run resumes automatically, through the
    /// same path any other parked run does, the moment the interrupting
    /// task's own run reaches a terminal status. This is opt-in because it
    /// bends the loop's own "one run at a time" principle (see this repository's
    /// `magi serve` help) for a specific, explicit operator request, and a
    /// repository that never files an interrupt task pays nothing for having
    /// it on - but an operator who does not want any run of theirs preempted,
    /// ever, should leave this `false`.
    pub pause_for_interrupts: bool,
    /// How many deputies `magi serve` runs at once. A deputy is the short-lived
    /// seat that waits on one open conductor question (see [`crate::deputy`]);
    /// each is a live agent conversation, so this is bounded - **two by
    /// default**, because the agent CLIs' quota is the scarce resource. A
    /// question over the limit keeps its place and starts when a deputy
    /// finishes; `0` runs none.
    pub max_deputies: usize,
    /// Minutes a release-bump pull request may make no progress before
    /// `magi serve` raises a notice and asks the owner (see
    /// [`crate::release_watch`]). Progress is a change of head commit or of any
    /// check's verdict. A required check that stays red after the one rerun the
    /// watcher is allowed escalates at once, whatever this says. **Sixty by
    /// default**; `0` turns the watcher off.
    pub release_stall_minutes: u64,
}

impl Default for Daemon {
    fn default() -> Self {
        Self {
            max_concurrent_runs: 1,
            pause_for_interrupts: false,
            max_deputies: 2,
            release_stall_minutes: 60,
        }
    }
}

/// Where `magi repos` and `GET /api/repos` look for local checkouts.
///
/// `roots` is one of the array keys [`array_merge_policy`] marks as
/// append-across-layers: which checkouts exist in general is a *machine*
/// fact in the same way the agent roster is - a repository's own `magi.toml`
/// cannot state where its siblings live before magi has resolved which
/// repository to read that file from in the first place - but a repository
/// that genuinely has an extra root worth scanning is not forced to choose
/// between an error and losing the machine's roots outright. Both layers'
/// roots are scanned; see [`Config::refuse_split_arrays`] for the keys that
/// are still refused.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Repos {
    /// Roots to scan for a ghq-layout checkout: `<root>/<host>/<owner>/<repo>`
    /// with a `.git` directory. Empty by default - nothing is scanned unless
    /// asked to be.
    pub roots: Vec<PathBuf>,
    /// How long a scan is trusted before the next request re-scans it,
    /// seconds. `0` means never trust it: scan on every request. Defaults to
    /// a day, the same order of magnitude as [`Graph::answer_timeout`] for
    /// the same reason - a checkout does not usually appear or vanish inside
    /// a session, so there is little to gain from scanning more often than
    /// that, and an explicit refresh exists for the moment one does.
    pub scan_ttl: u64,
    /// How often `magi serve` runs `git fetch origin` in every checkout under
    /// `roots`, seconds, so `origin/main` stays fresh whatever state the
    /// working tree is in. Fetch only: no branch, HEAD or working tree is
    /// touched. `0` disables it.
    pub fetch_interval: u64,
}

impl Default for Repos {
    fn default() -> Self {
        Self {
            roots: Vec::new(),
            scan_ttl: 86_400,
            fetch_interval: 600,
        }
    }
}

/// Project-specific text appended to each node's prompt.
///
/// **Additive by construction.** These fields cannot replace magi's prompts,
/// only extend them, and that restriction is the whole design. The built-in
/// prompts carry the invariants the competition rests on: a judging prompt
/// names no authors, every structured answer must arrive as one fenced `json`
/// block, and a judge is told not to speculate about who wrote what. A config
/// that could overwrite them would let a typo silently un-blind the panel or
/// break the parser, and the symptom would be "the judges got worse" rather
/// than an error.
///
/// Repository-wide context belongs in `AGENTS.md`, which every agent already
/// reads from the checkout. Use these fields for the things a *magi node*
/// needs to know and a repository file cannot say - for instance that
/// reviewers here should ignore formatting because a hook owns it.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Prompts {
    /// Appended to every node's prompt.
    pub all: String,
    /// Appended for implementers.
    pub implement: String,
    /// Appended for judges, both ranking and voting.
    pub judge: String,
    /// Appended for reviewers.
    pub review: String,
    /// Appended for the fixer.
    pub fix: String,
}

impl Prompts {
    /// The overlay for one node, or `None` when nothing is configured.
    ///
    /// `node` is the graph's own node name, so a new node gets no overlay
    /// rather than the wrong one.
    pub fn overlay(&self, node: &str) -> Option<String> {
        let specific = match node {
            "implement" => &self.implement,
            "judge" | "vote" | "deliberate" => &self.judge,
            "review" => &self.review,
            "fix" => &self.fix,
            _ => "",
        };
        let mut parts: Vec<&str> = Vec::new();
        for p in [self.all.trim(), specific.trim()] {
            if !p.is_empty() {
                parts.push(p);
            }
        }
        if parts.is_empty() {
            return None;
        }
        Some(parts.join("\n\n"))
    }
}

/// How the operator is told that a run is waiting on them.
///
/// A command rather than a built-in integration: magi is one binary with no
/// network dependencies, and every operator's notification path is different -
/// ntfy, a Slack webhook, a Windows toast, an SSH to a machine that beeps.
/// Shelling out keeps all of them possible and none of them magi's problem.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Notify {
    /// Command and arguments. `{summary}`, `{run}` and `{url}` are replaced.
    /// Empty means no notification - the web UI is then the only surface.
    pub command: Vec<String>,
}

/// Policy for [`crate::talk`], the standing conversation.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct Talk {
    /// Let the conversation's agent edit files in the repository instead of
    /// filing a task for one. **Off by default** - see
    /// [`crate::talk`]'s module doc for why an edit made mid-conversation is
    /// an edit no run and no review can be attributed to, which is exactly
    /// the property a repository entered in a competition depends on. A
    /// repository that is never judged - dotfiles, a personal config
    /// checkout - has nothing to lose by turning this on in its own
    /// `magi.toml`, and a one-line fix stops costing a queued task to get.
    pub allow_write: bool,
    /// Extra chat personas, `[[talk.personas]]`. They add to the built-ins in
    /// [`crate::persona`]; an entry with a built-in's id replaces it. Like every
    /// array outside [`array_merge_policy`]'s append list, declaring it in two
    /// layers is refused.
    pub personas: Vec<PersonaSpec>,
}

/// One `[[talk.personas]]` entry: a tone for the standing chat, nothing more.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PersonaSpec {
    /// Stable id the conversation stores. Not `default`.
    pub id: String,
    /// What the selector shows.
    pub name: String,
    /// The voice instruction appended to the chat's system prompt.
    pub prompt: String,
}

/// Roles resolved to concrete agent specs for one run.
#[derive(Debug, Clone)]
pub struct ResolvedRoles {
    /// One per candidate.
    pub implementers: Vec<AgentSpec>,
    /// One per judge.
    pub judges: Vec<AgentSpec>,
    /// One per reviewer slot.
    pub reviewers: Vec<AgentSpec>,
    /// The configured fixer chain in order, if `[roles] fixer` is set
    /// (resolved like [`crate::agent::pick_chain`]: unknown or uninstalled ids
    /// skipped, duplicates keep their first place). `None` means the winner's
    /// own author.
    pub fixer: Option<Vec<AgentSpec>>,
    /// Queue conductor, explicitly selected or resolved by the standalone-seat fallback.
    pub conductor: AgentSpec,
    /// The full ordered implementer roster, in [`Roles::implementers`]'s own
    /// order — or `[[agents]]` in file order, when that list is empty. Unlike
    /// [`Self::implementers`], never truncated to `graph.implementers` and
    /// never `rotate`d/wrapped: a solo run (`implementers = 1`) resolves
    /// `implementers` down to a single slot, but `graph::Runner`'s per-seat
    /// quota fallback needs the *whole* list to walk forward through when
    /// that one slot's agent runs out of quota mid-run.
    pub implementer_roster: Vec<AgentSpec>,
    /// [`Self::implementer_roster`]'s counterpart for judge seats: the whole
    /// `[roles] judges` list (or every agent), untruncated and unrotated, for
    /// the per-seat handover when a judge's agent fails.
    pub judge_roster: Vec<AgentSpec>,
    /// Likewise for reviewer seats.
    pub reviewer_roster: Vec<AgentSpec>,
}

/// Every array-valued key in a config table, as a dotted path.
///
/// Dotted so the error names `roles.implementers` rather than `implementers`:
/// an operator with three config files needs to know which key, not just that
/// there was one. `vars` is skipped because it is teravars' own input, merged
/// on purpose and never deserialised into `Config`.
fn array_keys(table: &toml::value::Table, prefix: &str) -> Vec<String> {
    let mut out = Vec::new();
    for (k, v) in table {
        if prefix.is_empty() && k == "vars" {
            continue;
        }
        let path = if prefix.is_empty() {
            k.clone()
        } else {
            format!("{prefix}.{k}")
        };
        match v {
            toml::Value::Array(_) => out.push(path),
            toml::Value::Table(t) => out.extend(array_keys(t, &path)),
            _ => {}
        }
    }
    out
}

/// How an array key behaves when two config layers both declare it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ArrayMerge {
    /// Two layers may both declare it; the composed value is the
    /// low-to-high-priority concatenation teravars already produces (see
    /// [`Config::load_layers`]'s doc for why that order and no dedup).
    Append,
    /// Two layers declaring it is refused; see
    /// [`Config::refuse_split_arrays`].
    Replace,
}

/// The single place that decides, for a dotted array key (as returned by
/// [`array_keys`]), whether declaring it in two config layers is a
/// concatenation the operator asked for or a silent accident.
///
/// Kept as one match so the whole policy is visible in one place - the same
/// reason `claude_quota` and `dropped_stream` close their own classification
/// in one spot elsewhere in this codebase. Anything not listed defaults to
/// [`ArrayMerge::Replace`]: refusing is the safe default for a key nobody has
/// reasoned about yet, and a new array key added later has to be added here
/// deliberately to become appendable.
///
/// - `verify.e2e` / `verify.gate` — a "run all of these, all must exit 0"
///   gate. Concatenating two of them is exactly the checks both layers
///   wanted, which is what lets a common gate (e.g. `editorconfig-checker`)
///   live in a shared layer while a repository's own layer adds its own
///   command, instead of every repository copying the shared command into
///   its own file.
/// - `repos.roots` — a set of directories to scan for checkouts. A
///   repository adding its own root on top of the machine's is additive by
///   nature, not a replacement of where the machine looks; see
///   [`Repos::roots`].
///
/// Left on the refuse side, and why:
/// - `roles.implementers` / `roles.judges` / `roles.reviewers` — an ordered
///   list of *seats*, not a set. A machine's two implementers plus a
///   repository's one is three seats nobody asked for and nobody is paying
///   for on purpose.
/// - `notify.command` — an argv. Concatenating two argvs does not produce a
///   program that runs; it produces `["ntfy", "publish", "curl", "-X"]`.
/// - `blind.strip_lines` — technically safe to concatenate (each entry is
///   matched as an independent substring, so a longer list only strips
///   *more*), but left on the refuse side anyway: the same list also drives
///   `commit_msg_hook`'s generated `sed` addresses, where position matters,
///   and a silent three-layer merge is exactly the kind of surprise
///   `refuse_split_arrays` exists to catch rather than to reason about
///   case-by-case. A repository that wants one more stripped phrase restates
///   the whole list; that restatement is visible in review, an accidental
///   concatenation would not be.
fn array_merge_policy(key: &str) -> ArrayMerge {
    match key {
        "verify.e2e" | "verify.gate" | "verify.pre_gate" | "repos.roots" => ArrayMerge::Append,
        _ => ArrayMerge::Replace,
    }
}

impl Config {
    /// Load one file through teravars: Tera rendering, `[vars]` resolution,
    /// and the `include = [...]` directive.
    pub fn load(path: &Path) -> Result<Self> {
        Self::load_layers(&[path.to_path_buf()])
    }

    /// The Tera render context shared by every layer: `system.*` (from
    /// teravars), `env` (magi's own addition - a config that names a shared
    /// build-cache directory or a machine-specific path needs
    /// `{{ env.NAME | default(value='...') }}`), and `repo` / `repo_name`
    /// derived from the last (highest-priority) path's parent directory.
    ///
    /// Factored out so [`Config::array_provenance`] can re-render a single
    /// layer under the exact same context [`Config::load_layers`] uses for
    /// the joint render, rather than drifting from it by accident.
    fn render_ctx(paths: &[PathBuf]) -> teravars::Context {
        let mut ctx = teravars::system_context();
        let env: std::collections::BTreeMap<String, String> = std::env::vars().collect();
        ctx.insert("env", &env);
        if let Some(last) = paths.last()
            && let Some(dir) = last.parent()
        {
            // A layer extracted from `<remote>/<base>` records the checkout it
            // stands for beside itself; its own directory is a cache path.
            let dir = std::fs::read_to_string(dir.join(REPO_MARKER))
                .map(|s| PathBuf::from(s.trim()))
                .unwrap_or_else(|_| dir.to_path_buf());
            ctx.insert("repo", &dir.to_string_lossy());
            ctx.insert(
                "repo_name",
                &dir.file_name().unwrap_or_default().to_string_lossy(),
            );
        }
        ctx
    }

    /// Load and deep-merge a stack of config files, later files winning.
    ///
    /// This is why the config is TOML-through-teravars rather than plain serde:
    /// the roster is a *machine* fact (which CLIs and plans you pay for) while
    /// the gate is a *repository* fact (`cargo make check` here, `pnpm test`
    /// there). Picking one file and ignoring the other would force every repo
    /// to restate the roster.
    pub fn load_layers(paths: &[PathBuf]) -> Result<Self> {
        let mut engine = teravars::Engine::default();
        let ctx = Self::render_ctx(paths);
        if paths.len() > 1 {
            Self::refuse_split_arrays(paths, &mut engine, &ctx)?;
        }
        let merged = teravars::load_merged(paths, &mut engine, &ctx).with_context(|| {
            format!(
                "rendering config via teravars: {}",
                paths
                    .iter()
                    .map(|p| p.display().to_string())
                    .collect::<Vec<_>>()
                    .join(", ")
            )
        })?;
        let mut table = merged.config;
        Self::normalize_renamed_keys(paths, &mut engine, &ctx, &mut table)?;
        // `[vars]` is teravars' own input, already resolved into the render
        // context; `deny_unknown_fields` must not trip over it.
        table.remove("vars");
        // No layer says anything about `agents`: the roster is whatever is on
        // `PATH` now, exactly as when no layer exists at all. An explicit
        // `agents = []` is a statement and is kept.
        let detect_agents = !table.contains_key("agents");
        let mut cfg: Self = toml::Value::Table(table)
            .try_into()
            .context("deserializing magi config")?;
        crate::persona::validate(&cfg.talk.personas)?;
        if detect_agents {
            cfg.agents = Self::autodetected().agents;
        }
        Ok(cfg)
    }

    /// `graph.candidates` was renamed `graph.implementers`. Both spellings are
    /// read, but the layers are merged into one table before serde sees it, so
    /// an old name in a lower layer and the new name in a higher one would
    /// arrive together and fail as a duplicate field instead of letting the
    /// higher layer win. Resolve it here: a single layer that writes both is
    /// refused (naming both keys and the file); otherwise the value from the
    /// last layer that wrote either key becomes `implementers`.
    fn normalize_renamed_keys(
        paths: &[PathBuf],
        engine: &mut teravars::Engine,
        ctx: &teravars::Context,
        table: &mut toml::map::Map<String, toml::Value>,
    ) -> Result<()> {
        let both = matches!(
            table.get("graph"),
            Some(toml::Value::Table(g)) if g.contains_key("candidates") && g.contains_key("implementers")
        );
        if !both {
            return Ok(());
        }
        let mut winner: Option<toml::Value> = None;
        for path in paths {
            let one = teravars::load_merged([path], engine, ctx)
                .with_context(|| format!("rendering {}", path.display()))?;
            let Some(toml::Value::Table(g)) = one.config.get("graph") else {
                continue;
            };
            if g.contains_key("candidates") && g.contains_key("implementers") {
                bail!(
                    "`[graph]` sets both `implementers` and its deprecated alias \n                     `candidates` in {}; keep only `implementers`.",
                    path.display()
                );
            }
            if let Some(v) = g.get("implementers").or_else(|| g.get("candidates")) {
                winner = Some(v.clone());
            }
        }
        if let Some(toml::Value::Table(g)) = table.get_mut("graph") {
            g.remove("candidates");
            if let Some(v) = winner {
                g.insert("implementers".to_owned(), v);
            }
        }
        Ok(())
    }

    /// Refuse an array that two layers both declare, unless
    /// [`array_merge_policy`] says that key is meant to accumulate.
    ///
    /// teravars **appends** arrays when it merges layers, and that is wrong for
    /// most arrays magi has: `implementers` is an ordered list of seats,
    /// `notify.command` is an argv. Concatenating two of them yields something
    /// nobody wrote - three implementers out of a machine's two and a
    /// repository's one, or an argv of `["ntfy", "publish", "curl", "-X"]`.
    ///
    /// Replacing instead would be the right merge rule for those keys, but the
    /// rule lives in teravars, which several other projects depend on;
    /// changing it there is a decision for that crate, not something to fake
    /// here by re-reading the files with different semantics and hoping the
    /// two paths agree.
    ///
    /// So magi refuses the ambiguity rather than resolving it silently, for
    /// every array key except the short, deliberate list
    /// [`array_merge_policy`] marks [`ArrayMerge::Append`] - for those, the
    /// concatenation teravars already produces *is* what both files say, so
    /// there is nothing to refuse. The cost of guessing wrong on the refused
    /// keys is a roster the operator did not ask for and is paying for by the
    /// token; the append keys carry no such risk because every element runs
    /// (or every directory is scanned) regardless of order.
    fn refuse_split_arrays(
        paths: &[PathBuf],
        engine: &mut teravars::Engine,
        ctx: &teravars::Context,
    ) -> Result<()> {
        let mut seen: std::collections::BTreeMap<String, PathBuf> = Default::default();
        for path in paths {
            let one = teravars::load_merged([path], engine, ctx)
                .with_context(|| format!("rendering {}", path.display()))?;
            for key in array_keys(&one.config, "") {
                if array_merge_policy(&key) == ArrayMerge::Append {
                    continue;
                }
                if let Some(first) = seen.get(&key) {
                    bail!(
                        "`{key}` is an array declared in two config layers:\n  \
                         {}\n  {}\nteravars appends arrays when it merges, so \
                         magi would run the concatenation of both - which is \
                         not what either file says. Declare `{key}` in exactly \
                         one of them.",
                        first.display(),
                        path.display()
                    );
                }
                seen.insert(key, path.clone());
            }
        }
        Ok(())
    }

    /// Which layers contributed to a composed, appendable array key (e.g.
    /// `"verify.gate"`), in the same low-to-high-priority order
    /// [`Config::load_layers`] concatenates them in. Layers that do not
    /// declare `key` at all are omitted.
    ///
    /// This is a **display aid for `magi doctor` only.** The command list
    /// that actually runs always comes from the one joint
    /// [`teravars::load_merged`] call in `load_layers`, never from this
    /// function - the exact hazard [`Config::refuse_split_arrays`] warns
    /// about is two merge paths that might disagree, so this function must
    /// never become a second source of the *composed* value, only of which
    /// file wrote which line in it.
    ///
    /// Re-rendering each layer alone can, in principle, resolve a
    /// `{{ vars.x }}` differently than the joint render would, if `x` is
    /// defined in one layer and referenced in another - the same caveat
    /// `refuse_split_arrays`'s structural, key-only check already lives with.
    /// None of magi's own gate commands cross that line, and a doctor listing
    /// is read by a human who can compare it against the joint one printed
    /// alongside it, so this is judged worth the simplicity of not
    /// threading provenance through the real load path.
    pub fn array_provenance(paths: &[PathBuf], key: &str) -> Vec<(PathBuf, Vec<String>)> {
        let mut engine = teravars::Engine::default();
        let ctx = Self::render_ctx(paths);
        let mut out = Vec::new();
        for path in paths {
            let Ok(one) = teravars::load_merged([path], &mut engine, &ctx) else {
                continue;
            };
            let mut cur = &one.config;
            let mut found = None;
            let parts: Vec<&str> = key.split('.').collect();
            for (i, part) in parts.iter().enumerate() {
                match cur.get(*part) {
                    Some(toml::Value::Array(a)) if i == parts.len() - 1 => {
                        found = Some(a);
                        break;
                    }
                    Some(toml::Value::Table(t)) => cur = t,
                    _ => break,
                }
            }
            let Some(values) = found else { continue };
            let strings: Vec<String> = values
                .iter()
                .filter_map(|v| v.as_str().map(str::to_owned))
                .collect();
            if !strings.is_empty() {
                out.push((path.clone(), strings));
            }
        }
        out
    }

    /// Each layer rendered on its own, with the outcome per file: the
    /// settings screen's way of saying which layer a value came from and which
    /// layer is the one that does not parse. A **display aid only**, for the
    /// same reason as [`Config::array_provenance`]: the effective config
    /// always comes from the one joint [`Config::load_layers`].
    pub(crate) fn layer_tables(paths: &[PathBuf]) -> Vec<(PathBuf, Result<toml::Table>)> {
        let mut engine = teravars::Engine::default();
        let ctx = Self::render_ctx(paths);
        paths
            .iter()
            .map(|path| {
                let one = teravars::load_merged([path], &mut engine, &ctx)
                    .map(|m| m.config)
                    .with_context(|| format!("rendering {}", path.display()));
                (path.clone(), one)
            })
            .collect()
    }

    /// Render a composed command list for `magi doctor`: the joined command
    /// line the run actually uses, plus - only when more than one layer
    /// contributed - which layer wrote which line.
    ///
    /// A single contributing layer (the common case today) stays the plain
    /// one-line summary magi has always printed, `empty` included: that
    /// honest "(none — ...)" is what caught a real gate-composition gap
    /// before this array could compose at all, and composition should not
    /// make the common case noisier.
    pub fn describe_composed(
        paths: &[PathBuf],
        commands: &[String],
        key: &str,
        empty: &str,
    ) -> String {
        if commands.is_empty() {
            return empty.to_owned();
        }
        let joined = commands.join(" && ");
        let provenance = Self::array_provenance(paths, key);
        if provenance.len() <= 1 {
            return joined;
        }
        let mut out = joined;
        for (path, cmds) in &provenance {
            out.push_str(&format!("\n    [{}] {}", path.display(), cmds.join(" && ")));
        }
        out
    }

    /// Resolve the config for `repo`, honouring an explicit `--config` path.
    ///
    /// Returns the config and the layers it came from, empty for built-in
    /// defaults. The repository layers come from the remote-tracking ref as it
    /// stands (see the module doc); use [`Config::discover_fetched`] where a
    /// stale ref would matter.
    pub fn discover(repo: &Path, explicit: Option<&Path>) -> Result<(Self, Vec<PathBuf>)> {
        if let Some(p) = explicit {
            let paths = vec![p.to_path_buf()];
            return Ok((Self::load_layers(&paths)?, paths));
        }
        let paths = Self::layers_checked(repo)?;
        if paths.is_empty() {
            return Ok((Self::autodetected(), paths));
        }
        Ok((Self::load_layers(&paths)?, paths))
    }

    /// [`Config::discover`] after `git fetch <remote> <base>`: for every path
    /// that is about to start work. A failed fetch is an error.
    pub async fn discover_fetched(
        repo: &Path,
        explicit: Option<&Path>,
    ) -> Result<(Self, Vec<PathBuf>)> {
        if explicit.is_none() && is_git_worktree(repo) {
            // A checkout that was never cloned from the remote has no
            // `<remote>/HEAD`; learn it here (refs/remotes only) so an
            // ordinary start recovers instead of failing in `discover`.
            let (remote, cfg_base) = probe_remote_base(repo);
            let base = crate::git::merge_base_branch(repo, &remote, cfg_base.as_deref()).await?;
            let out = crate::git::fetch(repo, &remote, &base)
                .await
                .with_context(|| format!("fetching {remote}/{base} to read magi.toml"))?;
            if !out.ok() {
                bail!(
                    "cannot read magi.toml: `git fetch {remote} {base}` failed ({});                      refusing to use the local checkout's copy, which may be stale",
                    out.stderr.lines().next().unwrap_or("").trim()
                );
            }
            if cfg_base.is_none() {
                crate::git::ensure_remote_head(repo, &remote, &base).await;
            }
        }
        Self::discover(repo, explicit)
    }

    /// [`Config::layers`], but an unreadable remote ref is an error.
    fn layers_checked(repo: &Path) -> Result<Vec<PathBuf>> {
        if !is_git_worktree(repo) {
            return Ok(Self::layers(repo));
        }
        let mut paths: Vec<PathBuf> = Self::machine_layer()
            .into_iter()
            .filter(|p| p.is_file())
            .collect();
        paths.extend(Self::repo_layers(repo)?);
        Ok(paths)
    }

    /// Only the repository layers (lowest first), from `<remote>/<base>` in a
    /// git working tree and from disk elsewhere.
    pub(crate) fn repo_layers(repo: &Path) -> Result<Vec<PathBuf>> {
        if !is_git_worktree(repo) {
            return Ok([
                repo.join(".magi").join("config.toml"),
                repo.join("magi.toml"),
            ]
            .into_iter()
            .filter(|p| p.is_file())
            .collect());
        }
        remote_layers(repo)
    }

    /// Environment variable that relocates the machine-wide config layer.
    ///
    /// Set it to a directory and magi reads `<dir>/magi/config.toml` instead
    /// of the one under [`dirs::config_dir`]; set it to the empty string and
    /// magi reads no machine layer at all.
    ///
    /// This exists because the machine layer is otherwise unavoidable, and a
    /// test that builds a config fixture is not asking for the operator's
    /// preferences to be merged into it. Adding `[repos] roots` to the real
    /// machine config on a development box turned two passing tests red -
    /// `repos_list_returns_name_and_path_for_every_configured_root` and
    /// `repos_list_only_rescans_within_the_ttl_when_asked_to`, whose fixtures
    /// declare `[repos] roots` of their own, which [`Config::layers`] then
    /// found in two layers and [`Config::refuse_split_arrays`] correctly
    /// refused. CI never saw it: a runner has no machine config, so the suite
    /// was green there and red only where somebody actually uses magi.
    ///
    /// An operator gets the same escape hatch for free: a second machine
    /// config, or none, without moving files about.
    pub const CONFIG_DIR_ENV: &str = "MAGI_CONFIG_DIR";

    /// Every config layer that applies to `repo`, in increasing precedence.
    ///
    /// The machine layer is whatever [`Config::machine_layer`] resolves to,
    /// which is nothing at all in a test build.
    pub fn layers(repo: &Path) -> Vec<PathBuf> {
        let mut paths = Vec::new();
        paths.extend(Self::machine_layer());
        paths.push(repo.join(".magi").join("config.toml"));
        paths.push(repo.join("magi.toml"));
        paths.retain(|p| p.is_file());
        paths
    }

    /// The machine-wide layer's path, when there is one.
    ///
    /// **A test build has none unless it names one.** A fixture is a complete
    /// statement of the config under test, and the operator's own preferences
    /// have no business being merged into it - least of all silently, on one
    /// machine, in a suite that is green everywhere else.
    #[cfg(test)]
    pub(crate) fn machine_layer() -> Option<PathBuf> {
        std::env::var(Self::CONFIG_DIR_ENV)
            .ok()
            .filter(|dir| !dir.trim().is_empty())
            .map(|dir| PathBuf::from(dir).join("magi").join("config.toml"))
    }

    /// The machine-wide layer's path, when there is one.
    #[cfg(not(test))]
    pub(crate) fn machine_layer() -> Option<PathBuf> {
        match std::env::var(Self::CONFIG_DIR_ENV) {
            // Named, and empty on purpose: no machine layer.
            Ok(dir) if dir.trim().is_empty() => None,
            Ok(dir) => Some(PathBuf::from(dir).join("magi").join("config.toml")),
            Err(_) => dirs::config_dir().map(|dir| dir.join("magi").join("config.toml")),
        }
    }

    /// Built-in config whose roster is the agent CLIs found on `PATH`.
    pub fn autodetected() -> Self {
        let mut cfg = Self::default();
        for (kind, id, model) in [
            (AgentKind::Claude, "opus", Some("opus")),
            (AgentKind::Claude, "sonnet", Some("sonnet")),
            (AgentKind::Antigravity, "antigravity", None),
            (AgentKind::Opencode, "opencode", None),
            (AgentKind::Codex, "codex", None),
            (AgentKind::Omp, "omp", None),
        ] {
            if kind.program().is_some_and(which) && !cfg.agents.iter().any(|a| a.id == id) {
                cfg.agents.push(AgentSpec {
                    id: id.to_owned(),
                    kind,
                    model: model.map(str::to_owned),
                    command: Vec::new(),
                    extra_args: Vec::new(),
                    env: BTreeMap::new(),
                    prompt_delivery: None,
                });
            }
        }
        cfg
    }

    /// The shared build cache the verify commands and the agents both build
    /// into, when the config declares one. See [`Verify::cache_dir`].
    pub fn cache_dir(&self) -> Option<PathBuf> {
        self.verify.cache_dir()
    }

    /// Look an agent up by id.
    pub fn agent(&self, id: &str) -> Result<&AgentSpec> {
        self.agents
            .iter()
            .find(|a| a.id == id)
            .with_context(|| format!("no agent with id `{id}` in the roster"))
    }

    /// Rotate `count` seats out of `ids`, or out of the whole roster at
    /// `offset` when `ids` is empty.
    ///
    /// The one rotation rule - explicit ids cycle, an empty list rotates the
    /// roster - shared by every seat count [`Config::resolve_roles`] fills in,
    /// rather than each seat reimplementing it and drifting apart.
    fn rotate(&self, ids: &[String], count: usize, offset: usize) -> Result<Vec<AgentSpec>> {
        let mut out = Vec::with_capacity(count);
        for i in 0..count {
            let spec = if ids.is_empty() {
                self.agents[(i + offset) % self.agents.len()].clone()
            } else {
                self.agent(&ids[i % ids.len()])?.clone()
            };
            out.push(spec);
        }
        Ok(out)
    }

    /// `ids`, resolved to specs in the order named, or the whole `[[agents]]`
    /// roster in file order when `ids` is empty — the same "explicit ids
    /// stand alone, an empty list means the whole roster" rule [`Self::rotate`]
    /// applies, but with no `count` to truncate to and no `offset` to wrap by.
    /// See [`ResolvedRoles::implementer_roster`] for why a truncated, rotated
    /// list cannot answer the question this exists for.
    fn full_roster(&self, ids: &[String]) -> Result<Vec<AgentSpec>> {
        if ids.is_empty() {
            Ok(self.agents.clone())
        } else {
            ids.iter().map(|id| self.agent(id).cloned()).collect()
        }
    }

    /// Fill the roles out to the configured widths.
    ///
    /// An empty role list rotates through the whole roster, so a three-agent
    /// roster with `implementers = 3` gives one implementation per agent, and
    /// `judges = 3` rotates the judge seats by one so that judge *i* is not the
    /// author of candidate *i* whenever the roster has more than one agent.
    pub fn resolve_roles(&self) -> Result<ResolvedRoles> {
        if self.agents.is_empty() {
            bail!(
                "agent roster is empty: no agent CLI found on PATH and no \
                 [[agents]] in the config. Run `magi init` to write a starter \
                 magi.toml."
            );
        }
        Ok(ResolvedRoles {
            implementers: self.rotate(&self.roles.implementers, self.graph.implementers, 0)?,
            judges: self.rotate(&self.roles.judges, self.graph.judges, 1)?,
            reviewers: self.rotate(&self.roles.reviewers, self.graph.reviewers, 0)?,
            fixer: match self.roles.fixer.as_ref() {
                // Ids are validated against the roster here; whether the CLI
                // is installed is left to invocation, like every other seat.
                Some(choice) => Some(crate::agent::pick_chain(
                    &self.agents,
                    Some(choice),
                    &|_| true,
                    "fixer",
                )?),
                None => None,
            },
            // Role resolution validates roster shape, but deliberately does
            // not preflight a CLI. The other graph seats have always deferred
            // that failure to invocation; doing it only for the conductor
            // made otherwise usable graph commands and `doctor` fail as one.
            conductor: match self.roles.conductor.as_ref().map(AgentChoice::ids) {
                Some(ids) if ids.len() == 1 => self.agent(ids[0])?.clone(),
                // A fallback chain: the first id the roster knows. The rest
                // are `agent::pick_chain`'s business at invocation.
                Some(ids) if !ids.is_empty() => ids
                    .iter()
                    .find_map(|id| self.agent(id).ok())
                    .cloned()
                    .with_context(|| {
                        format!("[roles] conductor names no agent in the roster: {ids:?}")
                    })?,
                // Keep the normal standalone-seat preference when something
                // is installed, but retain a roster fallback when it is not.
                // Invocation then reports the unavailable CLI in the same
                // place it does for every other graph role.
                _ => crate::agent::pick(&self.agents, None, &crate::agent::installed)
                    .unwrap_or_else(|_| self.agents[0].clone()),
            },
            implementer_roster: self.full_roster(&self.roles.implementers)?,
            judge_roster: self.full_roster(&self.roles.judges)?,
            reviewer_roster: self.full_roster(&self.roles.reviewers)?,
        })
    }

    /// Advisor seats for the design-deliberation stage (see
    /// `graph::Runner::advise`): `[roles] advisors` when set, otherwise the
    /// judge roster - see [`Roles::advisors`] for why that fallback and not
    /// the whole roster.
    ///
    /// The fallback rotates with `offset = 1`, matching the judges line in
    /// [`Config::resolve_roles`] exactly, `ids` and offset both - not just
    /// `roles.judges`, which is empty whenever judges themselves are
    /// unconfigured and rotating the whole roster. Falling back with
    /// `offset = 0` there would silently hand the advisors a *different*
    /// agent set than the judges an unconfigured run would actually get,
    /// which is the one thing [`Roles::advisors`]'s doc promises will not
    /// happen.
    ///
    /// Called lazily from the graph node itself rather than folded into
    /// [`Config::resolve_roles`]: unlike the other roles, a failure here must
    /// not stop a run from starting at all - the deliberation stage is an
    /// enrichment `[graph] advise` can turn off, not a seat later nodes
    /// cannot proceed without - and at the point `resolve_roles` runs (before
    /// [`crate::run::RunState`] exists, on `Runner::start`) there would be no
    /// run yet for a resolution failure to be reported against.
    pub fn advisors(&self) -> Result<Vec<AgentSpec>> {
        if self.agents.is_empty() {
            bail!(
                "agent roster is empty: no agent CLI found on PATH and no \
                 [[agents]] in the config. Run `magi init` to write a starter \
                 magi.toml."
            );
        }
        if !self.roles.advisors.is_empty() {
            return self.rotate(&self.roles.advisors, self.graph.advisors, 0);
        }
        self.rotate(&self.roles.judges, self.graph.advisors, 1)
    }

    /// The untruncated roster advisor seats hand over along: `[roles]
    /// advisors` when set, otherwise the judges' roster, exactly as
    /// [`Self::advisors`] chooses its own list.
    pub fn advisor_roster(&self) -> Result<Vec<AgentSpec>> {
        if self.roles.advisors.is_empty() {
            self.full_roster(&self.roles.judges)
        } else {
            self.full_roster(&self.roles.advisors)
        }
    }

    /// Shell prefix for [`Verify`] commands.
    pub fn shell(&self) -> Vec<String> {
        if let Some(s) = &self.verify.shell {
            return s.clone();
        }
        if which("sh") {
            vec!["sh".to_owned(), "-c".to_owned()]
        } else {
            vec!["cmd".to_owned(), "/C".to_owned()]
        }
    }

    /// Starter config, as written by `magi init`.
    pub fn starter_toml() -> String {
        let detected = Self::autodetected();
        let mut s = String::from(
            "# magi — blind multi-agent implementation competition.\n\
             # `magi run \"<task>\"` walks: implement (N parallel worktrees)\n\
             #   -> blind judging -> deliberation -> private final vote\n\
             #   -> fold losers -> review + E2E loop -> gate -> merge.\n\
             #\n\
             # Rendered by teravars: a `[vars]` table, env\n\
             # and system lookups, and `include = [...]` all work. Tera\n\
             # braces are live everywhere in this file, but comments are\n\
             # stripped before rendering (teravars >= 0.2.2), so a comment\n\
             # may quote `{{ ... }}` freely.\n\
             #\n\
             # Layers deep-merge in increasing\n\
             # precedence, so the roster can live once per machine in\n\
             # <config_dir>/magi/config.toml and each repo only states its own\n\
             # gate:\n\
             #   <config_dir>/magi/config.toml  <  .magi/config.toml  <  magi.toml\n\n\
             [vars]\n\
             # Reference it as vars.cache inside Tera braces, anywhere below.\n\
             # Single quotes inside the braces: teravars renders the raw file\n\
             # text, so TOML's own \\\" escaping never reaches Tera.\n\
             cache = \"{{ env.MAGI_CACHE | default(value='/tmp') }}\"\n\n",
        );
        if detected.agents.is_empty() {
            s.push_str(
                "# No agent CLI was found on PATH. Fill this in by hand.\n\
                 # kind = claude | opencode | antigravity | codex | command\n\
                 [[agents]]\nid = \"opus\"\nkind = \"claude\"\nmodel = \"opus\"\n\n",
            );
        } else {
            for a in &detected.agents {
                s.push_str("[[agents]]\n");
                s.push_str(&format!("id = {:?}\n", a.id));
                s.push_str(&format!("kind = {:?}\n", a.kind.as_str()));
                if let Some(m) = &a.model {
                    s.push_str(&format!("model = {m:?}\n"));
                }
                s.push('\n');
            }
        }
        s.push_str(
            "# Leave a role list empty to rotate through the roster.\n\
             # A non-empty list is also an ordered backup list: seats take entries from the\n\
             # front (see [graph] counts) and a failed or out-of-quota seat moves on to the\n\
             # next agent to its right, each tried once. Same for judges and reviewers.\n\
             # implementers = [\"opus\", \"codex\", \"sonnet\"]  # with implementers = 1 below: opus sits, codex then sonnet are spares\n\
             [roles]\n\
             implementers = []\n\
             judges = []\n\
             reviewers = []\n\
             # conductor = \"opus\"  # arranges the queue; unset picks a seat like chatter does\n\
             # synthesizer = \"opus\"  # blends the advisors into one brief; unset picks a seat like chatter does\n\
             # synthesizer = [\"opus\", \"codex\"]  # array form: fallback chain, each tried once on quota or failure\n\
             # fixer = \"opus\"  # applies review findings; unset keeps the winner's own author\n\
             # fixer = [\"opus\", \"codex\"]  # array form: fallback chain, each tried once on quota or failure\n\n\
             [graph]\n\
             # Gate GitHub prose; secret redaction is always enabled.\n\
             github_text_guard = true\n\
             implementers = 3\n\
             judges = 3\n\
             deliberate_rounds = 1\n\
             reviewers = 3\n\
             review_rounds = 6\n\
             # Fix rounds a failing verify.gate gets before the run is blocked (0 = none).\n\
             gate_fix_rounds = 1\n\
             max_parallel = 4\n\
             language = \"en\"\n\
             # One CLI conversation per seat: judges keep their own argument\n\
             # across deliberation, the fixer keeps its implementation context.\n\
             sessions = true\n\
             # Reviewer-seat timeout. When timeout_verify is omitted, E2E and\n\
             # the final gate inherit this value for compatibility.\n\
             timeout_review = 1200\n\
             # Optional independent E2E/final-gate timeout; uncomment to keep\n\
             # verification independent if timeout_review changes later.\n\
             # timeout_verify = 1200\n\n\
             # Chat personas (tone only; the web Chat picks one per conversation).\n\
             # Built in: magi, rei, misato, ritsuko, shinji, asuka, kaworu. Entries add to\n\
             # them, and one with a built-in's id replaces it. `default` is the plain\n\
             # voice and cannot be redefined. Declare this in one layer only.\n\
             # [[talk.personas]]\n\
             # id = \"gendo\"\n\
             # name = \"Gendo Ikari\"\n\
             # prompt = \"Speak coldly and tersely, hands folded.\"\n\n\
             [verify]\n\
             # Run once per review round in the winner's worktree; failures are\n\
             # fed back to the fixer.\n\
             e2e = []\n\
             # Final gate. Every command must exit 0 before a merge.\n\
             gate = []\n\
             # Mechanical fixers (formatters) run in the winner's worktree just\n\
             # before the gate; whatever they change becomes one commit. A failing\n\
             # command only warns - the gate stays the arbiter. Same timeout as the\n\
             # gate (timeout_verify). Keep it light and idempotent.\n\
             # pre_gate = []\n\n\
             [merge]\n\
             # none | local | pr\n\
             mode = \"none\"\n\
             # release_bump = true  # Rust (Cargo.toml) repositories only; a no-op elsewhere\n\n\
             [update]\n\
             # off | notify | install — checked in the background, throttled.\n\
             mode = \"notify\"\n\
             # interval = \"24h\"\n\n\
             [daemon]\n\
             # Minutes a release-bump pull request (chore/release-v*) may sit with\n\
             # no new commit and no check changing state before `magi serve`\n\
             # notices and asks you. A failed check is rerun once on its own;\n\
             # still red after that escalates at once. 0 turns the watcher off.\n\
             # release_stall_minutes = 60\n\n\
             [release]\n\
             # actions (default) | local. \"local\" is for repositories whose GitHub\n\
             # Actions never run (private, no minutes): the release pull request\n\
             # does not wait for CI, you approve the merge in magi, and then\n\
             # `magi serve` pushes the vX.Y.Z tag (never over an existing one) and\n\
             # runs `commands` from a clean checkout of the merge commit. A\n\
             # failure holds the release with a notice; it is never retried blind.\n\
             # Needs `magi serve` running and [daemon] release_stall_minutes > 0.\n\
             # mode = \"actions\"\n\
             # Run in order; the first failure stops. They see MAGI_RELEASE_VERSION,\n\
             # MAGI_RELEASE_TAG, MAGI_RELEASE_COMMIT and MAGI_RELEASE_PR. Make them\n\
             # safe to repeat: a crash mid-command is treated as unfinished.\n\
             # commands = [\"cargo build --release\", \"gh release create \\\"$MAGI_RELEASE_TAG\\\" --generate-notes\"]\n\
             # timeout_minutes = 30\n",
        );
        s
    }
}

/// Is `program` on `PATH`?
pub fn which(program: &str) -> bool {
    find_program(program).is_some()
}

/// The file a bare `program` name resolves to on `PATH`, the way the OS shell
/// would find it.
///
/// Spawn agents through this, not by bare name: on Windows Rust's std
/// only tries `name.exe`, so a CLI installed as an npm `.cmd` shim (codex
/// since its 2026-09-23 reinstall) is "not found" even though a shell runs it.
/// On Windows an extensionless file is never a match: npm writes an `sh`
/// script beside every `.cmd` shim, and spawning that fails with os error 193.
pub fn find_program(program: &str) -> Option<PathBuf> {
    find_program_on(program, &std::env::var_os("PATH")?)
}

/// [`find_program`] against an explicit `PATH`, for a child whose environment
/// overrides it.
pub fn find_program_on(program: &str, paths: &std::ffi::OsStr) -> Option<PathBuf> {
    let pathext = std::env::var("PATHEXT").unwrap_or_else(|_| ".EXE;.CMD;.BAT".into());
    find_program_in(program, paths, cfg!(windows).then_some(pathext.as_str()))
}

fn find_program_in(
    program: &str,
    paths: &std::ffi::OsStr,
    pathext: Option<&str>,
) -> Option<PathBuf> {
    let p = Path::new(program);
    if p.components().count() > 1 {
        return p.is_file().then(|| p.to_path_buf());
    }
    std::env::split_paths(paths).find_map(|dir| match pathext {
        Some(exts) => {
            let bare = dir.join(program);
            if p.extension().is_some() && bare.is_file() {
                return Some(bare);
            }
            exts.split(';')
                .filter(|e| !e.is_empty())
                .map(|e| dir.join(format!("{program}{}", e.to_lowercase())))
                .find(|c| c.is_file())
        }
        None => Some(dir.join(program)).filter(|c| c.is_file()),
    })
}

/// Sidecar naming the checkout an extracted layer stands for.
const REPO_MARKER: &str = ".magi-repo";

fn git_out(repo: &Path, args: &[&str]) -> Option<String> {
    use crate::proc::Quiet as _;
    let out = std::process::Command::new("git")
        .args(args)
        .quiet()
        .current_dir(repo)
        .stdin(std::process::Stdio::null())
        .output()
        .ok()?;
    out.status
        .success()
        .then(|| String::from_utf8_lossy(&out.stdout).into_owned())
}

/// Is `repo` inside a git working tree? A directory that is not has no branch
/// to be stale against, so its files are read as they are.
fn is_git_worktree(repo: &Path) -> bool {
    git_out(repo, &["rev-parse", "--git-dir"]).is_some()
}

#[derive(Deserialize, Default)]
struct ProbeMerge {
    base: Option<String>,
    remote: Option<String>,
}

#[derive(Deserialize, Default)]
struct Probe {
    merge: Option<ProbeMerge>,
}

/// `[merge]` base / remote from one file, nothing else. The file is rendered
/// (env templates, includes) exactly as a real load would, so a machine layer
/// saying `base = "{{ env.X }}"` locates the same ref; when rendering fails
/// (a checkout file that needs its own repo context) the plain TOML is read
/// instead. Unreadable is `None`: the real load reports it.
fn probe_merge(path: &Path, repo: &Path) -> Option<ProbeMerge> {
    if !path.is_file() {
        return None;
    }
    let paths = [path.to_path_buf()];
    let mut engine = teravars::Engine::default();
    let mut ctx = Config::render_ctx(&paths);
    // The layered load renders every layer for the checkout being resolved;
    // so does this, or `{{ repo_name }}` would name the file's own directory.
    ctx.insert("repo", &repo.to_string_lossy());
    ctx.insert(
        "repo_name",
        &repo.file_name().unwrap_or_default().to_string_lossy(),
    );
    if let Ok(merged) = teravars::load_merged(&paths, &mut engine, &ctx)
        && let Ok(probe) = toml::Value::Table(merged.config).try_into::<Probe>()
    {
        return probe.merge;
    }
    let text = std::fs::read_to_string(path).ok()?;
    toml::from_str::<Probe>(&text).ok()?.merge
}

/// The `[merge] remote` / `base` the layers name, before any git lookup.
fn probe_remote_base(repo: &Path) -> (String, Option<String>) {
    let mut remote = None;
    let mut base = None;
    let mut sources: Vec<PathBuf> = Config::machine_layer().into_iter().collect();
    sources.push(repo.join("magi.toml"));
    sources.push(repo.join(".magi").join("config.toml"));
    for path in sources {
        if let Some(m) = probe_merge(&path, repo) {
            remote = remote.or(m.remote.filter(|s| !s.trim().is_empty()));
            base = base.or(m.base.filter(|s| !s.trim().is_empty()));
        }
    }
    (remote.unwrap_or_else(|| "origin".to_owned()), base)
}

/// Where the remote ref is: see the module doc for the order.
fn resolve_remote_base(repo: &Path) -> Result<(String, String)> {
    let (remote, base) = probe_remote_base(repo);
    let base = match base {
        Some(b) => b,
        None => {
            let head = format!("refs/remotes/{remote}/HEAD");
            git_out(repo, &["symbolic-ref", "--quiet", &head])
                .and_then(|s| crate::git::remote_head_branch(&remote, &s))
                .with_context(|| {
                    format!(
                        "cannot tell which branch of `{remote}` holds magi.toml: \
                         set [merge] base, or run `git remote set-head {remote} -a`"
                    )
                })?
        }
    };
    Ok((remote, base))
}

fn fnv_hex(text: &str) -> String {
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
    for b in text.bytes() {
        hash ^= u64::from(b);
        hash = hash.wrapping_mul(0x0100_0000_01b3);
    }
    format!("{hash:016x}")
}

/// Does the text declare an `include` directive in any form teravars accepts
/// (root `include`, bare or quoted, or `[teravars] include`, as a table or an
/// inline table)? Parsed as TOML when it parses; a templated file that does
/// not parse is judged by a plain search for the word, because over-detecting
/// only costs an extra extraction while missing one fails the load.
fn declares_include(text: &str) -> bool {
    match toml::from_str::<toml::Table>(text) {
        Ok(table) => {
            table.contains_key("include")
                || table
                    .get("teravars")
                    .and_then(toml::Value::as_table)
                    .is_some_and(|t| t.contains_key("include"))
        }
        Err(_) => text.contains("include"),
    }
}

/// Unpack the whole tree of `sha` into `dest`, so relative `include`s of a
/// repository layer resolve against the same commit.
fn extract_tree(repo: &Path, sha: &str, dest: &Path) -> Result<()> {
    use crate::proc::Quiet as _;
    let mut archive = std::process::Command::new("git")
        .args(["archive", "--format=tar", sha])
        .quiet()
        .current_dir(repo)
        .stdin(std::process::Stdio::null())
        .stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::null())
        .spawn()
        .context("running git archive")?;
    let tar = std::process::Command::new("tar")
        .arg("-x")
        .arg("-C")
        .arg(dest)
        .quiet()
        .stdin(archive.stdout.take().context("git archive has no stdout")?)
        .output()
        .context("running tar")?;
    let status = archive.wait().context("waiting for git archive")?;
    if !status.success() || !tar.status.success() {
        bail!(
            "cannot unpack {sha} for the config's includes: {}",
            String::from_utf8_lossy(&tar.stderr).trim()
        );
    }
    Ok(())
}

/// The repository layers (`.magi/config.toml`, `magi.toml`; lowest first) of
/// `<remote>/<base>`, extracted from one commit so both files agree.
fn remote_layers(repo: &Path) -> Result<Vec<PathBuf>> {
    let (remote, base) = resolve_remote_base(repo)?;
    let tracking = format!("refs/remotes/{remote}/{base}");
    let spec = format!("{tracking}^{{commit}}");
    let sha = git_out(repo, &["rev-parse", "--verify", "--quiet", &spec])
        .map(|s| s.trim().to_owned())
        .filter(|s| !s.is_empty())
        .with_context(|| {
            format!(
                "`{remote}/{base}` does not exist in this checkout; fetch it \
                 (`git fetch {remote} {base}`) or set [merge] base/remote. magi will not read \
                 a possibly stale local magi.toml instead"
            )
        })?;
    let key = format!("{sha}-{}", fnv_hex(&repo.to_string_lossy()));
    let rels = [".magi/config.toml", "magi.toml"];
    let mut texts: Vec<(&str, String)> = Vec::new();
    for rel in rels {
        let object = format!("{sha}:{rel}");
        if git_out(repo, &["cat-file", "-e", &object]).is_none() {
            continue;
        }
        let Some(text) = git_out(repo, &["show", &object]) else {
            bail!("cannot read {rel} from {remote}/{base} ({sha})");
        };
        texts.push((rel, text));
    }
    let wants_tree = texts.iter().any(|(_, t)| declares_include(t));
    // Content-addressed and built beside the final name, then renamed in: a
    // concurrent `discover` sees the whole directory or none of it, never a
    // half-written file.
    let build = |root: &Path| -> Result<PathBuf> {
        let final_dir = root.join(&key);
        if !final_dir.is_dir() {
            std::fs::create_dir_all(root)?;
            let tmp = root.join(format!(
                "{key}.tmp-{}-{}",
                std::process::id(),
                std::time::SystemTime::now()
                    .duration_since(std::time::UNIX_EPOCH)
                    .map(|d| d.as_nanos())
                    .unwrap_or_default()
            ));
            let filled = (|| -> Result<()> {
                std::fs::create_dir_all(&tmp)?;
                if wants_tree {
                    extract_tree(repo, &sha, &tmp)?;
                }
                for (rel, text) in &texts {
                    let file = tmp.join(rel);
                    let parent = file.parent().unwrap_or(&tmp);
                    std::fs::create_dir_all(parent)?;
                    std::fs::write(&file, text)?;
                    std::fs::write(parent.join(REPO_MARKER), repo.to_string_lossy().as_bytes())?;
                }
                Ok(())
            })();
            if let Err(e) = filled {
                let _ = std::fs::remove_dir_all(&tmp);
                return Err(e);
            }
            if std::fs::rename(&tmp, &final_dir).is_err() {
                // Lost the race to another process building the same commit.
                let _ = std::fs::remove_dir_all(&tmp);
                if !final_dir.is_dir() {
                    bail!("cannot place {}", final_dir.display());
                }
            }
        }
        Ok(final_dir)
    };
    let common = git_out(
        repo,
        &["rev-parse", "--path-format=absolute", "--git-common-dir"],
    )
    .map(|s| PathBuf::from(s.trim()).join("magi").join("config"));
    let dir = match common.map(|c| build(&c)) {
        Some(Ok(d)) => d,
        _ => build(&std::env::temp_dir().join("magi-config"))
            .with_context(|| format!("extracting config from {remote}/{base}"))?,
    };
    Ok(texts.iter().map(|(rel, _)| dir.join(rel)).collect())
}

#[cfg(test)]
mod tests {
    #[test]
    fn context_window_prefers_exact_then_longest_prefix_and_user_over_builtin() {
        let mut cfg = Config::default();
        assert_eq!(
            cfg.context_window("claude-sonnet-4-5-20250929"),
            Some(200_000)
        );
        assert_eq!(cfg.context_window("gpt-4.1-mini"), Some(1_000_000));
        assert_eq!(cfg.context_window("mystery-model"), None);
        cfg.context_windows
            .insert("claude-sonnet-4-5".into(), 1_000_000);
        cfg.context_windows.insert("claude-sonnet-4".into(), 5);
        cfg.context_windows.insert("mystery".into(), 32_768);
        // Longest user prefix beats a shorter one and the built-in table.
        assert_eq!(
            cfg.context_window("claude-sonnet-4-5-20250929"),
            Some(1_000_000)
        );
        // An exact name beats any prefix.
        cfg.context_windows
            .insert("claude-sonnet-4-5-20250929".into(), 7);
        assert_eq!(cfg.context_window("claude-sonnet-4-5-20250929"), Some(7));
        assert_eq!(cfg.context_window("mystery-model"), Some(32_768));
    }

    use super::*;

    /// npm writes an extensionless `sh` script beside `codex.cmd`; on Windows
    /// the `.cmd` is the spawnable one (os error 193 otherwise, 2026-09-23).
    #[test]
    fn windows_lookup_picks_the_cmd_shim_over_the_extensionless_script() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("codex"), "#!/bin/sh\n").unwrap();
        std::fs::write(dir.path().join("codex.cmd"), "@echo off\n").unwrap();
        let paths = dir.path().as_os_str();
        assert_eq!(
            find_program_in("codex", paths, Some(".EXE;.CMD")),
            Some(dir.path().join("codex.cmd"))
        );
        assert_eq!(
            find_program_in("codex", paths, None),
            Some(dir.path().join("codex"))
        );
        assert_eq!(find_program_in("claude", paths, Some(".EXE;.CMD")), None);
    }

    fn spec(id: &str) -> AgentSpec {
        AgentSpec {
            id: id.to_owned(),
            kind: AgentKind::Command,
            model: None,
            command: vec!["true".to_owned()],
            extra_args: Vec::new(),
            env: BTreeMap::new(),
            prompt_delivery: None,
        }
    }

    #[test]
    fn github_text_guard_defaults_on_and_can_be_disabled() {
        let default: Graph = toml::from_str("").unwrap();
        assert!(default.github_text_guard);
        let disabled: Graph = toml::from_str("github_text_guard = false").unwrap();
        assert!(!disabled.github_text_guard);
        let config = layered("", "[graph]\ngithub_text_guard = false\n").unwrap();
        assert!(!config.graph.github_text_guard);
        assert!(Config::starter_toml().contains("github_text_guard = true"));
    }

    #[test]
    fn timeout_verify_omitted_from_old_toml_inherits_timeout_review() {
        // `timeout_verify` used to not exist: `verify.e2e`/`verify.gate` ran
        // under `timeout_review`. A config written before this field existed
        // must run exactly as before, which means its default has to be the
        // same 1200s `timeout_review` has always defaulted to.
        let g: Graph = toml::from_str("timeout_review = 3600").expect("parse");
        assert_eq!(g.timeout_verify, None);
        assert_eq!(g.verify_timeout(), 3600);
    }

    #[test]
    fn shrinking_timeout_review_does_not_shrink_timeout_verify() {
        // The bug this field exists to close: `[graph] timeout_review = 45`
        // used to shrink the real-machine `verify.e2e`/`verify.gate` budget
        // along with the reviewer seats' own timeout, because both read the
        // same field.
        let g: Graph = toml::from_str("timeout_review = 45").expect("parse");
        assert_eq!(g.timeout_review, 45);
        assert_eq!(
            g.verify_timeout(),
            45,
            "an omitted legacy value follows review"
        );
        let explicit: Graph = toml::from_str("timeout_review = 45\ntimeout_verify = 1200")
            .expect("parse explicit override");
        assert_eq!(explicit.verify_timeout(), 1200);
    }

    #[test]
    fn graph_implementers_new_key_loads_and_old_key_is_an_alias() {
        let g: Graph = toml::from_str("implementers = 4\n").unwrap();
        assert_eq!(g.implementers, 4);
        let g: Graph = toml::from_str("candidates = 5\n").unwrap();
        assert_eq!(g.implementers, 5);
    }

    fn layered(lower: &str, upper: &str) -> Result<Config> {
        let dir = tempfile::tempdir().unwrap();
        let a = dir.path().join("a.toml");
        let b = dir.path().join("b.toml");
        std::fs::write(&a, lower).unwrap();
        std::fs::write(&b, upper).unwrap();
        Config::load_layers(&[a, b])
    }

    #[test]
    fn graph_implementers_higher_layer_wins_across_spellings() {
        let c = layered("[graph]\ncandidates = 2\n", "[graph]\nimplementers = 5\n").unwrap();
        assert_eq!(c.graph.implementers, 5);
        let c = layered("[graph]\nimplementers = 2\n", "[graph]\ncandidates = 5\n").unwrap();
        assert_eq!(c.graph.implementers, 5);
        let c = layered("[graph]\ncandidates = 2\n", "[graph]\njudges = 3\n").unwrap();
        assert_eq!(c.graph.implementers, 2);
    }

    #[test]
    fn graph_implementers_both_keys_in_one_layer_is_refused() {
        let err = layered("", "[graph]\ncandidates = 2\nimplementers = 3\n")
            .unwrap_err()
            .to_string();
        assert!(
            err.contains("candidates") && err.contains("implementers"),
            "{err}"
        );
        assert!(err.contains("b.toml"), "{err}");
    }

    #[test]
    fn a_toml_layer_written_before_these_fields_existed_still_parses() {
        // `deny_unknown_fields` cuts both ways: a config from before
        // `timeout_verify`/`e2e_every_round` existed must still parse, with
        // both defaulted rather than refused as unknown-in-reverse.
        let g: Graph =
            toml::from_str("candidates = 1\nreviewers = 3\nreview_rounds = 6\nmax_parallel = 4\n")
                .expect("an old-shaped [graph] table must still parse");
        assert_eq!(g.verify_timeout(), Graph::default().timeout_review);
        assert!(
            !g.e2e_every_round,
            "off by default, same as before this field existed"
        );
    }

    #[test]
    fn empty_roles_rotate_judges_off_their_own_candidate() {
        // Three seats, said out loud: this is a test about *rotation*, and it
        // has nothing to say about how many candidates a task buys by default.
        let cfg = Config {
            agents: vec![spec("a"), spec("b"), spec("c")],
            graph: Graph {
                implementers: 3,
                ..Graph::default()
            },
            ..Config::default()
        };
        let roles = cfg.resolve_roles().unwrap();
        let impls: Vec<&str> = roles.implementers.iter().map(|a| a.id.as_str()).collect();
        let judges: Vec<&str> = roles.judges.iter().map(|a| a.id.as_str()).collect();
        assert_eq!(impls, ["a", "b", "c"]);
        assert_eq!(judges, ["b", "c", "a"]);
        for (i, j) in judges.iter().enumerate() {
            assert_ne!(*j, impls[i], "judge {i} must not sit on its own candidate");
        }
    }

    #[test]
    fn single_agent_roster_fills_every_seat() {
        let cfg = Config {
            agents: vec![spec("solo")],
            graph: Graph {
                implementers: 3,
                ..Graph::default()
            },
            ..Config::default()
        };
        let roles = cfg.resolve_roles().unwrap();
        assert_eq!(roles.implementers.len(), 3);
        assert!(roles.judges.iter().all(|a| a.id == "solo"));
    }

    #[test]
    fn implementer_roster_is_the_whole_agent_list_untruncated_when_unset() {
        // `implementers = 1` (a solo run) still resolves `implementers` down to
        // one slot, but `implementer_roster` must carry every agent in the
        // roster, in file order, for `graph::Runner`'s quota fallback to walk
        // forward through once that one slot's agent runs out of quota.
        let cfg = Config {
            agents: vec![spec("a"), spec("b"), spec("c")],
            graph: Graph {
                implementers: 1,
                ..Graph::default()
            },
            ..Config::default()
        };
        let roles = cfg.resolve_roles().unwrap();
        assert_eq!(roles.implementers.len(), 1);
        let roster: Vec<&str> = roles
            .implementer_roster
            .iter()
            .map(|a| a.id.as_str())
            .collect();
        assert_eq!(roster, ["a", "b", "c"]);
    }

    #[test]
    fn implementer_roster_follows_explicit_ids_in_the_order_named() {
        let cfg = Config {
            agents: vec![spec("a"), spec("b"), spec("c")],
            roles: Roles {
                implementers: vec!["c".to_owned(), "a".to_owned()],
                ..Roles::default()
            },
            graph: Graph {
                implementers: 1,
                ..Graph::default()
            },
            ..Config::default()
        };
        let roles = cfg.resolve_roles().unwrap();
        // Unaffected by the new field: still just the first named id.
        assert_eq!(roles.implementers.len(), 1);
        assert_eq!(roles.implementers[0].id, "c");
        let roster: Vec<&str> = roles
            .implementer_roster
            .iter()
            .map(|a| a.id.as_str())
            .collect();
        assert_eq!(roster, ["c", "a"]);
    }

    #[test]
    fn explicit_roles_win() {
        let cfg = Config {
            agents: vec![spec("a"), spec("b")],
            roles: Roles {
                implementers: vec!["b".to_owned()],
                judges: vec!["a".to_owned()],
                reviewers: Vec::new(),
                fixer: Some("a".into()),
                ..Roles::default()
            },
            ..Config::default()
        };
        let roles = cfg.resolve_roles().unwrap();
        assert!(roles.implementers.iter().all(|a| a.id == "b"));
        assert!(roles.judges.iter().all(|a| a.id == "a"));
        let fixer = roles.fixer.unwrap();
        assert_eq!(fixer.len(), 1);
        assert_eq!(fixer[0].id, "a");
        assert_eq!(roles.conductor.id, "a");
    }

    #[test]
    fn fixer_takes_a_string_or_an_ordered_chain() {
        let one: Roles = toml::from_str("fixer = \"a\"").unwrap();
        assert_eq!(one.fixer.as_ref().unwrap().ids(), ["a"]);
        let chain: Roles = toml::from_str("fixer = [\"b\", \"a\"]").unwrap();
        assert_eq!(chain.fixer.as_ref().unwrap().ids(), ["b", "a"]);

        let resolve = |fixer: Option<AgentChoice>| {
            Config {
                agents: vec![spec("a"), spec("b"), spec("c")],
                roles: Roles {
                    fixer,
                    ..Roles::default()
                },
                ..Config::default()
            }
            .resolve_roles()
        };
        let ids = |r: &ResolvedRoles| -> Vec<String> {
            r.fixer
                .as_ref()
                .unwrap()
                .iter()
                .map(|s| s.id.clone())
                .collect()
        };
        // The string form is a chain of one; unset stays unset (the winner's author).
        assert_eq!(ids(&resolve(Some("c".into())).unwrap()), ["c"]);
        assert!(resolve(None).unwrap().fixer.is_none());
        // Order kept, an unknown id skipped, a duplicate keeps its first place.
        let chain = AgentChoice::Chain(vec!["b".into(), "zzz".into(), "a".into(), "b".into()]);
        assert_eq!(ids(&resolve(Some(chain)).unwrap()), ["b", "a"]);
        // Nothing resolving names the role.
        let err = resolve(Some(AgentChoice::Chain(vec!["zzz".into()]))).unwrap_err();
        assert!(format!("{err:#}").contains("fixer"), "{err:#}");
    }

    #[test]
    fn unknown_agent_id_is_an_error() {
        let cfg = Config {
            agents: vec![spec("a")],
            roles: Roles {
                judges: vec!["nope".to_owned()],
                ..Roles::default()
            },
            ..Config::default()
        };
        assert!(cfg.resolve_roles().is_err());
    }

    #[test]
    fn conductor_role_is_resolved_validated_and_has_a_fallback() {
        let mut cfg = Config {
            agents: vec![spec("a"), spec("b")],
            ..Config::default()
        };
        assert_eq!(cfg.resolve_roles().unwrap().conductor.id, "a");

        cfg.roles.conductor = Some("b".into());
        assert_eq!(cfg.resolve_roles().unwrap().conductor.id, "b");

        cfg.roles.conductor = Some("missing".into());
        assert!(cfg.resolve_roles().is_err());
    }

    #[test]
    fn a_standalone_role_takes_a_string_or_an_array_and_round_trips() {
        let one: Roles = toml::from_str("synthesizer = \"opus\"").unwrap();
        assert_eq!(one.synthesizer, Some(AgentChoice::One("opus".to_owned())));
        assert_eq!(primary(one.synthesizer.as_ref()), Some("opus"));

        let chain: Roles = toml::from_str("chatter = [\"opus\", \"codex\"]").unwrap();
        assert_eq!(chain.chatter.as_ref().unwrap().ids(), ["opus", "codex"]);
        assert_eq!(primary(chain.chatter.as_ref()), Some("opus"));

        for roles in [one, chain] {
            let text = toml::to_string(&roles).unwrap();
            let back: Roles = toml::from_str(&text).unwrap();
            assert_eq!(back.synthesizer, roles.synthesizer);
            assert_eq!(back.chatter, roles.chatter);
        }
        let text = toml::to_string(&Roles {
            conductor: Some("x".into()),
            ..Roles::default()
        })
        .unwrap();
        assert!(
            text.contains("conductor = \"x\""),
            "string stays a string: {text}"
        );
        assert!(toml::from_str::<Roles>("synthesizer = 3").is_err());
    }

    #[test]
    fn an_empty_choice_counts_as_unset() {
        assert!(AgentChoice::Chain(Vec::new()).ids().is_empty());
        assert!(AgentChoice::One("  ".to_owned()).ids().is_empty());
        assert_eq!(primary(Some(&AgentChoice::Chain(vec![]))), None);
    }

    #[test]
    fn synthesizer_role_is_a_lazy_lookup_with_the_same_fallback_as_chatter() {
        // Unlike `conductor`, `synthesizer` is never validated by
        // `resolve_roles` — it is looked up lazily by
        // `graph::Runner::synthesize_brief` the same way `[roles] chatter`
        // is looked up by `talk::begin`, so this exercises `agent::pick`
        // directly instead of going through `resolve_roles`.
        let mut cfg = Config {
            agents: vec![spec("a"), spec("b")],
            ..Config::default()
        };
        let want = primary(cfg.roles.synthesizer.as_ref());
        assert_eq!(
            crate::agent::pick(&cfg.agents, want, &crate::agent::installed)
                .unwrap()
                .id,
            "a",
            "unset falls back to agent::pick's own default order"
        );

        cfg.roles.synthesizer = Some("b".into());
        let want = primary(cfg.roles.synthesizer.as_ref());
        assert_eq!(
            crate::agent::pick(&cfg.agents, want, &crate::agent::installed)
                .unwrap()
                .id,
            "b",
            "the named agent wins over the default order"
        );
    }

    #[test]
    fn empty_roster_is_an_error() {
        assert!(Config::default().resolve_roles().is_err());
    }

    #[test]
    fn advise_defaults_to_on_with_three_proposals() {
        let g = Graph::default();
        assert!(g.advise);
        assert_eq!(g.advisors, 3);
    }

    #[test]
    fn unset_advisors_falls_back_to_the_judge_roster() {
        let cfg = Config {
            agents: vec![spec("a"), spec("b")],
            roles: Roles {
                judges: vec!["b".to_owned()],
                ..Roles::default()
            },
            graph: Graph {
                advisors: 2,
                ..Graph::default()
            },
            ..Config::default()
        };
        let advisors = cfg.advisors().expect("advisors resolve");
        assert_eq!(advisors.len(), 2);
        assert!(
            advisors.iter().all(|a| a.id == "b"),
            "an unset [roles] advisors must fall back to [roles] judges: {advisors:?}"
        );
    }

    #[test]
    fn an_explicit_advisor_roster_wins_over_the_judge_fallback() {
        let cfg = Config {
            agents: vec![spec("a"), spec("b")],
            roles: Roles {
                judges: vec!["b".to_owned()],
                advisors: vec!["a".to_owned()],
                ..Roles::default()
            },
            graph: Graph {
                advisors: 2,
                ..Graph::default()
            },
            ..Config::default()
        };
        let advisors = cfg.advisors().expect("advisors resolve");
        assert!(advisors.iter().all(|a| a.id == "a"));
    }

    /// Neither `[roles] advisors` nor `[roles] judges` set: an unconfigured
    /// advisor roster must resolve to the exact same agents an unconfigured
    /// judge panel would get - same ids, same rotation offset - or the
    /// promise in [`Roles::advisors`]'s doc ("advisor diversity for free")
    /// does not actually hold.
    #[test]
    fn an_unconfigured_advisor_and_judge_roster_resolve_to_the_same_agents() {
        let cfg = Config {
            agents: vec![spec("a"), spec("b"), spec("c")],
            graph: Graph {
                advisors: 3,
                judges: 3,
                ..Graph::default()
            },
            ..Config::default()
        };
        let advisors = cfg.advisors().expect("advisors resolve");
        let judges = cfg.resolve_roles().expect("roles resolve").judges;
        let advisor_ids: Vec<&str> = advisors.iter().map(|a| a.id.as_str()).collect();
        let judge_ids: Vec<&str> = judges.iter().map(|a| a.id.as_str()).collect();
        assert_eq!(
            advisor_ids, judge_ids,
            "an unconfigured advisor roster must be the same seats an unconfigured judge panel gets"
        );
    }

    #[test]
    fn an_unresolvable_advisor_seat_is_an_error_naming_the_id() {
        let cfg = Config {
            agents: vec![spec("a")],
            roles: Roles {
                advisors: vec!["nope".to_owned()],
                ..Roles::default()
            },
            graph: Graph {
                advisors: 1,
                ..Graph::default()
            },
            ..Config::default()
        };
        let err = cfg.advisors().expect_err("`nope` is not in the roster");
        assert!(format!("{err:#}").contains("nope"));
    }

    #[test]
    fn repos_default_to_no_roots_and_a_day_of_trust() {
        assert_eq!(Config::default().repos.roots, Vec::<PathBuf>::new());
        assert_eq!(Config::default().repos.scan_ttl, 86_400);
        assert_eq!(Config::default().repos.fetch_interval, 600);
    }

    #[test]
    fn a_config_file_with_no_repos_table_still_loads() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, "[graph]\ncandidates = 2\n").unwrap();
        let cfg = Config::load(&path).expect("must load without [repos]");
        assert_eq!(cfg.repos.roots, Vec::<PathBuf>::new());
        assert_eq!(cfg.repos.scan_ttl, 86_400);
    }

    /// A fixture is the whole config under test.
    ///
    /// `layers` used to reach for `dirs::config_dir()` unconditionally, so on
    /// a machine where somebody had written `<config_dir>/magi/config.toml`
    /// the suite silently loaded it as the lowest layer. Adding `[repos]
    /// roots` there turned two web tests red - their fixtures declare
    /// `[repos] roots` too, and `refuse_split_arrays` rightly refuses one
    /// array key spread across two layers. CI stayed green throughout,
    /// because a runner has no such file: the suite failed only where magi is
    /// actually used.
    ///
    /// So a test build has no machine layer unless it asks for one, and this
    /// is that promise. Written against a real file at the real location so
    /// it fails if `machine_layer` starts reading it again.
    #[test]
    fn a_test_build_does_not_read_the_operators_machine_config() {
        let repo = tempfile::tempdir().unwrap();
        std::fs::write(repo.path().join("magi.toml"), "[graph]\ncandidates = 2\n").unwrap();

        let layers = Config::layers(repo.path());
        assert_eq!(
            layers,
            vec![repo.path().join("magi.toml")],
            "only the fixture's own file may be a layer"
        );
        if let Some(real) = dirs::config_dir() {
            let machine = real.join("magi").join("config.toml");
            assert!(
                !layers.contains(&machine),
                "the operator's {} must not be a layer in a test build",
                machine.display()
            );
        }
    }

    #[test]
    fn starter_toml_loads_through_teravars() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, Config::starter_toml()).unwrap();
        let parsed = Config::load(&path).expect("starter config must load");
        assert_eq!(parsed.graph.implementers, 3);
        assert_eq!(parsed.merge.mode, MergeMode::None);
        assert_eq!(parsed.merge.style, MergeStyle::Merge);
        assert!(parsed.graph.sessions);
        assert!(parsed.graph.github_text_guard);
        assert_eq!(parsed.graph.timeout_review, 1200);
        assert_eq!(parsed.graph.verify_timeout(), 1200);
        assert_eq!(parsed.update.mode, UpdateMode::Notify);
    }

    #[test]
    fn release_defaults_to_actions_and_the_starter_documents_it() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, Config::starter_toml()).unwrap();
        let r = Config::load(&path).unwrap().release;
        assert_eq!(r.mode, ReleaseMode::Actions);
        assert!(!r.is_local());
        assert!(r.commands.is_empty());
        assert_eq!(r.timeout_minutes, 30);
        assert!(Config::starter_toml().contains("# mode = \"actions\""));
    }

    #[test]
    fn release_local_parses_and_unknown_keys_are_refused() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(
            &path,
            "[release]\nmode = \"local\"\ncommands = [\"true\", \"echo $MAGI_RELEASE_TAG\"]\ntimeout_minutes = 5\n",
        )
        .unwrap();
        let r = Config::load(&path).unwrap().release;
        assert!(r.is_local());
        assert_eq!(r.commands.len(), 2);
        assert_eq!(r.timeout_minutes, 5);
        std::fs::write(&path, "[release]\nmode = \"local\"\nbogus = 1\n").unwrap();
        assert!(Config::load(&path).is_err());
        std::fs::write(&path, "[release]\nmode = \"gha\"\n").unwrap();
        assert!(Config::load(&path).is_err());
    }

    #[test]
    fn pre_gate_defaults_to_empty_and_the_starter_documents_it() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, Config::starter_toml()).unwrap();
        assert!(Config::load(&path).unwrap().verify.pre_gate.is_empty());
        assert!(Config::starter_toml().contains("# pre_gate = []"));
    }

    #[test]
    fn starter_toml_explains_inherited_and_explicit_verify_timeouts() {
        let starter = Config::starter_toml();
        assert!(starter.contains("When timeout_verify is omitted, E2E and"));
        assert!(starter.contains("verification independent if timeout_review changes later"));
        assert!(starter.contains("# timeout_verify = 1200"));
    }

    #[test]
    fn starter_toml_documents_chat_personas() {
        let starter = Config::starter_toml();
        assert!(starter.contains("# [[talk.personas]]"));
        assert!(starter.contains("tone only"));
    }

    #[test]
    fn talk_personas_parse_and_are_validated() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(
            &path,
            "[[talk.personas]]\nid = \"rei\"\nname = \"Quiet\"\nprompt = \"Be brief.\"\n\n\
             [[talk.personas]]\nid = \"gendo\"\nname = \"Gendo\"\nprompt = \"Be cold.\"\n",
        )
        .unwrap();
        let cfg = Config::load(&path).expect("loads");
        assert_eq!(cfg.talk.personas.len(), 2);
        let catalog = crate::persona::catalog(&cfg.talk.personas);
        let rei = catalog.iter().find(|p| p.id == "rei").unwrap();
        assert_eq!(
            (rei.name.as_str(), rei.prompt.as_str()),
            ("Quiet", "Be brief.")
        );
        assert_eq!(catalog.last().unwrap().id, "gendo");

        for (body, needle) in [
            (
                "[[talk.personas]]\nid = \"\"\nname = \"n\"\nprompt = \"p\"\n",
                "empty `id`",
            ),
            (
                "[[talk.personas]]\nid = \"a\"\nname = \"n\"\nprompt = \" \"\n",
                "empty `prompt`",
            ),
            (
                "[[talk.personas]]\nid = \"a\"\nname = \"n\"\nprompt = \"p\"\n\
                 [[talk.personas]]\nid = \"a\"\nname = \"m\"\nprompt = \"q\"\n",
                "more than once",
            ),
            (
                "[[talk.personas]]\nid = \"default\"\nname = \"n\"\nprompt = \"p\"\n",
                "cannot be redefined",
            ),
        ] {
            std::fs::write(&path, body).unwrap();
            let err = format!("{:#}", Config::load(&path).unwrap_err());
            assert!(err.contains(needle), "{needle}: {err}");
        }
    }

    #[test]
    fn talk_personas_in_two_layers_are_refused() {
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("repo.toml");
        let one = "[[talk.personas]]\nid = \"a\"\nname = \"n\"\nprompt = \"p\"\n";
        std::fs::write(&machine, one).unwrap();
        std::fs::write(&repo, one.replace("\"a\"", "\"b\"")).unwrap();
        let err = format!("{:#}", Config::load_layers(&[machine, repo]).unwrap_err());
        assert!(err.contains("talk.personas"), "{err}");
    }

    #[test]
    fn starter_toml_documents_role_lists_as_backup_order() {
        let starter = Config::starter_toml();
        assert!(starter.contains("also an ordered backup list"));
        assert!(starter.contains("codex then sonnet are spares"));
    }

    /// A repository whose ruleset forbids merge commits declares that once,
    /// here, rather than magi asking GitHub about it on every render (see
    /// [`MergeStyle`]'s own doc for why).
    #[test]
    fn a_repository_can_declare_a_linear_history_merge_style() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, "[merge]\nmode = \"none\"\nstyle = \"squash\"\n").unwrap();
        let parsed = Config::load(&path).expect("config must load");
        assert_eq!(parsed.merge.style, MergeStyle::Squash);
    }

    #[test]
    fn later_layers_win_and_vars_render() {
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let project = dir.path().join("magi.toml");
        // The machine layer owns the roster...
        std::fs::write(
            &machine,
            "[[agents]]\nid = \"opus\"\nkind = \"claude\"\nmodel = \"opus\"\n\n\
             [graph]\ncandidates = 3\nmax_parallel = 8\n",
        )
        .unwrap();
        // ...and the project layer only states what is repo-specific, plus a
        // `[vars]` value interpolated into a command.
        std::fs::write(
            &project,
            "[vars]\ncache = \"/shared\"\n\n\
             [graph]\ncandidates = 2\n\n\
             [verify]\ngate = [\"CARGO_TARGET_DIR={{ vars.cache }}/t cargo test\"]\n",
        )
        .unwrap();

        let cfg = Config::load_layers(&[machine, project]).expect("layered load");
        assert_eq!(cfg.agents.len(), 1, "roster comes from the machine layer");
        assert_eq!(cfg.graph.implementers, 2, "project layer wins");
        assert_eq!(cfg.graph.max_parallel, 8, "machine layer survives");
        assert_eq!(
            cfg.verify.gate,
            ["CARGO_TARGET_DIR=/shared/t cargo test".to_owned()]
        );
        // The rendered command is where the cache path is read back from.
        assert_eq!(cfg.cache_dir(), Some(PathBuf::from("/shared/t")));
    }

    #[test]
    fn talk_defaults_to_an_hour_and_an_unwritten_config_still_gets_it() {
        // An operator who writes no `[graph]` timeout keys at all must still
        // land on the hour, not on the five/fifteen minutes this turn used
        // to hardcode before it read from config.
        let g = Graph::default();
        assert_eq!(g.timeout_talk, 3600);

        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, "[graph]\ncandidates = 2\n").unwrap();
        let cfg = Config::load(&path).expect("must load without timeout_talk set");
        assert_eq!(cfg.graph.timeout_talk, 3600);
    }

    #[test]
    fn an_overridden_talk_timeout_reaches_the_loaded_config() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, "[graph]\ntimeout_talk = 120\n").unwrap();
        let cfg = Config::load(&path).expect("must load");
        assert_eq!(cfg.graph.timeout_talk, 120);
    }

    #[test]
    fn the_disk_defaults_are_the_measurements_made_up_front() {
        let cfg = Config::default();
        assert_eq!(cfg.disk.min_free_bytes, 8 * 1024 * 1024 * 1024);
        assert!(cfg.disk.auto_fold);
        assert_eq!(cfg.disk.fold_grace_secs, 6 * 60 * 60);
        assert_eq!(cfg.disk.cache_limit_bytes, 10 * 1024 * 1024 * 1024);
    }

    #[test]
    fn an_unset_disk_section_is_the_safe_default() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("magi.toml"), "[graph]\ncandidates = 1\n").unwrap();
        let cfg = Config::load(&dir.path().join("magi.toml")).expect("load");
        assert_eq!(cfg.disk, Disk::default());
    }

    #[test]
    fn env_is_available_to_templates_with_a_default() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        // teravars ships no `env`; magi adds it, and the `default` filter has
        // to cover the unset case or every machine would need the variable.
        //
        // Deliberately no named variable: `env` is keyed by the exact spelling
        // the OS reports, and Windows says `Path` where POSIX says `PATH`, so a
        // test asserting `env.PATH` passes on one runner and fails on another.
        // The map's non-emptiness is the platform-neutral claim.
        std::fs::write(
            &path,
            "[verify]\n\
             gate = [\"cache={{ env.MAGI_TEST_UNSET_XYZ | default(value='fallback') }}\", \
             \"populated={{ env | length > 0 }}\"]\n",
        )
        .unwrap();
        let cfg = Config::load(&path).expect("env lookup must render");
        assert_eq!(cfg.verify.gate[0], "cache=fallback");
        assert_eq!(cfg.verify.gate[1], "populated=true");
    }

    #[test]
    fn a_broken_template_names_the_file() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, "[graph]\nlanguage = \"{{ nope.\"\n").unwrap();
        let err = Config::load(&path).expect_err("must not silently ignore");
        assert!(err.to_string().contains("teravars"), "{err}");
    }

    #[test]
    fn tera_syntax_in_comments_is_inert() {
        // teravars >= 0.2.2 strips `#` comments before Tera sees the file, so a
        // comment may quote template syntax without rendering. Before 0.2.2 this
        // load failed: the commented-out braces reached the template parser.
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(
            &path,
            "# a comment may quote templates: `{{ env.NOPE | default(value='x') }}` and `{% if %}`\n\
             [graph]\ncandidates = 2\n",
        )
        .unwrap();
        let cfg = Config::load(&path).expect("comments must be inert, not rendered");
        assert_eq!(cfg.graph.implementers, 2);
    }

    #[test]
    fn opencode_defaults_to_file_delivery() {
        let mut s = spec("oc");
        s.kind = AgentKind::Opencode;
        assert_eq!(s.delivery(), Delivery::File);
        s.prompt_delivery = Some(Delivery::Argv);
        assert_eq!(s.delivery(), Delivery::Argv);
    }
    #[test]
    fn the_land_loop_is_on_but_it_cannot_merge_without_being_asked() {
        // Both default on, and that pair is the safety property: `land` takes
        // over the watching an operator was doing by hand, `land_approval`
        // keeps the irreversible step a human decision. An unattended merge
        // needs BOTH flipped, which has to be chosen deliberately twice.
        let g = Graph::default();
        assert!(
            g.land,
            "stopping at an open PR left the watching to a human"
        );
        assert!(
            g.land_approval,
            "on-by-default land is only defensible while this is also on"
        );
        assert!(g.land_rounds > 0, "a loop with no budget never terminates");
        assert!(
            g.hold_contested_merge,
            "a contested hand-off must still reach a human when approvals are off"
        );
    }
    #[test]
    fn an_array_declared_in_two_layers_is_refused_instead_of_concatenated() {
        // teravars appends arrays. For an ordered list of seats, or an argv,
        // the concatenation is something neither file says - and the operator
        // pays for the extra seats by the token.
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[roles]\nimplementers = [\"a\", \"b\"]\n").unwrap();
        std::fs::write(&repo, "[roles]\nimplementers = [\"oc\"]\n").unwrap();

        let err = Config::load_layers(&[machine.clone(), repo.clone()])
            .expect_err("two layers naming one array must not merge silently")
            .to_string();
        assert!(err.contains("roles.implementers"), "{err}");
        // Both files are named: the fix is to delete one of them, and the
        // operator has to know which two to choose between.
        assert!(err.contains("machine.toml"), "{err}");
        assert!(err.contains("magi.toml"), "{err}");
    }

    #[test]
    fn a_scalar_in_one_layer_and_an_array_in_another_still_merges() {
        // The split the layering exists for: state a preference machine-wide,
        // let the repository own its own lists.
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[roles]\nchatter = \"opus\"\n").unwrap();
        std::fs::write(
            &repo,
            "[[agents]]\nid = \"oc\"\nkind = \"opencode\"\n\n\
             [roles]\nimplementers = [\"oc\"]\n",
        )
        .unwrap();

        let cfg = Config::load_layers(&[machine, repo]).expect("layers merge");
        assert_eq!(primary(cfg.roles.chatter.as_ref()), Some("opus"));
        assert_eq!(cfg.roles.implementers, ["oc"]);
        assert_eq!(cfg.agents.len(), 1, "the roster is not doubled");
    }

    #[test]
    fn two_layers_declaring_verify_gate_run_both_in_priority_order() {
        // The `editorconfig-checker` distribution problem: a shared layer
        // wants to add a gate command without erasing the repository's own.
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[verify]\ngate = [\"editorconfig-checker\"]\n").unwrap();
        std::fs::write(&repo, "[verify]\ngate = [\"cargo make check\"]\n").unwrap();

        let cfg = Config::load_layers(&[machine, repo]).expect("appendable arrays must merge");
        assert_eq!(
            cfg.verify.gate,
            [
                "editorconfig-checker".to_owned(),
                "cargo make check".to_owned()
            ],
            "low-priority (machine) command first, high-priority (repo) command after"
        );
    }

    #[test]
    fn two_layers_declaring_verify_e2e_run_both_in_priority_order() {
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[verify]\ne2e = [\"shared-smoke-test\"]\n").unwrap();
        std::fs::write(&repo, "[verify]\ne2e = [\"cargo test\"]\n").unwrap();

        let cfg = Config::load_layers(&[machine, repo]).expect("appendable arrays must merge");
        assert_eq!(
            cfg.verify.e2e,
            ["shared-smoke-test".to_owned(), "cargo test".to_owned()]
        );
    }

    #[test]
    fn two_layers_declaring_repos_roots_are_both_scanned() {
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[repos]\nroots = [\"/machine/root\"]\n").unwrap();
        std::fs::write(&repo, "[repos]\nroots = [\"/repo/root\"]\n").unwrap();

        let cfg = Config::load_layers(&[machine, repo]).expect("appendable arrays must merge");
        assert_eq!(
            cfg.repos.roots,
            [PathBuf::from("/machine/root"), PathBuf::from("/repo/root")]
        );
    }

    #[test]
    fn duplicate_gate_commands_across_layers_both_run() {
        // Dropping the duplicate would be a silent surprise; the operator
        // sees a slower gate, never a missing one.
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[verify]\ngate = [\"same-command\"]\n").unwrap();
        std::fs::write(&repo, "[verify]\ngate = [\"same-command\"]\n").unwrap();

        let cfg = Config::load_layers(&[machine, repo]).expect("appendable arrays must merge");
        assert_eq!(
            cfg.verify.gate,
            ["same-command".to_owned(), "same-command".to_owned()]
        );
    }

    #[test]
    fn notify_command_is_still_refused_across_two_layers() {
        // An argv, not a set: concatenating two of them is not a program.
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[notify]\ncommand = [\"ntfy\", \"publish\"]\n").unwrap();
        std::fs::write(&repo, "[notify]\ncommand = [\"curl\", \"-X\"]\n").unwrap();

        let err = Config::load_layers(&[machine.clone(), repo.clone()])
            .expect_err("an argv split across layers must not concatenate")
            .to_string();
        assert!(err.contains("notify.command"), "{err}");
        assert!(err.contains("machine.toml"), "{err}");
        assert!(err.contains("magi.toml"), "{err}");
    }

    #[test]
    fn one_layer_declaring_verify_gate_runs_unchanged() {
        // The classification must not change behaviour for the configuration
        // this very repository has today: exactly one layer names the gate.
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("magi.toml");
        std::fs::write(&path, "[verify]\ngate = [\"cargo make check\"]\n").unwrap();

        let cfg = Config::load(&path).expect("single layer must still load");
        assert_eq!(cfg.verify.gate, ["cargo make check".to_owned()]);
    }

    #[test]
    fn describe_composed_names_the_contributing_layers_only_when_there_are_two() {
        let dir = tempfile::tempdir().unwrap();
        let machine = dir.path().join("machine.toml");
        let repo = dir.path().join("magi.toml");
        std::fs::write(&machine, "[verify]\ngate = [\"editorconfig-checker\"]\n").unwrap();
        std::fs::write(&repo, "[verify]\ngate = [\"cargo make check\"]\n").unwrap();
        let paths = vec![machine.clone(), repo.clone()];

        let cfg = Config::load_layers(&paths).expect("appendable arrays must merge");
        let described =
            Config::describe_composed(&paths, &cfg.verify.gate, "verify.gate", "(none)");
        assert!(described.contains("editorconfig-checker && cargo make check"));
        assert!(
            described.contains(&machine.display().to_string()),
            "{described}"
        );
        assert!(
            described.contains(&repo.display().to_string()),
            "{described}"
        );

        // A single contributing layer stays the plain one-line summary.
        let single = vec![repo.clone()];
        let solo_cfg = Config::load_layers(&single).expect("single layer loads");
        let solo_described =
            Config::describe_composed(&single, &solo_cfg.verify.gate, "verify.gate", "(none)");
        assert_eq!(solo_described, "cargo make check");
    }

    mod remote_layers {
        use super::*;

        fn git(dir: &Path, args: &[&str]) {
            use crate::proc::Quiet as _;
            let out = std::process::Command::new("git")
                .args(args)
                .quiet()
                .current_dir(dir)
                .output()
                .unwrap();
            assert!(out.status.success(), "git {args:?}: {out:?}");
        }

        /// A checkout whose origin/main carries `remote` as magi.toml and whose
        /// working tree carries `disk`.
        fn fixture(remote: &str, disk: &str) -> (tempfile::TempDir, PathBuf) {
            let tmp = tempfile::tempdir().unwrap();
            let bare = tmp.path().join("o.git");
            git(tmp.path(), &["init", "--bare", "-b", "trunk", "o.git"]);
            let repo = tmp.path().join("repo");
            std::fs::create_dir_all(&repo).unwrap();
            git(&repo, &["init", "-b", "trunk"]);
            git(&repo, &["config", "user.name", "t"]);
            git(&repo, &["config", "user.email", "t@example.com"]);
            std::fs::write(repo.join("magi.toml"), remote).unwrap();
            git(&repo, &["add", "-A"]);
            git(&repo, &["commit", "-m", "x"]);
            git(&repo, &["remote", "add", "origin", &bare.to_string_lossy()]);
            git(&repo, &["push", "origin", "trunk"]);
            git(&repo, &["fetch", "origin"]);
            git(&repo, &["remote", "set-head", "origin", "trunk"]);
            std::fs::write(repo.join("magi.toml"), disk).unwrap();
            (tmp, repo)
        }

        #[test]
        fn reads_the_remote_blob_not_the_working_tree() {
            let (_t, repo) = fixture("[graph]\ncandidates = 2\n", "[graph]\ncandidates = 5\n");
            let (cfg, _) = Config::discover(&repo, None).unwrap();
            assert_eq!(cfg.graph.implementers, 2);
        }

        #[test]
        fn detached_head_still_reads_the_remote() {
            let (_t, repo) = fixture("[graph]\ncandidates = 2\n", "[graph]\ncandidates = 5\n");
            git(&repo, &["checkout", "--detach"]);
            let (cfg, _) = Config::discover(&repo, None).unwrap();
            assert_eq!(cfg.graph.implementers, 2);
        }

        #[test]
        fn a_missing_ref_is_an_error_not_a_fallback() {
            let (_t, repo) = fixture("[graph]\ncandidates = 2\n", "[graph]\ncandidates = 5\n");
            git(&repo, &["update-ref", "-d", "refs/remotes/origin/trunk"]);
            let err = format!("{:#}", Config::discover(&repo, None).unwrap_err());
            assert!(err.contains("origin"), "{err}");
        }

        #[test]
        fn merge_base_in_the_checkout_locates_the_ref() {
            let (_t, repo) = fixture("[graph]\ncandidates = 2\n", "[merge]\nbase = \"nope\"\n");
            assert!(Config::discover(&repo, None).is_err());
        }

        #[test]
        fn the_magi_dir_layer_is_read_too() {
            let (_t, repo) = fixture("[graph]\ncandidates = 2\n", "");
            std::fs::write(repo.join("magi.toml"), "[graph]\ncandidates = 2\n").unwrap();
            std::fs::create_dir_all(repo.join(".magi")).unwrap();
            std::fs::write(repo.join(".magi/config.toml"), "[graph]\njudges = 3\n").unwrap();
            git(&repo, &["add", "-A"]);
            git(&repo, &["commit", "-m", "y"]);
            git(&repo, &["push", "origin", "trunk"]);
            git(&repo, &["fetch", "origin"]);
            let (cfg, layers) = Config::discover(&repo, None).unwrap();
            assert_eq!((cfg.graph.implementers, cfg.graph.judges), (2, 3));
            assert_eq!(layers.len(), 2);
        }

        #[test]
        fn an_include_in_a_repository_layer_resolves_against_the_same_commit() {
            let (_t, repo) = fixture("include = [\"gate.toml\"]\n", "");
            std::fs::write(repo.join("magi.toml"), "include = [\"gate.toml\"]\n").unwrap();
            std::fs::write(repo.join("gate.toml"), "[graph]\ncandidates = 2\n").unwrap();
            git(&repo, &["add", "-A"]);
            git(&repo, &["commit", "-m", "inc"]);
            git(&repo, &["push", "origin", "trunk"]);
            git(&repo, &["fetch", "origin"]);
            // The working tree's copy differs and must not be used.
            std::fs::write(repo.join("gate.toml"), "[graph]\ncandidates = 9\n").unwrap();
            let (cfg, _) = Config::discover(&repo, None).unwrap();
            assert_eq!(cfg.graph.implementers, 2);
        }

        #[test]
        fn a_machine_layer_base_is_rendered_before_locating_the_ref() {
            let (t, repo) = fixture("[graph]\ncandidates = 2\n", "[merge]\nbase = \"nope\"\n");
            let m = t.path().join("machine.toml");
            std::fs::write(
                &m,
                "[merge]\nbase = \"{{ env.MAGI_TEST_NO_SUCH | default(value='trunk') }}\"\n",
            )
            .unwrap();
            let (remote, base) = {
                let probe = probe_merge(&m, &repo).unwrap();
                (probe.remote, probe.base)
            };
            assert_eq!((remote, base), (None, Some("trunk".to_owned())));
        }

        #[test]
        fn a_machine_layer_base_sees_the_checkouts_repo_name() {
            let (t, repo) = fixture("[graph]\ncandidates = 2\n", "");
            let m = t.path().join("machine.toml");
            std::fs::write(&m, "[merge]\nbase = \"{{ repo_name }}\"\n").unwrap();
            let probe = probe_merge(&m, &repo).unwrap();
            assert_eq!(probe.base.as_deref(), Some("repo"));
        }

        #[test]
        fn every_include_form_is_recognised() {
            assert!(declares_include("include = [\"a.toml\"]\n"));
            assert!(declares_include("\"include\" = [\"a.toml\"]\n"));
            assert!(declares_include("teravars = { include = [\"a.toml\"] }\n"));
            assert!(declares_include("[teravars]\ninclude = [\"a.toml\"]\n"));
            assert!(!declares_include("[graph]\ncandidates = 2\n"));
        }

        #[test]
        fn an_explicit_config_is_read_as_named() {
            let (t, repo) = fixture("[graph]\ncandidates = 2\n", "");
            let own = t.path().join("own.toml");
            std::fs::write(&own, "[graph]\ncandidates = 4\n").unwrap();
            let (cfg, _) = Config::discover(&repo, Some(&own)).unwrap();
            assert_eq!(cfg.graph.implementers, 4);
        }

        #[test]
        fn discover_fetched_fails_when_the_fetch_does() {
            let (t, repo) = fixture("[graph]\ncandidates = 2\n", "");
            std::fs::remove_dir_all(t.path().join("o.git")).unwrap();
            let rt = tokio::runtime::Builder::new_current_thread()
                .enable_all()
                .build()
                .unwrap();
            let err = rt
                .block_on(Config::discover_fetched(&repo, None))
                .unwrap_err();
            assert!(format!("{err:#}").contains("fetch"), "{err:#}");
        }

        #[test]
        fn discover_fetched_survives_a_fetch_that_leaves_no_origin_head() {
            // Never-fetched remote + followRemoteHEAD=never: fetch creates
            // origin/trunk but not origin/HEAD, which discovery then re-reads.
            let (_t, repo) = fixture("[graph]\ncandidates = 2\n", "");
            git(&repo, &["remote", "set-head", "origin", "-d"]);
            git(&repo, &["update-ref", "-d", "refs/remotes/origin/trunk"]);
            git(
                &repo,
                &["config", "remote.origin.followRemoteHEAD", "never"],
            );
            let rt = tokio::runtime::Builder::new_current_thread()
                .enable_all()
                .build()
                .unwrap();
            let (cfg, _) = rt.block_on(Config::discover_fetched(&repo, None)).unwrap();
            assert_eq!(cfg.graph.implementers, 2);
        }

        #[test]
        fn a_non_git_directory_reads_its_files() {
            let dir = tempfile::tempdir().unwrap();
            std::fs::write(dir.path().join("magi.toml"), "[graph]\ncandidates = 4\n").unwrap();
            let (cfg, _) = Config::discover(dir.path(), None).unwrap();
            assert_eq!(cfg.graph.implementers, 4);
        }
    }
}