monochromatic-git-policy-cli 0.5.27

//! What:
//!  Controls for the clearing of reference locks that a killed Git left behind.
//! Why:
//!  The clearing deletes files in a repository, so each condition that lets a lock go is pinned on both sides: the lock of a
//!  Git killed with `SIGKILL` goes, and the lock of a Git that runs, of a process that holds it open, of a holder that has
//!  not been shown gone, and a lock that is too new, stays. The locks come from real Git in disposable repositories.
//!
//! In TS you'd write (pseudocode):
//! ```ts
//! held.kill('SIGKILL'); expect(clearStaleRefLocks(roots, judge).cleared).toHaveLength(2); expect(lockFiles(gitDir)).toEqual([]);
//! ```
#![cfg(unix)]

use super::*;
use crate::stale_ref_lock_judge::BOOT_SLACK;
use crate::stale_ref_lock_killed_git as killed;
use crate::stale_ref_lock_killed_git::{Held, Helper, Stage, GONE_REF};
use crate::test_support::{git_output, remove};
use std::path::{Path, PathBuf};
use std::process::{Child, Command, Stdio};
use std::time::{Duration, SystemTime};

/// A judge that sees the processes of this kernel completely, takes any lock as old enough, and trusts local disks.
fn judge() -> Judge {
    return Judge { margin: Duration::ZERO, pid_view_complete: true, boot: None, ..Judge::here() };
}

/// A process number that no running process has: one that has just ended.
fn ended_pid() -> i64 {
    let mut child: Child = Command::new("true").spawn().expect("start true");
    let pid: i64 = i64::from(child.id());
    child.wait().expect("reap true");
    return pid;
}

/// A long-running process whose command name is not `git`.
fn sleeper() -> Helper {
    return Helper(Command::new("sleep").arg("120").stdin(Stdio::null()).spawn().expect("start sleep"));
}

/// Write an empty lock and, when `pid` is given, the pid file Git would have written beside it after the lock.
fn plant_lock(stage: &Stage, reference: &str, pid: Option<i64>) {
    killed::write_file(stage.lock_of(reference).as_path(), "");
    if let Some(number) = pid {
        std::thread::sleep(Duration::from_millis(20));
        killed::write_file(stage.pid_file_of(reference).as_path(), &format!("pid {number}\n"));
    }
}

/// The reference the planted locks belong to.
const PLANTED_REF: &str = "refs/heads/planted";

/// Every file below the Git directory whose name ends in `.lock` or is the packed staging file, sorted.
fn leftovers(stage: &Stage) -> Vec<PathBuf> {
    let mut found: Vec<PathBuf> = Vec::new();
    let mut pending: Vec<PathBuf> = vec![stage.git_dir.clone()];
    while let Some(directory) = pending.pop() {
        for entry in std::fs::read_dir(directory.as_path()).expect("read the directory").flatten() {
            let path: PathBuf = entry.path();
            if entry.file_type().expect("file type").is_dir() {
                pending.push(path);
            } else if path.to_string_lossy().ends_with(".lock") || path.ends_with("packed-refs.new") {
                found.push(path);
            }
        }
    }
    found.sort();
    return found;
}

/// The verdict a pass gave one lock, wherever it landed.
fn verdict_of(outcome: &Outcome, lock: &Path) -> Option<Verdict> {
    return outcome.cleared.iter().chain(outcome.left.iter()).find(|found| { return found.lock == lock; }).map(|found| { return found.verdict.clone(); });
}

/// The fetch that failed in practice runs again, with the hook gone.
fn fetch_works(stage: &Stage) {
    let _removed = std::fs::remove_file(stage.git_dir.join("hooks").join("reference-transaction"));
    let fetched = git_output(stage.repo.as_path(), &["fetch", "--prune", "--quiet", "origin"]);
    assert!(fetched.status.success(), "the following fetch failed: {}", String::from_utf8_lossy(&fetched.stderr));
}

/// Locks that a fetch killed with `SIGKILL` left, with the pid files that name it, go with their staging file; the next fetch works.
#[test]
fn locks_left_by_a_killed_fetch_are_cleared_and_the_next_fetch_works() {
    let stage: Stage = killed::stage("stale-refs-killed-fetch", true);
    let mut held: Held = killed::hold_fetch(&stage);
    assert!(stage.lock_of(GONE_REF).exists() && stage.packed_lock().exists() && stage.packed_staging().exists(), "the fetch holds its locks");
    assert_eq!(std::fs::metadata(stage.lock_of(GONE_REF)).expect("lock").len(), 0, "a deleted reference's lock is empty");
    held.kill();
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert_eq!(outcome.cleared.len(), 2, "{outcome:?}");
    assert_eq!(leftovers(&stage), Vec::<PathBuf>::new());
    assert_eq!(verdict_of(&outcome, stage.packed_lock().as_path()), Some(Verdict::Stale(Proof::PidGone(i64::from(held.pid())))));
    fetch_works(&stage);
    stage.finish();
}

/// Without `core.lockfilePid` nothing names the holder: the locks stay and are reported, never removed.
#[test]
fn locks_of_a_killed_fetch_with_no_pid_file_stay() {
    let stage: Stage = killed::stage("stale-refs-no-pid-file", false);
    let mut held: Held = killed::hold_fetch(&stage);
    held.kill();
    let before: Vec<PathBuf> = leftovers(&stage);
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert_eq!(leftovers(&stage), before);
    assert!(matches!(verdict_of(&outcome, stage.lock_of(GONE_REF).as_path()), Some(Verdict::Unproven(_))), "{outcome:?}");
    stage.finish();
}

/// A Git that runs holds locks with no descriptor open; a pid file that names it keeps every one of them.
#[test]
fn locks_of_a_running_git_stay_though_no_descriptor_holds_them() {
    let stage: Stage = killed::stage("stale-refs-running", true);
    let held: Held = killed::hold_transaction(&stage, &["delete refs/remotes/origin/gone", "delete refs/remotes/origin/main"]);
    let before: Vec<PathBuf> = leftovers(&stage);
    assert!(before.contains(&stage.packed_lock()) && before.contains(&stage.lock_of(GONE_REF)), "{before:?}");
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert_eq!(leftovers(&stage), before);
    assert!(matches!(verdict_of(&outcome, stage.packed_lock().as_path()), Some(Verdict::Held(_))), "{outcome:?}");
    drop(held);
    stage.finish();
}

/// The same locks with no pid file are not shown gone either.
#[test]
fn locks_of_a_running_git_with_no_pid_file_stay() {
    let stage: Stage = killed::stage("stale-refs-running-no-pid", false);
    let held: Held = killed::hold_transaction(&stage, &["delete refs/remotes/origin/gone"]);
    let before: Vec<PathBuf> = leftovers(&stage);
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert_eq!(leftovers(&stage), before);
    drop(held);
    stage.finish();
}

/// A process that has the lock open is its holder, whatever the pid file says.
#[test]
fn a_lock_that_a_process_holds_open_stays_though_its_pid_file_names_a_gone_process() {
    let stage: Stage = killed::stage("stale-refs-open", true);
    plant_lock(&stage, PLANTED_REF, Some(ended_pid()));
    let lock: PathBuf = stage.lock_of(PLANTED_REF);
    let holder: Helper = Helper(Command::new("sh").arg("-c").arg("exec 3<>\"$1\"; exec sleep 120").arg("sh").arg(lock.as_os_str()).spawn().expect("start the holder"));
    let holder_pid: i64 = holder.pid();
    let descriptors: PathBuf = PathBuf::from(format!("/proc/{holder_pid}/fd"));
    let started: std::time::Instant = std::time::Instant::now();
    while !std::fs::read_dir(descriptors.as_path()).expect("fds").flatten().any(|entry| { return std::fs::read_link(entry.path()).is_ok_and(|target| { return target == lock; }); }) {
        assert!(started.elapsed() < killed::HOLD_PATIENCE, "the holder opened the lock");
        std::thread::sleep(Duration::from_millis(20));
    }
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(lock.exists() && stage.pid_file_of(PLANTED_REF).exists());
    assert!(matches!(verdict_of(&outcome, lock.as_path()), Some(Verdict::Held(_))), "{outcome:?}");
    drop(holder);
    stage.finish();
}

/// A lock younger than the margin is not judged: a live Git may have just made it.
#[test]
fn a_lock_inside_the_margin_stays_and_goes_once_it_is_older() {
    let stage: Stage = killed::stage("stale-refs-margin", true);
    let mut held: Held = killed::hold_fetch(&stage);
    held.kill();
    let before: Vec<PathBuf> = leftovers(&stage);
    let strict: Judge = Judge { margin: Duration::from_secs(3600), ..judge() };
    let young: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &strict);
    assert!(!young.cleared_any() && young.left.is_empty(), "a lock inside the margin is left without a word: {young:?}");
    assert_eq!(leftovers(&stage), before);
    let aged: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(aged.cleared_any(), "{aged:?}");
    stage.finish();
}

/// A pid file born before the lock was written by an earlier holder; it does not name this lock's holder.
#[test]
fn a_pid_file_born_before_the_lock_is_not_evidence() {
    let stage: Stage = killed::stage("stale-refs-older-pid-file", true);
    killed::write_file(stage.pid_file_of(PLANTED_REF).as_path(), &format!("pid {}\n", ended_pid()));
    std::thread::sleep(Duration::from_millis(50));
    killed::write_file(stage.lock_of(PLANTED_REF).as_path(), "");
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    assert!(matches!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Unproven(_))), "{outcome:?}");
    stage.finish();
}

/// A number that a program other than Git now has, having started after the lock was made, is not the holder, which ended.
#[test]
fn a_process_number_now_held_by_another_program_proves_the_holder_gone() {
    let stage: Stage = killed::stage("stale-refs-reused", true);
    killed::write_file(stage.lock_of(PLANTED_REF).as_path(), "");
    std::thread::sleep(Duration::from_millis(400));
    let other: Helper = sleeper();
    std::thread::sleep(Duration::from_millis(50));
    killed::write_file(stage.pid_file_of(PLANTED_REF).as_path(), &format!("pid {}\n", other.pid()));
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert_eq!(outcome.cleared.len(), 1, "{outcome:?}");
    assert!(matches!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Stale(Proof::PidReused { .. }))), "{outcome:?}");
    drop(other);
    stage.finish();
}

/// A running program that is not named Git but started before the lock was made may be a Git under another name: it is
/// taken for the holder.
#[test]
fn a_process_that_started_before_the_lock_is_the_holder_whatever_its_name() {
    let stage: Stage = killed::stage("stale-refs-renamed-git", true);
    let other: Helper = sleeper();
    std::thread::sleep(Duration::from_millis(400));
    plant_lock(&stage, PLANTED_REF, Some(other.pid()));
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(matches!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Held(_))), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    drop(other);
    stage.finish();
}

/// A running Git that the pid file names is taken for the holder.
#[test]
fn a_running_git_named_by_the_pid_file_is_the_holder() {
    let stage: Stage = killed::stage("stale-refs-running-git", true);
    let idle: Held = killed::idle_git(&stage);
    plant_lock(&stage, PLANTED_REF, Some(i64::from(idle.pid())));
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    assert!(matches!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Held(_))), "{outcome:?}");
    drop(idle);
    stage.finish();
}

/// A lock older than the boot has no holder; this proof is used only when no pid file speaks.
#[test]
fn a_lock_older_than_the_boot_goes_when_no_pid_file_names_a_holder() {
    let stage: Stage = killed::stage("stale-refs-boot", false);
    plant_lock(&stage, PLANTED_REF, None);
    let after: Judge = Judge { boot: Some(SystemTime::now() + BOOT_SLACK * 2), ..judge() };
    let before: Judge = Judge { boot: Some(SystemTime::now() - Duration::from_secs(3600)), ..judge() };
    let younger: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &before);
    assert!(!younger.cleared_any(), "a lock younger than the boot stays: {younger:?}");
    let within: Judge = Judge { boot: Some(SystemTime::now() + BOOT_SLACK / 2), ..judge() };
    let slack: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &within);
    assert!(!slack.cleared_any(), "a lock older than the boot by less than the slack stays, the clock may have stepped: {slack:?}");
    let older: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &after);
    assert_eq!(verdict_of(&older, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Stale(Proof::BeforeBoot)), "{older:?}");
    assert!(!stage.lock_of(PLANTED_REF).exists());
    stage.finish();
}

/// A running Git named by a pid file outranks the boot proof.
#[test]
fn the_boot_proof_does_not_override_a_pid_file_that_names_a_running_git() {
    let stage: Stage = killed::stage("stale-refs-boot-vs-pid", true);
    let idle: Held = killed::idle_git(&stage);
    plant_lock(&stage, PLANTED_REF, Some(i64::from(idle.pid())));
    let after: Judge = Judge { boot: Some(SystemTime::now() + BOOT_SLACK * 2), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &after);
    assert!(!outcome.cleared_any(), "{outcome:?}");
    drop(idle);
    stage.finish();
}

/// A view of the processes that may be another namespace's proves nothing about a pid file.
#[test]
fn a_view_of_processes_that_may_be_partial_proves_nothing() {
    let stage: Stage = killed::stage("stale-refs-partial-view", true);
    plant_lock(&stage, PLANTED_REF, Some(ended_pid()));
    let partial: Judge = Judge { pid_view_complete: false, ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &partial);
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    stage.finish();
}

/// A lock on a file system that is not on the local list may be held by a Git on another machine.
#[test]
fn a_file_system_off_the_local_list_proves_nothing() {
    let stage: Stage = killed::stage("stale-refs-remote-fs", true);
    plant_lock(&stage, PLANTED_REF, Some(ended_pid()));
    let nowhere: Judge = Judge { local_file_systems: Vec::new(), boot: Some(SystemTime::now() + BOOT_SLACK * 2), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &nowhere);
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    stage.finish();
}

/// A process table that cannot be listed shows no holder, which is not the same as none.
#[test]
fn an_unreadable_process_table_proves_nothing() {
    let stage: Stage = killed::stage("stale-refs-no-proc", true);
    plant_lock(&stage, PLANTED_REF, Some(ended_pid()));
    let blind: Judge = Judge { proc_root: stage.root.join("no-such-proc"), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &blind);
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    stage.finish();
}

/// Locks of other protocols, and pid files alone, are never touched, whatever else is proven.
#[test]
fn locks_of_other_protocols_are_never_candidates() {
    let stage: Stage = killed::stage("stale-refs-other-locks", false);
    let others: Vec<PathBuf> = vec![
        stage.git_dir.join("index.lock"),
        stage.git_dir.join("config.lock"),
        stage.git_dir.join("shallow.lock"),
        stage.git_dir.join("objects").join("pack").join("tmp.lock"),
        stage.git_dir.join("refs").join("heads").join("alone~pid.lock"),
    ];
    for path in &others {
        killed::write_file(path.as_path(), "");
    }
    let after: Judge = Judge { boot: Some(SystemTime::now() + BOOT_SLACK * 2), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &after);
    assert!(!outcome.cleared_any() && outcome.left.is_empty(), "{outcome:?}");
    for path in &others {
        assert!(path.exists(), "{path:?}");
    }
    stage.finish();
}

/// A reference named with shell and path characters is handled as the literal name it is.
#[test]
fn a_reference_with_shell_and_path_characters_is_cleared_literally() {
    let stage: Stage = killed::stage("stale-refs-adversarial", true);
    let name: &str = "refs/heads/it's$(touch${IFS}pwned);`id`&x|(y)";
    let mut held: Held = killed::hold_transaction(&stage, &[format!("create {name} HEAD").as_str()]);
    assert!(stage.lock_of(name).exists(), "Git holds the lock of the odd name");
    held.kill();
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert_eq!(outcome.cleared.len(), 1, "{outcome:?}");
    assert_eq!(leftovers(&stage), Vec::<PathBuf>::new());
    assert!(!stage.repo.join("pwned").exists() && !Path::new("pwned").exists(), "nothing was run");
    stage.finish();
}

/// A symbolic link is never followed and never removed, whether it stands for a directory or for a lock.
#[test]
fn symbolic_links_are_neither_followed_nor_removed() {
    let stage: Stage = killed::stage("stale-refs-symlinks", true);
    let outside: PathBuf = stage.root.join("outside");
    killed::write_file(outside.join("x.lock").as_path(), "");
    killed::write_file(outside.join("target.lock").as_path(), "");
    let heads: PathBuf = stage.git_dir.join("refs").join("heads");
    std::os::unix::fs::symlink(outside.as_path(), heads.join("linked-directory")).expect("link a directory");
    std::os::unix::fs::symlink(outside.join("target.lock"), heads.join("linked.lock")).expect("link a lock");
    let after: Judge = Judge { boot: Some(SystemTime::now() + BOOT_SLACK * 2), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &after);
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(outside.join("x.lock").exists() && outside.join("target.lock").exists());
    assert!(std::fs::symlink_metadata(heads.join("linked.lock")).is_ok());
    remove(stage.root.as_path());
}

/// A lock that cannot be set aside is left and reported, not retried and not an error.
#[test]
fn a_lock_in_a_directory_that_cannot_be_written_is_left() {
    use std::os::unix::fs::PermissionsExt as _;
    let stage: Stage = killed::stage("stale-refs-unwritable", true);
    plant_lock(&stage, PLANTED_REF, Some(ended_pid()));
    let directory: PathBuf = stage.git_dir.join("refs").join("heads");
    std::fs::set_permissions(directory.as_path(), std::fs::Permissions::from_mode(0o555)).expect("make read-only");
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    std::fs::set_permissions(directory.as_path(), std::fs::Permissions::from_mode(0o755)).expect("make writable");
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    assert!(matches!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Unproven(_))), "{outcome:?}");
    stage.finish();
}

/// A path that a live Git took again after the judgement is put back whole, never removed.
#[test]
fn a_lock_taken_again_after_the_judgement_is_put_back() {
    let stage: Stage = killed::stage("stale-refs-retaken", true);
    plant_lock(&stage, PLANTED_REF, Some(ended_pid()));
    let lock: PathBuf = stage.lock_of(PLANTED_REF);
    let judged = crate::stale_ref_lock_judge::identity_of(lock.as_path()).expect("identity");
    std::fs::remove_file(lock.as_path()).expect("the stale lock is removed by another wrapper");
    killed::write_file(lock.as_path(), "live holder's content\n");
    let mut outcome: Outcome = Outcome::default();
    let removed = crate::stale_ref_lock_retire::remove_if_unchanged(stage.git_dir.as_path(), lock.as_path(), &judged, &mut outcome);
    assert_eq!(removed, Ok(false));
    assert_eq!(std::fs::read_to_string(lock.as_path()).expect("the live lock"), "live holder's content\n");
    assert!(outcome.displaced.is_empty(), "{outcome:?}");
    stage.finish();
}

/// The Git directories of a command come from its working directory, without starting Git.
#[test]
fn the_roots_of_a_command_are_found_without_git() {
    let stage: Stage = killed::stage("stale-refs-roots", false);
    let mut command: Command = Command::new("git");
    command.current_dir(stage.repo.as_path());
    assert_eq!(crate::git_directory_roots::roots_of_command(&command), stage.roots());
    stage.finish();
}

/// A process table with one process of this account whose descriptors cannot be read, as `systemd --user` is on a host.
fn table_with_unreadable(stage: &Stage, command: &str) -> PathBuf {
    use std::os::unix::fs::PermissionsExt as _;
    let table: PathBuf = stage.root.join("proc");
    let descriptors: PathBuf = table.join("4242").join("fd");
    std::fs::create_dir_all(descriptors.as_path()).expect("fake process");
    std::fs::write(table.join("4242").join("comm"), format!("{command}\n")).expect("comm");
    std::fs::set_permissions(descriptors.as_path(), std::fs::Permissions::from_mode(0o000)).expect("hide the descriptors");
    return table;
}

/// Make the fake table removable again.
fn reveal(table: &Path) {
    use std::os::unix::fs::PermissionsExt as _;
    std::fs::set_permissions(table.join("4242").join("fd"), std::fs::Permissions::from_mode(0o700)).expect("reveal");
}

/// A process of this account that is not Git and cannot be looked into (the user's service manager) cannot hold a Git lock.
#[test]
fn an_unreadable_process_that_is_not_git_does_not_stop_a_proof() {
    let stage: Stage = killed::stage("stale-refs-unreadable-service", false);
    plant_lock(&stage, PLANTED_REF, None);
    let table: PathBuf = table_with_unreadable(&stage, "systemd");
    let after: Judge = Judge { proc_root: table.clone(), boot: Some(SystemTime::now() + BOOT_SLACK * 2), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &after);
    reveal(table.as_path());
    assert_eq!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Stale(Proof::BeforeBoot)), "{outcome:?}");
    stage.finish();
}

/// A Git process of this account that cannot be looked into may hold the lock, so nothing is proven.
#[test]
fn an_unreadable_git_process_stops_a_proof() {
    let stage: Stage = killed::stage("stale-refs-unreadable-git", false);
    plant_lock(&stage, PLANTED_REF, None);
    let table: PathBuf = table_with_unreadable(&stage, "git");
    let after: Judge = Judge { proc_root: table.clone(), boot: Some(SystemTime::now() + BOOT_SLACK * 2), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &after);
    reveal(table.as_path());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(matches!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Unproven(_))), "{outcome:?}");
    assert!(stage.lock_of(PLANTED_REF).exists());
    stage.finish();
}

/// The staging file of a killed packed-references update stays when its lock was removed by hand; it goes, and the next
/// packed-references update works.
#[test]
fn a_staging_file_with_no_lock_beside_it_is_cleared() {
    let stage: Stage = killed::stage("stale-refs-orphan-staging", true);
    let mut held: Held = killed::hold_fetch(&stage);
    held.kill();
    std::fs::remove_file(stage.packed_lock()).expect("the lock is removed by hand");
    std::fs::remove_file(stage.git_dir.join("packed-refs~pid.lock")).expect("its pid file too");
    assert!(stage.packed_staging().exists());
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!stage.packed_staging().exists(), "{outcome:?}");
    assert_eq!(verdict_of(&outcome, stage.packed_staging().as_path()), Some(Verdict::Stale(Proof::OrphanStaging)), "{outcome:?}");
    assert_eq!(leftovers(&stage), Vec::<PathBuf>::new());
    fetch_works(&stage);
    stage.finish();
}

/// While the lock is there, the staging file is part of a live or killed update that the lock's own judgement decides.
#[test]
fn a_staging_file_with_its_lock_beside_it_is_left_to_the_lock() {
    let stage: Stage = killed::stage("stale-refs-live-staging", true);
    let held: Held = killed::hold_transaction(&stage, &["delete refs/remotes/origin/gone"]);
    assert!(stage.packed_staging().exists(), "the update holds its staging file");
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.packed_staging().exists());
    drop(held);
    stage.finish();
}

/// A staging file younger than the margin may be a live update's whose lock a hand removed a moment ago: it stays.
#[test]
fn a_staging_file_inside_the_margin_stays() {
    let stage: Stage = killed::stage("stale-refs-young-staging", true);
    killed::write_file(stage.packed_staging().as_path(), "# pack-refs with:\n");
    let strict: Judge = Judge { margin: Duration::from_secs(3600), ..judge() };
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &strict);
    assert!(!outcome.cleared_any() && outcome.left.is_empty(), "{outcome:?}");
    assert!(stage.packed_staging().exists());
    stage.finish();
}

/// A Git program started after the lock was made, named by the pid file, is taken for the holder by its name alone.
#[test]
fn a_git_that_started_after_the_lock_is_still_taken_for_the_holder() {
    let stage: Stage = killed::stage("stale-refs-later-git", true);
    killed::write_file(stage.lock_of(PLANTED_REF).as_path(), "");
    std::thread::sleep(Duration::from_millis(400));
    let later: Held = killed::idle_git(&stage);
    std::thread::sleep(Duration::from_millis(50));
    killed::write_file(stage.pid_file_of(PLANTED_REF).as_path(), &format!("pid {}\n", later.pid()));
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(matches!(verdict_of(&outcome, stage.lock_of(PLANTED_REF).as_path()), Some(Verdict::Held(_))), "{outcome:?}");
    drop(later);
    stage.finish();
}

/// A staging file that a process has open is in use, though no lock is beside it.
#[test]
fn a_staging_file_that_a_process_holds_open_stays() {
    let stage: Stage = killed::stage("stale-refs-open-staging", true);
    killed::write_file(stage.packed_staging().as_path(), "# pack-refs with:\n");
    let holder: Helper = Helper(Command::new("sh").arg("-c").arg("exec 3<>\"$1\"; exec sleep 120").arg("sh").arg(stage.packed_staging().as_os_str()).spawn().expect("start the holder"));
    let descriptors: PathBuf = PathBuf::from(format!("/proc/{}/fd", holder.pid()));
    let staging: PathBuf = stage.packed_staging();
    let started: std::time::Instant = std::time::Instant::now();
    while !std::fs::read_dir(descriptors.as_path()).expect("fds").flatten().any(|entry| { return std::fs::read_link(entry.path()).is_ok_and(|target| { return target == staging; }); }) {
        assert!(started.elapsed() < killed::HOLD_PATIENCE, "the holder opened the staging file");
        std::thread::sleep(Duration::from_millis(20));
    }
    let outcome: Outcome = clear_stale_ref_locks(stage.roots().as_slice(), &judge());
    assert!(!outcome.cleared_any(), "{outcome:?}");
    assert!(stage.packed_staging().exists());
    assert!(matches!(verdict_of(&outcome, stage.packed_staging().as_path()), Some(Verdict::Held(_))), "{outcome:?}");
    drop(holder);
    stage.finish();
}