trusty-mpm 1.0.2

//! Unit tests for `provisioner::workspace` (extracted to keep `workspace.rs`
//! under the 500-SLOC production cap after the #1935 base-checkout +
//! per-session worktree rework added `GitBackend::ensure_base_checkout` /
//! `GitBackend::worktree_add` plus their `FakeGitBackend` implementations).
//!
//! Why: splitting the test module into its own file (rather than trimming
//! doc comments or logic in the production code) keeps the Why/What/Test
//! documentation density in the production module intact while satisfying
//! the mechanical SLOC gate (`scripts/check_line_cap.sh`) — this file's
//! basename (`tests.rs`) classifies it under the 1500-SLOC test/benchmark cap.
//! What: `WorkspaceProvisioner`/`FakeGitBackend` unit tests covering path
//! isolation, session-id subdirectory naming, base-checkout reuse across
//! sessions, blank-ref handling, and TASK.md write/skip behaviour.
//! Test: this file IS the test module; run with `cargo test -p trusty-mpm`.

use super::base_lock::{LOCK_STALE_AFTER, lock_is_stale};
use super::*;
use tempfile::TempDir;

fn make_provisioner(root: &TempDir) -> WorkspaceProvisioner<FakeGitBackend> {
    // Skip the global `prepare_session` deploy: these tests verify path
    // isolation only and must not touch the shared `~/.claude/` tree.
    WorkspaceProvisioner::without_prepare(FakeGitBackend::new(), root.path().to_owned())
}

#[test]
fn repo_slug_extraction() {
    assert_eq!(
        repo_slug("https://github.com/owner/trusty-tools"),
        "trusty-tools"
    );
    assert_eq!(
        repo_slug("https://github.com/owner/trusty-tools.git"),
        "trusty-tools"
    );
    assert_eq!(repo_slug("git@github.com:owner/my-repo.git"), "my-repo");
}

#[test]
fn provisioner_isolation_path() {
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let id = ManagedSessionId::new();

    let ws = prov
        .provision(&id, "https://github.com/owner/trusty-tools", "main", "task")
        .unwrap();

    // Path must be inside workspace_root, not the operator's project directory.
    assert!(ws.path.starts_with(root.path()));
    assert!(ws.path.to_string_lossy().contains("trusty-tools"));
    assert!(ws.path.to_string_lossy().contains(&id.to_string()));
}

#[test]
fn provisioner_path_not_in_existing_project() {
    // The workspace must NOT be inside any real project dir.
    // We simulate this by checking the path is inside workspace_root (a tempdir).
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let id = ManagedSessionId::new();

    let ws = prov
        .provision(&id, "https://github.com/owner/myrepo.git", "feat/x", "task")
        .unwrap();

    // Must start with the mpm-owned workspace root, not any other path.
    assert!(ws.path.starts_with(root.path()));
    // Must not be equal to the workspace root itself.
    assert_ne!(&ws.path, root.path());
}

#[test]
fn provisioner_uses_session_id_subdir() {
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let id = ManagedSessionId::new();

    let ws = prov
        .provision(&id, "https://github.com/owner/repo", "main", "task")
        .unwrap();

    // The leaf directory must be the session id.
    let leaf = ws.path.file_name().unwrap().to_string_lossy();
    assert_eq!(leaf.as_ref(), id.to_string());
}

#[test]
fn provision_in_uses_explicit_project_dir() {
    // The #1220 path: caller supplies a pre-resolved `<owner>/<repo>` project
    // dir. #1935: the session worktree nests under the project dir's shared
    // `.base/.worktrees/<session-id>/`, not directly under the project dir.
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let id = ManagedSessionId::new();
    let project_dir = root.path().join("bobmatnyc").join("trusty-tools");

    let ws = prov
        .provision_in(
            &project_dir,
            &id,
            "https://github.com/bobmatnyc/trusty-tools",
            "main",
            "task",
        )
        .unwrap();

    // Path must be exactly <project_dir>/.base/.worktrees/<session-id> —
    // isolated under the project dir, nested under the shared base checkout.
    assert_eq!(
        ws.path,
        project_dir
            .join(".base")
            .join(".worktrees")
            .join(id.to_string())
    );
    assert!(ws.path.starts_with(&project_dir));
}

/// #1935: a second session provisioned for the SAME project must reuse the
/// existing base checkout (no re-clone) and land in its OWN worktree.
///
/// Why: this is the entire point of the fix — before #1935 every session
/// paid for an independent full clone; now only the FIRST session for a
/// project establishes the base checkout, and every subsequent session for
/// that project reuses it via `worktree_add`.
/// What: provisions two sessions against the same project dir, asserts (1)
/// `FakeGitBackend::ensure_base_checkout` observed exactly one call whose
/// `HEAD` marker was absent (the actual clone) — the second call is a no-op
/// because the marker now exists; (2) the two sessions get DISTINCT
/// worktree paths sharing the same `.base/` parent.
/// Test: this function IS the test.
#[test]
fn provision_reuses_base_checkout_across_sessions() {
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let project_dir = root.path().join("owner").join("repo");

    let id1 = ManagedSessionId::new();
    let ws1 = prov
        .provision_in(
            &project_dir,
            &id1,
            "https://github.com/owner/repo",
            "main",
            "t1",
        )
        .unwrap();

    let id2 = ManagedSessionId::new();
    let ws2 = prov
        .provision_in(
            &project_dir,
            &id2,
            "https://github.com/owner/repo",
            "main",
            "t2",
        )
        .unwrap();

    let base_dir = project_dir.join(".base");
    // Both worktrees share the same base checkout directory...
    assert!(ws1.path.starts_with(&base_dir));
    assert!(ws2.path.starts_with(&base_dir));
    // ...but are otherwise distinct, isolated directories.
    assert_ne!(ws1.path, ws2.path);
    // The base checkout itself was established exactly once (idempotent
    // `HEAD` marker check inside `FakeGitBackend::ensure_base_checkout`).
    assert!(base_dir.join("HEAD").is_file());
}

#[test]
fn provisioner_records_repo_url_and_branch() {
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let id = ManagedSessionId::new();

    let ws = prov
        .provision(
            &id,
            "https://github.com/owner/repo",
            "feat/my-branch",
            "task",
        )
        .unwrap();

    assert_eq!(ws.repo_url, "https://github.com/owner/repo");
    assert_eq!(ws.branch, "feat/my-branch");
}

/// Why: WI-A #1585 — when `LaunchParams::ref_` is absent the spawn path
/// forwards `git_ref = ""` to `spawn_managed`/`SpawnParams`. This test
/// locks in the contract that a blank `git_ref` is passed through to the
/// git backend as `""` AND that provision still succeeds (no early error).
/// #1935: the production fix now lives in `RealGitBackend::worktree_add`
/// (`provision_in` no longer calls `clone_repo` at all): when
/// `git_ref.trim().is_empty()` the fetch source falls back to `HEAD` (the
/// remote's default branch pointer) instead of an empty, invalid ref name —
/// mirroring the same blank-ref-tolerance contract `RealGitBackend::clone_repo`
/// still upholds for `content::catalog_sync`'s unrelated use of the same trait.
/// What: provisions with `git_ref = ""` and asserts (1) provision
/// succeeds, (2) the returned `branch` field is `""` (the provisioner does
/// not substitute a default) — the internal per-session branch name backing
/// the worktree is unrelated to this field, which always echoes the
/// REQUESTED ref verbatim.
/// Test: this is the test.
#[test]
fn blank_git_ref_omits_branch_flag() {
    let root = crate::test_support::hermetic_temp_dir();
    // Use FakeGitBackend via make_provisioner so we can read its call log.
    // make_provisioner returns a provisioner whose backend is a FakeGitBackend
    // but we cannot access it post-move. We build explicitly here so we can
    // inspect calls.
    let fake = FakeGitBackend::new();
    // SAFETY: the calls Mutex is shared across the borrow boundary through
    // raw pointers; instead, use a shared Arc<FakeGitBackend> — but since the
    // type does not impl Clone we verify the contract via ws.branch instead.
    let prov = WorkspaceProvisioner::without_prepare(FakeGitBackend::new(), root.path().to_owned());
    let id = ManagedSessionId::new();

    let ws = prov
        .provision(&id, "https://github.com/owner/repo", "", "task")
        .unwrap();

    // Provision must succeed: the provisioner does not reject a blank ref.
    assert!(ws.path.starts_with(root.path()), "workspace inside root");
    // The branch field records what was passed — blank — not a substituted default.
    // This pins the invariant that the provisioner passes "" through to the
    // backend verbatim; only `RealGitBackend::worktree_add` substitutes `HEAD`
    // as the actual fetch source when the ref is blank.
    assert_eq!(
        ws.branch, "",
        "blank ref must be stored as-is, not substituted"
    );
    drop(fake); // explicitly drop to silence unused-variable lint
}

/// Why: closes #1693 — the task description must be written to TASK.md in
/// the workspace root so the agent can read its brief without requiring
/// interactive input. This test locks in the write behaviour.
/// What: provisions with a non-empty task and asserts TASK.md exists and
/// contains exactly the task string.
/// Test: this is the test.
#[test]
fn provision_writes_task_md() {
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let id = ManagedSessionId::new();
    let task = "Fix the authentication bug in the login flow";

    let ws = prov
        .provision(&id, "https://github.com/owner/repo", "main", task)
        .unwrap();

    let task_file = ws.path.join("TASK.md");
    assert!(
        task_file.exists(),
        "TASK.md must be written when task is non-empty"
    );
    let content = std::fs::read_to_string(&task_file).unwrap();
    assert_eq!(content, task, "TASK.md must contain the exact task text");
}

/// Why: closes #1693 — when no task is provided the workspace must NOT
/// receive an empty TASK.md (an empty file is misleading and wastes I/O).
/// What: provisions with an empty task string and asserts TASK.md is absent.
/// Test: this is the test.
#[test]
fn provision_skips_task_md_when_empty() {
    let root = crate::test_support::hermetic_temp_dir();
    let prov = make_provisioner(&root);
    let id = ManagedSessionId::new();

    let ws = prov
        .provision(&id, "https://github.com/owner/repo", "main", "")
        .unwrap();

    let task_file = ws.path.join("TASK.md");
    assert!(
        !task_file.exists(),
        "TASK.md must NOT be created when task is empty"
    );
}

// ── trusty-review PR #1936 (#1935) findings: RealGitBackend::ensure_base_checkout ──
//
// Both tests below exercise `RealGitBackend` against real local git
// repositories (no network required — `file://` remotes and local `git init`
// only), mirroring the graceful-skip-if-git-unavailable pattern already used
// by `decommission_worktree_tests.rs`.

/// Create a local bare "origin" repo with a single commit and return its path.
///
/// Why: shared fixture for the two `ensure_base_checkout` regression tests
/// below — both need a real, clonable bare repo to point `RealGitBackend` at.
/// What: `git init --bare`, then clones it to a scratch work dir, commits a
/// README, and pushes back to the bare repo. Returns `None` (callers must
/// skip, not fail) if the local `git` binary is unavailable, matching the
/// established pattern in `decommission_worktree_tests.rs`.
/// Test: exercised transitively by every test that calls it.
fn make_local_bare_origin(scratch: &TempDir) -> Option<PathBuf> {
    use std::process::Command;
    let bare = scratch.path().join("origin.git");
    let work = scratch.path().join("seed");
    if !Command::new("git")
        .args(["init", "--bare", "-b", "main"])
        .arg(&bare)
        .status()
        .map(|s| s.success())
        .unwrap_or(false)
    {
        return None;
    }
    if !Command::new("git")
        .args(["clone"])
        .arg(&bare)
        .arg(&work)
        .status()
        .map(|s| s.success())
        .unwrap_or(false)
    {
        return None;
    }
    std::fs::write(work.join("README.md"), "seed").unwrap();
    let work_s = work.to_str().unwrap();
    for args in [
        vec!["-C", work_s, "add", "."],
        vec![
            "-C",
            work_s,
            "-c",
            "user.email=t@t",
            "-c",
            "user.name=t",
            "commit",
            "-m",
            "seed",
        ],
        vec!["-C", work_s, "push", "origin", "main"],
    ] {
        if !Command::new("git")
            .args(&args)
            .status()
            .map(|s| s.success())
            .unwrap_or(false)
        {
            return None;
        }
    }
    Some(bare)
}

/// trusty-review finding #1 (TOCTOU race, PR #1936): two sessions
/// provisioning the SAME project for the first time must not fail when they
/// race on `ensure_base_checkout`.
///
/// Why: before the fix, both racing callers observed `base_dir.join("HEAD")`
/// absent, both attempted `git clone --bare`, and the loser hit git's
/// "destination path ... already exists and is not an empty directory"
/// error, surfacing as a hard `ProvisionError::Git` and failing that
/// session's provisioning outright.
/// What: spawns several real OS threads that all call
/// `RealGitBackend.ensure_base_checkout(repo_url, &base_dir)` concurrently
/// against the exact same, not-yet-existing `base_dir`, then asserts (1)
/// every thread returned `Ok(())` — no race loser propagates the "already
/// exists" error — and (2) exactly one genuinely established bare checkout
/// exists at `base_dir` afterward (`git rev-parse --is-bare-repository`
/// reports `true`). Skips gracefully if the local `git` binary is
/// unavailable.
/// Test: this function IS the test.
#[test]
fn ensure_base_checkout_recovers_from_concurrent_race() {
    let scratch = crate::test_support::hermetic_temp_dir();
    let Some(bare_origin) = make_local_bare_origin(&scratch) else {
        eprintln!("ensure_base_checkout_recovers_from_concurrent_race: git unavailable, skipping");
        return;
    };
    let repo_url = format!("file://{}", bare_origin.display());

    let root = crate::test_support::hermetic_temp_dir();
    let base_dir = root.path().join("project").join(".base");

    let handles: Vec<_> = (0..4)
        .map(|_| {
            let repo_url = repo_url.clone();
            let base_dir = base_dir.clone();
            std::thread::spawn(move || {
                RealGitBackend::default().ensure_base_checkout(&repo_url, &base_dir)
            })
        })
        .collect();

    for handle in handles {
        let result = handle.join().expect("thread must not panic");
        assert!(
            result.is_ok(),
            "every racing ensure_base_checkout call must recover and return Ok, got {result:?}"
        );
    }

    assert!(
        is_established_bare_checkout(&base_dir),
        "base_dir must be a genuinely established bare checkout after the race settles"
    );
}

/// trusty-review finding #2 (fragile bare-clone detection, PR #1936): a
/// stale NON-bare directory sitting at the base-checkout path must not be
/// silently accepted as a valid shared base.
///
/// Why: the previous idempotency guard (`base_dir.join("HEAD").is_file()`)
/// only checks for a file NAMED `HEAD` at the root of `base_dir` — it never
/// confirms that directory is actually a valid, complete git repository.
/// Verified empirically (see this test): a plain non-bare `git init`/`clone`
/// does NOT put a `HEAD` file at its OWN root (that lives at `.git/HEAD`
/// instead), but a directory that merely CONTAINS a stray file literally
/// named `HEAD` — e.g. left over from a `git clone --bare` that crashed
/// mid-clone (git writes `HEAD` early, before the rest of the object
/// database/refs), or any other stale/corrupt artifact occupying
/// `<project_dir>/.base/` — passes the old check and would be silently
/// treated as an established base, so cloning is skipped and a corrupt
/// directory is left as the "base"; later `git worktree add` /
/// `git fetch` calls against it then fail confusingly.
/// What: pre-creates `base_dir` containing ONLY a `HEAD` file (no `.git`,
/// no object database, no refs — the minimum needed to fool the OLD
/// file-existence check) and calls `RealGitBackend.ensure_base_checkout`
/// pointed at a real, unrelated bare origin. Asserts the call returns `Err`
/// (loud failure) rather than `Ok` (which would mean the corrupt directory
/// was silently treated as valid). Skips gracefully if the local `git`
/// binary is unavailable.
/// Test: this function IS the test.
#[test]
fn ensure_base_checkout_rejects_stale_non_bare_directory() {
    let scratch = crate::test_support::hermetic_temp_dir();
    let Some(bare_origin) = make_local_bare_origin(&scratch) else {
        eprintln!(
            "ensure_base_checkout_rejects_stale_non_bare_directory: git unavailable, skipping"
        );
        return;
    };
    let repo_url = format!("file://{}", bare_origin.display());

    let root = crate::test_support::hermetic_temp_dir();
    let base_dir = root.path().join("project").join(".base");
    std::fs::create_dir_all(&base_dir).unwrap();
    std::fs::write(base_dir.join("HEAD"), "ref: refs/heads/main\n").unwrap();

    assert!(
        base_dir.join("HEAD").is_file(),
        "sanity check: the stale directory has a file literally named HEAD"
    );
    assert!(
        !is_established_bare_checkout(&base_dir),
        "sanity check: a lone HEAD file with no repo structure must NOT read as bare"
    );

    let result = RealGitBackend::default().ensure_base_checkout(&repo_url, &base_dir);
    assert!(
        result.is_err(),
        "a stale non-repo directory must be rejected loudly, not silently reused: {result:?}"
    );
    // #1937 item 1: the error must be ACTIONABLE — name the exact path and a
    // recovery command the operator can run to allow re-provisioning. #3605:
    // that command must be a non-destructive quarantine, never a delete.
    let msg = result.unwrap_err().to_string();
    assert!(
        msg.contains(&base_dir.display().to_string()),
        "error must name the exact stale base path, got: {msg}"
    );
    assert_no_destructive_hint(&msg);
}

/// Assert an operator-facing recovery message offers a QUARANTINE and contains
/// no command that recursively destroys the shared base checkout (#3605).
///
/// Why: on 2026-07-21 a `<project>/.base` was destroyed and ~70 worktrees were
/// orphaned machine-wide, every one then emitting phantom git-discovery test
/// failures. The most plausible trigger was `stale_base_dir_error`'s own
/// suggested recovery: a literal, copy-pasteable `rm -rf <path>`. The threat
/// model is that this message is read by an autonomous agent that executes the
/// suggestion verbatim, so the string itself is the vulnerability and a
/// string-level assertion is the correct regression guard.
/// What: fails if the message names any recursive-delete form, and requires the
/// non-destructive `mv`-aside quarantine hint plus the shared-ownership warning
/// that was missing when the destructive hint was followed.
/// Test: used by `ensure_base_checkout_rejects_stale_non_bare_directory`,
/// `fake_ensure_base_checkout_rejects_stale_non_bare_directory`, and
/// `stale_base_dir_error_suggests_quarantine_not_deletion`.
fn assert_no_destructive_hint(msg: &str) {
    for forbidden in ["rm -rf", "rm -fr", "rm -r ", "remove_dir_all", "rmdir"] {
        assert!(
            !msg.contains(forbidden),
            "recovery message must never suggest a recursive delete of the SHARED \
             base checkout (#3605), but it contains {forbidden:?}: {msg}"
        );
    }
    assert!(
        msg.contains("    mv "),
        "recovery message must offer the non-destructive quarantine command, got: {msg}"
    );
    assert!(
        msg.contains("SHARED"),
        "recovery message must warn that the base is shared across sessions, got: {msg}"
    );
}

/// #3605 regression guard: `stale_base_dir_error`'s message must recover the
/// operator WITHOUT naming a destructive command.
///
/// Why: the two backend-level tests above reach this message through a full
/// `ensure_base_checkout` call; this one pins the message contract directly at
/// its source so a future edit to the string is caught even if the backends'
/// call paths change. It also pins the parts a purely negative assertion would
/// miss: the message must still leave the operator able to recover (a safe but
/// useless hint is not an improvement), and the quarantine destination must be
/// a concrete, distinct sibling path — not the base path itself, which would
/// make the suggested `mv` a no-op.
/// What: builds the error for a non-empty, non-bare directory and asserts the
/// message names the path, carries the quarantine + SHARED warning, offers no
/// recursive delete, and targets a `.stale-` sibling destination that differs
/// from the source path.
/// Test: this function IS the test.
#[test]
fn stale_base_dir_error_suggests_quarantine_not_deletion() {
    let root = crate::test_support::hermetic_temp_dir();
    let base_dir = root.path().join("project").join(".base");
    std::fs::create_dir_all(&base_dir).unwrap();
    std::fs::write(base_dir.join("HEAD"), "ref: refs/heads/main\n").unwrap();

    let err = super::base_lock::stale_base_dir_error(&base_dir)
        .expect("a non-empty, non-bare base dir must produce an error");
    let msg = err.to_string();

    assert!(
        msg.contains(&base_dir.display().to_string()),
        "error must name the exact stale base path, got: {msg}"
    );
    assert_no_destructive_hint(&msg);

    let quarantine = super::base_lock::stale_base_quarantine_path(&base_dir);
    assert_ne!(
        quarantine, base_dir,
        "quarantine destination must differ from the source, or the `mv` is a no-op"
    );
    assert!(
        quarantine
            .file_name()
            .and_then(|n| n.to_str())
            .is_some_and(|n| n.contains(".stale-")),
        "quarantine destination must be a timestamped `.stale-` sibling, got: {}",
        quarantine.display()
    );
    assert_eq!(
        quarantine.parent(),
        base_dir.parent(),
        "quarantine must be a sibling so the `mv` is a same-filesystem rename"
    );

    // An EMPTY or absent base dir is safe to clone into and must not error.
    let empty = root.path().join("project").join(".base-empty");
    std::fs::create_dir_all(&empty).unwrap();
    assert!(super::base_lock::stale_base_dir_error(&empty).is_none());
    assert!(super::base_lock::stale_base_dir_error(&root.path().join("nope")).is_none());
}

/// #1937 item 3: `FakeGitBackend`'s idempotency/stale-detection must match
/// `RealGitBackend`'s so a fake-backend test catches the same stale-directory
/// condition a real-backend test would — the fidelity gap flagged in the
/// PR #1936 review.
///
/// Why: before this fix `FakeGitBackend::ensure_base_checkout` reused any
/// directory containing a stray `HEAD` file (the same superficial probe the
/// real backend abandoned), so a future author simulating a stale `.base` with
/// the fake would get a false-positive "already established" pass instead of
/// the loud rejection the real backend now produces. This test mirrors
/// `ensure_base_checkout_rejects_stale_non_bare_directory` against the fake.
/// What: pre-seeds `base_dir` with ONLY a stray `HEAD` file (no `config`
/// `bare = true` marker — the fake's stand-in for "not a valid bare checkout")
/// and asserts `FakeGitBackend::ensure_base_checkout` returns an actionable
/// `Err` naming the path and the non-destructive quarantine recovery command,
/// exactly like the real backend — not a silent `Ok` reuse.
/// Test: this function IS the test.
#[test]
fn fake_ensure_base_checkout_rejects_stale_non_bare_directory() {
    let root = crate::test_support::hermetic_temp_dir();
    let base_dir = root.path().join("project").join(".base");
    std::fs::create_dir_all(&base_dir).unwrap();
    // A lone HEAD file with no `config bare = true` marker is the fake's
    // stand-in for a stale, non-bare, mid-crash directory.
    std::fs::write(base_dir.join("HEAD"), "ref: refs/heads/main\n").unwrap();

    let fake = FakeGitBackend::new();
    let result = fake.ensure_base_checkout("https://github.com/owner/repo", &base_dir);
    assert!(
        result.is_err(),
        "fake must reject a stale non-bare directory loudly, not silently reuse it: {result:?}"
    );
    let msg = result.unwrap_err().to_string();
    assert!(
        msg.contains(&base_dir.display().to_string()),
        "fake error must be actionable (must name the path), got: {msg}"
    );
    assert_no_destructive_hint(&msg);
}

/// #1937 item 3 (positive path): a FRESH `FakeGitBackend::ensure_base_checkout`
/// establishes a valid fake bare checkout, and a SECOND call reuses it
/// idempotently (no error, no clobber).
///
/// Why: locks in that the tightened validity check does not regress the
/// happy-path reuse contract — the fake must still recognise the base it just
/// wrote as established on the next call.
/// What: calls `ensure_base_checkout` twice against an empty base path; asserts
/// both return `Ok`, the second is recognised via `fake_is_established_bare_checkout`,
/// and the written markers (`HEAD` + `bare = true` `config`) are present.
/// Test: this function IS the test.
#[test]
fn fake_ensure_base_checkout_is_idempotent_on_valid_base() {
    let root = crate::test_support::hermetic_temp_dir();
    let base_dir = root.path().join("project").join(".base");
    let fake = FakeGitBackend::new();

    fake.ensure_base_checkout("https://github.com/owner/repo", &base_dir)
        .expect("first ensure must establish the fake base");
    assert!(
        super::base_lock::fake_is_established_bare_checkout(&base_dir),
        "a freshly-established fake base must read as a valid bare checkout"
    );

    // Second call must be an idempotent no-op reuse, not a stale rejection.
    fake.ensure_base_checkout("https://github.com/owner/repo", &base_dir)
        .expect("second ensure must reuse the established fake base");
    assert!(base_dir.join("HEAD").is_file());
    assert!(base_dir.join("config").is_file());
}

/// A lock marker abandoned by a crashed holder must not permanently deadlock
/// future base-checkout provisioning attempts.
///
/// Why: the base-checkout lock (added to fix trusty-review finding #1) is a
/// plain marker file, not a kernel-tracked `flock` — if the process holding
/// it is killed mid-clone, nothing ever runs its `Drop` impl to remove the
/// marker. Without stale-lock recovery, every future `ensure_base_checkout`
/// call for that project would wait out `LOCK_ACQUIRE_TIMEOUT` and then fail
/// forever, which is worse than the race it was meant to fix.
/// What: writes a lock marker file and backdates its modified time past
/// `LOCK_STALE_AFTER` via `File::set_modified` (no `filetime` dependency
/// needed — this has been in `std` since Rust 1.75, well under this
/// workspace's 1.91 MSRV). Asserts `lock_is_stale` reports it as stale, then
/// asserts `acquire_base_checkout_lock` recovers PROMPTLY (well under
/// `LOCK_ACQUIRE_TIMEOUT`) rather than blocking out the full timeout, and
/// that dropping the returned guard removes the marker file.
/// Test: this function IS the test.
#[test]
fn base_checkout_lock_recovers_stale_lock_marker() {
    let root = crate::test_support::hermetic_temp_dir();
    let lock_path = root.path().join(".base.lock");
    std::fs::write(&lock_path, b"").unwrap();

    let stale_time =
        std::time::SystemTime::now() - (LOCK_STALE_AFTER + std::time::Duration::from_secs(10));
    std::fs::File::options()
        .write(true)
        .open(&lock_path)
        .unwrap()
        .set_modified(stale_time)
        .unwrap();

    assert!(
        lock_is_stale(&lock_path),
        "a lock marker older than LOCK_STALE_AFTER must be considered stale"
    );

    let start = std::time::Instant::now();
    let guard = acquire_base_checkout_lock(&lock_path).expect("must recover from a stale lock");
    assert!(
        start.elapsed() < std::time::Duration::from_secs(5),
        "stale-lock recovery must not wait out the full acquire timeout"
    );

    drop(guard);
    assert!(
        !lock_path.exists(),
        "dropping the lock guard must remove the marker file"
    );
}

// ── #2184: RealGitBackend applies the resolved GitIdentity to every command ──

/// Why: a `RealGitBackend::default()` (no identity resolved) must build a
/// PLAIN `git` command — no env overrides, no `-c` args — so every existing
/// production call site (which constructs `RealGitBackend::default()` when it
/// has no project context) is byte-for-byte unaffected by #2184.
/// Test: itself.
#[test]
fn default_identity_produces_plain_git_command() {
    let backend = RealGitBackend::default();
    let cmd = backend.command();
    assert_eq!(
        cmd.get_args().count(),
        0,
        "no -c args for an empty identity"
    );
    assert_eq!(
        cmd.get_envs().count(),
        0,
        "no env overrides for an empty identity"
    );
}

/// Why: the resolved `GitIdentity::env` overrides must be applied to every
/// command this backend builds, so `git`/its credential helper authenticate
/// as the right per-project identity.
/// Test: itself.
#[test]
fn git_identity_env_applied_to_command() {
    let identity = crate::core::git_identity::GitIdentity {
        env: vec![("GH_CONFIG_DIR".to_string(), "/cfg/project".to_string())],
        commit_name: None,
        commit_email: None,
    };
    let backend = RealGitBackend::new(identity);
    let cmd = backend.command();
    let envs: Vec<_> = cmd.get_envs().collect();
    assert!(
        envs.iter().any(|(k, v)| {
            *k == std::ffi::OsStr::new("GH_CONFIG_DIR")
                && *v == Some(std::ffi::OsStr::new("/cfg/project"))
        }),
        "GH_CONFIG_DIR override must be applied: {envs:?}"
    );
}

/// Why: a resolved commit-identity override must render as `-c user.name=…`/
/// `-c user.email=…` BEFORE any subcommand arg (git only accepts `-c`
/// overrides in that position).
/// Test: itself.
#[test]
fn git_identity_commit_args_applied_to_command() {
    let identity = crate::core::git_identity::GitIdentity {
        env: vec![],
        commit_name: Some("Bot".to_string()),
        commit_email: Some("bot@example.com".to_string()),
    };
    let backend = RealGitBackend::new(identity);
    let cmd = backend.command();
    let args: Vec<&std::ffi::OsStr> = cmd.get_args().collect();
    assert_eq!(
        args,
        vec![
            std::ffi::OsStr::new("-c"),
            std::ffi::OsStr::new("user.name=Bot"),
            std::ffi::OsStr::new("-c"),
            std::ffi::OsStr::new("user.email=bot@example.com"),
        ]
    );
}