fallow_cli/

base_worktree.rs

use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::process::Command;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, SystemTime};

use fallow_engine::changed_files::clear_ambient_git_env;
pub use fallow_engine::repo_refs::materialize_base_dependency_context;
use rustc_hash::FxHashSet;
use xxhash_rust::xxh3::xxh3_64;

use crate::report::plural;

pub struct BaseWorktree {
    path: PathBuf,
    persistent: bool,
    _reusable_lock: Option<ReusableWorktreeLock>,
}

impl BaseWorktree {
    pub fn create(repo_root: &Path, base_ref: &str, base_sha: Option<&str>) -> Option<Self> {
        sweep_orphan_audit_worktrees(repo_root);
        if let Some(base_sha) = base_sha
            && let Some(worktree) = Self::reuse_or_create(repo_root, base_sha)
        {
            return Some(worktree);
        }
        let path = non_reusable_worktree_path()?;
        let mut guard = WorktreeCleanupGuard::new(repo_root, &path);
        if let Err(error) = fallow_engine::repo_refs::create_detached_base_worktree(
            repo_root,
            guard.path(),
            base_ref,
        ) {
            tracing::debug!(
                base_ref,
                error = %error,
                "could not materialize non-reusable audit base worktree",
            );
            return None;
        }
        // Deregister immediately so a crash before Drop never leaves a git
        // worktree admin entry behind (issue #1815). No early return runs
        // between here and the struct binding, so defusing the guard next is
        // safe: the entry is already unregistered.
        if let Err(error) = unregister_worktree(repo_root, guard.path()) {
            tracing::debug!(
                path = %guard.path().display(),
                error = %error,
                "could not deregister non-reusable audit base worktree",
            );
            return None;
        }
        guard.defuse();
        drop(guard);
        let worktree = Self {
            path,
            persistent: false,
            _reusable_lock: None,
        };
        materialize_base_dependency_context(repo_root, worktree.path());
        Some(worktree)
    }

    pub fn reuse_or_create(repo_root: &Path, base_sha: &str) -> Option<Self> {
        let path = reusable_audit_worktree_path(repo_root);
        let reusable_lock = ReusableWorktreeLock::try_acquire(&path)?;

        if reusable_audit_worktree_is_ready(&path, base_sha)
            || try_migrate_registered_current_cache(repo_root, &path, base_sha)
        {
            let worktree = Self {
                path,
                persistent: true,
                _reusable_lock: Some(reusable_lock),
            };
            materialize_base_dependency_context(repo_root, worktree.path());
            record_last_used(worktree.path(), repo_root);
            return Some(worktree);
        }

        if let Err(error) = remove_file_if_exists(&reusable_worktree_sha_path(&path)) {
            tracing::debug!(
                path = %path.display(),
                error = %error,
                "could not clear reusable audit worktree readiness before rebuild",
            );
            return None;
        }
        if let Err(error) = remove_reusable_cache_entry_locked(repo_root, &path) {
            tracing::debug!(
                path = %path.display(),
                error = %error,
                "could not remove stale reusable audit worktree before rebuild",
            );
            return None;
        }
        let mut guard = WorktreeCleanupGuard::new(repo_root, &path);
        if let Err(error) = fallow_engine::repo_refs::create_detached_base_worktree(
            repo_root,
            guard.path(),
            base_sha,
        ) {
            tracing::debug!(
                base_sha,
                error = %error,
                "could not materialize reusable audit base worktree",
            );
            return None;
        }
        // Deregister while keeping the directory, then atomically publish the
        // full base SHA through the `.sha` sidecar. Publication happens only
        // after successful materialization and deregistration under the lock,
        // so a torn snapshot is never advertised as ready to the next run.
        if let Err(error) = unregister_worktree_checked(repo_root, guard.path()) {
            tracing::debug!(
                path = %guard.path().display(),
                error = %error,
                "could not deregister reusable audit base worktree",
            );
            return None;
        }
        guard.defuse();
        drop(guard);
        let readiness_published = write_reusable_sha(&path, base_sha).is_ok();

        let worktree = Self {
            path,
            persistent: true,
            _reusable_lock: Some(reusable_lock),
        };
        materialize_base_dependency_context(repo_root, worktree.path());
        if readiness_published {
            record_last_used(worktree.path(), repo_root);
        }
        Some(worktree)
    }

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

/// Build a unique temp path for a non-reusable base worktree.
///
/// The pid stays the FIRST `-`-separated segment so [`audit_worktree_pid`] and
/// the orphan sweep keep working. A process-global monotonic counter is the
/// final segment: the wall-clock nanos read is NOT monotonic and repeats across
/// threads, so two `audit` runs in one process (e.g. parallel unit tests, or a
/// future in-process batch) could otherwise mint the same path and race on
/// `git worktree add`, where the loser fails and the audit aborts with a generic
/// error. The counter makes every path distinct regardless of clock resolution.
fn non_reusable_worktree_path() -> Option<PathBuf> {
    static SEQ: AtomicU64 = AtomicU64::new(0);
    let seq = SEQ.fetch_add(1, Ordering::Relaxed);
    let nanos = SystemTime::now()
        .duration_since(SystemTime::UNIX_EPOCH)
        .ok()?
        .as_nanos();
    Some(std::env::temp_dir().join(format!(
        "fallow-audit-base-{}-{nanos}-{seq}",
        std::process::id()
    )))
}

/// RAII cleanup guard for a freshly-created git worktree directory.
///
/// Armed before the `git worktree add` subprocess runs. If the holder returns
/// early (`?`) between subprocess success and the `BaseWorktree` struct binding,
/// `Drop` rolls back BOTH git's `.git/worktrees/<name>` registration AND the
/// on-disk directory. The owner calls `defuse()` once `BaseWorktree` is bound
/// and takes over cleanup via its own `Drop`.
///
/// With `panic = "abort"` on the release profile, this does not provide
/// panic-recovery cleanup (no unwind runs), but it is still load-bearing for
/// every early-return path between subprocess success and struct construction.
pub struct WorktreeCleanupGuard<'a> {
    repo_root: PathBuf,
    path: &'a Path,
    armed: bool,
}

impl<'a> WorktreeCleanupGuard<'a> {
    pub fn new(repo_root: &Path, path: &'a Path) -> Self {
        Self {
            repo_root: repo_root.to_path_buf(),
            path,
            armed: true,
        }
    }

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

    /// Disarm in place. Idempotent; calling twice is harmless. Drop becomes a
    /// no-op after this returns.
    pub fn defuse(&mut self) {
        self.armed = false;
    }
}

impl Drop for WorktreeCleanupGuard<'_> {
    fn drop(&mut self) {
        if self.armed {
            remove_audit_worktree(&self.repo_root, self.path);
            let _ = std::fs::remove_dir_all(self.path);
        }
    }
}

/// Kernel-level advisory lock around the reusable-cache `reuse_or_create`
/// critical section, backed by `std::fs::File::try_lock` (stable since Rust
/// 1.89), which wraps `flock(2)` on Unix and `LockFileEx` on Windows.
/// Concurrent acquirers either fall through (`None`) or observe a
/// freshly-prepared cache after the holder releases.
pub struct ReusableWorktreeLock {
    file: std::fs::File,
}

impl ReusableWorktreeLock {
    pub fn try_acquire(reusable_path: &Path) -> Option<Self> {
        let lock_path = reusable_worktree_lock_path(reusable_path);
        let file = open_or_create_owned_sidecar(&lock_path).ok()?;
        match file.try_lock() {
            Ok(()) => Some(Self { file }),
            Err(std::fs::TryLockError::WouldBlock) => {
                tracing::debug!(
                    path = %lock_path.display(),
                    "reusable audit worktree lock contended; falling back to non-reusable worktree",
                );
                None
            }
            Err(std::fs::TryLockError::Error(err)) => {
                tracing::debug!(
                    path = %lock_path.display(),
                    error = %err,
                    "could not acquire reusable audit worktree lock; falling back to non-reusable worktree",
                );
                None
            }
        }
    }
}

impl Drop for ReusableWorktreeLock {
    fn drop(&mut self) {
        let _ = self.file.unlock();
    }
}

pub fn reusable_worktree_lock_path(reusable_path: &Path) -> PathBuf {
    sidecar_path(reusable_path, REUSABLE_LOCK_SUFFIX)
}

/// Build a sidecar path `<cache dir name><suffix>` next to (NOT inside) the
/// reusable cache directory, so the sidecar survives `git worktree`
/// operations and directory materialization on the cache dir itself.
fn sidecar_path(reusable_path: &Path, suffix: &str) -> PathBuf {
    let mut name = reusable_path
        .file_name()
        .map(std::ffi::OsString::from)
        .unwrap_or_default();
    name.push(suffix);
    reusable_path
        .parent()
        .map_or_else(|| PathBuf::from(&name), |parent| parent.join(&name))
}

/// Sidecar path recording the base SHA a reusable cache entry was
/// materialized at. Lives next to the cache directory like the `.last-used` /
/// `.lock` sidecars, so readiness can be verified without a `git` subprocess.
pub fn reusable_worktree_sha_path(reusable_path: &Path) -> PathBuf {
    sidecar_path(reusable_path, REUSABLE_SHA_SUFFIX)
}

/// Record the base SHA a reusable cache holds. Failure is non-fatal: this run
/// proceeds and the next run rebuilds (a missing `.sha` reads as not-ready).
fn write_reusable_sha(reusable_path: &Path, base_sha: &str) -> std::io::Result<()> {
    static SEQ: AtomicU64 = AtomicU64::new(0);

    let sha_path = reusable_worktree_sha_path(reusable_path);
    let sequence = SEQ.fetch_add(1, Ordering::Relaxed);
    let temp_path = sidecar_path(
        reusable_path,
        &format!(
            "{REUSABLE_SHA_SUFFIX}.tmp-{}-{sequence}",
            std::process::id()
        ),
    );
    let result = (|| {
        let mut options = std::fs::OpenOptions::new();
        options.create_new(true).write(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt as _;
            options.mode(0o600);
        }
        let mut file = options.open(&temp_path)?;
        file.write_all(format!("{base_sha}\n").as_bytes())?;
        file.sync_all()?;
        std::fs::rename(&temp_path, &sha_path)
    })();
    if let Err(err) = &result {
        let _ = std::fs::remove_file(&temp_path);
        tracing::debug!(
            path = %sha_path.display(),
            error = %err,
            "failed to write reusable audit worktree .sha sidecar; next run will rebuild",
        );
    }
    result
}

/// Default GC threshold for persistent reusable base-snapshot caches.
const DEFAULT_AUDIT_CACHE_MAX_AGE_DAYS: u32 = 30;

/// Env var that overrides `audit.cacheMaxAgeDays` from the config.
const AUDIT_CACHE_MAX_AGE_ENV: &str = "FALLOW_AUDIT_CACHE_MAX_AGE_DAYS";

/// Sidecar filename suffix used to track last-use of a reusable worktree.
const REUSABLE_LAST_USED_SUFFIX: &str = ".last-used";

/// Sidecar filename suffix recording the base SHA a reusable cache holds.
const REUSABLE_SHA_SUFFIX: &str = ".sha";

/// Sidecar filename suffix of the reuse-lock file.
const REUSABLE_LOCK_SUFFIX: &str = ".lock";

/// Invalid gitdir pointer written into `<cache>/.git` after deregistering a
/// transient audit worktree (issue #1815).
///
/// The `.git` file is REPLACED, never deleted: both discovery walkers use the
/// `ignore` crate with `require_git` on, whose gitignore handling is gated on
/// `<root>/.git` existing. Deleting the gitfile would silently stop the base
/// pass from honoring `.gitignore`, inflating base findings and skewing
/// audit's introduced-vs-inherited split. The stub keeps gitignore parity
/// while pointing at a nonexistent gitdir, so any stray `git` command inside
/// the snapshot fails loudly instead of operating on the host repo.
const UNREGISTERED_GITDIR_STUB: &str = "gitdir: fallow-audit-unregistered\n";

/// Sidecar path for the "last used" timestamp of a reusable cache entry.
///
/// Lives next to the cache directory (NOT inside it) so the sidecar is
/// untouched by `git worktree add/remove` on the cache directory itself.
pub fn reusable_worktree_last_used_path(reusable_path: &Path) -> PathBuf {
    sidecar_path(reusable_path, REUSABLE_LAST_USED_SUFFIX)
}

/// Stamp the sidecar `.last-used` file's mtime to now.
///
/// Called on every cache-hit reuse (and from the pre-upgrade-grace branch
/// of the GC sweep) so the staleness signal stays current even when the
/// cache directory itself is not mutated. Failures are surfaced at
/// `warn!` so a persistent ENOSPC / read-only-tmp condition is visible at
/// default `RUST_LOG=warn`; the caller does not abort the audit.
pub fn touch_last_used(reusable_path: &Path) {
    stamp_last_used(reusable_path, None);
}

/// Stamp `.last-used` like [`touch_last_used`] and additionally record
/// `owner_root` (the requested analysis root that owns this cache) as the
/// sidecar's content. The cross-repo GC pass reads it back to decide whether
/// an entry outside the current repo's scope is still owned by a live project
/// (issue #2169): caches whose recorded owner no longer exists on disk are
/// abandoned and become eligible for age-based reclaim from any repo's sweep.
pub fn record_last_used(reusable_path: &Path, owner_root: &Path) {
    stamp_last_used(reusable_path, Some(owner_root));
}

fn stamp_last_used(reusable_path: &Path, owner_root: Option<&Path>) {
    let last_used = reusable_worktree_last_used_path(reusable_path);
    let result = open_or_create_owned_sidecar(&last_used).and_then(|mut file| {
        if let Some(owner_root) = owner_root {
            file.set_len(0)?;
            file.write_all(format!("{}\n", owner_root.display()).as_bytes())?;
        }
        file.set_modified(SystemTime::now())
    });
    if let Err(err) = result {
        tracing::warn!(
            path = %last_used.display(),
            error = %err,
            "failed to touch reusable audit worktree sidecar; staleness signal may not update",
        );
    }
}

/// Read the owner root recorded in a cache entry's `.last-used` sidecar.
/// Returns `None` for missing, empty (pre-#2169), oversized, or non-file
/// sidecars. The path is only ever used for an existence probe, never as a
/// removal target, so untrusted content cannot redirect the sweep.
fn read_last_used_owner(reusable_path: &Path) -> Option<PathBuf> {
    const MAX_OWNER_SIDECAR_BYTES: u64 = 4096;

    let sidecar = reusable_worktree_last_used_path(reusable_path);
    let metadata = std::fs::symlink_metadata(&sidecar).ok()?;
    if !metadata_is_regular_file(&metadata) || metadata.len() > MAX_OWNER_SIDECAR_BYTES {
        return None;
    }
    let mut contents = String::new();
    std::fs::File::open(sidecar)
        .ok()?
        .take(MAX_OWNER_SIDECAR_BYTES)
        .read_to_string(&mut contents)
        .ok()?;
    let owner = contents.trim();
    if owner.is_empty() {
        return None;
    }
    Some(PathBuf::from(owner))
}

fn open_or_create_owned_sidecar(path: &Path) -> std::io::Result<std::fs::File> {
    match std::fs::symlink_metadata(path) {
        Ok(metadata) if sidecar_metadata_is_trusted(&metadata) => {
            std::fs::OpenOptions::new().write(true).open(path)
        }
        Ok(_) => Err(std::io::Error::new(
            std::io::ErrorKind::PermissionDenied,
            "refusing to open an untrusted audit cache sidecar",
        )),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            let mut options = std::fs::OpenOptions::new();
            options.create_new(true).write(true);
            #[cfg(unix)]
            {
                use std::os::unix::fs::OpenOptionsExt as _;
                options.mode(0o600);
            }
            options.open(path)
        }
        Err(error) => Err(error),
    }
}

#[cfg(unix)]
fn sidecar_metadata_is_trusted(metadata: &std::fs::Metadata) -> bool {
    use std::os::unix::fs::MetadataExt as _;

    metadata_is_regular_file(metadata) && metadata.uid() == rustix::process::geteuid().as_raw()
}

#[cfg(not(unix))]
fn sidecar_metadata_is_trusted(metadata: &std::fs::Metadata) -> bool {
    metadata_is_regular_file(metadata)
}

#[expect(
    clippy::filetype_is_file,
    reason = "security-sensitive sidecars and gitfiles must be regular files, not arbitrary non-directories"
)]
fn metadata_is_regular_file(metadata: &std::fs::Metadata) -> bool {
    metadata.file_type().is_file()
}

/// Resolve the GC threshold for persistent reusable caches.
///
/// Precedence: `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` env var > `audit.cacheMaxAgeDays`
/// config field > 30-day default. `0` from either source disables the sweep
/// entirely (returns `None`). Invalid env values (non-integer) warn and fall
/// back to config / default; audits do not fail on a typo in a runner env var.
pub fn resolve_cache_max_age_with_options(
    root: &Path,
    config_path: Option<&PathBuf>,
    allow_remote_extends: bool,
) -> Option<Duration> {
    if let Ok(raw) = std::env::var(AUDIT_CACHE_MAX_AGE_ENV) {
        if let Ok(days) = raw.trim().parse::<u32>() {
            return days_to_duration(days);
        }
        tracing::warn!(
            value = %raw,
            "FALLOW_AUDIT_CACHE_MAX_AGE_DAYS is not a valid u32; falling back to config/default",
        );
    }
    if let Some(days) = load_audit_config(root, config_path, allow_remote_extends)
        .and_then(|c| c.cache_max_age_days)
    {
        return days_to_duration(days);
    }
    days_to_duration(DEFAULT_AUDIT_CACHE_MAX_AGE_DAYS)
}

pub fn days_to_duration(days: u32) -> Option<Duration> {
    if days == 0 {
        return None;
    }
    Some(Duration::from_secs(u64::from(days) * 86_400))
}

/// Load `AuditConfig` from `opts.config_path` (or auto-discover from
/// `opts.root`) for GC-threshold resolution only. Errors silently fall
/// back to `None`; the caller defaults to a 30-day window.
fn load_audit_config(
    root: &Path,
    config_path: Option<&PathBuf>,
    allow_remote_extends: bool,
) -> Option<fallow_config::AuditConfig> {
    let options = fallow_config::ConfigLoadOptions {
        allow_remote_extends,
    };
    if let Some(path) = config_path {
        return fallow_config::FallowConfig::load_with_options(path, options)
            .ok()
            .map(|config| config.audit);
    }
    fallow_config::FallowConfig::find_and_load_with_options(root, options)
        .ok()
        .flatten()
        .map(|(config, _path)| config.audit)
}

/// Reclaim persistent reusable base-snapshot worktree caches.
///
/// Two reclaim conditions, checked per entry:
/// - Prunable orphan: the cache directory no longer exists (an external
///   `$TMPDIR` reaper, a container restart, or a CI cache eviction deleted it
///   but left git's admin entry behind). Reclaimed eagerly, independent of
///   `max_age`, because the `.last-used` sidecar lives next to the deleted
///   directory and survives the reaper, so the age branch would re-touch a
///   fresh sidecar and never reclaim the dead entry. Passing `max_age = None`
///   (age-based GC disabled) still runs this reclaim.
/// - Aged-out: the sidecar `.last-used` file is older than `max_age` (only
///   when `max_age` is `Some`).
///
/// Entries under other repo hashes (other linked worktrees, deleted or moved
/// repos) are visited by a cross-repo pass; see
/// [`reclaim_foreign_cache_entry`] for its owner-liveness gate (issue #2169).
///
/// Concurrency: each candidate is gated by [`ReusableWorktreeLock`] before
/// removal, so an in-flight `fallow audit` mid-rebuild against the same
/// cache entry will not be disturbed (the sweep skips on contention). The
/// orphan branch re-checks existence under the lock so a rebuild that
/// recreated the directory between the check and the lock is preserved.
///
/// Pre-upgrade caches lacking a sidecar are NOT removed: instead the sweep
/// seeds a fresh sidecar so the next invocation can age them from real
/// last-use. Without this grace, the dir's own mtime (= creation date on
/// POSIX) would wipe every legitimately-warm pre-upgrade cache on the
/// first run after upgrade.
///
/// The `.lock` sidecar file is intentionally NOT deleted on removal: a
/// racing acquirer of an unlinked-but-still-flocked inode plus a sibling
/// `open(O_CREAT)` at the same path would produce two processes each
/// holding a kernel flock on different inodes. Lock files are tens of
/// bytes; leaking them is harmless.
pub fn sweep_old_reusable_caches(repo_root: &Path, max_age: Option<Duration>, quiet: bool) {
    sweep_old_reusable_caches_in(repo_root, max_age, quiet, &std::env::temp_dir());
}

/// Scan-root-injectable body of [`sweep_old_reusable_caches`]. Production
/// always passes `std::env::temp_dir()`; tests pass a private per-test
/// directory so one test's cross-repo pass never scans (and reclaims)
/// another test's fixtures or a developer's real ownerless caches in the
/// shared temp dir.
pub fn sweep_old_reusable_caches_in(
    repo_root: &Path,
    max_age: Option<Duration>,
    quiet: bool,
    scan_root: &Path,
) {
    // Legacy pass: deregister reusable caches left REGISTERED by pre-#1815
    // fallow (the reporter's `git worktree list` backlog). This is what makes
    // those entries vanish on the first post-upgrade audit; the `--expire=now`
    // prune is retained ONLY here to also sweep any admin entry orphaned by a
    // crash in the transient registration window.
    if deregister_legacy_reusable_caches(repo_root) {
        let mut command = Command::new("git");
        command
            .args(["worktree", "prune", "--expire=now"])
            .current_dir(repo_root);
        clear_ambient_git_env(&mut command);
        let _ = command.output();
    }

    // Primary pass: visit this requested root's cache plus legacy SHA-suffixed
    // entries from the old git-top-level identity. `git worktree list` no
    // longer sees the deregistered caches.
    let mut paths = vec![reusable_audit_worktree_path(repo_root)];
    paths.extend(scan_legacy_reusable_cache_paths(repo_root, scan_root));
    paths.sort();
    paths.dedup();
    let now = SystemTime::now();
    let mut removed: u32 = 0;
    for path in &paths {
        if reclaim_reusable_cache_entry(repo_root, path, max_age, now) {
            removed += 1;
        }
    }

    // Cross-repo pass (issue #2169): every other repo hash accumulates caches
    // the repo-scoped pass can never see (one per linked git worktree, plus
    // entries from deleted or moved repos that no surviving sweep covers).
    // Entries whose recorded owner root still exists are left to that repo's
    // own sweep, so its `cacheMaxAgeDays` setting, including `0`, governs;
    // the rest are abandoned and age out under this run's threshold.
    let scoped: FxHashSet<&PathBuf> = paths.iter().collect();
    for path in scan_all_reusable_cache_paths(scan_root) {
        if scoped.contains(&path) {
            continue;
        }
        if reclaim_foreign_cache_entry(repo_root, &path, max_age, now) {
            removed += 1;
        }
    }
    if removed == 0 {
        return;
    }
    tracing::info!(
        count = removed,
        "reclaimed stale audit base-snapshot caches",
    );
    if !quiet {
        let s = plural(removed as usize);
        let _ = writeln!(
            std::io::stderr(),
            "fallow: reclaimed {removed} stale base-snapshot cache{s}",
        );
    }
}

/// Deregister reusable base-snapshot caches left REGISTERED by fallow versions
/// before #1815. A mixed-version registration at the current path stays warm;
/// released SHA-keyed paths are removed because the root-owned cache cannot
/// reuse them. Returns `true` when at least one entry was deregistered.
fn deregister_legacy_reusable_caches(repo_root: &Path) -> bool {
    let Some(worktrees) = list_audit_worktrees(repo_root) else {
        return false;
    };
    let mut deregistered = false;
    for path in worktrees {
        if !is_reusable_audit_worktree_path(&path) {
            continue;
        }
        let Some(_lock) = ReusableWorktreeLock::try_acquire(&path) else {
            continue;
        };
        if !audit_worktree_is_registered(repo_root, &path) {
            continue;
        }
        let is_current_path = paths_equal(&path, &reusable_audit_worktree_path(repo_root));
        let head = is_current_path
            .then(|| legacy_reusable_sha(&path))
            .flatten();
        if unregister_worktree_checked(repo_root, &path).is_err() {
            continue;
        }
        if is_current_path {
            if let Some(head) = head {
                let _ = write_reusable_sha(&path, &head);
            }
        } else if let Err(error) = remove_reusable_cache_entry_locked(repo_root, &path) {
            tracing::warn!(
                path = %path.display(),
                error = %error,
                "failed to remove released SHA-keyed audit cache",
            );
        }
        deregistered = true;
    }
    deregistered
}

/// Seed the `.sha` sidecar for a still-registered legacy cache from its HEAD,
/// so after deregistration the readiness probe recognizes it as warm. Seeds
/// only when the snapshot was raw-materialized and no `.sha` exists yet.
fn legacy_reusable_sha(path: &Path) -> Option<String> {
    if reusable_worktree_sha_path(path).exists()
        || !fallow_engine::repo_refs::detached_base_worktree_is_raw_materialized(path)
    {
        return None;
    }
    git_rev_parse(path, "HEAD")
}

/// Enumerate reusable cache DIRECTORY paths for `prefix` by scanning the temp
/// dir. Sidecar entries (`.last-used` / `.sha` / `.lock`) are folded back to
/// their owning cache path and deduplicated, so a dir removed out from under
/// its sidecars is still visited for sidecar-orphan cleanup.
fn scan_legacy_reusable_cache_paths(repo_root: &Path, scan_root: &Path) -> Vec<PathBuf> {
    let Some(prefix) = legacy_reusable_cache_repo_prefix(repo_root) else {
        return Vec::new();
    };
    scan_cache_paths_with_hex_suffix(&prefix, scan_root)
}

fn scan_root_owned_cache_paths(repo_root: &Path) -> Vec<PathBuf> {
    let Some(prefix) = root_owned_cache_repo_prefix(repo_root) else {
        return Vec::new();
    };
    scan_cache_paths_with_hex_suffix(&prefix, &std::env::temp_dir())
}

/// Enumerate every reusable cache entry in the temp dir, regardless of repo
/// hash, for the cross-repo GC pass. Only names matching the two shapes
/// fallow has ever minted are accepted: `<repo16>-<sha16>` (legacy) and
/// `<repo16>-root-<root16>` (current). Sidecar entries fold back to their
/// owning cache path like the repo-scoped scan.
fn scan_all_reusable_cache_paths(scan_root: &Path) -> Vec<PathBuf> {
    const GLOBAL_CACHE_PREFIX: &str = "fallow-audit-base-cache-";

    let Ok(entries) = std::fs::read_dir(scan_root) else {
        return Vec::new();
    };
    let mut seen: FxHashSet<PathBuf> = FxHashSet::default();
    let mut paths = Vec::new();
    for entry in entries.flatten() {
        let name = entry.file_name();
        let Some(name) = name.to_str() else {
            continue;
        };
        let cache_name = strip_cache_sidecar_suffix(name);
        let Some(hash_suffix) = cache_name.strip_prefix(GLOBAL_CACHE_PREFIX) else {
            continue;
        };
        if !cache_hash_suffix_is_valid(hash_suffix) {
            continue;
        }
        let path = scan_root.join(cache_name);
        if seen.insert(path.clone()) {
            paths.push(path);
        }
    }
    paths
}

fn cache_hash_suffix_is_valid(suffix: &str) -> bool {
    fn is_hex16(part: &str) -> bool {
        part.len() == 16 && part.bytes().all(|byte| byte.is_ascii_hexdigit())
    }
    if let Some((repo, root)) = suffix.split_once("-root-") {
        return is_hex16(repo) && is_hex16(root);
    }
    suffix
        .split_once('-')
        .is_some_and(|(repo, sha)| is_hex16(repo) && is_hex16(sha))
}

fn scan_cache_paths_with_hex_suffix(prefix: &str, scan_root: &Path) -> Vec<PathBuf> {
    let Ok(entries) = std::fs::read_dir(scan_root) else {
        return Vec::new();
    };
    let mut seen: FxHashSet<PathBuf> = FxHashSet::default();
    let mut paths = Vec::new();
    for entry in entries.flatten() {
        let name = entry.file_name();
        let Some(name) = name.to_str() else {
            continue;
        };
        let cache_name = strip_cache_sidecar_suffix(name);
        let Some(hash_suffix) = cache_name.strip_prefix(prefix) else {
            continue;
        };
        if hash_suffix.len() != 16 || !hash_suffix.bytes().all(|byte| byte.is_ascii_hexdigit()) {
            continue;
        }
        let path = scan_root.join(cache_name);
        if seen.insert(path.clone()) {
            paths.push(path);
        }
    }
    paths
}

/// Strip a known reusable-cache sidecar suffix so a sidecar entry maps to its
/// owning cache directory name. Cache dir names end in a hex SHA prefix and
/// never contain these suffixes, so the mapping is unambiguous.
fn strip_cache_sidecar_suffix(name: &str) -> &str {
    for suffix in [
        REUSABLE_LAST_USED_SUFFIX,
        REUSABLE_SHA_SUFFIX,
        REUSABLE_LOCK_SUFFIX,
    ] {
        if let Some(stripped) = name.strip_suffix(suffix) {
            return stripped;
        }
    }
    name
}

/// Reclaim a single reusable-cache entry. Returns `true` when the entry was
/// removed (either as a sidecar orphan or as aged-out past `max_age`).
fn reclaim_reusable_cache_entry(
    repo_root: &Path,
    path: &Path,
    max_age: Option<Duration>,
    now: SystemTime,
) -> bool {
    // Sidecar orphan: an external temp-reaper (macOS `$TMPDIR` cleanup,
    // container restart, CI cache eviction) removed the cache directory but
    // its sidecars survive next to it. Reclaim the leftover `.last-used` /
    // `.sha` eagerly, independent of `max_age`, so orphans do not accumulate
    // even when age-based GC is disabled (`cacheMaxAgeDays = 0`). This also
    // fixes a leak that predates #1815: a manual `git worktree remove` left
    // sidecars the old git-scoped sweep could never see.
    if !path.exists() {
        return reclaim_orphan_cache_entry(repo_root, path);
    }
    let Some(max_age) = max_age else {
        return false;
    };
    reclaim_aged_cache_entry(repo_root, path, max_age, now)
}

/// Reclaim the leftover sidecars of a cache directory that was deleted out
/// from under them. Lock-guarded with a re-check so a concurrent rebuild that
/// recreated the directory is preserved. The `.lock` sidecar is deliberately
/// never removed (an unlinked-but-flocked inode plus a racer's `open(O_CREAT)`
/// would split the lock across two inodes).
fn reclaim_orphan_cache_entry(repo_root: &Path, path: &Path) -> bool {
    let Some(_lock) = ReusableWorktreeLock::try_acquire(path) else {
        return false;
    };
    // Re-check under the lock: a concurrent `reuse_or_create` rebuild may
    // have recreated the directory between the existence check and the lock.
    if path.exists() {
        return false;
    }
    remove_reusable_cache_entry_locked(repo_root, path).unwrap_or(false)
}

/// Reclaim a cache entry whose `.last-used` sidecar is older than `max_age`.
/// Seeds a fresh owner-recording sidecar for pre-upgrade entries that lack
/// one (returns `false` so they age from real last-use on the next run).
/// Removal is directory-and-sidecars only: the entry is unregistered, so no
/// `git` subprocess is involved.
fn reclaim_aged_cache_entry(
    repo_root: &Path,
    path: &Path,
    max_age: Duration,
    now: SystemTime,
) -> bool {
    let Some(mtime) = last_used_mtime(path) else {
        record_last_used(path, repo_root);
        return false;
    };
    remove_entry_past_max_age(repo_root, path, max_age, now, mtime)
}

/// Reclaim a cache entry that belongs to a DIFFERENT repo hash than the
/// sweeping repo (issue #2169).
///
/// An entry whose recorded owner root still exists on disk is skipped
/// unconditionally: that repo's own sweep governs it, so its
/// `cacheMaxAgeDays` policy (including `0` = never) cannot be defeated from
/// the outside. Entries with a dead owner, or with no recorded owner (pre-
/// upgrade or externally created), are abandoned: nothing will ever sweep
/// them under their own hash again, so they age out under THIS run's
/// threshold. The grace seed for a missing sidecar stays mtime-only because
/// the true owner is unknown here.
fn reclaim_foreign_cache_entry(
    repo_root: &Path,
    path: &Path,
    max_age: Option<Duration>,
    now: SystemTime,
) -> bool {
    if !path.exists() {
        return reclaim_orphan_cache_entry(repo_root, path);
    }
    if read_last_used_owner(path).is_some_and(|owner| owner.exists()) {
        return false;
    }
    let Some(max_age) = max_age else {
        return false;
    };
    let Some(mtime) = last_used_mtime(path) else {
        touch_last_used(path);
        return false;
    };
    remove_entry_past_max_age(repo_root, path, max_age, now, mtime)
}

fn last_used_mtime(path: &Path) -> Option<SystemTime> {
    std::fs::metadata(reusable_worktree_last_used_path(path))
        .ok()
        .and_then(|metadata| metadata.modified().ok())
}

fn remove_entry_past_max_age(
    repo_root: &Path,
    path: &Path,
    max_age: Duration,
    now: SystemTime,
    mtime: SystemTime,
) -> bool {
    let Ok(age) = now.duration_since(mtime) else {
        return false;
    };
    if age < max_age {
        return false;
    }
    let Some(_lock) = ReusableWorktreeLock::try_acquire(path) else {
        return false;
    };
    match remove_reusable_cache_entry_locked(repo_root, path) {
        Ok(removed) => removed,
        Err(err) => {
            tracing::warn!(
                path = %path.display(),
                error = %err,
                "failed to remove stale reusable audit worktree entry; entry may leak",
            );
            false
        }
    }
}

pub fn canonical_root_hash(root: &Path) -> u64 {
    let canonical_root = dunce::canonicalize(root).unwrap_or_else(|_| root.to_path_buf());
    xxh3_64(&path_identity_bytes(&canonical_root))
}

#[cfg(unix)]
fn path_identity_bytes(path: &Path) -> Vec<u8> {
    use std::os::unix::ffi::OsStrExt as _;

    path.as_os_str().as_bytes().to_vec()
}

#[cfg(windows)]
fn path_identity_bytes(path: &Path) -> Vec<u8> {
    use std::os::windows::ffi::OsStrExt as _;

    path.as_os_str()
        .encode_wide()
        .flat_map(u16::to_le_bytes)
        .collect()
}

#[cfg(not(any(unix, windows)))]
fn path_identity_bytes(path: &Path) -> Vec<u8> {
    path.to_string_lossy().as_bytes().to_vec()
}

pub fn reusable_audit_worktree_path(requested_root: &Path) -> PathBuf {
    let root_hash = canonical_root_hash(requested_root);
    let repo_hash = git_toplevel(requested_root)
        .as_deref()
        .map_or(root_hash, canonical_root_hash);
    std::env::temp_dir().join(format!(
        "fallow-audit-base-cache-{repo_hash:016x}-root-{root_hash:016x}"
    ))
}

fn root_owned_cache_repo_prefix(requested_root: &Path) -> Option<String> {
    let git_root = git_toplevel(requested_root)?;
    let repo_hash = canonical_root_hash(&git_root);
    Some(format!("fallow-audit-base-cache-{repo_hash:016x}-root-"))
}

fn legacy_reusable_cache_repo_prefix(requested_root: &Path) -> Option<String> {
    let git_root = git_toplevel(requested_root)?;
    let repo_hash = canonical_root_hash(&git_root);
    Some(format!("fallow-audit-base-cache-{repo_hash:016x}-"))
}

#[cfg(test)]
pub fn legacy_reusable_audit_worktree_path(
    requested_root: &Path,
    base_sha: &str,
) -> Option<PathBuf> {
    let sha_prefix = base_sha.get(..16).unwrap_or(base_sha);
    Some(std::env::temp_dir().join(format!(
        "{}{sha_prefix}",
        legacy_reusable_cache_repo_prefix(requested_root)?
    )))
}

/// Readiness for a reusable cache HIT: the directory exists and its `.sha`
/// sidecar records exactly `base_sha`.
///
/// Fidelity is equivalent to the old in-worktree `git rev-parse HEAD` probe:
/// that probe read the host admin dir's HEAD, never the snapshot's on-disk
/// content, so neither approach detects content damage. The `.sha` is only
/// ever written after a successful materialization + deregistration, so a
/// torn snapshot never presents a matching sidecar. On a hit the `.git` stub
/// is repaired idempotently so gitignore parity holds even if the stub was
/// removed out-of-band.
fn reusable_audit_worktree_is_ready(path: &Path, base_sha: &str) -> bool {
    if !reusable_cache_directory_is_trusted(path) {
        return false;
    }
    let recorded = read_reusable_sha(path);
    if recorded.as_deref() != Some(base_sha) {
        return false;
    }
    repair_unregistered_git_stub(path)
}

fn read_reusable_sha(path: &Path) -> Option<String> {
    const MAX_SHA_SIDECAR_BYTES: u64 = 129;

    let sidecar = reusable_worktree_sha_path(path);
    let metadata = std::fs::symlink_metadata(&sidecar).ok()?;
    if !metadata_is_regular_file(&metadata) || metadata.len() > MAX_SHA_SIDECAR_BYTES {
        return None;
    }
    let mut contents = String::new();
    std::fs::File::open(sidecar)
        .ok()?
        .take(MAX_SHA_SIDECAR_BYTES)
        .read_to_string(&mut contents)
        .ok()?;
    Some(contents.trim().to_owned())
}

#[cfg(unix)]
fn reusable_cache_directory_is_trusted(path: &Path) -> bool {
    use std::os::unix::fs::{MetadataExt as _, PermissionsExt as _};

    let Ok(metadata) = std::fs::symlink_metadata(path) else {
        return false;
    };
    metadata.file_type().is_dir()
        && metadata.uid() == rustix::process::geteuid().as_raw()
        && metadata.permissions().mode().trailing_zeros() >= 6
}

#[cfg(not(unix))]
fn reusable_cache_directory_is_trusted(path: &Path) -> bool {
    std::fs::symlink_metadata(path).is_ok_and(|metadata| metadata.file_type().is_dir())
}

/// Recover a current-path cache that is still a registered Git worktree.
///
/// This can occur during mixed-version use or after interruption between
/// registration and deregistration. Keep the cache warm only when HEAD matches
/// the requested full SHA and raw materialization completed.
fn try_migrate_registered_current_cache(repo_root: &Path, path: &Path, base_sha: &str) -> bool {
    if !path.exists() || !audit_worktree_is_registered(repo_root, path) {
        return false;
    }
    let head_matches = git_rev_parse(path, "HEAD").is_some_and(|head| head == base_sha);
    if !head_matches || !fallow_engine::repo_refs::detached_base_worktree_is_raw_materialized(path)
    {
        return false;
    }
    if unregister_worktree_checked(repo_root, path).is_err() {
        return false;
    }
    write_reusable_sha(path, base_sha).is_ok()
}

/// Remove every reusable base-snapshot cache owned by `requested_root`.
///
/// The root-owned entry and every SHA-suffixed entry from the old
/// git-top-level identity are locked independently. Contended entries are
/// reported as skipped. Lock files are permanent lock identities and are never
/// removed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AuditCacheRemovalReport {
    pub found: usize,
    pub removed: usize,
    pub skipped: usize,
    pub dry_run: bool,
}

pub fn remove_reusable_audit_caches(
    requested_root: &Path,
    dry_run: bool,
) -> std::io::Result<AuditCacheRemovalReport> {
    let mut paths = vec![reusable_audit_worktree_path(requested_root)];
    paths.extend(scan_legacy_reusable_cache_paths(
        requested_root,
        &std::env::temp_dir(),
    ));
    if git_toplevel(requested_root).is_some_and(|root| paths_equal(&root, requested_root)) {
        paths.extend(scan_root_owned_cache_paths(requested_root));
    }
    paths.sort();
    paths.dedup();

    let mut report = AuditCacheRemovalReport {
        found: 0,
        removed: 0,
        skipped: 0,
        dry_run,
    };
    for path in paths {
        if !reusable_cache_entry_exists(&path) {
            continue;
        }
        report.found += 1;
        if dry_run {
            // A preview must not touch the filesystem. Acquiring the lock would
            // create the `.lock` sidecar (create_new) for entries that lack one,
            // violating the documented --dry-run contract. Contention is a race
            // only the real removal reports.
            continue;
        }
        let Some(_lock) = ReusableWorktreeLock::try_acquire(&path) else {
            report.skipped += 1;
            continue;
        };
        if remove_reusable_cache_entry_locked(requested_root, &path)? {
            report.removed += 1;
        }
    }
    Ok(report)
}

fn reusable_cache_entry_exists(path: &Path) -> bool {
    path_entry_exists(path)
        || path_entry_exists(&reusable_worktree_sha_path(path))
        || path_entry_exists(&reusable_worktree_last_used_path(path))
}

fn path_entry_exists(path: &Path) -> bool {
    std::fs::symlink_metadata(path).is_ok()
}

/// Remove one reusable cache while its caller holds the entry's exclusive
/// lock. Absence is success. The lock sidecar is deliberately preserved.
fn remove_reusable_cache_entry_locked(repo_root: &Path, path: &Path) -> std::io::Result<bool> {
    let existed = reusable_cache_entry_exists(path);
    ensure_cache_entry_is_owned(path)?;
    if trusted_worktree_admin_dir(repo_root, path).is_some() {
        unregister_worktree_checked(repo_root, path)?;
    }
    remove_dir_if_exists(path)?;
    remove_file_if_exists(&reusable_worktree_sha_path(path))?;
    remove_file_if_exists(&reusable_worktree_last_used_path(path))?;
    Ok(existed)
}

#[cfg(unix)]
fn ensure_cache_entry_is_owned(path: &Path) -> std::io::Result<()> {
    use std::os::unix::fs::MetadataExt as _;

    let effective_uid = rustix::process::geteuid().as_raw();
    for entry in [
        path.to_path_buf(),
        reusable_worktree_sha_path(path),
        reusable_worktree_last_used_path(path),
    ] {
        let metadata = match std::fs::symlink_metadata(&entry) {
            Ok(metadata) => metadata,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
            Err(error) => return Err(error),
        };
        if metadata.uid() != effective_uid {
            return Err(std::io::Error::new(
                std::io::ErrorKind::PermissionDenied,
                format!(
                    "refusing to remove unowned audit cache entry `{}`",
                    entry.display()
                ),
            ));
        }
    }
    Ok(())
}

#[cfg(not(unix))]
#[expect(
    clippy::unnecessary_wraps,
    reason = "shared cross-platform signature; the Unix ownership check is fallible, non-Unix has no POSIX owner to verify"
)]
fn ensure_cache_entry_is_owned(_path: &Path) -> std::io::Result<()> {
    Ok(())
}

fn remove_dir_if_exists(path: &Path) -> std::io::Result<()> {
    match std::fs::remove_dir_all(path) {
        Ok(()) => Ok(()),
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(err) => Err(err),
    }
}

fn remove_file_if_exists(path: &Path) -> std::io::Result<()> {
    match std::fs::remove_file(path) {
        Ok(()) => Ok(()),
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(err) => Err(err),
    }
}

/// Deregister a freshly-added audit worktree from git while KEEPING its
/// directory on disk (issue #1815).
///
/// Targets the single admin dir this worktree owns via its `.git` gitfile
/// pointer, rather than a global `git worktree prune`, so a user's unrelated
/// prunable worktrees are never collaterally deregistered and git's
/// name-collision admin suffixing (`<name>1`) is handled for free. The `.git`
/// gitfile is REPLACED with an invalid stub (see [`UNREGISTERED_GITDIR_STUB`]),
/// never deleted.
pub fn unregister_worktree(repo_root: &Path, path: &Path) -> std::io::Result<()> {
    unregister_worktree_checked(repo_root, path)
}

fn unregister_worktree_checked(repo_root: &Path, path: &Path) -> std::io::Result<()> {
    if !path.exists() {
        return Ok(());
    }
    let gitfile = path.join(".git");
    let metadata = std::fs::symlink_metadata(&gitfile)?;
    if !metadata_is_regular_file(&metadata) {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            "refusing to deregister through a non-file audit worktree .git entry",
        ));
    }
    let contents = std::fs::read_to_string(&gitfile)?;
    if contents == UNREGISTERED_GITDIR_STUB {
        return Ok(());
    }
    let Some(admin_dir) = trusted_worktree_admin_dir(repo_root, path) else {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            "refusing to deregister an unverified audit worktree admin entry",
        ));
    };
    remove_dir_if_exists(&admin_dir)?;
    write_git_stub_safely(&gitfile)
}

/// Ensure a cache hit's `.git` stub stays valid. Recreates the stub if the
/// gitfile is gone (so gitignore parity holds), and deregisters in place if a
/// live pointer to a fallow admin dir is found (a mixed-version re-registration
/// or a torn transient window).
fn repair_unregistered_git_stub(path: &Path) -> bool {
    let gitfile = path.join(".git");
    let Ok(metadata) = std::fs::symlink_metadata(&gitfile) else {
        return write_git_stub_safely(&gitfile).is_ok();
    };
    if !metadata_is_regular_file(&metadata) {
        return false;
    }
    std::fs::read_to_string(&gitfile).is_ok_and(|contents| contents == UNREGISTERED_GITDIR_STUB)
}

fn write_git_stub_safely(gitfile: &Path) -> std::io::Result<()> {
    let mut options = std::fs::OpenOptions::new();
    options.write(true).truncate(true);
    match std::fs::symlink_metadata(gitfile) {
        Ok(metadata) if metadata_is_regular_file(&metadata) => {}
        Ok(_) => {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                "refusing to replace non-file audit worktree .git entry",
            ));
        }
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            options.create_new(true);
        }
        Err(error) => return Err(error),
    }
    let mut file = options.open(gitfile)?;
    file.write_all(UNREGISTERED_GITDIR_STUB.as_bytes())?;
    file.sync_all()
}

fn trusted_worktree_admin_dir(repo_root: &Path, path: &Path) -> Option<PathBuf> {
    let gitfile = path.join(".git");
    let metadata = std::fs::symlink_metadata(&gitfile).ok()?;
    if !metadata_is_regular_file(&metadata) {
        return None;
    }
    let contents = std::fs::read_to_string(&gitfile).ok()?;
    let admin_dir = parse_worktree_gitdir(&contents)?;
    if !is_fallow_admin_dir(&admin_dir) {
        return None;
    }
    let common_dir = fallow_engine::changed_files::resolve_git_common_dir(repo_root).ok()?;
    let worktrees_dir = dunce::canonicalize(common_dir.join("worktrees")).ok()?;
    let admin_parent = dunce::canonicalize(admin_dir.parent()?).ok()?;
    if admin_parent != worktrees_dir {
        return None;
    }
    let backlink = std::fs::read_to_string(admin_dir.join("gitdir")).ok()?;
    let expected_gitfile = dunce::canonicalize(&gitfile).ok()?;
    let actual_gitfile = dunce::canonicalize(Path::new(backlink.trim())).ok()?;
    (actual_gitfile == expected_gitfile).then_some(admin_dir)
}

/// Parse the `gitdir: <path>` pointer from a linked-worktree `.git` gitfile.
fn parse_worktree_gitdir(contents: &str) -> Option<PathBuf> {
    contents
        .lines()
        .find_map(|line| line.trim().strip_prefix("gitdir:"))
        .map(|rest| PathBuf::from(rest.trim()))
}

/// True when an admin dir basename is one fallow itself created, used as a
/// safety belt before removing it.
fn is_fallow_admin_dir(admin_dir: &Path) -> bool {
    admin_dir
        .file_name()
        .and_then(|name| name.to_str())
        .is_some_and(|name| name.starts_with("fallow-audit-base-"))
}

pub fn git_rev_parse(root: &Path, rev: &str) -> Option<String> {
    let mut command = Command::new("git");
    command.args(["rev-parse", rev]).current_dir(root);
    clear_ambient_git_env(&mut command);
    let output = command.output().ok()?;
    if !output.status.success() {
        return None;
    }
    Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
}

pub fn git_toplevel(root: &Path) -> Option<PathBuf> {
    let mut command = Command::new("git");
    command
        .args(["rev-parse", "--show-toplevel"])
        .current_dir(root);
    clear_ambient_git_env(&mut command);
    let output = command.output().ok()?;
    if !output.status.success() {
        return None;
    }
    let path = PathBuf::from(String::from_utf8_lossy(&output.stdout).trim());
    Some(dunce::canonicalize(&path).unwrap_or(path))
}

fn audit_worktree_is_registered(repo_root: &Path, path: &Path) -> bool {
    let Some(worktrees) = list_audit_worktrees(repo_root) else {
        return false;
    };
    worktrees.iter().any(|worktree| paths_equal(worktree, path))
}

pub fn paths_equal(left: &Path, right: &Path) -> bool {
    if left == right {
        return true;
    }
    match (dunce::canonicalize(left), dunce::canonicalize(right)) {
        (Ok(left), Ok(right)) => left == right,
        _ => false,
    }
}

pub fn remove_audit_worktree(repo_root: &Path, path: &Path) {
    let mut command = Command::new("git");
    command
        .args([
            "worktree",
            "remove",
            "--force",
            path.to_string_lossy().as_ref(),
        ])
        .current_dir(repo_root);
    clear_ambient_git_env(&mut command);
    match crate::signal::scoped_child::output(&mut command) {
        Ok(output) => {
            if !output.status.success() && path.exists() {
                let stderr = String::from_utf8_lossy(&output.stderr);
                tracing::warn!(
                    path = %path.display(),
                    stderr = %stderr.trim(),
                    "git worktree remove failed; the directory remains and may leak",
                );
            }
        }
        Err(err) => {
            tracing::warn!(
                path = %path.display(),
                error = %err,
                "git worktree remove subprocess failed to spawn",
            );
        }
    }
}

pub fn sweep_orphan_audit_worktrees(repo_root: &Path) {
    sweep_orphan_audit_worktrees_in(repo_root, &std::env::temp_dir());
}

/// `temp_root` is the directory scanned for unregistered dead-pid worktree
/// directories. Production always passes `std::env::temp_dir()`; tests pass a
/// private root because a fabricated dead-pid fixture in the SHARED temp dir
/// is legitimate prey for any concurrent sweep (a parallel test or a spawned
/// fallow binary), which races the fixture's own assertions.
pub fn sweep_orphan_audit_worktrees_in(repo_root: &Path, temp_root: &Path) {
    // Legacy pass: deregister dead-pid non-reusable worktrees left REGISTERED
    // by pre-#1815 fallow (or by a crash in the transient registration
    // window). The `--expire=now` prune, retained only here, also sweeps any
    // now-dangling admin entry.
    if deregister_legacy_orphan_worktrees(repo_root) {
        let mut command = Command::new("git");
        command
            .args(["worktree", "prune", "--expire=now"])
            .current_dir(repo_root);
        clear_ambient_git_env(&mut command);
        let _ = command.output();
    }

    // Primary pass: remove unregistered dead-pid worktree DIRECTORIES via a
    // temp-dir prefix scan. A dead PID means the owning process is gone
    // regardless of repo, so this scan is global (not repo-scoped).
    for path in scan_non_reusable_orphan_paths(temp_root) {
        let _ = std::fs::remove_dir_all(&path);
    }
}

/// Deregister dead-pid non-reusable worktrees left REGISTERED by pre-#1815
/// fallow or by a crash mid-registration. Returns `true` when any were removed.
fn deregister_legacy_orphan_worktrees(repo_root: &Path) -> bool {
    let Some(worktrees) = list_audit_worktrees(repo_root) else {
        return false;
    };
    let mut removed_any = false;
    for path in worktrees {
        if !is_fallow_audit_worktree_path(&path)
            || is_reusable_audit_worktree_path(&path)
            || audit_worktree_process_is_alive(&path)
        {
            continue;
        }
        remove_audit_worktree(repo_root, &path);
        let _ = std::fs::remove_dir_all(&path);
        removed_any = true;
    }
    removed_any
}

/// Enumerate unregistered non-reusable worktree DIRECTORY paths owned by a
/// dead PID. Reusable caches yield no parseable PID and are skipped.
fn scan_non_reusable_orphan_paths(temp: &Path) -> Vec<PathBuf> {
    let Ok(entries) = std::fs::read_dir(temp) else {
        return Vec::new();
    };
    let mut paths = Vec::new();
    for entry in entries.flatten() {
        let name = entry.file_name();
        let Some(name) = name.to_str() else {
            continue;
        };
        let Some(pid) = audit_worktree_pid(name) else {
            continue;
        };
        if process_is_alive(pid) || !entry.path().is_dir() {
            continue;
        }
        paths.push(temp.join(name));
    }
    paths
}

pub fn list_audit_worktrees(repo_root: &Path) -> Option<Vec<PathBuf>> {
    let mut command = Command::new("git");
    command
        .args(["worktree", "list", "--porcelain"])
        .current_dir(repo_root);
    clear_ambient_git_env(&mut command);
    let output = command.output().ok()?;
    if !output.status.success() {
        return None;
    }
    Some(parse_worktree_list(&String::from_utf8_lossy(
        &output.stdout,
    )))
}

pub fn parse_worktree_list(output: &str) -> Vec<PathBuf> {
    output
        .lines()
        .filter_map(|line| line.strip_prefix("worktree "))
        .map(PathBuf::from)
        .filter(|path| is_fallow_audit_worktree_path(path))
        .collect()
}

pub fn is_fallow_audit_worktree_path(path: &Path) -> bool {
    let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
        return false;
    };
    name.starts_with("fallow-audit-base-") && path_is_inside_temp_dir(path)
}

pub fn is_reusable_audit_worktree_path(path: &Path) -> bool {
    path.file_name()
        .and_then(|name| name.to_str())
        .is_some_and(|name| name.starts_with("fallow-audit-base-cache-"))
}

fn path_is_inside_temp_dir(path: &Path) -> bool {
    let temp = std::env::temp_dir();
    let simple_path = dunce::simplified(path);
    let simple_temp = dunce::simplified(&temp);
    if simple_path.starts_with(simple_temp) {
        return true;
    }
    let Ok(canonical_temp) = std::fs::canonicalize(&temp) else {
        return false;
    };
    let simple_canonical_temp = dunce::simplified(&canonical_temp);
    simple_path.starts_with(simple_canonical_temp)
        || std::fs::canonicalize(path).is_ok_and(|canonical_path| {
            dunce::simplified(&canonical_path).starts_with(simple_canonical_temp)
        })
}

fn audit_worktree_process_is_alive(path: &Path) -> bool {
    let Some(pid) = path
        .file_name()
        .and_then(|name| name.to_str())
        .and_then(audit_worktree_pid)
    else {
        return false;
    };
    process_is_alive(pid)
}

pub fn audit_worktree_pid(name: &str) -> Option<u32> {
    name.strip_prefix("fallow-audit-base-")?
        .split('-')
        .next()?
        .parse()
        .ok()
}

#[cfg(unix)]
pub fn process_is_alive(pid: u32) -> bool {
    Command::new("kill")
        .args(["-0", &pid.to_string()])
        .output()
        .is_ok_and(|output| output.status.success())
}

#[cfg(windows)]
pub fn process_is_alive(pid: u32) -> bool {
    windows_process::is_alive(pid)
}

#[cfg(not(any(unix, windows)))]
pub fn process_is_alive(_pid: u32) -> bool {
    true
}

#[cfg(windows)]
#[allow(
    unsafe_code,
    reason = "Win32 process-query API (OpenProcess / WaitForSingleObject / CloseHandle / GetLastError) requires unsafe FFI"
)]
mod windows_process {
    use windows_sys::Win32::Foundation::{
        CloseHandle, ERROR_ACCESS_DENIED, ERROR_INVALID_PARAMETER, GetLastError, HANDLE,
        WAIT_OBJECT_0,
    };
    use windows_sys::Win32::System::Threading::{
        OpenProcess, PROCESS_QUERY_LIMITED_INFORMATION, WaitForSingleObject,
    };

    /// RAII wrapper that calls `CloseHandle` on drop, mirroring `std::mem::drop`
    /// semantics for kernel handles. Used so every exit path through
    /// `is_alive` releases the handle without manual cleanup.
    struct ProcessHandle(HANDLE);

    impl Drop for ProcessHandle {
        fn drop(&mut self) {
            // SAFETY: `self.0` is a non-null handle obtained from a successful
            // `OpenProcess` call. We have unique ownership (the value is only
            // ever created inside `is_alive`), so this is the sole consumer.
            unsafe {
                CloseHandle(self.0);
            }
        }
    }

    /// Cross-platform PID liveness check for Windows.
    ///
    /// Mirrors `kill -0 $pid` semantics: returns `true` when the process is
    /// running OR when we cannot prove it dead (e.g., `ERROR_ACCESS_DENIED` on
    /// processes owned by another session). Returns `false` only when the PID
    /// definitively does not exist (`ERROR_INVALID_PARAMETER`) or the wait
    /// reports the process has exited.
    pub fn is_alive(pid: u32) -> bool {
        // SAFETY: `OpenProcess` accepts any `u32` PID; it either returns a
        // non-null handle we own, or null on failure with `GetLastError`
        // describing why. No memory is borrowed across the FFI boundary.
        let raw = unsafe { OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid) };
        if raw.is_null() {
            // SAFETY: `GetLastError` reads thread-local storage set by the
            // failing `OpenProcess` call. It has no preconditions.
            let err = unsafe { GetLastError() };
            #[expect(
                clippy::match_same_arms,
                reason = "named arm documents the cross-session case"
            )]
            return match err {
                ERROR_INVALID_PARAMETER => false,
                ERROR_ACCESS_DENIED => true,
                _ => true,
            };
        }
        let handle = ProcessHandle(raw);
        // SAFETY: `handle.0` is non-null (checked above) and owned by the
        // `ProcessHandle` RAII wrapper.
        let wait_result = unsafe { WaitForSingleObject(handle.0, 0) };
        wait_result != WAIT_OBJECT_0
    }
}

impl Drop for BaseWorktree {
    fn drop(&mut self) {
        if self.persistent {
            return;
        }
        // The non-reusable worktree was deregistered right after creation, so
        // cleanup is a plain directory removal: no `git` subprocess runs, and
        // a SIGKILL before this Drop can never leave an admin entry behind.
        let _ = std::fs::remove_dir_all(&self.path);
    }
}

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

    /// Many threads minting a non-reusable worktree path at the same instant
    /// must each get a distinct path. Before the monotonic counter, concurrent
    /// callers read the same non-monotonic `nanos` and collided, so two parallel
    /// `audit` runs in one process raced on `git worktree add` and one aborted
    /// with a generic error (a flaky exit 2 under parallel unit tests).
    #[test]
    fn non_reusable_worktree_paths_are_unique_under_concurrency() {
        const N: usize = 64;
        let barrier = std::sync::Barrier::new(N);
        let paths = std::sync::Mutex::new(Vec::with_capacity(N));
        std::thread::scope(|s| {
            for _ in 0..N {
                let barrier = &barrier;
                let paths = &paths;
                s.spawn(move || {
                    barrier.wait();
                    let path = non_reusable_worktree_path().expect("path should build");
                    paths.lock().unwrap().push(path);
                });
            }
        });
        let mut paths = paths.into_inner().unwrap();
        assert_eq!(paths.len(), N);
        paths.sort();
        paths.dedup();
        assert_eq!(paths.len(), N, "non-reusable worktree paths collided");
    }

    /// The pid stays the first segment so orphan-sweep parsing keeps working.
    #[test]
    fn non_reusable_worktree_path_pid_is_parseable() {
        let path = non_reusable_worktree_path().expect("path should build");
        let name = path.file_name().unwrap().to_str().unwrap();
        assert!(is_fallow_audit_worktree_path(&path));
        assert!(!is_reusable_audit_worktree_path(&path));
        assert_eq!(audit_worktree_pid(name), Some(std::process::id()));
    }

    #[cfg(unix)]
    #[test]
    fn cache_sidecar_open_does_not_follow_symlinks() {
        let temp = tempfile::TempDir::new().expect("temp dir should be created");
        let victim = temp.path().join("victim");
        let sidecar = temp.path().join("cache.lock");
        std::fs::write(&victim, "unchanged\n").expect("victim should be written");
        std::os::unix::fs::symlink(&victim, &sidecar).expect("sidecar symlink should be created");

        assert!(open_or_create_owned_sidecar(&sidecar).is_err());
        assert_eq!(
            std::fs::read_to_string(victim).expect("victim should remain readable"),
            "unchanged\n",
        );
    }
}