Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
115 KB
Raw Blame
//! Git versioning for the wiki tree.
//!
//! On `Wiki::new`, we lazily `git init` the wiki root if it isn't already
//! a repo. Auto-commits fire from the hook router on `SessionEnd` and
//! from the M7 consolidator. Author/email are fixed so the wiki history
//! can't accidentally leak the maintainer's git identity.
//!
//! A commit stages the paths reported through `mark_written` since the
//! last one; the adapter's own write methods report for their caller and
//! the crate's `clippy.toml` refuses the raw calls. The full walk is the
//! safety net, decided in `take_staging`. The repository stays open
//! between commits: reopening it dropped libgit2's index tree cache, so
//! every commit rebuilt every directory tree.
//!
//! The raw hook event ledgers (`log.md`, `log-YYYY-MM.md`) are never staged.
//! They are append-only logs that reach hundreds of megabytes, git stores each
//! new version as a whole blob, and nothing reads them back from git; see
//! [`is_ledger_file`].
//!
//! Every repository handle turns on libgit2's fsync for `.git` through a
//! config file only libgit2 reads, so a crash cannot leave a ref naming an
//! object whose bytes never reached disk; see [`attach_libgit2_config`].

use std::collections::BTreeSet;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, MutexGuard};
use std::time::{Duration, Instant};

use git2::{ErrorCode, IndexAddOption, ObjectType, Repository, Signature};
use tracing::{debug, error, warn};

use crate::error::{WikiError, WikiResult};

/// Author identity used for ai-memory's own commits. The user can
/// rewrite history with their own identity later if they care.
pub const COMMIT_AUTHOR_NAME: &str = "ai-memory";
/// Author email used for ai-memory's own commits.
pub const COMMIT_AUTHOR_EMAIL: &str = "ai-memory@local";

/// Thin handle over the wiki repo. Cheap to clone — a `PathBuf` and a
/// shared lock.
#[derive(Clone)]
pub struct GitAdapter {
    root: PathBuf,
    /// One commit at a time per repository: libgit2 fails a concurrent
    /// commit with "the index is locked" instead of waiting. Also holds
    /// the repository kept open between commits. Clones share it; a
    /// second adapter opened on the same root does not.
    commit_lock: Arc<Mutex<Option<Open>>>,
    /// Paths written since the last commit; shared by clones like the lock.
    written: Arc<Mutex<Written>>,
}

/// The repository kept open between commits, so libgit2's cached index
/// (tree cache included) survives them. `Index` itself is not `Send`.
struct Open {
    repo: Repository,
    /// HEAD as this adapter last left it; moved by another writer, the
    /// kept index is re-read and the next commit walks.
    head: Option<git2::Oid>,
}

#[derive(Debug, Default)]
struct Written {
    /// Relative to the root; a directory covers its subtree.
    paths: BTreeSet<PathBuf>,
    walk_needed: bool,
    /// `None` before the first commit, which walks.
    last_walk: Option<Instant>,
    /// Everything reported since the last walk, so the walk can name
    /// what nobody reported.
    since_walk: BTreeSet<PathBuf>,
    unreported_writes: u64,
    last_unreported: Vec<PathBuf>,
}

/// A path-scoped commit this long after the last walk walks instead.
const SWEEP_INTERVAL: Duration = Duration::from_secs(600);

const UNREPORTED_SAMPLE: usize = 5;

/// Retries for a commit whose staging read a file mid-write.
const RACY_READ_ATTEMPTS: u32 = 4;
const RACY_READ_BACKOFF: Duration = Duration::from_millis(25);

/// A staging read that raced a writer outside the commit lock: libgit2's
/// "file changed before we could read it" (mid-write), or a file that was
/// listed by the walk but gone by the time libgit2 streamed it in (an `Os`
/// "failed to read file into stream" — e.g. an atomic writer's temp file
/// renamed away between the scan and the read). Both settle within
/// milliseconds; a rescan no longer sees a vanished file.
fn is_racy_read(e: &git2::Error) -> bool {
    match e.class() {
        git2::ErrorClass::Filesystem => e.message().contains("changed before"),
        git2::ErrorClass::Os => e.message().contains("failed to read file into stream"),
        _ => false,
    }
}

/// Writes that reached the tree without a report: a writer bypassed the wiki.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SweepSnapshot {
    /// Over the adapter's life.
    pub unreported_writes: u64,
    /// Up to [`UNREPORTED_SAMPLE`] of them from the last walk.
    pub last_unreported: Vec<PathBuf>,
}

enum Staging {
    Everything,
    Paths(BTreeSet<PathBuf>),
}

/// One git checkpoint in the wiki repository.
#[derive(Debug, Clone)]
pub struct Checkpoint {
    /// Full commit OID.
    pub oid: String,
    /// Commit summary (first line of the commit message).
    pub summary: String,
    /// Author timestamp, seconds since Unix epoch.
    pub time: i64,
}

enum CommitGit2Error {
    Open(git2::Error),
    Other(git2::Error),
    Wiki(WikiError),
}

enum OpenRepositoryError {
    Git(git2::Error),
    Wiki(WikiError),
}

fn open_validated_repository(root: &Path) -> Result<Repository, OpenRepositoryError> {
    let expected_git_dir =
        crate::confinement::inspect_git_directory(root).map_err(OpenRepositoryError::Wiki)?;
    let repo = Repository::open(root).map_err(OpenRepositoryError::Git)?;
    let workdir = repo.workdir().ok_or_else(|| {
        OpenRepositoryError::Wiki(WikiError::Confinement {
            path: root.to_path_buf(),
            reason: "wiki repository must have a working tree",
        })
    })?;
    let canonical_root = root
        .canonicalize()
        .map_err(WikiError::from)
        .map_err(OpenRepositoryError::Wiki)?;
    let canonical_workdir = workdir
        .canonicalize()
        .map_err(WikiError::from)
        .map_err(OpenRepositoryError::Wiki)?;
    let canonical_git_dir = repo
        .path()
        .canonicalize()
        .map_err(WikiError::from)
        .map_err(OpenRepositoryError::Wiki)?;
    let canonical_common_dir = repo
        .commondir()
        .canonicalize()
        .map_err(WikiError::from)
        .map_err(OpenRepositoryError::Wiki)?;
    let canonical_expected_git_dir = expected_git_dir
        .canonicalize()
        .map_err(WikiError::from)
        .map_err(OpenRepositoryError::Wiki)?;
    if canonical_workdir != canonical_root {
        return Err(OpenRepositoryError::Wiki(WikiError::Confinement {
            path: workdir.to_path_buf(),
            reason: "wiki repository working directory escapes the wiki root",
        }));
    }
    if canonical_git_dir != canonical_expected_git_dir
        || canonical_common_dir != canonical_expected_git_dir
    {
        return Err(OpenRepositoryError::Wiki(WikiError::Confinement {
            path: repo.path().to_path_buf(),
            reason: "wiki repository metadata escapes the in-root .git directory",
        }));
    }
    attach_libgit2_config(&repo).map_err(OpenRepositoryError::Git)?;
    Ok(repo)
}

fn map_open_error(error: OpenRepositoryError) -> WikiError {
    match error {
        OpenRepositoryError::Git(error) => map_git_err(error),
        OpenRepositoryError::Wiki(error) => error,
    }
}

/// The validated repository, or `None` when libgit2 cannot open it and the
/// Windows git CLI fallback will serve it instead.
fn validate_repository_or_allow_cli_fallback(root: &Path) -> WikiResult<Option<Repository>> {
    match open_validated_repository(root) {
        Ok(repo) => Ok(Some(repo)),
        Err(OpenRepositoryError::Git(error))
            if cfg!(windows) && should_try_commit_cli_fallback(&error) =>
        {
            validate_cli_fallback_root(root).map(|()| None)
        }
        Err(error) => Err(map_open_error(error)),
    }
}

/// The config key that makes libgit2 fsync each loose object, ref and reflog
/// (and the directory it lands in) before renaming it into place.
const FSYNC_OBJECT_FILES: &str = "core.fsyncObjectFiles";

/// Config file in the wiki's `.git` that only libgit2 reads: git looks for
/// `config` (and `config.worktree`) there, never for this name.
const LIBGIT2_CONFIG_FILE: &str = "ai-memory.gitconfig";

const LIBGIT2_CONFIG: &str = "\
# Written by ai-memory and read only by its libgit2 handles (#1511).
[core]
\tfsyncObjectFiles = true
";

/// Write [`LIBGIT2_CONFIG_FILE`] into the wiki's `.git` unless it already
/// holds [`LIBGIT2_CONFIG`]. Runs once per adapter, at startup.
fn write_libgit2_config(git_dir: &Path) -> WikiResult<()> {
    let path = git_dir.join(LIBGIT2_CONFIG_FILE);
    if std::fs::read(&path).is_ok_and(|bytes| bytes == LIBGIT2_CONFIG.as_bytes()) {
        return Ok(());
    }
    // Inside `.git`, which a commit never stages, so there is nothing to report.
    #[allow(clippy::disallowed_methods)]
    crate::atomic::write_atomic(&path, LIBGIT2_CONFIG.as_bytes())?;
    Ok(())
}

/// Give this handle libgit2's fsync for `.git`, unless the repository's own
/// config turns it off.
///
/// libgit2 writes objects and refs to a temp file and renames it, without
/// fsync by default. After a crash the rename, and the ref update that names
/// the new commit, can survive while the object's bytes never reached disk:
/// zero-length loose objects and a HEAD that no longer reads, so every later
/// checkpoint fails (#1511). The process-wide `GIT_OPT_ENABLE_FSYNC_GITDIR`
/// covers the same writes, but git2 has no safe wrapper for it and the
/// workspace forbids `unsafe`. Writing the key to `.git/config` would make the
/// git CLI warn that it is deprecated on every command an operator runs in the
/// wiki, so it goes in [`LIBGIT2_CONFIG_FILE`], added to this handle's live
/// config at the app level.
///
/// Why this reaches the fsync decision (vendored libgit2 1.9.3):
/// `Repository::config` returns the handle's own config object, not a
/// snapshot, and libgit2 reads `core.fsyncObjectFiles` from that object
/// through the configmap cache when it first loads the object database
/// (`git_odb__set_caps`) and the refdb (`refdb_fs` backend). Opening a
/// repository loads neither, so the cached value is still unset here; this
/// runs before any caller touches the handle.
///
/// The app level outranks every file git itself reads, so an explicit
/// `false` in `.git/config` is checked first and kept. The app backend also
/// becomes the handle's preferred writer; ai-memory never writes config
/// through a handle.
fn attach_libgit2_config(repo: &Repository) -> Result<(), git2::Error> {
    let mut config = repo.config()?;
    let local = match config.open_level(git2::ConfigLevel::Local) {
        Ok(local) => local.get_bool(FSYNC_OBJECT_FILES).ok(),
        Err(error) if error.code() == ErrorCode::NotFound => None,
        Err(error) => return Err(error),
    };
    if local == Some(false) {
        return Ok(());
    }
    config.add_file(
        &repo.path().join(LIBGIT2_CONFIG_FILE),
        git2::ConfigLevel::App,
        false,
    )
}

/// `Ok` when HEAD is unborn (a fresh repository) or resolves to a commit
/// whose tree reads back; the error otherwise, such as libgit2's
/// "failed to parse loose object" for an object a crash left empty.
fn readable_head(repo: &Repository) -> Result<(), git2::Error> {
    let head = match repo.head() {
        Ok(head) => head,
        Err(error) if matches!(error.code(), ErrorCode::UnbornBranch | ErrorCode::NotFound) => {
            return Ok(());
        }
        Err(error) => return Err(error),
    };
    head.peel_to_commit()?.tree()?;
    Ok(())
}

/// Startup checks on the wiki repository. Neither fails the server: the
/// markdown on disk is the source of truth and keeps being served, but a
/// history that cannot take a commit is reported once, loudly, instead of
/// only as a warning from each checkpoint that fails.
fn check_repository_durability(root: &Path, repo: &Repository) {
    match repo
        .config()
        .and_then(|config| config.get_bool(FSYNC_OBJECT_FILES))
    {
        Ok(true) => {}
        Ok(false) => warn!(
            root = %root.display(),
            "{FSYNC_OBJECT_FILES} is false in the wiki repository's config; a crash can leave \
             its history with empty objects"
        ),
        Err(error) => warn!(
            root = %root.display(),
            %error,
            "could not read the wiki repository's fsync setting; a crash can leave its history \
             with empty objects"
        ),
    }
    if let Err(error) = readable_head(repo) {
        error!(
            root = %root.display(),
            %error,
            "wiki git history is unreadable: HEAD does not resolve to a readable commit, so \
             every checkpoint will fail until it is repaired. Pages on disk are not affected. \
             See \"Wiki git history unreadable after a crash\" in docs/lifecycle-ops.md"
        );
    }
}

fn validate_cli_fallback_root(root: &Path) -> WikiResult<()> {
    let git_dir = crate::confinement::inspect_git_directory(root)?;
    crate::confinement::inspect_tree_except(root, &[git_dir.as_path()])?;
    let worktree = git_resolved_path(root, "--show-toplevel")?;
    let resolved_git_dir = git_resolved_path(root, "--absolute-git-dir")?;
    let common_dir = git_resolved_path(root, "--git-common-dir")?;
    validate_resolved_repository_paths(root, &git_dir, &worktree, &resolved_git_dir, &common_dir)
}

/// Establish the configured repository root as a validated filesystem
/// boundary before it is retained by [`GitAdapter`].
fn repository_root(root: &Path) -> WikiResult<PathBuf> {
    crate::confinement::initialize_root(root)?;
    Ok(root.to_path_buf())
}

fn git_resolved_path(root: &Path, argument: &str) -> WikiResult<PathBuf> {
    let output = git_command(root)
        .args(["rev-parse", "--path-format=absolute", argument])
        .output()?;
    if !output.status.success() {
        return Err(WikiError::Io(std::io::Error::other(format!(
            "git repository validation exited with status {}: {}",
            output.status,
            String::from_utf8_lossy(&output.stderr)
        ))));
    }
    let raw = String::from_utf8_lossy(&output.stdout);
    let path = PathBuf::from(raw.trim());
    if path.as_os_str().is_empty() {
        return Err(WikiError::Confinement {
            path: root.to_path_buf(),
            reason: "git CLI returned an empty repository path",
        });
    }
    if !path.is_absolute() {
        return Err(WikiError::Confinement {
            path,
            reason: "git CLI returned a non-absolute repository path",
        });
    }
    Ok(path)
}

fn validate_resolved_repository_paths(
    root: &Path,
    expected_git_dir: &Path,
    worktree: &Path,
    git_dir: &Path,
    common_dir: &Path,
) -> WikiResult<()> {
    let canonical_root = root.canonicalize()?;
    let canonical_expected_git_dir = expected_git_dir.canonicalize()?;
    let canonical_worktree = worktree.canonicalize()?;
    let canonical_git_dir = git_dir.canonicalize()?;
    let canonical_common_dir = common_dir.canonicalize()?;
    if canonical_worktree != canonical_root {
        return Err(WikiError::Confinement {
            path: worktree.to_path_buf(),
            reason: "git CLI resolved a working directory outside the wiki root",
        });
    }
    if canonical_git_dir != canonical_expected_git_dir
        || canonical_common_dir != canonical_expected_git_dir
    {
        return Err(WikiError::Confinement {
            path: git_dir.to_path_buf(),
            reason: "git CLI resolved metadata outside the in-root .git directory",
        });
    }
    Ok(())
}

fn git_command(root: &Path) -> std::process::Command {
    let mut command = std::process::Command::new("git");
    command
        .env_remove("GIT_DIR")
        .env_remove("GIT_WORK_TREE")
        .env_remove("GIT_COMMON_DIR")
        .env_remove("GIT_INDEX_FILE")
        .env_remove("GIT_OBJECT_DIRECTORY")
        .env_remove("GIT_ALTERNATE_OBJECT_DIRECTORIES")
        .arg("-C")
        .arg(root); // lgtm [rust/command-line-injection]
    command
}

impl GitAdapter {
    /// Open or initialise the repo at `root`. Idempotent: if the
    /// directory is already a git repo, leaves it alone.
    ///
    /// # Errors
    /// Propagates any underlying libgit2 error.
    pub fn open_or_init(root: &Path) -> WikiResult<Self> {
        let root = repository_root(root)?;
        match std::fs::symlink_metadata(root.join(".git")) {
            Ok(_) => debug!(root = %root.display(), "wiki repo already initialised"),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
                debug!(root = %root.display(), "initialising wiki repo");
                init_repo(&root)?;
            }
            Err(error) => return Err(error.into()),
        }
        write_libgit2_config(&crate::confinement::inspect_git_directory(&root)?)?;
        if let Some(repo) = validate_repository_or_allow_cli_fallback(&root)? {
            check_repository_durability(&root, &repo);
        }
        Ok(Self {
            root,
            commit_lock: Arc::new(Mutex::new(None)),
            written: Arc::new(Mutex::new(Written::default())),
        })
    }

    fn written(&self) -> MutexGuard<'_, Written> {
        self.written.lock().unwrap_or_else(|e| e.into_inner())
    }

    /// Report a path written, moved or removed (absolute or relative to
    /// the root); the next commit stages it. A path outside the root is
    /// a caller's bug: logged, and the next commit walks.
    pub fn mark_written(&self, path: &Path) {
        let rel = if path.is_absolute() {
            path.strip_prefix(&self.root).ok()
        } else {
            Some(path)
        };
        // The watcher reports git's own writes too; never stage them.
        // Also ignore any path that contains a git-reserved component.
        if rel.is_some_and(|rel| {
            rel.components().any(|c| {
                ai_memory_core::is_git_reserved_component(&c.as_os_str().to_string_lossy())
            })
        }) {
            return;
        }
        let mut written = self.written();
        match rel {
            Some(rel) if !rel.as_os_str().is_empty() => {
                written.paths.insert(rel.to_path_buf());
                written.since_walk.insert(rel.to_path_buf());
            }
            _ => {
                warn!(path = %path.display(), "reported path is not under the wiki root");
                written.walk_needed = true;
            }
        }
    }

    /// Drop the kept repository, as a restart would.
    #[cfg(test)]
    pub(crate) fn close(&self) {
        *self.commit_lock.lock().unwrap_or_else(|e| e.into_inner()) = None;
    }

    /// Make the next path-scoped commit walk, as if the sweep were due.
    #[cfg(test)]
    pub(crate) fn age_last_walk(&self) {
        let mut written = self.written();
        if let Some(aged) = Instant::now().checked_sub(SWEEP_INTERVAL) {
            written.last_walk = Some(aged);
        } else {
            // A fresh Windows runner may not have ten minutes of clock history.
            // Preserve the previous walk so the sweep still counts missed writes.
            written.walk_needed = true;
        }
    }

    /// What the sweeps found; see [`SweepSnapshot`].
    #[must_use]
    pub fn sweep_snapshot(&self) -> SweepSnapshot {
        let written = self.written();
        SweepSnapshot {
            unreported_writes: written.unreported_writes,
            last_unreported: written.last_unreported.clone(),
        }
    }
    #[cfg(test)]
    pub(crate) fn written_paths(&self) -> Vec<PathBuf> {
        self.written().paths.iter().cloned().collect()
    }

    /// Path of the wiki root.
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// Stage the reported paths (or walk the tree; see `take_staging`)
    /// and commit with `message`. Returns `Ok(None)` when nothing
    /// changed, `Ok(Some(commit_oid))` on a commit.
    ///
    /// # Errors
    /// Propagates any underlying libgit2 error.
    pub fn commit_all(&self, message: &str) -> WikiResult<Option<git2::Oid>> {
        self.commit_all_with_fallback(message, commit_all_fallback)
    }

    fn commit_all_with_fallback<F>(
        &self,
        message: &str,
        fallback: F,
    ) -> WikiResult<Option<git2::Oid>>
    where
        F: FnOnce(&Path, &str, git2::Error) -> WikiResult<Option<git2::Oid>>,
    {
        // One hold of the commit lock spans the confinement walk and the
        // commit. Our own commit activity churns `.git` lock and temp
        // files and atomic temp names in the tree; a walk beside it saw
        // entries that vanished between read_dir and stat. Writers we do
        // not serialize (the git CLI, a second adapter) remain covered by
        // the walk's own vanish tolerance.
        let mut slot = self.writing();
        let git_dir = crate::confinement::inspect_git_directory(&self.root)?;
        crate::confinement::inspect_tree_except(&self.root, &[git_dir.as_path()])?;
        match self.commit_all_git2(&mut slot, message) {
            Ok(result) => Ok(result),
            Err(CommitGit2Error::Open(error)) => commit_open_error_with_fallback_on(
                cfg!(windows),
                &self.root,
                message,
                error,
                fallback,
            ),
            Err(CommitGit2Error::Other(error)) => Err(map_git_err(error)),
            Err(CommitGit2Error::Wiki(error)) => Err(error),
        }
    }

    /// Called with the commit lock already held by
    /// [`commit_all_with_fallback`]; `slot` is that lock's payload.
    fn commit_all_git2(
        &self,
        slot: &mut Option<Open>,
        message: &str,
    ) -> Result<Option<git2::Oid>, CommitGit2Error> {
        if slot.is_none() {
            let repo = open_validated_repository(&self.root).map_err(|error| match error {
                OpenRepositoryError::Git(error) => CommitGit2Error::Open(error),
                OpenRepositoryError::Wiki(error) => CommitGit2Error::Wiki(error),
            })?;
            *slot = Some(Open { repo, head: None });
        }
        crate::confinement::inspect_git_directory(&self.root).map_err(CommitGit2Error::Wiki)?;
        let open = slot.as_mut().expect("opened above");
        let head_now = open.repo.head().ok().and_then(|h| h.target());
        if open.head.is_some() && open.head != head_now {
            warn!("HEAD moved under the kept index; re-reading it and walking");
            open.repo
                .index()
                .and_then(|mut index| index.read(true))
                .map_err(CommitGit2Error::Other)?;
            self.written().walk_needed = true;
        }
        let staging = self.take_staging();
        let mut attempt = 0u32;
        let result = loop {
            attempt += 1;
            match self.commit_staged(open, message, &staging) {
                // A writer outside the lock was mid-write; it settles in
                // milliseconds.
                Err(CommitGit2Error::Other(e))
                    if is_racy_read(&e) && attempt < RACY_READ_ATTEMPTS =>
                {
                    debug!(attempt, "a file changed under the commit; retrying");
                    std::thread::sleep(RACY_READ_BACKOFF);
                }
                other => break other,
            }
        };
        if let Ok(oid) = &result {
            open.head = oid.or(head_now);
        }
        if let Err(e) = &result {
            *slot = None;
            let racy = matches!(e, CommitGit2Error::Other(e) if is_racy_read(e));
            self.keep_pending(staging, racy);
        }
        result
    }

    /// After a failed commit: the paths stay reported, and unless the
    /// failure was a racy read the next commit walks.
    fn keep_pending(&self, staging: Staging, racy: bool) {
        let mut written = self.written();
        if let Staging::Paths(paths) = staging {
            written.since_walk.extend(paths.iter().cloned());
            written.paths.extend(paths);
        }
        written.walk_needed |= !racy;
    }
    /// Walk when told to, when nothing was reported, or when the sweep is
    /// due; otherwise stage the reported paths. Called under the commit lock.
    fn take_staging(&self) -> Staging {
        let mut written = self.written();
        let sweep_due = written
            .last_walk
            .is_none_or(|at| at.elapsed() >= SWEEP_INTERVAL);
        if written.walk_needed || written.paths.is_empty() || sweep_due {
            written.walk_needed = false;
            written.paths.clear();
            Staging::Everything
        } else {
            Staging::Paths(std::mem::take(&mut written.paths))
        }
    }

    /// After a walk: name what nobody reported since the last one and
    /// start the next interval. The first walk has nothing to compare
    /// against.
    fn record_walk(&self, walked: &[PathBuf]) {
        let mut written = self.written();
        if written.last_walk.is_some() {
            // A report covers its subtree.
            let mut unreported: Vec<PathBuf> = walked
                .iter()
                .filter(|path| !path.ancestors().any(|a| written.since_walk.contains(a)))
                .cloned()
                .collect();
            if !unreported.is_empty() {
                warn!(
                    count = unreported.len(),
                    first = ?unreported.iter().take(UNREPORTED_SAMPLE).collect::<Vec<_>>(),
                    "the sweep staged writes nobody reported: a writer bypassed the wiki"
                );
            }
            written.unreported_writes += unreported.len() as u64;
            unreported.truncate(UNREPORTED_SAMPLE);
            written.last_unreported = unreported;
        }
        written.since_walk.clear();
        written.last_walk = Some(Instant::now());
    }

    fn commit_staged(
        &self,
        open: &Open,
        message: &str,
        staging: &Staging,
    ) -> Result<Option<git2::Oid>, CommitGit2Error> {
        let root = repository_root(&self.root).map_err(CommitGit2Error::Wiki)?;
        let repo = &open.repo;
        let mut index = repo.index().map_err(CommitGit2Error::Other)?;
        // Stage through libgit2's stat cache: an entry whose size and mtime
        // are unchanged keeps its cached blob OID and is not re-read, so a
        // commit costs what changed rather than the whole tree. The cache can
        // name a blob that is gone from the object database (a store carried
        // across libgit2/git versions, or an interrupted operation); then
        // `write_tree` fails, and through the wiki migration that crash-looped
        // the server at boot (#594). That is the recovery path: drop the index
        // and hash every file again, once.
        let touched = match staging {
            Staging::Everything => {
                let walked =
                    stage_working_tree(&root, &mut index).map_err(CommitGit2Error::Other)?;
                // The walk only skips ledgers it would add or update; one a
                // past version already tracks, and that has not changed, is
                // not offered to it at all.
                untrack_ledgers(&root, &mut index, None).map_err(CommitGit2Error::Other)?;
                self.record_walk(&walked);
                walked.len()
            }
            Staging::Paths(paths) => {
                stage_paths(&root, &mut index, paths).map_err(CommitGit2Error::Other)?
            }
        };
        debug!(
            touched,
            walked = matches!(staging, Staging::Everything),
            "staged"
        );
        let tree_oid = match index.write_tree() {
            Ok(oid) => oid,
            Err(e) => {
                warn!(
                    error = %e,
                    "index could not be written as a tree; re-hashing the working tree (#594)"
                );
                index.clear().map_err(CommitGit2Error::Other)?;
                stage_working_tree(&root, &mut index).map_err(CommitGit2Error::Other)?;
                index.write().map_err(CommitGit2Error::Other)?;
                index.write_tree().map_err(CommitGit2Error::Other)?
            }
        };
        // Every commit, including the one with nothing to commit, leaves the
        // index file matching the tree: another process (the git CLI, an
        // editor, a backup) reads the file, and a stale one shows the
        // checkpointed pages as both staged and unstaged (#983). Written
        // after `write_tree`, it also carries the tree cache.
        index.write().map_err(CommitGit2Error::Other)?;

        // If the index matches HEAD, there is nothing to commit.
        if let Ok(head) = repo.head()
            && let Some(target) = head.target()
            && let Ok(parent_commit) = repo.find_commit(target)
            && parent_commit.tree_id() == tree_oid
        {
            debug!("working tree clean; no commit");
            return Ok(None);
        }
        // Fresh repo with no HEAD yet: still skip the commit if there
        // is nothing staged. Otherwise we'd produce an "initial" commit
        // pointing at the empty tree, which surprises both `git log`
        // and our own callers.
        if repo.head().is_err() && index.is_empty() {
            debug!("fresh repo, empty index; no commit");
            return Ok(None);
        }
        let tree = repo.find_tree(tree_oid).map_err(CommitGit2Error::Other)?;
        let sig = Signature::now(COMMIT_AUTHOR_NAME, COMMIT_AUTHOR_EMAIL)
            .map_err(CommitGit2Error::Other)?;

        let parents: Vec<git2::Commit<'_>> = match repo.head() {
            Ok(head) => match head.target() {
                Some(oid) => vec![repo.find_commit(oid).map_err(CommitGit2Error::Other)?],
                None => Vec::new(),
            },
            Err(_) => Vec::new(),
        };
        let parent_refs: Vec<&git2::Commit<'_>> = parents.iter().collect();
        let oid = repo
            .commit(Some("HEAD"), &sig, &sig, message, &tree, &parent_refs)
            .map_err(CommitGit2Error::Other)?;
        debug!(oid = %oid, "wiki commit");
        Ok(Some(oid))
    }

    /// Count commits reachable from HEAD. Returns 0 for an empty or unreadable repo.
    /// Useful for the test suite + for `ai-memory status`.
    #[must_use]
    pub fn commit_count(&self) -> usize {
        self.commit_count_checked().unwrap_or(0)
    }

    pub(crate) fn commit_count_checked(&self) -> WikiResult<usize> {
        let repo = match open_validated_repository(&self.root) {
            Ok(repo) => repo,
            Err(OpenRepositoryError::Git(error)) => {
                #[cfg(windows)]
                if should_try_commit_cli_fallback(&error) {
                    return commit_count_fallback_checked(&self.root);
                }
                return Err(map_git_err(error));
            }
            Err(OpenRepositoryError::Wiki(error)) => return Err(error),
        };
        let Ok(mut walk) = repo.revwalk() else {
            return Ok(0);
        };
        if walk.push_head().is_err() {
            return Ok(0);
        }
        Ok(walk.count())
    }

    /// Return the most recent commits reachable from HEAD.
    ///
    /// Empty repositories return an empty list.
    ///
    /// # Errors
    /// Propagates any underlying libgit2 error.
    pub fn recent_checkpoints(&self, limit: usize) -> WikiResult<Vec<Checkpoint>> {
        let repo = match open_validated_repository(&self.root) {
            Ok(repo) => repo,
            Err(OpenRepositoryError::Git(error)) => {
                #[cfg(windows)]
                if should_try_commit_cli_fallback(&error) {
                    return recent_checkpoints_fallback(&self.root, limit, error);
                }
                return Err(map_git_err(error));
            }
            Err(OpenRepositoryError::Wiki(error)) => return Err(error),
        };
        if limit == 0 {
            return Ok(Vec::new());
        }
        let mut walk = repo.revwalk().map_err(map_git_err)?;
        if walk.push_head().is_err() {
            return Ok(Vec::new());
        }
        let mut out = Vec::with_capacity(limit.min(100));
        for oid in walk.take(limit) {
            let oid = oid.map_err(map_git_err)?;
            let commit = repo.find_commit(oid).map_err(map_git_err)?;
            out.push(Checkpoint {
                oid: oid.to_string(),
                summary: commit
                    .summary()
                    .ok()
                    .flatten()
                    .unwrap_or("(no summary)")
                    .to_string(),
                time: commit.time().seconds(),
            });
        }
        Ok(out)
    }

    /// Return up to `limit` commits, newest first, that changed the file at
    /// `path` (relative to the repo root), including the commit that deleted
    /// it. At most `max_walk` commits are inspected, so a page untouched for a
    /// long history costs a bounded walk rather than the whole repository.
    ///
    /// # Errors
    /// Propagates any underlying libgit2 error.
    pub fn path_checkpoints(
        &self,
        path: &Path,
        limit: usize,
        max_walk: usize,
    ) -> WikiResult<Vec<Checkpoint>> {
        let repo = open_validated_repository(&self.root).map_err(|error| match error {
            OpenRepositoryError::Git(error) => map_git_err(error),
            OpenRepositoryError::Wiki(error) => error,
        })?;
        if limit == 0 {
            return Ok(Vec::new());
        }
        let mut walk = repo.revwalk().map_err(map_git_err)?;
        if walk.push_head().is_err() {
            return Ok(Vec::new());
        }
        let blob_at = |commit: &git2::Commit<'_>| {
            commit
                .tree()
                .ok()
                .and_then(|tree| tree.get_path(path).ok())
                .map(|entry| entry.id())
        };
        let mut out = Vec::new();
        for oid in walk.take(max_walk) {
            let oid = oid.map_err(map_git_err)?;
            let commit = repo.find_commit(oid).map_err(map_git_err)?;
            let parent_blob = commit.parent(0).ok().and_then(|p| blob_at(&p));
            if blob_at(&commit) == parent_blob {
                continue;
            }
            out.push(Checkpoint {
                oid: oid.to_string(),
                summary: commit
                    .summary()
                    .ok()
                    .flatten()
                    .unwrap_or("(no summary)")
                    .to_string(),
                time: commit.time().seconds(),
            });
            if out.len() >= limit {
                break;
            }
        }
        Ok(out)
    }

    /// Read `path` as it existed at `rev`.
    ///
    /// `path` is relative to the wiki repo root. The returned bytes are the
    /// blob contents exactly as stored in git.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the revision, path, or blob cannot be read.
    pub fn file_at_rev(&self, rev: &str, path: &Path) -> WikiResult<Vec<u8>> {
        let repo = match open_validated_repository(&self.root) {
            Ok(repo) => repo,
            Err(OpenRepositoryError::Git(error)) => {
                #[cfg(windows)]
                if should_try_commit_cli_fallback(&error) {
                    return file_at_rev_fallback(&self.root, rev, path, map_git_err(error));
                }
                return Err(map_git_err(error));
            }
            Err(OpenRepositoryError::Wiki(error)) => return Err(error),
        };
        let object = repo.revparse_single(rev).map_err(map_git_err)?;
        let commit = object.peel_to_commit().map_err(map_git_err)?;
        let tree = commit.tree().map_err(map_git_err)?;
        let entry = tree.get_path(path).map_err(map_git_err)?;
        let blob = entry
            .to_object(&repo)
            .map_err(map_git_err)?
            .peel(ObjectType::Blob)
            .map_err(map_git_err)?;
        let blob = blob.as_blob().ok_or_else(|| {
            WikiError::Io(std::io::Error::other(format!(
                "{} at {rev} is not a file",
                path.display()
            )))
        })?;
        Ok(blob.content().to_vec())
    }
}

/// The writes into the tree, each reporting its path; `clippy.toml`
/// refuses the raw calls. Each holds the commit lock for the write, so a
/// commit never reads a file mid-write ("file changed before we could
/// read it" would drop the commit).
#[allow(clippy::disallowed_methods)]
impl GitAdapter {
    fn confined(&self, path: &Path, prepare: crate::confinement::Prepare) -> WikiResult<PathBuf> {
        let relative = path
            .strip_prefix(&self.root)
            .map_err(|_| WikiError::Confinement {
                path: path.to_path_buf(),
                reason: "path is outside the wiki root",
            })?;
        crate::confinement::tree_path(&self.root, relative, prepare)
    }

    fn writing(&self) -> MutexGuard<'_, Option<Open>> {
        self.commit_lock.lock().unwrap_or_else(|e| e.into_inner())
    }

    /// Write `bytes` to `path` atomically (tmp, rename, fsync).
    ///
    /// # Errors
    /// Propagates the filesystem error.
    pub fn write_atomic(&self, path: &Path, bytes: &[u8]) -> WikiResult<()> {
        let _writing = self.writing();
        let path = self.confined(path, crate::confinement::Prepare::Parents)?;
        crate::atomic::write_atomic(&path, bytes)?;
        self.mark_written(&path);
        Ok(())
    }

    /// Persist a temp file over `path` and return the persisted file.
    pub(crate) fn persist(
        &self,
        tmp: tempfile::NamedTempFile,
        path: &Path,
    ) -> WikiResult<std::fs::File> {
        let _writing = self.writing();
        let path = self.confined(path, crate::confinement::Prepare::Parents)?;
        let file = crate::atomic::persist_with_retry(tmp, &path)?;
        self.mark_written(&path);
        Ok(file)
    }

    /// Append `bytes` to `path`, creating it and its parent as needed.
    ///
    /// # Errors
    /// Propagates the filesystem error.
    pub fn append(&self, path: &Path, bytes: &[u8]) -> std::io::Result<()> {
        self.append_checked(path, bytes)
            .map_err(crate::error::into_io_error)
    }

    pub(crate) fn append_checked(&self, path: &Path, bytes: &[u8]) -> WikiResult<()> {
        let _writing = self.writing();
        use std::io::Write as _;
        let path = self.confined(path, crate::confinement::Prepare::Parents)?;
        let mut file = std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&path)?; // lgtm [rust/path-injection]
        file.write_all(bytes)?;
        file.sync_data()?;
        self.mark_written(&path);
        Ok(())
    }

    /// Move `from` to `to`.
    ///
    /// # Errors
    /// Propagates the filesystem error.
    pub fn rename(&self, from: &Path, to: &Path) -> std::io::Result<()> {
        self.rename_checked(from, to)
            .map_err(crate::error::into_io_error)
    }

    pub(crate) fn rename_checked(&self, from: &Path, to: &Path) -> WikiResult<()> {
        let _writing = self.writing();
        let from = self.confined(from, crate::confinement::Prepare::Inspect)?;
        let to = self.confined(to, crate::confinement::Prepare::Parents)?;
        std::fs::rename(&from, &to)?;
        self.mark_written(&from);
        self.mark_written(&to);
        Ok(())
    }

    /// Remove one file.
    ///
    /// # Errors
    /// Propagates the filesystem error.
    pub fn remove_file(&self, path: &Path) -> std::io::Result<()> {
        self.remove_file_checked(path)
            .map_err(crate::error::into_io_error)
    }

    pub(crate) fn remove_file_checked(&self, path: &Path) -> WikiResult<()> {
        let _writing = self.writing();
        let path = self.confined(path, crate::confinement::Prepare::Inspect)?;
        std::fs::remove_file(&path)?; // lgtm [rust/path-injection]
        self.mark_written(&path);
        Ok(())
    }

    /// Remove a directory and everything under it.
    ///
    /// # Errors
    /// Propagates the filesystem error.
    pub fn remove_dir_all(&self, path: &Path) -> std::io::Result<()> {
        self.remove_dir_all_checked(path)
            .map_err(crate::error::into_io_error)
    }

    pub(crate) fn remove_dir_all_checked(&self, path: &Path) -> WikiResult<()> {
        let _writing = self.writing();
        let path = self.confined(path, crate::confinement::Prepare::Inspect)?;
        std::fs::remove_dir_all(&path)?;
        self.mark_written(&path);
        Ok(())
    }
}

/// Forward slashes whatever the platform, for pathspecs and page paths.
pub(crate) fn slash_path(rel: &Path) -> String {
    rel.to_string_lossy().replace('\\', "/")
}

/// Bring the index in line with the working tree: refresh modified
/// entries, drop deleted ones, add untracked files. libgit2 does all three
/// from one index-to-workdir diff. Returns the paths touched; does not
/// write the index file.
///
/// Ledgers are skipped: a positive return from the callback leaves that path
/// alone, neither added nor refreshed.
fn stage_working_tree(root: &Path, index: &mut git2::Index) -> Result<Vec<PathBuf>, git2::Error> {
    let mut touched = Vec::new();
    index.add_all(
        ["*"].iter(),
        IndexAddOption::DEFAULT,
        Some(&mut |path: &Path, _: &[u8]| {
            if is_ledger_file(root, path) || is_in_flight_write(path) {
                return 1;
            }
            touched.push(path.to_path_buf());
            0
        }),
    )?;
    Ok(touched)
}

/// True when `rel`'s basename belongs to a write still in flight: a
/// `.ai-memory-tmp.` staging file or a `.ai-memory-delete.` parked page.
///
/// These exist only between a write starting and its rename, so committing one
/// records a page body that may never be installed. `Wiki::apply_batch` holds
/// one staging file per page across an `await`, and `commit_all` takes only the
/// commit lock, never the mutation lock, so a checkpoint can land in that
/// window. A parked page is also reported by name: `rename_checked` marks the
/// `.ai-memory-delete.` quarantine and the `.ai-memory-tmp.move-session.` name
/// written, so the reported-file branch of [`stage_paths`] checks this too.
/// The watcher drops both for its own reasons: `is_tempfile` matches the
/// `.ai-memory-tmp.` prefix, and a quarantine name carries no `.md` suffix.
fn is_in_flight_write(rel: &Path) -> bool {
    rel.file_name()
        .and_then(|name| name.to_str())
        .is_some_and(|name| {
            name.starts_with(".ai-memory-tmp.") || name.starts_with(".ai-memory-delete.")
        })
}

/// True when `rel` (relative to the wiki root) is a raw hook event ledger:
/// a `log.md` / `log-YYYY-MM.md` file whose content also opens with a hook log
/// entry.
///
/// Both halves are needed, as everywhere else a ledger is recognized
/// ([`crate::ledger`]): an ordinary page may be named `log-2026-09.md`, and it
/// must stay versioned. The content half reads at most
/// `GATE_PREFIX_BYTES` from the file, so a ledger of any size costs one small
/// read per commit.
///
/// Why this is not a `.gitignore` or `info/exclude` entry: those match names,
/// so one entry would also hide an ordinary page that wears a ledger's name,
/// and the entry would outlive the file's being a ledger.
fn is_ledger_file(root: &Path, rel: &Path) -> bool {
    rel.file_name()
        .and_then(|name| name.to_str())
        .is_some_and(ai_memory_core::log_ledger::is_log_ledger_path)
        && crate::ledger::opens_with_log_ledger(&root.join(rel))
}

/// Drop ledgers that earlier versions committed from the index, under the
/// directory `under` (a `/`-separated path) or everywhere when it is `None`.
/// The files stay on disk: only the index entry goes, so the next commit's tree
/// no longer names them and they stop growing the repository. Their old blobs
/// remain in history. Returns how many entries were dropped.
fn untrack_ledgers(
    root: &Path,
    index: &mut git2::Index,
    under: Option<&str>,
) -> Result<usize, git2::Error> {
    let prefix = under.map(|dir| format!("{}/", dir.trim_end_matches('/')));
    let tracked: Vec<PathBuf> = index
        .iter()
        .filter_map(|entry| String::from_utf8(entry.path).ok())
        .filter(|path| prefix.as_ref().is_none_or(|p| path.starts_with(p)))
        .filter(|path| {
            // The shape test is a string compare; only a shape match pays for
            // the file read.
            path.rsplit('/')
                .next()
                .is_some_and(ai_memory_core::log_ledger::is_log_ledger_path)
        })
        .map(PathBuf::from)
        .filter(|path| is_ledger_file(root, path))
        .collect();
    for path in &tracked {
        index.remove_path(path)?;
    }
    if !tracked.is_empty() {
        debug!(
            count = tracked.len(),
            "hook event ledgers dropped from the index; the files stay on disk"
        );
    }
    Ok(tracked.len())
}
/// Stage only `paths`: a file by path, a directory with its subtree, a
/// gone path by removing its entries. Does not write the index file.
fn stage_paths(
    root: &Path,
    index: &mut git2::Index,
    paths: &BTreeSet<PathBuf>,
) -> Result<usize, git2::Error> {
    for rel in paths {
        if rel
            .components()
            .any(|c| ai_memory_core::is_git_reserved_component(&c.as_os_str().to_string_lossy()))
        {
            warn!(path = %rel.display(), "skipping invalid git path with git-reserved component");
            continue;
        }
        let abs =
            match crate::confinement::tree_path(root, rel, crate::confinement::Prepare::Inspect) {
                Ok(path) => path,
                Err(error) => {
                    warn!(path = %rel.display(), %error, "skipping invalid reported git path");
                    continue;
                }
            };
        if abs.is_dir() {
            let spec = slash_path(rel);
            index.add_all(
                [spec.as_str()].iter(),
                IndexAddOption::DISABLE_PATHSPEC_MATCH,
                Some(&mut |path: &Path, _: &[u8]| {
                    i32::from(is_ledger_file(root, path) || is_in_flight_write(path))
                }),
            )?;
            untrack_ledgers(root, index, Some(&spec))?;
        } else if abs.is_file() {
            if is_ledger_file(root, rel) {
                if index.get_path(rel, 0).is_some() {
                    index.remove_path(rel)?;
                }
            } else if !is_in_flight_write(rel) {
                index.add_path(rel)?;
            }
        } else if index.get_path(rel, 0).is_some() {
            index.remove_path(rel)?;
        } else {
            // Gone and not a file in the index: a directory, or nothing.
            index.remove_dir(rel, 0)?;
        }
    }
    Ok(paths.len())
}

fn commit_open_error_with_fallback_on<F>(
    windows: bool,
    root: &Path,
    message: &str,
    error: git2::Error,
    fallback: F,
) -> WikiResult<Option<git2::Oid>>
where
    F: FnOnce(&Path, &str, git2::Error) -> WikiResult<Option<git2::Oid>>,
{
    if should_try_commit_cli_fallback_on(windows, &error) {
        validate_cli_fallback_root(root)?;
        fallback(root, message, error)
    } else {
        Err(map_git_err(error))
    }
}

fn should_try_commit_cli_fallback(error: &git2::Error) -> bool {
    should_try_commit_cli_fallback_on(cfg!(windows), error)
}

fn should_try_commit_cli_fallback_on(windows: bool, error: &git2::Error) -> bool {
    !matches!(error.code(), ErrorCode::Owner)
        && (matches!(error.code(), ErrorCode::NotFound)
            || windows
                && matches!(error.class(), git2::ErrorClass::Os)
                && error.message().contains("failed to resolve path"))
}

#[cfg(windows)]
fn commit_all_fallback(
    root: &Path,
    message: &str,
    original: git2::Error,
) -> WikiResult<Option<git2::Oid>> {
    validate_cli_fallback_root(root)?;
    warn!(error = %original, root = %root.display(), "libgit2 commit failed; trying git CLI fallback");
    stage_all_except_ledgers_cli(root)?;
    let diff = git_command(root)
        .args(["diff", "--cached", "--quiet", "--exit-code"])
        .status()
        .map_err(|error| {
            WikiError::Io(std::io::Error::other(format!(
                "{original}; git diff fallback failed to start: {error}"
            )))
        })?;
    if diff.success() {
        return Ok(None);
    }
    run_git(
        root,
        [
            "-c",
            "user.name=ai-memory",
            "-c",
            "user.email=ai-memory@local",
            "commit",
            "-q",
            "-m",
            message,
        ],
    )?;
    let out = git_output(root, ["rev-parse", "HEAD"])?;
    let oid = String::from_utf8_lossy(&out.stdout);
    git2::Oid::from_str(oid.trim())
        .map(Some)
        .map_err(map_git_err)
}

#[cfg(not(windows))]
fn commit_all_fallback(
    _root: &Path,
    _message: &str,
    original: git2::Error,
) -> WikiResult<Option<git2::Oid>> {
    Err(map_git_err(original))
}

#[cfg(windows)]
fn commit_count_fallback_checked(root: &Path) -> WikiResult<usize> {
    validate_cli_fallback_root(root)?;
    let out = git_output(root, ["rev-list", "--count", "HEAD"])?;
    String::from_utf8_lossy(&out.stdout)
        .trim()
        .parse()
        .map_err(|error| {
            WikiError::Io(std::io::Error::other(format!(
                "git fallback returned an invalid commit count: {error}"
            )))
        })
}

#[cfg(windows)]
fn recent_checkpoints_fallback(
    root: &Path,
    limit: usize,
    original: git2::Error,
) -> WikiResult<Vec<Checkpoint>> {
    validate_cli_fallback_root(root)?;
    warn!(error = %original, root = %root.display(), "libgit2 log failed; trying git CLI fallback");
    let limit = limit.to_string();
    let out = git_output(root, ["log", "-n", &limit, "--format=%H%x1f%s%x1f%ct"])?;
    let text = String::from_utf8_lossy(&out.stdout);
    let mut checkpoints = Vec::new();
    for line in text.lines() {
        let mut fields = line.split('\x1f');
        let (Some(oid), Some(summary), Some(time)) = (fields.next(), fields.next(), fields.next())
        else {
            continue;
        };
        checkpoints.push(Checkpoint {
            oid: oid.to_string(),
            summary: if summary.is_empty() {
                "(no summary)".to_string()
            } else {
                summary.to_string()
            },
            time: time.parse().unwrap_or_default(),
        });
    }
    Ok(checkpoints)
}

#[cfg(windows)]
fn file_at_rev_fallback(
    root: &Path,
    rev: &str,
    path: &Path,
    original: WikiError,
) -> WikiResult<Vec<u8>> {
    validate_cli_fallback_root(root)?;
    warn!(error = %original, root = %root.display(), "libgit2 show failed; trying git CLI fallback");
    let rel = slash_path(path);
    let spec = format!("{rev}:{rel}");
    let out = git_output(root, ["show", &spec])?;
    Ok(out.stdout)
}

fn init_repo(root: &Path) -> WikiResult<()> {
    match Repository::init(root) {
        Ok(_) => Ok(()),
        Err(error) => init_error_with_fallback_on(cfg!(windows), root, error, init_repo_fallback),
    }
}

fn init_error_with_fallback_on<F>(
    windows: bool,
    root: &Path,
    error: git2::Error,
    fallback: F,
) -> WikiResult<()>
where
    F: FnOnce(&Path, git2::Error) -> WikiResult<()>,
{
    if !windows {
        return Err(map_git_err(error));
    }
    validate_init_fallback_root(root)?;
    fallback(root, error)
}

fn validate_init_fallback_root(root: &Path) -> WikiResult<()> {
    crate::confinement::initialize_root(root)?;
    match std::fs::symlink_metadata(root.join(".git")) {
        Ok(_) => validate_cli_fallback_root(root),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(error) => Err(error.into()),
    }
}

#[cfg(windows)]
fn init_repo_fallback(root: &Path, original: git2::Error) -> WikiResult<()> {
    validate_init_fallback_root(root)?;
    warn!(error = %original, root = %root.display(), "libgit2 init failed; trying git CLI fallback");
    run_git(root, ["init", "-q"])?;
    validate_cli_fallback_root(root)
}

#[cfg(not(windows))]
fn init_repo_fallback(_root: &Path, original: git2::Error) -> WikiResult<()> {
    Err(map_git_err(original))
}

#[cfg(windows)]
fn run_git<const N: usize>(root: &Path, args: [&str; N]) -> WikiResult<()> {
    let status = git_command(root)
        .args(args)
        .status()
        .map_err(|error| WikiError::Io(std::io::Error::other(error.to_string())))?;
    if status.success() {
        Ok(())
    } else {
        Err(WikiError::Io(std::io::Error::other(format!(
            "git fallback exited with status {status}"
        ))))
    }
}

/// `git add -A` for the CLI fallback, leaving the hook event ledgers out the
/// way [`stage_working_tree`] does for libgit2.
///
/// Ledgers a past version committed are dropped from the index first, then
/// everything else is added with the ledgers as `exclude` pathspecs, so git
/// never reads a ledger into a blob. Pathspecs go through stdin because a
/// project with a ledger per month can name more files than a Windows command
/// line holds.
#[cfg(windows)]
fn stage_all_except_ledgers_cli(root: &Path) -> WikiResult<()> {
    let mut ledgers = Vec::new();
    collect_ledger_files(root, root, &mut ledgers)?;
    if ledgers.is_empty() {
        return run_git(root, ["add", "-A"]);
    }
    let pathspecs = |prefix: &str, first: &str| -> Vec<u8> {
        let mut input = first.as_bytes().to_vec();
        for ledger in &ledgers {
            input.extend_from_slice(prefix.as_bytes());
            input.extend_from_slice(slash_path(ledger).as_bytes());
            input.push(0);
        }
        input
    };
    run_git_with_stdin(
        root,
        [
            "rm",
            "--cached",
            // Without `--force` git refuses an entry whose staged content
            // matches neither HEAD nor the file (an old version staged an
            // append and never committed it), and that refusal would abort
            // the whole checkpoint. Only paths already validated as ledgers
            // are listed, and only their index entries go.
            "--force",
            "-q",
            "--ignore-unmatch",
            "--pathspec-from-file=-",
            "--pathspec-file-nul",
        ],
        &pathspecs(":(literal)", ""),
    )?;
    run_git_with_stdin(
        root,
        ["add", "-A", "--pathspec-from-file=-", "--pathspec-file-nul"],
        &pathspecs(":(exclude,literal)", ".\0"),
    )
}

/// Every ledger file under `dir`, relative to `root`, skipping `.git` and
/// symlinks.
#[cfg(windows)]
fn collect_ledger_files(root: &Path, dir: &Path, found: &mut Vec<PathBuf>) -> WikiResult<()> {
    for entry in std::fs::read_dir(dir)? {
        let entry = entry?;
        let file_type = entry.file_type()?;
        let path = entry.path();
        if file_type.is_dir() {
            if entry.file_name() != ".git" {
                collect_ledger_files(root, &path, found)?;
            }
        } else if file_type.is_file()
            && let Ok(rel) = path.strip_prefix(root)
            && is_ledger_file(root, rel)
        {
            found.push(rel.to_path_buf());
        }
    }
    Ok(())
}

#[cfg(windows)]
fn run_git_with_stdin<const N: usize>(
    root: &Path,
    args: [&str; N],
    input: &[u8],
) -> WikiResult<()> {
    use std::io::Write;
    use std::process::Stdio;
    let mut child = git_command(root)
        .args(args)
        .stdin(Stdio::piped())
        .spawn()
        .map_err(|error| WikiError::Io(std::io::Error::other(error.to_string())))?;
    if let Some(mut stdin) = child.stdin.take() {
        stdin.write_all(input)?;
    }
    let status = child.wait()?;
    if status.success() {
        Ok(())
    } else {
        Err(WikiError::Io(std::io::Error::other(format!(
            "git fallback exited with status {status}"
        ))))
    }
}

#[cfg(windows)]
fn git_output<const N: usize>(root: &Path, args: [&str; N]) -> WikiResult<std::process::Output> {
    let output = git_command(root)
        .args(args)
        .output()
        .map_err(|error| WikiError::Io(std::io::Error::other(error.to_string())))?;
    if output.status.success() {
        Ok(output)
    } else {
        Err(WikiError::Io(std::io::Error::other(format!(
            "git fallback exited with status {}: {}",
            output.status,
            String::from_utf8_lossy(&output.stderr)
        ))))
    }
}

fn map_git_err(e: git2::Error) -> WikiError {
    // An owner-check failure (`code=Owner`, CVE-2022-24765 dubious-ownership
    // guard) is kept as a distinct variant so startup can log it at ERROR with
    // an actionable fix instead of burying it in a generic WARN. Everything
    // else stays an opaque I/O error, matching prior behaviour.
    if matches!(e.code(), ErrorCode::Owner) {
        warn!(error = %e, "libgit2 wiki owner-validation error");
        return WikiError::GitOwner(e.to_string());
    }
    warn!(error = %e, "libgit2 error");
    WikiError::Io(std::io::Error::other(e.to_string()))
}

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

    fn tempdir() -> TempDir {
        tempfile::Builder::new()
            .prefix("ai-memory-")
            .tempdir()
            .unwrap()
    }

    #[test]
    fn commit_count_public_api_remains_a_plain_usize() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let count: usize = adapter.commit_count();
        assert_eq!(count, 0);
    }

    #[test]
    fn windows_commit_fallback_accepts_established_eligible_errors() {
        let eligible = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "failed to resolve path 'C:\\wiki\\.git'",
        );
        assert!(should_try_commit_cli_fallback_on(true, &eligible));
        assert!(!should_try_commit_cli_fallback_on(false, &eligible));

        let wrong_class = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Repository,
            "failed to resolve path 'C:\\wiki\\.git'",
        );
        assert!(!should_try_commit_cli_fallback_on(true, &wrong_class));
        let not_found = git2::Error::new(
            ErrorCode::NotFound,
            git2::ErrorClass::Repository,
            "not found",
        );
        assert!(should_try_commit_cli_fallback_on(true, &not_found));
        assert!(should_try_commit_cli_fallback_on(false, &not_found));

        let owner = git2::Error::new(
            ErrorCode::Owner,
            git2::ErrorClass::Os,
            "failed to resolve path 'C:\\wiki\\.git'",
        );
        assert!(!should_try_commit_cli_fallback_on(true, &owner));
        let wrong_message = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "repository is corrupt",
        );
        assert!(!should_try_commit_cli_fallback_on(true, &wrong_message));
    }

    #[test]
    fn public_filesystem_wrappers_preserve_io_signatures_and_non_not_found_confinement() {
        fn assert_signatures(
            append: fn(&GitAdapter, &Path, &[u8]) -> std::io::Result<()>,
            rename: fn(&GitAdapter, &Path, &Path) -> std::io::Result<()>,
            remove_file: fn(&GitAdapter, &Path) -> std::io::Result<()>,
            remove_dir_all: fn(&GitAdapter, &Path) -> std::io::Result<()>,
        ) {
            let _ = (append, rename, remove_file, remove_dir_all);
        }
        assert_signatures(
            GitAdapter::append,
            GitAdapter::rename,
            GitAdapter::remove_file,
            GitAdapter::remove_dir_all,
        );

        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let outside = tmp.path().join("outside");
        std::fs::create_dir(&outside).unwrap();
        let linked = root.join("linked");
        if !link_directory(&outside, &linked) {
            return;
        }
        let error = adapter.append(&linked.join("log.md"), b"x").unwrap_err();
        assert_eq!(error.kind(), std::io::ErrorKind::PermissionDenied);
    }

    #[test]
    fn windows_init_error_dispatches_fallback_after_root_preflight() {
        use std::sync::atomic::{AtomicBool, Ordering};

        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        std::fs::create_dir(&root).unwrap();
        let called = AtomicBool::new(false);
        let error = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "failed to initialize repository",
        );

        init_error_with_fallback_on(true, &root, error, |validated, _| {
            assert_eq!(validated, root);
            called.store(true, Ordering::Relaxed);
            Ok(())
        })
        .unwrap();
        assert!(called.load(Ordering::Relaxed));
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn invalid_root_never_reaches_init_fallback() {
        use std::sync::atomic::{AtomicBool, Ordering};

        let tmp = tempdir();
        let outside = tmp.path().join("outside");
        let root = tmp.path().join("wiki");
        std::fs::create_dir(&outside).unwrap();
        if !link_directory(&outside, &root) {
            return;
        }
        let called = AtomicBool::new(false);
        let error = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "failed to initialize repository",
        );

        assert!(matches!(
            init_error_with_fallback_on(true, &root, error, |_, _| {
                called.store(true, Ordering::Relaxed);
                Ok(())
            }),
            Err(WikiError::Confinement { .. })
        ));
        assert!(!called.load(Ordering::Relaxed));
    }

    #[test]
    fn init_is_idempotent_and_creates_dotgit() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        assert!(root.join(".git").is_dir());
        let adapter2 = GitAdapter::open_or_init(&root).unwrap();
        assert_eq!(adapter.commit_count(), 0);
        assert!(adapter2.recent_checkpoints(1).unwrap().is_empty());
    }

    #[cfg(unix)]
    fn link_directory(target: &Path, link: &Path) -> bool {
        std::os::unix::fs::symlink(target, link).unwrap();
        true
    }

    #[cfg(windows)]
    fn link_directory(target: &Path, link: &Path) -> bool {
        match std::os::windows::fs::symlink_dir(target, link) {
            Ok(()) => true,
            Err(error) if error.raw_os_error() == Some(1314) => {
                eprintln!("skipping .git reparse assertion: Windows privilege unavailable");
                false
            }
            Err(error) => panic!("failed to create .git directory link: {error}"),
        }
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn git_metadata_link_is_refused_without_touching_external_repository() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        std::fs::create_dir(&root).unwrap();
        let external = tmp.path().join("external-git");
        Repository::init_bare(&external).unwrap();
        let before = std::fs::read(external.join("HEAD")).unwrap();
        if !link_directory(&external, &root.join(".git")) {
            return;
        }

        assert!(matches!(
            GitAdapter::open_or_init(&root),
            Err(WikiError::Confinement { .. })
        ));
        assert_eq!(std::fs::read(external.join("HEAD")).unwrap(), before);
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn eligible_windows_open_error_dispatches_the_fallback_after_validation() {
        use std::sync::atomic::{AtomicBool, Ordering};

        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let called = AtomicBool::new(false);
        let error = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "failed to resolve path 'C:\\wiki\\.git'",
        );

        assert!(
            commit_open_error_with_fallback_on(
                true,
                &adapter.root,
                "fallback",
                error,
                |root, message, _| {
                    assert_eq!(root, adapter.root);
                    assert_eq!(message, "fallback");
                    called.store(true, Ordering::Relaxed);
                    Ok(None)
                },
            )
            .unwrap()
            .is_none()
        );
        assert!(called.load(Ordering::Relaxed));
    }

    fn assert_eligible_fallback_is_refused(root: &Path) {
        use std::sync::atomic::{AtomicBool, Ordering};

        let called = AtomicBool::new(false);
        let error = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "failed to resolve path 'C:\\wiki\\.git'",
        );
        assert!(
            commit_open_error_with_fallback_on(true, root, "refused", error, |_, _, _| {
                called.store(true, Ordering::Relaxed);
                Ok(None)
            },)
            .is_err()
        );
        assert!(!called.load(Ordering::Relaxed));
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn linked_git_metadata_never_reaches_commit_fallback() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        adapter.close();
        let original = root.join(".git-original");
        std::fs::rename(root.join(".git"), &original).unwrap();
        if !link_directory(&original, &root.join(".git")) {
            return;
        }

        assert_eligible_fallback_is_refused(&adapter.root);
    }

    #[test]
    fn gitfile_metadata_never_reaches_commit_fallback() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        adapter.close();
        let original = root.join(".git-original");
        std::fs::rename(root.join(".git"), &original).unwrap();
        std::fs::write(
            root.join(".git"),
            format!("gitdir: {}\n", original.display()),
        )
        .unwrap();

        assert_eligible_fallback_is_refused(&adapter.root);
    }

    #[test]
    fn out_of_root_worktree_never_reaches_commit_fallback() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let outside = tmp.path().join("outside");
        std::fs::create_dir(&outside).unwrap();
        Repository::open(&root)
            .unwrap()
            .config()
            .unwrap()
            .set_str("core.worktree", outside.to_str().unwrap())
            .unwrap();

        assert_eligible_fallback_is_refused(&adapter.root);
    }

    #[test]
    fn fallback_preflight_refuses_invalid_git_metadata() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        std::fs::write(root.join(".git/commondir"), "../outside\n").unwrap();

        assert!(matches!(
            validate_cli_fallback_root(&adapter.root),
            Err(WikiError::Confinement { .. })
        ));
    }

    #[test]
    fn fallback_resolved_paths_must_match_the_validated_repository() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let git_dir = root.join(".git");
        let outside = tmp.path().join("outside");
        std::fs::create_dir(&outside).unwrap();

        assert!(
            validate_resolved_repository_paths(&root, &git_dir, &root, &git_dir, &git_dir,).is_ok()
        );
        for (worktree, resolved_git_dir, common_dir) in [
            (outside.as_path(), git_dir.as_path(), git_dir.as_path()),
            (root.as_path(), outside.as_path(), git_dir.as_path()),
            (root.as_path(), git_dir.as_path(), outside.as_path()),
        ] {
            assert!(matches!(
                validate_resolved_repository_paths(
                    &root,
                    &git_dir,
                    worktree,
                    resolved_git_dir,
                    common_dir,
                ),
                Err(WikiError::Confinement { .. })
            ));
        }
        assert_eq!(adapter.root(), root);
    }

    #[test]
    fn gitfile_redirect_outside_is_refused_without_touching_target() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        std::fs::create_dir(&root).unwrap();
        let external = tmp.path().join("external-git");
        Repository::init_bare(&external).unwrap();
        let before = std::fs::read(external.join("HEAD")).unwrap();
        std::fs::write(
            root.join(".git"),
            format!("gitdir: {}\n", external.display()),
        )
        .unwrap();

        assert!(matches!(
            GitAdapter::open_or_init(&root),
            Err(WikiError::Confinement { .. })
        ));
        assert_eq!(std::fs::read(external.join("HEAD")).unwrap(), before);
    }

    #[test]
    fn git_metadata_redirect_files_are_refused_before_repository_open() {
        for relative in [
            "commondir",
            "objects/info/alternates",
            "objects/info/http-alternates",
        ] {
            let tmp = tempdir();
            let root = tmp.path().join("wiki");
            let adapter = GitAdapter::open_or_init(&root).unwrap();
            let redirect = root.join(".git").join(relative);
            std::fs::create_dir_all(redirect.parent().unwrap()).unwrap();
            std::fs::write(&redirect, "../outside\n").unwrap();

            assert!(matches!(
                adapter.recent_checkpoints(0),
                Err(WikiError::Confinement { .. })
            ));
        }
    }

    #[test]
    fn configured_worktree_outside_the_wiki_root_is_refused() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let external = tmp.path().join("external-worktree");
        std::fs::create_dir(&external).unwrap();
        std::fs::write(external.join("canary"), "outside canary").unwrap();
        let repo = Repository::init(&root).unwrap();
        repo.config()
            .unwrap()
            .set_str("core.worktree", external.to_str().unwrap())
            .unwrap();
        drop(repo);

        assert!(matches!(
            GitAdapter::open_or_init(&root),
            Err(WikiError::Confinement { .. })
        ));
        assert_eq!(
            std::fs::read_to_string(external.join("canary")).unwrap(),
            "outside canary"
        );
    }

    #[cfg(any(unix, windows))]
    #[test]
    fn checkpoint_and_revision_reads_refuse_a_replaced_git_directory() {
        let (_tmp, root, adapter) = committed(&[("a.md", "one")]);
        adapter.close();
        let original = root.join(".git-original");
        std::fs::rename(root.join(".git"), &original).unwrap();
        let external = root.parent().unwrap().join("external-git");
        Repository::init_bare(&external).unwrap();
        let before = std::fs::read(external.join("HEAD")).unwrap();
        if !link_directory(&external, &root.join(".git")) {
            return;
        }

        assert!(matches!(
            adapter.commit_all("refused"),
            Err(WikiError::Confinement { .. })
        ));
        assert!(matches!(
            adapter.recent_checkpoints(1),
            Err(WikiError::Confinement { .. })
        ));
        assert!(matches!(
            adapter.file_at_rev("HEAD", Path::new("a.md")),
            Err(WikiError::Confinement { .. })
        ));
        assert!(matches!(
            adapter.commit_count_checked(),
            Err(WikiError::Confinement { .. })
        ));
        assert_eq!(adapter.commit_count(), 0);
        assert_eq!(std::fs::read(external.join("HEAD")).unwrap(), before);
    }

    #[test]
    fn path_checkpoints_lists_changes_and_deletion_and_stops_at_the_walk_cap() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        std::fs::write(root.join("page.md"), "v1").unwrap();
        adapter.commit_all("write v1").unwrap();
        std::fs::write(root.join("page.md"), "v2").unwrap();
        adapter.commit_all("write v2").unwrap();
        std::fs::remove_file(root.join("page.md")).unwrap();
        adapter.commit_all("delete").unwrap();
        for i in 0..3 {
            std::fs::write(root.join("other.md"), format!("o{i}")).unwrap();
            adapter.commit_all("unrelated").unwrap();
        }
        let summaries = |hits: Vec<Checkpoint>| -> Vec<String> {
            hits.into_iter().map(|c| c.summary).collect()
        };

        let all = adapter
            .path_checkpoints(Path::new("page.md"), 10, 100)
            .unwrap();
        assert_eq!(summaries(all), ["delete", "write v2", "write v1"]);
        let limited = adapter
            .path_checkpoints(Path::new("page.md"), 1, 100)
            .unwrap();
        assert_eq!(summaries(limited), ["delete"]);
        // Three unrelated commits sit on top: a walk of four sees only the
        // delete, a walk of three sees nothing.
        let capped = adapter
            .path_checkpoints(Path::new("page.md"), 10, 4)
            .unwrap();
        assert_eq!(summaries(capped), ["delete"]);
        assert!(
            adapter
                .path_checkpoints(Path::new("page.md"), 10, 3)
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn commit_all_returns_none_when_clean_some_when_dirty() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        // No changes: returns None.
        assert!(adapter.commit_all("initial").unwrap().is_none());

        // Add a file -> commit -> Some(oid).
        std::fs::write(root.join("foo.md"), "hello").unwrap();
        let oid = adapter.commit_all("add foo").unwrap();
        assert!(oid.is_some());

        // Re-commit with no changes -> None again.
        assert!(adapter.commit_all("no changes").unwrap().is_none());
        assert_eq!(adapter.commit_count(), 1);
    }

    /// #594 as it happens: the index trusts a cached blob OID whose object
    /// is gone from the store. Stat-cache staging cannot see that, so the
    /// tree write refuses it and the commit must recover by re-hashing.
    #[test]
    fn commit_all_recovers_when_the_index_names_a_missing_blob() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        std::fs::write(root.join("cached.md"), "content the index remembers").unwrap();
        adapter.commit_all("first").unwrap();

        // Remove the blob the index entry points at. The file on disk is
        // untouched, so its size and mtime still match the cached entry.
        let blob = {
            let repo = Repository::open(&root).unwrap();
            let index = repo.index().unwrap();
            index.get_path(Path::new("cached.md"), 0).unwrap().id
        };
        let hex = blob.to_string();
        let object = root
            .join(".git")
            .join("objects")
            .join(&hex[..2])
            .join(&hex[2..]);
        std::fs::remove_file(&object).expect("a fresh repo stores the blob loose");

        std::fs::write(root.join("other.md"), "a second file").unwrap();
        let oid = adapter
            .commit_all("second")
            .expect("the commit recovers by re-hashing the tree");
        assert!(oid.is_some());
        assert!(object.exists(), "the re-hash wrote the blob back");
        assert_eq!(
            adapter.file_at_rev("HEAD", Path::new("cached.md")).unwrap(),
            b"content the index remembers"
        );
        assert_eq!(adapter.commit_count(), 2);
    }

    /// The cost of a commit is what changed, not the size of the wiki: after
    /// a hundred files are committed, changing one must stage one path.
    #[test]
    fn commit_stages_only_what_changed_since_the_last_one() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        for i in 0..100 {
            std::fs::write(root.join(format!("page-{i}.md")), format!("page {i}")).unwrap();
        }
        adapter.commit_all("hundred pages").unwrap();

        let staged = |root: &Path| {
            let repo = Repository::open(root).unwrap();
            let mut index = repo.index().unwrap();
            let touched = stage_working_tree(root, &mut index).unwrap().len();
            index.write().unwrap();
            touched
        };
        assert_eq!(staged(&root), 0, "a clean tree stages nothing");
        std::fs::write(root.join("page-7.md"), "page 7, revised").unwrap();
        assert_eq!(staged(&root), 1, "one changed file stages one path");
        std::fs::remove_file(root.join("page-8.md")).unwrap();
        std::fs::write(root.join("page-100.md"), "new page").unwrap();
        assert_eq!(staged(&root), 2, "a delete and an add stage two paths");
        assert!(adapter.commit_all("edits").unwrap().is_some());
        assert_eq!(adapter.commit_count(), 2);
    }

    fn head_blob(adapter: &GitAdapter, rel: &str) -> Option<String> {
        adapter
            .file_at_rev("HEAD", Path::new(rel))
            .ok()
            .map(|bytes| String::from_utf8_lossy(&bytes).into_owned())
    }

    fn write(root: &Path, rel: &str, body: &str) {
        let path = root.join(rel);
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(path, body).unwrap();
    }

    /// `files` committed by the fixture's own walk.
    fn committed(files: &[(&str, &str)]) -> (TempDir, PathBuf, GitAdapter) {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        for (rel, body) in files {
            write(&root, rel, body);
        }
        adapter.commit_all("initial").unwrap();
        (tmp, root, adapter)
    }

    /// `apply_batch` keeps one `.ai-memory-tmp.*` staging file per page on disk
    /// across an await, and `commit_all` takes only the commit lock — so a
    /// sweep landing in that window must not capture a write in flight.
    #[test]
    fn a_sweep_never_stages_an_in_flight_atomic_write() {
        let (_tmp, root, adapter) = committed(&[("ws/proj/a.md", "a")]);
        write(&root, "ws/proj/b.md", "b");
        write(
            &root,
            "ws/proj/.ai-memory-tmp.aB3x9Q",
            "a body still being written",
        );
        write(
            &root,
            "ws/proj/.ai-memory-delete.b.md",
            "a page parked for deletion",
        );

        assert!(
            adapter
                .commit_all("sweep with writes in flight")
                .unwrap()
                .is_some()
        );

        assert_eq!(head_blob(&adapter, "ws/proj/b.md").as_deref(), Some("b"));
        assert_eq!(head_blob(&adapter, "ws/proj/.ai-memory-tmp.aB3x9Q"), None);
        assert_eq!(head_blob(&adapter, "ws/proj/.ai-memory-delete.b.md"), None);
    }

    /// The same for a path-scoped commit, whose directory pathspec reaches
    /// `stage_paths`' own `add_all` rather than the sweep's.
    #[test]
    fn a_path_scoped_commit_never_stages_an_in_flight_atomic_write() {
        let (_tmp, root, adapter) = committed(&[("ws/proj/a.md", "a")]);
        write(&root, "ws/proj/c.md", "c");
        write(
            &root,
            "ws/proj/.ai-memory-tmp.cD4y0R",
            "a body still being written",
        );
        adapter.mark_written(&root.join("ws/proj"));

        adapter.commit_all("scoped with a write in flight").unwrap();

        assert_eq!(head_blob(&adapter, "ws/proj/c.md").as_deref(), Some("c"));
        assert_eq!(head_blob(&adapter, "ws/proj/.ai-memory-tmp.cD4y0R"), None);
    }

    /// `quarantine_file` and `move_session_page` park a page under a staging
    /// name with `rename_checked`, which reports that exact path, so the
    /// reported-file branch of `stage_paths` must skip it as well.
    #[test]
    fn a_reported_staging_file_is_never_staged() {
        let (_tmp, root, adapter) = committed(&[("ws/proj/a.md", "a")]);
        let parked = [
            "ws/proj/.ai-memory-delete.Xy12Ab",
            "ws/proj/.ai-memory-tmp.move-session.s1.md",
        ];
        for rel in parked {
            write(&root, rel, "a page between two renames");
            adapter.mark_written(&root.join(rel));
        }
        write(&root, "ws/proj/c.md", "c");
        adapter.mark_written(&root.join("ws/proj/c.md"));

        adapter.commit_all("scoped with pages parked").unwrap();

        assert_eq!(head_blob(&adapter, "ws/proj/c.md").as_deref(), Some("c"));
        for rel in parked {
            assert_eq!(head_blob(&adapter, rel), None, "{rel} was committed");
        }
    }

    #[test]
    fn a_commit_stages_the_reported_paths_only() {
        let (_tmp, root, adapter) = committed(&[("page-7.md", "page 7"), ("page-8.md", "page 8")]);
        write(&root, "page-7.md", "seven, revised");
        write(&root, "page-8.md", "eight, revised");
        adapter.mark_written(&root.join("page-7.md"));
        assert_eq!(adapter.written_paths(), vec![PathBuf::from("page-7.md")]);
        assert!(adapter.commit_all("seven").unwrap().is_some());
        assert_eq!(
            head_blob(&adapter, "page-7.md").as_deref(),
            Some("seven, revised")
        );
        assert_eq!(
            head_blob(&adapter, "page-8.md").as_deref(),
            Some("page 8"),
            "the unreported edit is not in this commit"
        );
        assert!(adapter.written_paths().is_empty(), "the report is consumed");

        // Nothing reported: the tree is walked and the edit lands.
        assert!(adapter.commit_all("sweep").unwrap().is_some());
        assert_eq!(
            head_blob(&adapter, "page-8.md").as_deref(),
            Some("eight, revised")
        );
    }

    #[test]
    fn reported_deletions_and_directories_are_staged() {
        let (_tmp, root, adapter) =
            committed(&[("ws/proj/sessions/a.md", "a"), ("gone.md", "gone")]);
        std::fs::remove_file(root.join("gone.md")).unwrap();
        write(&root, "ws/proj/sessions/b.md", "b");
        adapter.mark_written(Path::new("gone.md"));
        adapter.mark_written(&root.join("ws/proj/sessions"));
        assert!(adapter.commit_all("delete and add").unwrap().is_some());
        assert!(head_blob(&adapter, "gone.md").is_none());
        assert_eq!(
            head_blob(&adapter, "ws/proj/sessions/b.md").as_deref(),
            Some("b")
        );
    }

    #[test]
    fn path_scoped_staging_refuses_traversal_reports() {
        let (tmp, _root, adapter) = committed(&[("page.md", "page")]);
        std::fs::write(tmp.path().join("outside.md"), "outside").unwrap();
        std::fs::write(tmp.path().join("log-2026-09.md"), LEDGER_BODY).unwrap();

        adapter.mark_written(Path::new("../outside.md"));
        adapter.mark_written(Path::new("../log-2026-09.md"));

        assert!(adapter.commit_all("invalid reports").unwrap().is_none());
        assert_eq!(head_blob(&adapter, "page.md").as_deref(), Some("page"));
    }

    #[test]
    fn the_repository_directory_is_never_reported() {
        let (_tmp, root, adapter) = committed(&[("a.md", "a")]);
        adapter.mark_written(Path::new(".git/logs/HEAD"));
        adapter.mark_written(&root.join(".git/index"));
        adapter.mark_written(Path::new(".git"));
        adapter.mark_written(Path::new("ws/proj/.git/config"));
        adapter.mark_written(&root.join("ws/proj/.git/hooks/pre-commit"));
        adapter.mark_written(Path::new("ws/proj/git~1/config"));
        assert!(adapter.written_paths().is_empty());
    }

    const LEDGER_BODY: &str = "## [2026-09-05T00:00:00Z] tool Bash: cargo test\n";
    const PROSE_BODY: &str = "# Log\n\nAn ordinary page named like a ledger.\n";

    /// Whether the index names `rel`, from a fresh read of the index file.
    fn indexed(root: &Path, rel: &str) -> bool {
        let repo = Repository::open(root).unwrap();
        let index = repo.index().unwrap();
        index.get_path(Path::new(rel), 0).is_some()
    }

    /// Path-scoped staging (the commit after the first walk): a ledger a past
    /// version tracked is dropped from the index when it is reported, by file
    /// or through its directory, and the file stays on disk. Ordinary files in
    /// the same call, including a page wearing a ledger's name, are staged.
    #[test]
    fn path_staging_untracks_a_ledger_and_keeps_a_page_wearing_its_name() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        write(&root, "p/log-2026-09.md", LEDGER_BODY);
        write(&root, "q/log-2026-09.md", LEDGER_BODY);
        write(&root, "r/log-2026-09.md", PROSE_BODY);
        let repo = Repository::open(&root).unwrap();
        let mut index = repo.index().unwrap();
        for rel in ["p/log-2026-09.md", "q/log-2026-09.md", "r/log-2026-09.md"] {
            index.add_path(Path::new(rel)).unwrap();
        }
        index.write().unwrap();
        drop(adapter);

        write(
            &root,
            "p/log-2026-09.md",
            &format!("{LEDGER_BODY}{LEDGER_BODY}"),
        );
        write(&root, "r/log-2026-09.md", &format!("{PROSE_BODY}edited\n"));
        write(&root, "q/other.md", "page\n");
        // Never tracked, reported through its directory: it must not even be
        // read into a blob.
        let fresh = format!("{LEDGER_BODY}## [2026-09-06T00:00:00Z] stop\n");
        write(&root, "s/log-2026-08.md", &fresh);
        let mut index = repo.index().unwrap();
        // `p` is reported by file, `q` and `s` through their directories.
        let paths: BTreeSet<PathBuf> = ["p/log-2026-09.md", "q", "r/log-2026-09.md", "s"]
            .iter()
            .map(PathBuf::from)
            .collect();
        stage_paths(&root, &mut index, &paths).unwrap();
        index.write().unwrap();

        assert!(!indexed(&root, "p/log-2026-09.md"), "file report");
        assert!(!indexed(&root, "q/log-2026-09.md"), "directory report");
        assert!(
            !indexed(&root, "s/log-2026-08.md"),
            "untracked, by directory"
        );
        assert!(
            !repo
                .odb()
                .unwrap()
                .exists(git2::Oid::hash_object(ObjectType::Blob, fresh.as_bytes()).unwrap()),
            "a ledger under a reported directory was hashed into git"
        );
        assert!(indexed(&root, "q/other.md"), "control: the page beside it");
        assert!(indexed(&root, "r/log-2026-09.md"), "control: a page");
        assert_eq!(
            std::fs::read_to_string(root.join("p/log-2026-09.md")).unwrap(),
            format!("{LEDGER_BODY}{LEDGER_BODY}"),
            "the file on disk is untouched"
        );
        assert_eq!(
            std::fs::read_to_string(root.join("q/log-2026-09.md")).unwrap(),
            LEDGER_BODY
        );
    }

    /// The CLI fallback (Windows only, when libgit2 cannot open the repo)
    /// must leave ledgers out as well, and must never read one into a blob.
    #[cfg(windows)]
    #[test]
    fn cli_fallback_commit_leaves_ledgers_out_and_untracks_a_tracked_one() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        // A repo-local setting beats a contributor's global `commit.gpgsign`.
        Repository::open(&root)
            .unwrap()
            .config()
            .unwrap()
            .set_bool("commit.gpgsign", false)
            .unwrap();
        write(&root, "p/log-2026-07.md", LEDGER_BODY);
        run_git(&root, ["add", "p/log-2026-07.md"]).unwrap();
        run_git(
            &root,
            [
                "-c",
                "user.name=fixture",
                "-c",
                "user.email=fixture@local",
                "commit",
                "-q",
                "--no-gpg-sign",
                "-m",
                "fixture: tracked by an earlier version",
            ],
        )
        .unwrap();
        // Content no other file or commit holds, so a blob for it can only come
        // from staging this file.
        let new_ledger = format!("{LEDGER_BODY}## [2026-09-06T00:00:00Z] stop\n");
        write(&root, "p/log-2026-09.md", &new_ledger);
        write(&root, "p/log.md", PROSE_BODY);
        write(&root, "p/page.md", "page\n");

        let oid = commit_all_fallback(&root, "fallback", git2::Error::from_str("forced"))
            .unwrap()
            .expect("the page is new");

        let repo = Repository::open(&root).unwrap();
        let tree = repo.find_commit(oid).unwrap().tree().unwrap();
        assert!(tree.get_path(Path::new("p/page.md")).is_ok());
        assert!(tree.get_path(Path::new("p/log.md")).is_ok(), "a page");
        assert!(tree.get_path(Path::new("p/log-2026-09.md")).is_err());
        assert!(
            tree.get_path(Path::new("p/log-2026-07.md")).is_err(),
            "the tracked ledger was untracked"
        );
        assert!(root.join("p/log-2026-07.md").is_file(), "and kept on disk");
        let unseen = git2::Oid::hash_object(ObjectType::Blob, new_ledger.as_bytes()).unwrap();
        assert!(
            !repo.odb().unwrap().exists(unseen),
            "git read the new ledger into a blob"
        );
        drop(adapter);
    }

    /// The state an older version could leave behind: it staged an append to a
    /// ledger and never committed it, and the hook appended again after that.
    /// HEAD, the index and the file then hold three different contents, which
    /// plain `git rm --cached` refuses; that refusal must not abort the
    /// checkpoint, which still has ordinary pages to save.
    #[cfg(windows)]
    #[test]
    fn cli_fallback_untracks_a_ledger_whose_index_matches_neither_head_nor_disk() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        Repository::open(&root)
            .unwrap()
            .config()
            .unwrap()
            .set_bool("commit.gpgsign", false)
            .unwrap();
        let ledger = "p/log-2026-09.md";
        let version_a = LEDGER_BODY.to_string();
        let version_b = format!(
            "{version_a}## [2026-09-06T00:00:00Z] stop
"
        );
        let version_c = format!(
            "{version_b}## [2026-09-07T00:00:00Z] start
"
        );

        write(&root, ledger, &version_a);
        run_git(&root, ["add", ledger]).unwrap();
        run_git(
            &root,
            [
                "-c",
                "user.name=fixture",
                "-c",
                "user.email=fixture@local",
                "commit",
                "-q",
                "--no-gpg-sign",
                "-m",
                "fixture: HEAD holds version A",
            ],
        )
        .unwrap();
        write(&root, ledger, &version_b);
        run_git(&root, ["add", ledger]).unwrap();
        write(&root, ledger, &version_c);
        write(
            &root,
            "p/page.md",
            "page
",
        );

        let oid = commit_all_fallback(&root, "fallback", git2::Error::from_str("forced"))
            .expect("the unforced removal aborted the whole checkpoint")
            .expect("the page is new");

        let repo = Repository::open(&root).unwrap();
        let tree = repo.find_commit(oid).unwrap().tree().unwrap();
        assert!(
            tree.get_path(Path::new("p/page.md")).is_ok(),
            "the ordinary page was not committed"
        );
        assert!(
            tree.get_path(Path::new(ledger)).is_err(),
            "the ledger is still in the commit"
        );
        assert!(!indexed(&root, ledger), "the ledger is still in the index");
        assert_eq!(
            std::fs::read_to_string(root.join(ledger)).unwrap(),
            version_c,
            "the file on disk was changed"
        );
        drop(adapter);
    }

    #[test]
    fn the_adapters_writes_report_their_paths() {
        let (_tmp, root, adapter) = committed(&[("a.md", "a")]);
        adapter.write_atomic(&root.join("b.md"), b"b").unwrap();
        adapter.append(&root.join("log.md"), b"line\n").unwrap();
        adapter
            .rename(&root.join("a.md"), &root.join("c.md"))
            .unwrap();
        adapter.remove_file(&root.join("b.md")).unwrap();
        let reported: Vec<PathBuf> = adapter.written_paths();
        assert_eq!(
            reported,
            ["a.md", "b.md", "c.md", "log.md"]
                .map(PathBuf::from)
                .to_vec()
        );
        adapter.commit_all("writes").unwrap();
        assert!(head_blob(&adapter, "a.md").is_none());
        assert!(head_blob(&adapter, "b.md").is_none());
        assert_eq!(head_blob(&adapter, "c.md").as_deref(), Some("a"));
        assert_eq!(head_blob(&adapter, "log.md").as_deref(), Some("line\n"));
    }

    #[test]
    fn the_tree_is_swept_on_the_interval_and_when_a_report_is_untrusted() {
        let (tmp, root, adapter) = committed(&[("tracked.md", "0"), ("bypassed.md", "old")]);
        write(&root, "bypassed.md", "edited behind the wiki");
        write(&root, "tracked.md", "1");
        adapter.mark_written(Path::new("tracked.md"));
        adapter.commit_all("session 1").unwrap();
        assert_eq!(
            head_blob(&adapter, "bypassed.md").as_deref(),
            Some("old"),
            "a path-scoped commit within the interval leaves the bypassed edit"
        );

        adapter.age_last_walk();
        write(&root, "tracked.md", "2");
        adapter.mark_written(Path::new("tracked.md"));
        adapter.commit_all("session 2").unwrap();
        assert_eq!(
            head_blob(&adapter, "bypassed.md").as_deref(),
            Some("edited behind the wiki"),
            "the sweep walks the tree"
        );

        write(&root, "bypassed.md", "edited again");
        write(&root, "tracked.md", "x");
        adapter.mark_written(Path::new("tracked.md"));
        adapter.mark_written(tmp.path().join("elsewhere.md").as_path());
        adapter.commit_all("untrusted report").unwrap();
        assert_eq!(
            head_blob(&adapter, "bypassed.md").as_deref(),
            Some("edited again"),
            "a report naming a path outside the root walks the tree"
        );
    }

    /// A directory report covers its subtree.
    #[test]
    fn the_sweep_names_the_writes_nobody_reported() {
        let (_tmp, root, adapter) = committed(&[("ws/proj/a.md", "a")]);
        assert_eq!(adapter.sweep_snapshot(), SweepSnapshot::default());

        write(&root, "ws/proj/a.md", "a2");
        write(&root, "ws/proj/b.md", "nobody reported this");
        adapter.mark_written(Path::new("ws/proj/a.md"));
        adapter.age_last_walk();
        adapter.commit_all("sweep").unwrap();
        assert_eq!(
            adapter.sweep_snapshot(),
            SweepSnapshot {
                unreported_writes: 1,
                last_unreported: vec![PathBuf::from("ws/proj/b.md")],
            }
        );

        write(&root, "ws/proj/c.md", "c");
        adapter.mark_written(Path::new("ws/proj"));
        adapter.age_last_walk();
        adapter.commit_all("sweep again").unwrap();
        let snapshot = adapter.sweep_snapshot();
        assert_eq!(snapshot.unreported_writes, 1, "the count is cumulative");
        assert!(snapshot.last_unreported.is_empty());
    }

    #[test]
    fn concurrent_appends_do_not_fail_a_commit() {
        let (_tmp, root, adapter) = committed(&[("ws/proj/log.md", "")]);
        let ledger = root.join("ws/proj/log.md");
        const ROUNDS: usize = 8;
        const WRITERS: usize = 3;
        // Two barrier waits per round make every append race a commit attempt,
        // while bounding the fsync-heavy work independently of mutex fairness.
        let round = Arc::new(std::sync::Barrier::new(WRITERS + 1));
        let writers: Vec<_> = (0..3)
            .map(|_| {
                let adapter = adapter.clone();
                let ledger = ledger.clone();
                let round = Arc::clone(&round);
                std::thread::spawn(move || {
                    let mut results = Vec::with_capacity(ROUNDS);
                    for _ in 0..ROUNDS {
                        round.wait();
                        results.push(adapter.append(&ledger, b"2026-09-08T00:00:00Z stop x\n"));
                        round.wait();
                    }
                    for result in results {
                        result.unwrap();
                    }
                })
            })
            .collect();
        let mut commits = Vec::with_capacity(ROUNDS);
        for i in 0..ROUNDS {
            round.wait();
            adapter.mark_written(&ledger);
            commits.push((i, adapter.commit_all(&format!("session {i}"))));
            round.wait();
        }
        for w in writers {
            w.join().unwrap();
        }
        for (i, result) in commits {
            result.unwrap_or_else(|e| panic!("commit {i} failed: {e}"));
        }
        assert!(adapter.commit_count() >= 2);
    }

    /// Not a test: run by hand with `--ignored --nocapture`.
    #[test]
    #[ignore]
    fn measure_commit_cost_on_a_large_tree() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let projects = 120usize;
        let per_project = 150usize;
        for p in 0..projects {
            let dir = root.join(format!("ws/proj-{p:04}/sessions"));
            std::fs::create_dir_all(&dir).unwrap();
            for f in 0..per_project {
                std::fs::write(dir.join(format!("s-{f:04}.md")), "# session\n\nbody\n").unwrap();
            }
        }
        let t = Instant::now();
        adapter.commit_all("initial walk").unwrap();
        println!(
            "files {}: initial walk {:?}",
            projects * per_project,
            t.elapsed()
        );

        let t = Instant::now();
        adapter.commit_all("clean walk").unwrap();
        println!("clean walk (nothing reported) {:?}", t.elapsed());

        let mut scoped = Vec::new();
        for i in 0..10 {
            let rel = format!("ws/proj-{:04}/sessions/new-{i}.md", i % projects);
            std::fs::write(root.join(&rel), "# new\n\nbody\n").unwrap();
            adapter.mark_written(Path::new(&rel));
            let t = Instant::now();
            adapter.commit_all(&format!("scoped {i}")).unwrap();
            scoped.push(t.elapsed());
        }
        println!("path-scoped commits: {scoped:?}");
    }
    /// A later adapter's first commit walks from the stale index file
    /// and still commits everything.
    #[test]
    fn a_stale_index_file_costs_a_later_adapter_only_a_walk() {
        let (_tmp, root, adapter) = committed(&[("a.md", "a")]);
        for i in 0..3 {
            write(&root, "a.md", &format!("a{i}"));
            adapter.mark_written(Path::new("a.md"));
            adapter.commit_all(&format!("scoped {i}")).unwrap();
        }
        assert_eq!(head_blob(&adapter, "a.md").as_deref(), Some("a2"));
        write(&root, "b.md", "b");
        let later = GitAdapter::open_or_init(&root).unwrap();
        assert!(later.commit_all("from a fresh adapter").unwrap().is_some());
        assert_eq!(head_blob(&later, "a.md").as_deref(), Some("a2"));
        assert_eq!(head_blob(&later, "b.md").as_deref(), Some("b"));
        // The first adapter's kept index predates that commit.
        write(&root, "a.md", "a3");
        adapter.mark_written(Path::new("a.md"));
        adapter.commit_all("after the other adapter").unwrap();
        assert_eq!(head_blob(&adapter, "a.md").as_deref(), Some("a3"));
        assert_eq!(head_blob(&adapter, "b.md").as_deref(), Some("b"));
    }

    #[test]
    fn a_racy_read_is_the_filesystem_error_that_names_it() {
        let racy = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Filesystem,
            "file changed before we could read it",
        );
        assert!(is_racy_read(&racy));
        let other_class = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "file changed before we could read it",
        );
        assert!(!is_racy_read(&other_class));
        let other_message = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Filesystem,
            "failed to open",
        );
        assert!(!is_racy_read(&other_message));
    }

    #[test]
    fn owner_error_is_surfaced_distinctly() {
        let owner = git2::Error::new(
            ErrorCode::Owner,
            git2::ErrorClass::Config,
            "repository path is not owned by current user",
        );
        assert!(matches!(map_git_err(owner), WikiError::GitOwner(_)));
        let generic = git2::Error::new(
            ErrorCode::GenericError,
            git2::ErrorClass::Os,
            "some other failure",
        );
        assert!(matches!(map_git_err(generic), WikiError::Io(_)));
    }

    /// A racy read keeps the commit path-scoped; any other failure walks.
    #[test]
    fn a_racy_read_failure_does_not_escalate_to_a_walk() {
        let (_tmp, _root, adapter) = committed(&[("a.md", "a")]);
        adapter.mark_written(Path::new("a.md"));
        let staging = adapter.take_staging();
        assert!(matches!(staging, Staging::Paths(_)));
        adapter.keep_pending(staging, true);
        assert_eq!(adapter.written_paths(), vec![PathBuf::from("a.md")]);
        let staging = adapter.take_staging();
        assert!(matches!(&staging, Staging::Paths(p) if p.len() == 1));

        adapter.keep_pending(staging, false);
        assert_eq!(adapter.written_paths(), vec![PathBuf::from("a.md")]);
        assert!(matches!(adapter.take_staging(), Staging::Everything));
    }

    #[test]
    fn persist_and_remove_dir_all_report_their_paths() {
        let (_tmp, root, adapter) = committed(&[("d/x.md", "x"), ("d/y.md", "y")]);
        let mut tmp = tempfile::NamedTempFile::new_in(&root).unwrap();
        std::io::Write::write_all(&mut tmp, b"p").unwrap();
        adapter.persist(tmp, &root.join("p.md")).unwrap();
        adapter.remove_dir_all(&root.join("d")).unwrap();
        assert_eq!(
            adapter.written_paths(),
            ["d", "p.md"].map(PathBuf::from).to_vec()
        );
        assert!(adapter.commit_all("persist and remove").unwrap().is_some());
        assert_eq!(head_blob(&adapter, "p.md").as_deref(), Some("p"));
        assert!(head_blob(&adapter, "d/x.md").is_none());
        assert!(head_blob(&adapter, "d/y.md").is_none());
    }

    /// What another process sees: a repository opened fresh reads the
    /// index file, not the adapter's kept index.
    fn assert_clean_from_outside(root: &Path, context: &str) {
        let repo = Repository::open(root).unwrap();
        let dirty: Vec<(String, git2::Status)> = repo
            .statuses(None)
            .unwrap()
            .iter()
            .map(|entry| (entry.path().unwrap_or_default().to_owned(), entry.status()))
            .collect();
        assert!(dirty.is_empty(), "{context}: {dirty:?}");
        // The git CLI too, where there is one.
        if let Ok(out) = std::process::Command::new("git")
            .args(["status", "--porcelain=v2"])
            .current_dir(root)
            .output()
            && out.status.success()
        {
            let porcelain = String::from_utf8_lossy(&out.stdout);
            assert!(porcelain.is_empty(), "{context}: git status: {porcelain}");
        }
    }

    #[test]
    fn every_commit_leaves_the_index_file_matching_head() {
        let (_tmp, root, adapter) = committed(&[("a.md", "a"), ("b.md", "b")]);
        assert_clean_from_outside(&root, "after the walk");
        for i in 1..=3 {
            write(&root, "a.md", &format!("a{i}"));
            adapter.mark_written(Path::new("a.md"));
            assert!(
                adapter
                    .commit_all(&format!("scoped {i}"))
                    .unwrap()
                    .is_some()
            );
            assert_clean_from_outside(&root, &format!("after scoped commit {i}"));
        }
        assert_eq!(head_blob(&adapter, "a.md").as_deref(), Some("a3"));
    }

    #[test]
    fn a_commit_with_nothing_to_commit_still_writes_the_index_file() {
        let (_tmp, root, adapter) = committed(&[("a.md", "a")]);
        let index_file = root.join(".git/index");
        let stale = std::fs::read(&index_file).unwrap();
        write(&root, "a.md", "a2");
        adapter.mark_written(Path::new("a.md"));
        assert!(adapter.commit_all("a2").unwrap().is_some());
        // The index file falls behind HEAD, as a missed write left it.
        std::fs::write(&index_file, &stale).unwrap();
        adapter.mark_written(Path::new("a.md"));
        assert!(adapter.commit_all("unchanged").unwrap().is_none());
        assert_clean_from_outside(&root, "after the no-op commit");
    }

    #[test]
    fn a_failed_commit_keeps_the_reported_paths() {
        let (_tmp, root, adapter) = committed(&[("a.md", "a")]);
        write(&root, "a.md", "a2");
        adapter.mark_written(Path::new("a.md"));
        // Break the repository; the kept one is dropped first, as a restart would.
        adapter.close();
        let git_dir = root.join(".git");
        std::fs::rename(&git_dir, root.join(".git-parked")).unwrap();
        assert!(adapter.commit_all("broken").is_err());
        std::fs::rename(root.join(".git-parked"), &git_dir).unwrap();
        assert_eq!(adapter.written_paths(), vec![PathBuf::from("a.md")]);
        assert!(adapter.commit_all("retry").unwrap().is_some());
        assert_eq!(head_blob(&adapter, "a.md").as_deref(), Some("a2"));
    }
    /// The stat cache's blind spot: a file rewritten with the same size and
    /// an mtime no newer than the index looks unchanged by stat alone. git
    /// treats an entry whose mtime is not older than the index as "racy"
    /// and re-reads it; the commit must carry the new content, or a page
    /// saved right after a session end would be snapshotted stale. The
    /// rewritten file is given the index file's own mtime so the case is
    /// forced rather than left to the clock.
    #[test]
    fn a_same_size_rewrite_with_an_unchanged_mtime_is_still_committed() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let file = root.join("racy.md");
        std::fs::write(&file, "version A").unwrap();
        adapter.commit_all("A").unwrap();

        std::fs::write(&file, "version B").unwrap();
        let index_written = std::fs::metadata(root.join(".git").join("index"))
            .unwrap()
            .modified()
            .unwrap();
        std::fs::File::options()
            .write(true)
            .open(&file)
            .unwrap()
            .set_modified(index_written)
            .unwrap();

        adapter.commit_all("B").unwrap();
        assert_eq!(
            adapter.file_at_rev("HEAD", Path::new("racy.md")).unwrap(),
            b"version B"
        );
        assert_eq!(adapter.commit_count(), 2);
    }

    /// Two session ends at once used to collide on libgit2's index lock and
    /// one of them lost its snapshot; now they queue.
    /// The CI flake behind `concurrent_commits_queue_instead_of_failing`: a
    /// walk listed a file that was gone when libgit2 read it, and libgit2
    /// reports that as an `Os`-class "failed to read file into stream" — not
    /// the "changed before" the retry recognized — so the commit failed
    /// instead of retrying. Unrelated errors must still fail fast.
    #[test]
    fn a_file_vanishing_mid_walk_is_a_racy_read_but_other_errors_are_not() {
        let err =
            |class, message: &str| git2::Error::new(git2::ErrorCode::GenericError, class, message);
        assert!(is_racy_read(&err(
            git2::ErrorClass::Os,
            "failed to read file into stream: "
        )));
        assert!(is_racy_read(&err(
            git2::ErrorClass::Filesystem,
            "file changed before we could read it"
        )));
        assert!(!is_racy_read(&err(
            git2::ErrorClass::Os,
            "failed to open file"
        )));
        assert!(!is_racy_read(&err(
            git2::ErrorClass::Index,
            "failed to read file into stream: "
        )));
    }

    #[test]
    fn concurrent_commits_queue_instead_of_failing() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        let threads: Vec<_> = (0..8)
            .map(|i| {
                let adapter = adapter.clone();
                let root = root.clone();
                std::thread::spawn(move || {
                    std::fs::write(root.join(format!("s{i}.md")), format!("session {i}")).unwrap();
                    adapter.commit_all(&format!("session {i}")).unwrap()
                })
            })
            .collect();
        for t in threads {
            t.join().unwrap();
        }
        // Every file is in HEAD whether its own commit ran or a later one
        // swept it up; nothing was dropped.
        for i in 0..8 {
            assert_eq!(
                adapter
                    .file_at_rev("HEAD", Path::new(&format!("s{i}.md")))
                    .unwrap(),
                format!("session {i}").as_bytes()
            );
        }
    }

    #[test]
    fn commit_all_captures_deletes_too() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();
        std::fs::write(root.join("a.md"), "first").unwrap();
        adapter.commit_all("first").unwrap();
        std::fs::remove_file(root.join("a.md")).unwrap();
        let oid = adapter.commit_all("remove a").unwrap();
        assert!(oid.is_some());
        assert_eq!(adapter.commit_count(), 2);
    }

    #[cfg(windows)]
    #[test]
    fn commit_all_handles_windows_dot_prefixed_temp_roots() {
        let tmp = TempDir::new().unwrap();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();

        std::fs::write(root.join("foo.md"), "hello").unwrap();
        assert!(adapter.commit_all("add foo").unwrap().is_some());
        assert_eq!(adapter.commit_count(), 1);
    }

    #[test]
    fn recent_checkpoints_returns_newest_first() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();

        std::fs::write(root.join("a.md"), "one").unwrap();
        let first = adapter.commit_all("first checkpoint").unwrap().unwrap();
        std::fs::write(root.join("a.md"), "two").unwrap();
        let second = adapter.commit_all("second checkpoint").unwrap().unwrap();

        let checkpoints = adapter.recent_checkpoints(10).unwrap();
        assert_eq!(checkpoints.len(), 2);
        assert_eq!(checkpoints[0].oid, second.to_string());
        assert_eq!(checkpoints[0].summary, "second checkpoint");
        assert_eq!(checkpoints[1].oid, first.to_string());
    }

    #[test]
    fn file_at_rev_reads_historical_blob() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        let adapter = GitAdapter::open_or_init(&root).unwrap();

        std::fs::write(root.join("a.md"), "one").unwrap();
        let first = adapter.commit_all("first").unwrap().unwrap();
        std::fs::write(root.join("a.md"), "two").unwrap();
        adapter.commit_all("second").unwrap();

        let bytes = adapter
            .file_at_rev(&first.to_string(), Path::new("a.md"))
            .unwrap();
        assert_eq!(String::from_utf8(bytes).unwrap(), "one");
    }

    fn local_fsync_setting(root: &Path) -> Option<bool> {
        Repository::open(root)
            .unwrap()
            .config()
            .unwrap()
            .open_level(git2::ConfigLevel::Local)
            .unwrap()
            .get_bool(FSYNC_OBJECT_FILES)
            .ok()
    }

    fn fsync_setting(repo: &Repository) -> Option<bool> {
        repo.config().unwrap().get_bool(FSYNC_OBJECT_FILES).ok()
    }

    /// What the git CLI prints for `status`, or `None` without git on PATH.
    fn git_status_stderr(root: &Path) -> Option<String> {
        let output = git_command(root).arg("status").output().ok()?;
        assert!(output.status.success(), "git status failed: {output:?}");
        Some(String::from_utf8_lossy(&output.stderr).into_owned())
    }

    /// #1511: without it libgit2 renames objects and refs into place unsynced,
    /// and a crash left a ref naming an empty commit object. The setting lives
    /// on ai-memory's handles only, never in `.git/config`, where git warns
    /// that the key is deprecated on every command.
    #[test]
    fn every_wiki_handle_turns_on_git_object_fsync_without_touching_git_config() {
        let tmp = tempdir();
        let fresh = tmp.path().join("fresh");
        let existing = tmp.path().join("existing");
        // A repository an older version created gets it on the next open.
        Repository::init(&existing).unwrap();

        for root in [&fresh, &existing] {
            let adapter = GitAdapter::open_or_init(root).unwrap();
            write(root, "page.md", "page");
            adapter.commit_all("checkpoint").unwrap().unwrap();

            let slot = adapter.writing();
            let kept = &slot.as_ref().expect("the commit keeps its handle").repo;
            assert_eq!(fsync_setting(kept), Some(true));
            drop(slot);
            let validated = open_validated_repository(root).ok().unwrap();
            assert_eq!(fsync_setting(&validated), Some(true));

            assert_eq!(local_fsync_setting(root), None);
            assert_eq!(fsync_setting(&Repository::open(root).unwrap()), None);
            let git_config = std::fs::read_to_string(root.join(".git/config")).unwrap();
            assert!(!git_config.to_ascii_lowercase().contains("fsyncobjectfiles"));
            if let Some(stderr) = git_status_stderr(root) {
                assert!(
                    !stderr.contains("deprecated"),
                    "git status warned: {stderr}"
                );
            }
        }
    }

    #[test]
    fn an_explicit_fsync_opt_out_in_git_config_is_kept() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        Repository::init(&root)
            .unwrap()
            .config()
            .unwrap()
            .set_bool(FSYNC_OBJECT_FILES, false)
            .unwrap();

        GitAdapter::open_or_init(&root).unwrap();

        let validated = open_validated_repository(&root).ok().unwrap();
        assert_eq!(fsync_setting(&validated), Some(false));
        assert_eq!(local_fsync_setting(&root), Some(false));
    }

    /// The crash shape from #1511: HEAD names a commit whose loose object is
    /// empty. Startup still opens the wiki, the check reports it, and a
    /// checkpoint returns the error instead of passing for a clean tree.
    #[test]
    fn an_empty_head_commit_object_is_reported_not_swallowed() {
        let (_tmp, root, _adapter) = committed(&[("page.md", "page")]);
        let repo = Repository::open(&root).unwrap();
        readable_head(&repo).unwrap();
        let head = repo.head().unwrap().target().unwrap().to_string();
        let object = root.join(".git/objects").join(&head[..2]).join(&head[2..]);
        let mut permissions = std::fs::metadata(&object).unwrap().permissions();
        #[allow(clippy::permissions_set_readonly_false)]
        permissions.set_readonly(false);
        std::fs::set_permissions(&object, permissions).unwrap();
        std::fs::write(&object, b"").unwrap();
        drop(repo);

        let reopened = GitAdapter::open_or_init(&root).unwrap();
        assert!(readable_head(&Repository::open(&root).unwrap()).is_err());
        write(&root, "page.md", "page, edited after the crash");
        assert!(reopened.commit_all("after the crash").is_err());
    }

    #[test]
    fn a_fresh_repository_has_a_readable_head() {
        let tmp = tempdir();
        let root = tmp.path().join("wiki");
        GitAdapter::open_or_init(&root).unwrap();
        readable_head(&Repository::open(&root).unwrap()).unwrap();
    }
}