spar/

repo.rs

//! git and gh. Every outbound string passes through the style and concision
//! gates before it reaches GitHub.

use std::collections::{BTreeMap, BTreeSet};
use std::ffi::OsStr;
use std::fs::OpenOptions;
use std::io::{BufRead, Read, Write};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Mutex, OnceLock};

use serde::Deserialize;
use serde_json::Value;
use sha1::Sha1;
use sha2::{Digest, Sha256};

use crate::config::{Config, Drafts, Followups, StateStore};
use crate::error::Result;
use crate::model::{
    Contested, ContestedItem, Followup, Issue, IssueRef, ItemKind, LiveHead, PersistedState, PrRef,
    PrRow, PrSweepRow, PrView, PR_SWEEP_FIELDS,
};
use crate::proc::{self, ExecOpts};
use crate::style::{self, Style};
use crate::textsim;
use crate::{bail, logdim, logwarn, spar_err};

/// What is read of one issue that is about to reach a prompt.
///
/// The comments come in the same call. The body is what somebody wrote once,
/// and the thread is where they narrowed it, widened it, or found the real
/// defect under the one they filed. Linking to the thread instead left that to
/// an agent that had to guess the body was out of date, and codex, which has no
/// network, could not follow the link at all.
const ISSUE_FIELDS: &str = "number,title,body,labels,state,stateReason,url,author,comments";

/// gh returns newest first, so its `--limit` cannot be used to take the lowest
/// numbered items: it would slice the newest N and then sorting that slice
/// silently drops the older ones. Fetch a generous page, sort, then truncate.
pub const FETCH_CEILING: usize = 500;

/// An unclosed HTML comment on purpose. The payload is written after it and
/// terminated with `-->`, so GitHub renders the whole block as nothing.
pub const STATE_MARKER: &str = "<!-- spar:state";

/// The signature on a comment spar composed, invisible when rendered.
///
/// spar posts as whoever ran it, so a comment from the viewer proves nothing
/// about who wrote it. Without this, spar's own outcome and round comments
/// counted as the viewer having answered, and `checkin` skipped a person's
/// comment as "replied to since" because a bookkeeping comment happened to be
/// newer than it.
pub const COMMENT_MARKER: &str = "<!-- spar:comment -->";

/// An entry boundary in the local follow-up note, on the same principle as
/// `STATE_MARKER` and rendered as nothing for the same reason.
///
/// A follow-up's own sections are written as `## Problem` and friends, at the
/// same heading level as the entry's title, so the file's shape does not say
/// which of two `## ` lines starts an entry. This does. Files written before it
/// existed are still read, by the heuristic in `followups::parse`.
pub const FOLLOWUP_MARKER: &str = "<!-- spar:followup -->";

const WORKTREE_DIR: &str = ".spar-worktrees";
const STATE_DIR: &str = ".spar";

/// Files SPAR writes into a worktree itself, which no agent ever authors.
pub(crate) const RECOVERY_MARKER_PREFIX: &str = ".spar-recovery-needed-";
pub(crate) const EDITED_GIT_MARKER: &str = ".spar-edited-git-marker";

/// What SPAR is allowed to throw away when it decides a checkout can go.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Disposable {
    /// Recognized build output, and nothing else. Somebody may have put the
    /// rest there and want it back.
    BuildOutput,
    /// Every ignored file, and SPAR's own markers. Only rebuilding a review
    /// checkout qualifies, and only because the next statement replaces it with
    /// a fresh checkout of the same ref: what is there came from an earlier
    /// `spar review` of the same pull request, and `git worktree add` would
    /// write over it regardless. Refusing instead left the command unusable on
    /// any project whose build writes outside `target/`, since a single
    /// lockfile beside a generator's manifest blocked every later run.
    ReviewOutput,
}

/// Whether `path` is one of the files SPAR leaves in a worktree root.
///
/// A marker is evidence for a person, not something a call did to the tree, and
/// two reviewers share one checkout: the marker written when the first one's
/// answer was refused is otherwise a brand new untracked file in the snapshot
/// the second one is compared against, so one refusal took the other review
/// down with it.
pub(crate) fn is_spar_marker(path: &Path) -> bool {
    let mut components = path.components();
    let Some(std::path::Component::Normal(name)) = components.next() else {
        return false;
    };
    if components.next().is_some() {
        return false;
    }
    let Some(name) = name.to_str() else {
        return false;
    };
    name == EDITED_GIT_MARKER || name.starts_with(RECOVERY_MARKER_PREFIX)
}

/// Whether `path` is somewhere SPAR writes in the repository it is driving.
///
/// The markers are one part of it. The other is the run state under `.spar/`,
/// which SPAR rewrites while a call it started is still running: recording the
/// branches it created during a parallel triage is enough to make both agents
/// look like they changed the tree they were told only to read. SPAR's own
/// bookkeeping is not evidence about an agent, so it never enters the snapshot
/// a call is compared against.
///
/// `.spar-worktrees/` is deliberately not here. A resident worktree enters the
/// snapshot as one ignored entry so that another run's churn inside it does not
/// disturb this baseline, while deleting the whole checkout still does.
pub(crate) fn is_spar_own_path(path: &Path) -> bool {
    if is_spar_marker(path) {
        return true;
    }
    let Some(std::path::Component::Normal(name)) = path.components().next() else {
        return false;
    };
    name == OsStr::new(STATE_DIR)
}

/// How many names one part of a split may be tried on before giving up. High
/// enough that nobody reaches it by splitting the same pull request again, low
/// enough that a repository where every name is taken says so rather than
/// looping.
const SPLIT_SLOTS: u32 = 20;

#[derive(Debug, Clone)]
pub struct SplitPushError {
    message: String,
    retain_worktree: bool,
}

impl SplitPushError {
    pub(crate) fn new(message: impl Into<String>, retain_worktree: bool) -> Self {
        Self {
            message: message.into(),
            retain_worktree,
        }
    }

    pub fn retain_worktree(&self) -> bool {
        self.retain_worktree
    }
}

impl std::fmt::Display for SplitPushError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for SplitPushError {}

/// The branch and worktree name for one part, on its `attempt`th name.
///
/// The unsuffixed name first, so the ordinary case reads as `split-12-1` and
/// only a repeat split carries a suffix.
fn split_slot(parent: i64, index: usize, attempt: u32) -> String {
    match attempt {
        1 => format!("split-{parent}-{index}"),
        n => format!("split-{parent}-{index}-{n}"),
    }
}

#[derive(Debug)]
pub struct Repo {
    root: PathBuf,
    pub style: Style,
    pub branch_prefix: String,
    pub state_store: StateStore,
    pub followups: Followups,
    pub drafts: Drafts,
    /// The login `gh` is authenticated as, asked at most once.
    ///
    /// `OnceLock` rather than `OnceCell` because `&Repo` crosses a
    /// `std::thread::scope` whenever both agents are asked at the same time,
    /// and only `OnceLock` is `Sync`.
    viewer: OnceLock<String>,
    /// Highest persisted checkpoint observed for each pull request.
    ///
    /// Kept in memory so a transient state read cannot reset the sequence
    /// after a resume already loaded a newer checkpoint.
    checkpoints: Mutex<BTreeMap<i64, u64>>,
    writes: WriteStats,
}

#[derive(Debug, Default)]
struct WriteStats {
    attempted: AtomicUsize,
    failed: AtomicUsize,
}

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub(crate) struct WriteSummary {
    pub(crate) attempted: usize,
    pub(crate) failed: usize,
}

impl WriteSummary {
    pub(crate) fn succeeded(self) -> usize {
        self.attempted.saturating_sub(self.failed)
    }
}

/// Ignored, untracked paths present before an editing call starts.
///
/// Existing build artifacts are deliberately part of the baseline. Callers can
/// therefore distinguish them from an ignored file the editing call created
/// and avoid deleting the latter as if no work had happened.
#[derive(Debug, Clone)]
pub(crate) struct WorktreeBaseline {
    attributes: AttributeState,
    ignored_untracked: IgnoredState,
    git_state: GitState,
}

/// The recorded Git state of a worktree that must remain read only.
///
/// Read-only agent calls are still ordinary processes. Capturing the complete
/// working state lets callers refuse to publish their answer or delete the
/// checkout if a call writes despite its instructions.
#[derive(Debug, Clone)]
pub(crate) struct WorktreeCheckpoint {
    path: PathBuf,
    attributes: AttributeState,
    git_state: GitState,
    ignored_untracked: IgnoredState,
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub(crate) struct AttributeState {
    files: BTreeMap<PathBuf, [u8; 32]>,
}

/// Exact paths and fingerprints for every untracked file, plus ignored paths.
///
/// Paths stay as operating-system strings so a non-UTF-8 filename cannot be
/// merged with another path by lossy command-output conversion.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub(crate) struct IgnoredState {
    files: BTreeMap<PathBuf, UntrackedFile>,
    ignored: BTreeSet<PathBuf>,
}

/// A bounded-cost fingerprint for an untracked filesystem entry.
///
/// Content hashing every ignored compiler artifact made each checkpoint read
/// gigabytes. File identity, type, size, timestamps, and mode detect ordinary
/// writes without rereading build output. Unix change time also changes when a
/// writer restores the modification time.
#[derive(Debug, Clone, PartialEq, Eq)]
struct UntrackedFile {
    kind: u8,
    len: u64,
    modified: Option<std::time::SystemTime>,
    created: Option<std::time::SystemTime>,
    readonly: bool,
    symlink_target: Option<Vec<u8>>,
    #[cfg(unix)]
    device: u64,
    #[cfg(unix)]
    inode: u64,
    #[cfg(unix)]
    mode: u32,
    #[cfg(unix)]
    change_seconds: i64,
    #[cfg(unix)]
    change_nanoseconds: i64,
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub(crate) struct GitState {
    repositories: BTreeMap<PathBuf, RepositoryState>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct RepositoryState {
    head: String,
    unsafe_index_flags: Vec<u8>,
    tracked: BTreeMap<PathBuf, TrackedEntry>,
    gitlinks: BTreeMap<PathBuf, String>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct TrackedEntry {
    index_mode: String,
    index_oid: String,
    worktree: Option<WorktreeFile>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct WorktreeFile {
    mode: String,
    #[cfg(unix)]
    permissions: u32,
    raw_oid: String,
    fingerprint: [u8; 32],
    content: [u8; 32],
}

struct Gitlink {
    path: PathBuf,
    oid: String,
}

struct IndexEntry {
    path: PathBuf,
    mode: String,
    oid: String,
}

impl IgnoredState {
    fn is_ignored(&self, path: &Path) -> bool {
        self.ignored.contains(path)
    }

    fn changed_paths(&self, after: &Self) -> Vec<PathBuf> {
        let mut paths: BTreeSet<PathBuf> = self.files.keys().cloned().collect();
        paths.extend(after.files.keys().cloned());
        paths
            .into_iter()
            .filter(|path| {
                self.files.get(path) != after.files.get(path)
                    || self.is_ignored(path) != after.is_ignored(path)
            })
            .collect()
    }

    fn changed_existing_paths(&self, after: &Self) -> Vec<PathBuf> {
        self.files
            .iter()
            .filter(|(path, state)| after.files.get(*path) != Some(*state))
            .map(|(path, _)| path.clone())
            .collect()
    }

    fn new_ordinary_paths(&self, after: &Self) -> Vec<PathBuf> {
        after
            .files
            .keys()
            .filter(|path| !after.is_ignored(path) && !self.files.contains_key(*path))
            .cloned()
            .collect()
    }

    /// Whether anything moved here that is not recognized build or cache
    /// output.
    ///
    /// A read-only call is held to its word by comparing the worktree before
    /// and after. Verifying a finding usually means building the project and
    /// running its tests, which rewrites that output, and holding a reviewer to
    /// a byte-identical `dist/` threw away the review it had just done. What
    /// the call was asked to judge is the tracked tree, and that is compared as
    /// strictly as ever, along with every other untracked file.
    pub(crate) fn changed_beyond_generated(&self, after: &Self) -> bool {
        let mut paths: BTreeSet<&PathBuf> = self.files.keys().collect();
        paths.extend(after.files.keys());
        paths.into_iter().any(|path| {
            if self.files.get(path) == after.files.get(path)
                && self.is_ignored(path) == after.is_ignored(path)
            {
                return false;
            }
            !self.generated_move(after, path)
        })
    }

    /// What a read-only call left behind, split by whether it condemns the
    /// answer.
    ///
    /// `changed_beyond_generated` answers this from a list of directory names,
    /// which is a guess about where a build writes. The repository already
    /// states where it writes, in its own ignore rules, and a review died over
    /// the gap: a reviewer ran the project's binding generator to check a
    /// finding, that wrote a lockfile beside its own manifest rather than under
    /// `target/`, and both agents lost an hour of work to a path Git had been
    /// told to disown.
    ///
    /// Forgiving only the creation of such a path was not enough, because the
    /// call is not the only writer. A read-only call runs for minutes in the
    /// primary checkout, which is a live desk: Finder rewrites `.DS_Store`, an
    /// editor rewrites its own state, and a triage that asks two agents at once
    /// compares both of them against that same directory. One ambient write
    /// discarded two good answers and ended the run with nothing scheduled. So
    /// a path the project ignores is out of scope however it moved, and what
    /// remains fatal is what the call was actually asked about: the tracked
    /// tree, and any ordinary untracked file, because a reviewer was told to
    /// keep its scratch out of the worktree.
    ///
    /// Nothing is silent. A tolerated path that is not recognized build output
    /// is named by the caller, so an agent that rewrote a person's `.env` is
    /// reported rather than hidden. That is the trade this makes: the answer of
    /// a call that never commits is worth more than the guarantee, and the
    /// warning carries what the guarantee used to.
    pub(crate) fn read_only_leavings(&self, after: &Self) -> ReadOnlyLeavings {
        let mut paths: BTreeSet<&PathBuf> = self.files.keys().collect();
        paths.extend(after.files.keys());
        let mut leavings = ReadOnlyLeavings::default();
        for path in paths {
            if self.files.get(path) == after.files.get(path)
                && self.is_ignored(path) == after.is_ignored(path)
            {
                continue;
            }
            if !self.ignored_file_move(after, path) {
                leavings.condemning.push(path.clone());
            } else if !is_generated_artifact(path) {
                leavings.tolerated.push(path.clone());
            }
        }
        leavings
    }

    /// Whether what happened at `path` between these two states is a build or
    /// cache directory doing its job, rather than a change a person would miss.
    ///
    /// Removal counts, on either side. A compiler that keeps an incremental
    /// cache does not only add and rewrite: it finalizes a new session
    /// directory and deletes the one it superseded, lock file and all. A rule
    /// that forgave creation and rewriting but not removal therefore passed the
    /// first build in a fresh worktree and failed the second one, which is the
    /// build a reviewer runs to check a finding. Two of these rules disagreeing
    /// about the same directory is what cost the run: the read-only check
    /// forgave the deleted session and the commit-side check called it
    /// unrepresentable, so the work was already on a pull request when the run
    /// ended. There is one rule now, and this is it.
    fn generated_move(&self, after: &Self, path: &Path) -> bool {
        is_generated_artifact(path) && self.disposable_move(after, path)
    }

    /// Successful edits and read-only calls share an ignore policy. Spar's
    /// resident worktrees belong to other runs, not to this call's output.
    /// Cleanup separately preserves ignored data, including dependency clones.
    fn ignored_file_move(&self, after: &Self, path: &Path) -> bool {
        if path.starts_with(WORKTREE_DIR)
            && self.files.get(path).is_some_and(|file| file.kind == 3)
            && self.files.get(path) != after.files.get(path)
        {
            return false;
        }
        self.disposable_move(after, path)
    }

    /// Whether neither state has anything at `path` worth keeping, so whatever
    /// happened there took nothing with it.
    fn disposable_move(&self, after: &Self, path: &Path) -> bool {
        self.disposable(path) && after.disposable(path)
    }

    /// Whether this state has nothing at `path` worth keeping: either the path
    /// is not there at all, or it is there as an ignored file.
    fn disposable(&self, path: &Path) -> bool {
        !self.files.contains_key(path) || self.is_ignored(path)
    }
}

impl GitState {
    /// What moved between two states, said so a person can act on it.
    ///
    /// The guards that compare these used to report only that the worktree had
    /// changed, which left the one question worth answering, which file, to a
    /// `git status` run by hand against a tree that had moved on since.
    pub(crate) fn describe_difference(&self, after: &Self) -> Option<String> {
        let mut prefixes: BTreeSet<&PathBuf> = self.repositories.keys().collect();
        prefixes.extend(after.repositories.keys());
        let mut notes: Vec<String> = Vec::new();
        let mut paths: Vec<PathBuf> = Vec::new();
        for prefix in prefixes {
            let label = describe_repository(prefix);
            match (
                self.repositories.get(prefix),
                after.repositories.get(prefix),
            ) {
                (None, Some(_)) => notes.push(format!("a repository appeared at {label}")),
                (Some(_), None) => notes.push(format!("the repository at {label} is gone")),
                (Some(before), Some(current)) => {
                    if before.head != current.head {
                        notes.push(format!("HEAD moved in {label}"));
                    }
                    if before.unsafe_index_flags != current.unsafe_index_flags {
                        notes.push(format!("index flags changed in {label}"));
                    }
                    paths.extend(
                        differing_keys(&before.gitlinks, &current.gitlinks)
                            .chain(differing_keys(&before.tracked, &current.tracked))
                            .map(|path| prefix.join(path)),
                    );
                }
                (None, None) => {}
            }
        }
        if !paths.is_empty() {
            paths.sort();
            paths.dedup();
            notes.push(format!("tracked file(s) changed: {}", list_paths(&paths)));
        }
        (!notes.is_empty()).then(|| notes.join("; "))
    }

    /// The tracked half of what a read-only call left behind, with a checkout
    /// that moved under the call reported rather than held against it.
    pub(crate) fn read_only_difference(&self, after: &Self, cwd: &Path) -> Option<String> {
        let difference = self.describe_difference(after)?;
        let Some(moved) = self.moved_wholesale(after) else {
            return Some(difference);
        };
        // Once, however many calls were reading when it happened: two triage
        // agents share the checkout and would otherwise both report the move.
        if said_once("moved", cwd, &moved) {
            logwarn!(
                "the checkout at {} moved while a read-only call was reading it: {moved}. The \
                 answer was kept, and it describes the tree as it stood before the move.",
                cwd.display()
            );
        }
        None
    }

    /// Whether every difference between these two states is the checkout moving
    /// as a whole rather than the call writing into it.
    ///
    /// The primary checkout is a live desk and a read-only call reads it for
    /// minutes. A person or their editor pulls, the branch fast forwards, and
    /// every file that arrived with it now differs from the snapshot taken
    /// before the call. Holding the call to that snapshot threw away two good
    /// triage answers and ended a run with nothing scheduled, over a change the
    /// call had no part in.
    ///
    /// The index tells the two apart. A call that wrote leaves a path
    /// disagreeing with the index, staged or unstaged, and leaves HEAD where it
    /// was. A checkout that moved rewrote the index and the worktree together,
    /// so every path it touched agrees with the index, and it moved HEAD to say
    /// so. Anything else, a tracked file that changed while HEAD stood still
    /// most of all, is the call's to answer for.
    fn moved_wholesale(&self, after: &Self) -> Option<String> {
        let mut prefixes: BTreeSet<&PathBuf> = self.repositories.keys().collect();
        prefixes.extend(after.repositories.keys());
        let mut notes: Vec<String> = Vec::new();
        for prefix in prefixes {
            // A repository that appeared or vanished is not a checkout moving.
            let before = self.repositories.get(prefix)?;
            let current = after.repositories.get(prefix)?;
            if before.unsafe_index_flags != current.unsafe_index_flags
                || before.gitlinks != current.gitlinks
            {
                return None;
            }
            let moved: Vec<&PathBuf> = differing_keys(&before.tracked, &current.tracked).collect();
            if before.head == current.head {
                if moved.is_empty() {
                    continue;
                }
                return None;
            }
            if !moved.iter().all(|path| {
                checked_out(before.tracked.get(*path)) && checked_out(current.tracked.get(*path))
            }) {
                return None;
            }
            let label = describe_repository(prefix);
            notes.push(match moved.len() {
                0 => format!("HEAD moved in {label}"),
                count => format!("HEAD moved in {label}, carrying {count} tracked file(s)"),
            });
        }
        (!notes.is_empty()).then(|| notes.join("; "))
    }
}

/// Whether a tracked path holds exactly what the index says it holds, so
/// nothing there is staged or left unstaged.
///
/// A path the index no longer lists counts as checked out: only an index
/// operation drops one, and a file left in the worktree after that is an
/// ordinary untracked file, which the untracked half of the same check has.
fn checked_out(entry: Option<&TrackedEntry>) -> bool {
    entry.is_none_or(|entry| {
        entry
            .worktree
            .as_ref()
            .is_some_and(|file| file.raw_oid == entry.index_oid && file.mode == entry.index_mode)
    })
}

/// Say what a call left among paths the project ignores, once per run for a
/// given set of them.
///
/// The project's own ignore rules put these outside what the call was asked
/// about, so this is a note about the desk the call ran on rather than a
/// finding about the call. Said as a warning on every call, it became the
/// loudest thing in the log of every run in a checkout with an editor open in
/// it: `.DS_Store` twice per triage, and again for each review. It still names
/// the paths, so an agent that rewrote a person's `.env` is reported rather
/// than hidden.
pub(crate) fn note_ignored_leavings(cwd: &Path, what: &str, paths: &[PathBuf]) {
    if paths.is_empty() {
        return;
    }
    let named = list_paths(paths);
    if !said_once("ignored", cwd, &named) {
        return;
    }
    logdim!(
        "a read-only {what} left {} ignored file(s) changed in {}: {named}. It was kept; the \
         project ignores these paths.",
        paths.len(),
        cwd.display()
    );
}

/// Whether this run has yet to say this about this directory.
///
/// A run reads the same checkout dozens of times, and the ambient facts about
/// it, an editor's own files moving and a branch advancing under the reader,
/// are true for every one of those calls. Said once they are context; said
/// each time they are the log.
fn said_once(topic: &str, cwd: &Path, detail: &str) -> bool {
    static SAID: Mutex<BTreeSet<String>> = Mutex::new(BTreeSet::new());
    SAID.lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .insert(format!("{topic}\0{}\0{detail}", cwd.display()))
}

/// Name a repository inside a state for a report. The root carries an empty
/// prefix, and calling that "" helps nobody.
fn describe_repository(prefix: &Path) -> String {
    if prefix.as_os_str().is_empty() {
        "the worktree".to_string()
    } else {
        format!("the submodule at {:?}", prefix.as_os_str())
    }
}

/// The keys whose values differ between two maps, present on either side.
fn differing_keys<'a, V: PartialEq>(
    before: &'a BTreeMap<PathBuf, V>,
    after: &'a BTreeMap<PathBuf, V>,
) -> impl Iterator<Item = &'a PathBuf> {
    let mut keys: BTreeSet<&'a PathBuf> = before.keys().collect();
    keys.extend(after.keys());
    keys.into_iter()
        .filter(move |key| before.get(*key) != after.get(*key))
}

/// What a read-only call left in the untracked and ignored tree.
///
/// Split rather than reduced to a yes or no, because the two halves are
/// answered differently: one ends the call, the other is said out loud and the
/// answer is kept.
#[derive(Default)]
pub(crate) struct ReadOnlyLeavings {
    /// Disposable on both sides, so out of scope for a call that only read.
    /// Recognized build output is left out: rebuilding is what a reviewer was
    /// asked to do, and nothing reports it today.
    pub(crate) tolerated: Vec<PathBuf>,
    /// Everything else. The answer does not survive these.
    pub(crate) condemning: Vec<PathBuf>,
}

/// Put two accounts of what moved into one sentence, keeping whichever of them
/// there is. Both guards that report a changed worktree ask the tracked tree
/// and the untracked tree separately, and either can be the only answer.
pub(crate) fn join_reasons(first: Option<String>, second: Option<String>) -> Option<String> {
    match (first, second) {
        (None, None) => None,
        (Some(one), None) | (None, Some(one)) => Some(one),
        (Some(first), Some(second)) => Some(format!("{first}; {second}")),
    }
}

/// Name some paths for a person, without printing a build directory at them.
///
/// Every report of a path that stopped or was let through a call goes through
/// this, so an error and the warning beside it read alike.
pub(crate) fn list_paths(paths: &[PathBuf]) -> String {
    const SHOWN: usize = 5;
    let mut listed = paths
        .iter()
        .take(SHOWN)
        .map(|path| format!("{:?}", path.as_os_str()))
        .collect::<Vec<_>>()
        .join(", ");
    if paths.len() > SHOWN {
        listed.push_str(&format!(", and {} more", paths.len() - SHOWN));
    }
    listed
}

/// Ignored files one commit attempt let through, gathered for a single report.
///
/// The checks that allow it run more than once per attempt, before staging,
/// after staging, and again after the commit, because the tree could have moved
/// under any of them. Reporting from inside each check said the same thing
/// about the same files two and three times over.
#[derive(Default)]
struct IgnoredArtifacts {
    new_paths: BTreeSet<PathBuf>,
    changed_paths: BTreeSet<PathBuf>,
    removed_paths: BTreeSet<PathBuf>,
}

impl IgnoredArtifacts {
    fn left(&mut self, allowed: AllowedArtifacts) {
        self.new_paths.extend(allowed.present);
        self.removed_paths.extend(allowed.removed);
    }

    fn changed(&mut self, allowed: AllowedArtifacts) {
        self.changed_paths.extend(allowed.present);
        self.removed_paths.extend(allowed.removed);
    }

    /// Report paths without claiming ignored files are safe to delete.
    fn report(&self, cwd: &Path) {
        let paths: BTreeSet<_> = self
            .new_paths
            .iter()
            .chain(&self.changed_paths)
            .chain(&self.removed_paths)
            .cloned()
            .collect();
        if !paths.is_empty() {
            logdim!(
                "the editing call changed {} ignored file(s) in {}: {}. They are outside \
                 the commit; cleanup checks them separately.",
                paths.len(),
                cwd.display(),
                list_paths(&paths.into_iter().collect::<Vec<_>>())
            );
        }
    }
}

/// Ignored files a check let through, split by whether each one
/// is still on disk, so the report can say what happened rather than call a
/// deleted incremental session a file that was left behind.
#[derive(Default)]
struct AllowedArtifacts {
    present: Vec<PathBuf>,
    removed: Vec<PathBuf>,
}

impl AllowedArtifacts {
    fn split(paths: Vec<PathBuf>, after: &IgnoredState) -> Self {
        let (present, removed) = paths
            .into_iter()
            .partition(|path| after.files.contains_key(path));
        Self { present, removed }
    }
}

/// Generated directories that test and build commands routinely create.
///
/// Files under these directories are never committed, and they do not keep a
/// worktree that is otherwise finished, so running the requested tests neither
/// stops the tracked change reaching review nor leaves a checkout behind.
fn is_generated_artifact(path: &Path) -> bool {
    const DIRECTORIES: &[&str] = &[
        "target",
        "dist",
        "node_modules",
        "__pycache__",
        ".pytest_cache",
        ".mypy_cache",
        ".ruff_cache",
        ".tox",
        ".nox",
        ".venv",
        "venv",
        ".gradle",
        ".build",
        "DerivedData",
        ".next",
        ".nuxt",
        ".svelte-kit",
        ".turbo",
        "coverage",
    ];
    path.components().any(|component| {
        let std::path::Component::Normal(name) = component else {
            return false;
        };
        DIRECTORIES
            .iter()
            .any(|directory| name == OsStr::new(directory))
    })
}

/// Files the desktop writes into any folder a person opens.
///
/// Finder drops `.DS_Store` into every directory it shows, so a finished
/// worktree someone once looked at in Finder held nothing but these, and
/// `spar clean` kept every one of them as if it were work.
fn is_desktop_metadata(path: &Path) -> bool {
    path.file_name() == Some(OsStr::new(".DS_Store"))
}

fn merge_pr_args<'a>(
    number: &'a str,
    expected_head: Option<&'a str>,
    delete_branch: bool,
) -> Vec<&'a str> {
    let mut args = vec!["pr", "merge", number, "--squash"];
    if delete_branch {
        args.push("--delete-branch");
    }
    if let Some(expected_head) = expected_head {
        args.extend(["--match-head-commit", expected_head]);
    }
    args
}

fn reconcile_pr_creation(
    branch: &str,
    created: Result<String>,
    found: Result<Option<PrRef>>,
) -> Result<PrRef> {
    match (created, found) {
        (_, Ok(Some(pr))) => Ok(pr),
        (Ok(_), Ok(None)) => Err(crate::error::SparError::uncertain_write(format!(
            "PR creation reported success but none was found for {branch}"
        ))),
        (Err(create), Ok(None)) => Err(spar_err!(
            "could not open a PR for {branch}. {}",
            create.last_line()
        )),
        (Ok(_), Err(check)) => Err(crate::error::SparError::uncertain_write(format!(
            "PR creation reported success for {branch}, but it could not be verified. {}",
            check.last_line()
        ))),
        (Err(create), Err(check)) => Err(crate::error::SparError::uncertain_write(format!(
            "could not open a PR for {branch}. {} The result could not be verified: {}",
            create.last_line(),
            check.last_line()
        ))),
    }
}

fn pr_for_base(text: &str, branch: &str, base: &str) -> Result<Option<PrRef>> {
    #[derive(Deserialize)]
    #[serde(rename_all = "camelCase")]
    struct Row {
        number: i64,
        #[serde(default)]
        url: String,
        #[serde(default)]
        title: String,
        base_ref_name: String,
    }

    let rows = serde_json::from_str::<Vec<Row>>(text.trim()).map_err(|e| {
        spar_err!("unexpected pull request list for branch {branch} against {base}: {e}")
    })?;
    Ok(rows
        .into_iter()
        .find(|row| row.base_ref_name == base)
        .map(|row| PrRef {
            number: row.number,
            url: row.url,
            title: row.title,
        }))
}

/// Sign a comment spar composed, so it can be told from one the same account
/// wrote by hand. Idempotent: a body already signed is returned as it is.
fn signed(body: &str) -> String {
    if body.contains(COMMENT_MARKER) {
        return body.to_string();
    }
    format!("{body}\n\n{COMMENT_MARKER}")
}

/// Whether a comment body is one spar composed rather than one a person wrote.
pub fn is_spar_comment(body: &str) -> bool {
    body.contains(COMMENT_MARKER) || body.contains(STATE_MARKER)
}

/// What `gh api -i` printed, taken apart.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ApiResponse {
    pub status: u16,
    /// Header names lowercased, values trimmed.
    pub headers: BTreeMap<String, String>,
    pub body: String,
}

/// Split `gh api -i` output into the status, the headers, and the body. None
/// when it does not start with a status line, which is what a spawn that
/// printed an error looks like.
pub fn parse_api_response(stdout: &str) -> Option<ApiResponse> {
    let mut lines = stdout.split_inclusive('\n');
    let first = lines.next()?.trim_end_matches(['\r', '\n']);
    if !first.starts_with("HTTP/") {
        return None;
    }
    let status: u16 = first.split_whitespace().nth(1)?.parse().ok()?;
    let mut headers = BTreeMap::new();
    let mut body = String::new();
    let mut in_body = false;
    for line in lines {
        if in_body {
            body.push_str(line);
            continue;
        }
        let bare = line.trim_end_matches(['\r', '\n']);
        if bare.is_empty() {
            in_body = true;
            continue;
        }
        if let Some((name, value)) = bare.split_once(':') {
            headers.insert(name.trim().to_ascii_lowercase(), value.trim().to_string());
        }
    }
    Some(ApiResponse {
        status,
        headers,
        body,
    })
}

/// The pull request a per item state file is about: `pr-12.json`,
/// `review-12.json`, `checkin-12.json`. None for anything else, so the shared
/// files beside them, `spend.json` and the rest, are never touched.
pub(crate) fn state_file_number(name: &str) -> Option<i64> {
    let stem = name.strip_suffix(".json")?;
    ["pr-", "review-", "checkin-"]
        .iter()
        .find_map(|prefix| stem.strip_prefix(prefix))
        .filter(|digits| !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit()))
        .and_then(|digits| digits.parse().ok())
}

/// Whether the viewer has already submitted this review: exactly this body, on
/// this commit, and still standing. A clean review reads the same on every
/// commit, so a body alone would take an approval of an older commit for this
/// one; and a dismissed review was withdrawn, so it is not this one either.
fn has_viewer_review(reviews: &[Value], viewer: &str, body: &str, commit: &str) -> bool {
    reviews.iter().any(|review| {
        let field = |name: &str| review.get(name).and_then(Value::as_str).unwrap_or("");
        let standing = !matches!(
            field("state").to_uppercase().as_str(),
            "DISMISSED" | "PENDING"
        );
        review
            .get("user")
            .and_then(|u| u.get("login"))
            .and_then(Value::as_str)
            .is_some_and(|login| crate::comments::same_login(login, viewer))
            && field("body") == body
            && field("commit_id").eq_ignore_ascii_case(commit)
            && standing
    })
}

fn reconcile_review_post(
    number: i64,
    body: &str,
    viewer: &str,
    commit: &str,
    post_error: crate::error::SparError,
    reviews: Result<Vec<Value>>,
) -> Result<()> {
    match reviews {
        Ok(reviews) if has_viewer_review(&reviews, viewer, body, commit) => Ok(()),
        Ok(_) => Err(post_error),
        Err(read_error) => Err(crate::error::SparError::uncertain_write(format!(
            "could not submit a review on #{number}. {} The result could not be verified: {}",
            post_error.last_line(),
            read_error.last_line()
        ))),
    }
}

fn has_exact_comment(comments: &[Value], body: &str) -> bool {
    comments.iter().any(|comment| {
        comment
            .get("body")
            .and_then(Value::as_str)
            .is_some_and(|seen| seen == body)
    })
}

fn reconcile_comment_post(
    number: i64,
    body: &str,
    post_error: crate::error::SparError,
    comments: Result<Vec<Value>>,
) -> Result<()> {
    match comments {
        Ok(comments) if has_exact_comment(&comments, body) => Ok(()),
        Ok(_) => Err(post_error),
        Err(read_error) => Err(crate::error::SparError::uncertain_write(format!(
            "could not comment on #{number}. {} The result could not be verified: {}",
            post_error.last_line(),
            read_error.last_line()
        ))),
    }
}

fn reconcile_issue_edit(
    number: i64,
    wanted: &str,
    edit_error: crate::error::SparError,
    observed: Result<String>,
) -> Result<()> {
    match observed {
        Ok(body) if body == wanted => Ok(()),
        Ok(_) => Err(spar_err!(
            "could not rewrite the body of #{number}. {}",
            edit_error.last_line()
        )),
        Err(read_error) => Err(crate::error::SparError::uncertain_write(format!(
            "could not rewrite the body of #{number}. {} The result could not be verified: {}",
            edit_error.last_line(),
            read_error.last_line()
        ))),
    }
}

fn issue_url_has_number(url: &str) -> bool {
    url.trim()
        .rsplit('/')
        .next()
        .and_then(|tail| tail.parse::<i64>().ok())
        .is_some_and(|number| number > 0)
}

fn reconcile_issue_creation(
    title: &str,
    created: Result<String>,
    found: Result<Option<ExistingIssue>>,
) -> Result<String> {
    match (created, found) {
        (Ok(url), _) if issue_url_has_number(&url) => Ok(url.trim().to_string()),
        (_, Ok(Some(issue))) => Ok(issue.url),
        (Ok(_), Ok(None)) => Err(crate::error::SparError::uncertain_write(format!(
            "issue creation reported success but no matching issue was found for {title:?}"
        ))),
        (Err(create), Ok(None)) => Err(spar_err!(
            "could not file issue {title:?}. {}",
            create.last_line()
        )),
        (Ok(_), Err(check)) => Err(crate::error::SparError::uncertain_write(format!(
            "issue creation reported success for {title:?}, but it could not be verified. {}",
            check.last_line()
        ))),
        (Err(create), Err(check)) => Err(crate::error::SparError::uncertain_write(format!(
            "could not file issue {title:?}. {} The result could not be verified: {}",
            create.last_line(),
            check.last_line()
        ))),
    }
}

fn remote_head_oid(output: &str, remote_ref: &str) -> Result<Option<String>> {
    if output.trim().is_empty() {
        return Ok(None);
    }
    for line in output.lines() {
        let mut fields = line.split_whitespace();
        let oid = fields.next().unwrap_or_default();
        let name = fields.next().unwrap_or_default();
        if name == remote_ref && !oid.is_empty() {
            return Ok(Some(oid.to_string()));
        }
    }
    Err(spar_err!(
        "origin returned an unexpected ref listing for {remote_ref}"
    ))
}

fn reconcile_failed_split_push(
    branch: &str,
    push_error: crate::error::SparError,
    local: Result<String>,
    remote: Result<String>,
) -> std::result::Result<(), SplitPushError> {
    let remote_ref = format!("refs/heads/{branch}");
    match (local, remote) {
        (Ok(local), Ok(remote)) => match remote_head_oid(&remote, &remote_ref) {
            Ok(Some(oid)) if oid == local.trim() => Ok(()),
            Ok(_) => Err(SplitPushError::new(
                format!(
                    "could not create origin/{branch}. {} The remote branch is absent or points \
                     somewhere else. Nothing was overwritten.",
                    push_error.last_line()
                ),
                false,
            )),
            Err(check) => Err(SplitPushError::new(
                format!(
                    "could not confirm whether origin/{branch} was created. {} The remote result \
                     could not be verified: {}",
                    push_error.last_line(),
                    check.last_line()
                ),
                true,
            )),
        },
        (local, remote) => {
            let check = match (local, remote) {
                (Err(local), Err(remote)) => format!(
                    "the local commit could not be read: {}; origin could not be read: {}",
                    local.last_line(),
                    remote.last_line()
                ),
                (Err(local), _) => {
                    format!("the local commit could not be read: {}", local.last_line())
                }
                (_, Err(remote)) => format!("origin could not be read: {}", remote.last_line()),
                _ => unreachable!(),
            };
            Err(SplitPushError::new(
                format!(
                    "could not confirm whether origin/{branch} was created. {} The result could \
                     not be verified because {check}",
                    push_error.last_line()
                ),
                true,
            ))
        }
    }
}

impl Repo {
    pub fn open(root: impl AsRef<Path>, cfg: &Config) -> Result<Self> {
        let root =
            std::fs::canonicalize(root.as_ref()).unwrap_or_else(|_| root.as_ref().to_path_buf());
        // A linked worktree has a `.git` file rather than a directory, and a
        // bare-ish layout can have neither, so ask git instead of guessing.
        let inside = proc::run_str(
            &["git", "rev-parse", "--is-inside-work-tree"],
            &ExecOpts::new().cwd(&root).check(false).timeout_secs(30),
        )
        .unwrap_or_default();
        if inside.trim() != "true" {
            bail!("not a git repository: {}", root.display());
        }
        let repo = Self {
            root,
            style: cfg.style.clone(),
            branch_prefix: cfg.loop_cfg.branch_prefix.clone(),
            state_store: cfg.loop_cfg.state_store,
            followups: cfg.loop_cfg.followups,
            drafts: cfg.loop_cfg.drafts,
            viewer: OnceLock::new(),
            checkpoints: Mutex::new(BTreeMap::new()),
            writes: WriteStats::default(),
        };
        repo.self_exclude();
        Ok(repo)
    }

    /// Keep spar's own scratch directories out of the target repo's
    /// `git status`.
    ///
    /// Written to `.git/info/exclude`, never to a tracked `.gitignore`: this is
    /// somebody else's repository and spar has no business committing to it.
    /// Best effort and silent on failure, because a read-only git directory is
    /// not a reason to abandon a run.
    fn self_exclude(&self) {
        let git_dir = self.git_try(&["rev-parse", "--path-format=absolute", "--git-common-dir"]);
        let git_dir = git_dir.trim();
        if git_dir.is_empty() {
            return;
        }
        let path = Path::new(git_dir).join("info").join("exclude");
        let existing = std::fs::read_to_string(&path).unwrap_or_default();

        // The marker too. It is written into whichever directory the call ran
        // in, which for a shared checkout is the repository root, and an
        // untracked file there is one `git add -A` away from being committed.
        // The error names its path, which is how a person is meant to find it.
        let wanted = [
            format!("/{WORKTREE_DIR}/"),
            format!("/{STATE_DIR}/"),
            format!("{RECOVERY_MARKER_PREFIX}*"),
        ];
        let missing: Vec<&String> = wanted
            .iter()
            .filter(|line| !existing.lines().any(|l| l.trim() == line.as_str()))
            .collect();
        if missing.is_empty() {
            return;
        }

        use std::io::Write;
        if let Some(parent) = path.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        let mut block = String::new();
        if !existing.is_empty() && !existing.ends_with('\n') {
            block.push('\n');
        }
        block.push_str("\n# added by spar: its worktrees, run state, and recovery markers\n");
        for line in missing {
            block.push_str(line);
            block.push('\n');
        }
        if let Ok(mut file) = std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&path)
        {
            let _ = file.write_all(block.as_bytes());
        }
    }

    pub fn root(&self) -> &Path {
        &self.root
    }

    pub(crate) fn write_summary(&self) -> WriteSummary {
        WriteSummary {
            attempted: self.writes.attempted.load(Ordering::Relaxed),
            failed: self.writes.failed.load(Ordering::Relaxed),
        }
    }

    pub(crate) fn record_write<T, E>(
        &self,
        result: std::result::Result<T, E>,
    ) -> std::result::Result<T, E> {
        self.record_write_outcome(result.is_err());
        result
    }

    pub(crate) fn record_failed_write<T, E>(
        &self,
        result: std::result::Result<T, E>,
    ) -> std::result::Result<T, E> {
        if result.is_err() {
            self.record_write_outcome(true);
        }
        result
    }

    fn record_write_outcome(&self, failed: bool) {
        self.writes.attempted.fetch_add(1, Ordering::Relaxed);
        if failed {
            self.writes.failed.fetch_add(1, Ordering::Relaxed);
        }
    }

    // -- gates ------------------------------------------------------------

    /// Scrub, then verify. A leak here reaches GitHub, so it is a hard error
    /// rather than a warning: silent partial compliance is how a style rule
    /// erodes over a long run.
    pub fn clean(&self, text: &str) -> Result<String> {
        let out = style::scrub(text, &self.style);
        let bad = style::violations(&out, &self.style);
        if !bad.is_empty() {
            bail!(
                "style gate could not clean text ({}): {}",
                bad.join(", "),
                style::clip(&out, 300)
            );
        }
        Ok(out)
    }

    /// Clean, and hold to a length budget. For anything a model wrote.
    pub fn clean_body(&self, text: &str) -> Result<String> {
        self.clean(&style::body(text, &self.style))
    }

    /// The same, with an issue's far larger budget and its exemption for code.
    pub fn clean_issue_body(&self, text: &str) -> Result<String> {
        self.clean(&style::issue_body(text, &self.style))
    }

    /// The single transform every outbound title goes through.
    ///
    /// Scrub first, clip second, and never the other way round. Clipping first
    /// lets the scrub lengthen the result past the budget (an em dash becomes
    /// two characters), so a second pass would clip again and produce a
    /// different string. That broke follow-up deduplication silently: the
    /// lookup searched for one title while GitHub had stored another, no match
    /// was ever found, and a fresh duplicate issue was filed every review
    /// round. Doing it in this order makes the transform idempotent, which the
    /// tests assert.
    pub fn clean_title(&self, text: &str) -> Result<String> {
        Ok(style::title(&self.clean(text)?, &self.style))
    }

    pub(crate) fn clean_nonempty_title_for_write(&self, text: &str) -> Result<String> {
        let title = self.record_failed_write(self.clean_title(text))?;
        if title.trim().is_empty() {
            return self.record_failed_write(Err(spar_err!(
                "nothing left of the title after cleaning it"
            )));
        }
        Ok(title)
    }

    pub(crate) fn clean_followup_title(&self, text: &str) -> Result<String> {
        if self.followups == Followups::Issues {
            self.clean_nonempty_title_for_write(text)
        } else {
            self.clean_title(text)
        }
    }

    // -- git --------------------------------------------------------------

    fn git_opts(&self, cwd: Option<&Path>, check: bool) -> ExecOpts {
        ExecOpts::new()
            .cwd(cwd.unwrap_or(&self.root))
            .check(check)
            .timeout_secs(600)
    }

    pub fn git(&self, args: &[&str]) -> Result<String> {
        self.git_at(None, args)
    }

    pub fn git_at(&self, cwd: Option<&Path>, args: &[&str]) -> Result<String> {
        let argv = git_without_maintenance_argv(args);
        proc::run(&argv, &self.git_opts(cwd, true))
    }

    /// Run a parent-side Git operation without inherited background helpers.
    ///
    /// Editing calls are untrusted. Once one returns, status, staging, and
    /// committing happen in this process, so an inherited fsmonitor or automatic
    /// maintenance command must not become a way to execute outside its sandbox.
    fn git_at_without_automation(&self, cwd: &Path, args: &[&str]) -> Result<String> {
        let argv = git_without_automation_argv(args);
        proc::run(
            &argv,
            &self.git_opts(Some(cwd), true).stop_descendants(true),
        )
    }

    fn git_try_without_automation(&self, args: &[&str]) -> Result<bool> {
        let argv = git_without_automation_argv(args);
        proc::exec(&argv, &self.git_opts(None, false).stop_descendants(true))
            .map(|output| output.ok())
    }

    /// Run git, tolerating failure. Returns whatever landed on stdout.
    pub fn git_try(&self, args: &[&str]) -> String {
        self.git_try_at(None, args)
    }

    pub fn git_try_at(&self, cwd: Option<&Path>, args: &[&str]) -> String {
        let argv = git_without_maintenance_argv(args);
        proc::run(&argv, &self.git_opts(cwd, false)).unwrap_or_default()
    }

    /// The base branch the remote actually points at, rather than assuming
    /// `main`. Falls back to the configured value when there is no origin.
    pub fn default_branch(&self, configured: &str) -> String {
        let refname = self.git_try(&["symbolic-ref", "refs/remotes/origin/HEAD"]);
        match refname.trim().rsplit('/').next() {
            Some(name) if !name.is_empty() => name.to_string(),
            _ => configured.to_string(),
        }
    }

    // -- branch naming and ownership --------------------------------------
    //
    // Branch names default to `issue-N`, which is exactly what a person would
    // name a branch by hand. Ownership therefore cannot be inferred from the
    // name, so every branch spar creates is recorded and cleanup only ever
    // touches what is in that record.

    pub fn branch_for_issue(&self, issue: i64) -> String {
        format!("{}issue-{issue}", self.branch_prefix)
    }

    pub fn branch_for_pr(&self, number: i64) -> String {
        format!("{}pr-{number}", self.branch_prefix)
    }

    /// One part of a split, numbered from 1 within its parent.
    ///
    /// Its own namespace rather than `issue-N`, because the parts of a split
    /// pull request have no issue of their own and would otherwise collide with
    /// the branch of the issue that happens to share the parent's number.
    ///
    /// The name a part is tried on first. `worktree_for_split` may end up on a
    /// suffixed one, because this name is not free forever.
    pub fn branch_for_split(&self, parent: i64, index: usize) -> String {
        format!("{}{}", self.branch_prefix, split_slot(parent, index, 1))
    }

    fn ledger_path(&self) -> PathBuf {
        self.root.join(STATE_DIR).join("branches.json")
    }

    pub fn known_branches(&self) -> BTreeMap<String, BranchRecord> {
        std::fs::read_to_string(self.ledger_path())
            .ok()
            .and_then(|text| serde_json::from_str(&text).ok())
            .unwrap_or_default()
    }

    pub fn record_branch(&self, branch: &str, kind: &str, number: i64) {
        let mut data = self.known_branches();
        data.insert(
            branch.to_string(),
            BranchRecord {
                kind: kind.to_string(),
                number,
            },
        );
        if let Err(e) = write_json_atomic(&self.ledger_path(), &data) {
            logdim!("could not record branch {branch}: {e}");
        }
    }

    pub fn forget_branch(&self, branch: &str) {
        let mut data = self.known_branches();
        if data.remove(branch).is_none() {
            return;
        }
        if let Err(e) = write_json_atomic(&self.ledger_path(), &data) {
            logdim!("could not update the branch record: {e}");
        }
    }

    // -- worktrees --------------------------------------------------------

    fn worktree_path(&self, name: &str) -> PathBuf {
        self.root.join(WORKTREE_DIR).join(name)
    }

    /// Isolate an issue so a failed run cannot poison the next one's base.
    pub fn worktree_add(&self, issue: i64, base: &str) -> Result<(PathBuf, String)> {
        let branch = self.branch_for_issue(issue);
        let path = self.worktree_path(&format!("issue-{issue}"));

        self.refuse_issue_branch_rebuild(issue, base)?;
        self.refuse_dirty_worktree(
            &path,
            &format!("worktree for issue #{issue}"),
            Disposable::BuildOutput,
        )?;

        if !self.branch_deletion_is_safe(&branch)? {
            bail!(
                "the existing branch {branch} has a tip or reflog-only commit that no surviving \
                 ref preserves. Rebuilding it would delete recovery history. Inspect the branch \
                 before retrying."
            );
        }

        if !self.remove_worktree_at(&path)? {
            bail!(
                "the existing worktree for issue #{issue} could not be removed safely. Its \
                 branch was kept."
            );
        }
        if !self.delete_branch_if_safe(&branch)? {
            bail!(
                "the existing branch {branch} changed or remained checked out while its \
                 worktree was being rebuilt. It was kept."
            );
        }

        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)
                .map_err(|e| spar_err!("could not create {}: {e}", parent.display()))?;
        }

        let path_str = path.display().to_string();
        let remote_start = format!("origin/{base}");
        let created = self
            .git(&["worktree", "add", "-b", &branch, &path_str, &remote_start])
            .or_else(|_| self.git(&["worktree", "add", "-b", &branch, &path_str, base]));

        // Recorded on both paths: an unrecorded branch is one cleanup will
        // never remove, and the fallback creates a branch just the same.
        created.map_err(|e| {
            spar_err!(
                "could not create a worktree for issue #{issue}. {}\nIs `{base}` a real branch, \
                 and does `origin` exist?",
                e.last_line()
            )
        })?;
        self.record_branch(&branch, "issue", issue);
        Ok((path, branch))
    }

    /// Refuse to reset the local or remote branch assigned to an issue when it
    /// carries work that no pull request preserves.
    ///
    /// Both linked-worktree mode and shared-checkout mode rebuild the same
    /// branch name. Keeping the guard here prevents either path from silently
    /// replacing recovery commits left by an earlier run.
    pub(crate) fn refuse_issue_branch_rebuild(&self, issue: i64, base: &str) -> Result<()> {
        let branch = self.branch_for_issue(issue);
        let base_remote_ref = format!("refs/heads/{base}");
        let base_tracking_ref = format!("refs/remotes/origin/{base}");
        let base_refspec = format!("+{base_remote_ref}:{base_tracking_ref}");
        self.git(&["fetch", "--no-tags", "origin", &base_refspec])
            .map_err(|e| {
                spar_err!(
                    "could not refresh origin/{base} before checking issue #{issue}: {}",
                    e.last_line()
                )
            })?;

        if let Some(remote_ref) = self.refresh_issue_remote_ref(&branch)? {
            let ahead = self.commit_count_checked(&self.root, &remote_ref, base)?;
            if ahead > 0 && !self.pull_request_holds(&branch, &remote_ref, base) {
                bail!(
                    "origin/{branch} already has {ahead} commit(s) that are not on {base}, and no \
                     pull request accounts for them. Rebuilding it would force push over that \
                     work.\nOpen a pull request for the branch and run `spar resume <pr>` to continue \
                     it, or delete it with `git push origin --delete {branch}` if the remote \
                     branch is no longer needed."
                );
            }
        }

        let local_ref = format!("refs/heads/{branch}");
        if self.exact_ref_exists_checked(&self.root, &local_ref)? {
            let ahead = self.commit_count_checked(&self.root, &local_ref, base)?;
            let recorded_pr = self
                .known_branches()
                .get(&branch)
                .is_some_and(|record| record.kind == "pr");
            let preserved = ahead == 0
                || if recorded_pr {
                    self.local_branch_is_preserved(&branch)?
                } else {
                    self.pull_request_holds(&branch, &local_ref, base)
                };
            if !preserved {
                let listed = self
                    .commit_lines(&self.root, &local_ref, base)
                    .iter()
                    .map(|line| format!("  {line}"))
                    .collect::<Vec<_>>()
                    .join("\n");
                bail!(
                    "the local branch {branch} has {ahead} commit(s) that are not on {base}, and \
                     no pull request preserves them. Rebuilding it would delete the only copy.\n\
                     {listed}\nPush it and run `spar resume <pr>` on the pull request to continue \
                     it, or delete it with `git branch -D {branch}` if it is stale."
                );
            }
        }
        Ok(())
    }

    fn refresh_issue_remote_ref(&self, branch: &str) -> Result<Option<String>> {
        let live_ref = format!("refs/heads/{branch}");
        let tracking_ref = format!("refs/remotes/origin/{branch}");
        let listed = self
            .git(&["ls-remote", "--heads", "origin", &live_ref])
            .map_err(|e| {
                spar_err!(
                    "could not verify whether origin/{branch} still exists: {}",
                    e.last_line()
                )
            })?;

        if remote_head_oid(&listed, &live_ref)?.is_some() {
            let refspec = format!("+{live_ref}:{tracking_ref}");
            self.git(&["fetch", "--no-tags", "origin", &refspec])
                .map_err(|e| {
                    spar_err!(
                        "origin/{branch} exists but its tracking ref could not be refreshed: {}",
                        e.last_line()
                    )
                })?;
            if !self.exact_ref_exists_checked(&self.root, &tracking_ref)? {
                bail!("origin/{branch} was fetched but its tracking ref is missing");
            }
            return Ok(Some(tracking_ref));
        }

        if !self.exact_ref_exists_checked(&self.root, &tracking_ref)? {
            return Ok(None);
        }
        let expected = self
            .git_at(Some(&self.root), &["rev-parse", "--verify", &tracking_ref])?
            .trim()
            .to_string();
        self.git_at_without_automation(&self.root, &["update-ref", "-d", &tracking_ref, &expected])
            .map_err(|e| {
                spar_err!(
                    "could not discard stale origin/{branch} tracking ref safely: {}",
                    e.last_line()
                )
            })?;
        if self.exact_ref_exists_checked(&self.root, &tracking_ref)? {
            bail!(
                "origin/{branch} changed while its stale tracking ref was being removed. It was \
                 kept."
            );
        }
        Ok(None)
    }

    /// Whether a pull request from `branch` already holds every commit `refname`
    /// has beyond `base`.
    ///
    /// GitHub serves `refs/pull/N/head` for as long as the repository lives, so
    /// commits that reached a pull request outlive the branch they were pushed
    /// from. A matching branch name does not establish that on its own: an
    /// issue worked twice reuses the name, and the merged pull request from the
    /// first round says nothing about where the second round's commits are.
    fn pull_request_holds(&self, branch: &str, refname: &str, base: &str) -> bool {
        self.prs_for_branch(branch)
            .iter()
            .any(|pr| self.pr_head_holds(pr.number, refname, base))
    }

    fn pr_head_holds(&self, number: i64, refname: &str, base: &str) -> bool {
        let head = format!("refs/spar/pr-head/{number}");
        let refspec = format!("+refs/pull/{number}/head:{head}");
        if self.git(&["fetch", "origin", &refspec]).is_err() {
            return false;
        }
        let held = self.commits_held_by(refname, base, &head);
        self.git_try(&["update-ref", "-d", &head]);
        held
    }

    pub(crate) fn is_ancestor_checked(&self, cwd: &Path, older: &str, newer: &str) -> Result<bool> {
        let argv = vec![
            "git".to_string(),
            "merge-base".to_string(),
            "--is-ancestor".to_string(),
            older.to_string(),
            newer.to_string(),
        ];
        let out = proc::exec(&argv, &self.git_opts(Some(cwd), false))?;
        match out.code {
            0 => Ok(true),
            1 => Ok(false),
            _ => Err(spar_err!("{}", proc::failure_message(&argv, &out))),
        }
    }

    fn pr_head_contains_checked(&self, number: i64, branch_ref: &str) -> Result<bool> {
        let head = format!("refs/spar/pr-head/{number}");
        let refspec = format!("+refs/pull/{number}/head:{head}");
        self.git(&["fetch", "origin", &refspec]).map_err(|e| {
            spar_err!(
                "could not verify the immutable head of PR #{number}: {}",
                e.last_line()
            )
        })?;
        let held = self.is_ancestor_checked(&self.root, branch_ref, &head);
        self.git_try(&["update-ref", "-d", &head]);
        held
    }

    fn branch_prs_checked(&self, branch: &str) -> Result<Vec<PrRef>> {
        let text = self.gh(&[
            "pr",
            "list",
            "--head",
            branch,
            "--state",
            "all",
            "--json",
            "number,url,title",
        ])?;
        serde_json::from_str(text.trim())
            .map_err(|e| spar_err!("could not read pull requests for {branch}: {e}"))
    }

    fn branch_is_preserved_checked(&self, branch: &str, record: &BranchRecord) -> Result<bool> {
        let branch_ref = format!("refs/heads/{branch}");
        if record.kind == "pr" {
            return self.pr_head_contains_checked(record.number, &branch_ref);
        }
        let prs = self.branch_prs_checked(branch)?;
        if prs.is_empty() {
            return Ok(false);
        }
        for pr in prs {
            if self.pr_head_contains_checked(pr.number, &branch_ref)? {
                return Ok(true);
            }
        }
        Ok(false)
    }

    fn branch_deletion_is_safe(&self, branch: &str) -> Result<bool> {
        let local_ref = format!("refs/heads/{branch}");
        if !self.exact_ref_exists_checked(&self.root, &local_ref)? {
            return Ok(true);
        }
        let oid = self
            .git_at(Some(&self.root), &["rev-parse", "--verify", &local_ref])?
            .trim()
            .to_string();
        let mut durable_tip = commit_has_shared_ref_except(&self.root, &oid, Some(&local_ref))?;
        if !durable_tip {
            let remote_ref = format!("refs/heads/{branch}");
            let remote = self.git(&["ls-remote", "--heads", "origin", &remote_ref])?;
            durable_tip = remote.lines().any(|line| {
                line.split_whitespace()
                    .next()
                    .is_some_and(|remote_oid| remote_oid == oid)
            });
        }
        if !durable_tip {
            if let Some(record) = self.known_branches().get(branch) {
                durable_tip = self.branch_is_preserved_checked(branch, record)?;
            }
        }
        if !durable_tip {
            return Ok(false);
        }
        ref_reflog_is_preserved(&self.root, &local_ref, &oid)
    }

    /// Delete a branch only if its exact current tip and reflog are still safe.
    /// The expected old value makes a concurrent ref update fail instead of
    /// deleting work that appeared after the preservation check.
    fn delete_branch_if_safe(&self, branch: &str) -> Result<bool> {
        let local_ref = format!("refs/heads/{branch}");
        if !self.exact_ref_exists_checked(&self.root, &local_ref)? {
            return Ok(true);
        }
        let expected = self
            .git_at(Some(&self.root), &["rev-parse", "--verify", &local_ref])?
            .trim()
            .to_string();
        if !self.branch_deletion_is_safe(branch)? {
            return Ok(false);
        }
        let checked_out = self
            .git_at(Some(&self.root), &["worktree", "list", "--porcelain"])?
            .lines()
            .any(|line| line == format!("branch {local_ref}"));
        if checked_out {
            return Ok(false);
        }
        self.git_at_without_automation(&self.root, &["update-ref", "-d", &local_ref, &expected])?;
        Ok(!self.exact_ref_exists_checked(&self.root, &local_ref)?)
    }

    fn review_ref_deletion_is_safe(&self, number: i64) -> Result<bool> {
        let local_ref = review_ref(number);
        if !self.exact_ref_exists_checked(&self.root, &local_ref)? {
            return Ok(true);
        }
        let oid = self
            .git_at(Some(&self.root), &["rev-parse", "--verify", &local_ref])?
            .trim()
            .to_string();
        if !self.pr_head_contains_checked(number, &local_ref)? {
            return Ok(false);
        }
        ref_reflog_is_preserved(&self.root, &local_ref, &oid)
    }

    fn delete_review_ref_if_safe(&self, number: i64) -> Result<bool> {
        let local_ref = review_ref(number);
        if !self.exact_ref_exists_checked(&self.root, &local_ref)? {
            return Ok(true);
        }
        let expected = self
            .git_at(Some(&self.root), &["rev-parse", "--verify", &local_ref])?
            .trim()
            .to_string();
        if !self.review_ref_deletion_is_safe(number)? {
            return Ok(false);
        }
        self.git_at_without_automation(&self.root, &["update-ref", "-d", &local_ref, &expected])?;
        Ok(!self.exact_ref_exists_checked(&self.root, &local_ref)?)
    }

    /// Whether `other` already contains every commit `branch` has beyond
    /// `base`. False when either ref fails to resolve, so a ref that is not
    /// there cannot vouch for anything.
    pub fn commits_held_by(&self, branch: &str, base: &str, other: &str) -> bool {
        let range = format!("{}..{branch}", self.base_ref(&self.root, base));
        self.git_try(&["rev-list", "--count", &range, "--not", other])
            .trim()
            == "0"
    }

    pub fn worktree_remove(&self, issue: i64) -> bool {
        let path = self.worktree_path(&format!("issue-{issue}"));
        match self.remove_worktree_at(&path) {
            Ok(removed) => removed,
            Err(error) => {
                logdim!(
                    "kept {} because removal did not reach a confirmed quiet point: {}",
                    path.display(),
                    error.last_line()
                );
                false
            }
        }
    }

    /// Verify both the common Git directory and the worktree top level.
    ///
    /// A stale worktree entry is not ownership proof. An unrelated repository
    /// can later occupy the same path and must survive cleanup.
    fn worktree_belongs_to_repo(&self, path: &Path) -> Result<bool> {
        let wanted = std::fs::canonicalize(path)
            .map_err(|e| spar_err!("could not resolve {}: {e}", path.display()))?;
        // Every SPAR worktree path is built from the canonical repository root.
        // A different canonical path therefore means the final component or
        // one of its parents is a symlink. Passing that alias to `git worktree
        // remove` can delete the worktree at its real target.
        if wanted != path {
            return Ok(false);
        }
        let resolve = |cwd: &Path, value: &str| -> Result<PathBuf> {
            let raw = PathBuf::from(value.trim());
            let joined = if raw.is_absolute() {
                raw
            } else {
                cwd.join(raw)
            };
            std::fs::canonicalize(&joined)
                .map_err(|e| spar_err!("could not resolve {}: {e}", joined.display()))
        };
        let expected =
            self.git_at_without_automation(&self.root, &["rev-parse", "--git-common-dir"])?;
        let actual = self.git_at_without_automation(path, &["rev-parse", "--git-common-dir"])?;
        let top = self.git_at_without_automation(path, &["rev-parse", "--show-toplevel"])?;
        let expected = resolve(&self.root, &expected)?;
        let actual = resolve(path, &actual)?;
        let top = resolve(path, &top)?;
        Ok(expected == actual && top == wanted)
    }

    /// Remove only a worktree that belongs to this repository.
    ///
    /// The path sits under a predictable directory, but that does not establish
    /// ownership. A clean independent repository at the same path must survive
    /// even when `git worktree remove` rejects it.
    fn remove_worktree_at_with_force(
        &self,
        path: &Path,
        force: bool,
        disposable: Disposable,
    ) -> Result<bool> {
        let existed = path.exists();
        if path.exists() {
            match self.worktree_belongs_to_repo(path) {
                Ok(true) => {}
                Ok(false) => {
                    logdim!(
                        "kept {} because it is not a worktree owned by this repository",
                        path.display()
                    );
                    return Ok(false);
                }
                Err(e) => {
                    logdim!(
                        "kept {} because its worktree ownership could not be verified: {}",
                        path.display(),
                        e.last_line()
                    );
                    return Ok(false);
                }
            }
            if !force {
                match self.has_recoverable_work(path, disposable) {
                    Ok(true) => {
                        logdim!(
                            "kept {} because it contains recoverable files or repository state",
                            path.display()
                        );
                        return Ok(false);
                    }
                    Err(e) => {
                        logdim!(
                            "kept {} because its recoverable state could not be checked: {}",
                            path.display(),
                            e.last_line()
                        );
                        return Ok(false);
                    }
                    Ok(false) => {}
                }
            }
        }
        // Git refuses to remove a worktree holding any untracked file, which is
        // the same question SPAR has just answered in more detail: under
        // `ReviewOutput` the checks above have already established that nothing
        // there is worth keeping. `--force` here is that answer being carried
        // out, not the check being skipped, which is what `force` means.
        let path_str = path.display().to_string();
        let command_ok = if force || disposable == Disposable::ReviewOutput {
            self.git_try_without_automation(&["worktree", "remove", "--force", &path_str])?
        } else {
            self.git_try_without_automation(&["worktree", "remove", &path_str])?
        };
        Ok((command_ok || !existed) && !path.exists())
    }

    fn remove_worktree_at(&self, path: &Path) -> Result<bool> {
        self.remove_worktree_at_with_force(path, false, Disposable::BuildOutput)
    }

    /// Remove a review checkout that is about to be rebuilt from origin.
    fn remove_review_worktree_at(&self, path: &Path) -> Result<bool> {
        self.remove_worktree_at_with_force(path, false, Disposable::ReviewOutput)
    }

    /// Force removal is reserved for the explicit `clean --all` path.
    fn remove_worktree_at_force(&self, path: &Path) -> bool {
        match self.remove_worktree_at_with_force(path, true, Disposable::BuildOutput) {
            Ok(removed) => removed,
            Err(error) => {
                logdim!(
                    "kept {} because removal did not reach a confirmed quiet point: {}",
                    path.display(),
                    error.last_line()
                );
                false
            }
        }
    }

    /// Remove a worktree only after a caller has verified it is unchanged.
    ///
    /// There is deliberately no force fallback, so Git can still refuse a
    /// removal if tracked or non-ignored work appears after the final check.
    fn remove_worktree_at_checked(&self, path: &Path, disposable: Disposable) -> Result<bool> {
        if path.exists() && !self.worktree_belongs_to_repo(path)? {
            bail!(
                "{} is not a worktree owned by this repository, so it was kept",
                path.display()
            );
        }
        if path.exists() && self.has_recoverable_work(path, disposable)? {
            bail!(
                "the verified worktree at {} contains recoverable files or repository state. It \
                 was kept.",
                path.display()
            );
        }
        let path_str = path.display().to_string();
        self.git_at_without_automation(&self.root, &["worktree", "remove", &path_str])
            .map_err(|e| {
                e.with_message(format!(
                    "could not remove the verified worktree at {}: {}. It was kept.",
                    path.display(),
                    e.last_line()
                ))
            })?;
        Ok(!path.exists())
    }

    fn refuse_dirty_worktree(
        &self,
        path: &Path,
        label: &str,
        disposable: Disposable,
    ) -> Result<()> {
        if !path.is_dir() {
            return Ok(());
        }
        let has_files = std::fs::read_dir(path)
            .map_err(|e| spar_err!("could not inspect {}: {e}", path.display()))?
            .next()
            .is_some();
        let owned = self.worktree_belongs_to_repo(path).map_err(|e| {
            spar_err!(
                "could not verify whether the existing {label} at {} belongs to this repository, \
                 so it was kept: {}",
                path.display(),
                e.last_line()
            )
        })?;
        if !owned {
            if has_files {
                bail!(
                    "the existing {label} at {} is not a worktree owned by \
                     this repository. Refusing to remove it.",
                    path.display()
                );
            }
            return Ok(());
        }
        if !path.join(".git").exists() {
            if has_files {
                bail!(
                    "the existing {label} at {} is not a readable Git worktree and is not empty. \
                     Refusing to remove it.",
                    path.display()
                );
            }
            return Ok(());
        }
        let dirty = self.has_recoverable_work(path, disposable).map_err(|e| {
            spar_err!(
                "could not verify whether the existing {label} at {} is clean, so it was kept: \
                 {}",
                path.display(),
                e.last_line()
            )
        })?;
        if dirty {
            bail!(
                "the existing {label} contains uncommitted changes or ignored files at {}. \
                 Rebuilding it would delete those files.\nCommit or recover them before running this \
                 command again, or use `spar clean --all` if they are not needed.",
                path.display()
            );
        }
        Ok(())
    }

    /// Check an existing PR branch out into an isolated worktree.
    pub fn worktree_for_pr(&self, pr: &PrView) -> Result<(PathBuf, String)> {
        let head = pr.head_ref_name.clone();
        if head.trim().is_empty() {
            bail!("PR #{} has no head branch to check out", pr.number);
        }
        let path = self.worktree_path(&format!("pr-{}", pr.number));
        let local = self.branch_for_pr(pr.number);

        self.git(&["fetch", "origin", &head]).map_err(|e| {
            spar_err!(
                "could not fetch the branch behind PR #{}: {}",
                pr.number,
                e.last_line()
            )
        })?;
        let start = format!("origin/{head}");
        let start_ref = format!("refs/remotes/origin/{head}");
        let local_ref = format!("refs/heads/{local}");
        if self.exact_ref_exists_checked(&self.root, &local_ref)? {
            let unpushed = self.commits_not_in_checked(&self.root, &local_ref, &start_ref)?;
            if unpushed > 0 {
                bail!(
                    "the existing worktree for PR #{} has {unpushed} local commit(s) that are not \
                     on {start}. Rebuilding it would delete their branch.\nInspect the worktree at \
                     {} and push or recover those commits before running this command again.",
                    pr.number,
                    path.display()
                );
            }
        }
        self.retain_ignored_pr_worktree(&path, &local, pr.number)?;
        self.refuse_dirty_worktree(
            &path,
            &format!("worktree for PR #{}", pr.number),
            Disposable::BuildOutput,
        )?;
        if !self.branch_deletion_is_safe(&local)? {
            bail!(
                "the existing branch {local} has a tip or reflog-only commit that no surviving \
                 ref preserves. Rebuilding it would delete recovery history. Inspect the branch \
                 before retrying."
            );
        }
        if !self.remove_worktree_at(&path)? {
            bail!(
                "the existing worktree for PR #{} could not be removed safely. Its branch was \
                 kept.",
                pr.number
            );
        }
        if !self.delete_branch_if_safe(&local)? {
            bail!(
                "the existing branch {local} changed or remained checked out while the PR \
                 worktree was being rebuilt. It was kept."
            );
        }

        let path_str = path.display().to_string();
        self.git(&["worktree", "add", "-B", &local, &path_str, &start])?;
        self.record_branch(&local, "pr", pr.number);
        Ok((path, head))
    }

    /// A retry needs a fresh checkout, not permission to delete ignored data.
    /// Keep that data and its branch when all commits are already published.
    fn retain_ignored_pr_worktree(&self, path: &Path, branch: &str, number: i64) -> Result<()> {
        if !path.is_dir() || !self.worktree_belongs_to_repo(path)? {
            return Ok(());
        }
        let current =
            self.git_at_without_automation(path, &["rev-parse", "--abbrev-ref", "HEAD"])?;
        if current.trim() != branch
            || self.has_uncommitted_changes(path)?
            || !has_untracked_work_worth_keeping(path, Disposable::BuildOutput)?
        {
            return Ok(());
        }
        static NEXT: AtomicUsize = AtomicUsize::new(0);
        let (name, retained) = loop {
            let serial = NEXT.fetch_add(1, Ordering::Relaxed);
            let name = format!("retained-pr-{number}-{}-{serial}", std::process::id());
            let retained = self.worktree_path(&name);
            if !retained
                .try_exists()
                .map_err(|e| spar_err!("could not inspect {}: {e}", retained.display()))?
                && !self.exact_ref_exists_checked(&self.root, &format!("refs/heads/{name}"))?
            {
                break (name, retained);
            }
        };
        // Neither command overwrites an existing destination. The branch rename
        // preserves its reflog, and the worktree move preserves every file.
        self.git_at_without_automation(path, &["branch", "-m", branch, &name])?;
        if let Err(error) = self.git_at_without_automation(
            &self.root,
            &[
                "worktree",
                "move",
                &path.display().to_string(),
                &retained.display().to_string(),
            ],
        ) {
            // A locked worktree or one with submodules cannot always be moved.
            // Restore the branch name so a failed move does not strand a retry.
            let rollback =
                self.git_at_without_automation(&self.root, &["branch", "-m", &name, branch]);
            let detail = rollback
                .err()
                .map(|e| format!(" Branch name recovery also failed: {}", e.last_line()))
                .unwrap_or_default();
            bail!(
                "could not retain the PR checkout at {}: {}. Its files were kept.{detail}",
                retained.display(),
                error.last_line()
            );
        }
        logdim!(
            "retained ignored files and branch {name} at {}; preparing a fresh PR checkout",
            retained.display()
        );
        Ok(())
    }

    /// Check a pull request's head out read only, detached, with no branch.
    ///
    /// Fetches `refs/pull/N/head`, which GitHub serves for every pull request
    /// including one from a fork whose branch is not in this repository at all.
    /// That is what makes reviewing an outside contribution possible when
    /// pushing to it is not.
    ///
    /// Detached on purpose. Review only mode has nothing to push, and a branch
    /// would only invite something to try.
    pub fn worktree_for_pr_head(&self, number: i64) -> Result<PathBuf> {
        let path = self.worktree_path(&format!("review-{number}"));
        let local_ref = review_ref(number);
        let refspec = format!("+refs/pull/{number}/head:{local_ref}");

        self.refuse_review_worktree_changes(number)?;

        self.git(&["fetch", "origin", &refspec]).map_err(|e| {
            spar_err!(
                "could not fetch the head of PR #{number}. {}\nGitHub serves refs/pull/N/head for \
                 every pull request, so this usually means the number is wrong or `origin` does \
                 not point at the repository the PR is on.",
                e.last_line()
            )
        })?;

        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)
                .map_err(|e| spar_err!("could not create {}: {e}", parent.display()))?;
        }
        if !self.remove_review_worktree_at(&path)? {
            bail!(
                "the existing review worktree for PR #{number} could not be removed safely. Its \
                 reference was kept."
            );
        }
        let path_str = path.display().to_string();
        self.git(&["worktree", "add", "--detach", &path_str, &local_ref])?;
        Ok(path)
    }

    fn refuse_review_worktree_changes(&self, number: i64) -> Result<()> {
        let path = self.worktree_path(&format!("review-{number}"));
        if !path.is_dir() {
            return Ok(());
        }
        let local_ref = review_ref(number);
        if !self.worktree_belongs_to_repo(&path)? {
            return Ok(());
        }
        if !self.exact_ref_exists_checked(&self.root, &local_ref)? {
            bail!(
                "the existing review worktree for PR #{number} has no recorded head at \
                 {local_ref}. Refusing to rebuild {}.",
                path.display()
            );
        }
        let worktree_head = self.head_oid_checked(&path)?;
        let recorded_head = self
            .git_at(Some(&self.root), &["rev-parse", "--verify", &local_ref])?
            .trim()
            .to_string();
        if worktree_head != recorded_head {
            bail!(
                "the existing review worktree for PR #{number} has a local commit that is not on \
                 {local_ref}. Rebuilding it would delete the only checkout of that work. Inspect \
                 {} before retrying.",
                path.display()
            );
        }
        self.report_recovery_markers(&path);
        self.refuse_dirty_worktree(
            &path,
            &format!("review worktree for PR #{number}"),
            Disposable::ReviewOutput,
        )?;
        Ok(())
    }

    /// Read out what an earlier run refused to explain away, before rebuilding
    /// over it.
    ///
    /// The marker is the only record of why a call's answer was thrown out, and
    /// a review checkout is rebuilt on the next run. Saying it here is what
    /// keeps the file from being the thing that quietly blocks the command
    /// instead.
    fn report_recovery_markers(&self, path: &Path) {
        let Ok(entries) = std::fs::read_dir(path) else {
            return;
        };
        for entry in entries.flatten() {
            let name = entry.file_name();
            let Some(name) = name.to_str() else { continue };
            if !name.starts_with(RECOVERY_MARKER_PREFIX) {
                continue;
            }
            match std::fs::read_to_string(entry.path()) {
                Ok(detail) => logwarn!("an earlier run left {name}: {}", detail.trim()),
                Err(e) => logdim!("could not read {}: {e}", entry.path().display()),
            }
        }
    }

    /// A worktree for one part of a split, on a new branch off `start`.
    ///
    /// `start` is the base branch for independent parts and the previous part's
    /// branch for stacked ones, which is the only difference between the two
    /// shapes at this level.
    ///
    /// The branch is whatever name was free, which is why it is returned rather
    /// than derived by the caller. Splitting the same pull request a second
    /// time would otherwise target the branch behind the first run's pull
    /// request. Split pushes are create-only and would refuse that target, but
    /// a repeated split still needs distinct branches rather than a name that
    /// can never be created.
    pub fn worktree_for_split(
        &self,
        parent: i64,
        index: usize,
        start: &str,
    ) -> Result<(PathBuf, String)> {
        let slot = self.free_split_slot(parent, index)?;
        let branch = format!("{}{slot}", self.branch_prefix);
        let path = self.worktree_path(&slot);

        if let Some(dir) = path.parent() {
            std::fs::create_dir_all(dir)
                .map_err(|e| spar_err!("could not create {}: {e}", dir.display()))?;
        }
        self.refuse_dirty_worktree(
            &path,
            &format!("worktree for part {index} of PR #{parent}"),
            Disposable::BuildOutput,
        )?;
        // The name is free, so there is no branch to delete. A directory can
        // still be in the way, left by a worktree that was pruned from git's
        // records without being removed from disk.
        if !self.remove_worktree_at(&path)? {
            bail!(
                "the existing worktree for part {index} of PR #{parent} could not be removed \
                 safely. No branch was created."
            );
        }

        let path_str = path.display().to_string();
        self.git(&["worktree", "add", "-b", &branch, &path_str, start])
            .map_err(|e| {
                spar_err!(
                    "could not create a worktree for part {index} of #{parent}. {}",
                    e.last_line()
                )
            })?;
        // Recorded before anything else can fail. An unrecorded branch is one
        // `prune_branches` will never remove.
        self.record_branch(&branch, "split", parent);
        Ok((path, branch))
    }

    /// The first part branch nothing is already sitting on.
    ///
    /// Origin as well as local, because a part's branch outlives the local one:
    /// a second split of the same pull request finds its own earlier branches
    /// deleted here but alive on origin, where the pull requests that reviewed
    /// them still point at them.
    fn free_split_slot(&self, parent: i64, index: usize) -> Result<String> {
        for attempt in 1..=SPLIT_SLOTS {
            let slot = split_slot(parent, index, attempt);
            let branch = format!("{}{slot}", self.branch_prefix);
            self.git_try(&["fetch", "origin", &branch]);
            if !self.rev_exists(&self.root, &branch)
                && !self.rev_exists(&self.root, &format!("origin/{branch}"))
            {
                return Ok(slot);
            }
        }
        bail!(
            "part {index} of #{parent} has no free branch name: {} and {SPLIT_SLOTS} suffixed \
             names are all taken. Inspect the existing branches and child pull requests. Finish \
             recording the earlier split, or remove every retained local worktree and branch, \
             child pull request, and remote split branch before starting over.",
            self.branch_for_split(parent, index)
        )
    }

    /// Whether a previous attempt pushed any branch for this split.
    ///
    /// The parent comment is the normal retry marker. A branch is the fallback
    /// when that comment or the pull request creation failed after the push.
    /// Reading origin directly makes the guard survive a fresh clone.
    pub fn has_remote_split_branch(&self, parent: i64) -> Result<bool> {
        let pattern = format!("refs/heads/{}split-{parent}-*", self.branch_prefix);
        Ok(!self
            .git(&["ls-remote", "--heads", "origin", &pattern])?
            .trim()
            .is_empty())
    }

    /// Throw one part away: its worktree, its branch, and its record.
    ///
    /// For a part that would not stand on its own. Nothing has been pushed at
    /// that point, so this leaves no trace anywhere but the log. Takes what
    /// `worktree_for_split` returned, since the name it settled on is not
    /// derivable from the parent and the index.
    pub fn release_split_worktree(&self, dir: &Path, branch: &str) {
        match self.branch_deletion_is_safe(branch) {
            Ok(true) => {}
            Ok(false) => {
                logdim!(
                    "kept {branch} and {} because no surviving ref preserves its tip",
                    dir.display()
                );
                return;
            }
            Err(error) => {
                logdim!(
                    "kept {branch} and {} because preservation could not be verified: {}",
                    dir.display(),
                    error.last_line()
                );
                return;
            }
        }
        match self.remove_worktree_at(dir) {
            Ok(true) => match self.delete_branch_if_safe(branch) {
                Ok(true) => self.forget_branch(branch),
                Ok(false) => {
                    logdim!("kept {branch} because its tip or reflog changed before deletion")
                }
                Err(error) => logdim!(
                    "kept {branch} because deletion safety could not be rechecked: {}",
                    error.last_line()
                ),
            },
            Ok(false) => {}
            Err(error) => logdim!(
                "kept {branch} and {} because removal did not reach a confirmed quiet point: {}",
                dir.display(),
                error.last_line()
            ),
        }
    }

    /// Discard one exact mechanical slice that the split workflow just made.
    ///
    /// Unlike ordinary release, this intentionally removes an unpushed commit.
    /// The caller supplies the exact disposable tip, and every file, worktree,
    /// ownership, and ref check must still match before anything is removed.
    pub fn discard_split_worktree(&self, dir: &Path, branch: &str, disposable_head: &str) -> bool {
        let record = self.known_branches().get(branch).cloned();
        if record.is_none_or(|record| record.kind != "split") {
            logdim!("kept {branch} because no split branch record proves ownership");
            return false;
        }
        let local_ref = format!("refs/heads/{branch}");
        let expected = match self.git_at(Some(&self.root), &["rev-parse", "--verify", &local_ref]) {
            Ok(value) => value.trim().to_string(),
            Err(error) => {
                logdim!(
                    "kept {branch} because its tip could not be checked: {}",
                    error.last_line()
                );
                return false;
            }
        };
        if expected != disposable_head {
            logdim!("kept {branch} because it moved beyond the disposable slice");
            return false;
        }
        match ref_reflog_is_preserved(&self.root, &local_ref, disposable_head) {
            Ok(true) => {}
            Ok(false) => {
                logdim!(
                    "kept {branch} because its reflog contains work outside the disposable slice"
                );
                return false;
            }
            Err(error) => {
                logdim!(
                    "kept {branch} because its reflog could not be checked: {}",
                    error.last_line()
                );
                return false;
            }
        }
        match self.head_oid_checked(dir) {
            Ok(head) if head == disposable_head => {}
            Ok(_) => {
                logdim!(
                    "kept {branch} and {} because the worktree moved beyond the disposable slice",
                    dir.display()
                );
                return false;
            }
            Err(error) => {
                logdim!(
                    "kept {branch} and {} because its head could not be checked: {}",
                    dir.display(),
                    error.last_line()
                );
                return false;
            }
        }
        match self.remove_worktree_at_checked(dir, Disposable::BuildOutput) {
            Ok(true) => {}
            Ok(false) => return false,
            Err(error) => {
                logdim!(
                    "kept {branch} and {} because the disposable slice could not be verified: {}",
                    dir.display(),
                    error.last_line()
                );
                return false;
            }
        }
        if let Err(error) =
            self.git_at_without_automation(&self.root, &["update-ref", "-d", &local_ref, &expected])
        {
            logdim!(
                "kept {branch} because its exact disposable tip could not be deleted: {}",
                error.last_line()
            );
            return false;
        }
        match self.exact_ref_exists_checked(&self.root, &local_ref) {
            Ok(false) => {
                self.forget_branch(branch);
                true
            }
            Ok(true) => {
                logdim!("kept {branch} because its ref still exists after deletion");
                false
            }
            Err(error) => {
                logdim!(
                    "kept the branch record for {branch} because deletion could not be verified: {}",
                    error.last_line()
                );
                false
            }
        }
    }

    pub fn release_review_worktree(&self, number: i64) {
        let path = self.worktree_path(&format!("review-{number}"));
        match self.review_ref_deletion_is_safe(number) {
            Ok(true) => {}
            Ok(false) => {
                logdim!(
                    "kept {} because no surviving ref preserves its review history",
                    path.display()
                );
                return;
            }
            Err(error) => {
                logdim!(
                    "kept {} because review history could not be verified: {}",
                    path.display(),
                    error.last_line()
                );
                return;
            }
        }
        match self.remove_worktree_at(&path) {
            Ok(true) => match self.delete_review_ref_if_safe(number) {
                Ok(true) => {}
                Ok(false) => logdim!(
                    "kept {} because its review history changed before deletion",
                    review_ref(number)
                ),
                Err(error) => logdim!(
                    "kept {} because deletion safety could not be rechecked: {}",
                    review_ref(number),
                    error.last_line()
                ),
            },
            Ok(false) => {}
            Err(error) => logdim!(
                "kept {} because removal did not reach a confirmed quiet point: {}",
                path.display(),
                error.last_line()
            ),
        }
    }

    /// Release a read-only review checkout only when every observed part of
    /// its Git state still matches the checkpoint captured before the calls.
    pub(crate) fn release_review_worktree_checked(
        &self,
        number: i64,
        checkpoint: &WorktreeCheckpoint,
    ) -> Result<()> {
        let path = self.worktree_path(&format!("review-{number}"));
        self.require_unchanged_worktree(
            &path,
            checkpoint,
            &format!("review worktree for PR #{number}"),
        )?;
        if !self.review_ref_deletion_is_safe(number)? {
            bail!(
                "the review reference for PR #{number} has reflog-only recovery history. The \
                 worktree and reference were kept."
            );
        }
        if !self.remove_worktree_at_checked(&path, Disposable::BuildOutput)? {
            bail!(
                "the verified review worktree at {} could not be removed, so its reference was \
                 kept",
                path.display()
            );
        }
        if !self.delete_review_ref_if_safe(number)? {
            bail!(
                "the review reference for PR #{number} changed before deletion. The reference was \
                 kept."
            );
        }
        Ok(())
    }

    pub fn release_pr_worktree(&self, number: i64) -> bool {
        let path = self.worktree_path(&format!("pr-{number}"));
        let local = self.branch_for_pr(number);
        match self.branch_deletion_is_safe(&local) {
            Ok(true) => {}
            Ok(false) => {
                logdim!(
                    "kept {local} and {} because no surviving ref preserves its tip",
                    path.display()
                );
                return false;
            }
            Err(error) => {
                logdim!(
                    "kept {local} and {} because preservation could not be verified: {}",
                    path.display(),
                    error.last_line()
                );
                return false;
            }
        }
        match self.remove_worktree_at(&path) {
            Ok(true) => match self.delete_branch_if_safe(&local) {
                Ok(true) => {
                    self.forget_branch(&local);
                    true
                }
                Ok(false) => {
                    logdim!("kept {local} because its tip or reflog changed before deletion");
                    false
                }
                Err(error) => {
                    logdim!(
                        "kept {local} because deletion safety could not be rechecked: {}",
                        error.last_line()
                    );
                    false
                }
            },
            Ok(false) => false,
            Err(error) => {
                logdim!(
                    "kept {local} and {} because removal did not reach a confirmed quiet point: {}",
                    path.display(),
                    error.last_line()
                );
                false
            }
        }
    }

    // -- branch state -----------------------------------------------------

    /// What to diff against: the remote tracking branch when it resolves, the
    /// local branch when it does not.
    ///
    /// This is not a nicety. Every "did the agent do anything" check hangs off
    /// this ref, and `git log` against a ref that does not exist fails silently
    /// and reads as "no commits". A checkout whose `origin/main` was never
    /// fetched would report every implementation as abandoned and throw the
    /// work away.
    pub fn base_ref(&self, cwd: &Path, base: &str) -> String {
        let remote = format!("origin/{base}");
        if self.rev_exists(cwd, &remote) {
            return remote;
        }
        if self.rev_exists(cwd, base) {
            logdim!("origin/{base} does not resolve, comparing against local {base}");
            return base.to_string();
        }
        logdim!("neither origin/{base} nor {base} resolves; results will be unreliable");
        remote
    }

    fn rev_exists(&self, cwd: &Path, refname: &str) -> bool {
        let spec = format!("{refname}^{{commit}}");
        !self
            .git_try_at(Some(cwd), &["rev-parse", "--verify", "--quiet", &spec])
            .trim()
            .is_empty()
    }

    pub fn has_changes(&self, cwd: &Path, base: &str) -> bool {
        let range = format!("{}..HEAD", self.base_ref(cwd, base));
        !self
            .git_try_at(Some(cwd), &["log", &range, "--oneline"])
            .trim()
            .is_empty()
    }

    fn exact_ref_exists_checked(&self, cwd: &Path, refname: &str) -> Result<bool> {
        let found = self.git_at(Some(cwd), &["for-each-ref", "--format=%(refname)", refname])?;
        Ok(found.lines().any(|line| line.trim() == refname))
    }

    fn commits_not_in_checked(&self, cwd: &Path, tip: &str, published: &str) -> Result<usize> {
        let count = self.git_at(Some(cwd), &["rev-list", "--count", tip, "--not", published])?;
        count.trim().parse::<usize>().map_err(|e| {
            spar_err!(
                "git returned an invalid commit count for {tip} outside {published}: {:?} ({e})",
                count.trim()
            )
        })
    }

    pub(crate) fn base_ref_checked(&self, cwd: &Path, base: &str) -> Result<String> {
        let remote = format!("refs/remotes/origin/{base}");
        if self.exact_ref_exists_checked(cwd, &remote)? {
            return Ok(remote);
        }
        let local = format!("refs/heads/{base}");
        if self.exact_ref_exists_checked(cwd, &local)? {
            return Ok(local);
        }
        bail!("neither origin/{base} nor local branch {base} resolves")
    }

    pub(crate) fn commit_count_checked(
        &self,
        cwd: &Path,
        refname: &str,
        base: &str,
    ) -> Result<usize> {
        let range = format!("{}..{refname}", self.base_ref_checked(cwd, base)?);
        let count = self.git_at(Some(cwd), &["rev-list", "--count", &range])?;
        count.trim().parse::<usize>().map_err(|e| {
            spar_err!(
                "git returned an invalid commit count for {range}: {:?} ({e})",
                count.trim()
            )
        })
    }

    pub(crate) fn has_changes_checked(&self, cwd: &Path, base: &str) -> Result<bool> {
        Ok(self.commit_count_checked(cwd, "HEAD", base)? > 0)
    }

    pub(crate) fn head_oid_checked(&self, cwd: &Path) -> Result<String> {
        let head = self.git_at(Some(cwd), &["rev-parse", "--verify", "HEAD^{commit}"])?;
        let head = head.trim().to_string();
        if head.is_empty() {
            bail!("git returned an empty HEAD for {}", cwd.display());
        }
        Ok(head)
    }

    /// Whether a recorded SPAR branch's exact tip is retained by a pull request.
    ///
    /// Pull request head refs remain available after close or merge, so this is
    /// stronger than requiring an open pull request or a live remote branch.
    pub(crate) fn current_branch_is_preserved(&self, cwd: &Path) -> Result<bool> {
        let branch = self.git_at(Some(cwd), &["symbolic-ref", "--quiet", "--short", "HEAD"])?;
        self.local_branch_is_preserved(branch.trim())
    }

    /// Whether a recorded local branch's exact tip is retained by its pull
    /// request head, regardless of which branch is currently checked out.
    pub(crate) fn local_branch_is_preserved(&self, branch: &str) -> Result<bool> {
        let known = self.known_branches();
        let Some(record) = known.get(branch) else {
            return Ok(false);
        };
        self.branch_is_preserved_checked(branch, record)
    }

    /// Whether tracked, staged, or non-ignored untracked files are uncommitted.
    pub(crate) fn has_uncommitted_changes(&self, cwd: &Path) -> Result<bool> {
        has_uncommitted_work(cwd)
    }

    /// Whether removing a worktree would delete any local file Git does not
    /// reproduce from its commits, including ignored untracked files.
    fn has_recoverable_work(&self, cwd: &Path, disposable: Disposable) -> Result<bool> {
        repository_has_recoverable_work_with(cwd, true, disposable)
    }

    /// Record ignored artifacts that existed before an editing call.
    pub(crate) fn worktree_baseline(&self, cwd: &Path) -> Result<WorktreeBaseline> {
        let attributes = attribute_state(cwd)?;
        Ok(WorktreeBaseline {
            attributes,
            ignored_untracked: ignored_untracked_state(cwd)?,
            git_state: safe_git_state(cwd)?,
        })
    }

    /// Capture the Git state of a checkout intended to remain read only while
    /// external commands inspect it.
    pub(crate) fn worktree_checkpoint(&self, cwd: &Path) -> Result<WorktreeCheckpoint> {
        let attributes = attribute_state(cwd)?;
        Ok(WorktreeCheckpoint {
            path: std::fs::canonicalize(cwd)
                .map_err(|e| spar_err!("could not resolve {}: {e}", cwd.display()))?,
            attributes,
            git_state: safe_git_state(cwd)?,
            ignored_untracked: ignored_untracked_state(cwd)?,
        })
    }

    /// Require a read-only checkout to match a previously captured checkpoint.
    /// Any probe failure is an error because deletion cannot be proven safe.
    pub(crate) fn require_unchanged_worktree(
        &self,
        cwd: &Path,
        checkpoint: &WorktreeCheckpoint,
        label: &str,
    ) -> Result<()> {
        let resolved = std::fs::canonicalize(cwd).map_err(|e| {
            crate::error::SparError::uncertain_write(format!(
                "could not resolve the {label} at {} after inspection: {e}. It was kept.",
                cwd.display()
            ))
        })?;
        if resolved != checkpoint.path {
            return Err(uncertain_worktree_change(
                cwd,
                format!(
                    "the {label} moved from {} to {} during inspection. It was kept.",
                    checkpoint.path.display(),
                    resolved.display()
                ),
            ));
        }
        let attributes = probe_again_on_failure(|| attribute_state(cwd)).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify attribute files in the {label} at {}: {}. It was kept.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        if attributes != checkpoint.attributes {
            return Err(uncertain_worktree_change(
                cwd,
                format!(
                    "attribute files in the {label} at {} changed during inspection. It was \
                     kept for recovery.",
                    cwd.display()
                ),
            ));
        }
        let git_state = probe_again_on_failure(|| git_state(cwd)).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify the Git state of the {label} at {}: {}. It was kept.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        let ignored = probe_again_on_failure(|| ignored_untracked_state(cwd)).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify untracked files in the {label} at {}: {}. It was kept.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        let leavings = checkpoint.ignored_untracked.read_only_leavings(&ignored);
        // Said even when the inspection is accepted, for the same reason it is
        // said on an agent call: a path the project ignores is out of scope,
        // not unnoticed.
        note_ignored_leavings(cwd, "inspection", &leavings.tolerated);
        let tracked = checkpoint.git_state.describe_difference(&git_state);
        let untracked = (!leavings.condemning.is_empty()).then(|| {
            format!(
                "untracked file(s) changed: {}",
                list_paths(&leavings.condemning)
            )
        });
        let Some(reason) = join_reasons(tracked, untracked) else {
            return Ok(());
        };
        Err(uncertain_worktree_change(
            cwd,
            format!(
                "the {label} at {} changed during a read-only inspection: {reason}. It was kept \
                 for recovery.",
                cwd.display()
            ),
        ))
    }

    /// Accept project-ignored files left by a successful editing call.
    /// Ordinary untracked files must already be represented by the commit.
    /// Acceptance does not authorize cleanup of the ignored files.
    pub(crate) fn refuse_new_ignored_files(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<()> {
        self.allow_ignored_files(cwd, baseline).map(drop)
    }

    /// Preserve unexpected output when the editing call did not finish.
    pub(crate) fn refuse_failed_edit_leavings(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<()> {
        self.check_new_ignored_files(cwd, baseline, IgnoredState::generated_move)
            .map(drop)
    }

    /// Reject ordinary untracked changes after a read-only call.
    pub(crate) fn refuse_read_only_leavings(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<()> {
        self.refuse_changed_attributes(cwd, baseline)?;
        let after = ignored_untracked_state(cwd).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify untracked files in {} after a read-only call: {}. The \
                     worktree was kept for recovery.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        let leavings = baseline.ignored_untracked.read_only_leavings(&after);
        if leavings.condemning.is_empty() {
            return Ok(());
        }
        Err(uncertain_worktree_change(
            cwd,
            format!(
                "the read-only call left untracked file(s) in {} that the project does not \
                 ignore: {}. The worktree was kept for recovery.",
                cwd.display(),
                list_paths(&leavings.condemning)
            ),
        ))
    }

    /// The ignored paths the check let through, for one report per attempt
    /// rather than one per check.
    fn allow_ignored_files(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<AllowedArtifacts> {
        self.check_new_ignored_files(cwd, baseline, IgnoredState::ignored_file_move)
    }

    fn check_new_ignored_files(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
        allowed_move: fn(&IgnoredState, &IgnoredState, &Path) -> bool,
    ) -> Result<AllowedArtifacts> {
        self.refuse_changed_attributes(cwd, baseline)?;
        let after = ignored_untracked_state(cwd).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify untracked files in {} after editing: {}. The worktree was \
                     kept for recovery.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        let changed = baseline.ignored_untracked.changed_paths(&after);
        if changed.is_empty() {
            return Ok(AllowedArtifacts::default());
        }
        let (ignored, changed): (Vec<_>, Vec<_>) = changed
            .into_iter()
            .partition(|path| allowed_move(&baseline.ignored_untracked, &after, path));
        if changed.is_empty() {
            return Ok(AllowedArtifacts::split(ignored, &after));
        }
        let listed = list_paths(&changed);
        Err(uncertain_worktree_change(
            cwd,
            format!(
                "the editing call created or changed untracked or ignored file(s) in {} that \
                 cannot be represented by a managed commit: {listed}. The worktree was kept for \
                 recovery.",
                cwd.display()
            ),
        ))
    }

    /// Existing untracked files belong to the checkout owner, even when a call
    /// also produces a valid tracked change. Refuse their modification or
    /// deletion before accepting the tracked result. Project-ignored files
    /// stay outside the commit, wherever the project puts them.
    pub(crate) fn refuse_changed_existing_untracked(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<()> {
        self.check_changed_existing_untracked(cwd, baseline)
            .map(drop)
    }

    fn allow_changed_ignored_artifacts(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<AllowedArtifacts> {
        self.check_changed_existing_untracked(cwd, baseline)
    }

    fn check_changed_existing_untracked(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<AllowedArtifacts> {
        self.refuse_changed_attributes(cwd, baseline)?;
        let after = ignored_untracked_state(cwd).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify existing untracked files in {} after editing: {}. The \
                     worktree was kept for recovery.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        let changed = baseline.ignored_untracked.changed_existing_paths(&after);
        if changed.is_empty() {
            return Ok(AllowedArtifacts::default());
        }
        let (ignored, changed): (Vec<_>, Vec<_>) = changed
            .into_iter()
            .partition(|path| baseline.ignored_untracked.ignored_file_move(&after, path));
        if changed.is_empty() {
            return Ok(AllowedArtifacts::split(ignored, &after));
        }
        let listed = list_paths(&changed);
        Err(uncertain_worktree_change(
            cwd,
            format!(
                "the editing call changed or deleted existing untracked file(s) in {}: \
                 {listed}. The worktree was kept for recovery.",
                cwd.display()
            ),
        ))
    }

    /// Refuse a byte or mode change that the index did not represent.
    ///
    /// Clean filters can normalize a working file back to its existing blob,
    /// and index flags can hide a change from porcelain status. Comparing the
    /// actual tracked files on both sides keeps those bytes from being treated
    /// as disposable just because Git has no diff for them.
    pub(crate) fn refuse_unrepresented_tracked_changes(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<()> {
        self.refuse_changed_attributes(cwd, baseline)?;
        let after = safe_git_state(cwd).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify tracked files in {} after editing: {}. The worktree was \
                     kept for recovery.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        let mut changed = Vec::new();
        let before_filter_untracked = ignored_untracked_state(cwd).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not record untracked files before verifying transformed content in {}: \
                     {}. The worktree was kept for recovery.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        let mut filter_was_run = false;
        let mut filter_problem = None;
        let mut repositories: BTreeSet<PathBuf> =
            baseline.git_state.repositories.keys().cloned().collect();
        repositories.extend(after.repositories.keys().cloned());
        'repositories: for repository_path in repositories {
            let before_repository = baseline.git_state.repositories.get(&repository_path);
            let after_repository = after.repositories.get(&repository_path);
            if before_repository.is_none() || after_repository.is_none() {
                changed.push(repository_path.clone());
                continue;
            }
            if before_repository.map(|repository| &repository.gitlinks)
                != after_repository.map(|repository| &repository.gitlinks)
            {
                changed.push(repository_path.join("<gitlinks>"));
            }
            let mut paths = BTreeSet::new();
            if let Some(repository) = before_repository {
                paths.extend(repository.tracked.keys().cloned());
            }
            if let Some(repository) = after_repository {
                paths.extend(repository.tracked.keys().cloned());
            }
            for path in paths {
                let before = before_repository.and_then(|repository| repository.tracked.get(&path));
                let current = after_repository.and_then(|repository| repository.tracked.get(&path));
                let worktree_changed =
                    before.map(|entry| &entry.worktree) != current.map(|entry| &entry.worktree);
                let index_changed = before.map(|entry| (&entry.index_mode, &entry.index_oid))
                    != current.map(|entry| (&entry.index_mode, &entry.index_oid));
                if !worktree_changed {
                    continue;
                }
                if !index_changed {
                    changed.push(repository_path.join(&path));
                    continue;
                }
                let before_worktree = before.and_then(|entry| entry.worktree.as_ref());
                let current_worktree = current.and_then(|entry| entry.worktree.as_ref());
                let Some(current_entry) = current else {
                    continue;
                };
                let Some(current_worktree) = current_worktree else {
                    continue;
                };
                let content_changed =
                    before_worktree.map(|file| file.content) != Some(current_worktree.content);
                let mode_changed = before_worktree.map(|file| file.mode.as_str())
                    != Some(current_worktree.mode.as_str());
                let repository = cwd.join(&repository_path);
                let represented_content = if content_changed {
                    filter_was_run = true;
                    let result =
                        filtered_index_content(&repository, &path, &current_entry.index_oid);
                    self.refuse_changed_attributes(cwd, baseline)?;
                    match result {
                        Ok(expected) => expected == current_worktree.content,
                        Err(error) => {
                            filter_problem = Some(format!(
                                "could not verify transformed content for {:?}: {}",
                                repository_path.join(&path),
                                error.last_line()
                            ));
                            false
                        }
                    }
                } else {
                    true
                };
                let represented_mode =
                    !mode_changed || current_worktree.mode == current_entry.index_mode;
                if !represented_content || !represented_mode {
                    changed.push(repository_path.join(&path));
                }
                if filter_problem.is_some() {
                    break 'repositories;
                }
            }
        }
        if filter_was_run {
            self.refuse_changed_attributes(cwd, baseline)?;
            let verified = safe_git_state(cwd).map_err(|e| {
                uncertain_worktree_change(
                    cwd,
                    format!(
                        "could not recheck tracked files after verifying transformed content in \
                         {}: {}. The worktree was kept for recovery.",
                        cwd.display(),
                        e.last_line()
                    ),
                )
            })?;
            let verified_untracked = ignored_untracked_state(cwd).map_err(|e| {
                uncertain_worktree_change(
                    cwd,
                    format!(
                        "could not recheck untracked files after verifying transformed content \
                         in {}: {}. The worktree was kept for recovery.",
                        cwd.display(),
                        e.last_line()
                    ),
                )
            })?;
            if verified != after
                || before_filter_untracked.changed_beyond_generated(&verified_untracked)
            {
                return Err(uncertain_worktree_change(
                    cwd,
                    "a content filter changed the worktree while SPAR verified the managed \
                     commit. The worktree was kept for recovery.",
                ));
            }
            self.refuse_changed_existing_untracked(cwd, baseline)?;
        }
        if let Some(problem) = filter_problem {
            return Err(uncertain_worktree_change(
                cwd,
                format!("{problem}. The worktree was kept for recovery."),
            ));
        }
        if changed.is_empty() {
            return Ok(());
        }
        let listed = list_paths(&changed);
        Err(uncertain_worktree_change(
            cwd,
            format!(
                "the editing call changed tracked working-file bytes, modes, repositories, or \
                 gitlinks outside an accepted commit: {listed}. The worktree was kept for \
                 recovery."
            ),
        ))
    }

    pub(crate) fn refuse_changed_attributes(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
    ) -> Result<()> {
        let after = attribute_state(cwd).map_err(|e| {
            uncertain_worktree_change(
                cwd,
                format!(
                    "could not verify attribute files in {} after editing: {}. The worktree was \
                     kept for recovery.",
                    cwd.display(),
                    e.last_line()
                ),
            )
        })?;
        if after == baseline.attributes {
            return Ok(());
        }
        Err(uncertain_worktree_change(
            cwd,
            format!(
                "the editing call changed a .gitattributes file in {}. It was kept, but SPAR \
                 refused to run a Git operation that could select a new external filter.",
                cwd.display()
            ),
        ))
    }

    /// Commit a successful editing call from the trusted harness process.
    ///
    /// Editing sandboxes only need the working tree. They never need writable
    /// access to the repository's object database, refs, config, or hooks.
    pub(crate) fn commit_pending_changes(
        &self,
        cwd: &Path,
        baseline: &WorktreeBaseline,
        preferred_subject: &str,
        fallback_subject: &str,
    ) -> Result<bool> {
        let mut artifacts = IgnoredArtifacts::default();
        self.refuse_changed_attributes(cwd, baseline)?;
        artifacts.changed(self.allow_changed_ignored_artifacts(cwd, baseline)?);
        refuse_unsafe_index_flags(cwd)?;
        if !self.has_uncommitted_changes(cwd)? {
            artifacts.left(self.allow_ignored_files(cwd, baseline)?);
            artifacts.report(cwd);
            return Ok(false);
        }
        self.stage_managed_changes(cwd, baseline).map_err(|e| {
            e.with_message(format!(
                "could not stage changes in {}: {}",
                cwd.display(),
                e.last_line()
            ))
        })?;
        // Git ignore rules decide which files stay outside the commit.
        // Whether cleanup can delete them is a separate decision.
        artifacts.left(self.allow_ignored_files(cwd, baseline)?);
        let changed_gitlinks = changed_staged_gitlinks(cwd)?;
        if !changed_gitlinks.is_empty() {
            let listed = list_paths(&changed_gitlinks);
            bail!(
                "the editing call added or changed a gitlink at {listed}. It was staged but not \
                 committed because the referenced repository objects might exist only inside \
                 this worktree. The worktree was kept for recovery."
            );
        }
        let mut subject = self.clean_title(preferred_subject)?;
        if subject.trim().is_empty() {
            subject = self.clean_title(fallback_subject)?;
        }
        self.commit_staged_changes(cwd, &subject).map_err(|e| {
            e.with_message(format!(
                "could not commit changes in {}: {}. The staged files were kept.",
                cwd.display(),
                e.last_line()
            ))
        })?;
        if has_tracked_or_staged_work(cwd)? {
            bail!(
                "the commit in {} left additional uncommitted files. They were kept for \
                 recovery.",
                cwd.display()
            );
        }
        artifacts.changed(self.allow_changed_ignored_artifacts(cwd, baseline)?);
        artifacts.left(self.allow_ignored_files(cwd, baseline)?);
        artifacts.report(cwd);
        Ok(true)
    }

    fn stage_managed_changes(&self, cwd: &Path, baseline: &WorktreeBaseline) -> Result<()> {
        let after = ignored_untracked_state(cwd)?;
        self.git_at_without_automation(cwd, &["add", "-u"])?;
        let paths = baseline.ignored_untracked.new_ordinary_paths(&after);
        if paths.is_empty() {
            return Ok(());
        }
        let mut input = Vec::new();
        for path in paths {
            input.extend(os_str_bytes(path.as_os_str())?);
            input.push(0);
        }
        let argv = git_without_automation_argv(&[
            "--literal-pathspecs",
            "add",
            "--pathspec-from-file=-",
            "--pathspec-file-nul",
        ]);
        proc::run_with_input_bytes(
            &argv,
            &self.git_opts(Some(cwd), true).stop_descendants(true),
            &input,
        )?;
        Ok(())
    }

    /// Commit an index prepared by the parent without signing, hooks, or
    /// inherited repository automation.
    pub(crate) fn commit_staged_changes(&self, cwd: &Path, subject: &str) -> Result<()> {
        self.git_at_without_automation(cwd, &["commit", "--no-verify", "-m", subject])
            .map(|_| ())
    }

    /// How many commits `refname` carries that the base does not.
    ///
    /// Counted from the commits themselves rather than from `commit_subjects`,
    /// which drops a commit whose message is empty. The guards in
    /// `worktree_add` decide whether to delete a branch on this number, and an
    /// empty message must not read as an empty branch.
    pub fn commit_count(&self, cwd: &Path, refname: &str, base: &str) -> usize {
        let range = format!("{}..{refname}", self.base_ref(cwd, base));
        self.git_try_at(Some(cwd), &["rev-list", "--count", &range])
            .trim()
            .parse()
            .unwrap_or(0)
    }

    /// One `hash subject` line per commit `refname` carries that the base does
    /// not, oldest first. For showing a person what is on a branch, so the
    /// hash keeps a commit with no message from listing as nothing.
    pub fn commit_lines(&self, cwd: &Path, refname: &str, base: &str) -> Vec<String> {
        let range = format!("{}..{refname}", self.base_ref(cwd, base));
        self.git_try_at(Some(cwd), &["log", &range, "--reverse", "--format=%h %s"])
            .lines()
            .map(str::to_string)
            .collect()
    }

    /// The commits `later` carries that `earlier` does not, oldest first, when
    /// `earlier` is genuinely behind it.
    ///
    /// `None` when it is not an ancestor, which is not the same as nothing
    /// having landed. `rewrite_commits_if_needed` rewrites hashes from the first
    /// offending commit spar made onward, so a head recorded part way through a
    /// round can still be a readable object and no longer be on the branch. `git log` answers that
    /// with every commit on the branch, so without the check the one caller
    /// would report the whole branch as unread, which is the widest possible
    /// wrong answer.
    ///
    /// No `base_ref` resolution, unlike its neighbours: these are commits rather
    /// than branch names, and putting a sha through it logs a fallback line
    /// every time.
    pub fn commits_since(&self, cwd: &Path, earlier: &str, later: &str) -> Option<Vec<String>> {
        let ancestor = self
            .git_at(Some(cwd), &["merge-base", "--is-ancestor", earlier, later])
            .is_ok();
        if !ancestor {
            return None;
        }
        let range = format!("{earlier}..{later}");
        Some(
            self.git_try_at(Some(cwd), &["log", &range, "--reverse", "--format=%h %s"])
                .lines()
                .map(str::to_string)
                .collect(),
        )
    }

    /// The subjects of the commits `refname` carries that the base does not,
    /// oldest first.
    pub fn commit_subjects(&self, cwd: &Path, refname: &str, base: &str) -> Vec<String> {
        let range = format!("{}..{refname}", self.base_ref(cwd, base));
        self.git_try_at(Some(cwd), &["log", &range, "--reverse", "--format=%s"])
            .lines()
            .map(str::trim)
            .filter(|line| !line.is_empty())
            .map(str::to_string)
            .collect()
    }

    /// The paths this checkout changes relative to the base, sorted.
    ///
    /// A three dot range, matching `diff_stat`: what the branch did, not what
    /// the base has done since.
    ///
    /// `--no-renames` because a rename reported as its destination alone leaves
    /// the source out of the list, and a part carrying only the destination
    /// would be a copy. As a deletion and an addition it is two paths, which a
    /// part can carry together or leave to the leftover report.
    ///
    /// `-z` because without it git writes paths for display: anything
    /// non-ASCII comes back escaped and wrapped in quotes, and that string is
    /// not a path. A part built from one carries a pathspec matching no file,
    /// so the file never reaches the slice while every list still says the part
    /// took it. It also keeps a path with a space at either end intact.
    pub fn changed_files(&self, cwd: &Path, base: &str) -> Vec<String> {
        let range = format!("{}...HEAD", self.base_ref(cwd, base));
        self.git_try_at(
            Some(cwd),
            &["diff", "--name-only", "--no-renames", "-z", &range],
        )
        .split('\0')
        .filter(|path| !path.is_empty())
        .map(str::to_string)
        .collect()
    }

    /// The files one commit range touched, for checking a claim against the
    /// diff rather than against the report that made it.
    pub fn files_changed_between(&self, cwd: &Path, from: &str, to: &str) -> Vec<String> {
        self.git_try_at(
            Some(cwd),
            &[
                "diff",
                "--name-only",
                "--no-renames",
                "-z",
                &format!("{from}..{to}"),
            ],
        )
        .split('\0')
        .filter(|path| !path.is_empty())
        .map(str::to_string)
        .collect()
    }

    /// Where `refname` left the base: the commit its own change is measured
    /// from, and the one a slice of that change has to be taken against.
    pub fn merge_base(&self, cwd: &Path, base: &str, refname: &str) -> Result<String> {
        let base_ref = self.base_ref(cwd, base);
        let out = self
            .git_at(Some(cwd), &["merge-base", &base_ref, refname])
            .map_err(|e| {
                spar_err!(
                    "could not find where {refname} and {base_ref} diverged. {}",
                    e.last_line()
                )
            })?;
        let sha = out.trim().to_string();
        if sha.is_empty() {
            bail!("{refname} and {base_ref} share no history");
        }
        Ok(sha)
    }

    pub fn diff_stat(&self, cwd: &Path, base: &str) -> String {
        let range = format!("{}...HEAD", self.base_ref(cwd, base));
        let full = self.git_try_at(Some(cwd), &["diff", &range, "--shortstat"]);
        full.trim().to_string()
    }

    /// Scrub commit messages that slipped past the prompt.
    ///
    /// `git filter-branch` calls back into this same binary, so there is no
    /// interpreter to find and no second copy of the rules to drift.
    ///
    /// `floor` is the head spar found when it started, and nothing at or below
    /// it is rewritten. The style gate is for what spar writes, and a person's
    /// commit message is not that: rewriting one changes a published SHA, which
    /// diverges the branch under somebody's own checkout and is exactly the
    /// history rewrite this design promises never to do. A `None` floor means
    /// every commit above the base is spar's own, which is true of a branch
    /// spar created in this invocation and of nothing else.
    pub fn rewrite_commits_if_needed(
        &self,
        cwd: &Path,
        base: &str,
        floor: Option<&str>,
    ) -> Result<()> {
        let base_ref = self.base_ref(cwd, base);
        let floor = floor.filter(|f| !f.trim().is_empty()).unwrap_or(&base_ref);
        self.report_commits_left_alone(cwd, &base_ref, floor);

        let range = format!("{floor}..HEAD");
        let raw = self.git_try_at(Some(cwd), &["log", &range, "--format=%H%x00%B%x1e"]);

        let offenders = raw
            .split('\x1e')
            .filter_map(|entry| entry.split_once('\0'))
            .filter(|(_, body)| !style::violations(body, &self.style).is_empty())
            .count();
        if offenders == 0 {
            return Ok(());
        }
        logdim!("{offenders} commit message(s) violated style rules, rewriting");

        let exe = self_binary()?;
        let filter = format!("{} scrub-filter", sh_quote(&exe.display().to_string()));

        let argv: Vec<String> = [
            "git",
            "filter-branch",
            "-f",
            "--msg-filter",
            &filter,
            &range,
        ]
        .iter()
        .map(|s| s.to_string())
        .collect();
        let opts = ExecOpts::new()
            .cwd(cwd)
            .check(false)
            .timeout_secs(600)
            .env("FILTER_BRANCH_SQUELCH_WARNING", "1")
            .env("SPAR_BAN_EM_DASH", bool_env(self.style.ban_em_dash))
            .env(
                "SPAR_BAN_AI_ATTRIBUTION",
                bool_env(self.style.ban_ai_attribution),
            );
        let _ = proc::run(&argv, &opts);

        let after = self.git_try_at(Some(cwd), &["log", &range, "--format=%B"]);
        if !style::violations(&after, &self.style).is_empty() {
            bail!(
                "commit messages still violate style rules after a rewrite in {}.",
                cwd.display()
            );
        }
        Ok(())
    }

    /// Say out loud when a message spar will not touch breaks the style rules.
    ///
    /// Silence here would read as "there was nothing to scrub", and the point
    /// of the floor is that there was something and spar chose to leave it.
    fn report_commits_left_alone(&self, cwd: &Path, base_ref: &str, floor: &str) {
        if floor == base_ref {
            return;
        }
        let raw = self.git_try_at(
            Some(cwd),
            &[
                "log",
                &format!("{base_ref}..{floor}"),
                "--format=%H%x00%B%x1e",
            ],
        );
        let left: Vec<&str> = raw
            .split('\x1e')
            .filter_map(|entry| entry.split_once('\0'))
            .filter(|(_, body)| !style::violations(body, &self.style).is_empty())
            .map(|(hash, _)| &hash.trim()[..hash.trim().len().min(8)])
            .collect();
        if left.is_empty() {
            return;
        }
        logdim!(
            "{} commit message(s) already on the branch break the style rules and were left \
             alone: {}. spar does not rewrite commits it did not write.",
            left.len(),
            left.join(", ")
        );
    }

    /// Push by explicit refspec from HEAD, leasing the head spar reviewed.
    ///
    /// A resumed PR is checked out under a local name (`pr-N`) that does not
    /// match its remote branch, so pushing by branch name would resolve the
    /// wrong local ref or fail outright.
    ///
    /// `expected` is the remote head spar last read. A bare `--force-with-lease`
    /// leases the implicit tracking ref instead, which is shared across every
    /// worktree and is updated by any `git fetch`. The editing agent is a real
    /// CLI with shell access, and fetching is a normal thing for it to do: one
    /// `git fetch` mid round moves the tracking ref to whatever the remote holds
    /// and the lease then passes against a head spar never reviewed, which
    /// silently drops somebody's commit. Naming the head makes the push refuse
    /// exactly that case.
    pub fn push(&self, cwd: &Path, branch: &str, expected: Option<&str>) -> Result<()> {
        let expected = expected.map(str::trim).filter(|head| !head.is_empty());
        if let Some(head) = expected {
            self.refuse_push_that_drops(cwd, head)?;
        }
        let refspec = format!("HEAD:{branch}");
        let lease = match expected {
            Some(head) => format!("--force-with-lease=refs/heads/{branch}:{head}"),
            None => "--force-with-lease".to_string(),
        };
        let pushed = self
            .git_at(Some(cwd), &["push", &lease, "origin", &refspec])
            .map(|_| ())
            .map_err(|e| {
                spar_err!(
                    "could not push to origin/{branch}. {}\nCheck push access and whether the \
                     branch moved under you.",
                    e.last_line()
                )
            });
        self.record_write(pushed)
    }

    /// Refuse a push whose HEAD does not contain the head spar reviewed.
    ///
    /// The lease answers the remote moving. This answers the local side moving:
    /// an agent that reset or rebased the worktree leaves a HEAD that would
    /// publish over the reviewed head rather than on top of it, and the lease
    /// cannot tell the difference because the remote is exactly where spar left
    /// it.
    fn refuse_push_that_drops(&self, cwd: &Path, expected: &str) -> Result<()> {
        let head = self.head_oid_checked(cwd)?;
        if head == expected || self.is_ancestor_checked(cwd, expected, &head)? {
            return Ok(());
        }
        bail!(
            "refusing to push {head} because it does not contain the reviewed head {expected}. \
             The worktree at {} was kept and nothing was published. Restore {expected} or reapply \
             the intended commits on top of it before resuming.",
            cwd.display()
        )
    }

    /// Create one remote branch for a split without ever moving an existing ref.
    ///
    /// `worktree_for_split` chooses a name that is free locally and on origin,
    /// but another writer can still take it before the push. An empty expected
    /// value in the lease makes this an atomic create: it creates an absent ref,
    /// accepts an identical ref as a no-op, and never moves an existing ref.
    /// The shared `push` method cannot be used because its lease permits
    /// updating a ref fetched earlier.
    pub fn push_split_branch(
        &self,
        cwd: &Path,
        branch: &str,
    ) -> std::result::Result<(), SplitPushError> {
        let remote_ref = format!("refs/heads/{branch}");
        let lease = format!("--force-with-lease={remote_ref}:");
        let refspec = format!("HEAD:{remote_ref}");
        let result = match self.git_at(Some(cwd), &["push", &lease, "origin", &refspec]) {
            Ok(_) => Ok(()),
            Err(push_error) => {
                let local = self.git_at(Some(cwd), &["rev-parse", "HEAD"]);
                let remote = self.git(&["ls-remote", "--heads", "origin", &remote_ref]);
                reconcile_failed_split_push(branch, push_error, local, remote)
            }
        };
        self.record_write(result)
    }

    // -- gh ---------------------------------------------------------------

    pub fn gh(&self, args: &[&str]) -> Result<String> {
        self.gh_at(None, args)
    }

    pub fn gh_at(&self, cwd: Option<&Path>, args: &[&str]) -> Result<String> {
        let mut argv = vec!["gh".to_string()];
        argv.extend(args.iter().map(|s| s.to_string()));
        proc::run(
            &argv,
            &ExecOpts::new()
                .cwd(cwd.unwrap_or(&self.root))
                .timeout_secs(300),
        )
    }

    /// Run gh with something on its stdin.
    ///
    /// A tracker body is far too long to pass on argv, and `--body-file -` is
    /// how gh takes one. `proc::exec` already wires the pipe, so this is a
    /// sibling of `gh_at` rather than anything new.
    pub fn gh_stdin(&self, args: &[&str], stdin: &str) -> Result<String> {
        let mut argv = vec!["gh".to_string()];
        argv.extend(args.iter().map(|s| s.to_string()));
        proc::run(
            &argv,
            &ExecOpts::new()
                .cwd(&self.root)
                .timeout_secs(300)
                .stdin(stdin),
        )
    }

    pub fn gh_try(&self, args: &[&str]) -> String {
        let mut argv = vec!["gh".to_string()];
        argv.extend(args.iter().map(|s| s.to_string()));
        proc::run(
            &argv,
            &ExecOpts::new()
                .cwd(&self.root)
                .check(false)
                .timeout_secs(300),
        )
        .unwrap_or_default()
    }

    /// `gh api -i`: the status line and headers with the body, and the exit
    /// code ignored on purpose. A `304 Not Modified`, which is the answer a
    /// conditional poll wants, makes gh exit 1 while printing exactly what is
    /// needed. Only a spawn failure or a timeout is an error here.
    pub fn gh_api_raw(&self, endpoint: &str, headers: &[(&str, &str)]) -> Result<ApiResponse> {
        let mut argv = vec!["gh".to_string(), "api".to_string(), "-i".to_string()];
        for (name, value) in headers {
            argv.push("-H".to_string());
            argv.push(format!("{name}: {value}"));
        }
        argv.push(endpoint.to_string());
        let out = proc::exec(
            &argv,
            &ExecOpts::new()
                .cwd(&self.root)
                .check(false)
                .timeout_secs(300),
        )?;
        parse_api_response(&out.stdout)
            .ok_or_else(|| crate::error::SparError::call_failed(proc::failure_message(&argv, &out)))
    }

    /// Every open pull request, with what a sweep needs to know about each.
    pub fn sweep_open_prs(&self) -> Result<Vec<PrSweepRow>> {
        let text = self.gh(&[
            "pr",
            "list",
            "--state",
            "open",
            "--limit",
            "500",
            "--json",
            PR_SWEEP_FIELDS,
        ])?;
        serde_json::from_str(&text)
            .map_err(|e| spar_err!("unexpected shape for the pull request list: {e}"))
    }

    /// One pull request, open or not, with what a sweep needs to know.
    pub fn sweep_pr(&self, number: i64) -> Result<PrSweepRow> {
        let text = self.gh(&["pr", "view", &number.to_string(), "--json", PR_SWEEP_FIELDS])?;
        serde_json::from_str(&text).map_err(|e| spar_err!("unexpected shape for PR #{number}: {e}"))
    }

    /// Whether `login` is in a team, named `org/slug` as gh gives a team in
    /// `reviewRequests`. GitHub answers 404 for a team the login is not in, and
    /// a team the viewer is in is one it can always see. None when GitHub did
    /// not answer either way.
    pub fn team_has_member(&self, team: &str, login: &str) -> Option<bool> {
        // A team asked for a review belongs to the repository's own owner.
        let (org, slug) = team.split_once('/').unwrap_or(("{owner}", team));
        if slug.is_empty() || login.is_empty() {
            return None;
        }
        let path = format!("orgs/{org}/teams/{slug}/memberships/{login}");
        let resp = self.gh_api_raw(&path, &[]).ok()?;
        match resp.status {
            200 => {
                let body: Value = serde_json::from_str(&resp.body).ok()?;
                Some(body.get("state")?.as_str()? == "active")
            }
            404 => Some(false),
            _ => None,
        }
    }

    /// How many commits lie between two SHAs, when GitHub will say.
    pub fn commits_between(&self, from: &str, to: &str) -> Option<u64> {
        if from.is_empty() || to.is_empty() {
            return None;
        }
        let path = format!("repos/{{owner}}/{{repo}}/compare/{from}...{to}");
        self.gh_try(&["api", &path, "--jq", ".total_commits"])
            .trim()
            .parse()
            .ok()
    }

    /// `owner/name`, for the line that says what is being watched.
    pub fn repo_name(&self) -> Option<String> {
        let name = self.gh_try(&[
            "repo",
            "view",
            "--json",
            "nameWithOwner",
            "--jq",
            ".nameWithOwner",
        ]);
        let name = name.trim();
        (!name.is_empty()).then(|| name.to_string())
    }

    pub fn listen_state_path(&self) -> PathBuf {
        self.root.join(STATE_DIR).join("state").join("listen.json")
    }

    pub fn listen_lock_path(&self) -> PathBuf {
        self.root.join(STATE_DIR).join("state").join("listen.lock")
    }

    /// The login `gh` is authenticated as.
    ///
    /// A hard error, never a degradation. Everything spar wrote has to be
    /// excluded from what it answers, and custody cannot be read from git
    /// authorship, so this is the only thing that tells spar's own comments
    /// from somebody else's. Without it the failure is not "answers a bit too
    /// much", it is a thread where spar answers itself until somebody notices.
    ///
    /// Not cached on disk: `gh auth switch` between runs would make a stored
    /// answer wrong in exactly the way that produces that thread.
    pub fn viewer_login(&self) -> Result<&str> {
        if let Some(login) = self.viewer.get() {
            return Ok(login);
        }
        let rest = self.gh_try(&["api", "user", "--jq", ".login"]);
        let login = if !rest.trim().is_empty() {
            rest.trim().to_string()
        } else {
            // A token that cannot read /user can still answer for itself in
            // GraphQL, which is the case on some Enterprise installs.
            self.gh(&[
                "api",
                "graphql",
                "-f",
                "query={ viewer { login } }",
                "--jq",
                ".data.viewer.login",
            ])
            .map_err(|e| {
                spar_err!(
                    "could not find out who `gh` is authenticated as, so spar cannot tell its \
                     own comments from anybody else's. {}\nRun `gh auth status`.",
                    e.last_line()
                )
            })?
            .trim()
            .to_string()
        };
        if login.is_empty() {
            bail!("`gh` reported an empty login. Run `gh auth status`.");
        }
        Ok(self.viewer.get_or_init(|| login))
    }

    /// One issue as it stands, open or closed.
    ///
    /// `fetch_issues` reads a queue to work: it drops a closed issue and fails
    /// when nothing survives. Both are wrong for reading one issue back, where
    /// closed is an answer and the empty case cannot arise.
    pub fn read_issue(&self, number: i64) -> Result<Issue> {
        let text = self
            .gh(&["issue", "view", &number.to_string(), "--json", ISSUE_FIELDS])
            .map_err(|e| spar_err!("could not read issue #{number}: {}", e.last_line()))?;
        serde_json::from_str(&text)
            .map_err(|e| spar_err!("unexpected shape for issue #{number}: {e}"))
    }

    pub fn fetch_issues(&self, numbers: &[i64]) -> Result<Vec<Issue>> {
        let mut issues = Vec::new();
        for number in numbers {
            let text = self
                .gh(&["issue", "view", &number.to_string(), "--json", ISSUE_FIELDS])
                .map_err(|e| spar_err!("could not read issue #{number}: {}", e.last_line()))?;
            let issue: Issue = serde_json::from_str(&text)
                .map_err(|e| spar_err!("unexpected shape for issue #{number}: {e}"))?;
            if issue.is_closed() {
                crate::log!("issue #{number} is closed, skipping");
                continue;
            }
            issues.push(issue);
        }
        if issues.is_empty() {
            bail!("no open issues to work on");
        }
        Ok(issues)
    }

    /// Open items, lowest numbered first, from `min_number` upward.
    ///
    /// The floor exists because a long lived repository accumulates a tail of
    /// old issues nobody is going to get to, and taking the lowest numbered
    /// open items means walking straight into them.
    fn open_numbers(&self, kind: &str, limit: usize, min_number: i64) -> Result<Vec<i64>> {
        #[derive(Deserialize)]
        struct Row {
            number: i64,
        }
        let text = self.gh(&[
            kind,
            "list",
            "--state",
            "open",
            "--limit",
            &FETCH_CEILING.to_string(),
            "--json",
            "number",
        ])?;
        let rows: Vec<Row> = serde_json::from_str(text.trim()).unwrap_or_default();
        let mut numbers: Vec<i64> = rows.into_iter().map(|r| r.number).collect();
        numbers.sort_unstable();

        let noun = if kind == "issue" { "issues" } else { "PRs" };
        let found = numbers.len();
        if min_number > 0 {
            numbers.retain(|n| *n >= min_number);
            let skipped = found - numbers.len();
            if skipped > 0 {
                crate::log!("{skipped} open {noun} below #{min_number} skipped");
            }
        }
        if found >= FETCH_CEILING {
            crate::log!(
                "more than {FETCH_CEILING} open {noun}; only the first {FETCH_CEILING} were \
                 considered."
            );
        }
        if numbers.len() > limit {
            crate::log!(
                "{} open {noun}, taking the {limit} lowest numbered. Raise --limit or name them \
                 explicitly.",
                numbers.len()
            );
            numbers.truncate(limit);
        }
        Ok(numbers)
    }

    /// Open issues, lowest numbered first. `gh issue list` excludes PRs.
    pub fn list_open_issues(&self, limit: usize, min_number: i64) -> Result<Vec<i64>> {
        self.open_numbers("issue", limit, min_number)
    }

    pub fn list_open_prs(&self, limit: usize, min_number: i64) -> Result<Vec<i64>> {
        self.open_numbers("pr", limit, min_number)
    }

    pub fn pr_for_branch(&self, branch: &str) -> Option<PrRef> {
        self.branch_prs(branch, "open").into_iter().next()
    }

    /// The open pull request for a branch, preserving a failed lookup as an
    /// error when the caller is deciding whether a write already landed.
    pub fn try_pr_for_branch(&self, branch: &str, base: &str) -> Result<Option<PrRef>> {
        let text = self.gh(&[
            "pr",
            "list",
            "--head",
            branch,
            "--base",
            base,
            "--state",
            "open",
            "--json",
            "number,url,title,baseRefName",
        ])?;
        pr_for_base(&text, branch, base)
    }

    /// Every pull request opened from this branch, merged and closed ones
    /// included, because a commit is preserved by whichever one carries it and
    /// that is rarely the newest.
    fn prs_for_branch(&self, branch: &str) -> Vec<PrRef> {
        self.branch_prs(branch, "all")
    }

    fn branch_prs(&self, branch: &str, state: &str) -> Vec<PrRef> {
        let text = self.gh_try(&[
            "pr",
            "list",
            "--head",
            branch,
            "--state",
            state,
            "--json",
            "number,url,title",
        ]);
        serde_json::from_str::<Vec<PrRef>>(text.trim()).unwrap_or_default()
    }

    /// Whether a number names an issue or a pull request.
    ///
    /// `gh issue view` happily returns a pull request when handed its number,
    /// so it cannot be used to tell them apart. The issues API carries both and
    /// marks a pull request with a `pull_request` key, which is definitive.
    pub fn item_kind(&self, number: i64) -> Result<ItemKind> {
        let path = format!("repos/{{owner}}/{{repo}}/issues/{number}");
        let text = self
            .gh(&[
                "api",
                &path,
                "--jq",
                "if .pull_request then \"pr\" else \"issue\" end",
            ])
            .map_err(|e| {
                spar_err!(
                    "no issue or pull request #{number} in this repository. {}",
                    e.last_line()
                )
            })?;
        match text.trim() {
            "pr" => Ok(ItemKind::Pr),
            "issue" => Ok(ItemKind::Issue),
            other => Err(spar_err!(
                "could not tell whether #{number} is an issue or a pull request (got {other:?})"
            )),
        }
    }

    /// An open pull request that would close this issue, whoever opened it.
    ///
    /// spar's own branch naming is checked first because it is exact and cheap.
    /// Falling back to GitHub's own issue linkage is what lets spar pick up a
    /// pull request a person started on a branch named anything at all.
    ///
    /// An error rather than `None` when the question could not be asked. The
    /// two answers are not interchangeable: "no pull request exists" is the one
    /// that makes spar implement over the top of somebody's work and open a
    /// second pull request for the same issue.
    pub fn try_open_pr_for_issue(&self, issue: i64, base: &str) -> Result<Option<PrRef>> {
        let mine = self.pr_for_branch_failing_closed(&self.branch_for_issue(issue), base, issue)?;
        if let Some(pr) = mine {
            return Ok(Some(pr));
        }
        let listed = match self.gh(&[
            "pr",
            "list",
            "--state",
            "open",
            "--limit",
            &FETCH_CEILING.to_string(),
            "--json",
            "number,url,title,baseRefName,closingIssuesReferences",
        ]) {
            Ok(text) => linked_pr_rows(&text).ok_or_else(|| {
                spar_err!("could not read the pull request list while looking for #{issue}")
            })?,
            Err(e) => return self.unanswered_pr_lookup(issue, e).map(|()| None),
        };
        if listed.len() >= FETCH_CEILING {
            logwarn!(
                "#{issue}: the open pull request list filled its page of {FETCH_CEILING}, so a                  pull request past it cannot be seen from here."
            );
        }
        let default = self.default_branch(base);
        if !base.eq_ignore_ascii_case(&default) {
            // GitHub populates closingIssuesReferences only for pull requests
            // targeting the default branch, so on any other base the linkage is
            // silence rather than an answer.
            logwarn!(
                "#{issue}: the base branch is `{base}` and the default is `{default}`. GitHub                  links closing issues only on the default branch, so an existing pull request                  for this issue may not be found. Name the pull request instead of the issue if                  there is one."
            );
        }
        Ok(pick_linked_pr(&listed, issue))
    }

    /// spar's own branch, with a failed lookup kept as a failure.
    fn pr_for_branch_failing_closed(
        &self,
        branch: &str,
        base: &str,
        issue: i64,
    ) -> Result<Option<PrRef>> {
        match self.try_pr_for_branch(branch, base) {
            Ok(found) => Ok(found),
            Err(e) => self.unanswered_pr_lookup(issue, e).map(|()| None),
        }
    }

    /// What to do when GitHub would not say whether a pull request exists.
    ///
    /// An error, because "no pull request exists" is the answer that makes spar
    /// implement from scratch and open a second pull request over somebody's
    /// work. The one exception is a repository gh cannot reach at all: there is
    /// no pull request to collide with when there is no GitHub repository in
    /// play, and every later write would fail anyway. That case is a warning and
    /// a `None`, so a run against a plain git remote behaves as it always did.
    fn unanswered_pr_lookup(&self, issue: i64, e: crate::error::SparError) -> Result<()> {
        if self.gh(&["repo", "view", "--json", "name"]).is_ok() {
            return Err(spar_err!(
                "could not check whether a pull request already exists for #{issue}: {}. \
                 Refusing to implement over the top of work that may already be open.",
                e.last_line()
            ));
        }
        logwarn!(
            "#{issue}: this repository could not be read through gh ({}), so spar cannot tell \
             whether a pull request already exists for it.",
            e.last_line()
        );
        Ok(())
    }

    pub fn pr_view(&self, number: i64) -> Result<PrView> {
        let text = self.gh(&[
            "pr",
            "view",
            &number.to_string(),
            "--json",
            "number,url,title,body,headRefName,baseRefName,state,closingIssuesReferences,isCrossRepository",
        ])?;
        serde_json::from_str(&text).map_err(|e| spar_err!("unexpected shape for PR #{number}: {e}"))
    }

    fn try_pr_state(&self, number: i64) -> Result<String> {
        let text = self.gh(&["pr", "view", &number.to_string(), "--json", "state"])?;
        serde_json::from_str::<Value>(text.trim())
            .map_err(|e| spar_err!("unexpected shape for PR #{number}: {e}"))?
            .get("state")
            .and_then(Value::as_str)
            .map(str::to_string)
            .ok_or_else(|| spar_err!("PR #{number} did not include a state"))
    }

    pub fn pr_state(&self, number: i64) -> String {
        self.try_pr_state(number).unwrap_or_default()
    }

    /// The commit currently exposed as a pull request's head.
    pub fn pr_head_oid(&self, number: i64) -> Result<String> {
        let text = self.gh(&["pr", "view", &number.to_string(), "--json", "headRefOid"])?;
        let oid = serde_json::from_str::<Value>(&text)
            .ok()
            .and_then(|value| {
                value
                    .get("headRefOid")
                    .and_then(Value::as_str)
                    .map(str::trim)
                    .filter(|oid| !oid.is_empty())
                    .map(str::to_string)
            })
            .ok_or_else(|| spar_err!("could not read the head commit for PR #{number}"))?;
        Ok(oid)
    }

    /// Where a pull request's head stands now: what GitHub's pull request
    /// names, and, for a branch in this repository, where `origin` has the
    /// branch. The two differ until GitHub catches up with a push.
    pub fn live_head(&self, pr: &PrView) -> Result<LiveHead> {
        let pull = self.pr_head_oid(pr.number)?;
        let branch = if pr.is_cross_repository || pr.head_ref_name.trim().is_empty() {
            None
        } else {
            let remote_ref = format!("refs/heads/{}", pr.head_ref_name.trim());
            let listed = self
                .git(&["ls-remote", "--heads", "origin", &remote_ref])
                .map_err(|e| {
                    spar_err!(
                        "could not read where {} is on origin: {}",
                        pr.head_ref_name.trim(),
                        e.last_line()
                    )
                })?;
            remote_head_oid(&listed, &remote_ref)?
        };
        Ok(LiveHead { pull, branch })
    }

    pub fn create_pr(
        &self,
        cwd: &Path,
        branch: &str,
        base: &str,
        title: &str,
        body: &str,
    ) -> Result<PrRef> {
        let title = self.record_failed_write(self.clean_title(title))?;
        let body = self.record_failed_write(self.clean(body))?;
        let mut argv = vec![
            "pr", "create", "--base", base, "--head", branch, "--title", &title, "--body", &body,
        ];
        if self.drafts != Drafts::Never {
            argv.push("--draft");
        }
        let created = self.gh_at(Some(cwd), &argv);
        let found = self.try_pr_for_branch(branch, base);
        self.record_write(reconcile_pr_creation(branch, created, found))
    }

    pub fn comment_pr(&self, number: i64, body: &str) -> Result<()> {
        let body = signed(&self.record_failed_write(self.clean(body))?);
        let comments = self.record_failed_write(self.try_issue_comments(number))?;
        if has_exact_comment(&comments, &body) {
            return Ok(());
        }
        let posted = self.gh(&["pr", "comment", &number.to_string(), "--body", &body]);
        let result = match posted {
            Ok(_) => Ok(()),
            Err(post_error) => {
                reconcile_comment_post(number, &body, post_error, self.try_issue_comments(number))
            }
        };
        self.record_write(result)
    }

    /// Whether the viewer wrote this pull request. GitHub refuses to let an
    /// author approve or request changes on their own, so a verdict on one can
    /// only ever be a comment.
    fn pr_is_own(&self, number: i64) -> Result<bool> {
        let text = self.gh(&["pr", "view", &number.to_string(), "--json", "author"])?;
        let author = serde_json::from_str::<Value>(&text)
            .ok()
            .and_then(|v| v.get("author")?.get("login")?.as_str().map(str::to_string))
            .unwrap_or_default();
        let viewer = self.viewer_login()?.to_string();
        Ok(!author.is_empty() && crate::comments::same_login(&author, &viewer))
    }

    /// Submit a formal review, or a comment carrying the verdict's words when
    /// GitHub will not take the verdict: the viewer's own pull request, or no
    /// verdict at all.
    ///
    /// Mirrors `comment_pr` step for step: the style gate, the signature, a
    /// duplicate check against the viewer's own reviews, the write, and a read
    /// back on failure so an unverifiable write is reported as one.
    ///
    /// `commit` is the commit the reviewers read. GitHub attaches a review
    /// that names no commit to whatever the head is when it arrives, so a push
    /// made while a review ran would otherwise receive an approval nobody
    /// gave it. `gh pr review` cannot name one, hence the REST call.
    pub fn submit_review(
        &self,
        number: i64,
        verdict: Option<crate::model::ReviewVerdict>,
        body: &str,
        commit: &str,
    ) -> Result<()> {
        let own = match verdict {
            Some(_) => self.record_failed_write(self.pr_is_own(number))?,
            None => false,
        };
        let text = match (verdict, own) {
            (Some(v), true) => format!("Verdict: {}.\n\n{body}", v.words()),
            _ => body.to_string(),
        };
        let body = signed(&self.record_failed_write(self.clean(&text))?);
        let viewer = self.record_failed_write(self.viewer_login())?.to_string();
        let reviews = self.record_failed_write(self.try_pr_reviews(number))?;
        if has_viewer_review(&reviews, &viewer, &body, commit) {
            return Ok(());
        }
        let event = match (verdict, own) {
            (Some(v), false) => v.api_event(),
            _ => "COMMENT",
        };
        let path = format!("repos/{{owner}}/{{repo}}/pulls/{number}/reviews");
        let posted = self.gh(&[
            "api",
            "-X",
            "POST",
            &path,
            "-f",
            &format!("commit_id={commit}"),
            "-f",
            &format!("event={event}"),
            "-f",
            &format!("body={body}"),
            "--silent",
        ]);
        let result = match posted {
            Ok(_) => Ok(()),
            Err(post_error) => reconcile_review_post(
                number,
                &body,
                &viewer,
                commit,
                post_error,
                self.try_pr_reviews(number),
            ),
        };
        self.record_write(result)
    }

    pub fn comment_issue(&self, number: i64, body: &str) -> Result<()> {
        let body = signed(&self.record_failed_write(self.clean(body))?);
        let comments = self.record_failed_write(self.try_issue_comments(number))?;
        if has_exact_comment(&comments, &body) {
            return Ok(());
        }
        let posted = self.gh(&["issue", "comment", &number.to_string(), "--body", &body]);
        let result = match posted {
            Ok(_) => Ok(()),
            Err(post_error) => {
                reconcile_comment_post(number, &body, post_error, self.try_issue_comments(number))
            }
        };
        self.record_write(result)
    }

    /// Comment, then close as not planned.
    ///
    /// Only ever called when both agents independently declined the issue: one
    /// agent's opinion is not enough to close somebody's report.
    pub fn close_issue(&self, number: i64, body: &str) -> Result<()> {
        self.comment_issue(number, body)?;
        let n = number.to_string();
        let closed = match self.gh(&["issue", "close", &n, "--reason", "not planned"]) {
            Ok(_) => Ok(()),
            // Older gh builds do not take --reason.
            Err(_) => self.gh(&["issue", "close", &n]).map(|_| ()).map_err(|e| {
                spar_err!(
                    "commented on #{number} but could not close it: {}",
                    e.last_line()
                )
            }),
        };
        self.record_write(closed)
    }

    /// Replace an issue body, refusing unless it is still byte for byte what
    /// the caller read and validating only the fragment spar inserted.
    ///
    /// The only place spar rewrites text somebody else wrote, so the check is
    /// the whole point: an edit computed from a body that has since moved would
    /// silently delete whatever moved it. The caller decides whether another
    /// attempt is safe for its workflow.
    ///
    /// Deliberately not through `clean_issue_body`. The body is mostly a
    /// person's own prose, and the scrub would rewrite their punctuation while
    /// the length budget could truncate the end of a long report. `inserted` is
    /// the only text here spar is answerable for, so it still passes through the
    /// style gate. The full body travels over stdin because a tracker can be far
    /// too long for one argument.
    pub fn edit_issue_body(
        &self,
        number: i64,
        expected: &str,
        body: &str,
        inserted: &str,
    ) -> Result<()> {
        let cleaned = self.record_failed_write(self.clean(inserted))?;
        if cleaned.trim() != inserted.trim() {
            return self.record_failed_write(Err(spar_err!(
                "the style gate rewrote {inserted:?} to {cleaned:?}, so it is not being inserted"
            )));
        }
        let current = self.record_failed_write(self.issue_body(number))?;
        if current != expected {
            return self.record_failed_write(Err(spar_err!(
                "the body of #{number} changed since it was read, so it was left alone rather \
                 than written over."
            )));
        }
        let edited = self.gh_stdin(
            &["issue", "edit", &number.to_string(), "--body-file", "-"],
            body,
        );
        let result = match edited {
            Ok(_) => Ok(()),
            Err(edit_error) => {
                reconcile_issue_edit(number, body, edit_error, self.issue_body(number))
            }
        };
        self.record_write(result)
    }

    /// One issue's body, exactly as GitHub holds it.
    pub fn issue_body(&self, number: i64) -> Result<String> {
        #[derive(Deserialize)]
        struct Row {
            #[serde(default)]
            body: Option<String>,
        }
        let text = self.gh(&["issue", "view", &number.to_string(), "--json", "body"])?;
        let row: Row = serde_json::from_str(text.trim())
            .map_err(|e| spar_err!("unexpected shape for issue #{number}: {e}"))?;
        Ok(row.body.unwrap_or_default())
    }

    /// Every open issue with its title and body, in one call.
    ///
    /// For a screen that has to say something about each of twenty items before
    /// anything expensive happens. One call rather than one per issue.
    pub fn open_issue_rows(&self) -> Vec<Issue> {
        let text = self.gh_try(&[
            "issue",
            "list",
            "--state",
            "open",
            "--limit",
            &FETCH_CEILING.to_string(),
            "--json",
            "number,title,body,labels,state,stateReason,url",
        ]);
        serde_json::from_str::<Vec<Issue>>(text.trim()).unwrap_or_default()
    }

    /// Every open pull request with its size, in one call.
    pub fn open_pr_rows(&self) -> Vec<PrRow> {
        let text = self.gh_try(&[
            "pr",
            "list",
            "--state",
            "open",
            "--limit",
            &FETCH_CEILING.to_string(),
            "--json",
            "number,title,changedFiles,additions,deletions",
        ]);
        serde_json::from_str::<Vec<PrRow>>(text.trim()).unwrap_or_default()
    }

    pub fn create_issue(&self, title: &str, body: &str) -> Result<String> {
        self.create_issue_apart_from(title, body, None)
    }

    pub fn create_issue_apart_from(
        &self,
        title: &str,
        body: &str,
        apart_from: Option<i64>,
    ) -> Result<String> {
        let title = self.record_failed_write(self.clean_title(title))?;
        let body = self.record_failed_write(self.clean_issue_body(body))?;
        let created = self.gh(&["issue", "create", "--title", &title, "--body", &body]);
        let result = match created {
            Ok(url) if issue_url_has_number(&url) => Ok(url.trim().to_string()),
            created => {
                let found = self.try_exact_issue_apart_from(&title, &body, apart_from);
                reconcile_issue_creation(&title, created, found)
            }
        };
        self.record_write(result)
    }
}

/// An issue that already covers what spar was about to file.
#[derive(Debug, Clone)]
pub struct ExistingIssue {
    pub number: i64,
    pub url: String,
    pub title: String,
    pub body: String,
    pub open: bool,
}

impl Repo {
    pub(crate) fn try_exact_issue_apart_from(
        &self,
        title: &str,
        body: &str,
        apart_from: Option<i64>,
    ) -> Result<Option<ExistingIssue>> {
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Row {
            number: i64,
            #[serde(default)]
            title: String,
            #[serde(default)]
            url: String,
            #[serde(default)]
            body: Option<String>,
            #[serde(default)]
            state: String,
        }

        let text = self.gh(&[
            "issue",
            "list",
            "--state",
            "all",
            "--limit",
            "100",
            "--json",
            "number,title,url,body,state,stateReason",
        ])?;
        let rows = serde_json::from_str::<Vec<Row>>(text.trim())
            .map_err(|e| spar_err!("unexpected issue list while verifying {title:?}: {e}"))?;
        Ok(rows
            .into_iter()
            .filter(|row| Some(row.number) != apart_from)
            .find(|row| row.title == title && row.body.as_deref().unwrap_or_default() == body)
            .map(|row| ExistingIssue {
                number: row.number,
                url: row.url,
                title: row.title,
                body: row.body.unwrap_or_default(),
                open: row.state.eq_ignore_ascii_case("open"),
            }))
    }

    /// An issue that already describes this defect, however it was worded.
    ///
    /// Exact title matching let duplicates through: two agents, or two runs a
    /// week apart, never word one defect identically. A real run filed two
    /// duplicates that way, and each had to be closed by hand afterwards.
    /// Titles alone are too thin to match on, so this compares titles and
    /// bodies together.
    pub fn find_similar_issue(&self, title: &str, body: &str) -> Option<ExistingIssue> {
        self.find_similar_issue_apart_from(title, body, None)
    }

    /// The same search, with one issue that cannot be its own duplicate.
    ///
    /// A tracker's body quotes every item in its checklist, so searching for an
    /// item's words matches the tracker before it matches anything else. That
    /// would link an item to the issue it is written in.
    /// The search a tracker runs, which wants closed issues too: a checklist
    /// item matching a closed issue is a done item that wants a link.
    pub fn find_similar_issue_apart_from(
        &self,
        title: &str,
        body: &str,
        apart_from: Option<i64>,
    ) -> Option<ExistingIssue> {
        self.try_similar_issue(title, body, apart_from, true)
            .ok()
            .flatten()
    }

    /// The search a filing runs, over open issues only.
    pub fn try_find_similar_issue_apart_from(
        &self,
        title: &str,
        body: &str,
        apart_from: Option<i64>,
    ) -> Result<Option<ExistingIssue>> {
        self.try_similar_issue(title, body, apart_from, false)
    }

    /// The same search, preserving lookup failure for a caller about to write.
    fn try_similar_issue(
        &self,
        title: &str,
        body: &str,
        apart_from: Option<i64>,
        include_closed: bool,
    ) -> Result<Option<ExistingIssue>> {
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Row {
            number: i64,
            #[serde(default)]
            title: String,
            #[serde(default)]
            url: String,
            #[serde(default)]
            body: String,
            #[serde(default)]
            state: String,
        }
        if title.trim().is_empty() {
            return Ok(None);
        }
        // Search on the title's own words: GitHub's index is the cheap way to
        // narrow the field before comparing properly.
        let query: String = title
            .chars()
            .filter(|c| !matches!(c, '"' | '\'' | '\n' | '\r'))
            .take(120)
            .collect();
        // Open issues only when something is about to be filed. A fuzzy match
        // against a closed one is the case worth keeping rather than dropping:
        // a defect that was fixed, closed, and has come back is exactly the
        // finding a maintainer wants, and "#N covers it and is closed" wrote it
        // nowhere. An exact match is still checked against every state, since
        // that is a regression of one specific issue rather than a resemblance
        // to one, and a tracker still searches closed issues because a
        // checklist item matching one is a done item that wants a link.
        let state = if include_closed { "all" } else { "open" };
        let text = self.gh(&[
            "issue",
            "list",
            "--state",
            state,
            "--limit",
            "100",
            "--search",
            query.trim(),
            "--json",
            "number,title,url,body,state,stateReason",
        ])?;
        let rows: Vec<Row> = serde_json::from_str(text.trim())
            .map_err(|e| spar_err!("unexpected issue search for {title:?}: {e}"))?;

        Ok(rows
            .into_iter()
            .filter(|row| Some(row.number) != apart_from)
            .find(|row| {
                row.title.trim().eq_ignore_ascii_case(title.trim())
                    || textsim::covers(title, body, &row.title, &row.body)
            })
            .map(|row| ExistingIssue {
                number: row.number,
                url: row.url,
                title: row.title,
                open: row.state.eq_ignore_ascii_case("open"),
                body: row.body,
            }))
    }

    /// Avoid filing a duplicate when a follow-up already exists.
    pub fn find_issue_by_title(&self, title: &str) -> Option<String> {
        #[derive(Deserialize)]
        struct Row {
            title: String,
            url: String,
        }
        let needle = title.trim().to_lowercase();
        if needle.is_empty() {
            return None;
        }
        // Quotes and newlines would be read as search syntax rather than text.
        let query: String = title
            .chars()
            .filter(|c| !matches!(c, '"' | '\'' | '\n' | '\r'))
            .take(120)
            .collect();
        let text = self.gh_try(&[
            "issue",
            "list",
            "--state",
            "all",
            "--limit",
            "100",
            "--search",
            query.trim(),
            "--json",
            "number,title,url",
        ]);
        serde_json::from_str::<Vec<Row>>(text.trim())
            .ok()?
            .into_iter()
            .find(|row| row.title.trim().to_lowercase() == needle)
            .map(|row| row.url)
    }

    /// Squash merge, tolerating cleanup failures after a successful merge.
    ///
    /// Take a pull request out of draft, once the review has converged.
    ///
    /// Best effort for the remaining workflow. A failure does not discard the
    /// review or stop later independent work, but the final write summary
    /// reports it and the command returns non-zero.
    pub fn mark_ready(&self, number: i64) -> bool {
        match self.record_write(self.gh(&["pr", "ready", &number.to_string()])) {
            Ok(_) => true,
            Err(e) => {
                logdim!(
                    "PR #{number} is approved but could not be taken out of draft: {}",
                    e.last_line()
                );
                false
            }
        }
    }

    /// The worktree that has `branch` checked out, if one does.
    fn worktree_holding(&self, branch: &str) -> Option<PathBuf> {
        let listed = self
            .git_at(Some(&self.root), &["worktree", "list", "--porcelain"])
            .ok()?;
        let wanted = format!("branch refs/heads/{branch}");
        let mut current: Option<PathBuf> = None;
        for line in listed.lines() {
            if let Some(path) = line.strip_prefix("worktree ") {
                current = Some(PathBuf::from(path));
            } else if line == wanted {
                return current;
            }
        }
        None
    }

    /// Finish the local cleanup a merge could not.
    ///
    /// `gh pr merge --delete-branch` gives up on the local branch whenever any
    /// worktree has it checked out, which is the ordinary state rather than an
    /// odd one: `spar run` opens the pull request from
    /// `.spar-worktrees/issue-N` and leaves the checkout there, and the merge
    /// usually happens in a later `spar resume` working somewhere else. The
    /// next run's sweep tidied it, so nothing was ever lost, but the run that
    /// did the merge reported a failure about a branch nobody will touch again
    /// and left a checkout for the next run to explain.
    ///
    /// Held to the same rules the sweep uses, because they are the rules that
    /// decide whether anything would be lost: a branch spar recorded creating,
    /// a worktree of spar's own with no recoverable work in it, and a tip some
    /// surviving ref preserves. Anything else is left exactly where it is.
    fn finish_merged_branch_cleanup(&self, number: i64) -> Option<String> {
        let branch = self.pr_view(number).ok()?.head_ref_name;
        if branch.is_empty() || !self.known_branches().contains_key(&branch) {
            return None;
        }
        let mut released = None;
        if let Some(path) = self.worktree_holding(&branch) {
            if !path.starts_with(self.root.join(WORKTREE_DIR)) {
                return None;
            }
            if !matches!(
                self.has_recoverable_work(&path, Disposable::BuildOutput),
                Ok(false)
            ) {
                return None;
            }
            match self.remove_worktree_at(&path) {
                Ok(true) => released = Some(path),
                _ => return None,
            }
        }
        match self.delete_branch_if_safe(&branch) {
            Ok(true) => {
                self.forget_branch(&branch);
                Some(match released {
                    Some(path) => format!(
                        " The worktree at {} was released and branch {branch} deleted.",
                        path.display()
                    ),
                    None => format!(" Branch {branch} was deleted."),
                })
            }
            _ => released.map(|path| {
                format!(
                    " The worktree at {} was released, but branch {branch} was kept.",
                    path.display()
                )
            }),
        }
    }

    /// `gh pr merge --delete-branch` exits non-zero when it cannot delete the
    /// local branch, which happens *after* the merge has already landed.
    /// Treating that as a failure reports work as lost when it is not.
    pub fn merge_pr(&self, number: i64) -> Result<()> {
        let n = number.to_string();
        let merged = match self.gh(&merge_pr_args(&n, None, true)) {
            Ok(_) => Ok(()),
            Err(e) => {
                if self.pr_state(number) == "MERGED" {
                    let finished = self
                        .finish_merged_branch_cleanup(number)
                        .unwrap_or_default();
                    logdim!(
                        "PR #{number} merged; branch cleanup did not finish: {}{finished}",
                        e.last_line()
                    );
                    Ok(())
                } else {
                    Err(spar_err!("could not merge PR #{number}. {}", e.last_line()))
                }
            }
        };
        self.record_write(merged)
    }

    /// Squash merge only if the pull request still exposes the reviewed head.
    pub fn merge_pr_at_head(
        &self,
        number: i64,
        expected_head: &str,
        delete_branch: bool,
    ) -> Result<()> {
        let n = number.to_string();
        let merged = match self.gh(&merge_pr_args(&n, Some(expected_head), delete_branch)) {
            Ok(_) => Ok(()),
            Err(e) => {
                if self.pr_state(number) == "MERGED" {
                    let finished = self
                        .finish_merged_branch_cleanup(number)
                        .unwrap_or_default();
                    logdim!(
                        "PR #{number} merged; branch cleanup did not finish: {}{finished}",
                        e.last_line()
                    );
                    Ok(())
                } else {
                    Err(spar_err!("could not merge PR #{number}. {}", e.last_line()))
                }
            }
        };
        self.record_write(merged)
    }

    // -- follow-ups -------------------------------------------------------

    /// The queue of follow-ups recorded locally rather than filed, which
    /// `spar followup` works.
    pub fn followups_path(&self) -> PathBuf {
        self.root.join(STATE_DIR).join("followups.md")
    }

    /// Where `spar brainstorm` writes a session unless told otherwise.
    ///
    /// Under the state directory, so it is kept out of the repository's own
    /// `git status`; `--out` puts one somewhere a person would commit.
    pub fn brainstorms_dir(&self) -> PathBuf {
        self.root.join(STATE_DIR).join("brainstorms")
    }

    /// What `spar followup` already dealt with, kept beside the queue.
    ///
    /// Two jobs. It is what stops `append_local_followup` re-recording a
    /// follow-up whose entry has since left the queue, which would otherwise
    /// turn the file into a ring buffer of things already filed. And it keeps
    /// the text of an entry a screening pass ruled stale, so a wrong verdict
    /// costs a re-read rather than the only copy of a real defect.
    pub fn worked_followups_path(&self) -> PathBuf {
        self.root.join(STATE_DIR).join("followups.done.md")
    }

    /// What `spar checkin` has already answered on one pull request or issue.
    /// Where what a run spent is kept.
    pub fn spend_path(&self) -> PathBuf {
        self.root.join(STATE_DIR).join("state").join("spend.json")
    }

    /// Append this run's calls to the record.
    ///
    /// Appended rather than replaced, so a resumed pull request adds to the
    /// count of what it has cost so far rather than starting it again, and so
    /// anybody charting this has a file to chart.
    pub fn record_spend(&self, calls: &[crate::spend::Spent]) -> Result<()> {
        if calls.is_empty() {
            return Ok(());
        }
        let mut all: Vec<crate::spend::Spent> = std::fs::read_to_string(self.spend_path())
            .ok()
            .and_then(|text| serde_json::from_str(&text).ok())
            .unwrap_or_default();
        all.extend(calls.iter().cloned());
        if let Some(parent) = self.spend_path().parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        write_json_atomic(&self.spend_path(), &all)
    }

    /// Who wrote the first draft of each issue, by number.
    ///
    /// Custody alternates within a pull request and the record of it lives in
    /// that pull request's state. This is the other question, which nothing
    /// answered: over a queue, which model authored what.
    pub fn implementors_path(&self) -> PathBuf {
        self.root
            .join(STATE_DIR)
            .join("state")
            .join("implementors.json")
    }

    pub fn read_implementors(&self) -> BTreeMap<i64, String> {
        std::fs::read_to_string(self.implementors_path())
            .ok()
            .and_then(|text| serde_json::from_str(&text).ok())
            .unwrap_or_default()
    }

    /// Best effort: this is a record for a person, not something the loop reads
    /// back, so a failure to write it is not a reason to stop.
    pub fn remember_implementor(&self, issue: i64, agent: &str) {
        let mut known = self.read_implementors();
        known.insert(issue, agent.to_string());
        if let Some(parent) = self.implementors_path().parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        if let Err(e) = write_json_atomic(&self.implementors_path(), &known) {
            logdim!("could not record who implemented #{issue}: {e}");
        }
    }

    /// Where the issues triage disagreed about are remembered.
    ///
    /// One file rather than one per issue: it is read once per run, before any
    /// triage call, to decide what not to ask about again.
    pub fn contested_path(&self) -> PathBuf {
        self.root
            .join(STATE_DIR)
            .join("state")
            .join("contested.json")
    }

    /// The issues a person has been asked to decide, by number.
    pub fn read_contested(&self) -> BTreeMap<i64, Contested> {
        std::fs::read_to_string(self.contested_path())
            .ok()
            .and_then(|text| serde_json::from_str(&text).ok())
            .unwrap_or_default()
    }

    /// Remember an issue triage could not agree on.
    ///
    /// Best effort: a run that cannot write this asks again next time, which is
    /// what it did before this existed.
    pub fn remember_contested(&self, items: &[ContestedItem]) {
        if items.is_empty() {
            return;
        }
        let mut known = self.read_contested();
        for item in items {
            known.insert(
                item.issue,
                Contested {
                    title: item.title.clone(),
                    positions: item.positions.clone(),
                    reasons: item.reasons.clone(),
                },
            );
        }
        if let Some(parent) = self.contested_path().parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        if let Err(e) = write_json_atomic(&self.contested_path(), &known) {
            logdim!("could not record the contested issues: {e}");
        }
    }

    /// Ask about them again, because a person has acted on them.
    pub fn forget_contested(&self, numbers: &[i64]) {
        let mut known = self.read_contested();
        let before = known.len();
        known.retain(|number, _| !numbers.contains(number));
        if known.len() == before {
            return;
        }
        if let Err(e) = write_json_atomic(&self.contested_path(), &known) {
            logdim!("could not update the contested issues: {e}");
        }
    }

    pub fn checkin_state_path(&self, number: i64) -> PathBuf {
        self.root
            .join(STATE_DIR)
            .join("state")
            .join(format!("checkin-{number}.json"))
    }

    /// Where `spar review` records what it reviewed, and a second look reads it.
    pub fn review_record_path(&self, number: i64) -> PathBuf {
        self.root
            .join(STATE_DIR)
            .join("state")
            .join(format!("review-{number}.json"))
    }

    /// None when there is no record, or when it cannot be read. A record spar
    /// cannot read is one it reviews afresh over, and the log says so.
    pub fn read_review_record(&self, number: i64) -> Option<crate::model::ReviewRecord> {
        let path = self.review_record_path(number);
        let text = std::fs::read_to_string(&path).ok()?;
        match serde_json::from_str(&text) {
            Ok(record) => Some(record),
            Err(e) => {
                logdim!("could not read {}: {e}", path.display());
                None
            }
        }
    }

    pub fn write_review_record(
        &self,
        number: i64,
        record: &crate::model::ReviewRecord,
    ) -> Result<()> {
        write_json_atomic(&self.review_record_path(number), record)
    }

    /// Append a follow-up to a local note instead of the tracker.
    ///
    /// Deduplicated on the title, matching the issue path. The body arrives
    /// with its provenance already stamped by the caller, so nothing is added
    /// here.
    ///
    /// A write that did not happen is reported as such rather than as a
    /// duplicate: the caller settles the point on the strength of this answer,
    /// and settling it on a failed write is how a real defect is lost.
    ///
    /// Both files are checked, because `spar followup` removes an entry from
    /// the queue once it has filed it. Checking only the queue would let the
    /// next run that rediscovers the same defect append it again, on top of the
    /// issue that now exists for it.
    pub fn append_local_followup(&self, title: &str, body: &str) -> Followup {
        let path = self.followups_path();
        let heading = format!("## {}", title.trim());
        for seen in [&path, &self.worked_followups_path()] {
            if let Ok(existing) = std::fs::read_to_string(seen) {
                if has_heading(&existing, title) {
                    logdim!("follow-up already noted: {title}");
                    return Followup::Covered(format!("note: {}", title.trim()));
                }
            }
        }
        if let Some(parent) = path.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        use std::io::Write;
        // The caller already stamped the provenance into the body. Adding
        // "From #N." here as well printed it twice, in two different wordings.
        //
        // The marker above the heading is what makes the entry boundary
        // unambiguous to the parser, since the body's own sections are written
        // at the same heading level as the title.
        let entry = format!("{FOLLOWUP_MARKER}\n{heading}\n\n{}\n\n", body.trim());
        match std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&path)
        {
            Ok(mut file) => match file.write_all(entry.as_bytes()) {
                Ok(()) => Followup::Recorded(format!("note: {}", title.trim())),
                Err(e) => {
                    logdim!("could not write {}: {e}", path.display());
                    Followup::Failed
                }
            },
            Err(e) => {
                logdim!("could not write {}: {e}", path.display());
                Followup::Failed
            }
        }
    }

    /// Record what `spar followup` did with an entry, and why.
    ///
    /// Best effort: an archive that could not be written is not a reason to
    /// stop, since the entry has already been filed or ruled on.
    pub fn archive_followup(&self, title: &str, body: &str, verdict: &str) {
        let path = self.worked_followups_path();
        if let Some(parent) = path.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        use std::io::Write;
        let entry = format!(
            "{FOLLOWUP_MARKER}\n## {}\n\n{verdict}\n\n{}\n\n",
            title.trim(),
            body.trim()
        );
        if let Ok(mut file) = std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&path)
        {
            let _ = file.write_all(entry.as_bytes());
        }
    }

    // -- resumable state --------------------------------------------------
    //
    // Custody cannot be read from GitHub authorship: every agent commits and
    // comments as the same git identity, so `author` is always the human who
    // ran spar. State is kept on disk by default and can additionally travel in
    // a PR comment, which is what lets a run be resumed from another machine.

    /// Where a comment spar produced but did not post is kept.
    pub fn pending_comment_path(&self, number: i64) -> PathBuf {
        self.root
            .join(STATE_DIR)
            .join("reviews")
            .join(format!("pr-{number}.md"))
    }

    /// Keep a comment spar decided not to post.
    ///
    /// A dry run that prints and forgets means agreeing with what you read
    /// costs a second full review. Saving it makes the whole point of reading
    /// it first: look, edit if you like, then post what you already paid for.
    pub fn save_pending_comment(&self, number: i64, text: &str) -> Result<PathBuf> {
        let path = self.pending_comment_path(number);
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)
                .map_err(|e| spar_err!("could not create {}: {e}", parent.display()))?;
        }
        std::fs::write(&path, text)
            .map_err(|e| spar_err!("could not write {}: {e}", path.display()))?;
        Ok(path)
    }

    pub fn read_pending_comment(&self, number: i64) -> Option<String> {
        std::fs::read_to_string(self.pending_comment_path(number)).ok()
    }

    pub fn state_path(&self, number: i64) -> PathBuf {
        self.root
            .join(STATE_DIR)
            .join("state")
            .join(format!("pr-{number}.json"))
    }

    fn read_local_state(&self, number: i64) -> Option<PersistedState> {
        let path = self.state_path(number);
        let text = std::fs::read_to_string(&path).ok()?;
        match serde_json::from_str(&text) {
            Ok(state) => Some(state),
            Err(_) => {
                logdim!("could not read {}, starting fresh", path.display());
                None
            }
        }
    }

    pub fn read_state(&self, pr: &PrView) -> Option<PersistedState> {
        if let Some(local) = self.read_local_state(pr.number) {
            return Some(local);
        }
        if self.state_store.writes_pr() {
            return self.read_pr_state(pr.number);
        }
        None
    }

    pub(crate) fn read_state_for_head(
        &self,
        pr: &PrView,
        actual_head: &str,
    ) -> Option<PersistedState> {
        let local = self
            .state_store
            .writes_local()
            .then(|| self.read_local_state(pr.number))
            .flatten();
        let remote = self
            .state_store
            .writes_pr()
            .then(|| self.read_pr_state(pr.number))
            .flatten();
        let candidates: Vec<PersistedState> = [local, remote].into_iter().flatten().collect();
        if let Some(checkpoint) = candidates.iter().map(|state| state.checkpoint).max() {
            self.remember_checkpoint(pr.number, checkpoint);
        }
        choose_state_for_head(candidates, actual_head)
    }

    fn read_pr_state(&self, number: i64) -> Option<PersistedState> {
        self.try_read_pr_state(number).ok().flatten()
    }

    fn try_read_pr_state(&self, number: i64) -> Result<Option<PersistedState>> {
        for (_, body) in self.try_state_comments(number)?.into_iter().rev() {
            if let Some(state) = parse_state_comment(&body) {
                return Ok(Some(state));
            }
        }
        Ok(None)
    }

    pub fn write_state(&self, number: i64, state: &PersistedState) -> Result<()> {
        let remote_state = if self.state_store.writes_pr() {
            self.try_read_pr_state(number)
        } else {
            Ok(None)
        };
        self.write_state_after_remote_read(number, state, remote_state)
    }

    fn write_state_after_remote_read(
        &self,
        number: i64,
        state: &PersistedState,
        remote_state: Result<Option<PersistedState>>,
    ) -> Result<()> {
        let remote_checkpoint = if self.state_store.writes_pr() {
            self.record_failed_write(remote_state)?
                .map(|saved| saved.checkpoint)
                .unwrap_or_default()
        } else {
            0
        };
        let local_checkpoint = self
            .state_store
            .writes_local()
            .then(|| self.read_local_state(number))
            .flatten()
            .map(|saved| saved.checkpoint)
            .unwrap_or_default();
        let mut stamped = state.clone();
        stamped.checkpoint = state
            .checkpoint
            .max(local_checkpoint)
            .max(remote_checkpoint)
            .max(self.remembered_checkpoint(number))
            .saturating_add(1);
        self.remember_checkpoint(number, stamped.checkpoint);
        if self.state_store.writes_local() {
            write_json_atomic(&self.state_path(number), &stamped)?;
        }
        if self.state_store.writes_pr() {
            self.write_pr_state(number, &stamped)?;
        }
        Ok(())
    }

    fn remembered_checkpoint(&self, number: i64) -> u64 {
        self.checkpoints
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .get(&number)
            .copied()
            .unwrap_or_default()
    }

    fn remember_checkpoint(&self, number: i64, checkpoint: u64) {
        let mut checkpoints = self
            .checkpoints
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let saved = checkpoints.entry(number).or_default();
        *saved = (*saved).max(checkpoint);
    }

    fn write_pr_state(&self, number: i64, state: &PersistedState) -> Result<()> {
        // Not run through clean(): this is structured data, and scrubbing would
        // corrupt refutation text stored in the ledger. It sits inside an
        // unclosed HTML comment so GitHub renders it as nothing.
        let serialized = self.record_failed_write(serde_json::to_string_pretty(state))?;
        let body = format!("{STATE_MARKER}\n{}\n-->", serialized);
        let comment_id = self.record_failed_write(self.try_state_comment_id(number))?;
        if let Some(id) = comment_id {
            let path = format!("repos/{{owner}}/{{repo}}/issues/comments/{id}");
            let field = format!("body={body}");
            let written = self
                .gh(&["api", "-X", "PATCH", &path, "-f", &field, "--silent"])
                .map(|_| ());
            return self.record_write(written);
        }
        let written = self
            .gh(&["pr", "comment", &number.to_string(), "--body", &body])
            .map(|_| ());
        self.record_write(written)
    }

    /// Top level comments. Works for issues and pull requests alike, because
    /// GitHub serves both from the issues endpoint.
    ///
    /// Nothing when they cannot be read, which suits a reader that is going to
    /// go on regardless. A caller deciding whether it has already written here
    /// wants `try_issue_comments`, since for that one no comments and no answer
    /// are opposite answers.
    pub fn issue_comments(&self, number: i64) -> Vec<Value> {
        self.try_issue_comments(number).unwrap_or_default()
    }

    pub fn try_issue_comments(&self, number: i64) -> Result<Vec<Value>> {
        let path = format!("repos/{{owner}}/{{repo}}/issues/{number}/comments");
        try_parse_comment_pages(&self.gh(&["api", "--paginate", &path])?)
    }

    /// spar's own state comments on a pull request, newest last.
    ///
    /// Three tests, because the answer decides what gets patched over and what
    /// gets deleted. A comment matching the marker loosely, which is what
    /// somebody asking "why is there a `<!-- spar:state` block on this PR?"
    /// writes, is named in the log and left exactly where it is.
    fn try_state_comments(&self, number: i64) -> Result<Vec<(i64, String)>> {
        let viewer = self.viewer_login()?.to_string();
        let mut mine = Vec::new();
        let mut theirs = Vec::new();
        for comment in self.try_issue_comments(number)? {
            let Some(body) = comment.get("body").and_then(Value::as_str) else {
                continue;
            };
            if !body.contains("spar:state") {
                continue;
            }
            let Some(id) = comment.get("id").and_then(Value::as_i64) else {
                continue;
            };
            let author = comment
                .get("user")
                .and_then(|u| u.get("login"))
                .and_then(Value::as_str)
                .unwrap_or_default();
            if is_state_comment(body, author, &viewer) {
                mine.push((id, body.to_string()));
            } else {
                theirs.push(format!("@{author}"));
            }
        }
        if !theirs.is_empty() {
            logdim!(
                "left {} comment(s) on #{number} that mention spar:state alone: {}. Only spar's \
                 own state block is patched or deleted.",
                theirs.len(),
                theirs.join(", ")
            );
        }
        Ok(mine)
    }

    fn try_state_comment_id(&self, number: i64) -> Result<Option<i64>> {
        Ok(self.try_state_comments(number)?.last().map(|(id, _)| *id))
    }

    /// Drop state once the PR is finished and there is nothing to resume.
    pub fn clear_state(&self, number: i64) {
        let path = self.state_path(number);
        let _ = std::fs::remove_file(&path);
        let _ = std::fs::remove_file(path.with_extension("json.tmp"));
    }

    // -- housekeeping -----------------------------------------------------

    /// Remove state files whose PR is merged or closed: the custody loop's
    /// state, the review record, and the check-in watermark alike. Grouped by
    /// number so each finished pull request costs one `gh` read however many
    /// files it left.
    pub fn prune_state(&self) -> Vec<String> {
        let base = self.root.join(STATE_DIR).join("state");
        let Ok(entries) = std::fs::read_dir(&base) else {
            return Vec::new();
        };
        let mut by_number: BTreeMap<i64, Vec<String>> = BTreeMap::new();
        for name in entries
            .flatten()
            .filter_map(|e| e.file_name().to_str().map(str::to_string))
        {
            if let Some(number) = state_file_number(&name) {
                by_number.entry(number).or_default().push(name);
            }
        }

        let mut removed = Vec::new();
        for (number, mut names) in by_number {
            if !is_finished(&self.pr_state(number)) {
                continue;
            }
            names.sort();
            for name in names {
                let _ = std::fs::remove_file(base.join(&name));
                removed.push(format!("state {name}"));
            }
        }
        removed
    }

    /// Delete state comments from PRs that are finished.
    ///
    /// Open PRs are left alone: their state may still be live.
    pub fn prune_pr_state(&self, numbers: Option<Vec<i64>>) -> Vec<String> {
        #[derive(Deserialize)]
        struct Row {
            number: i64,
        }
        let numbers = match numbers {
            Some(numbers) => numbers,
            None => {
                let listed: Result<Vec<i64>> = (|| {
                    let text = self.gh(&[
                        "pr", "list", "--state", "all", "--limit", "200", "--json", "number",
                    ])?;
                    let rows = serde_json::from_str::<Vec<Row>>(text.trim())
                        .map_err(|e| spar_err!("unexpected pull request list: {e}"))?;
                    Ok(rows.into_iter().map(|row| row.number).collect())
                })();
                match self.record_failed_write(listed) {
                    Ok(numbers) => numbers,
                    Err(e) => {
                        logdim!("could not inspect pull requests for state cleanup: {e}");
                        return Vec::new();
                    }
                }
            }
        };

        let mut removed = Vec::new();
        for number in numbers {
            let state = match self.record_failed_write(self.try_pr_state(number)) {
                Ok(state) => state,
                Err(e) => {
                    logdim!("could not inspect PR #{number} for state cleanup: {e}");
                    continue;
                }
            };
            if !is_finished(&state) {
                continue;
            }
            let comments = match self.record_failed_write(self.try_state_comments(number)) {
                Ok(comments) => comments,
                Err(e) => {
                    logdim!("could not inspect state comments on PR #{number}: {e}");
                    continue;
                }
            };
            for (id, _) in comments {
                let path = format!("repos/{{owner}}/{{repo}}/issues/comments/{id}");
                let deleted = self
                    .gh(&["api", "-X", "DELETE", &path, "--silent"])
                    .map(|_| ());
                match self.record_write(deleted) {
                    Ok(()) => removed.push(format!("state comment on PR #{number}")),
                    Err(e) => logdim!("could not remove state comment on PR #{number}: {e}"),
                }
            }
        }
        removed
    }

    /// Drop worktrees whose PR is finished, then the branches they left behind.
    ///
    /// With auto_merge off, which is the default, a run ends at "approved", so
    /// nothing would ever clean these up on its own and they accumulate one per
    /// run. A stranded worktree also holds its branch checked out, which makes
    /// a later `gh pr merge --delete-branch` fail to clean up.
    pub fn prune_worktrees(&self, force_all: bool) -> Vec<String> {
        let base = self.root.join(WORKTREE_DIR);
        let mut removed = Vec::new();
        let known = self.known_branches();

        if let Ok(entries) = std::fs::read_dir(&base) {
            let mut names: Vec<String> = entries
                .flatten()
                .filter(|e| e.path().is_dir())
                .filter_map(|e| e.file_name().to_str().map(str::to_string))
                .collect();
            names.sort();

            for name in names {
                // A review worktree is detached and owns no branch, so it is
                // tied to the pull request only by its directory name.
                if let Some(rest) = name.strip_prefix("review-") {
                    let number: i64 = rest.parse().unwrap_or(-1);
                    if !(force_all || is_finished(&self.pr_state(number))) {
                        continue;
                    }
                    let path = base.join(&name);
                    if force_all {
                        let owned = self.worktree_belongs_to_repo(&path).and_then(|belongs| {
                            if !belongs {
                                return Ok(false);
                            }
                            let local_ref = review_ref(number);
                            if !self.exact_ref_exists_checked(&self.root, &local_ref)? {
                                return Ok(false);
                            }
                            let head = self.head_oid_checked(&path)?;
                            let recorded = self
                                .git_at(Some(&self.root), &["rev-parse", "--verify", &local_ref])?
                                .trim()
                                .to_string();
                            Ok(head == recorded)
                        });
                        match owned {
                            Ok(true) => {}
                            Ok(false) => {
                                logdim!(
                                    "kept {} because no matching SPAR review reference proves \
                                     ownership",
                                    path.display()
                                );
                                continue;
                            }
                            Err(e) => {
                                logdim!(
                                    "kept {} because review ownership could not be verified: {}",
                                    path.display(),
                                    e.last_line()
                                );
                                continue;
                            }
                        }
                    } else {
                        if let Err(e) = self.refuse_review_worktree_changes(number) {
                            logdim!(
                                "kept {} because its review state could not be verified as \
                                 disposable: {}",
                                path.display(),
                                e.last_line()
                            );
                            continue;
                        }
                    }
                    if force_all {
                        if self.remove_worktree_at_force(&path) {
                            self.git_try(&["update-ref", "-d", &review_ref(number)]);
                        }
                    } else {
                        self.release_review_worktree(number);
                    }
                    if !path.exists() {
                        removed.push(name);
                    }
                    continue;
                }
                let branch = format!("{}{name}", self.branch_prefix);
                if !(force_all || self.worktree_is_done(&branch)) {
                    continue;
                }
                if !known.contains_key(&branch) {
                    logdim!("kept {branch} because it has no branch record");
                    continue;
                }
                let path = base.join(&name);
                if !force_all {
                    match self.has_recoverable_work(&path, Disposable::BuildOutput) {
                        Ok(true) => {
                            logdim!(
                                "kept {} because it contains uncommitted changes or ignored files",
                                path.display()
                            );
                            continue;
                        }
                        Err(e) => {
                            logdim!(
                                "kept {} because its Git state could not be checked: {}",
                                path.display(),
                                e.last_line()
                            );
                            continue;
                        }
                        Ok(false) => {}
                    }
                    match self.branch_deletion_is_safe(&branch) {
                        Ok(true) => {}
                        Ok(false) => {
                            logdim!(
                                "kept {branch} because no surviving ref preserves its tip or \
                                 reflog-only commits"
                            );
                            continue;
                        }
                        Err(e) => {
                            logdim!(
                                "kept {branch} because preservation could not be verified: {}",
                                e.last_line()
                            );
                            continue;
                        }
                    }
                }
                let removed_worktree = if force_all {
                    self.remove_worktree_at_force(&path)
                } else {
                    match self.remove_worktree_at(&path) {
                        Ok(removed) => removed,
                        Err(error) => {
                            logdim!(
                                "kept {branch} and {} because removal did not reach a confirmed \
                                 quiet point: {}",
                                path.display(),
                                error.last_line()
                            );
                            false
                        }
                    }
                };
                if !removed_worktree {
                    continue;
                }
                if force_all {
                    self.git_try(&["branch", "-D", &branch]);
                    self.forget_branch(&branch);
                } else {
                    match self.delete_branch_if_safe(&branch) {
                        Ok(true) => self.forget_branch(&branch),
                        Ok(false) => logdim!(
                            "kept {branch} because its tip or reflog changed before deletion"
                        ),
                        Err(error) => logdim!(
                            "kept {branch} because deletion safety could not be rechecked: {}",
                            error.last_line()
                        ),
                    }
                }
                removed.push(name);
            }
        }
        removed.extend(self.prune_branches(force_all));
        removed
    }

    /// Delete leftover branches spar created whose worktree is already gone.
    ///
    /// Deletion is driven by the ledger of branches spar actually created, not
    /// by a name pattern. Names default to `issue-N`, which is exactly what a
    /// person would call a branch themselves, so a name alone can never
    /// establish ownership. This is the data loss guard.
    pub fn prune_branches(&self, force_all: bool) -> Vec<String> {
        let known = self.known_branches();
        let branches: Vec<String> = known.keys().cloned().collect();
        if branches.is_empty() {
            return Vec::new();
        }

        let checked_out: Vec<String> = self
            .git_try(&["worktree", "list", "--porcelain"])
            .lines()
            .filter_map(|l| l.strip_prefix("branch refs/heads/").map(str::to_string))
            .collect();

        // %(refname:short) is ambiguous when a tag shares the branch name (it
        // yields "heads/..."), so take the full ref and strip it here.
        let existing: Vec<String> = self
            .git_try(&["for-each-ref", "refs/heads/", "--format=%(refname)"])
            .lines()
            .filter_map(|l| l.trim().strip_prefix("refs/heads/").map(str::to_string))
            .collect();

        let mut removed = Vec::new();
        for branch in branches {
            if !existing.contains(&branch) {
                self.forget_branch(&branch); // already gone, drop the record
                continue;
            }
            if checked_out.contains(&branch) {
                continue;
            }
            if !(force_all || self.worktree_is_done(&branch)) {
                continue;
            }
            if !force_all {
                let Some(_record) = known.get(&branch) else {
                    continue;
                };
                match self.branch_deletion_is_safe(&branch) {
                    Ok(true) => {}
                    Ok(false) => {
                        logdim!(
                            "kept {branch} because no surviving ref preserves its tip or \
                             reflog-only commits"
                        );
                        continue;
                    }
                    Err(e) => {
                        logdim!(
                            "kept {branch} because preservation could not be verified: {}",
                            e.last_line()
                        );
                        continue;
                    }
                }
            }
            let deleted = if force_all {
                self.git(&["branch", "-D", &branch]).map(|_| true)
            } else {
                self.delete_branch_if_safe(&branch)
            };
            match deleted {
                Ok(true) => {
                    self.forget_branch(&branch);
                    removed.push(format!("branch {branch}"));
                }
                Ok(false) => {
                    logdim!("kept {branch} because its tip or reflog changed before deletion");
                }
                Err(e) => {
                    // A branch that silently survives pruning looks like a spar
                    // bug, so the name and git's own reason have to be said.
                    logdim!("could not delete {branch}: {}", e.last_line());
                }
            }
        }
        removed
    }

    /// True when the PR behind this branch is merged or closed.
    fn worktree_is_done(&self, branch: &str) -> bool {
        #[derive(Deserialize)]
        struct Row {
            state: String,
        }
        let entry = branch
            .strip_prefix(self.branch_prefix.as_str())
            .unwrap_or(branch);
        if let Some(rest) = entry.strip_prefix("pr-") {
            return is_finished(&self.pr_state(rest.parse().unwrap_or(-1)));
        }
        // A split part is the same shape as an issue branch: one branch, whose
        // pull requests say whether it is finished. Without it here, a part
        // branch is one nothing but `clean --all` would ever remove.
        if entry.starts_with("issue-") || entry.starts_with("split-") {
            let text = self.gh_try(&[
                "pr", "list", "--head", branch, "--state", "all", "--json", "state",
            ]);
            let rows: Vec<Row> = serde_json::from_str(text.trim()).unwrap_or_default();
            return !rows.is_empty() && rows.iter().all(|r| is_finished(&r.state));
        }
        false
    }
}

// ---------------------------------------------------------------------------
// Free helpers
// ---------------------------------------------------------------------------

/// Take a read-only probe again before treating its failure as evidence.
///
/// Every probe is a Git invocation under a thirty second cap plus a walk over a
/// tree an agent may still be building in. A probe that fails proves nothing
/// about the worktree, and there is a real difference between "the tree moved"
/// and "the question could not be asked just then", which the caller turns into
/// the same run-ending error.
pub(crate) fn probe_again_on_failure<T>(probe: impl Fn() -> Result<T>) -> Result<T> {
    match probe() {
        Ok(value) => Ok(value),
        Err(first) => {
            logdim!("retrying a worktree probe after: {}", first.last_line());
            probe()
        }
    }
}

/// Read attribute files without asking Git to inspect working-tree content.
///
/// A newly written attribute can select a clean or smudge filter. It must be
/// detected before a post-call status, diff, or add command has a chance to run
/// that filter in the parent process.
pub(crate) fn attribute_state(cwd: &Path) -> Result<AttributeState> {
    let root = std::fs::canonicalize(cwd)
        .map_err(|e| spar_err!("could not resolve {}: {e}", cwd.display()))?;
    let mut files = BTreeMap::new();
    let mut visited = BTreeSet::new();
    collect_attribute_files(&root, &root, Path::new(""), &mut visited, &mut files)?;
    Ok(AttributeState { files })
}

fn collect_attribute_files(
    root: &Path,
    repository: &Path,
    prefix: &Path,
    visited: &mut BTreeSet<PathBuf>,
    files: &mut BTreeMap<PathBuf, [u8; 32]>,
) -> Result<()> {
    let canonical = std::fs::canonicalize(repository)
        .map_err(|e| spar_err!("could not resolve {}: {e}", repository.display()))?;
    if !visited.insert(canonical) {
        bail!("submodule recursion revisited {}", repository.display());
    }
    let entries = index_entries(repository)?;
    let mut paths: BTreeSet<PathBuf> = entries
        .iter()
        .filter(|entry| entry.path.file_name() == Some(OsStr::new(".gitattributes")))
        .map(|entry| entry.path.clone())
        .collect();
    // Ignored on purpose. A `.gitattributes` under build output can only select
    // filters for paths that are themselves ignored, and no ignored path is
    // ever staged or compared as tracked content, so it cannot reach a managed
    // commit. Capturing it meant `cargo package` or `npm ci` writing one into
    // its own output ended a read-only call outright.
    paths.extend(untracked_attribute_paths(repository)?);
    for path in paths {
        let from_root = prefix.join(&path);
        let state = attribute_file_fingerprint(&root.join(&from_root))?;
        files.insert(from_root, state);
    }
    for entry in entries.into_iter().filter(|entry| entry.mode == "160000") {
        let Some(submodule) = initialized_submodule(repository, &entry.path)? else {
            continue;
        };
        collect_attribute_files(root, &submodule, &prefix.join(&entry.path), visited, files)?;
    }
    Ok(())
}

/// Leave a visible, untracked reason ordinary cleanup can detect on a later
/// run even when Git status normalizes the original working-file change away.
pub(crate) fn uncertain_worktree_change(
    cwd: &Path,
    message: impl Into<String>,
) -> crate::error::SparError {
    let message = message.into();
    let marker = write_recovery_marker(cwd, &message);
    let note = match marker {
        Ok(path) => format!(" Recovery marker: {}.", path.display()),
        Err(e) => format!(
            " A recovery marker could not be written: {}.",
            e.last_line()
        ),
    };
    crate::error::SparError::uncertain_write(format!("{message}{note}"))
}

fn write_recovery_marker(cwd: &Path, detail: &str) -> Result<PathBuf> {
    use std::sync::atomic::{AtomicU32, Ordering};
    static NEXT: AtomicU32 = AtomicU32::new(0);
    for _ in 0..1000 {
        let serial = NEXT.fetch_add(1, Ordering::Relaxed);
        let path = cwd.join(format!(
            "{RECOVERY_MARKER_PREFIX}{}-{serial}",
            std::process::id()
        ));
        let mut options = OpenOptions::new();
        options.write(true).create_new(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt;
            options.mode(0o600);
        }
        match options.open(&path) {
            Ok(mut file) => {
                file.write_all(detail.as_bytes())
                    .and_then(|_| file.write_all(b"\n"))
                    .map_err(|e| spar_err!("could not write {}: {e}", path.display()))?;
                return Ok(path);
            }
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
            Err(e) => {
                return Err(spar_err!(
                    "could not create a recovery marker in {}: {e}",
                    cwd.display()
                ))
            }
        }
    }
    bail!(
        "could not choose a free recovery marker name in {}",
        cwd.display()
    )
}

/// Build a Git command that cannot launch automatic repository maintenance.
///
/// A fetch may otherwise prune missing linked worktree registrations. SPAR
/// must only remove registrations it has proven it owns.
fn git_without_maintenance_argv(args: &[&str]) -> Vec<String> {
    let mut argv = vec![
        "git".to_string(),
        "-c".to_string(),
        "maintenance.auto=false".to_string(),
        "-c".to_string(),
        "gc.auto=0".to_string(),
    ];
    argv.extend(args.iter().map(|arg| (*arg).to_string()));
    argv
}

fn git_without_automation_argv(args: &[&str]) -> Vec<String> {
    let mut argv = git_without_maintenance_argv(&[]);
    argv.extend([
        "-c".to_string(),
        "core.fsmonitor=".to_string(),
        "-c".to_string(),
        "commit.gpgsign=false".to_string(),
        "-c".to_string(),
        "core.hooksPath=/dev/null".to_string(),
    ]);
    argv.extend(args.iter().map(|arg| (*arg).to_string()));
    argv
}

/// Snapshot every untracked file, including ignored files, without changing
/// path bytes.
///
/// Without an exclude option, Git lists both ordinary and ignored untracked
/// entries. Metadata fingerprints make overwriting an existing path observable
/// without hashing a potentially multi-gigabyte build tree on every call.
pub(crate) fn ignored_untracked_state(cwd: &Path) -> Result<IgnoredState> {
    let root = std::fs::canonicalize(cwd)
        .map_err(|e| spar_err!("could not resolve {}: {e}", cwd.display()))?;
    let mut files = BTreeMap::new();
    let mut ignored = BTreeSet::new();
    let mut visited = BTreeSet::new();
    collect_untracked_files(
        &root,
        &root,
        Path::new(""),
        &mut visited,
        &mut files,
        &mut ignored,
    )?;
    Ok(IgnoredState { files, ignored })
}

fn collect_untracked_files(
    root: &Path,
    repository: &Path,
    prefix: &Path,
    visited: &mut BTreeSet<PathBuf>,
    files: &mut BTreeMap<PathBuf, UntrackedFile>,
    ignored: &mut BTreeSet<PathBuf>,
) -> Result<()> {
    let canonical = std::fs::canonicalize(repository)
        .map_err(|e| spar_err!("could not resolve {}: {e}", repository.display()))?;
    if !visited.insert(canonical.clone()) {
        bail!("submodule recursion revisited {}", canonical.display());
    }
    // Classify ordinary paths in the listing itself. Listing every path here
    // and marking ignored paths in a second query misclassifies build output
    // deleted between queries as ordinary untracked work.
    let listed = run_git_bytes(
        repository,
        &["ls-files", "--others", "--exclude-standard", "-z"],
    )?;
    if !listed.is_empty() && !listed.ends_with(&[0]) {
        bail!(
            "git returned an unterminated untracked-file list for {}",
            repository.display()
        );
    }

    for raw in listed
        .split(|byte| *byte == 0)
        .filter(|raw| !raw.is_empty())
    {
        let (relative, nested) = untracked_record(raw, "untracked")?;
        let from_root = prefix.join(&relative);
        if is_spar_own_path(&from_root) {
            continue;
        }
        let absolute = root.join(&from_root);
        let fingerprint = if nested {
            nested_repository_fingerprint(&absolute)?
        } else {
            ignored_file_fingerprint(&absolute)?
        };
        if files.insert(from_root.clone(), fingerprint).is_some() {
            bail!(
                "git returned the untracked path more than once: {:?}",
                from_root
            );
        }
    }

    let ignored_listed = run_git_bytes(
        repository,
        &[
            "ls-files",
            "--others",
            "--ignored",
            "--exclude-standard",
            "-z",
        ],
    )?;
    if !ignored_listed.is_empty() && !ignored_listed.ends_with(&[0]) {
        bail!(
            "git returned an unterminated ignored-file list for {}",
            repository.display()
        );
    }
    // Two `ls-files` runs cannot be made to agree about a tree that is being
    // built in. A path named only by the second one was created between them,
    // which is a fact about the moment, not a corruption: record it and let the
    // comparison decide, rather than ending a run that had nothing wrong with
    // it.
    for raw in ignored_listed
        .split(|byte| *byte == 0)
        .filter(|raw| !raw.is_empty())
    {
        let (relative, nested) = untracked_record(raw, "ignored")?;
        let from_root = prefix.join(relative);
        if is_spar_own_path(&from_root) {
            continue;
        }
        if let std::collections::btree_map::Entry::Vacant(slot) = files.entry(from_root.clone()) {
            let absolute = root.join(&from_root);
            let fingerprint = if nested {
                nested_repository_fingerprint(&absolute)?
            } else {
                ignored_file_fingerprint(&absolute)?
            };
            slot.insert(fingerprint);
        }
        if !ignored.insert(from_root.clone()) {
            bail!(
                "git returned the ignored path more than once: {:?}",
                from_root
            );
        }
    }

    for link in gitlinks(repository)? {
        let Some(submodule) = initialized_submodule(repository, &link.path)? else {
            continue;
        };
        collect_untracked_files(
            root,
            &submodule,
            &prefix.join(&link.path),
            visited,
            files,
            ignored,
        )?;
    }
    Ok(())
}

fn run_git_bytes(cwd: &Path, args: &[&str]) -> Result<Vec<u8>> {
    let argv = git_without_automation_argv(args);
    proc::run_bytes(
        &argv,
        &ExecOpts::new()
            .cwd(cwd)
            .timeout_secs(30)
            .stop_descendants(true),
    )
}

fn run_git_text(cwd: &Path, args: &[&str]) -> Result<String> {
    let argv = git_without_automation_argv(args);
    proc::run(
        &argv,
        &ExecOpts::new()
            .cwd(cwd)
            .timeout_secs(30)
            .stop_descendants(true),
    )
}

fn filtered_index_content(cwd: &Path, path: &Path, oid: &str) -> Result<[u8; 32]> {
    let path = path.to_str().ok_or_else(|| {
        spar_err!(
            "cannot verify filtered content for a non-UTF-8 path in {}",
            cwd.display()
        )
    })?;
    let path_arg = format!("--path={path}");
    let bytes = run_git_bytes(cwd, &["cat-file", "--filters", &path_arg, oid])?;
    Ok(Sha256::digest(bytes).into())
}

fn safe_git_path(raw: &[u8], kind: &str) -> Result<PathBuf> {
    let relative = path_from_git_bytes(raw)?;
    if relative.is_absolute()
        || relative.components().any(|component| {
            matches!(
                component,
                std::path::Component::ParentDir
                    | std::path::Component::RootDir
                    | std::path::Component::Prefix(_)
            )
        })
    {
        bail!("git returned an unsafe {kind} path: {:?}", relative);
    }
    Ok(relative)
}

/// Split one `ls-files --others` record into its path and whether Git reported
/// a nested repository rather than a single file.
///
/// Git never lists the contents of a repository inside the working tree, so a
/// checkout parked there, such as another of SPAR's own worktrees, arrives as
/// one record for the directory itself ending in a separator. Git writes that
/// separator on every platform. Trimming it keeps the recorded path equal to
/// the same path seen any other way.
fn untracked_record(raw: &[u8], kind: &str) -> Result<(PathBuf, bool)> {
    let nested = raw.last() == Some(&b'/');
    let trimmed = if nested { &raw[..raw.len() - 1] } else { raw };
    if trimmed.is_empty() {
        bail!("git returned an empty {kind} path");
    }
    Ok((safe_git_path(trimmed, kind)?, nested))
}

fn index_entries(cwd: &Path) -> Result<Vec<IndexEntry>> {
    let listed = run_git_bytes(cwd, &["ls-files", "--stage", "-z"])?;
    if !listed.is_empty() && !listed.ends_with(&[0]) {
        bail!(
            "git returned an unterminated index listing for {}",
            cwd.display()
        );
    }
    let mut entries = Vec::new();
    for record in listed
        .split(|byte| *byte == 0)
        .filter(|record| !record.is_empty())
    {
        let Some(tab) = record.iter().position(|byte| *byte == b'\t') else {
            bail!(
                "git returned a malformed index record for {}",
                cwd.display()
            );
        };
        let header = &record[..tab];
        let fields = header.split(|byte| *byte == b' ').collect::<Vec<_>>();
        if fields.len() != 3 {
            bail!(
                "git returned a malformed index header for {}",
                cwd.display()
            );
        }
        if fields[2] != b"0" {
            continue;
        }
        let mode = std::str::from_utf8(fields[0])
            .map_err(|_| spar_err!("git returned a non-UTF-8 index mode"))?
            .to_string();
        let oid = std::str::from_utf8(fields[1])
            .map_err(|_| spar_err!("git returned a non-UTF-8 object id"))?
            .to_string();
        entries.push(IndexEntry {
            path: safe_git_path(&record[tab + 1..], "index")?,
            mode,
            oid,
        });
    }
    Ok(entries)
}

/// Share Git's complete ignore policy between call checkpoints and handoffs.
fn untracked_attribute_paths(cwd: &Path) -> Result<Vec<PathBuf>> {
    let listed = run_git_bytes(
        cwd,
        &[
            "ls-files",
            "--others",
            "--exclude-standard",
            "-z",
            "--",
            ".gitattributes",
            ":(glob)**/.gitattributes",
        ],
    )?;
    if !listed.is_empty() && !listed.ends_with(&[0]) {
        bail!(
            "git returned an unterminated attribute-file listing for {}",
            cwd.display()
        );
    }
    listed
        .split(|byte| *byte == 0)
        .filter(|record| !record.is_empty())
        .map(|raw| safe_git_path(raw, "attribute"))
        .collect()
}

fn attributes_may_be_modified(cwd: &Path) -> Result<bool> {
    if !untracked_attribute_paths(cwd)?.is_empty() {
        return Ok(true);
    }

    let index = index_entries(cwd)?
        .into_iter()
        .filter(|entry| entry.path.file_name() == Some(OsStr::new(".gitattributes")))
        .map(|entry| (entry.path, (entry.mode, entry.oid)))
        .collect::<BTreeMap<_, _>>();
    let head = tree_entries(cwd, "HEAD")?
        .into_iter()
        .filter(|entry| entry.path.file_name() == Some(OsStr::new(".gitattributes")))
        .map(|entry| (entry.path, (entry.mode, entry.oid)))
        .collect::<BTreeMap<_, _>>();
    if index != head {
        return Ok(true);
    }

    let effective = check_attributes(cwd, index.keys().cloned())?;
    let config = CheckoutConfig::read(cwd)?;
    for (path, (_mode, oid)) in index {
        let Some(worktree) = tracked_worktree_file(&cwd.join(&path), oid.len())? else {
            return Ok(true);
        };
        let attributes = effective
            .get(&path)
            .ok_or_else(|| spar_err!("git omitted attributes for {}", cwd.join(&path).display()))?;
        if allows_expected_crlf(&config, attributes)? {
            if worktree.mode == "120000" {
                return Ok(true);
            }
            let (normalized, every_lf_was_crlf) =
                normalized_git_blob_oid(&cwd.join(&path), oid.len())?;
            if !every_lf_was_crlf || normalized != oid {
                return Ok(true);
            }
        } else if worktree.raw_oid != oid {
            return Ok(true);
        }
    }
    Ok(false)
}

fn gitlinks(cwd: &Path) -> Result<Vec<Gitlink>> {
    Ok(index_entries(cwd)?
        .into_iter()
        .filter(|entry| entry.mode == "160000")
        .map(|entry| Gitlink {
            path: entry.path,
            oid: entry.oid,
        })
        .collect())
}

fn tracked_entries(cwd: &Path) -> Result<BTreeMap<PathBuf, TrackedEntry>> {
    let mut tracked = BTreeMap::new();
    for entry in index_entries(cwd)? {
        if entry.mode == "160000" {
            continue;
        }
        let worktree = tracked_worktree_file(&cwd.join(&entry.path), entry.oid.len())?;
        tracked.insert(
            entry.path,
            TrackedEntry {
                index_mode: entry.mode,
                index_oid: entry.oid,
                worktree,
            },
        );
    }
    Ok(tracked)
}

fn tracked_worktree_file(path: &Path, oid_len: usize) -> Result<Option<WorktreeFile>> {
    let metadata = match std::fs::symlink_metadata(path) {
        Ok(metadata) => metadata,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => {
            return Err(spar_err!(
                "could not inspect tracked file {}: {e}",
                path.display()
            ))
        }
    };
    let mut fingerprint = Sha256::new();
    if metadata.file_type().is_symlink() {
        let target = std::fs::read_link(path)
            .map_err(|e| spar_err!("could not read tracked symlink {}: {e}", path.display()))?;
        let bytes = os_str_bytes(target.as_os_str())?;
        fingerprint.update(b"symlink\0");
        fingerprint.update(&bytes);
        let content = Sha256::digest(&bytes).into();
        return Ok(Some(WorktreeFile {
            mode: "120000".to_string(),
            #[cfg(unix)]
            permissions: 0,
            raw_oid: git_blob_oid(oid_len, &bytes)?,
            fingerprint: fingerprint.finalize().into(),
            content,
        }));
    }
    if !metadata.is_file() {
        bail!("tracked path {} is not a file or symlink", path.display());
    }

    let mut options = OpenOptions::new();
    options.read(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.custom_flags(libc::O_NOFOLLOW);
    }
    let mut file = options
        .open(path)
        .map_err(|e| spar_err!("could not read tracked file {}: {e}", path.display()))?;
    let before = file
        .metadata()
        .map_err(|e| spar_err!("could not inspect tracked file {}: {e}", path.display()))?;
    let mode = tracked_file_mode(&before);
    #[cfg(unix)]
    let permissions = {
        use std::os::unix::fs::MetadataExt;
        before.mode() & 0o7777
    };
    fingerprint.update(b"file\0");
    fingerprint.update(mode.as_bytes());
    #[cfg(unix)]
    fingerprint.update(permissions.to_le_bytes());
    fingerprint.update(before.len().to_le_bytes());
    let mut content = Sha256::new();
    let header = format!("blob {}\0", before.len());
    let mut object = ObjectHasher::new(oid_len, header.as_bytes())?;
    let mut buf = [0u8; 64 * 1024];
    loop {
        let read = file
            .read(&mut buf)
            .map_err(|e| spar_err!("could not read tracked file {}: {e}", path.display()))?;
        if read == 0 {
            break;
        }
        fingerprint.update(&buf[..read]);
        content.update(&buf[..read]);
        object.update(&buf[..read]);
    }
    let after = file
        .metadata()
        .map_err(|e| spar_err!("could not recheck tracked file {}: {e}", path.display()))?;
    if before.len() != after.len()
        || before.modified().ok() != after.modified().ok()
        || before.permissions() != after.permissions()
    {
        bail!(
            "tracked file {} changed while it was being inspected",
            path.display()
        );
    }
    let current = std::fs::symlink_metadata(path)
        .map_err(|e| spar_err!("could not recheck tracked file {}: {e}", path.display()))?;
    if !same_file(&after, &current) {
        bail!(
            "tracked file {} was replaced while it was being inspected",
            path.display()
        );
    }
    Ok(Some(WorktreeFile {
        mode,
        #[cfg(unix)]
        permissions,
        raw_oid: object.finish(),
        fingerprint: fingerprint.finalize().into(),
        content: content.finalize().into(),
    }))
}

fn attribute_file_fingerprint(path: &Path) -> Result<[u8; 32]> {
    let metadata = std::fs::symlink_metadata(path)
        .map_err(|e| spar_err!("could not inspect attribute file {}: {e}", path.display()))?;
    let mut digest = Sha256::new();
    if metadata.file_type().is_symlink() {
        digest.update(b"symlink\0");
        let target = std::fs::read_link(path)
            .map_err(|e| spar_err!("could not read attribute symlink {}: {e}", path.display()))?;
        digest.update(os_str_bytes(target.as_os_str())?);
        return Ok(digest.finalize().into());
    }
    if !metadata.is_file() {
        bail!("attribute path {} is not a file or symlink", path.display());
    }
    let mut options = OpenOptions::new();
    options.read(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.custom_flags(libc::O_NOFOLLOW);
    }
    let mut file = options
        .open(path)
        .map_err(|e| spar_err!("could not read attribute file {}: {e}", path.display()))?;
    let before = file
        .metadata()
        .map_err(|e| spar_err!("could not inspect attribute file {}: {e}", path.display()))?;
    digest.update(b"file\0");
    let mut buf = [0u8; 64 * 1024];
    loop {
        let read = file
            .read(&mut buf)
            .map_err(|e| spar_err!("could not read attribute file {}: {e}", path.display()))?;
        if read == 0 {
            break;
        }
        digest.update(&buf[..read]);
    }
    let after = file
        .metadata()
        .map_err(|e| spar_err!("could not recheck attribute file {}: {e}", path.display()))?;
    let current = std::fs::symlink_metadata(path)
        .map_err(|e| spar_err!("could not recheck attribute file {}: {e}", path.display()))?;
    if before.len() != after.len()
        || before.modified().ok() != after.modified().ok()
        || !same_file(&after, &current)
    {
        bail!(
            "attribute file {} changed while it was being inspected",
            path.display()
        );
    }
    Ok(digest.finalize().into())
}

enum ObjectHasher {
    Sha1(Sha1),
    Sha256(Sha256),
}

impl ObjectHasher {
    fn new(oid_len: usize, header: &[u8]) -> Result<Self> {
        let mut hasher = match oid_len {
            40 => Self::Sha1(<Sha1 as sha1::Digest>::new()),
            64 => Self::Sha256(Sha256::new()),
            _ => bail!("git returned an object id with an unsupported length: {oid_len}"),
        };
        hasher.update(header);
        Ok(hasher)
    }

    fn update(&mut self, bytes: &[u8]) {
        match self {
            Self::Sha1(hasher) => sha1::Digest::update(hasher, bytes),
            Self::Sha256(hasher) => hasher.update(bytes),
        }
    }

    fn finish(self) -> String {
        let bytes = match self {
            Self::Sha1(hasher) => sha1::Digest::finalize(hasher).to_vec(),
            Self::Sha256(hasher) => hasher.finalize().to_vec(),
        };
        bytes.iter().map(|byte| format!("{byte:02x}")).collect()
    }
}

fn git_blob_oid(oid_len: usize, bytes: &[u8]) -> Result<String> {
    let header = format!("blob {}\0", bytes.len());
    let mut hasher = ObjectHasher::new(oid_len, header.as_bytes())?;
    hasher.update(bytes);
    Ok(hasher.finish())
}

fn normalized_git_blob_oid(path: &Path, oid_len: usize) -> Result<(String, bool)> {
    let mut first = open_regular_file(path)?;
    let first_before = first
        .metadata()
        .map_err(|e| spar_err!("could not inspect tracked file {}: {e}", path.display()))?;
    let mut raw_len = 0u64;
    let mut crlf_pairs = 0u64;
    let mut previous_was_cr = false;
    let mut every_lf_was_crlf = true;
    let mut buf = [0u8; 64 * 1024];
    loop {
        let read = first
            .read(&mut buf)
            .map_err(|e| spar_err!("could not read tracked file {}: {e}", path.display()))?;
        if read == 0 {
            break;
        }
        raw_len = raw_len
            .checked_add(read as u64)
            .ok_or_else(|| spar_err!("tracked file {} is too large", path.display()))?;
        for byte in &buf[..read] {
            if *byte == b'\n' {
                if previous_was_cr {
                    crlf_pairs += 1;
                } else {
                    every_lf_was_crlf = false;
                }
            }
            previous_was_cr = *byte == b'\r';
        }
    }
    let first_after = first
        .metadata()
        .map_err(|e| spar_err!("could not recheck tracked file {}: {e}", path.display()))?;
    let current = std::fs::symlink_metadata(path)
        .map_err(|e| spar_err!("could not recheck tracked file {}: {e}", path.display()))?;
    if raw_len != first_before.len()
        || !stable_file_metadata(&first_before, &first_after)
        || !stable_file_metadata(&first_after, &current)
    {
        bail!(
            "tracked file {} changed while line endings were inspected",
            path.display()
        );
    }

    let normalized_len = raw_len
        .checked_sub(crlf_pairs)
        .ok_or_else(|| spar_err!("could not normalize tracked file {}", path.display()))?;
    let header = format!("blob {normalized_len}\0");
    let mut object = ObjectHasher::new(oid_len, header.as_bytes())?;
    let mut second = open_regular_file(path)?;
    let second_before = second
        .metadata()
        .map_err(|e| spar_err!("could not inspect tracked file {}: {e}", path.display()))?;
    if !stable_file_metadata(&first_after, &second_before) {
        bail!(
            "tracked file {} changed between line-ending checks",
            path.display()
        );
    }
    let mut pending_cr = false;
    loop {
        let read = second
            .read(&mut buf)
            .map_err(|e| spar_err!("could not read tracked file {}: {e}", path.display()))?;
        if read == 0 {
            break;
        }
        for byte in &buf[..read] {
            if pending_cr {
                if *byte == b'\n' {
                    object.update(b"\n");
                    pending_cr = false;
                    continue;
                }
                object.update(b"\r");
                pending_cr = false;
            }
            if *byte == b'\r' {
                pending_cr = true;
            } else {
                object.update(std::slice::from_ref(byte));
            }
        }
    }
    if pending_cr {
        object.update(b"\r");
    }
    let second_after = second
        .metadata()
        .map_err(|e| spar_err!("could not recheck tracked file {}: {e}", path.display()))?;
    let current = std::fs::symlink_metadata(path)
        .map_err(|e| spar_err!("could not recheck tracked file {}: {e}", path.display()))?;
    if !stable_file_metadata(&second_before, &second_after)
        || !stable_file_metadata(&second_after, &current)
    {
        bail!(
            "tracked file {} changed while line endings were hashed",
            path.display()
        );
    }
    Ok((object.finish(), every_lf_was_crlf))
}

fn open_regular_file(path: &Path) -> Result<std::fs::File> {
    let mut options = OpenOptions::new();
    options.read(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.custom_flags(libc::O_NOFOLLOW);
    }
    let file = options
        .open(path)
        .map_err(|e| spar_err!("could not read tracked file {}: {e}", path.display()))?;
    let metadata = file
        .metadata()
        .map_err(|e| spar_err!("could not inspect tracked file {}: {e}", path.display()))?;
    if !metadata.is_file() {
        bail!("tracked path {} is not a regular file", path.display());
    }
    Ok(file)
}

fn stable_file_metadata(left: &std::fs::Metadata, right: &std::fs::Metadata) -> bool {
    if !same_file(left, right)
        || left.len() != right.len()
        || left.modified().ok() != right.modified().ok()
        || left.permissions() != right.permissions()
    {
        return false;
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        left.ctime() == right.ctime() && left.ctime_nsec() == right.ctime_nsec()
    }
    #[cfg(not(unix))]
    {
        left.created().ok() == right.created().ok()
    }
}

/// How many paths one `check-attr` call is asked about.
///
/// `check-attr` answers with three NUL fields per attribute per path, so the
/// output is several times the input. A whole monorepo in one call is megabytes
/// in both directions, and the 30 second timeout below is a timeout on the
/// batch. Batching keeps each call small enough to be honest about.
const ATTRIBUTE_BATCH: usize = 1000;

fn check_attributes(
    cwd: &Path,
    paths: impl IntoIterator<Item = PathBuf>,
) -> Result<BTreeMap<PathBuf, BTreeMap<String, String>>> {
    let paths = paths.into_iter().collect::<BTreeSet<_>>();
    if paths.is_empty() {
        return Ok(BTreeMap::new());
    }
    let ordered = paths.into_iter().collect::<Vec<_>>();
    let mut values: BTreeMap<PathBuf, BTreeMap<String, String>> = BTreeMap::new();
    for batch in ordered.chunks(ATTRIBUTE_BATCH) {
        values.extend(check_attribute_batch(cwd, batch)?);
    }
    Ok(values)
}

fn check_attribute_batch(
    cwd: &Path,
    batch: &[PathBuf],
) -> Result<BTreeMap<PathBuf, BTreeMap<String, String>>> {
    const NAMES: [&str; 6] = [
        "filter",
        "working-tree-encoding",
        "ident",
        "text",
        "eol",
        "crlf",
    ];
    let paths = batch.iter().cloned().collect::<BTreeSet<_>>();
    let mut input = String::new();
    for path in &paths {
        let path = path.to_str().ok_or_else(|| {
            spar_err!(
                "cannot inspect attributes for a non-UTF-8 path in {}",
                cwd.display()
            )
        })?;
        input.push_str(path);
        input.push('\0');
    }
    let argv = git_without_automation_argv(&[
        "check-attr",
        "-z",
        "--cached",
        "--stdin",
        "filter",
        "working-tree-encoding",
        "ident",
        "text",
        "eol",
        "crlf",
    ]);
    let output = proc::run_bytes(
        &argv,
        &ExecOpts::new()
            .cwd(cwd)
            .timeout_secs(30)
            .stdin(input)
            .stop_descendants(true),
    )?;
    if !output.is_empty() && !output.ends_with(&[0]) {
        bail!(
            "git returned an unterminated attribute result for {}",
            cwd.display()
        );
    }
    let fields = output
        .split(|byte| *byte == 0)
        .filter(|field| !field.is_empty())
        .collect::<Vec<_>>();
    if fields.len() != paths.len() * NAMES.len() * 3 {
        bail!(
            "git returned an unexpected attribute result for {}",
            cwd.display()
        );
    }
    let mut values: BTreeMap<PathBuf, BTreeMap<String, String>> = BTreeMap::new();
    for record in fields.chunks_exact(3) {
        let path = safe_git_path(record[0], "attribute")?;
        if !paths.contains(&path) {
            bail!(
                "git returned attributes for the wrong path in {}",
                cwd.display()
            );
        }
        let name = std::str::from_utf8(record[1])
            .map_err(|_| spar_err!("git returned a non-UTF-8 attribute name"))?;
        let value = std::str::from_utf8(record[2])
            .map_err(|_| spar_err!("git returned a non-UTF-8 attribute value"))?;
        values
            .entry(path)
            .or_default()
            .insert(name.to_string(), value.to_string());
    }
    if paths.iter().any(|path| {
        values
            .get(path)
            .is_none_or(|attributes| attributes.len() != NAMES.len())
    }) {
        bail!(
            "git omitted an attribute result for a tracked path in {}",
            cwd.display()
        );
    }
    Ok(values)
}

fn attribute_is_active(value: Option<&String>) -> bool {
    !matches!(
        value.map(String::as_str),
        None | Some("unspecified") | Some("unset")
    )
}

fn path_has_external_transform(values: &BTreeMap<String, String>) -> bool {
    attribute_is_active(values.get("filter"))
        || attribute_is_active(values.get("working-tree-encoding"))
}

/// The checkout settings a per-file line-ending decision depends on.
///
/// These are constant for a worktree, but the checks that read them run once
/// per tracked file, and each read was its own `git config` process. A
/// thousand-file repository with no `.gitattributes` takes every one of those
/// branches, which is half a minute of process spawning per scan, and the sweep
/// before a run scans every finished worktree more than once. Read them here,
/// once, and hand them down.
struct CheckoutConfig {
    autocrlf: Option<String>,
    eol: Option<String>,
    symlinks: Option<bool>,
}

impl CheckoutConfig {
    fn read(cwd: &Path) -> Result<Self> {
        Ok(Self {
            autocrlf: git_config_value(cwd, "core.autocrlf")?,
            eol: git_config_value(cwd, "core.eol")?,
            symlinks: git_config_bool(cwd, "core.symlinks")?,
        })
    }

    fn autocrlf_is_true(&self) -> bool {
        self.autocrlf.as_ref().is_some_and(|value| {
            matches!(
                value.to_ascii_lowercase().as_str(),
                "true" | "yes" | "on" | "1"
            )
        })
    }

    fn eol_is(&self, wanted: &str) -> bool {
        self.eol
            .as_ref()
            .is_some_and(|value| value.eq_ignore_ascii_case(wanted))
    }
}

fn path_has_ambiguous_transform(
    config: &CheckoutConfig,
    values: &BTreeMap<String, String>,
) -> Result<bool> {
    if path_has_external_transform(values)
        || attribute_is_active(values.get("ident"))
        || attribute_is_active(values.get("crlf"))
    {
        return Ok(true);
    }
    let text = values.get("text").map(String::as_str);
    let eol = values.get("eol").map(String::as_str);
    if text == Some("auto") {
        return Ok(true);
    }
    if !matches!(text, Some("set") | Some("unset") | Some("unspecified"))
        || !matches!(
            eol,
            Some("lf") | Some("crlf") | Some("unset") | Some("unspecified")
        )
    {
        return Ok(true);
    }
    if text == Some("unspecified") && matches!(eol, Some("unspecified") | Some("unset")) {
        return Ok(config.autocrlf_is_true());
    }
    Ok(false)
}

fn allows_expected_crlf(
    config: &CheckoutConfig,
    values: &BTreeMap<String, String>,
) -> Result<bool> {
    if path_has_external_transform(values)
        || attribute_is_active(values.get("ident"))
        || attribute_is_active(values.get("crlf"))
    {
        return Ok(false);
    }
    let text = values.get("text").map(String::as_str);
    let eol = values.get("eol").map(String::as_str);
    if matches!(text, Some("unset") | Some("auto")) || eol == Some("lf") {
        return Ok(false);
    }
    if eol == Some("crlf") {
        return Ok(true);
    }
    if text != Some("set") {
        return Ok(false);
    }
    if let Some(autocrlf) = config.autocrlf.as_deref() {
        match autocrlf.to_ascii_lowercase().as_str() {
            "true" | "yes" | "on" | "1" => return Ok(true),
            "input" => return Ok(false),
            _ => {}
        }
    }
    if config.eol_is("crlf") {
        return Ok(true);
    }
    #[cfg(windows)]
    if config.eol.is_none() || config.eol_is("native") {
        return Ok(true);
    }
    Ok(false)
}

fn git_config_value(cwd: &Path, key: &str) -> Result<Option<String>> {
    let argv = git_without_automation_argv(&["config", "--get", key]);
    let output = proc::exec(
        &argv,
        &ExecOpts::new()
            .cwd(cwd)
            .timeout_secs(30)
            .check(false)
            .stop_descendants(true),
    )?;
    match output.code {
        0 => Ok(Some(output.stdout.trim().to_string())),
        1 => Ok(None),
        _ => bail!(
            "could not read Git configuration in {}: {}",
            cwd.display(),
            output.stderr.trim()
        ),
    }
}

fn git_config_bool(cwd: &Path, key: &str) -> Result<Option<bool>> {
    let argv = git_without_automation_argv(&["config", "--type=bool", "--get", key]);
    let output = proc::exec(
        &argv,
        &ExecOpts::new()
            .cwd(cwd)
            .timeout_secs(30)
            .check(false)
            .stop_descendants(true),
    )?;
    match output.code {
        0 if output.stdout.trim() == "true" => Ok(Some(true)),
        0 if output.stdout.trim() == "false" => Ok(Some(false)),
        0 => bail!(
            "git returned an invalid boolean for {key} in {}",
            cwd.display()
        ),
        1 => Ok(None),
        _ => bail!(
            "could not read Git configuration in {}: {}",
            cwd.display(),
            output.stderr.trim()
        ),
    }
}

#[cfg(unix)]
fn tracked_file_mode(metadata: &std::fs::Metadata) -> String {
    use std::os::unix::fs::PermissionsExt;
    if metadata.permissions().mode() & 0o111 == 0 {
        "100644".to_string()
    } else {
        "100755".to_string()
    }
}

#[cfg(not(unix))]
fn tracked_file_mode(_metadata: &std::fs::Metadata) -> String {
    "100644".to_string()
}

fn tree_entries(cwd: &Path, treeish: &str) -> Result<Vec<IndexEntry>> {
    let listed = run_git_bytes(cwd, &["ls-tree", "-r", "-z", treeish])?;
    if !listed.is_empty() && !listed.ends_with(&[0]) {
        bail!(
            "git returned an unterminated tree listing for {}",
            cwd.display()
        );
    }
    let mut entries = Vec::new();
    for record in listed
        .split(|byte| *byte == 0)
        .filter(|record| !record.is_empty())
    {
        let Some(tab) = record.iter().position(|byte| *byte == b'\t') else {
            bail!("git returned a malformed tree record for {}", cwd.display());
        };
        let fields = record[..tab]
            .split(|byte| *byte == b' ')
            .collect::<Vec<_>>();
        if fields.len() != 3 {
            bail!("git returned a malformed tree header for {}", cwd.display());
        }
        let mode = std::str::from_utf8(fields[0])
            .map_err(|_| spar_err!("git returned a non-UTF-8 tree mode"))?
            .to_string();
        let oid = std::str::from_utf8(fields[2])
            .map_err(|_| spar_err!("git returned a non-UTF-8 object id"))?
            .to_string();
        entries.push(IndexEntry {
            path: safe_git_path(&record[tab + 1..], "tree")?,
            mode,
            oid,
        });
    }
    Ok(entries)
}

fn head_gitlinks(cwd: &Path) -> Result<BTreeMap<PathBuf, String>> {
    Ok(tree_entries(cwd, "HEAD")?
        .into_iter()
        .filter(|entry| entry.mode == "160000")
        .map(|entry| (entry.path, entry.oid))
        .collect())
}

fn changed_staged_gitlinks(cwd: &Path) -> Result<Vec<PathBuf>> {
    let head = head_gitlinks(cwd)?;
    let index: BTreeMap<PathBuf, String> = gitlinks(cwd)?
        .into_iter()
        .map(|link| (link.path, link.oid))
        .collect();
    let mut paths: BTreeSet<PathBuf> = head.keys().cloned().collect();
    paths.extend(index.keys().cloned());
    Ok(paths
        .into_iter()
        .filter(|path| head.get(path) != index.get(path))
        .collect())
}

fn initialized_submodule(parent: &Path, relative: &Path) -> Result<Option<PathBuf>> {
    let path = parent.join(relative);
    let metadata = match std::fs::symlink_metadata(&path) {
        Ok(metadata) => metadata,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(spar_err!("could not inspect {}: {e}", path.display())),
    };
    if !metadata.is_dir() {
        bail!("the gitlink at {} is not a directory", path.display());
    }
    let canonical = std::fs::canonicalize(&path)
        .map_err(|e| spar_err!("could not resolve {}: {e}", path.display()))?;
    if canonical != path {
        bail!(
            "the gitlink at {} resolves through a symlink",
            path.display()
        );
    }
    if !path.join(".git").exists() {
        let empty = std::fs::read_dir(&path)
            .map_err(|e| spar_err!("could not inspect {}: {e}", path.display()))?
            .next()
            .is_none();
        if empty {
            return Ok(None);
        }
        bail!(
            "the uninitialized gitlink at {} contains local files",
            path.display()
        );
    }
    let inside = run_git_text(&path, &["rev-parse", "--is-inside-work-tree"])?;
    if inside.trim() != "true" {
        bail!("the gitlink at {} is not a worktree", path.display());
    }
    let top = run_git_text(&path, &["rev-parse", "--show-toplevel"])?;
    let top = std::fs::canonicalize(top.trim()).map_err(|e| {
        spar_err!(
            "could not resolve the gitlink top level at {}: {e}",
            path.display()
        )
    })?;
    if top != canonical {
        bail!(
            "the gitlink at {} belongs to a different worktree",
            path.display()
        );
    }
    Ok(Some(canonical))
}

/// A Git entry the outer repository cannot account for.
///
/// A checkout Git itself reports as a nested repository is expected. Its
/// directory is recorded by identity in the untracked snapshot and keeps the
/// worktree from being released, so a reviewer that clones a reproduction into
/// ignored build output neither loses that clone nor fails the run over it.
/// The scan does not descend into one, because what is under it belongs to
/// that repository.
///
/// A Git entry Git does not report is the one worth stopping for. Running
/// `git init` inside a directory that already holds tracked files leaves
/// nothing in any listing while making every file written under it invisible
/// to the outer worktree, so SPAR can no longer prove what is there.
fn unexpected_nested_git_entry(cwd: &Path) -> Result<Option<PathBuf>> {
    let root = std::fs::canonicalize(cwd)
        .map_err(|e| spar_err!("could not resolve {}: {e}", cwd.display()))?;
    let mut allowed = BTreeSet::from([root.join(".git")]);
    let mut checkouts = BTreeSet::new();
    let mut repositories = vec![root.clone()];
    let mut visited = BTreeSet::new();
    while let Some(repository) = repositories.pop() {
        let canonical = std::fs::canonicalize(&repository)
            .map_err(|e| spar_err!("could not resolve {}: {e}", repository.display()))?;
        if !visited.insert(canonical.clone()) {
            bail!("submodule recursion revisited {}", canonical.display());
        }
        for raw in untracked_listing(&canonical, &["ls-files", "--others", "-z"])? {
            let (path, nested) = untracked_record(&raw, "untracked")?;
            if nested {
                checkouts.insert(canonical.join(path));
            }
        }
        for link in gitlinks(&canonical)? {
            let Some(submodule) = initialized_submodule(&canonical, &link.path)? else {
                continue;
            };
            allowed.insert(submodule.join(".git"));
            repositories.push(submodule);
        }
    }

    // A build deletes its own directories while this walks them. A directory
    // that is gone holds no Git entry, so skipping it answers the question
    // being asked; erroring instead ended runs whose worktrees were fine.
    let scan_root = root.clone();
    let mut directories = vec![root];
    while let Some(directory) = directories.pop() {
        let entries = match std::fs::read_dir(&directory) {
            Ok(entries) => entries,
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
            Err(e) => return Err(spar_err!("could not inspect {}: {e}", directory.display())),
        };
        for entry in entries {
            let entry = match entry {
                Ok(entry) => entry,
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
                Err(e) => return Err(spar_err!("could not inspect {}: {e}", directory.display())),
            };
            let path = entry.path();
            if directory == scan_root && entry.file_name() == OsStr::new(WORKTREE_DIR) {
                continue;
            }
            if entry.file_name() == OsStr::new(".git") {
                if !allowed.contains(&path) {
                    return Ok(Some(path));
                }
                continue;
            }
            let kind = match entry.file_type() {
                Ok(kind) => kind,
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
                Err(e) => return Err(spar_err!("could not inspect {}: {e}", path.display())),
            };
            if kind.is_dir() && !checkouts.contains(&path) {
                directories.push(path);
            }
        }
    }
    Ok(None)
}

pub(crate) fn git_state(cwd: &Path) -> Result<GitState> {
    if let Some(path) = unexpected_nested_git_entry(cwd)? {
        bail!(
            "the worktree contains a Git entry at {} that Git does not report as a nested \
             checkout. Files under it are invisible to the outer worktree, so SPAR cannot \
             prove they are unchanged.",
            path.display()
        );
    }
    let root = std::fs::canonicalize(cwd)
        .map_err(|e| spar_err!("could not resolve {}: {e}", cwd.display()))?;
    let mut repositories = BTreeMap::new();
    let mut visited = BTreeSet::new();
    collect_git_state(&root, Path::new(""), &mut visited, &mut repositories)?;
    Ok(GitState { repositories })
}

fn collect_git_state(
    repository: &Path,
    prefix: &Path,
    visited: &mut BTreeSet<PathBuf>,
    repositories: &mut BTreeMap<PathBuf, RepositoryState>,
) -> Result<()> {
    let canonical = std::fs::canonicalize(repository)
        .map_err(|e| spar_err!("could not resolve {}: {e}", repository.display()))?;
    if !visited.insert(canonical.clone()) {
        bail!("submodule recursion revisited {}", canonical.display());
    }
    let head = run_git_text(repository, &["rev-parse", "--verify", "HEAD^{commit}"])?;
    let head = head.trim().to_string();
    if head.is_empty() {
        bail!("git returned an empty head for {}", repository.display());
    }
    let unsafe_index_flags = unsafe_index_flags(repository)?;
    let tracked = tracked_entries(repository)?;
    let gitlinks = gitlinks(repository)?;
    if repositories
        .insert(
            prefix.to_path_buf(),
            RepositoryState {
                head,
                unsafe_index_flags,
                tracked,
                gitlinks: gitlinks
                    .iter()
                    .map(|link| (link.path.clone(), link.oid.clone()))
                    .collect(),
            },
        )
        .is_some()
    {
        bail!("Git state contains duplicate repository path {:?}", prefix);
    }

    for link in gitlinks {
        let Some(submodule) = initialized_submodule(repository, &link.path)? else {
            continue;
        };
        collect_git_state(&submodule, &prefix.join(&link.path), visited, repositories)?;
    }
    Ok(())
}

fn unsafe_index_flags(cwd: &Path) -> Result<Vec<u8>> {
    let listed = run_git_bytes(cwd, &["ls-files", "-v", "-z"])?;
    if !listed.is_empty() && !listed.ends_with(&[0]) {
        bail!(
            "git returned an unterminated index-flag listing for {}",
            cwd.display()
        );
    }
    let mut unsafe_records = Vec::new();
    for record in listed
        .split(|byte| *byte == 0)
        .filter(|record| !record.is_empty())
    {
        if record.len() < 3 || record[1] != b' ' {
            bail!(
                "git returned a malformed index-flag record for {}",
                cwd.display()
            );
        }
        if record[0] != b'H' {
            unsafe_records.extend_from_slice(record);
            unsafe_records.push(0);
        }
    }
    Ok(unsafe_records)
}

pub(crate) fn refuse_unsafe_index_flags(cwd: &Path) -> Result<()> {
    safe_git_state(cwd).map(|_| ())
}

pub(crate) fn safe_git_state(cwd: &Path) -> Result<GitState> {
    let state = git_state(cwd)?;
    if let Some((path, _repository)) = state
        .repositories
        .iter()
        .find(|(_, repository)| !repository.unsafe_index_flags.is_empty())
    {
        let label = if path.as_os_str().is_empty() {
            cwd.to_path_buf()
        } else {
            cwd.join(path)
        };
        bail!(
            "the index at {} has assume-unchanged, skip-worktree, or another nonstandard flag. \
             SPAR cannot prove the working files are unchanged, so it was kept.",
            label.display()
        );
    }
    Ok(state)
}

fn repository_has_recoverable_work(cwd: &Path, include_ignored: bool) -> Result<bool> {
    repository_has_recoverable_work_with(cwd, include_ignored, Disposable::BuildOutput)
}

fn repository_has_recoverable_work_with(
    cwd: &Path,
    include_ignored: bool,
    disposable: Disposable,
) -> Result<bool> {
    if include_ignored && unexpected_nested_git_entry(cwd)?.is_some() {
        return Ok(true);
    }
    let mut visited = BTreeSet::new();
    repository_has_recoverable_work_inner(cwd, include_ignored, disposable, &mut visited)
}

fn has_recoverable_worktree_admin_state(cwd: &Path) -> Result<bool> {
    let git_dir = run_git_text(cwd, &["rev-parse", "--git-dir"])?;
    let git_dir = PathBuf::from(git_dir.trim());
    let git_dir = if git_dir.is_absolute() {
        git_dir
    } else {
        cwd.join(git_dir)
    };
    let git_dir = std::fs::canonicalize(&git_dir)
        .map_err(|e| spar_err!("could not resolve {}: {e}", git_dir.display()))?;
    match std::fs::symlink_metadata(git_dir.join("config.worktree")) {
        Ok(_) => return Ok(true),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
        Err(error) => {
            return Err(spar_err!(
                "could not inspect per-worktree configuration in {}: {error}",
                git_dir.display()
            ))
        }
    }

    let orig_head = git_dir.join("ORIG_HEAD");
    match std::fs::symlink_metadata(&orig_head) {
        Ok(metadata) if metadata.is_file() => {
            let oid = std::fs::read_to_string(&orig_head)
                .map_err(|e| spar_err!("could not read {}: {e}", orig_head.display()))?;
            let Some(commit) = resolve_optional_commit(cwd, oid.trim())? else {
                return Ok(true);
            };
            if !commit_has_shared_ref(cwd, &commit)? {
                return Ok(true);
            }
        }
        Ok(_) => return Ok(true),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
        Err(error) => {
            return Err(spar_err!(
                "could not inspect {}: {error}",
                orig_head.display()
            ))
        }
    }

    let edit_message = git_dir.join("COMMIT_EDITMSG");
    match std::fs::symlink_metadata(&edit_message) {
        Ok(metadata) if metadata.is_file() => {
            let draft = std::fs::read(&edit_message)
                .map_err(|e| spar_err!("could not read {}: {e}", edit_message.display()))?;
            if draft != head_commit_message(cwd)? {
                return Ok(true);
            }
        }
        Ok(_) => return Ok(true),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
        Err(error) => {
            return Err(spar_err!(
                "could not inspect {}: {error}",
                edit_message.display()
            ))
        }
    }

    if reflogs_have_unpreserved_commits(cwd, &git_dir.join("logs"))? {
        return Ok(true);
    }

    let local_refs = run_git_bytes(
        cwd,
        &[
            "for-each-ref",
            "--format=%(refname)",
            "refs/worktree",
            "refs/bisect",
            "refs/rewritten",
        ],
    )?;
    if !local_refs.is_empty() {
        return Ok(true);
    }

    // `FETCH_HEAD` only names what a `git fetch` in this worktree brought
    // down. The objects live in the shared store and the next fetch rewrites
    // it, so an agent that fetched once must not keep the checkout forever.
    for entry in std::fs::read_dir(&git_dir)
        .map_err(|e| spar_err!("could not inspect {}: {e}", git_dir.display()))?
    {
        let entry = entry.map_err(|e| spar_err!("could not inspect {}: {e}", git_dir.display()))?;
        let known = matches!(
            entry.file_name().to_str(),
            Some(
                "HEAD"
                    | "ORIG_HEAD"
                    | "COMMIT_EDITMSG"
                    | "FETCH_HEAD"
                    | "commondir"
                    | "gitdir"
                    | "index"
                    | "logs"
                    | "refs"
            )
        );
        if !known {
            return Ok(true);
        }
    }

    let head = run_git_text(cwd, &["rev-parse", "--verify", "HEAD^{commit}"])?;
    if !commit_has_shared_ref(cwd, head.trim())? {
        return Ok(true);
    }
    Ok(false)
}

fn head_commit_message(cwd: &Path) -> Result<Vec<u8>> {
    let commit = run_git_bytes(cwd, &["cat-file", "commit", "HEAD"])?;
    let Some(split) = commit.windows(2).position(|bytes| bytes == b"\n\n") else {
        bail!(
            "git returned a commit without a message separator in {}",
            cwd.display()
        );
    };
    Ok(commit[split + 2..].to_vec())
}

fn reflogs_have_unpreserved_commits(cwd: &Path, logs: &Path) -> Result<bool> {
    let metadata = match std::fs::symlink_metadata(logs) {
        Ok(metadata) => metadata,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(false),
        Err(error) => return Err(spar_err!("could not inspect {}: {error}", logs.display())),
    };
    if !metadata.is_dir() {
        return Ok(true);
    }
    let mut files = Vec::new();
    let mut directories = vec![logs.to_path_buf()];
    while let Some(directory) = directories.pop() {
        for entry in std::fs::read_dir(&directory)
            .map_err(|e| spar_err!("could not inspect {}: {e}", directory.display()))?
        {
            let entry =
                entry.map_err(|e| spar_err!("could not inspect {}: {e}", directory.display()))?;
            let path = entry.path();
            let kind = entry
                .file_type()
                .map_err(|e| spar_err!("could not inspect {}: {e}", path.display()))?;
            if kind.is_dir() {
                directories.push(path);
            } else if kind.is_file() {
                files.push(path);
            } else {
                return Ok(true);
            }
        }
    }

    let mut commits = BTreeSet::new();
    for path in files {
        if !collect_reflog_commits(cwd, &path, &mut commits)? {
            return Ok(true);
        }
    }
    for commit in commits {
        if !commit_has_shared_ref(cwd, &commit)? {
            return Ok(true);
        }
    }
    Ok(false)
}

/// Every commit named by one ref's common reflog must survive deletion of that
/// ref. Ancestors of a durable current tip survive with the tip; divergent
/// entries need another shared ref of their own.
fn ref_reflog_is_preserved(cwd: &Path, refname: &str, durable_tip: &str) -> Result<bool> {
    let common = common_git_dir(cwd)?;
    let reflog = common.join("logs").join(refname);
    let metadata = match std::fs::symlink_metadata(&reflog) {
        Ok(metadata) => metadata,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(true),
        Err(error) => return Err(spar_err!("could not inspect {}: {error}", reflog.display())),
    };
    if !metadata.is_file() {
        return Ok(false);
    }
    let mut commits = BTreeSet::new();
    if !collect_reflog_commits(cwd, &reflog, &mut commits)? {
        return Ok(false);
    }
    for commit in commits {
        if is_ancestor(cwd, &commit, durable_tip)?
            || commit_has_shared_ref_except(cwd, &commit, Some(refname))?
        {
            continue;
        }
        return Ok(false);
    }
    Ok(true)
}

fn collect_reflog_commits(cwd: &Path, path: &Path, commits: &mut BTreeSet<String>) -> Result<bool> {
    let file = std::fs::File::open(path)
        .map_err(|e| spar_err!("could not read {}: {e}", path.display()))?;
    for line in std::io::BufReader::new(file).lines() {
        let line = line.map_err(|e| spar_err!("could not read {}: {e}", path.display()))?;
        let mut fields = line.splitn(3, ' ');
        let Some(old) = fields.next() else {
            return Ok(false);
        };
        let Some(new) = fields.next() else {
            return Ok(false);
        };
        if fields.next().is_none() {
            return Ok(false);
        }
        for oid in [old, new] {
            if oid.bytes().all(|byte| byte == b'0') {
                continue;
            }
            let Some(commit) = resolve_optional_commit(cwd, oid)? else {
                return Ok(false);
            };
            commits.insert(commit);
        }
    }
    Ok(true)
}

fn common_git_dir(cwd: &Path) -> Result<PathBuf> {
    let raw = run_git_text(cwd, &["rev-parse", "--git-common-dir"])?;
    let path = PathBuf::from(raw.trim());
    let path = if path.is_absolute() {
        path
    } else {
        cwd.join(path)
    };
    std::fs::canonicalize(&path).map_err(|e| spar_err!("could not resolve {}: {e}", path.display()))
}

fn is_ancestor(cwd: &Path, older: &str, newer: &str) -> Result<bool> {
    let argv = git_without_automation_argv(&["merge-base", "--is-ancestor", older, newer]);
    let output = proc::exec(
        &argv,
        &ExecOpts::new()
            .cwd(cwd)
            .timeout_secs(30)
            .check(false)
            .stop_descendants(true),
    )?;
    match output.code {
        0 => Ok(true),
        1 => Ok(false),
        _ => bail!("{}", proc::failure_message(&argv, &output)),
    }
}

fn resolve_optional_commit(cwd: &Path, oid: &str) -> Result<Option<String>> {
    let commit = format!("{oid}^{{commit}}");
    let argv = git_without_automation_argv(&["rev-parse", "--quiet", "--verify", &commit]);
    let output = proc::exec(
        &argv,
        &ExecOpts::new()
            .cwd(cwd)
            .timeout_secs(30)
            .check(false)
            .stop_descendants(true),
    )?;
    if output.code != 0 {
        return Ok(None);
    }
    let oid = output.stdout.trim();
    if oid.is_empty() {
        return Ok(None);
    }
    Ok(Some(oid.to_string()))
}

fn commit_has_shared_ref(cwd: &Path, oid: &str) -> Result<bool> {
    commit_has_shared_ref_except(cwd, oid, None)
}

fn commit_has_shared_ref_except(cwd: &Path, oid: &str, exclude: Option<&str>) -> Result<bool> {
    let contains = format!("--contains={oid}");
    let shared = run_git_bytes(cwd, &["for-each-ref", "--format=%(refname)", &contains])?;
    Ok(shared.split(|byte| *byte == b'\n').any(|record| {
        !record.is_empty()
            && !record.starts_with(b"refs/worktree/")
            && !record.starts_with(b"refs/bisect/")
            && !record.starts_with(b"refs/rewritten/")
            && exclude.is_none_or(|excluded| record != excluded.as_bytes())
    }))
}

/// Whether removing the worktree would take away an untracked file somebody
/// might want back.
///
/// Ordinary untracked files always count. So does an ignored file outside the
/// known build and cache directories, because an ignored path is only a path
/// Git was told not to track, which is where a local `.env` lives as readily as
/// compiler output.
///
/// Recognized build and cache output does not. A managed commit already leaves
/// it out rather than treating it as work, and the command that wrote it writes
/// it again. Counting it kept every worktree whose tests or build had run,
/// which is nearly all of them, so a merged pull request still left its
/// checkout behind. A repository nested in that output is somebody else's
/// history and counts whatever it sits under.
fn has_untracked_work_worth_keeping(cwd: &Path, disposable: Disposable) -> Result<bool> {
    let ordinary = untracked_listing(cwd, &["ls-files", "--others", "--exclude-standard", "-z"])?;
    for raw in &ordinary {
        let (path, _) = untracked_record(raw, "untracked")?;
        if disposable == Disposable::ReviewOutput && is_spar_marker(&path) {
            continue;
        }
        return Ok(true);
    }
    let listed = untracked_listing(
        cwd,
        &[
            "ls-files",
            "--others",
            "--ignored",
            "--exclude-standard",
            "-z",
        ],
    )?;
    for raw in listed {
        let (path, nested) = untracked_record(&raw, "ignored")?;
        // A repository cloned into the output keeps the checkout whatever the
        // mode: its objects exist nowhere else, which is the one thing a
        // rebuild from origin cannot replace.
        if nested {
            return Ok(true);
        }
        if disposable == Disposable::BuildOutput
            && !is_generated_artifact(&path)
            && !is_desktop_metadata(&path)
        {
            return Ok(true);
        }
    }
    Ok(false)
}

fn untracked_listing(cwd: &Path, args: &[&str]) -> Result<Vec<Vec<u8>>> {
    let listed = run_git_bytes(cwd, args)?;
    if !listed.is_empty() && !listed.ends_with(&[0]) {
        bail!(
            "git returned an unterminated untracked-file list for {}",
            cwd.display()
        );
    }
    Ok(listed
        .split(|byte| *byte == 0)
        .filter(|raw| !raw.is_empty())
        .map(|raw| raw.to_vec())
        .collect())
}

fn repository_has_recoverable_work_inner(
    cwd: &Path,
    include_ignored: bool,
    disposable: Disposable,
    visited: &mut BTreeSet<PathBuf>,
) -> Result<bool> {
    let canonical = std::fs::canonicalize(cwd)
        .map_err(|e| spar_err!("could not resolve {}: {e}", cwd.display()))?;
    if !visited.insert(canonical.clone()) {
        bail!("submodule recursion revisited {}", canonical.display());
    }
    if include_ignored && has_untracked_work_worth_keeping(cwd, disposable)? {
        return Ok(true);
    }
    if !unsafe_index_flags(cwd)?.is_empty() {
        return Ok(true);
    }
    if attributes_may_be_modified(cwd)? {
        return Ok(true);
    }
    if include_ignored && has_recoverable_worktree_admin_state(cwd)? {
        return Ok(true);
    }
    if include_ignored {
        let index = index_entries(cwd)?
            .into_iter()
            .map(|entry| (entry.path, (entry.mode, entry.oid)))
            .collect::<BTreeMap<_, _>>();
        let head = tree_entries(cwd, "HEAD")?
            .into_iter()
            .map(|entry| (entry.path, (entry.mode, entry.oid)))
            .collect::<BTreeMap<_, _>>();
        if index != head || !run_git_bytes(cwd, &["ls-files", "--unmerged", "-z"])?.is_empty() {
            return Ok(true);
        }
        let tracked = tracked_entries(cwd)?;
        let effective = check_attributes(cwd, tracked.keys().cloned())?;
        let config = CheckoutConfig::read(cwd)?;
        for (path, entry) in tracked {
            let Some(worktree) = entry.worktree else {
                return Ok(true);
            };
            let attributes = effective.get(&path).ok_or_else(|| {
                spar_err!("git omitted attributes for {}", cwd.join(&path).display())
            })?;
            if path_has_ambiguous_transform(&config, attributes)? {
                return Ok(true);
            }
            let symlink_file = entry.index_mode == "120000"
                && worktree.mode == "100644"
                && worktree.raw_oid == entry.index_oid
                && config.symlinks == Some(false);
            if worktree.mode != entry.index_mode && !symlink_file {
                return Ok(true);
            }
            if entry.index_mode == "120000" {
                if worktree.raw_oid != entry.index_oid {
                    return Ok(true);
                }
                continue;
            }
            #[cfg(unix)]
            {
                let expected = if entry.index_mode == "100755" {
                    0o755
                } else {
                    0o644
                };
                if worktree.permissions != expected {
                    return Ok(true);
                }
            }
            if allows_expected_crlf(&config, attributes)? {
                let (normalized, every_lf_was_crlf) =
                    normalized_git_blob_oid(&cwd.join(&path), entry.index_oid.len())?;
                if !every_lf_was_crlf || normalized != entry.index_oid {
                    return Ok(true);
                }
            } else if worktree.raw_oid != entry.index_oid {
                return Ok(true);
            }
        }
    } else {
        let args = ["status", "--porcelain=v1", "-z", "--untracked-files=all"];
        if !run_git_bytes(cwd, &args)?.is_empty() {
            return Ok(true);
        }
    }
    for link in gitlinks(cwd)? {
        let Some(submodule) = initialized_submodule(cwd, &link.path)? else {
            continue;
        };
        // Git stores a linked worktree's initialized submodule objects under
        // that worktree's administrative directory. Ordinary removal cannot
        // prove a local submodule commit exists anywhere else, even when both
        // working trees look clean.
        if include_ignored {
            return Ok(true);
        }
        let head = run_git_text(&submodule, &["rev-parse", "--verify", "HEAD^{commit}"])?;
        if head.trim() != link.oid {
            return Ok(true);
        }
        if repository_has_recoverable_work_inner(&submodule, include_ignored, disposable, visited)?
        {
            return Ok(true);
        }
    }
    Ok(false)
}

pub(crate) fn has_uncommitted_work(cwd: &Path) -> Result<bool> {
    repository_has_recoverable_work(cwd, false)
}

fn has_tracked_or_staged_work(cwd: &Path) -> Result<bool> {
    let args = ["status", "--porcelain=v1", "-z", "--untracked-files=no"];
    Ok(!run_git_bytes(cwd, &args)?.is_empty())
}

#[cfg(unix)]
fn path_from_git_bytes(raw: &[u8]) -> Result<PathBuf> {
    use std::os::unix::ffi::OsStringExt;
    Ok(PathBuf::from(std::ffi::OsString::from_vec(raw.to_vec())))
}

#[cfg(not(unix))]
fn path_from_git_bytes(raw: &[u8]) -> Result<PathBuf> {
    String::from_utf8(raw.to_vec())
        .map(PathBuf::from)
        .map_err(|_| spar_err!("git returned a non-UTF-8 ignored path"))
}

/// Fingerprint the directory of a nested repository without reading inside it.
///
/// The files under it are that repository's, not this one's. They are recorded
/// against its own baseline whenever SPAR works there, and a run of its own may
/// legitimately add or remove entries while this call is in flight, so the
/// volatile directory fields stay out of the fingerprint. Identity and type
/// remain, which is what makes deleting the checkout, or replacing it with a
/// file, observable from the outer worktree.
/// What a path Git listed looks like once it is no longer there.
///
/// A reviewer building the project deletes and rewrites its output constantly,
/// so a path can go between the listing that named it and the stat that
/// measures it. Treating that as an unreadable worktree ended runs that had
/// nothing wrong with them. The record stays in the snapshot rather than being
/// dropped, so a path that vanishes cannot pass for one that was never there.
fn vanished_untracked_file() -> UntrackedFile {
    UntrackedFile {
        kind: 0,
        len: 0,
        modified: None,
        created: None,
        readonly: false,
        symlink_target: None,
        #[cfg(unix)]
        device: 0,
        #[cfg(unix)]
        inode: 0,
        #[cfg(unix)]
        mode: 0,
        #[cfg(unix)]
        change_seconds: 0,
        #[cfg(unix)]
        change_nanoseconds: 0,
    }
}

fn nested_repository_fingerprint(path: &Path) -> Result<UntrackedFile> {
    let metadata = match std::fs::symlink_metadata(path) {
        Ok(metadata) => metadata,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(vanished_untracked_file()),
        Err(e) => {
            return Err(spar_err!(
                "could not inspect the nested repository at {}: {e}",
                path.display()
            ))
        }
    };
    if !metadata.is_dir() {
        bail!(
            "git reported {} as a nested repository, but it is not a directory",
            path.display()
        );
    }
    if std::fs::symlink_metadata(path.join(".git")).is_err() {
        bail!(
            "git reported {} as a nested repository, but it has no Git entry",
            path.display()
        );
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        Ok(UntrackedFile {
            kind: 3,
            len: 0,
            modified: None,
            created: metadata.created().ok(),
            readonly: metadata.permissions().readonly(),
            symlink_target: None,
            device: metadata.dev(),
            inode: metadata.ino(),
            mode: metadata.mode(),
            change_seconds: 0,
            change_nanoseconds: 0,
        })
    }
    #[cfg(not(unix))]
    {
        Ok(UntrackedFile {
            kind: 3,
            len: 0,
            modified: None,
            created: metadata.created().ok(),
            readonly: metadata.permissions().readonly(),
            symlink_target: None,
        })
    }
}

fn ignored_file_fingerprint(path: &Path) -> Result<UntrackedFile> {
    let metadata = match std::fs::symlink_metadata(path) {
        Ok(metadata) => metadata,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(vanished_untracked_file()),
        Err(e) => {
            return Err(spar_err!(
                "could not inspect untracked file {}: {e}",
                path.display()
            ))
        }
    };
    let kind = if metadata.file_type().is_symlink() {
        2
    } else if metadata.is_file() {
        1
    } else {
        bail!(
            "untracked path {} is not a regular file or symlink",
            path.display()
        );
    };
    let symlink_target = if kind == 2 {
        match std::fs::read_link(path) {
            Ok(target) => Some(os_str_bytes(target.as_os_str())?),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                return Ok(vanished_untracked_file())
            }
            Err(e) => {
                return Err(spar_err!(
                    "could not read untracked symlink {}: {e}",
                    path.display()
                ))
            }
        }
    } else {
        None
    };
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        Ok(UntrackedFile {
            kind,
            len: metadata.len(),
            modified: metadata.modified().ok(),
            created: metadata.created().ok(),
            readonly: metadata.permissions().readonly(),
            symlink_target,
            device: metadata.dev(),
            inode: metadata.ino(),
            mode: metadata.mode(),
            change_seconds: metadata.ctime(),
            change_nanoseconds: metadata.ctime_nsec(),
        })
    }
    #[cfg(not(unix))]
    {
        Ok(UntrackedFile {
            kind,
            len: metadata.len(),
            modified: metadata.modified().ok(),
            created: metadata.created().ok(),
            readonly: metadata.permissions().readonly(),
            symlink_target,
        })
    }
}

#[cfg(unix)]
fn os_str_bytes(value: &OsStr) -> Result<Vec<u8>> {
    use std::os::unix::ffi::OsStrExt;
    Ok(value.as_bytes().to_vec())
}

#[cfg(not(unix))]
fn os_str_bytes(value: &OsStr) -> Result<Vec<u8>> {
    value
        .to_str()
        .map(|value| value.as_bytes().to_vec())
        .ok_or_else(|| spar_err!("a filesystem path is not UTF-8"))
}

#[cfg(unix)]
fn same_file(left: &std::fs::Metadata, right: &std::fs::Metadata) -> bool {
    use std::os::unix::fs::MetadataExt;
    right.is_file() && left.dev() == right.dev() && left.ino() == right.ino()
}

#[cfg(not(unix))]
fn same_file(left: &std::fs::Metadata, right: &std::fs::Metadata) -> bool {
    right.is_file() && left.len() == right.len() && left.permissions() == right.permissions()
}

#[derive(Debug, Clone, serde::Serialize, Deserialize)]
pub struct BranchRecord {
    pub kind: String,
    pub number: i64,
}

/// Where a pull request's fetched head is parked. Under `refs/spar/` rather
/// than `refs/heads/` so it can never be mistaken for a branch, or pushed.
pub fn review_ref(number: i64) -> String {
    format!("refs/spar/pr-{number}")
}

pub fn is_finished(state: &str) -> bool {
    matches!(state.trim().to_uppercase().as_str(), "MERGED" | "CLOSED")
}

/// Write text through a temporary file and rename, so a kill cannot leave a
/// truncated file behind.
///
/// The follow-up queue is the one file spar rewrites in place rather than
/// appends to, and a truncated queue is lost work: what it held was never
/// written anywhere else.
pub fn write_text_atomic(path: &Path, text: &str) -> Result<()> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)
            .map_err(|e| spar_err!("could not create {}: {e}", parent.display()))?;
    }
    // The extension defaults to `json` so `clear_state`, which removes a
    // leftover `pr-N.json.tmp` by name, keeps finding the one this wrote.
    let tmp = path.with_extension(format!(
        "{}.tmp",
        path.extension().and_then(|e| e.to_str()).unwrap_or("json")
    ));
    std::fs::write(&tmp, text).map_err(|e| spar_err!("could not write {}: {e}", tmp.display()))?;
    std::fs::rename(&tmp, path)
        .map_err(|e| spar_err!("could not replace {}: {e}", path.display()))?;
    Ok(())
}

/// Whether a follow-up file already has an entry under this exact title.
///
/// Whole heading lines, case insensitively. A substring check answered yes
/// for "Retry loop" against "## Retry loop never terminates", which is a
/// different defect, and the new one was dropped with a line saying it was
/// already noted.
pub fn has_heading(text: &str, title: &str) -> bool {
    let wanted = title.trim().to_lowercase();
    if wanted.is_empty() {
        return false;
    }
    text.lines()
        .filter_map(|line| line.trim().strip_prefix("## "))
        .any(|heading| heading.trim().to_lowercase() == wanted)
}

/// Write JSON through a temporary file and rename, so a kill cannot leave a
/// truncated state file behind.
pub fn write_json_atomic<T: serde::Serialize>(path: &Path, value: &T) -> Result<()> {
    write_text_atomic(path, &serde_json::to_string_pretty(value)?)
}

/// One row of `gh pr list --json number,url,title,baseRefName,closingIssuesReferences`.
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LinkedPrRow {
    number: i64,
    #[serde(default)]
    url: String,
    #[serde(default)]
    title: String,
    #[serde(default)]
    closing_issues_references: Vec<IssueRef>,
}

/// The listed pull requests, or `None` when the payload could not be read.
///
/// Separated from the gh call so the real payload shape can be tested, and kept
/// distinct from an empty list, because silently failing to parse would look
/// exactly like "no pull request exists", which is the answer that makes spar
/// implement over the top of somebody's work.
pub fn linked_pr_rows(json: &str) -> Option<Vec<LinkedPrRow>> {
    serde_json::from_str::<Vec<LinkedPrRow>>(json.trim()).ok()
}

/// Among the listed pull requests, the first that would close `issue`.
pub fn pick_linked_pr(rows: &[LinkedPrRow], issue: i64) -> Option<PrRef> {
    rows.iter()
        .find(|row| {
            row.closing_issues_references
                .iter()
                .any(|linked| linked.number == issue)
        })
        .map(|row| PrRef {
            number: row.number,
            url: row.url.clone(),
            title: row.title.clone(),
        })
}

/// Both halves together, for the tests that hold the real payload.
pub fn find_linked_pr(json: &str, issue: i64) -> Option<PrRef> {
    pick_linked_pr(&linked_pr_rows(json)?, issue)
}

/// Flatten whatever `gh api --paginate` printed into a list of comments.
///
/// Current gh merges array pages into one array. Older builds concatenated one
/// document per page. A streaming parser reads either, and unlike splitting the
/// text on a bracket pair it cannot be fooled by a comment body that happens to
/// contain one, which would otherwise make a resume silently start over.
pub(crate) fn try_parse_comment_pages(text: &str) -> Result<Vec<Value>> {
    if text.trim().is_empty() {
        return Err(spar_err!("GitHub returned no comment data"));
    }
    let mut out = Vec::new();
    for value in serde_json::Deserializer::from_str(text.trim()).into_iter::<Value>() {
        match value.map_err(|e| spar_err!("unexpected comment pages: {e}"))? {
            Value::Array(items) => out.extend(items),
            _ => return Err(spar_err!("unexpected non-array comment page")),
        }
    }
    Ok(out)
}

pub fn parse_comment_pages(text: &str) -> Vec<Value> {
    let mut out = Vec::new();
    for value in serde_json::Deserializer::from_str(text.trim()).into_iter::<Value>() {
        match value {
            Ok(Value::Array(items)) => out.extend(items),
            Ok(other) => out.push(other),
            Err(_) => break,
        }
    }
    out
}

/// Whether a comment is a state block spar itself wrote.
///
/// The body has to open with the marker, so a person quoting it in a sentence
/// is not one; it has to parse, so a half-quoted block is not one; and it has
/// to be the viewer's own comment, the way `comments.rs` already tells spar's
/// writes apart. Anything less and `write_pr_state` patches somebody's comment
/// with JSON, and `spar clean --pr-state` later deletes it.
pub fn is_state_comment(body: &str, author: &str, viewer: &str) -> bool {
    body.trim_start().starts_with(STATE_MARKER)
        && !viewer.trim().is_empty()
        && author.trim().eq_ignore_ascii_case(viewer.trim())
        && parse_state_comment(body).is_some()
}

/// Extract the payload from a state comment. The marker is followed by JSON and
/// terminated with `-->`.
pub fn parse_state_comment(body: &str) -> Option<PersistedState> {
    let marker = body.find(STATE_MARKER)?;
    let start = body[marker..].find('{')? + marker;
    let end = body.rfind('}')?;
    if end <= start {
        return None;
    }
    match serde_json::from_str(&body[start..=end]) {
        Ok(state) => Some(state),
        Err(_) => {
            logdim!("found a spar state comment but could not parse it");
            None
        }
    }
}

fn choose_state_for_head(
    candidates: Vec<PersistedState>,
    actual_head: &str,
) -> Option<PersistedState> {
    let matching: Vec<PersistedState> = candidates
        .iter()
        .filter(|state| state.pr_head == actual_head)
        .cloned()
        .collect();
    if !matching.is_empty() {
        return newest_state(matching);
    }
    newest_state(candidates)
}

fn newest_state(candidates: Vec<PersistedState>) -> Option<PersistedState> {
    candidates.into_iter().reduce(|best, candidate| {
        if (candidate.checkpoint, candidate.round) > (best.checkpoint, best.round) {
            candidate
        } else {
            // The local candidate is supplied first. Keeping the first exact
            // tie recovers correctly from a local write followed by a failed
            // pull request state update, including legacy states with no
            // checkpoint field.
            best
        }
    })
}

/// Where this binary lives, so `git filter-branch` can call back into it.
///
/// `SPAR_SELF_BIN` overrides the answer. That matters for the integration
/// tests, whose `current_exe` is the test harness rather than spar, and for
/// anyone who ships spar behind a wrapper script.
pub fn self_binary() -> Result<PathBuf> {
    if let Some(path) = std::env::var_os("SPAR_SELF_BIN") {
        let path = PathBuf::from(path);
        if proc::is_executable(&path) {
            return Ok(path);
        }
        bail!(
            "SPAR_SELF_BIN is set to {}, which is not executable",
            path.display()
        );
    }
    std::env::current_exe()
        .map_err(|e| spar_err!("could not locate the spar binary for a commit rewrite: {e}"))
}

fn bool_env(value: bool) -> &'static str {
    if value {
        "1"
    } else {
        "0"
    }
}

/// Wrap a string for a POSIX shell. `git filter-branch` takes its filter as a
/// shell command, and an install path with a space in it is not exotic.
pub fn sh_quote(text: &str) -> String {
    format!("'{}'", text.replace('\'', r"'\''"))
}

/// Style rules for the `scrub-filter` subcommand, which runs in a child process
/// spawned by git and so cannot see the parent's config.
pub fn style_from_env() -> Style {
    let flag = |key: &str| !matches!(std::env::var(key).as_deref(), Ok("0"));
    Style {
        ban_em_dash: flag("SPAR_BAN_EM_DASH"),
        ban_ai_attribution: flag("SPAR_BAN_AI_ATTRIBUTION"),
        ..Style::permissive()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::StateStore;
    use crate::model::{Dispute, Finding, Ledger, PersistedState, Severity, Status};
    use std::process::Command;

    fn repo_for_titles() -> Repo {
        Repo {
            root: PathBuf::from("/nonexistent"),
            style: Style::default(),
            branch_prefix: String::new(),
            state_store: StateStore::Local,
            followups: crate::config::Followups::Issues,
            drafts: Drafts::Never,
            viewer: OnceLock::new(),
            checkpoints: Mutex::new(BTreeMap::new()),
            writes: WriteStats::default(),
        }
    }

    #[test]
    fn write_results_accumulate_for_the_run() {
        let repo = repo_for_titles();

        let _: std::result::Result<(), ()> = repo.record_write(Ok(()));
        let _: std::result::Result<(), ()> = repo.record_write(Err(()));

        assert_eq!(
            WriteSummary {
                attempted: 2,
                failed: 1,
            },
            repo.write_summary()
        );
    }

    #[test]
    fn only_failed_write_preflights_join_the_summary() {
        let repo = repo_for_titles();

        let _: std::result::Result<(), ()> = repo.record_failed_write(Ok(()));
        let _: std::result::Result<(), ()> = repo.record_failed_write(Err(()));

        assert_eq!(
            WriteSummary {
                attempted: 1,
                failed: 1,
            },
            repo.write_summary()
        );
    }

    #[test]
    fn a_nonempty_write_title_that_cleans_to_empty_is_one_failed_preflight() {
        let repo = repo_for_titles();

        assert!(repo.clean_nonempty_title_for_write("\u{1F916}").is_err());
        assert_eq!(
            WriteSummary {
                attempted: 1,
                failed: 1,
            },
            repo.write_summary()
        );
    }

    #[test]
    fn a_local_followup_title_failure_is_not_a_remote_write_failure() {
        let mut repo = repo_for_titles();
        repo.followups = Followups::Local;

        assert_eq!("", repo.clean_followup_title("\u{1F916}").unwrap());
        assert_eq!(WriteSummary::default(), repo.write_summary());
    }

    #[test]
    fn a_failed_remote_state_read_stops_before_state_mutation() {
        let root = std::env::temp_dir().join(format!(
            "spar-state-preflight-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&root).unwrap();
        let _fixture = ReviewFixture { root: root.clone() };
        let mut repo = repo_for_titles();
        repo.root = root;
        repo.state_store = StateStore::Both;
        let state = PersistedState {
            version: 1,
            checkpoint: 4,
            round: 2,
            next_actor: "a".into(),
            status: Status::Pending,
            pr_head: "abc123".into(),
            ledger: Ledger::new(),
            filed: Vec::new(),
            open_findings: Vec::new(),
            disputes: Vec::new(),
            noted: Vec::new(),
        };

        let error = repo
            .write_state_after_remote_read(
                7,
                &state,
                Err(crate::error::SparError::new("state comments unavailable")),
            )
            .unwrap_err();

        assert!(error.to_string().contains("state comments unavailable"));
        assert!(!repo.state_path(7).exists());
        assert_eq!(0, repo.remembered_checkpoint(7));
        assert_eq!(
            WriteSummary {
                attempted: 1,
                failed: 1,
            },
            repo.write_summary()
        );
    }

    #[test]
    fn only_known_build_and_cache_directories_are_generated_artifacts() {
        assert!(is_generated_artifact(Path::new("target/debug/artifact")));
        assert!(is_generated_artifact(Path::new("dist/cli/index.js")));
        assert!(is_generated_artifact(Path::new(
            "package/node_modules/dependency/file.js"
        )));
        assert!(!is_generated_artifact(Path::new(
            "distribution/required-package.js"
        )));
        assert!(!is_generated_artifact(Path::new(
            "generated/required-fixture.txt"
        )));
        assert!(!is_generated_artifact(Path::new("local.env")));
    }

    #[test]
    fn only_finder_state_files_are_desktop_metadata() {
        assert!(is_desktop_metadata(Path::new(".DS_Store")));
        assert!(is_desktop_metadata(Path::new("src/tests/.DS_Store")));
        assert!(!is_desktop_metadata(Path::new(".DS_Store.bak")));
        assert!(!is_desktop_metadata(Path::new(".DS_Store/notes.md")));
    }

    struct ReviewFixture {
        root: PathBuf,
    }

    impl Drop for ReviewFixture {
        fn drop(&mut self) {
            let _ = std::fs::remove_dir_all(&self.root);
        }
    }

    fn test_git(cwd: &Path, args: &[&str]) -> String {
        let output = Command::new("git")
            .args(args)
            .current_dir(cwd)
            .output()
            .unwrap_or_else(|e| panic!("git {args:?}: {e}"));
        assert!(
            output.status.success(),
            "git {args:?} failed: {}",
            String::from_utf8_lossy(&output.stderr)
        );
        String::from_utf8_lossy(&output.stdout).into_owned()
    }

    fn review_fixture(
        tag: &str,
        number: i64,
    ) -> (ReviewFixture, Repo, PathBuf, WorktreeCheckpoint) {
        use std::sync::atomic::{AtomicU32, Ordering};
        static NEXT: AtomicU32 = AtomicU32::new(0);
        let id = NEXT.fetch_add(1, Ordering::Relaxed);
        let root =
            std::env::temp_dir().join(format!("spar-repo-test-{tag}-{}-{id}", std::process::id()));
        let origin = root.join("origin.git");
        let work = root.join("work");
        std::fs::create_dir_all(&origin).unwrap();
        std::fs::create_dir_all(&work).unwrap();
        test_git(&origin, &["init", "--bare", "-b", "main"]);
        test_git(&work, &["init", "-b", "main"]);
        test_git(&work, &["config", "user.email", "spar@example.invalid"]);
        test_git(&work, &["config", "user.name", "spar test"]);
        test_git(&work, &["config", "commit.gpgsign", "false"]);
        test_git(&work, &["config", "filter.drop.clean", "sed '/^secret:/d'"]);
        test_git(&work, &["config", "filter.drop.smudge", "cat"]);
        std::fs::write(work.join("README.md"), "seed\n").unwrap();
        std::fs::write(work.join("data.txt"), "old\n").unwrap();
        std::fs::write(work.join(".gitignore"), "generated/\n").unwrap();
        std::fs::write(work.join(".gitattributes"), "* text\n").unwrap();
        test_git(&work, &["add", "."]);
        test_git(&work, &["commit", "-m", "seed"]);
        test_git(
            &work,
            &["remote", "add", "origin", origin.to_str().unwrap()],
        );
        test_git(&work, &["push", "-u", "origin", "main"]);
        test_git(
            &work,
            &["push", "origin", &format!("HEAD:refs/pull/{number}/head")],
        );
        let cfg = crate::config::parse(
            "[agents.a]\ncommand = [\"true\"]\n[agents.b]\ncommand = [\"true\"]\n",
        )
        .unwrap();
        let repo = Repo::open(&work, &cfg).unwrap();
        let path = repo.worktree_for_pr_head(number).unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        (ReviewFixture { root }, repo, path, checkpoint)
    }

    #[test]
    fn an_unchanged_review_worktree_is_released_after_a_checked_read() {
        let (_fixture, repo, path, checkpoint) = review_fixture("checked-release", 901);

        repo.release_review_worktree_checked(901, &checkpoint)
            .unwrap();

        assert!(!path.exists());
    }

    #[test]
    fn a_branch_reflog_only_commit_prevents_ordinary_deletion() {
        let (_fixture, repo, _review, _checkpoint) = review_fixture("branch-reflog", 920);
        let (path, branch) = repo.worktree_for_split(45, 1, "main").unwrap();
        std::fs::write(path.join("recovery.txt"), "keep me\n").unwrap();
        test_git(&path, &["add", "recovery.txt"]);
        test_git(&path, &["commit", "-m", "recovery commit"]);
        let recovery = test_git(&path, &["rev-parse", "HEAD"]);
        test_git(&path, &["reset", "--hard", "main"]);

        assert!(!repo.branch_deletion_is_safe(&branch).unwrap());
        test_git(
            &path,
            &["cat-file", "-e", &format!("{}^{{commit}}", recovery.trim())],
        );
    }

    #[test]
    fn a_review_ref_reflog_only_commit_prevents_deletion() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("review-ref-reflog", 921);
        let local_ref = review_ref(921);
        let original = test_git(&path, &["rev-parse", &local_ref]);
        let tree = test_git(&path, &["rev-parse", "HEAD^{tree}"]);
        let recovery = test_git(
            &path,
            &[
                "commit-tree",
                tree.trim(),
                "-p",
                original.trim(),
                "-m",
                "review ref recovery",
            ],
        );
        test_git(
            &path,
            &["update-ref", "--create-reflog", &local_ref, recovery.trim()],
        );
        test_git(
            &path,
            &["update-ref", &local_ref, original.trim(), recovery.trim()],
        );

        assert!(!repo.review_ref_deletion_is_safe(921).unwrap());
        assert_eq!(original, test_git(&path, &["rev-parse", &local_ref]));
        test_git(
            &path,
            &["cat-file", "-e", &format!("{}^{{commit}}", recovery.trim())],
        );
    }

    #[test]
    fn an_unpublished_commit_message_draft_is_recoverable() {
        let (_fixture, _repo, path, _checkpoint) = review_fixture("commit-draft", 922);
        let raw = PathBuf::from(test_git(&path, &["rev-parse", "--git-dir"]).trim());
        let git_dir = if raw.is_absolute() {
            raw
        } else {
            path.join(raw)
        };
        std::fs::write(git_dir.join("COMMIT_EDITMSG"), "unique recovery draft\n").unwrap();

        assert!(repository_has_recoverable_work(&path, true).unwrap());
        assert_eq!(
            "unique recovery draft\n",
            std::fs::read_to_string(git_dir.join("COMMIT_EDITMSG")).unwrap()
        );
    }

    #[test]
    fn a_changed_review_worktree_is_retained_after_a_checked_read() {
        let (_fixture, repo, path, checkpoint) = review_fixture("checked-dirty", 902);
        std::fs::write(path.join("README.md"), "recover me\n").unwrap();

        let error = repo
            .release_review_worktree_checked(902, &checkpoint)
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("kept for recovery"), "{error}");
        assert_eq!(
            "recover me\n",
            std::fs::read_to_string(path.join("README.md")).unwrap()
        );
        repo.release_review_worktree(902);
    }

    #[test]
    fn a_review_commit_is_retained_after_a_checked_read() {
        let (_fixture, repo, path, checkpoint) = review_fixture("checked-commit", 903);
        std::fs::write(path.join("review-note.txt"), "recover me\n").unwrap();
        test_git(&path, &["add", "review-note.txt"]);
        test_git(&path, &["commit", "-m", "local review recovery"]);
        let head = test_git(&path, &["rev-parse", "HEAD"]);

        let error = repo
            .release_review_worktree_checked(903, &checkpoint)
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert_eq!(head, test_git(&path, &["rev-parse", "HEAD"]));
        assert_eq!(
            "recover me\n",
            std::fs::read_to_string(path.join("review-note.txt")).unwrap()
        );
        repo.release_review_worktree(903);
    }

    /// The read is no longer what refuses: a file the call created and Git was
    /// told to ignore is its own output. Removal still refuses, so the file is
    /// there to look at, which is the part that mattered.
    #[test]
    fn an_ignored_review_file_is_retained_after_a_checked_read() {
        let (_fixture, repo, path, checkpoint) = review_fixture("checked-ignored", 904);
        std::fs::create_dir_all(path.join("generated")).unwrap();
        std::fs::write(path.join("generated/recovery.txt"), "recover me\n").unwrap();

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .expect("its own output is not a change");
        let error = repo
            .release_review_worktree_checked(904, &checkpoint)
            .unwrap_err();

        assert!(error.to_string().contains("recoverable"), "{error}");
        assert_eq!(
            "recover me\n",
            std::fs::read_to_string(path.join("generated/recovery.txt")).unwrap()
        );
        repo.release_review_worktree(904);
    }

    #[test]
    /// The checkpoint no longer refuses this: a path the project ignores is out
    /// of scope for a call that only read. What keeps the file is the gate that
    /// actually deletes the checkout, which refuses any ignored file outside a
    /// known build directory. That is the check with the stake in it, and it is
    /// the one that has to hold.
    fn a_preexisting_ignored_review_file_change_is_retained() {
        let (_fixture, repo, path, _initial) = review_fixture("changed-existing-ignored", 905);
        std::fs::create_dir_all(path.join("generated")).unwrap();
        let ignored = path.join("generated/recovery.txt");
        std::fs::write(&ignored, "before\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::write(&ignored, "after!\n").unwrap();

        let error = repo
            .release_review_worktree_checked(905, &checkpoint)
            .unwrap_err();

        assert!(error.to_string().contains("recoverable"), "{error}");
        assert!(path.exists());
        assert_eq!("after!\n", std::fs::read_to_string(&ignored).unwrap());
        repo.release_review_worktree(905);
    }

    #[test]
    fn a_preexisting_ignored_review_file_prevents_checked_removal() {
        let (_fixture, repo, path, _initial) = review_fixture("existing-ignored", 906);
        std::fs::create_dir_all(path.join("generated")).unwrap();
        let ignored = path.join("generated/recovery.txt");
        std::fs::write(&ignored, "keep me\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();

        let error = repo
            .release_review_worktree_checked(906, &checkpoint)
            .unwrap_err();

        assert!(error.to_string().contains("recoverable"), "{error}");
        assert_eq!("keep me\n", std::fs::read_to_string(&ignored).unwrap());
    }

    #[test]
    fn overwriting_a_preexisting_untracked_file_is_detected() {
        let (_fixture, repo, path, _initial) = review_fixture("changed-untracked", 907);
        let untracked = path.join("notes.txt");
        std::fs::write(&untracked, "before\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::write(&untracked, "after!\n").unwrap();

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert_eq!("after!\n", std::fs::read_to_string(&untracked).unwrap());
    }

    #[test]
    fn an_assume_unchanged_edit_is_detected() {
        let (_fixture, repo, path, checkpoint) = review_fixture("assume-unchanged", 908);
        test_git(&path, &["update-index", "--assume-unchanged", "README.md"]);
        std::fs::write(path.join("README.md"), "hidden\n").unwrap();

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert_eq!(
            "hidden\n",
            std::fs::read_to_string(path.join("README.md")).unwrap()
        );
    }

    #[test]
    fn a_normalized_text_edit_is_detected_even_when_status_is_clean() {
        let (_fixture, repo, path, checkpoint) = review_fixture("normalized-text", 909);
        std::fs::write(path.join("README.md"), b"seed\r\n").unwrap();
        test_git(&path, &["add", "README.md"]);
        assert!(test_git(&path, &["status", "--porcelain"]).is_empty());

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert_eq!(
            b"seed\r\n",
            std::fs::read(path.join("README.md")).unwrap().as_slice()
        );
    }

    #[cfg(unix)]
    #[test]
    fn a_mode_edit_is_detected_when_filemode_is_disabled() {
        use std::os::unix::fs::PermissionsExt;

        let (_fixture, repo, path, checkpoint) = review_fixture("hidden-mode", 910);
        test_git(&path, &["config", "core.filemode", "false"]);
        let readme = path.join("README.md");
        let mut permissions = std::fs::metadata(&readme).unwrap().permissions();
        permissions.set_mode(0o755);
        std::fs::set_permissions(&readme, permissions).unwrap();
        assert!(test_git(&path, &["status", "--porcelain"]).is_empty());

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert_eq!(
            0o755,
            std::fs::metadata(&readme).unwrap().permissions().mode() & 0o777
        );
    }

    #[test]
    fn a_lossy_filter_cannot_hide_raw_bytes_from_a_managed_commit() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("lossy-filter", 911);
        std::fs::write(path.join(".gitattributes"), "* text\n*.txt filter=drop\n").unwrap();
        test_git(&path, &["add", ".gitattributes"]);
        test_git(&path, &["commit", "-m", "select data filter"]);
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join("data.txt"), "secret: recover me\nnew\n").unwrap();

        assert!(repo
            .commit_pending_changes(&path, &baseline, "change data", "change data")
            .unwrap());
        let error = repo
            .refuse_unrepresented_tracked_changes(&path, &baseline)
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert_eq!(
            "secret: recover me\nnew\n",
            std::fs::read_to_string(path.join("data.txt")).unwrap()
        );
        assert_eq!("new\n", test_git(&path, &["show", "HEAD:data.txt"]));
    }

    #[test]
    fn a_baseline_ordinary_untracked_file_is_not_staged_by_a_managed_commit() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("baseline-untracked", 927);
        std::fs::create_dir_all(path.join("target")).unwrap();
        let untracked = path.join("target/user.yaml");
        std::fs::write(&untracked, "user data\n").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join("README.md"), "tracked change\n").unwrap();

        assert!(repo
            .commit_pending_changes(&path, &baseline, "change readme", "change readme")
            .unwrap());

        assert_eq!("user data\n", std::fs::read_to_string(&untracked).unwrap());
        assert_eq!(
            "?? target/user.yaml\n",
            test_git(&path, &["status", "--short", "--untracked-files=all"])
        );
        assert!(test_git(
            &path,
            &[
                "ls-tree",
                "-r",
                "--name-only",
                "HEAD",
                "--",
                "target/user.yaml"
            ]
        )
        .is_empty());
    }

    #[test]
    fn changing_a_baseline_ordinary_untracked_file_stops_a_managed_commit() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("changed-untracked", 929);
        std::fs::create_dir_all(path.join("target")).unwrap();
        let untracked = path.join("target/user.yaml");
        std::fs::write(&untracked, "before\n").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        let before = test_git(&path, &["rev-parse", "HEAD"]);
        std::fs::write(&untracked, "after\n").unwrap();
        std::fs::write(path.join("README.md"), "tracked change\n").unwrap();

        let error = repo
            .commit_pending_changes(&path, &baseline, "change readme", "change readme")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("target/user.yaml"), "{error}");
        assert_eq!(before, test_git(&path, &["rev-parse", "HEAD"]));
        assert!(test_git(&path, &["diff", "--cached", "--name-only"]).is_empty());
        assert_eq!("after\n", std::fs::read_to_string(&untracked).unwrap());
    }

    #[test]
    fn a_new_ordinary_untracked_file_is_staged_by_a_managed_commit() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("new-untracked", 928);
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::create_dir_all(path.join("target")).unwrap();
        std::fs::write(path.join("target/new.txt"), "new file\n").unwrap();

        assert!(repo
            .commit_pending_changes(&path, &baseline, "add file", "add file")
            .unwrap());

        assert_eq!(
            "new file\n",
            test_git(&path, &["show", "HEAD:target/new.txt"])
        );
        assert!(test_git(&path, &["status", "--porcelain"]).is_empty());
    }

    #[test]
    fn a_managed_commit_accepts_a_custom_output_rebuild() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("custom-output", 912);
        exclude_paths(&repo, &["manager/public/"]);
        let output = path.join("manager/public/assets");
        std::fs::create_dir_all(&output).unwrap();
        std::fs::write(output.join("old.js"), "old bundle\n").unwrap();
        std::fs::write(output.join("index.css"), "old styles\n").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join("README.md"), "tracked change\n").unwrap();
        std::fs::write(path.join("new-source.txt"), "new source\n").unwrap();
        std::fs::remove_file(output.join("old.js")).unwrap();
        std::fs::write(output.join("index.css"), "new styles\n").unwrap();
        std::fs::write(output.join("index-DUym-Rfj.js"), "new bundle\n").unwrap();

        assert!(repo
            .commit_pending_changes(&path, &baseline, "change readme", "change readme")
            .unwrap());
        repo.refuse_new_ignored_files(&path, &baseline).unwrap();
        repo.refuse_changed_existing_untracked(&path, &baseline)
            .unwrap();
        repo.refuse_unrepresented_tracked_changes(&path, &baseline)
            .unwrap();

        assert_eq!(
            "tracked change\n",
            test_git(&path, &["show", "HEAD:README.md"])
        );
        assert_eq!(
            "new source\n",
            test_git(&path, &["show", "HEAD:new-source.txt"])
        );
        assert!(test_git(
            &path,
            &[
                "ls-tree",
                "-r",
                "--name-only",
                "HEAD",
                "--",
                "manager/public"
            ]
        )
        .is_empty());
        assert!(test_git(&path, &["status", "--porcelain"]).is_empty());
        assert!(!output.join("old.js").exists());
        assert_eq!(
            "new styles\n",
            std::fs::read_to_string(output.join("index.css")).unwrap()
        );
        assert!(repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(912);
        assert!(output.join("index-DUym-Rfj.js").exists());
    }

    #[test]
    fn newly_ignoring_existing_untracked_work_does_not_allow_its_modification() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("newly-ignored", 926);
        std::fs::write(path.join("notes.txt"), "original notes\n").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join(".gitignore"), "generated/\nnotes.txt\n").unwrap();
        std::fs::write(path.join("notes.txt"), "overwritten notes\n").unwrap();

        let error = repo
            .commit_pending_changes(&path, &baseline, "change", "change")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("notes.txt"), "{error}");
    }

    #[test]
    fn a_new_ignored_nested_repository_allows_a_commit_but_is_preserved() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("ignored-nested-edit", 927);
        let baseline = repo.worktree_baseline(&path).unwrap();
        let nested = path.join("generated/repro");
        std::fs::create_dir_all(&nested).unwrap();
        test_git(&nested, &["init"]);
        std::fs::write(path.join("README.md"), "tracked change\n").unwrap();

        assert!(repo
            .commit_pending_changes(&path, &baseline, "change", "change")
            .unwrap());
        assert!(!repo.has_uncommitted_changes(&path).unwrap());
        assert!(repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(927);
        assert!(nested.join(".git").exists());
    }

    #[test]
    fn an_lf_override_of_an_expected_crlf_checkout_is_recoverable() {
        let (_fixture, _repo, path, _checkpoint) = review_fixture("lf-override", 913);
        test_git(&path, &["config", "core.autocrlf", "true"]);
        std::fs::write(path.join("README.md"), "seed\n").unwrap();
        assert_eq!(
            test_git(&path, &["hash-object", "README.md"]).trim(),
            test_git(&path, &["rev-parse", "HEAD:README.md"]).trim()
        );

        assert!(repository_has_recoverable_work(&path, true).unwrap());
        assert_eq!(
            "seed\n",
            std::fs::read_to_string(path.join("README.md")).unwrap()
        );
    }

    #[test]
    fn autocrlf_input_overrides_a_crlf_core_eol() {
        let (_fixture, _repo, path, _checkpoint) = review_fixture("autocrlf-input", 923);
        test_git(&path, &["config", "core.autocrlf", "input"]);
        test_git(&path, &["config", "core.eol", "crlf"]);
        std::fs::write(path.join("README.md"), b"seed\r\n").unwrap();
        assert_eq!(
            test_git(&path, &["hash-object", "README.md"]).trim(),
            test_git(&path, &["rev-parse", "HEAD:README.md"]).trim()
        );

        assert!(repository_has_recoverable_work(&path, true).unwrap());
        assert_eq!(
            b"seed\r\n",
            std::fs::read(path.join("README.md")).unwrap().as_slice()
        );
    }

    #[cfg(unix)]
    #[test]
    fn a_non_executable_permission_change_is_recoverable() {
        use std::os::unix::fs::PermissionsExt;

        let (_fixture, repo, path, checkpoint) = review_fixture("permission-change", 924);
        let readme = path.join("README.md");
        let mut permissions = std::fs::metadata(&readme).unwrap().permissions();
        permissions.set_mode(0o600);
        std::fs::set_permissions(&readme, permissions).unwrap();
        assert!(test_git(&path, &["status", "--porcelain"]).is_empty());

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(repository_has_recoverable_work(&path, true).unwrap());
        assert_eq!(
            0o600,
            std::fs::metadata(&readme).unwrap().permissions().mode() & 0o777
        );
    }

    #[cfg(unix)]
    #[test]
    fn a_managed_commit_skips_signing_and_hooks() {
        use std::os::unix::fs::PermissionsExt;

        let (fixture, repo, path, _checkpoint) = review_fixture("managed-commit", 925);
        let common = common_git_dir(&path).unwrap();
        let hook = common.join("hooks/pre-commit");
        let marker = fixture.root.join("hook-ran");
        std::fs::create_dir_all(hook.parent().unwrap()).unwrap();
        std::fs::write(
            &hook,
            format!(
                "#!/bin/sh\nprintf ran > {}\nexit 1\n",
                sh_quote(marker.to_str().unwrap())
            ),
        )
        .unwrap();
        let mut permissions = std::fs::metadata(&hook).unwrap().permissions();
        permissions.set_mode(0o755);
        std::fs::set_permissions(&hook, permissions).unwrap();
        test_git(&path, &["config", "commit.gpgsign", "true"]);
        test_git(&path, &["config", "gpg.program", "/usr/bin/false"]);
        std::fs::write(path.join("managed.txt"), "managed\n").unwrap();
        test_git(&path, &["add", "managed.txt"]);

        repo.commit_staged_changes(&path, "record managed change")
            .unwrap();

        assert!(!marker.exists());
        assert_eq!("managed\n", test_git(&path, &["show", "HEAD:managed.txt"]));
    }

    #[test]
    fn an_auto_text_checkout_is_retained_when_representation_is_ambiguous() {
        let (_fixture, _repo, path, _checkpoint) = review_fixture("auto-text", 914);
        std::fs::write(
            path.join(".gitattributes"),
            ".gitattributes -text\n.gitignore -text\ndata.txt -text\nREADME.md text=auto\n",
        )
        .unwrap();
        test_git(&path, &["add", ".gitattributes"]);
        test_git(&path, &["commit", "-m", "select automatic text"]);
        test_git(&path, &["config", "core.autocrlf", "true"]);

        assert!(repository_has_recoverable_work(&path, true).unwrap());
    }

    #[test]
    fn an_ident_checkout_is_retained_even_when_raw_bytes_match_the_index() {
        let (_fixture, _repo, path, _checkpoint) = review_fixture("ident", 915);
        std::fs::write(
            path.join(".gitattributes"),
            ".gitattributes -text\n.gitignore -text\ndata.txt -text\nREADME.md -text ident\n",
        )
        .unwrap();
        test_git(&path, &["add", ".gitattributes"]);
        test_git(&path, &["commit", "-m", "select ident expansion"]);
        std::fs::write(path.join("README.md"), "seed\n").unwrap();

        assert!(repository_has_recoverable_work(&path, true).unwrap());
    }

    /// Add ignore rules the way SPAR does, without a tracked change the
    /// worktree would then be kept for.
    /// The failure this whole rule was rewritten for: a reviewer ran the
    /// project's binding generator to check a finding, and the lockfile it left
    /// beside its own manifest matched no directory name spar knew.
    #[test]
    fn a_lockfile_a_generator_left_outside_build_output_is_the_calls_own_output() {
        let (_fixture, repo, path, _initial) = review_fixture("generator-lockfile", 940);
        exclude_paths(&repo, &["target/", "bindings/uniffi-bindgen/Cargo.lock"]);
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::create_dir_all(path.join("bindings/uniffi-bindgen")).unwrap();
        std::fs::write(
            path.join("bindings/uniffi-bindgen/Cargo.lock"),
            "# generated\n",
        )
        .unwrap();

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .expect("a path the project ignores is the call's own output");
    }

    #[test]
    fn an_attribute_file_under_build_output_is_not_a_filter_change() {
        let (_fixture, repo, path, _initial) = review_fixture("ignored-attributes", 941);
        exclude_paths(&repo, &["target/"]);
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::create_dir_all(path.join("target/package")).unwrap();
        std::fs::write(path.join("target/package/.gitattributes"), "* -text\n").unwrap();

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .expect("an ignored attribute file governs only ignored paths");
        assert!(
            !repo.has_uncommitted_changes(&path).unwrap(),
            "ignored dependency attributes must not stop the next review"
        );
    }

    #[test]
    fn ordinary_untracked_attributes_still_count_as_uncommitted_work() {
        let (_fixture, repo, path, _initial) = review_fixture("ordinary-attributes", 942);
        std::fs::create_dir_all(path.join("source")).unwrap();
        std::fs::write(path.join("source/.gitattributes"), "* -text\n").unwrap();

        assert!(repo.has_uncommitted_changes(&path).unwrap());
    }

    #[test]
    fn all_standard_ignore_sources_allow_artifact_changes_and_preserve_data() {
        for source in ["repository", "nested", "local", "global"] {
            let (_fixture, repo, path, _initial) = review_fixture(source, 945);
            std::fs::create_dir_all(path.join("manager")).unwrap();
            match source {
                "repository" => {
                    std::fs::write(path.join(".gitignore"), "generated/\nmanager/scratch/\n")
                        .unwrap();
                    test_git(&path, &["add", ".gitignore"]);
                    test_git(&path, &["commit", "-m", "ignore artifacts"]);
                }
                "nested" => {
                    std::fs::write(path.join("manager/.gitignore"), "scratch/\n").unwrap();
                    test_git(&path, &["add", "manager/.gitignore"]);
                    test_git(&path, &["commit", "-m", "ignore artifacts"]);
                }
                "local" => exclude_paths(&repo, &["manager/scratch/"]),
                "global" => {
                    let excludes = repo.root().parent().unwrap().join("global-ignore");
                    std::fs::write(&excludes, "manager/scratch/\n").unwrap();
                    test_git(
                        &path,
                        &["config", "core.excludesFile", excludes.to_str().unwrap()],
                    );
                }
                _ => unreachable!(),
            }
            let output = path.join("manager/scratch");
            std::fs::create_dir_all(&output).unwrap();
            std::fs::write(output.join(".env.local"), "LOCAL=value\n").unwrap();
            std::fs::write(output.join(".DS_Store"), "old metadata").unwrap();
            let checkpoint = repo.worktree_checkpoint(&path).unwrap();
            std::fs::write(output.join(".env.local"), "LOCAL=updated\n").unwrap();
            std::fs::remove_file(output.join(".DS_Store")).unwrap();
            for file in [
                ".gitattributes",
                "Cargo.lock",
                "font.woff2",
                "bundle.js",
                "cache.db",
            ] {
                std::fs::write(output.join(file), "generated\n").unwrap();
            }
            #[cfg(unix)]
            std::os::unix::fs::symlink("bundle.js", output.join("bundle-link")).unwrap();
            let nested = output.join("dependency");
            std::fs::create_dir_all(&nested).unwrap();
            test_git(&nested, &["init"]);
            repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
                .unwrap_or_else(|error| panic!("{source}: {error}"));
            assert!(!repo.has_uncommitted_changes(&path).unwrap(), "{source}");

            let baseline = repo.worktree_baseline(&path).unwrap();
            std::fs::write(path.join("README.md"), "source fix\n").unwrap();
            std::fs::write(output.join("bundle.js"), "rebuilt\n").unwrap();
            std::fs::remove_file(output.join("Cargo.lock")).unwrap();
            std::fs::write(output.join("new-lock.json"), "{}\n").unwrap();
            std::fs::write(nested.join("uncommitted.txt"), "dependency output\n").unwrap();
            assert!(repo
                .commit_pending_changes(&path, &baseline, "fix source", "fix source")
                .unwrap_or_else(|error| panic!("{source}: {error}")));
            assert!(!repo.has_uncommitted_changes(&path).unwrap(), "{source}");
            assert!(test_git(
                &path,
                &[
                    "ls-tree",
                    "-r",
                    "--name-only",
                    "HEAD",
                    "--",
                    "manager/scratch"
                ]
            )
            .is_empty());
            assert!(
                repository_has_recoverable_work(&path, true).unwrap(),
                "{source}"
            );
            repo.release_review_worktree(945);
            assert_eq!(
                "LOCAL=updated\n",
                std::fs::read_to_string(output.join(".env.local")).unwrap()
            );
            assert!(nested.join(".git").exists(), "{source}");
        }
    }

    /// Two reviewers share one checkout. The marker written when the first
    /// one's answer was refused used to be a brand new untracked file in the
    /// snapshot the second one was compared against.
    #[test]
    fn a_recovery_marker_is_not_a_change_to_the_worktree() {
        let (_fixture, repo, path, _initial) = review_fixture("marker-snapshot", 942);
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        let _ = uncertain_worktree_change(&path, "an earlier call was refused");

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .expect("spar's own marker is not something a call did");
    }

    #[test]
    fn a_path_that_vanishes_between_listing_and_stat_does_not_fail_the_probe() {
        let (_fixture, _repo, path, _initial) = review_fixture("vanishing-path", 943);

        let gone = ignored_file_fingerprint(&path.join("deleted-mid-build"))
            .expect("a path a build removed is not an unreadable worktree");

        assert_eq!(vanished_untracked_file(), gone);
    }

    /// A path that goes is still a path that was there. Dropping it from the
    /// snapshot would let it pass for one the call never touched.
    #[test]
    fn a_vanished_path_is_not_recorded_as_absent() {
        let (_fixture, repo, path, _initial) = review_fixture("vanished-not-absent", 944);
        std::fs::write(path.join("notes.txt"), "before\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::remove_file(path.join("notes.txt")).unwrap();

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
    }

    fn exclude_paths(repo: &Repo, lines: &[&str]) {
        use std::io::Write;
        let path = repo.root().join(".git").join("info").join("exclude");
        let mut file = std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&path)
            .unwrap();
        for line in lines {
            writeln!(file, "{line}").unwrap();
        }
    }

    #[test]
    fn a_replaced_generated_session_does_not_stop_a_managed_commit() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("rebuilt-commit", 942);
        exclude_paths(&repo, &["dist/"]);
        std::fs::create_dir_all(path.join("dist/session-old")).unwrap();
        std::fs::write(path.join("dist/session-old/dep-graph.bin"), "old\n").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join("README.md"), "tracked change\n").unwrap();
        std::fs::remove_dir_all(path.join("dist/session-old")).unwrap();
        std::fs::create_dir_all(path.join("dist/session-new")).unwrap();
        std::fs::write(path.join("dist/session-new/dep-graph.bin"), "new\n").unwrap();

        assert!(repo
            .commit_pending_changes(&path, &baseline, "change readme", "change readme")
            .unwrap());
        assert_eq!(
            "tracked change\n",
            std::fs::read_to_string(path.join("README.md")).unwrap()
        );
    }

    #[test]
    fn a_rebuild_that_replaces_a_generated_session_does_not_stop_a_call() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("rebuilt-session", 941);
        exclude_paths(&repo, &["dist/"]);
        std::fs::create_dir_all(path.join("dist/session-old")).unwrap();
        std::fs::write(path.join("dist/session-old/dep-graph.bin"), "old\n").unwrap();
        std::fs::write(path.join("dist/session-old.lock"), "").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::remove_dir_all(path.join("dist/session-old")).unwrap();
        std::fs::remove_file(path.join("dist/session-old.lock")).unwrap();
        std::fs::create_dir_all(path.join("dist/session-new")).unwrap();
        std::fs::write(path.join("dist/session-new/dep-graph.bin"), "new\n").unwrap();

        repo.refuse_new_ignored_files(&path, &baseline).unwrap();
        repo.refuse_changed_existing_untracked(&path, &baseline)
            .unwrap();
    }

    #[test]
    fn rebuilt_output_does_not_stop_a_call_that_committed_nothing() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("rebuilt-output", 939);
        exclude_paths(&repo, &["dist/"]);
        std::fs::create_dir_all(path.join("dist")).unwrap();
        std::fs::write(path.join("dist/index.js"), "first build\n").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join("dist/index.js"), "second build\n").unwrap();
        std::fs::write(path.join("dist/extra.js"), "more output\n").unwrap();

        repo.refuse_new_ignored_files(&path, &baseline).unwrap();
        repo.refuse_changed_existing_untracked(&path, &baseline)
            .unwrap();
    }

    /// The run this comes from: a reviewer rebuilt a project whose build output
    /// lands in `manager/public/assets/`, which no directory list will ever
    /// name. The guard inside the call kept the review. This check then called
    /// the same thirteen files unrepresentable and ended the round, five
    /// minutes of review thrown away over a path Git had been told to disown.
    /// The run this comes from: `gh pr merge --delete-branch` could not delete
    /// `issue-784` because `.spar-worktrees/issue-784`, left by the run that
    /// opened the pull request, still had it checked out.
    #[test]
    fn the_worktree_holding_a_branch_is_found_by_its_branch_name() {
        let (_fixture, repo, _path, _checkpoint) = review_fixture("holding", 950);
        let held = repo.root().join(WORKTREE_DIR).join("issue-950");
        std::fs::create_dir_all(held.parent().unwrap()).unwrap();
        test_git(
            repo.root(),
            &[
                "worktree",
                "add",
                "-b",
                "issue-950",
                held.to_str().unwrap(),
                "main",
            ],
        );

        let found = repo
            .worktree_holding("issue-950")
            .expect("the branch is checked out somewhere");

        assert!(found.ends_with("issue-950"), "{}", found.display());
        assert_eq!(None, repo.worktree_holding("issue-951"));
    }

    #[test]
    fn a_read_only_call_may_rebuild_ignored_output_outside_the_directory_list() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("read-only-rebuild", 943);
        exclude_paths(&repo, &["manager/public/assets/"]);
        std::fs::create_dir_all(path.join("manager/public/assets")).unwrap();
        let bundle = path.join("manager/public/assets/index-DPQ2vCfq.css");
        std::fs::write(&bundle, "first build\n").unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(&bundle, "second build\n").unwrap();
        std::fs::write(path.join("manager/public/assets/index-ptLOWYCS.js"), "b\n").unwrap();

        repo.refuse_read_only_leavings(&path, &baseline).unwrap();
        repo.refuse_new_ignored_files(&path, &baseline).unwrap();
    }

    #[test]
    fn a_read_only_call_may_not_leave_an_ordinary_untracked_file() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("read-only-scratch", 944);
        exclude_paths(&repo, &["dist/"]);
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join("scratch.md"), "notes\n").unwrap();

        let error = repo
            .refuse_read_only_leavings(&path, &baseline)
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("scratch.md"), "{error}");
    }

    #[test]
    fn a_new_ignored_file_is_accepted_but_still_keeps_the_worktree() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("new-ignored-local", 940);
        exclude_paths(&repo, &["dist/", ".env.local"]);
        std::fs::create_dir_all(path.join("dist")).unwrap();
        let baseline = repo.worktree_baseline(&path).unwrap();
        std::fs::write(path.join("dist/index.js"), "a build\n").unwrap();
        std::fs::write(path.join(".env.local"), "TOKEN=x\n").unwrap();

        repo.refuse_new_ignored_files(&path, &baseline).unwrap();
        assert!(repository_has_recoverable_work(&path, true).unwrap());
    }

    #[test]
    fn a_read_only_inspection_may_rebuild_generated_output() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("inspect-build", 937);
        exclude_paths(&repo, &["dist/"]);
        std::fs::create_dir_all(path.join("dist")).unwrap();
        std::fs::write(path.join("dist/index.js"), "first build\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::write(path.join("dist/index.js"), "second build\n").unwrap();
        std::fs::write(path.join("dist/extra.js"), "more output\n").unwrap();

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap();
    }

    #[test]
    fn a_read_only_inspection_may_change_an_ignored_file_elsewhere() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("inspect-local", 938);
        exclude_paths(&repo, &["dist/", ".env.local"]);
        std::fs::write(path.join(".env.local"), "TOKEN=before\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::write(path.join(".env.local"), "TOKEN=after\n").unwrap();

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap();
    }

    #[test]
    fn a_read_only_inspection_may_delete_an_ignored_file_elsewhere() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("inspect-deleted", 939);
        exclude_paths(&repo, &["dist/", ".env.local"]);
        std::fs::write(path.join(".env.local"), "TOKEN=before\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::remove_file(path.join(".env.local")).unwrap();

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap();
    }

    #[test]
    fn a_read_only_inspection_may_not_change_an_ordinary_untracked_file() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("inspect-ordinary", 940);
        exclude_paths(&repo, &["dist/"]);
        std::fs::write(path.join("notes.md"), "before\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::write(path.join("notes.md"), "after\n").unwrap();

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("notes.md"), "{error}");
    }

    #[test]
    fn an_ignored_file_that_becomes_ordinary_stops_a_read_only_inspection() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("inspect-unignored", 941);
        exclude_paths(&repo, &["dist/", "local.env"]);
        std::fs::write(path.join("local.env"), "TOKEN=before\n").unwrap();
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        // Stop ignoring it, so the same bytes are now an ordinary untracked
        // file. What a path is counts, not only whether it moved.
        std::fs::write(
            repo.root().join(".git").join("info").join("exclude"),
            "dist/\n",
        )
        .unwrap();

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("local.env"), "{error}");
    }

    #[test]
    fn a_read_only_inspection_names_the_tracked_file_that_moved() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("inspect-tracked", 942);
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        std::fs::write(path.join("README.md"), "recover me\n").unwrap();

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("README.md"), "{error}");
    }

    #[test]
    fn build_output_alone_does_not_keep_a_worktree() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("build-output", 933);
        exclude_paths(&repo, &["target/", "dist/"]);
        std::fs::create_dir_all(path.join("target/debug")).unwrap();
        std::fs::write(path.join("target/debug/artifact"), "compiler output\n").unwrap();
        std::fs::create_dir_all(path.join("dist/cli")).unwrap();
        std::fs::write(path.join("dist/cli/index.js"), "typescript output\n").unwrap();

        assert!(!repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(933);

        assert!(!path.exists());
    }

    #[test]
    fn finder_metadata_alone_does_not_keep_a_worktree() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("finder-metadata", 937);
        exclude_paths(&repo, &[".DS_Store"]);
        std::fs::create_dir_all(path.join("src")).unwrap();
        std::fs::write(path.join(".DS_Store"), "finder state\n").unwrap();
        std::fs::write(path.join("src/.DS_Store"), "finder state\n").unwrap();

        assert!(!repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(937);

        assert!(!path.exists());
    }

    #[test]
    fn a_fetch_record_alone_does_not_keep_a_worktree() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("fetch-record", 938);
        let raw = PathBuf::from(test_git(&path, &["rev-parse", "--git-dir"]).trim());
        let git_dir = if raw.is_absolute() {
            raw
        } else {
            path.join(raw)
        };
        let head = test_git(&path, &["rev-parse", "HEAD"]);
        std::fs::write(
            git_dir.join("FETCH_HEAD"),
            format!("{}\t\tbranch 'main' of origin\n", head.trim()),
        )
        .unwrap();

        assert!(!repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(938);

        assert!(!path.exists());
    }

    #[test]
    fn an_ignored_file_outside_build_output_keeps_a_worktree() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("ignored-local", 934);
        exclude_paths(&repo, &["target/", ".env.local"]);
        std::fs::create_dir_all(path.join("target/debug")).unwrap();
        std::fs::write(path.join("target/debug/artifact"), "compiler output\n").unwrap();
        std::fs::write(path.join(".env.local"), "TOKEN=keep me\n").unwrap();

        assert!(repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(934);

        assert_eq!(
            "TOKEN=keep me\n",
            std::fs::read_to_string(path.join(".env.local")).unwrap()
        );
    }

    #[test]
    fn a_repository_nested_in_build_output_keeps_a_worktree() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("nested-in-build", 935);
        exclude_paths(&repo, &["node_modules/"]);
        let nested = path.join("node_modules/local-dep");
        std::fs::create_dir_all(&nested).unwrap();
        test_git(&nested, &["init"]);
        std::fs::write(nested.join("work.txt"), "uncommitted\n").unwrap();

        assert!(repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(935);

        assert!(nested.join(".git").exists());
    }

    #[test]
    fn an_ordinary_untracked_file_keeps_a_worktree() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("ordinary-untracked", 936);
        std::fs::write(path.join("notes.md"), "somebody's notes\n").unwrap();

        assert!(repository_has_recoverable_work(&path, true).unwrap());
        repo.release_review_worktree(936);

        assert_eq!(
            "somebody's notes\n",
            std::fs::read_to_string(path.join("notes.md")).unwrap()
        );
    }

    #[test]
    fn a_legacy_crlf_checkout_is_retained_conservatively() {
        let (_fixture, _repo, path, _checkpoint) = review_fixture("legacy-crlf", 916);
        std::fs::write(
            path.join(".gitattributes"),
            ".gitattributes -text\n.gitignore -text\ndata.txt -text\nREADME.md crlf\n",
        )
        .unwrap();
        test_git(&path, &["add", ".gitattributes"]);
        test_git(&path, &["commit", "-m", "select legacy line endings"]);

        assert!(repository_has_recoverable_work(&path, true).unwrap());
    }

    #[test]
    fn a_nested_git_entry_inside_a_tracked_directory_is_recoverable() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("nested-git", 917);
        let nested = path.join("tracked");
        std::fs::create_dir_all(&nested).unwrap();
        std::fs::write(nested.join("seed.txt"), "seed\n").unwrap();
        test_git(&path, &["add", "tracked/seed.txt"]);
        test_git(&path, &["commit", "-m", "add tracked directory"]);
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        test_git(&nested, &["init"]);

        let error = repo
            .require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("Git entry"), "{error}");
        assert!(nested.join(".git").exists());
    }

    /// A reviewer that clones a reproduction into ignored build output used to
    /// lose the whole review. The state check refused every Git entry it had
    /// not put there, including the one Git reports as a nested checkout and
    /// the untracked snapshot already records by identity.
    #[test]
    fn a_repository_cloned_into_build_output_leaves_the_state_readable() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("cloned-repro", 918);
        exclude_paths(&repo, &["target/"]);
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        let repro = path.join("target/pr918-repro");
        std::fs::create_dir_all(&repro).unwrap();
        test_git(&repro, &["init"]);
        std::fs::write(repro.join("main.rs"), "fn main() {}\n").unwrap();

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap();

        assert!(repository_has_recoverable_work(&path, true).unwrap());
        assert!(repro.join(".git").exists());
    }

    /// What sits under a nested checkout is that repository's business, so the
    /// scan stops at its directory rather than reading a checkout of its own
    /// as an entry the outer worktree has to account for.
    #[test]
    fn a_repository_inside_a_nested_checkout_is_left_alone() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("checkout-in-checkout", 919);
        exclude_paths(&repo, &["target/"]);
        let checkpoint = repo.worktree_checkpoint(&path).unwrap();
        let repro = path.join("target/repro");
        let vendored = repro.join("vendor/dep");
        std::fs::create_dir_all(&vendored).unwrap();
        test_git(&repro, &["init"]);
        test_git(&vendored, &["init"]);

        repo.require_unchanged_worktree(&path, &checkpoint, "review worktree")
            .unwrap();

        assert!(vendored.join(".git").exists());
    }

    #[test]
    fn a_resident_worktree_is_snapshotted_as_one_ignored_entry() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("resident-snapshot", 930);

        let state = ignored_untracked_state(repo.root()).unwrap();

        let relative = path.strip_prefix(repo.root()).unwrap();
        assert!(
            state.files.contains_key(relative),
            "{:?}",
            state.files.keys().collect::<Vec<_>>()
        );
        assert!(state.is_ignored(relative));
    }

    #[test]
    fn work_inside_a_resident_worktree_leaves_the_outer_baseline_alone() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("resident-churn", 931);
        let baseline = repo.worktree_baseline(repo.root()).unwrap();
        std::fs::write(path.join("scratch.txt"), "another run's work\n").unwrap();
        std::fs::write(path.join("README.md"), "another run's edit\n").unwrap();

        repo.refuse_new_ignored_files(repo.root(), &baseline)
            .unwrap();
        repo.refuse_changed_existing_untracked(repo.root(), &baseline)
            .unwrap();
    }

    #[test]
    fn deleting_a_resident_worktree_during_a_call_is_refused() {
        let (_fixture, repo, path, _checkpoint) = review_fixture("resident-deleted", 932);
        let baseline = repo.worktree_baseline(repo.root()).unwrap();
        let checkpoint = repo.worktree_checkpoint(repo.root()).unwrap();
        std::fs::remove_dir_all(&path).unwrap();

        let read_error = repo
            .require_unchanged_worktree(repo.root(), &checkpoint, "main checkout")
            .unwrap_err();
        assert!(
            read_error.to_string().contains("review-932"),
            "{read_error}"
        );
        let error = repo
            .refuse_new_ignored_files(repo.root(), &baseline)
            .unwrap_err();

        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(error.to_string().contains("review-932"), "{error}");
    }

    #[test]
    fn a_nested_repository_record_is_read_as_a_plain_path() {
        let (path, nested) = untracked_record(b"vendor/checkout/", "untracked").unwrap();
        assert_eq!(Path::new("vendor/checkout"), path);
        assert!(nested);

        let (path, nested) = untracked_record(b"vendor/notes.txt", "untracked").unwrap();
        assert_eq!(Path::new("vendor/notes.txt"), path);
        assert!(!nested);

        assert!(untracked_record(b"/", "untracked").is_err());
    }

    #[cfg(unix)]
    #[test]
    fn a_non_utf8_git_path_is_preserved_without_loss() {
        use std::os::unix::ffi::OsStrExt;

        let path = path_from_git_bytes(&[b'f', 0xff]).unwrap();

        assert_eq!(&[b'f', 0xff], path.as_os_str().as_bytes());
    }

    #[test]
    fn guarded_merge_pins_the_reviewed_head() {
        let args = merge_pr_args("36", Some("abc123"), true);
        assert_eq!(
            vec![
                "pr",
                "merge",
                "36",
                "--squash",
                "--delete-branch",
                "--match-head-commit",
                "abc123"
            ],
            args
        );
    }

    #[test]
    fn an_ambiguous_create_is_success_when_the_pull_request_exists() {
        let pr = PrRef {
            number: 7,
            url: "https://example.test/pull/7".into(),
            title: "part one".into(),
        };
        let result = reconcile_pr_creation(
            "split-34-1",
            Err(crate::error::SparError::new("connection lost")),
            Ok(Some(pr)),
        )
        .unwrap();
        assert_eq!(7, result.number);
    }

    #[test]
    fn a_failed_create_keeps_its_original_error_when_no_pr_exists() {
        let error = reconcile_pr_creation(
            "split-34-1",
            Err(crate::error::SparError::new("permission denied")),
            Ok(None),
        )
        .unwrap_err();
        assert!(error.to_string().contains("permission denied"), "{error}");
    }

    #[test]
    fn a_pull_request_against_the_wrong_base_does_not_reconcile_creation() {
        let text = r#"[{"number":7,"url":"https://example.test/pull/7","title":"part one","baseRefName":"main"}]"#;
        assert!(pr_for_base(text, "split-34-2", "split-34-1")
            .unwrap()
            .is_none());
        let found = pr_for_base(text, "split-34-2", "main").unwrap().unwrap();
        assert_eq!(7, found.number);
    }

    #[test]
    fn an_ambiguous_comment_is_success_when_the_exact_body_exists() {
        let result = reconcile_comment_post(
            34,
            "the summary",
            crate::error::SparError::new("connection lost"),
            Ok(vec![serde_json::json!({"body": "the summary"})]),
        );
        assert!(result.is_ok(), "{result:?}");
    }

    #[test]
    fn an_ambiguous_comment_preserves_failure_when_only_other_text_exists() {
        let error = reconcile_comment_post(
            34,
            "the summary",
            crate::error::SparError::new("connection lost"),
            Ok(vec![serde_json::json!({"body": "<!-- spar:split -->"})]),
        )
        .unwrap_err();
        assert_eq!("connection lost", error.to_string());
    }

    #[test]
    fn an_ambiguous_comment_reports_an_unverifiable_lookup() {
        let error = reconcile_comment_post(
            34,
            "the summary",
            crate::error::SparError::new("connection lost"),
            Err(crate::error::SparError::new("comments unavailable")),
        )
        .unwrap_err();
        assert!(
            error.to_string().contains("could not be verified"),
            "{error}"
        );
        assert!(
            error.to_string().contains("comments unavailable"),
            "{error}"
        );
        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(!error.worth_retrying());
    }

    #[test]
    fn an_ambiguous_issue_edit_is_success_when_the_wanted_body_exists() {
        let result = reconcile_issue_edit(
            34,
            "wanted body",
            crate::error::SparError::new("connection lost"),
            Ok("wanted body".to_string()),
        );
        assert!(result.is_ok(), "{result:?}");
    }

    #[test]
    fn an_ambiguous_issue_edit_reports_an_unverifiable_lookup() {
        let error = reconcile_issue_edit(
            34,
            "wanted body",
            crate::error::SparError::new("connection lost"),
            Err(crate::error::SparError::new("issue unavailable")),
        )
        .unwrap_err();
        assert!(
            error.to_string().contains("could not be verified"),
            "{error}"
        );
        assert!(error.to_string().contains("issue unavailable"), "{error}");
        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(!error.worth_retrying());
    }

    #[test]
    fn an_ambiguous_issue_creation_recovers_the_exact_issue() {
        let found = ExistingIssue {
            number: 101,
            url: "https://example.test/issues/101".into(),
            title: "child".into(),
            body: "body".into(),
            open: true,
        };
        let url = reconcile_issue_creation(
            "child",
            Err(crate::error::SparError::new("connection lost")),
            Ok(Some(found)),
        )
        .unwrap();
        assert_eq!("https://example.test/issues/101", url);
    }

    #[test]
    fn a_failed_issue_creation_keeps_its_error_when_no_issue_exists() {
        let error = reconcile_issue_creation(
            "child",
            Err(crate::error::SparError::new("permission denied")),
            Ok(None),
        )
        .unwrap_err();
        assert!(error.to_string().contains("permission denied"), "{error}");
    }

    #[test]
    fn an_unverifiable_issue_creation_is_marked_uncertain() {
        let error = reconcile_issue_creation(
            "child",
            Err(crate::error::SparError::new("connection lost")),
            Err(crate::error::SparError::new("issues unavailable")),
        )
        .unwrap_err();
        assert_eq!(crate::error::ErrorKind::UncertainWrite, error.kind());
        assert!(!error.worth_retrying());
    }

    #[test]
    fn an_ambiguous_split_push_is_success_when_origin_has_local_head() {
        let result = reconcile_failed_split_push(
            "split-34-1",
            crate::error::SparError::new("connection lost"),
            Ok("abc123\n".into()),
            Ok("abc123\trefs/heads/split-34-1\n".into()),
        );
        assert!(result.is_ok(), "{result:?}");
    }

    #[test]
    fn a_split_push_collision_is_definite_and_never_overwrites() {
        let error = reconcile_failed_split_push(
            "split-34-1",
            crate::error::SparError::new("lease rejected"),
            Ok("abc123\n".into()),
            Ok("def456\trefs/heads/split-34-1\n".into()),
        )
        .unwrap_err();
        assert!(!error.retain_worktree());
        assert!(
            error.to_string().contains("Nothing was overwritten"),
            "{error}"
        );
    }

    #[test]
    fn an_unreadable_split_push_result_keeps_the_worktree() {
        let error = reconcile_failed_split_push(
            "split-34-1",
            crate::error::SparError::new("connection lost"),
            Ok("abc123\n".into()),
            Err(crate::error::SparError::new("origin unavailable")),
        )
        .unwrap_err();
        assert!(error.retain_worktree());
        assert!(error.to_string().contains("could not confirm"), "{error}");
    }

    /// Follow-up deduplication compares a title it computed against the title
    /// GitHub stored. If those two transforms can disagree, the check never
    /// matches and every review round files another copy of the same issue.
    #[test]
    fn clean_title_is_idempotent_even_when_the_scrub_lengthens_it() {
        let repo = repo_for_titles();
        for raw in [
            "Retry loop spins \u{2014} Retry-After parses to zero",
            "plain title",
            "  spread   over\nlines  ",
            "\u{1F916} Generated with something",
            &format!("a \u{2014} {}", "very long title ".repeat(20)),
            &"x".repeat(300),
            &format!("{} \u{2014} end", "y".repeat(88)),
            // Exactly the budget, with two spaceless dashes. The scrub turns
            // each "a\u{2014}b" into "a, b", so clip-then-scrub lands one
            // character over budget per dash and a second pass clips again,
            // producing a different string. Scrub-then-clip cannot.
            &{
                let tail = "a\u{2014}b c\u{2014}d";
                let pad = Style::default().max_title_chars - tail.chars().count();
                format!("{}{tail}", "w".repeat(pad))
            },
        ] {
            let once = repo.clean_title(raw).unwrap();
            let twice = repo.clean_title(&once).unwrap();
            assert_eq!(once, twice, "not idempotent for {raw:?}");
            assert!(
                once.chars().count() <= repo.style.max_title_chars,
                "over budget: {once:?}"
            );
            assert!(style::violations(&once, &repo.style).is_empty(), "{once:?}");
        }
    }

    #[test]
    fn a_title_with_an_em_dash_survives_as_readable_text() {
        let repo = repo_for_titles();
        assert_eq!(
            "Retry loop spins, Retry-After parses to zero",
            repo.clean_title("Retry loop spins \u{2014} Retry-After parses to zero")
                .unwrap()
        );
    }

    #[test]
    fn sh_quote_survives_a_quote() {
        assert_eq!(r"'a'\''b'", sh_quote("a'b"));
    }

    #[test]
    fn sh_quote_wraps_a_space() {
        assert_eq!(
            "'/Applications/My App/spar'",
            sh_quote("/Applications/My App/spar")
        );
    }

    #[test]
    fn finished_states_are_recognised_case_insensitively() {
        assert!(is_finished("MERGED"));
        assert!(is_finished("closed"));
        assert!(!is_finished("OPEN"));
        assert!(!is_finished(""));
    }

    fn state() -> PersistedState {
        PersistedState {
            version: 1,
            checkpoint: 0,
            round: 4,
            next_actor: "codex".into(),
            status: Status::Pending,
            pr_head: "abc123".into(),
            ledger: Ledger::new(),
            filed: vec![],
            open_findings: vec![Finding {
                severity: Severity::Blocking,
                title: "Unchecked error".into(),
                detail: "the failure is discarded".into(),
                file: "src/a.rs:12".into(),
                ..Finding::default()
            }],
            disputes: vec![Dispute {
                title: "Retry limit".into(),
                file: "src/net.rs".into(),
                reasoning: "the caller already bounds it".into(),
            }],
            noted: vec![Finding {
                severity: Severity::NonBlocking,
                title: "Timeout is fixed".into(),
                file: "src/config.rs".into(),
                ..Finding::default()
            }],
        }
    }

    #[test]
    fn a_state_comment_round_trips() {
        let body = format!(
            "{STATE_MARKER}\n{}\n-->",
            serde_json::to_string(&state()).unwrap()
        );
        let back = parse_state_comment(&body).unwrap();
        assert_eq!(4, back.round);
        assert_eq!("codex", back.next_actor);
        assert_eq!("abc123", back.pr_head);
        assert_eq!("Unchecked error", back.open_findings[0].title);
        assert_eq!("src/net.rs", back.disputes[0].file);
        assert_eq!("Timeout is fixed", back.noted[0].title);
    }

    #[test]
    fn old_state_without_new_lists_still_parses() {
        let body = format!(
            "{STATE_MARKER}\n{{\"version\":1,\"round\":2,\"next_actor\":\"b\",\
             \"status\":\"pending\",\"ledger\":{{}},\"filed\":[]}}\n-->"
        );
        let back = parse_state_comment(&body).expect("old state");
        assert!(back.open_findings.is_empty());
        assert!(back.disputes.is_empty());
        assert!(back.noted.is_empty());
        assert!(back.pr_head.is_empty());
        assert_eq!(0, back.checkpoint);
    }

    #[test]
    fn matching_remote_state_beats_a_newer_stale_local_checkpoint() {
        let mut local = state();
        local.pr_head = "old".into();
        local.round = 9;
        let mut remote = state();
        remote.pr_head = "current".into();
        remote.round = 4;

        let chosen = choose_state_for_head(vec![local, remote], "current").unwrap();
        assert_eq!("current", chosen.pr_head);
        assert_eq!(4, chosen.round);
    }

    #[test]
    fn checkpoint_order_breaks_same_round_ties() {
        let mut local = state();
        local.pr_head = "current".into();
        local.round = 4;
        local.checkpoint = 8;
        let mut remote = local.clone();
        remote.checkpoint = 7;
        remote.open_findings.clear();

        let chosen = choose_state_for_head(vec![local], "current").unwrap();
        assert_eq!(8, chosen.checkpoint);

        let mut local = state();
        local.pr_head = "current".into();
        local.round = 4;
        local.checkpoint = 8;
        let chosen = choose_state_for_head(vec![remote, local], "current").unwrap();
        assert_eq!(8, chosen.checkpoint);
    }

    #[test]
    fn legacy_same_round_tie_keeps_the_local_checkpoint() {
        let mut local = state();
        local.pr_head = "current".into();
        local.round = 4;
        local.open_findings.push(Finding {
            title: "local checkpoint".into(),
            ..Finding::default()
        });
        let mut remote = state();
        remote.pr_head = "current".into();
        remote.round = 4;

        let chosen = choose_state_for_head(vec![local, remote], "current").unwrap();
        assert_eq!(
            "local checkpoint",
            chosen.open_findings.last().unwrap().title
        );
    }

    /// It must render as nothing, so PRs are not littered with machine state.
    #[test]
    fn the_state_block_is_an_html_comment() {
        let body = format!(
            "{STATE_MARKER}\n{}\n-->",
            serde_json::to_string(&state()).unwrap()
        );
        assert!(body.starts_with("<!--"));
        assert!(body.trim_end().ends_with("-->"));
        assert!(!body[..body.find('{').unwrap()].contains("-->"));
    }

    #[test]
    fn an_unrelated_json_block_is_not_state() {
        assert!(parse_state_comment("here is a snippet\n```json\n{\"round\": 99}\n```").is_none());
    }

    /// Patching and deleting a comment is not something to do on a substring.
    ///
    /// A maintainer who notices the block and asks about it writes a comment
    /// containing `spar:state`, and the loose filter could not tell theirs from
    /// spar's. The next `persist` replaced their words with JSON and
    /// `spar clean --pr-state` later deleted it.
    #[test]
    fn a_persons_comment_about_the_state_block_is_not_the_state_block() {
        let block = format!(
            "{STATE_MARKER}\n{}\n-->",
            serde_json::to_string(&state()).unwrap()
        );
        assert!(is_state_comment(&block, "spar-bot", "spar-bot"));
        assert!(
            is_state_comment(&block, "Spar-Bot", "spar-bot"),
            "a login differs only in case"
        );

        assert!(
            !is_state_comment(
                "why is there a `<!-- spar:state` block on this PR?",
                "maintainer",
                "spar-bot"
            ),
            "a question about the block was treated as the block"
        );
        assert!(
            !is_state_comment(&block, "maintainer", "spar-bot"),
            "somebody else's comment is not spar's to rewrite"
        );
        assert!(
            !is_state_comment(
                &format!("here is what spar writes:\n\n{block}"),
                "spar-bot",
                "spar-bot"
            ),
            "the marker has to open the body, not appear in it"
        );
        assert!(
            !is_state_comment(
                &format!("{STATE_MARKER}\n{{not json\n-->"),
                "spar-bot",
                "spar-bot"
            ),
            "a block that does not parse is not state"
        );
        assert!(
            !is_state_comment(&block, "spar-bot", ""),
            "an unknown viewer proves nothing about who wrote it"
        );
    }

    #[test]
    fn a_malformed_state_comment_is_none_not_a_panic() {
        assert!(parse_state_comment(&format!("{STATE_MARKER}\n{{not json\n-->")).is_none());
    }

    #[test]
    fn atomic_write_leaves_no_temp_file() {
        let dir = std::env::temp_dir().join(format!("spar-atomic-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let path = dir.join("state").join("pr-7.json");
        write_json_atomic(&path, &state()).unwrap();
        let files: Vec<String> = std::fs::read_dir(path.parent().unwrap())
            .unwrap()
            .flatten()
            .filter_map(|e| e.file_name().to_str().map(str::to_string))
            .collect();
        assert_eq!(vec!["pr-7.json".to_string()], files);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn atomic_write_overwrites_rather_than_accumulating() {
        let dir = std::env::temp_dir().join(format!("spar-overwrite-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let path = dir.join("pr-7.json");
        for round in 1..4 {
            let mut s = state();
            s.round = round;
            write_json_atomic(&path, &s).unwrap();
        }
        let back: PersistedState =
            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
        assert_eq!(3, back.round);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn style_from_env_defaults_to_enforcing() {
        std::env::remove_var("SPAR_BAN_EM_DASH");
        std::env::remove_var("SPAR_BAN_AI_ATTRIBUTION");
        let style = style_from_env();
        assert!(style.ban_em_dash && style.ban_ai_attribution);
        assert!(
            !style.terse,
            "the commit filter must not truncate a commit message"
        );
    }
}

#[cfg(test)]
mod comment_page_tests {
    use super::*;

    #[test]
    fn a_single_merged_array_is_read() {
        let pages = parse_comment_pages(r#"[{"id":1,"body":"a"},{"id":2,"body":"b"}]"#);
        assert_eq!(2, pages.len());
        assert_eq!(Some(2), pages[1]["id"].as_i64());
    }

    #[test]
    fn concatenated_pages_from_an_older_gh_are_read_too() {
        let pages = parse_comment_pages(r#"[{"id":1}][{"id":2}]"#);
        assert_eq!(2, pages.len());
    }

    /// A comment body containing a bracket pair used to split the payload into
    /// two invalid halves, so no state comment was found and a resume silently
    /// started from round one.
    #[test]
    fn a_comment_body_containing_a_bracket_pair_is_not_mistaken_for_a_page_break() {
        let text = r#"[{"id":1,"body":"see [the docs][ref] for why"},{"id":2,"body":"ok"}]"#;
        let pages = parse_comment_pages(text);
        assert_eq!(2, pages.len(), "{pages:?}");
        assert!(pages[0]["body"].as_str().unwrap().contains("[ref]"));
    }

    #[test]
    fn empty_output_is_no_comments_not_a_panic() {
        assert!(parse_comment_pages("").is_empty());
        assert!(parse_comment_pages("   ").is_empty());
        assert!(parse_comment_pages("[]").is_empty());
    }

    #[test]
    fn a_gh_error_message_on_stdout_yields_nothing_rather_than_garbage() {
        assert!(parse_comment_pages("gh: Not Found (HTTP 404)").is_empty());
    }

    #[test]
    fn a_write_postcheck_rejects_truncated_comment_pages() {
        let error = try_parse_comment_pages(r#"[{"body":"the summary"}]["#).unwrap_err();
        assert!(
            error.to_string().contains("unexpected comment pages"),
            "{error}"
        );
    }

    #[test]
    fn a_write_postcheck_rejects_empty_or_non_array_output() {
        assert!(try_parse_comment_pages("").is_err());
        assert!(try_parse_comment_pages(r#"{"body":"the summary"}"#).is_err());
        assert!(try_parse_comment_pages("[]").is_ok());
    }

    #[test]
    fn state_is_found_in_the_last_matching_comment() {
        let payload = |round: u32| {
            format!(
                "{STATE_MARKER}\n{{\"version\":1,\"round\":{round},\"next_actor\":\"a\",\"status\":\"pending\",\"ledger\":{{}},\"filed\":[]}}\n-->"
            )
        };
        let text = serde_json::to_string(&serde_json::json!([
            {"id": 1, "body": payload(1)},
            {"id": 2, "body": "looks good to me"},
            {"id": 3, "body": payload(5)},
        ]))
        .unwrap();
        let pages = parse_comment_pages(&text);
        let last = pages
            .iter()
            .rev()
            .find_map(|c| parse_state_comment(c["body"].as_str().unwrap_or("")))
            .unwrap();
        assert_eq!(5, last.round);
    }
}

#[cfg(test)]
mod linked_pr_tests {
    use super::*;

    /// The exact shape `gh pr list --json closingIssuesReferences` returns.
    /// It carries an id and a whole repository object per linked issue, and a
    /// parser that chokes on those reports "no pull request", which is the one
    /// answer that makes spar implement over the top of somebody's work.
    const REAL_PAYLOAD: &str = r#"[
      {"number":14252,"title":"fix: reject leading-dash branch names",
       "url":"https://github.com/cli/cli/pull/14252",
       "closingIssuesReferences":[{"id":"I_kwDO","number":14238,
         "repository":{"id":"MDEwOlJl","name":"cli","owner":{"id":"MDEy","login":"cli"}},
         "url":"https://github.com/cli/cli/issues/14238"}]},
      {"number":14217,"title":"another change",
       "url":"https://github.com/cli/cli/pull/14217",
       "closingIssuesReferences":[{"id":"I_kwDO","number":9761,
         "repository":{"id":"MDEwOlJl","name":"cli","owner":{"id":"MDEy","login":"cli"}},
         "url":"https://github.com/cli/cli/issues/9761"}]},
      {"number":14200,"title":"unlinked work",
       "url":"https://github.com/cli/cli/pull/14200","closingIssuesReferences":[]}
    ]"#;

    #[test]
    fn a_linked_pr_is_found_whatever_its_branch_is_called() {
        let pr = find_linked_pr(REAL_PAYLOAD, 14238).expect("should find it");
        assert_eq!(14252, pr.number);
        assert_eq!("https://github.com/cli/cli/pull/14252", pr.url);
    }

    #[test]
    fn the_right_pr_is_picked_out_of_several() {
        assert_eq!(14217, find_linked_pr(REAL_PAYLOAD, 9761).unwrap().number);
    }

    #[test]
    fn an_issue_nobody_is_working_on_finds_nothing() {
        assert!(find_linked_pr(REAL_PAYLOAD, 99999).is_none());
    }

    #[test]
    fn an_unlinked_pr_is_never_matched() {
        // 14200 closes nothing, so no issue number should ever return it.
        for issue in [14200, 0, 1] {
            if let Some(pr) = find_linked_pr(REAL_PAYLOAD, issue) {
                assert_ne!(14200, pr.number, "matched a PR that closes nothing");
            }
        }
    }

    #[test]
    fn empty_or_broken_output_is_none_rather_than_a_panic() {
        assert!(find_linked_pr("", 1).is_none());
        assert!(find_linked_pr("[]", 1).is_none());
        assert!(find_linked_pr("gh: Not Found (HTTP 404)", 1).is_none());
        assert!(find_linked_pr("[{\"number\":", 1).is_none());
    }

    /// "gh could not answer" and "nobody is working on it" are different
    /// answers, and only one of them means implement from scratch.
    ///
    /// The parse used to fold both into `None`, so an authentication failure or
    /// a rate limit read as an empty list and spar opened a second pull request
    /// for an issue somebody already had work open on.
    #[test]
    fn an_unreadable_list_is_not_an_empty_list() {
        assert!(linked_pr_rows("gh: Not Found (HTTP 404)").is_none());
        assert!(linked_pr_rows("[{\"number\":").is_none());
        assert!(linked_pr_rows("").is_none());

        let empty = linked_pr_rows("[]").expect("an empty list is an answer");
        assert!(empty.is_empty());
        assert!(pick_linked_pr(&empty, 14238).is_none());

        let listed = linked_pr_rows(REAL_PAYLOAD).expect("the real payload reads");
        assert_eq!(3, listed.len());
        assert_eq!(14252, pick_linked_pr(&listed, 14238).unwrap().number);
    }

    /// A fork PR cannot be pushed to, so the flag has to survive parsing.
    #[test]
    fn pr_view_reads_the_cross_repository_flag() {
        let json = r#"{"number":7,"url":"u","title":"t","headRefName":"patch-1",
                       "baseRefName":"main","state":"OPEN",
                       "closingIssuesReferences":[],"isCrossRepository":true}"#;
        let pr: PrView = serde_json::from_str(json).unwrap();
        assert!(pr.is_cross_repository);
        assert!(pr.is_open());

        let same_repo = json.replace("\"isCrossRepository\":true", "\"isCrossRepository\":false");
        assert!(
            !serde_json::from_str::<PrView>(&same_repo)
                .unwrap()
                .is_cross_repository
        );
    }
}

#[cfg(test)]
mod min_number_tests {
    /// The floor is applied before the cap, which is the order that matters.
    /// spar takes the *lowest* numbered open items, so a repository with a tail
    /// of old issues would otherwise spend its whole run in the tail: the cap
    /// would be filled by the oldest items and the floor would never be
    /// reached. Filtering first is what makes the setting do anything.
    fn pick(open: &[i64], limit: usize, min_number: i64) -> Vec<i64> {
        let mut numbers: Vec<i64> = open.to_vec();
        numbers.sort_unstable();
        if min_number > 0 {
            numbers.retain(|n| *n >= min_number);
        }
        numbers.truncate(limit);
        numbers
    }

    #[test]
    fn the_floor_is_applied_before_the_cap_not_after() {
        let open = [12, 13, 14, 480, 481, 482];
        assert_eq!(vec![480, 481], pick(&open, 2, 480));
        // Capping first would have returned the two oldest and then filtered
        // them all away, leaving nothing.
        assert!(!pick(&open, 2, 480).is_empty());
    }

    #[test]
    fn no_floor_keeps_the_old_behaviour() {
        assert_eq!(vec![12, 13], pick(&[12, 13, 14, 480], 2, 0));
    }

    #[test]
    fn the_floor_is_inclusive() {
        assert_eq!(vec![480, 481], pick(&[479, 480, 481], 10, 480));
    }

    #[test]
    fn a_floor_above_everything_open_yields_nothing() {
        assert!(pick(&[1, 2, 3], 10, 9999).is_empty());
    }
}

#[cfg(test)]
mod review_record_tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn prune_state_knows_which_files_belong_to_a_pull_request() {
        assert_eq!(Some(12), state_file_number("pr-12.json"));
        assert_eq!(Some(12), state_file_number("review-12.json"));
        assert_eq!(Some(12), state_file_number("checkin-12.json"));
        for shared in [
            "spend.json",
            "implementors.json",
            "contested.json",
            "listen.json",
            "pr-.json",
            "pr-12.json.tmp",
            "pr-x.json",
        ] {
            assert_eq!(None, state_file_number(shared), "{shared}");
        }
    }

    #[test]
    fn a_review_the_viewer_already_submitted_with_the_same_body_is_not_sent_again() {
        let reviews = vec![
            json!({"user": {"login": "Me"}, "body": "the body", "commit_id": "AAA", "state": "APPROVED"}),
            json!({"user": {"login": "alice"}, "body": "other", "commit_id": "aaa", "state": "COMMENTED"}),
        ];
        assert!(has_viewer_review(&reviews, "me", "the body", "aaa"));
        assert!(!has_viewer_review(&reviews, "me", "other", "aaa"));
        assert!(!has_viewer_review(&reviews, "alice", "the body", "aaa"));
    }

    /// A clean review says the same thing on every commit. Taking the approval
    /// of an older commit for this one left the new head unapproved while the
    /// record said it was.
    #[test]
    fn the_same_body_on_another_commit_or_dismissed_is_a_review_still_to_send() {
        let older = vec![
            json!({"user": {"login": "me"}, "body": "the body", "commit_id": "aaa", "state": "APPROVED"}),
        ];
        assert!(!has_viewer_review(&older, "me", "the body", "bbb"));
        let dismissed = vec![
            json!({"user": {"login": "me"}, "body": "the body", "commit_id": "bbb", "state": "DISMISSED"}),
        ];
        assert!(!has_viewer_review(&dismissed, "me", "the body", "bbb"));
    }

    #[test]
    fn a_response_splits_into_status_headers_and_body() {
        let text = "HTTP/2.0 200 OK\r\nX-Poll-Interval: 60\r\nLast-Modified: Tue, 20 Oct 2026 10:00:00 GMT\r\nContent-Type: application/json\r\n\r\n[{\"id\": \"1\"}]\n";
        let resp = parse_api_response(text).expect("a response");
        assert_eq!(200, resp.status);
        assert_eq!(Some(&"60".to_string()), resp.headers.get("x-poll-interval"));
        assert_eq!(
            Some(&"Tue, 20 Oct 2026 10:00:00 GMT".to_string()),
            resp.headers.get("last-modified")
        );
        assert_eq!("[{\"id\": \"1\"}]\n", resp.body);

        let not_modified =
            parse_api_response("HTTP/2.0 304 Not Modified\nX-Poll-Interval: 60\n\n").unwrap();
        assert_eq!(304, not_modified.status);
        assert!(not_modified.body.is_empty());

        assert_eq!(None, parse_api_response(""));
        assert_eq!(None, parse_api_response("gh: command not found\n"));
    }

    #[test]
    fn a_failed_review_submission_that_landed_is_reconciled_as_success() {
        let landed = vec![json!({"user": {"login": "me"}, "body": "the body", "commit_id": "aaa"})];
        let error = crate::error::SparError::call_failed("gh: boom");
        assert!(
            reconcile_review_post(5, "the body", "me", "aaa", error.clone(), Ok(landed)).is_ok()
        );

        let missing = vec![json!({"user": {"login": "me"}, "body": "older", "commit_id": "aaa"})];
        let err = reconcile_review_post(5, "the body", "me", "aaa", error.clone(), Ok(missing))
            .unwrap_err();
        assert_eq!(crate::error::ErrorKind::CallFailed, err.kind());

        let unreadable = Err(crate::error::SparError::new("no network"));
        let err = reconcile_review_post(5, "the body", "me", "aaa", error, unreadable).unwrap_err();
        assert_eq!(crate::error::ErrorKind::UncertainWrite, err.kind());
        assert!(err.to_string().contains("could not be verified"), "{err}");
    }
}