magi/

settings.rs

//! The machine-config settings screen: which agent each role resolves to, and
//! a safe way to change those assignments.
//!
//! Reading goes through [`Config::load_layers`] like every other consumer, so
//! the screen shows what a run started now would see. Writing touches **one
//! file, the machine layer**, whose path is resolved here from
//! [`Config::machine_layer`] (or injected by a test) and never taken from the
//! client - a repository's `magi.toml` cannot become a write target.
//!
//! `toml_edit` is not a dependency, so the write is a line-level patch of the
//! `[roles]` table: every byte outside the keys being changed (comments,
//! `[vars]`, Tera expressions, other tables) is carried over untouched. The
//! patch is only a proposal. It is written to a temporary file beside the
//! original, the layered config is re-loaded with that file standing in for
//! the machine layer, and the result must say exactly what was asked for
//! before the original is replaced by a rename. Anything the line patcher
//! cannot place (an inline `roles = { .. }`, say) fails that check and is
//! refused with a readable message instead of being guessed at.
//!
//! The machine file applies to every repository, so two more rules hold. The
//! detected roster is never written down (`Config::load_layers` fills `agents`
//! from `PATH` whenever no layer declares the key), so a role save adds no
//! second `[[agents]]` declaration and CLIs installed later are still found.
//! And a save is also loaded against every other checkout found under
//! `[repos] roots`: one that loaded before and would not now (it declares the
//! same `roles.*` key) refuses the save in words. Limits: checkouts outside
//! `roots` are not checked, a checkout already broken is ignored, and another
//! process editing a repo config between the check and the rename is not
//! prevented. The view shows the same lock up front.

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use std::sync::Mutex;

use serde::Serialize;

use crate::config::{AgentChoice, AgentSpec, Config};

/// The `[roles]` keys the screen edits, in display order.
pub(crate) const ROLE_KEYS: [&str; 10] = [
    "implementers",
    "judges",
    "reviewers",
    "advisors",
    "synthesizer",
    "fixer",
    "chatter",
    "conductor",
    "language_judge",
    "dupes_judge",
];

/// The roles that take one id as a bare string and several as a chain.
fn is_chain_role(key: &str) -> bool {
    matches!(
        key,
        "synthesizer" | "fixer" | "chatter" | "conductor" | "language_judge" | "dupes_judge"
    )
}

/// Serializes saves: a read-modify-write of one file is not safe to interleave.
static SAVE_LOCK: Mutex<()> = Mutex::new(());

/// What `GET /api/settings` returns.
#[derive(Debug, Serialize)]
pub(crate) struct SettingsView {
    /// The repository the effective config was resolved against.
    pub(crate) repo: String,
    pub(crate) machine: MachineView,
    /// Fingerprint of the machine file's bytes; a save must quote it.
    pub(crate) revision: String,
    /// Set when the layered config does not load. `roles` and `agents` are
    /// then empty *because nothing could be read*, and the screen says so.
    pub(crate) error: Option<ConfigError>,
    pub(crate) roles: Vec<RoleView>,
    pub(crate) agents: Vec<AgentView>,
}

#[derive(Debug, Serialize)]
pub(crate) struct MachineView {
    /// Where a save would write, when there is such a place.
    pub(crate) path: Option<String>,
    pub(crate) exists: bool,
    /// Why nothing can be saved, when that is so.
    pub(crate) unavailable: Option<String>,
}

#[derive(Debug, Serialize)]
pub(crate) struct ConfigError {
    pub(crate) message: String,
    /// The layer that fails on its own, when one does.
    pub(crate) path: Option<String>,
}

#[derive(Debug, Serialize)]
pub(crate) struct RoleView {
    pub(crate) key: &'static str,
    /// Whether ids form an ordered fallback chain rather than a seat roster.
    pub(crate) chain: bool,
    /// The ids the config names, in order; unset and explicit empty both have no ids.
    pub(crate) configured: Vec<String>,
    /// `machine`, `repo` or `default`.
    pub(crate) source: &'static str,
    pub(crate) source_path: Option<String>,
    /// Whether a machine-file save can change what a run sees.
    pub(crate) editable: bool,
    pub(crate) locked_reason: Option<String>,
    /// The inherited role or behavior when this role is unset.
    pub(crate) fallback: Option<&'static str>,
    /// The seats a run started now would fill, in order.
    pub(crate) seats: Vec<String>,
    pub(crate) seats_error: Option<String>,
    /// Chain ids that cannot run here (not in the roster, or not installed).
    pub(crate) skipped: Vec<String>,
    /// The `[graph]` seat count, for the four roster roles only.
    pub(crate) count: Option<CountView>,
}

/// The number of seats a roster role fills (`[graph]`), and how it relates to
/// the roster: seats beyond the count are the ordered backup list that
/// `graph::pick_successor` walks when a seat's agent fails.
#[derive(Debug, Serialize)]
pub(crate) struct CountView {
    pub(crate) value: usize,
    /// Lowest value a save accepts: `0` for advisors (the design stage is
    /// skipped), `1` otherwise.
    pub(crate) min: usize,
    /// The `[graph]` key a save writes (`candidates` when the machine file
    /// already spells implementers that way).
    pub(crate) file_key: &'static str,
    /// `machine`, `repo` or `default`.
    pub(crate) source: &'static str,
    pub(crate) source_path: Option<String>,
    pub(crate) editable: bool,
    pub(crate) locked_reason: Option<String>,
    /// Length of the untruncated roster; `None` when roles do not resolve.
    pub(crate) roster_len: Option<usize>,
    /// `roster_len - value`, never below zero; `None` with `roster_len`.
    pub(crate) backups: Option<usize>,
}

/// The four roles that have a seat count, with the `[graph]` spellings of it.
const COUNT_KEYS: [&str; 4] = ["implementers", "judges", "reviewers", "advisors"];

fn count_spellings(key: &str) -> &'static [&'static str] {
    match key {
        "implementers" => &["implementers", "candidates"],
        "judges" => &["judges"],
        "reviewers" => &["reviewers"],
        _ => &["advisors"],
    }
}

fn count_min(key: &str) -> usize {
    usize::from(key != "advisors")
}

fn graph_count(cfg: &Config, key: &str) -> usize {
    match key {
        "implementers" => cfg.graph.implementers,
        "judges" => cfg.graph.judges,
        "reviewers" => cfg.graph.reviewers,
        _ => cfg.graph.advisors,
    }
}

fn declares_count(table: &toml::Table, key: &str) -> bool {
    table
        .get("graph")
        .and_then(toml::Value::as_table)
        .is_some_and(|g| count_spellings(key).iter().any(|k| g.contains_key(*k)))
}

#[derive(Debug, Serialize)]
pub(crate) struct AgentView {
    pub(crate) id: String,
    pub(crate) kind: String,
    pub(crate) model: Option<String>,
    /// `machine`, `repo` or `detected` (found on `PATH`, written by nobody).
    pub(crate) source: &'static str,
    pub(crate) source_path: Option<String>,
}

/// Why a save did not happen.
#[derive(Debug)]
pub(crate) enum SaveError {
    /// The machine file changed since the client read it.
    Conflict(String),
    /// The request or the resulting config is not acceptable.
    Refused(String),
    /// The disk said no.
    Internal(String),
}

/// FNV-1a of the file's bytes, hex. Same function family as `notices::id_of`.
fn fingerprint(bytes: &[u8]) -> String {
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
    for b in bytes {
        hash ^= u64::from(*b);
        hash = hash.wrapping_mul(0x0100_0000_01b3);
    }
    format!("{hash:016x}")
}

fn repo_layers(repo: &Path) -> Vec<PathBuf> {
    Config::repo_layers(repo).unwrap_or_else(|e| {
        tracing::warn!("could not read the repository's config layers: {e:#}");
        Vec::new()
    })
}

/// Every layer that applies to `repo` itself, machine first; an unreadable
/// remote ref is an error, never an empty list (settings for an unknown config
/// must not be editable).
fn layer_paths_strict(repo: &Path, machine: Option<&Path>) -> anyhow::Result<Vec<PathBuf>> {
    let mut paths: Vec<PathBuf> = machine
        .filter(|m| m.is_file())
        .map(Path::to_path_buf)
        .into_iter()
        .collect();
    paths.extend(Config::repo_layers(repo)?);
    Ok(paths)
}

/// Every layer that applies, machine first - [`Config::layers`] with the
/// machine path injected. Lenient: for *other* checkouts, whose own failures
/// are not this screen's business.
fn layer_paths(repo: &Path, machine: Option<&Path>) -> Vec<PathBuf> {
    let mut paths: Vec<PathBuf> = machine
        .filter(|m| m.is_file())
        .map(Path::to_path_buf)
        .into_iter()
        .collect();
    paths.extend(repo_layers(repo));
    paths
}

fn effective(paths: &[PathBuf]) -> anyhow::Result<Config> {
    if paths.is_empty() {
        return Ok(Config::autodetected());
    }
    Config::load_layers(paths)
}

fn declares(table: &toml::Table, key: &str) -> bool {
    table
        .get("roles")
        .and_then(toml::Value::as_table)
        .is_some_and(|r| r.contains_key(key))
}

fn key_name(key: &str) -> &'static str {
    COUNT_KEYS
        .iter()
        .find(|k| **k == key)
        .copied()
        .unwrap_or("")
}

fn choice_ids(choice: Option<&AgentChoice>) -> Vec<String> {
    choice
        .map(|c| c.ids().into_iter().map(str::to_owned).collect())
        .unwrap_or_default()
}

fn role_ids(cfg: &Config, key: &str) -> Vec<String> {
    match key {
        "implementers" => cfg.roles.implementers.clone(),
        "judges" => cfg.roles.judges.clone(),
        "reviewers" => cfg.roles.reviewers.clone(),
        "advisors" => cfg.roles.advisors.clone(),
        key if is_chain_role(key) => choice_ids(chain_choice(cfg, key)),
        _ => unreachable!("unknown settings role: {key}"),
    }
}

fn chain_choice<'a>(cfg: &'a Config, key: &str) -> Option<&'a AgentChoice> {
    match key {
        "synthesizer" => cfg.roles.synthesizer.as_ref(),
        "fixer" => cfg.roles.fixer.as_ref(),
        "chatter" => cfg.roles.chatter.as_ref(),
        "conductor" => cfg.roles.conductor.as_ref(),
        "language_judge" => cfg.roles.language_judge.as_ref(),
        "dupes_judge" => cfg.roles.dupes_judge.as_ref(),
        _ => unreachable!("unknown chain role: {key}"),
    }
}

fn chain_seats(
    cfg: &Config,
    choice: Option<&AgentChoice>,
    view: &mut RoleView,
) -> anyhow::Result<Vec<String>> {
    let seats = crate::agent::pick_chain(&cfg.agents, choice, &crate::agent::installed, view.key)
        .map(|chain| ids_of(&chain));
    let runnable = seats.as_ref().cloned().unwrap_or_default();
    view.skipped = choice_ids(choice)
        .into_iter()
        .filter(|id| !runnable.contains(id))
        .collect();
    seats
}

fn ids_of(specs: &[AgentSpec]) -> Vec<String> {
    specs.iter().map(|s| s.id.clone()).collect()
}

/// The effective roles and roster for `repo`, with the machine layer at
/// `machine`.
pub(crate) fn view(repo: &Path, machine: Option<&Path>) -> SettingsView {
    let bytes = machine
        .and_then(|m| std::fs::read(m).ok())
        .unwrap_or_default();
    let mut out = SettingsView {
        repo: repo.display().to_string(),
        machine: MachineView {
            path: machine.map(|m| m.display().to_string()),
            exists: machine.is_some_and(Path::is_file),
            unavailable: machine.is_none().then(|| {
                "This machine has no machine-config location (the config directory is \
                 unset or empty), so nothing can be saved from here."
                    .to_owned()
            }),
        },
        revision: fingerprint(&bytes),
        error: None,
        roles: Vec::new(),
        agents: Vec::new(),
    };
    let paths = match layer_paths_strict(repo, machine) {
        Ok(p) => p,
        Err(e) => {
            out.error = Some(ConfigError {
                message: format!("{e:#}"),
                path: None,
            });
            return out;
        }
    };
    let cfg = match effective(&paths) {
        Ok(cfg) => cfg,
        Err(e) => {
            let failing = Config::layer_tables(&paths)
                .into_iter()
                .find(|(_, t)| t.is_err())
                .map(|(p, _)| p.display().to_string());
            out.error = Some(ConfigError {
                message: format!("{e:#}"),
                path: failing,
            });
            return out;
        }
    };
    let tables: Vec<(PathBuf, toml::Table)> = Config::layer_tables(&paths)
        .into_iter()
        .filter_map(|(p, t)| t.ok().map(|t| (p, t)))
        .collect();
    let is_machine = |p: &Path| machine.is_some_and(|m| m == p);

    let mut other_declares: BTreeMap<&str, String> = BTreeMap::new();
    for other in other_checkouts(repo, &cfg.repos.roots) {
        let theirs = Config::layer_tables(&repo_layers(&other.path));
        for key in ROLE_KEYS {
            if theirs
                .iter()
                .any(|(_, t)| t.as_ref().is_ok_and(|t| declares(t, key)))
            {
                other_declares
                    .entry(key)
                    .or_insert_with(|| other.name.clone());
            }
        }
    }
    let resolved = cfg.resolve_roles();
    let advisors = cfg.advisors();
    for key in ROLE_KEYS {
        let configured = role_ids(&cfg, key);
        let owner = tables.iter().rev().find(|(_, t)| declares(t, key));
        let (source, source_path) = match owner {
            Some((p, _)) if is_machine(p) => ("machine", Some(p.display().to_string())),
            Some((p, _)) => ("repo", Some(p.display().to_string())),
            None => ("default", None),
        };
        let repo_owner = tables
            .iter()
            .find(|(p, t)| !is_machine(p) && declares(t, key));
        let (editable, locked_reason) = if let Some((p, _)) = repo_owner {
            (
                false,
                Some(format!(
                    "This repo overrides roles.{key} in {} - edit it there.",
                    p.display()
                )),
            )
        } else if let Some(name) = other_declares.get(key) {
            (
                false,
                Some(format!(
                    "`{name}` declares roles.{key} in its own config, so a machine setting \
                     would stop it from loading. Edit it there."
                )),
            )
        } else if machine.is_none() {
            (false, out.machine.unavailable.clone())
        } else {
            (true, None)
        };
        let mut view = RoleView {
            key,
            chain: is_chain_role(key),
            configured,
            source,
            source_path,
            editable,
            locked_reason,
            fallback: None,
            seats: Vec::new(),
            seats_error: None,
            skipped: Vec::new(),
            count: None,
        };
        if COUNT_KEYS.contains(&key) {
            let owner = tables.iter().rev().find(|(_, t)| declares_count(t, key));
            let (source, source_path) = match owner {
                Some((p, _)) if is_machine(p) => ("machine", Some(p.display().to_string())),
                Some((p, _)) => ("repo", Some(p.display().to_string())),
                None => ("default", None),
            };
            let repo_owner = tables
                .iter()
                .find(|(p, t)| !is_machine(p) && declares_count(t, key));
            let (editable, locked_reason) = if let Some((p, _)) = repo_owner {
                (
                    false,
                    Some(format!(
                        "This repo overrides graph.{key} in {} - edit it there.",
                        p.display()
                    )),
                )
            } else if machine.is_none() {
                (false, out.machine.unavailable.clone())
            } else {
                (true, None)
            };
            let file_key = tables
                .iter()
                .find(|(p, _)| is_machine(p))
                .and_then(|(_, t)| t.get("graph").and_then(toml::Value::as_table))
                .filter(|g| key == "implementers" && g.contains_key("candidates"))
                .map_or(key_name(key), |_| "candidates");
            let roster_len = resolved.as_ref().ok().map(|r| match key {
                "implementers" => r.implementer_roster.len(),
                "judges" => r.judge_roster.len(),
                _ => r.reviewer_roster.len(),
            });
            let roster_len = if key == "advisors" {
                cfg.advisor_roster().ok().map(|r| r.len())
            } else {
                roster_len
            };
            let value = graph_count(&cfg, key);
            view.count = Some(CountView {
                value,
                min: count_min(key),
                file_key,
                source,
                source_path,
                editable,
                locked_reason,
                roster_len,
                backups: roster_len.map(|n| n.saturating_sub(value)),
            });
        }
        let seats = match key {
            "implementers" => resolved
                .as_ref()
                .map(|r| ids_of(&r.implementers))
                .map_err(|e| anyhow::anyhow!("{e:#}")),
            "judges" => resolved
                .as_ref()
                .map(|r| ids_of(&r.judges))
                .map_err(|e| anyhow::anyhow!("{e:#}")),
            "reviewers" => resolved
                .as_ref()
                .map(|r| ids_of(&r.reviewers))
                .map_err(|e| anyhow::anyhow!("{e:#}")),
            "advisors" => {
                if view.configured.is_empty() {
                    view.fallback = Some("judges");
                }
                advisors
                    .as_ref()
                    .map(|a| ids_of(a))
                    .map_err(|e| anyhow::anyhow!("{e:#}"))
            }
            // Unset keeps the winner's own author: no chain to show.
            "fixer" if cfg.roles.fixer.is_none() => {
                view.fallback = Some("winner's implementer");
                Ok(Vec::new())
            }
            "language_judge" if cfg.roles.language_judge.is_none() => {
                view.fallback = Some("built-in heuristics");
                Ok(Vec::new())
            }
            "dupes_judge" => {
                if cfg.roles.dupes_judge.is_none() {
                    view.fallback = Some("chatter");
                }
                chain_seats(
                    &cfg,
                    cfg.roles
                        .dupes_judge
                        .as_ref()
                        .or(cfg.roles.chatter.as_ref()),
                    &mut view,
                )
            }
            // Like conduct::maybe_run, only a multi-id conductor choice preflights CLIs.
            "conductor"
                if cfg
                    .roles
                    .conductor
                    .as_ref()
                    .is_none_or(|c| c.ids().len() <= 1) =>
            {
                let seats = resolved
                    .as_ref()
                    .map(|r| vec![r.conductor.id.clone()])
                    .map_err(|e| anyhow::anyhow!("{e:#}"));
                if seats.is_err() {
                    view.skipped = view.configured.clone();
                }
                seats
            }
            "fixer" | "synthesizer" | "chatter" | "conductor" | "language_judge" => {
                chain_seats(&cfg, chain_choice(&cfg, key), &mut view)
            }
            _ => unreachable!("unknown settings role: {key}"),
        };
        match seats {
            Ok(ids) => view.seats = ids,
            Err(e) => view.seats_error = Some(format!("{e:#}")),
        }
        out.roles.push(view);
    }

    out.agents = cfg
        .agents
        .iter()
        .map(|a| {
            let owner = tables.iter().rev().find(|(_, t)| {
                t.get("agents")
                    .and_then(toml::Value::as_array)
                    .is_some_and(|list| {
                        list.iter()
                            .any(|x| x.get("id").and_then(toml::Value::as_str) == Some(&a.id))
                    })
            });
            let (source, source_path) = match owner {
                Some((p, _)) if is_machine(p) => ("machine", Some(p.display().to_string())),
                Some((p, _)) => ("repo", Some(p.display().to_string())),
                None => ("detected", None),
            };
            AgentView {
                id: a.id.clone(),
                kind: toml::Value::try_from(a.kind)
                    .ok()
                    .and_then(|v| v.as_str().map(str::to_owned))
                    .unwrap_or_default(),
                model: a.model.clone(),
                source,
                source_path,
            }
        })
        .collect();
    out
}

/// Replace the given `[roles]` keys in the machine file at `machine`.
///
/// `roles` maps a key to its new ids; an empty list removes the key (back to
/// the default). Keys not named are left exactly as they are.
pub(crate) fn save(
    repo: &Path,
    machine: Option<&Path>,
    revision: &str,
    roles: &BTreeMap<String, Vec<String>>,
    counts: &BTreeMap<String, serde_json::Value>,
) -> Result<SettingsView, SaveError> {
    let _guard = SAVE_LOCK.lock().unwrap_or_else(|p| p.into_inner());
    let Some(machine) = machine else {
        return Err(SaveError::Refused(
            "This machine has no machine-config location, so there is nowhere to save to."
                .to_owned(),
        ));
    };
    let current = view(repo, Some(machine));
    if let Some(err) = &current.error {
        return Err(SaveError::Refused(format!(
            "The current config does not load, so it cannot be edited safely: {}",
            err.message
        )));
    }
    if current.revision != revision {
        return Err(SaveError::Conflict(
            "The machine config changed since this screen loaded it. Reload and apply \
             the change again."
                .to_owned(),
        ));
    }
    if roles.is_empty() && counts.is_empty() {
        return Err(SaveError::Refused("Nothing to change.".to_owned()));
    }
    let known: Vec<&str> = current.agents.iter().map(|a| a.id.as_str()).collect();
    let mut edits: Vec<(&'static str, Vec<String>)> = Vec::new();
    for (key, ids) in roles {
        let Some(role) = current.roles.iter().find(|r| r.key == key) else {
            return Err(SaveError::Refused(format!(
                "`{key}` is not a role this screen edits."
            )));
        };
        if !role.editable {
            return Err(SaveError::Refused(
                role.locked_reason
                    .clone()
                    .unwrap_or_else(|| format!("`{key}` cannot be edited here.")),
            ));
        }
        let ids: Vec<String> = ids.iter().map(|i| i.trim().to_owned()).collect();
        if let Some(bad) = ids
            .iter()
            .find(|i| i.is_empty() || !known.contains(&i.as_str()))
        {
            return Err(SaveError::Refused(format!(
                "`{bad}` is not a defined agent. Defined: {}.",
                known.join(", ")
            )));
        }
        edits.push((role.key, ids));
    }
    let mut count_edits: Vec<(&'static str, &'static str, usize)> = Vec::new();
    for (key, raw) in counts {
        let Some(count) = current
            .roles
            .iter()
            .find(|r| r.key == key)
            .and_then(|r| r.count.as_ref())
        else {
            return Err(SaveError::Refused(format!(
                "`{key}` has no seat count this screen edits."
            )));
        };
        if !count.editable {
            return Err(SaveError::Refused(
                count
                    .locked_reason
                    .clone()
                    .unwrap_or_else(|| format!("The `{key}` seat count cannot be edited here.")),
            ));
        }
        let Some(n) = raw.as_u64().and_then(|n| usize::try_from(n).ok()) else {
            return Err(SaveError::Refused(format!(
                "The {key} seat count must be a whole number, got {raw}."
            )));
        };
        if n < count.min {
            return Err(SaveError::Refused(format!(
                "The {key} seat count must be at least {}, got {n}.",
                count.min
            )));
        }
        count_edits.push((key_name(key), count.file_key, n));
    }

    let original = match std::fs::read_to_string(machine) {
        Ok(text) => text,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => String::new(),
        Err(e) => {
            return Err(SaveError::Internal(format!(
                "reading {}: {e}",
                machine.display()
            )));
        }
    };
    let mut text = original.clone();
    for (key, ids) in &edits {
        text = patch_role(&text, key, ids).map_err(SaveError::Refused)?;
    }
    for (key, file_key, n) in &count_edits {
        text = patch_count(&text, file_key, key, *n).map_err(SaveError::Refused)?;
    }
    let dir = machine
        .parent()
        .ok_or_else(|| SaveError::Internal("the machine config has no parent directory".into()))?;
    std::fs::create_dir_all(dir)
        .map_err(|e| SaveError::Internal(format!("creating {}: {e}", dir.display())))?;
    let nonce = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |d| d.as_nanos());
    let tmp = dir.join(format!(".config.toml.{}.{nonce}.tmp", std::process::id()));
    let cleanup = |e: SaveError| {
        let _ = std::fs::remove_file(&tmp);
        e
    };
    write_synced(&tmp, &text).map_err(|e| {
        cleanup(SaveError::Internal(format!(
            "writing {}: {e}",
            tmp.display()
        )))
    })?;

    // Validate the real thing: the layered load with the proposal standing in
    // for the machine file.
    let mut layers = vec![tmp.clone()];
    match Config::repo_layers(repo) {
        Ok(l) => layers.extend(l),
        Err(e) => {
            return Err(cleanup(SaveError::Refused(format!(
                "The repository's config cannot be read, so nothing was saved: {e:#}"
            ))));
        }
    }
    let loaded = Config::load_layers(&layers).map_err(|e| {
        cleanup(SaveError::Refused(format!(
            "The change would leave the config unloadable, so nothing was saved: {e:#}"
        )))
    })?;
    for (key, ids) in &edits {
        let got = role_ids(&loaded, key);
        if &got != ids {
            return Err(cleanup(SaveError::Refused(format!(
                "The change would not take effect as asked: `{key}` would resolve to [{}] \
                 instead of [{}] (an include or a template in the machine file overrides \
                 it). Nothing was saved.",
                got.join(", "),
                ids.join(", ")
            ))));
        }
    }
    for (key, _, n) in &count_edits {
        let got = graph_count(&loaded, key);
        if got != *n {
            return Err(cleanup(SaveError::Refused(format!(
                "The change would not take effect as asked: the {key} seat count would be \
                 {got} instead of {n} (an include or a template in the machine file \
                 overrides it). Nothing was saved."
            ))));
        }
    }
    other_repos_still_load(repo, machine, &tmp, &loaded.repos.roots).map_err(cleanup)?;
    std::fs::rename(&tmp, machine).map_err(|e| {
        cleanup(SaveError::Internal(format!(
            "replacing {}: {e}",
            machine.display()
        )))
    })?;
    Ok(view(repo, Some(machine)))
}

/// Every checkout under `roots` other than `repo` that has its own config
/// layers.
fn other_checkouts(repo: &Path, roots: &[PathBuf]) -> Vec<crate::repos::Repo> {
    let here = repo.canonicalize().unwrap_or_else(|_| repo.to_path_buf());
    crate::repos::scan(roots)
        .into_iter()
        .filter(|r| r.path != here && !repo_layers(&r.path).is_empty())
        .collect()
}

/// The machine file applies to every repository, so a proposal is checked
/// against each other known checkout too: one that loaded with the old machine
/// file and no longer loads with `proposal` (a `roles.*` array now declared in
/// two layers) refuses the save. A checkout that did not load before is not
/// this change's doing and is ignored.
fn other_repos_still_load(
    repo: &Path,
    machine: &Path,
    proposal: &Path,
    roots: &[PathBuf],
) -> Result<(), SaveError> {
    for other in other_checkouts(repo, roots) {
        let layers = repo_layers(&other.path);
        let mut old = layer_paths(&other.path, Some(machine));
        if old.is_empty() {
            old = layers.clone();
        }
        if Config::load_layers(&old).is_err() {
            continue;
        }
        let mut new = vec![proposal.to_path_buf()];
        new.extend(layers);
        if let Err(e) = Config::load_layers(&new) {
            return Err(SaveError::Refused(format!(
                "Nothing was saved: this machine setting would stop `{}` from loading, \
                 because that repository declares the same setting in its own config \
                 ({e:#}). Edit it there, or remove it from that repository first.",
                other.name
            )));
        }
    }
    Ok(())
}

fn write_synced(path: &Path, text: &str) -> std::io::Result<()> {
    use std::io::Write;
    let mut f = std::fs::File::create(path)?;
    f.write_all(text.as_bytes())?;
    f.sync_all()
}

fn quote(s: &str) -> String {
    toml::Value::String(s.to_owned()).to_string()
}

/// The value text for `key`: a bare string for a one-agent chain role
/// or an array for several ids; roster roles always use arrays.
fn value_text(key: &str, ids: &[String]) -> String {
    if is_chain_role(key) && ids.len() == 1 {
        return quote(&ids[0]);
    }
    let items: Vec<String> = ids.iter().map(|i| quote(i)).collect();
    format!("[{}]", items.join(", "))
}

/// Lexer state carried from one line to the next: bracket depth, and the
/// delimiter of a multi-line string still open at the end of the last line.
#[derive(Default)]
struct Scan {
    depth: i32,
    multi: Option<&'static str>,
}

impl Scan {
    fn open(&self) -> bool {
        self.depth > 0 || self.multi.is_some()
    }
}

/// Walk one line, tracking bracket depth outside strings and any multi-line
/// string that opens or closes on it. Returns the byte offset of a trailing
/// comment, if any.
fn scan_line(line: &str, st: &mut Scan) -> Option<usize> {
    let b = line.as_bytes();
    let mut quote: Option<u8> = None;
    let mut escaped = false;
    let mut i = 0;
    while i < b.len() {
        if let Some(delim) = st.multi {
            if b[i..].starts_with(delim.as_bytes()) {
                st.multi = None;
                i += 3;
            } else if delim == "\"\"\"" && b[i] == b'\\' {
                i += 2;
            } else {
                i += 1;
            }
            continue;
        }
        let c = b[i];
        match quote {
            Some(b'"') if escaped => escaped = false,
            Some(b'"') if c == b'\\' => escaped = true,
            Some(q) if c == q => quote = None,
            Some(_) => {}
            None => {
                if b[i..].starts_with(b"\"\"\"") {
                    st.multi = Some("\"\"\"");
                    i += 3;
                    continue;
                }
                if b[i..].starts_with(b"'''") {
                    st.multi = Some("'''");
                    i += 3;
                    continue;
                }
                match c {
                    b'"' | b'\'' => quote = Some(c),
                    b'[' | b'{' => st.depth += 1,
                    b']' | b'}' => st.depth -= 1,
                    b'#' => return Some(i),
                    _ => {}
                }
            }
        }
        i += 1;
    }
    None
}

/// The strings quoted on one line, outside its comment.
fn quoted_ids(code: &str) -> Vec<String> {
    code.split('"')
        .skip(1)
        .step_by(2)
        .map(str::to_owned)
        .collect()
}

/// The key a `key = value` line assigns, bare or quoted.
fn assigned_key(trimmed: &str) -> Option<(String, usize)> {
    let eq = trimmed.find('=')?;
    let raw = trimmed[..eq].trim();
    let key = raw.trim_matches(|c| c == '"' || c == '\'');
    let simple = !key.is_empty()
        && key
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-');
    simple.then(|| (key.to_owned(), eq + 1))
}

fn is_roles_header(trimmed: &str) -> bool {
    is_table_header(trimmed, "roles")
}

fn is_table_header(trimmed: &str, name: &str) -> bool {
    let Some(rest) = trimmed.strip_prefix('[') else {
        return false;
    };
    if rest.starts_with('[') {
        return false;
    }
    rest.split(']')
        .next()
        .is_some_and(|n| n.trim().trim_matches(|c| c == '"' || c == '\'') == name)
}

/// What the old value's lines said besides the ids: per line, the ids on it
/// and its comment, so a rewrite can carry the comments over.
struct OldSpan {
    start: usize,
    end: usize,
    /// `(line, ids on the line, comment)` for each line that has a comment.
    notes: Vec<(usize, Vec<String>, String)>,
    /// Every id in order of appearance (duplicates included), with the
    /// comment on its line when it is the last id there - so a comment follows
    /// one occurrence of an id, not every seat of the same agent.
    seats: Vec<(String, Option<String>)>,
}

/// Patch one key of the `[roles]` table, leaving every other byte alone.
///
/// Comments inside the replaced value are kept: a comment on an id's line
/// follows that id, standalone ones stay inside the array, and a trailing
/// comment stays trailing. Only the comment of an id that is removed goes with
/// it - and a reset keeps every comment of the key as plain comment lines.
fn patch_role(text: &str, key: &str, ids: &[String]) -> Result<String, String> {
    let eol = if text.contains("\r\n") { "\r\n" } else { "\n" };
    let lines: Vec<&str> = text.split_inclusive('\n').collect();

    // Section bounds and the key's span, found in one pass that knows about
    // multi-line arrays and multi-line strings.
    let mut st = Scan::default();
    let mut in_roles = false;
    let mut header: Option<usize> = None;
    let mut last_key_end: Option<usize> = None;
    let mut span: Option<OldSpan> = None;
    let mut i = 0;
    while i < lines.len() {
        let trimmed = lines[i].trim();
        if !st.open() && trimmed.starts_with('[') {
            in_roles = header.is_none() && is_roles_header(trimmed);
            if in_roles {
                header = Some(i);
            } else if header.is_some() {
                break;
            }
            i += 1;
            continue;
        }
        if !st.open()
            && let Some((name, _)) = assigned_key(trimmed)
        {
            let start = i;
            let first = lines[i].trim_start();
            let at = first.find('=').map_or(0, |p| p + 1);
            let mut end = i;
            let mut notes = Vec::new();
            let mut seats: Vec<(String, Option<String>)> = Vec::new();
            let mut note = |line: usize, code: &str, hash: Option<usize>| {
                let ids = quoted_ids(&code[..hash.unwrap_or(code.len())]);
                let comment = hash.map(|h| code[h..].trim_end().to_owned());
                let last = ids.len().saturating_sub(1);
                for (n, id) in ids.iter().enumerate() {
                    seats.push((id.clone(), comment.clone().filter(|_| n == last)));
                }
                if let Some(c) = comment {
                    notes.push((line, ids, c));
                }
            };
            let code = &first[at..];
            let hash = scan_line(code, &mut st);
            note(start, code, hash);
            while st.open() && end + 1 < lines.len() {
                end += 1;
                let hash = scan_line(lines[end], &mut st);
                note(end, lines[end], hash);
            }
            if in_roles {
                last_key_end = Some(end);
                if name == key {
                    let body = lines[start..=end].concat();
                    if body.contains("\"\"\"") || body.contains("'''") {
                        return Err(format!(
                            "`{key}` uses a multi-line string; edit it by hand."
                        ));
                    }
                    if body.contains("{{") || body.contains("{%") {
                        return Err(format!(
                            "`{key}` is written with a template expression, which this screen \
                             cannot edit without losing it. Change it by hand."
                        ));
                    }
                    span = Some(OldSpan {
                        start,
                        end,
                        notes,
                        seats,
                    });
                }
            }
            i = end + 1;
            continue;
        }
        if st.open() {
            scan_line(lines[i], &mut st);
        }
        i += 1;
    }

    let mut out: Vec<String> = lines.iter().map(|l| (*l).to_owned()).collect();
    let new_line = |indent: &str, comment: Option<&str>| {
        let mut s = format!("{indent}{key} = {}", value_text(key, ids));
        if let Some(c) = comment {
            s.push_str("  ");
            s.push_str(c);
        }
        s.push_str(eol);
        s
    };
    match (span, ids.is_empty()) {
        (Some(old), true) => {
            let indent: String = lines[old.start]
                .chars()
                .take_while(|c| c.is_whitespace())
                .collect();
            let kept: Vec<String> = old
                .notes
                .iter()
                .map(|(_, _, c)| format!("{indent}{c}{eol}"))
                .collect();
            out.splice(old.start..=old.end, kept);
        }
        (Some(old), false) => {
            let indent: String = lines[old.start]
                .chars()
                .take_while(|c| c.is_whitespace())
                .collect();
            let single = old.start == old.end;
            // A trailing comment is the last line's: always for a one-line
            // value, otherwise only when that line holds no id (`]  # tail`).
            let trailing = match old.notes.last() {
                Some((line, on_line, c)) if *line == old.end && (single || on_line.is_empty()) => {
                    Some(c.clone())
                }
                _ => None,
            };
            let interior = &old.notes[..old.notes.len() - usize::from(trailing.is_some())];
            let replacement: Vec<String> =
                if interior.is_empty() || (is_chain_role(key) && ids.len() == 1) {
                    // One line. Comments that cannot ride on it stay above it.
                    let mut v: Vec<String> = interior
                        .iter()
                        .map(|(_, _, c)| format!("{indent}{c}{eol}"))
                        .collect();
                    v.push(new_line(&indent, trailing.as_deref()));
                    v
                } else {
                    let mut v = vec![format!("{indent}{key} = [{eol}")];
                    for (_, _, c) in interior.iter().filter(|(_, l, _)| l.is_empty()) {
                        v.push(format!("{indent}  {c}{eol}"));
                    }
                    let mut taken: std::collections::HashMap<&str, usize> = Default::default();
                    for id in ids {
                        let nth = taken.entry(id.as_str()).or_insert(0);
                        let note = old
                            .seats
                            .iter()
                            .filter(|(old_id, _)| old_id == id)
                            .nth(*nth)
                            .and_then(|(_, c)| c.as_ref())
                            .map(|c| format!("  {c}"))
                            .unwrap_or_default();
                        *nth += 1;
                        v.push(format!("{indent}  {},{note}{eol}", quote(id)));
                    }
                    v.push(format!(
                        "{indent}]{}{eol}",
                        trailing.map(|c| format!("  {c}")).unwrap_or_default()
                    ));
                    v
                };
            out.splice(old.start..=old.end, replacement);
        }
        (None, true) => {}
        (None, false) => match (header, last_key_end) {
            (Some(_), Some(end)) | (Some(end), None) => {
                if !out[end].ends_with('\n') {
                    out[end].push_str(eol);
                }
                out.insert(end + 1, new_line("", None));
            }
            (None, _) => {
                if let Some(last) = out.last_mut()
                    && !last.ends_with('\n')
                {
                    last.push_str(eol);
                }
                if !out.is_empty() {
                    out.push(eol.to_owned());
                }
                out.push(format!("[roles]{eol}"));
                out.push(new_line("", None));
            }
        },
    }
    Ok(out.concat())
}

/// Set the seat count in the `[graph]` table, leaving every other byte alone.
///
/// `file_key` is the spelling to edit when the file already has it
/// (`candidates` is the deprecated alias of `implementers`); a file that
/// spells both is refused, as is a value this screen cannot rewrite in place
/// (template, multi-line, inline `graph = {..}`, dotted `graph.x = ..`). With
/// no such key the canonical `key` is added after the table's last key, and a
/// missing `[graph]` is appended at the end.
fn patch_count(text: &str, file_key: &str, key: &str, n: usize) -> Result<String, String> {
    let eol = if text.contains("\r\n") { "\r\n" } else { "\n" };
    let spellings = count_spellings(key);
    let lines: Vec<&str> = text.split_inclusive('\n').collect();
    let mut st = Scan::default();
    let mut in_graph = false;
    let mut in_table = false;
    let mut header: Option<usize> = None;
    let mut last_key_end: Option<usize> = None;
    let mut found: Vec<(usize, usize)> = Vec::new();
    let mut i = 0;
    while i < lines.len() {
        let trimmed = lines[i].trim();
        if !st.open() && trimmed.starts_with('[') {
            in_table = true;
            in_graph = header.is_none() && is_table_header(trimmed, "graph");
            if in_graph {
                header = Some(i);
            } else if header.is_some() {
                break;
            }
            i += 1;
            continue;
        }
        if !st.open()
            && !in_table
            && (trimmed.starts_with("graph.") || trimmed.starts_with("graph "))
        {
            let inline = assigned_key(trimmed).is_some_and(|(k, _)| k == "graph");
            if inline || trimmed.starts_with("graph.") {
                return Err(
                    "`graph` is written as an inline or dotted table, which this screen \
                     cannot edit. Change it by hand."
                        .to_owned(),
                );
            }
        }
        if !st.open()
            && let Some((name, _)) = assigned_key(trimmed)
        {
            let start = i;
            let first = lines[i].trim_start();
            let at = first.find('=').map_or(0, |p| p + 1);
            let mut end = i;
            scan_line(&first[at..], &mut st);
            while st.open() && end + 1 < lines.len() {
                end += 1;
                scan_line(lines[end], &mut st);
            }
            if in_graph {
                last_key_end = Some(end);
                if spellings.contains(&name.as_str()) {
                    found.push((start, end));
                }
            }
            i = end + 1;
            continue;
        }
        if st.open() {
            scan_line(lines[i], &mut st);
        }
        i += 1;
    }
    if found.len() > 1 {
        return Err(format!(
            "`[graph]` sets `{key}` more than once (it and its alias `candidates`); keep \
             only one and try again."
        ));
    }
    let mut out: Vec<String> = lines.iter().map(|l| (*l).to_owned()).collect();
    if let Some(&(start, end)) = found.first() {
        let body = lines[start..=end].concat();
        if start != end || body.contains("{{") || body.contains("{%") {
            return Err(format!(
                "`{file_key}` is written with a template expression or over several lines, \
                 which this screen cannot edit without losing it. Change it by hand."
            ));
        }
        let line = lines[start];
        let eq = line.find('=').unwrap_or(0) + 1;
        let rest = &line[eq..];
        let mut scratch = Scan::default();
        let code_len = scan_line(rest, &mut scratch).unwrap_or(rest.len());
        let value_end = rest[..code_len].trim_end().len();
        let lead = rest.len() - rest.trim_start().len();
        out[start] = format!(
            "{}{}{n}{}",
            &line[..eq],
            &rest[..lead.min(value_end)],
            &rest[value_end..]
        );
        return Ok(out.concat());
    }
    let new_line = format!("{key} = {n}{eol}");
    match (header, last_key_end) {
        (Some(_), Some(end)) | (Some(end), None) => {
            if !out[end].ends_with('\n') {
                out[end].push_str(eol);
            }
            out.insert(end + 1, new_line);
        }
        (None, _) => {
            if let Some(last) = out.last_mut()
                && !last.ends_with('\n')
            {
                last.push_str(eol);
            }
            if !out.is_empty() {
                out.push(eol.to_owned());
            }
            out.push(format!("[graph]{eol}"));
            out.push(new_line);
        }
    }
    Ok(out.concat())
}

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    fn ids(v: &[&str]) -> Vec<String> {
        v.iter().map(|s| (*s).to_owned()).collect()
    }

    const AGENTS: &str = "[[agents]]\nid = \"a\"\nkind = \"command\"\ncommand = [\"true\"]\n\n\
                          [[agents]]\nid = \"b\"\nkind = \"command\"\ncommand = [\"true\"]\n";

    #[test]
    fn patch_keeps_comments_and_unrelated_keys() {
        let src = "# top comment\n[vars]\ncache = \"/x\"  # keep\n\n[roles]\n# why\nimplementers = [\n  \"a\", # first\n  \"b\",\n]  # tail\njudges = [\"a\"]\nfixer = \"a\"\n\n[graph]\ncandidates = 2\n";
        let out = patch_role(src, "implementers", &ids(&["b", "a"])).unwrap();
        assert_eq!(
            out,
            "# top comment\n[vars]\ncache = \"/x\"  # keep\n\n[roles]\n# why\nimplementers = [\n  \"b\",\n  \"a\",  # first\n]  # tail\njudges = [\"a\"]\nfixer = \"a\"\n\n[graph]\ncandidates = 2\n"
        );
        let out = patch_role(&out, "judges", &[]).unwrap();
        assert!(!out.contains("judges"));
        assert!(out.contains("fixer = \"a\"") && out.contains("[graph]"));
    }

    #[test]
    fn patch_does_not_read_a_role_table_out_of_a_multiline_string() {
        let src = "[vars]\nexample = \'\'\'\n[roles]\njudges = [\"a\"]\n\'\'\'\nother = \"\"\"\n[roles]\n\"\"\"\n";
        // No real [roles] table: removing is a no-op, adding creates one.
        assert_eq!(patch_role(src, "judges", &[]).unwrap(), src);
        let out = patch_role(src, "judges", &ids(&["a"])).unwrap();
        assert!(out.starts_with(src), "{out}");
        assert!(out.ends_with("\n[roles]\njudges = [\"a\"]\n"), "{out}");
    }

    #[test]
    fn duplicate_seats_keep_their_own_comments() {
        let src =
            "[roles]\njudges = [\n  \"a\", # first seat\n  \"a\", # second seat\n  \"b\",\n]\n";
        let out = patch_role(src, "judges", &ids(&["b", "a", "a"])).unwrap();
        assert_eq!(
            out,
            "[roles]\njudges = [\n  \"b\",\n  \"a\",  # first seat\n  \"a\",  # second seat\n]\n"
        );
    }

    #[test]
    fn a_reset_keeps_the_comments_of_the_removed_key() {
        let out = patch_role(
            "[roles]\njudges = [\"a\"]  # why a\nfixer = \"a\"\n",
            "judges",
            &[],
        )
        .unwrap();
        assert_eq!(out, "[roles]\n# why a\nfixer = \"a\"\n");
        let out = patch_role(
            "[roles]\njudges = [\n  # lead\n  \"a\", # why a\n]\n",
            "judges",
            &[],
        )
        .unwrap();
        assert_eq!(out, "[roles]\n# lead\n# why a\n");
    }

    #[test]
    fn a_comment_follows_its_id_through_a_reorder() {
        let src =
            "[roles]\njudges = [ # head\n  # lead\n  \"a\", # why a\n  \"b\", # why b\n]  # tail\n";
        let out = patch_role(src, "judges", &ids(&["b", "c", "a"])).unwrap();
        assert_eq!(
            out,
            "[roles]\njudges = [\n  # head\n  # lead\n  \"b\",  # why b\n  \"c\",\n  \"a\",  # why a\n]  # tail\n"
        );
    }

    #[test]
    fn patch_creates_the_table_and_inserts_into_it() {
        let out = patch_role("[vars]\nx = 1", "judges", &ids(&["a"])).unwrap();
        assert_eq!(out, "[vars]\nx = 1\n\n[roles]\njudges = [\"a\"]\n");
        let out = patch_role(
            "[roles]\nfixer = \"a\"\n\n[graph]\njudges = 3\n",
            "judges",
            &ids(&["a"]),
        )
        .unwrap();
        assert_eq!(
            out,
            "[roles]\nfixer = \"a\"\njudges = [\"a\"]\n\n[graph]\njudges = 3\n"
        );
        // `[graph] judges` is not `[roles] judges`.
        let out = patch_role("[graph]\njudges = 3\n", "judges", &[]).unwrap();
        assert_eq!(out, "[graph]\njudges = 3\n");
    }

    #[test]
    fn fixer_is_a_string_for_one_and_an_array_for_a_chain() {
        let one = patch_role("", "fixer", &ids(&["a"])).unwrap();
        assert!(one.contains("fixer = \"a\""), "{one}");
        let two = patch_role("[roles]\nfixer = \"a\"\n", "fixer", &ids(&["a", "b"])).unwrap();
        assert!(two.contains("fixer = [\"a\", \"b\"]"), "{two}");
        let reset = patch_role(&two, "fixer", &[]).unwrap();
        assert!(!reset.contains("fixer ="), "{reset}");
    }

    #[test]
    fn synthesizer_is_a_string_for_one_and_an_array_for_a_chain() {
        let one = patch_role("", "synthesizer", &ids(&["a"])).unwrap();
        assert!(one.contains("synthesizer = \"a\""), "{one}");
        let two = patch_role("", "synthesizer", &ids(&["a", "b"])).unwrap();
        assert!(two.contains("synthesizer = [\"a\", \"b\"]"), "{two}");
    }

    const NEW_CHAIN_KEYS: [&str; 4] = ["chatter", "conductor", "language_judge", "dupes_judge"];

    #[test]
    fn new_chain_roles_save_round_trip_and_reset() {
        for key in NEW_CHAIN_KEYS {
            let tmp = TempDir::new().unwrap();
            let repo = tmp.path().join("repo");
            std::fs::create_dir_all(&repo).unwrap();
            std::fs::write(repo.join("magi.toml"), AGENTS).unwrap();
            let machine = tmp.path().join("config.toml");
            for wanted in [ids(&["b"]), ids(&["b", "a"]), Vec::new()] {
                let before = view(&repo, Some(&machine));
                let after = save(
                    &repo,
                    Some(&machine),
                    &before.revision,
                    &BTreeMap::from([(key.to_owned(), wanted.clone())]),
                    &BTreeMap::new(),
                )
                .unwrap();
                let role = after.roles.iter().find(|r| r.key == key).unwrap();
                assert_eq!(role.configured, wanted, "{key}");
                assert!(role.chain && role.count.is_none(), "{key}");
                let text = std::fs::read_to_string(&machine).unwrap();
                if wanted.is_empty() {
                    assert!(!text.contains(&format!("{key} =")), "{text}");
                    assert_eq!(role.source, "default");
                } else {
                    assert!(text.contains(&format!("{key} = {}", value_text(key, &wanted))));
                    assert_eq!(role.source, "machine");
                }
                let cfg = effective(&layer_paths(&repo, Some(&machine))).unwrap();
                assert_eq!(role_ids(&cfg, key), wanted, "{key}");
            }
        }
    }

    #[test]
    fn new_chain_roles_refuse_repo_overrides_in_words() {
        for key in NEW_CHAIN_KEYS {
            let tmp = TempDir::new().unwrap();
            let repo = tmp.path().join("repo");
            std::fs::create_dir_all(&repo).unwrap();
            std::fs::write(
                repo.join("magi.toml"),
                format!("{AGENTS}\n[roles]\n{key} = \"a\"\n"),
            )
            .unwrap();
            let machine = tmp.path().join("config.toml");
            let original = "# machine settings\n[vars]\nx = 1\n";
            std::fs::write(&machine, original).unwrap();
            let before = view(&repo, Some(&machine));
            let role = before.roles.iter().find(|r| r.key == key).unwrap();
            assert_eq!(role.source, "repo");
            assert!(!role.editable);
            for wanted in [ids(&["b"]), Vec::new()] {
                let err = save(
                    &repo,
                    Some(&machine),
                    &before.revision,
                    &BTreeMap::from([(key.to_owned(), wanted)]),
                    &BTreeMap::new(),
                )
                .unwrap_err();
                assert!(
                    matches!(&err, SaveError::Refused(m)
                        if m.contains(&format!("This repo overrides roles.{key}"))
                            && m.contains("edit it there")),
                    "{err:?}"
                );
                assert_eq!(std::fs::read_to_string(&machine).unwrap(), original);
            }
        }
    }

    #[test]
    fn new_chain_roles_show_defaults_inheritance_and_resolution_errors() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        let config = repo.join("magi.toml");
        std::fs::write(&config, AGENTS).unwrap();
        let defaults = view(&repo, None);
        for key in ["chatter", "conductor", "dupes_judge"] {
            let role = defaults.roles.iter().find(|r| r.key == key).unwrap();
            assert_eq!(role.seats, ids(&["a"]), "{key}");
        }
        let language = defaults
            .roles
            .iter()
            .find(|r| r.key == "language_judge")
            .unwrap();
        assert!(language.seats.is_empty() && language.seats_error.is_none());
        assert_eq!(language.fallback, Some("built-in heuristics"));
        std::fs::write(&config, format!("{AGENTS}\n[roles]\nchatter = \"b\"\n")).unwrap();
        let inherited = view(&repo, None);
        let dupes = inherited
            .roles
            .iter()
            .find(|r| r.key == "dupes_judge")
            .unwrap();
        assert_eq!(dupes.seats, ids(&["b"]));
        assert_eq!(dupes.fallback, Some("chatter"));
        // An explicit empty chain must not inherit chatter.
        std::fs::write(
            &config,
            format!("{AGENTS}\n[roles]\nchatter = \"b\"\ndupes_judge = []\n"),
        )
        .unwrap();
        let explicit = view(&repo, None);
        let dupes = explicit
            .roles
            .iter()
            .find(|r| r.key == "dupes_judge")
            .unwrap();
        assert_eq!(dupes.seats, ids(&["a"]));
        assert_eq!(dupes.fallback, None);
        for key in NEW_CHAIN_KEYS {
            for (choice, expected) in [
                ("[\"missing\", \"b\"]", ids(&["b"])),
                ("\"missing\"", Vec::new()),
            ] {
                std::fs::write(&config, format!("{AGENTS}\n[roles]\n{key} = {choice}\n")).unwrap();
                let v = view(&repo, None);
                let role = v.roles.iter().find(|r| r.key == key).unwrap();
                assert_eq!(role.seats, expected, "{key}");
                assert_eq!(role.skipped, ids(&["missing"]), "{key}");
                assert_eq!(role.seats_error.is_some(), expected.is_empty(), "{key}");
            }
        }
    }

    #[test]
    fn patch_refuses_a_templated_value() {
        let src = "[roles]\njudges = [\"{{ env.X | default(value='a') }}\"]\n";
        assert!(patch_role(src, "judges", &ids(&["a"])).is_err());
    }

    #[test]
    fn save_writes_machine_file_only_and_keeps_comments() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        let repo_toml = format!("{AGENTS}\n[graph]\ncandidates = 1\n");
        std::fs::write(repo.join("magi.toml"), &repo_toml).unwrap();
        let machine = tmp.path().join("cfg").join("magi").join("config.toml");
        std::fs::create_dir_all(machine.parent().unwrap()).unwrap();
        std::fs::write(
            &machine,
            "# mine\n[roles]\n# seats\njudges = [\"a\"] # note\n\n[vars]\nx = 1\n",
        )
        .unwrap();

        let v = view(&repo, Some(&machine));
        assert!(v.error.is_none(), "{:?}", v.error);
        let r = save(
            &repo,
            Some(&machine),
            &v.revision,
            &BTreeMap::from([("judges".to_owned(), ids(&["b", "a"]))]),
            &BTreeMap::new(),
        )
        .unwrap();
        let text = std::fs::read_to_string(&machine).unwrap();
        assert_eq!(
            text,
            "# mine\n[roles]\n# seats\njudges = [\"b\", \"a\"]  # note\n\n[vars]\nx = 1\n"
        );
        assert_eq!(
            std::fs::read_to_string(repo.join("magi.toml")).unwrap(),
            repo_toml
        );
        let judges = r.roles.iter().find(|x| x.key == "judges").unwrap();
        assert_eq!(judges.source, "machine");
        assert_eq!(judges.configured, ids(&["b", "a"]));
        // No tmp file left behind.
        let leftovers = std::fs::read_dir(machine.parent().unwrap())
            .unwrap()
            .count();
        assert_eq!(leftovers, 1);
    }

    #[test]
    fn save_refuses_unknown_ids_and_leaves_the_file_alone() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(repo.join("magi.toml"), AGENTS).unwrap();
        let machine = tmp.path().join("m").join("magi").join("config.toml");
        let v = view(&repo, Some(&machine));
        let err = save(
            &repo,
            Some(&machine),
            &v.revision,
            &BTreeMap::from([("judges".to_owned(), ids(&["nope"]))]),
            &BTreeMap::new(),
        )
        .unwrap_err();
        assert!(matches!(err, SaveError::Refused(m) if m.contains("nope")));
        assert!(!machine.exists());
    }

    #[test]
    fn save_refuses_a_key_the_repo_owns_and_a_stale_revision() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            repo.join("magi.toml"),
            format!("{AGENTS}\n[roles]\njudges = [\"a\"]\n"),
        )
        .unwrap();
        let machine = tmp.path().join("m").join("magi").join("config.toml");
        let v = view(&repo, Some(&machine));
        let j = v.roles.iter().find(|r| r.key == "judges").unwrap();
        assert!(!j.editable && j.source == "repo");
        let want = BTreeMap::from([("judges".to_owned(), ids(&["b"]))]);
        assert!(matches!(
            save(&repo, Some(&machine), &v.revision, &want, &BTreeMap::new()),
            Err(SaveError::Refused(_))
        ));
        let want = BTreeMap::from([("reviewers".to_owned(), ids(&["b"]))]);
        assert!(matches!(
            save(&repo, Some(&machine), "stale", &want, &BTreeMap::new()),
            Err(SaveError::Conflict(_))
        ));
    }

    #[test]
    fn a_config_that_does_not_parse_is_an_error_not_an_empty_list() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(repo.join("magi.toml"), "[roles\nbroken").unwrap();
        let v = view(&repo, None);
        let e = v.error.expect("an error");
        assert!(
            e.path.is_some_and(|p| p.ends_with("magi.toml")),
            "{}",
            e.message
        );
        assert!(v.roles.is_empty() && v.agents.is_empty());
    }

    #[test]
    fn advisors_unset_falls_back_to_judges() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            repo.join("magi.toml"),
            format!("{AGENTS}\n[roles]\njudges = [\"b\"]\n"),
        )
        .unwrap();
        let v = view(&repo, None);
        let a = v.roles.iter().find(|r| r.key == "advisors").unwrap();
        assert_eq!(a.fallback, Some("judges"));
        assert_eq!(a.source, "default");
        assert!(
            a.seats.iter().all(|s| s == "b") && !a.seats.is_empty(),
            "{:?}",
            a.seats
        );
    }

    /// A current repo whose config names `roots`, and a second checkout under
    /// it whose own `magi.toml` is `other_toml`.
    fn two_repos(tmp: &TempDir, other_toml: &str) -> (PathBuf, PathBuf, PathBuf) {
        let root = tmp.path().join("ghq");
        let repo = root.join("h").join("o").join("cur");
        let other = root.join("h").join("o").join("other");
        for d in [&repo, &other] {
            std::fs::create_dir_all(d.join(".git")).unwrap();
        }
        std::fs::write(
            repo.join("magi.toml"),
            format!(
                "{AGENTS}\n[repos]\nroots = [{}]\n",
                quote(&root.to_string_lossy())
            ),
        )
        .unwrap();
        std::fs::write(other.join("magi.toml"), other_toml).unwrap();
        let machine = tmp.path().join("m").join("magi").join("config.toml");
        (repo, other, machine)
    }

    #[test]
    fn saving_judges_is_refused_when_another_repo_declares_them() {
        let tmp = TempDir::new().unwrap();
        let (repo, other, machine) =
            two_repos(&tmp, &format!("{AGENTS}\n[roles]\njudges = [\"a\"]\n"));
        let v = view(&repo, Some(&machine));
        let j = v.roles.iter().find(|r| r.key == "judges").unwrap();
        assert!(!j.editable, "{:?}", j.locked_reason);
        let err = save(
            &repo,
            Some(&machine),
            &v.revision,
            &BTreeMap::from([("judges".to_owned(), ids(&["b"]))]),
            &BTreeMap::new(),
        )
        .unwrap_err();
        assert!(
            matches!(&err, SaveError::Refused(m) if m.contains("o/other")),
            "{err:?}"
        );
        assert!(!machine.exists());
        assert!(Config::load_layers(&repo_layers(&other)).is_ok());
        // A key nobody else declares still saves, and the other repo loads.
        save(
            &repo,
            Some(&machine),
            &v.revision,
            &BTreeMap::from([("reviewers".to_owned(), ids(&["b"]))]),
            &BTreeMap::new(),
        )
        .unwrap();
        let mut layers = vec![machine.clone()];
        layers.extend(repo_layers(&other));
        assert!(Config::load_layers(&layers).is_ok());
    }

    #[test]
    fn saving_a_role_writes_no_agents_and_detection_stays_dynamic() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(repo.join("magi.toml"), "[graph]\ncandidates = 1\n").unwrap();
        let machine = tmp.path().join("m").join("magi").join("config.toml");
        let v = view(&repo, Some(&machine));
        let Some(first) = Config::autodetected().agents.first().map(|a| a.id.clone()) else {
            return; // no agent CLI on PATH here; nothing to pick
        };
        save(
            &repo,
            Some(&machine),
            &v.revision,
            &BTreeMap::from([("judges".to_owned(), ids(&[&first]))]),
            &BTreeMap::new(),
        )
        .unwrap();
        let text = std::fs::read_to_string(&machine).unwrap();
        assert!(!text.contains("[[agents]]"), "{text}");
        let after = view(&repo, Some(&machine));
        assert!(after.agents.iter().all(|a| a.source == "detected"));
        assert_eq!(
            ids_of(
                &Config::load_layers(&layer_paths(&repo, Some(&machine)))
                    .unwrap()
                    .agents
            ),
            ids_of(&Config::autodetected().agents)
        );
    }

    #[test]
    fn an_explicit_empty_agents_list_is_kept() {
        let tmp = TempDir::new().unwrap();
        let f = tmp.path().join("magi.toml");
        std::fs::write(&f, "agents = []\n").unwrap();
        assert!(Config::load_layers(&[f]).unwrap().agents.is_empty());
    }

    #[test]
    fn the_repo_lock_says_the_repo_overrides_the_key() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            repo.join("magi.toml"),
            format!("{AGENTS}\n[roles]\njudges = [\"a\"]\n"),
        )
        .unwrap();
        let machine = tmp.path().join("m").join("magi").join("config.toml");
        let v = view(&repo, Some(&machine));
        let j = v.roles.iter().find(|r| r.key == "judges").unwrap();
        let why = j.locked_reason.as_deref().unwrap();
        assert!(
            why.starts_with("This repo overrides roles.judges in "),
            "{why}"
        );
    }

    #[test]
    fn patch_count_replaces_in_place_and_keeps_the_rest() {
        let src =
            "# top\n[graph]\n# seats\njudges   =   3   # three\nreviewers = 2\n\n[vars]\nx = 1\n";
        let out = patch_count(src, "judges", "judges", 5).unwrap();
        assert_eq!(
            out,
            "# top\n[graph]\n# seats\njudges   =   5   # three\nreviewers = 2\n\n[vars]\nx = 1\n"
        );
    }

    #[test]
    fn patch_count_keeps_the_alias_spelling() {
        let src = "[graph]\ncandidates = 2\n";
        let out = patch_count(src, "candidates", "implementers", 4).unwrap();
        assert_eq!(out, "[graph]\ncandidates = 4\n");
        assert!(!out.contains("implementers"));
    }

    #[test]
    fn patch_count_refuses_both_spellings() {
        let src = "[graph]\ncandidates = 2\nimplementers = 3\n";
        assert!(patch_count(src, "implementers", "implementers", 4).is_err());
    }

    #[test]
    fn patch_count_adds_the_key_after_the_last_graph_key() {
        let src = "[graph]\nreviewers = 2 # r\n\n[roles]\njudges = [\"a\"]\n";
        let out = patch_count(src, "judges", "judges", 2).unwrap();
        assert_eq!(
            out,
            "[graph]\nreviewers = 2 # r\njudges = 2\n\n[roles]\njudges = [\"a\"]\n"
        );
        let empty = patch_count("[graph]\n", "advisors", "advisors", 0).unwrap();
        assert_eq!(empty, "[graph]\nadvisors = 0\n");
    }

    #[test]
    fn patch_count_creates_a_missing_graph_table_and_keeps_crlf() {
        let out = patch_count("# c\n[roles]\njudges = [\"a\"]", "judges", "judges", 2).unwrap();
        assert_eq!(
            out,
            "# c\n[roles]\njudges = [\"a\"]\n\n[graph]\njudges = 2\n"
        );
        assert_eq!(
            patch_count("", "judges", "judges", 2).unwrap(),
            "[graph]\njudges = 2\n"
        );
        let crlf = patch_count("[graph]\r\nreviewers = 2\r\n", "judges", "judges", 2).unwrap();
        assert_eq!(crlf, "[graph]\r\nreviewers = 2\r\njudges = 2\r\n");
    }

    #[test]
    fn patch_count_refuses_what_it_cannot_rewrite_in_place() {
        assert!(patch_count("[graph]\njudges = {{ vars.n }}\n", "judges", "judges", 2).is_err());
        assert!(patch_count("graph = { judges = 2 }\n", "judges", "judges", 3).is_err());
        assert!(patch_count("graph.judges = 2\n", "judges", "judges", 3).is_err());
        assert!(patch_count("[graph]\njudges = \\\n", "judges", "judges", 3).is_ok());
    }

    #[test]
    fn save_writes_a_count_through_the_alias_and_refuses_bad_ones() {
        let tmp = TempDir::new().unwrap();
        let repo = tmp.path().join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            repo.join("magi.toml"),
            "[[agents]]\nid = \"a\"\nkind = \"command\"\ncommand = [\"true\"]\n",
        )
        .unwrap();
        let machine = tmp.path().join("m").join("magi").join("config.toml");
        std::fs::create_dir_all(machine.parent().unwrap()).unwrap();
        std::fs::write(&machine, "[graph]\ncandidates = 1 # old\n").unwrap();
        let v = view(&repo, Some(&machine));
        let c = |n: serde_json::Value| BTreeMap::from([("implementers".to_owned(), n)]);
        for bad in [
            serde_json::json!(0),
            serde_json::json!(2.5),
            serde_json::json!("x"),
            serde_json::json!(-1),
        ] {
            let err = save(
                &repo,
                Some(&machine),
                &v.revision,
                &BTreeMap::new(),
                &c(bad),
            )
            .unwrap_err();
            assert!(matches!(err, SaveError::Refused(_)), "{err:?}");
        }
        save(
            &repo,
            Some(&machine),
            &v.revision,
            &BTreeMap::new(),
            &c(serde_json::json!(2)),
        )
        .unwrap();
        assert_eq!(
            std::fs::read_to_string(&machine).unwrap(),
            "[graph]\ncandidates = 2 # old\n"
        );
        let after = view(&repo, Some(&machine));
        let count = after.roles[0].count.as_ref().unwrap();
        assert_eq!(
            (count.value, count.file_key, count.backups),
            (2, "candidates", Some(0))
        );
        // Advisors may be zero.
        save(
            &repo,
            Some(&machine),
            &after.revision,
            &BTreeMap::new(),
            &BTreeMap::from([("advisors".to_owned(), serde_json::json!(0))]),
        )
        .unwrap();
    }
}