vcs_git/

lib.rs

#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(rustdoc::broken_intra_doc_links)]
//! `vcs-git` — automate Git from Rust by driving the `git` CLI.
//!
//! You call typed `async` methods; `vcs-git` runs the real `git`, parses its
//! output, and hands you structured values — so you get *git's own* behaviour,
//! config, and credentials, not a reimplementation of the object format. Async,
//! structured errors, mockable. Every command runs inside an OS **job** (an
//! OS-level container that kills the whole process tree if your program exits, via
//! [`processkit`]) so a `git` subprocess is never orphaned, with an optional
//! per-client [timeout](Git::default_timeout).
//!
//! # What you can do
//!
//! Status & branches · stage, commit, checkout · diff & log · merge / rebase /
//! reset · worktrees · tags · blame · clone · config · cherry-pick / revert · parse
//! & resolve conflict markers · a hardened (hooks-off) profile for untrusted repos.
//! One tiny call to start:
//!
//! ```no_run
//! use std::path::Path;
//! use vcs_git::{Git, GitApi};
//! # async fn demo() -> Result<(), processkit::Error> {
//! let git = Git::new();
//! // `current_branch` is `Option` — `None` on a detached HEAD.
//! println!("{:?}", git.current_branch(Path::new(".")).await?); // e.g. Some("main")
//! # Ok(()) }
//! ```
//!
//! # The surface (engineering reference)
//!
//! - **[`GitApi`]** — the object-safe trait every operation lives on. Depend on
//!   `&dyn GitApi` (or generically on `impl GitApi`) so a test can swap the real
//!   client for a double. Methods take the working directory as the first
//!   argument and return typed results ([`StatusEntry`], [`Branch`], [`Commit`],
//!   [`FileDiff`], [`BlameLine`], …) or a structured [`Error`].
//! - **[`Git`]** — the real client. [`Git::new`] uses the job-backed runner;
//!   [`Git::with_runner`] injects a fake one for tests. It is generic over the
//!   [`ProcessRunner`] seam, defaulting to the production runner.
//!   [`with_credentials`](Git::with_credentials) attaches a [`CredentialProvider`]
//!   to authenticate HTTPS remote ops (fetch/push/clone/ls-remote) with a token
//!   kept out of `argv` — opt-in, off by default (ambient helpers / SSH agent).
//! - **[`GitAt`]** — a cwd-bound view ([`Git::at`]) whose methods drop the
//!   leading `dir`, so `git.at(dir).status()` reads as `git.status(dir)` — handy
//!   when one client drives one checkout.
//! - **Builder specs** for the multi-option commands — [`CommitPaths`],
//!   [`MergeCommit`] / [`MergeNoCommit`], [`GitPush`], [`CloneSpec`],
//!   [`WorktreeAdd`], [`AnnotatedTag`], [`MergeCheck`], [`BranchDelete`],
//!   [`StashPush`], [`WorktreeRemove`] — each `#[non_exhaustive]`, built
//!   with a constructor + chained setters, named after the flags they emit.
//! - **[`conflict`]** — a typed conflict-marker model: parse marker soup into
//!   structured regions, re-render byte-exact, and resolve to a chosen side.
//! - **[`Git::hardened`]** — a profile for untrusted repositories (hooks off,
//!   `GIT_*` scrubbed, system config skipped); see the [`guide::security`] guide.
//!
//! # Recipes
//!
//! Read state — depend on the trait so the same code takes a real client or a mock:
//!
//! ```no_run
//! use std::path::Path;
//! use vcs_git::{Git, GitApi};
//! # async fn demo() -> Result<(), processkit::Error> {
//! let git = Git::new();
//! let dir = Path::new(".");
//! let branch = git.current_branch(dir).await?;        // the checked-out branch
//! let dirty = !git.status(dir).await?.is_empty();     // any uncommitted change?
//! # let _ = (branch, dirty); Ok(()) }
//! ```
//!
//! Mutate through the builder specs — `fetch` retries transient network failures:
//!
//! ```no_run
//! use std::path::Path;
//! use vcs_git::{CommitPaths, Git, GitApi, GitPush, RefName};
//! # async fn demo(git: &Git) -> Result<(), processkit::Error> {
//! let dir = Path::new(".");
//! git.fetch(dir).await?;
//! git.commit_paths(dir, CommitPaths::new(["src/a.rs"], "wip")).await?;
//! // Ref/revision inputs are validated newtypes — build them at the boundary.
//! git.push(dir, GitPush::branch(RefName::new("feature")?).set_upstream()).await?;
//! # Ok(()) }
//! ```
//!
//! # Testing
//!
//! Two seams: enable the **`mock`** feature for a `mockall`-generated
//! `MockGitApi` (stub whole methods), or inject a
//! [`ScriptedRunner`](processkit::testing::ScriptedRunner) with [`Git::with_runner`] to
//! exercise the *real* argv-building and parsing against canned output. The
//! cross-cutting testing patterns live in
//! [vcs-testkit's guide](https://docs.rs/vcs-testkit/latest/vcs_testkit/guide/testing/).
//!
//! # Features
//!
//! - **`mock`** — the `mockall`-generated `MockGitApi` (see *Testing* above).
//! - **`tracing`** — a `tracing` event per command run.
//! - **`serde`** — derives `serde::Serialize` on the public [`conflict`] model
//!   ([`ConflictSegment`](conflict::ConflictSegment),
//!   [`ConflictRegion`](conflict::ConflictRegion),
//!   [`ResolutionSide`](conflict::ResolutionSide)) so a caller can emit a parsed
//!   conflict as JSON. `Serialize` only — these types are a parser's *output*,
//!   never a wire input.
//!
//! # Safety
//!
//! Every operation that takes a caller-supplied **reference name** or **revision
//! expression** now does so through a validated newtype — [`RefName`] for
//! branch/tag/ref names, [`RevSpec`] for revisions/ranges — so a flag-like or
//! malformed value is rejected at construction, *before* it can reach an argv
//! slot (a classifiable [`vcs_cli_support::is_invalid_input`] failure). The one
//! context-dependent special value, git's `-` "previous branch", is modelled
//! explicitly as [`CheckoutTarget::Previous`] rather than smuggled through a
//! newtype. Remaining bare-positional inputs that are **not** refs/revisions
//! (remote names, URLs, config keys) keep an internal
//! [`reject_flag_like`](vcs_cli_support::reject_flag_like) guard — refused before
//! spawning if empty or starting with `-`. Flag-value slots (`-b <name>`) are
//! consumed verbatim; paths — and a config *value*, which may legitimately begin
//! with `-` (e.g. `-1`) and so can't be flag-rejected — go through a `--` option
//! terminator instead (see [`config_set`](GitApi::config_set)).
//!
//! One named exception to the "revisions go through `RevSpec`" rule:
//! [`DiffSpec::Rev`] — the diff target on
//! [`GitApi::diff_text`]/[`GitApi::diff`] and [`Git::diff_text_within`]/
//! [`Git::diff_within`] — is a bare `String` from the shared, backend-agnostic
//! `vcs-diff` crate, not a `RevSpec`. It is still guarded, just per-call rather
//! than by the type: `diff_text_budgeted` runs the same
//! [`reject_flag_like`](vcs_cli_support::reject_flag_like) check inline before
//! using it, and a trailing `--` pins it as a revision rather than a pathspec.
//! Behaviourally equivalent to `RevSpec::new`'s guarantee, just enforced at the
//! call site because `vcs-diff` is intentionally a plain-data, dependency-free
//! crate with no newtype of its own to construct through.
//!
//! # In-depth guide
//!
//! Beyond this page, this crate ships a full how-to guide — rendered on docs.rs
//! from `docs/`. See the [`guide`] module (and its
//! [`security`](crate::guide::security) / [`conflicts`](crate::guide::conflicts)
//! sub-guides).

use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;

use processkit::Command;
// Re-export the processkit types that appear in this crate's public API, so
// consumers needn't depend on processkit directly — incl. `ProcessRunner` (the
// `with_runner`/`Git<R>` seam) and the `JobRunner` default. (`Error`/`Result`/
// `ProcessResult`/`ProcessRunner` are in scope here too via this `pub use`.)
// `ErrorReason` and `ErrorKind` ride along deliberately: since processkit 3.0
// `Error` is an opaque wrapper, so *classifying* a failure means reaching
// `err.reason()` (variant-grain) or `err.kind()` (flat) — types a consumer cannot
// name without them. Omitting them would leave the re-exported `Error` unmatched,
// a silent capability regression rather than a mechanical rename.
pub use processkit::{
    Error, ErrorKind, ErrorReason, JobRunner, ProcessResult, ProcessRunner, Result,
};
// Re-exported so a consumer can name the token for `default_cancel_on` without
// taking a direct `processkit` dependency.
pub use processkit::CancellationToken;

pub mod conflict;
mod parse;
#[doc(hidden)]
pub use parse::parse_porcelain_v2;
pub use parse::{
    BlameLine, Branch, BranchStatus, CleanEntry, Commit, Remote, StashEntry, StatusEntry,
    Submodule, SubmoduleState, SubmoduleStatus, Worktree,
};
// The git-format diff model + parser and the version type are shared with
// `vcs-jj` (identical output) — re-exported so `vcs_git::FileDiff`,
// `vcs_git::parse_diff`, `vcs_git::GitVersion`, … still resolve.
pub use vcs_diff::{
    ChangeKind, DiffLine, DiffSpec, DiffStat, FileDiff, Hunk, Version as GitVersion, parse_diff,
};
// The error classifiers live in the shared plumbing crate — re-exported so
// `vcs_git::is_merge_conflict`, … still resolve.
use vcs_cli_support::git_credential_helper;
pub use vcs_cli_support::{
    Credential, CredentialProvider, CredentialRequest, CredentialService, EnvToken, OutputBudget,
    ProcessEvent, ProgressCallback, RetryPolicy, Secret, StaticCredential, is_lock_contention,
    is_merge_conflict, is_nothing_to_commit, is_transient_fetch_error, provider_fn,
};

/// Name of the underlying CLI binary this crate drives.
pub const BINARY: &str = "git";

mod specs;
pub use specs::{
    AnnotatedTag, BisectResult, BisectStep, BranchDelete, CheckoutTarget, Clean, CleanIgnored,
    CloneFilter, CloneSpec, CommitPaths, GitCapabilities, GitPush, MergeCheck, MergeCheckPartial,
    MergeCommit, MergeNoCommit, RefName, RevSpec, SparseCheckoutSet, StashPush, SubmoduleUpdate,
    WorktreeAdd, WorktreeRemove,
};

/// The Git operations this crate exposes — the interface consumers code against
/// and mock in tests.
///
/// **Injection safety:** reference names and revision expressions are taken as
/// the validated [`RefName`] / [`RevSpec`] newtypes (directly or inside an
/// options struct), so a flag-like or malformed value is rejected at
/// construction, before it can reach an argv slot. The remaining
/// caller-supplied bare positionals that are *not* refs/revisions — remote
/// names and URLs — keep an internal `reject_flag_like` guard: a value that is
/// empty or begins with `-` is rejected with an [`ErrorReason::Spawn`] *before*
/// spawning. Flag-value slots (`-m <msg>`, `--branch <b>`), filesystem path
/// arguments (`--`-separated pathspecs, plus worktree paths and clone
/// destinations — typed `Path`, caller-trusted), and the `run`/`run_raw`
/// escape hatches are not guarded. The one context-dependent special value,
/// git's `-` "previous branch", is [`CheckoutTarget::Previous`].
#[cfg_attr(feature = "mock", mockall::automock)]
#[async_trait::async_trait]
pub trait GitApi: Send + Sync {
    /// Run `git <args>` **in the process's current directory**, returning trimmed
    /// stdout (throws on a non-zero exit). A raw escape hatch for unmodelled commands
    /// — you supply the whole argv, so target a specific repo with `-C <dir>` in the
    /// args. This method on the client is the **process-cwd** escape hatch; the
    /// `at(dir)` bound view's [`run`](GitAt::run) is instead **bound to `dir`** (it
    /// forwards to [`Git::run_in`], so `git.at(dir).run(…)` runs in the bound repo).
    /// Use `git.at(dir).run(…)` (or [`Git::run_in`]) for the bound repo; use this for
    /// the process cwd (T-035, was M15).
    async fn run(&self, args: &[String]) -> Result<String>;
    /// Like [`GitApi::run`] but never errors on a non-zero exit — returns the
    /// captured [`ProcessResult`].
    async fn run_raw(&self, args: &[String]) -> Result<ProcessResult<String>>;
    /// Installed Git version (`git --version`).
    async fn version(&self) -> Result<String>;
    /// The installed binary's parsed version, as [`GitCapabilities`]
    /// (`git --version`). A value type — probe once and keep it; an
    /// unrecognisable version string is an [`ErrorReason::Parse`].
    async fn capabilities(&self) -> Result<GitCapabilities>;
    /// Working-tree status (`git status --porcelain=v1 -z`).
    async fn status(&self, dir: &Path) -> Result<Vec<StatusEntry>>;
    /// Raw porcelain status text (`git status --porcelain=v1`) — the unparsed
    /// counterpart of [`status`](GitApi::status), mirroring `vcs_jj` `status_text`.
    async fn status_text(&self, dir: &Path) -> Result<String>;
    /// Like [`status`](GitApi::status) but ignoring untracked files
    /// (`git status --porcelain=v1 -z --untracked-files=no`) — "is the *tracked*
    /// tree dirty", staged or not.
    async fn status_tracked(&self, dir: &Path) -> Result<Vec<StatusEntry>>;
    /// A combined branch + working-tree snapshot in **one** spawn
    /// (`git status --porcelain=v2 --branch -z`): HEAD, branch, upstream,
    /// ahead/behind, and change counts — the data a prompt/status-bar needs
    /// without N round-trips. See [`BranchStatus`].
    async fn branch_status(&self, dir: &Path) -> Result<BranchStatus>;
    /// Paths with unresolved merge conflicts, repo-relative with `/` separators
    /// (`git diff --name-only --diff-filter=U -z`). Empty when there are none.
    /// Returns [`PathBuf`]s built from the raw `-z` bytes, so a non-UTF-8
    /// conflicted path survives losslessly.
    async fn conflicted_files(&self, dir: &Path) -> Result<Vec<PathBuf>>;
    /// Current branch name, or `None` on a **detached HEAD**
    /// (`git symbolic-ref --quiet --short HEAD`). Returns the branch name for a
    /// normal branch **and for an unborn branch** (a fresh `init`/`clone` before the
    /// first commit); `None` only when HEAD is detached. Mirrors
    /// [`JjApi::current_bookmark`](../vcs_jj/trait.JjApi.html#tymethod.current_bookmark)'s
    /// `Option` shape, so cross-backend code treats "no named branch/bookmark" the
    /// same way on both wrappers.
    async fn current_branch(&self, dir: &Path) -> Result<Option<String>>;
    /// Local branches, current one flagged (`git branch`).
    async fn branches(&self, dir: &Path) -> Result<Vec<Branch>>;
    /// Up to `max` commits reachable from `revspec`, newest first
    /// (`git log <revspec> -- `). Pass `"HEAD"` for the current branch's
    /// history, or a range like `"main..HEAD"` / `"origin/main..HEAD"` to scope
    /// it. Mirrors [`JjApi::log`](../vcs_jj/trait.JjApi.html#tymethod.log)'s
    /// revset argument, so cross-backend code uses one signature. The
    /// `revspec` is a validated [`RevSpec`], so it can never be parsed as a
    /// flag. The argv ends in a literal `--` (end of revisions, no pathspecs)
    /// so a `revspec` that happens to match an existing file's name (e.g.
    /// `Makefile`) resolves as a revision or fails outright, rather than
    /// silently falling back to git's pathspec DWIM and returning `HEAD`'s
    /// history filtered by that path (C2/M13) — the same convention already
    /// used by [`log_paths`](GitApi::log_paths),
    /// [`diff_text`](GitApi::diff_text),
    /// [`diff_range_is_empty`](GitApi::diff_range_is_empty),
    /// [`diff_stat`](GitApi::diff_stat), and [`checkout`](GitApi::checkout).
    async fn log(&self, dir: &Path, revspec: &RevSpec, max: usize) -> Result<Vec<Commit>>;
    /// Like [`log`](GitApi::log), but scoped to commits that touched `paths`
    /// (`git --literal-pathspecs log <revspec> -n <max> -- <paths>`) — e.g. "who
    /// changed this module". `--literal-pathspecs` matches a path containing
    /// `*`/`?`/`[]` literally rather than as pathspec glob magic (R-02); the `--`
    /// separator keeps a path from being read as a flag (same convention as
    /// [`add`](GitApi::add)/[`commit_paths`](GitApi::commit_paths)). An empty
    /// `paths` is refused *before spawning*: silently falling back to
    /// [`log`](GitApi::log)'s unrestricted history would defeat the "scoped to
    /// these paths" contract. Mirrors
    /// [`JjApi::log_paths`](../vcs_jj/trait.JjApi.html#tymethod.log_paths), which
    /// takes filesets instead of pathspecs.
    ///
    /// Unlike [`add`](GitApi::add)/[`commit_paths`](GitApi::commit_paths), git's
    /// `log` has no `--pathspec-from-file` support, so a `paths` set that would
    /// risk exceeding the OS argv limit is instead split into multiple `git log`
    /// calls, each within budget; the per-call results are merged (deduplicated
    /// by hash — a commit can touch paths spread across more than one chunk)
    /// and restored to git's own commit order using a separate, pathless `git
    /// log <revspec> --format=%H` oracle call (T-052/R-03): pathspec filtering
    /// only drops non-matching commits, it never reorders the ones that
    /// remain, so the oracle's order — over the *same* revspec, unrestricted
    /// by paths — gives the exact relative order a single, hypothetical
    /// unchunked call would have produced. Unlike sorting by a parsed date
    /// field, this needs no assumption about author-vs-committer timestamps or
    /// same-second ties (git log dates have no sub-second precision). A
    /// `paths` set that fits in one call is unaffected — same single
    /// invocation, same order, as before.
    ///
    /// Before any of that, `revspec` (which may be symbolic, e.g. `HEAD`, or a
    /// range, e.g. `main..feature`) is resolved exactly once via `git
    /// rev-parse` into a fixed set of commit ids that every chunk call and the
    /// oracle call then reuse verbatim (T-052/R-04): without this, each of
    /// those several independent invocations would re-resolve the same
    /// symbolic text on its own, so a concurrent commit/reset/ref-move landing
    /// between any two of them could make them see different repository
    /// snapshots, silently omitting a newer matching commit, including one no
    /// longer reachable, or interleaving two different histories into the
    /// merged result. This resolution only happens on the chunked path (more
    /// than one invocation); the single-call fast path is unaffected. Also
    /// before any of that, every individual path is checked against the argv
    /// budget on its own (T-052/R-05): `git log` has no NUL-safe transport to
    /// fall back to the way `add`/`commit_paths` do, so a single path that by
    /// itself cannot fit in argv is rejected up front with a clear error
    /// rather than silently forwarded as an over-budget singleton chunk.
    async fn log_paths(
        &self,
        dir: &Path,
        revspec: &RevSpec,
        max: usize,
        paths: &[String],
    ) -> Result<Vec<Commit>>;
    /// Resolve a revision to a full hash (`git rev-parse --verify <rev>`). `--verify`
    /// requires `rev` to name exactly one object, so a non-revision (e.g. a filename)
    /// errors instead of being echoed back as a fake id.
    async fn rev_parse(&self, dir: &Path, rev: &RevSpec) -> Result<String>;
    /// Resolve a revision to its abbreviated hash (`git rev-parse --short <rev>`) —
    /// e.g. to label a detached HEAD.
    async fn rev_parse_short(&self, dir: &Path, rev: &RevSpec) -> Result<String>;
    /// Initialise a repository (`git init`).
    async fn init(&self, dir: &Path) -> Result<()>;
    /// Stage `paths` (`git --literal-pathspecs add -- <paths>`) —
    /// `--literal-pathspecs` applies regardless of path-set size, so a path
    /// containing `*`/`?`/`[]` always matches literally rather than as pathspec
    /// glob magic (R-01). A path set whose combined length would risk exceeding
    /// the OS command-line limit (`ARGV_PATHSPEC_BUDGET`; Windows' `CreateProcess`
    /// caps out around 32,767 characters) instead goes over stdin via
    /// `--pathspec-from-file=- --pathspec-file-nul` — the paths never touch argv
    /// at all in that case, so there is no upper bound left to exceed (T-052).
    async fn add(&self, dir: &Path, paths: &[PathBuf]) -> Result<()>;
    /// Commit staged changes (`git commit -m`).
    async fn commit(&self, dir: &Path, message: &str) -> Result<()>;
    /// Create a branch without switching to it (`git branch <name>`).
    async fn create_branch(&self, dir: &Path, name: &RefName) -> Result<()>;
    /// Switch to a branch/revision, or the previous branch (`git checkout
    /// <target>`); see [`CheckoutTarget`].
    async fn checkout(&self, dir: &Path, target: &CheckoutTarget) -> Result<()>;
    /// Check out a commit as a detached HEAD (`git checkout --detach <commit>`).
    async fn checkout_detach(&self, dir: &Path, commit: &RevSpec) -> Result<()>;
    /// Commit exactly the spec's paths' working-tree content, ignoring the index
    /// (`git --literal-pathspecs commit [--amend] -m <message> --only -- <paths>`);
    /// see [`CommitPaths`]. `--literal-pathspecs` applies regardless of path-set
    /// size, so a glob-magic character (`*`/`?`/`[]`) in a path is matched
    /// literally rather than expanded — otherwise `commit_paths`'s "exactly these
    /// paths" contract could be violated (R-01). Like [`add`](GitApi::add), a
    /// path set that would risk exceeding the OS argv limit is instead routed
    /// over stdin (`--pathspec-from-file=- --pathspec-file-nul`) — always as a
    /// **single** `git commit` invocation either way, so the one-atomic-commit
    /// contract is unaffected by the path set's size (T-052).
    async fn commit_paths(&self, dir: &Path, spec: CommitPaths) -> Result<()>;
    /// The last commit's full message (`git log -1 --format=%B`) — e.g. to
    /// pre-fill an amend.
    async fn last_commit_message(&self, dir: &Path) -> Result<String>;
    /// Whether `HEAD` is unborn — a fresh repo with no commits yet
    /// (`git rev-parse --verify -q HEAD`, exit-code mapped).
    async fn is_unborn(&self, dir: &Path) -> Result<bool>;
    /// Whether the working tree has no unstaged modifications to **tracked** files
    /// (`git diff --quiet`). Untracked files are *not* counted — this is not a full
    /// "is the working tree clean?" check; use [`status`](GitApi::status) for that.
    async fn diff_is_empty(&self, dir: &Path) -> Result<bool>;

    // --- Discovery / identity ------------------------------------------------

    /// The repository's common git directory (`rev-parse --git-common-dir`) —
    /// stable across linked worktrees.
    async fn common_dir(&self, dir: &Path) -> Result<PathBuf>;
    /// This worktree's git directory (`rev-parse --git-dir`).
    async fn git_dir(&self, dir: &Path) -> Result<PathBuf>;
    /// Resolve a revision to a commit hash, peeling tags
    /// (`rev-parse --verify <rev>^{commit}`).
    async fn resolve_commit(&self, dir: &Path, rev: &RevSpec) -> Result<String>;
    /// The remote's default branch from `symbolic-ref refs/remotes/origin/HEAD`
    /// (short name only); `None` when `origin/HEAD` is unset.
    async fn remote_head_branch(&self, dir: &Path) -> Result<Option<String>>;
    /// Whether a local branch exists (`show-ref --verify --quiet refs/heads/<name>`).
    async fn branch_exists(&self, dir: &Path, name: &RefName) -> Result<bool>;
    /// Whether `origin` has `name`, without fetching (`ls-remote origin
    /// refs/heads/<name>` — the fully-qualified ref, so `foo` can't tail-match
    /// `bar/foo`). Runs with `GIT_TERMINAL_PROMPT=0` and a 10s timeout so a missing
    /// credential or a flaky network can't hang the call.
    async fn remote_branch_exists(&self, dir: &Path, name: &RefName) -> Result<bool>;
    /// A remote's URL (`remote get-url <remote>`).
    async fn remote_url(&self, dir: &Path, remote: &str) -> Result<String>;
    /// Configured remotes from `remote -v`, coalesced to one typed row per name
    /// with its fetch URL.
    async fn remote_list(&self, dir: &Path) -> Result<Vec<Remote>>;
    /// The current attached branch's upstream, e.g. `Some("origin/main")`
    /// (`rev-parse --abbrev-ref --symbolic-full-name @{u}`); `None` when unset.
    /// A detached HEAD or a directory outside a repository is an error.
    async fn upstream(&self, dir: &Path) -> Result<Option<String>>;
    /// Branch names on `remote`, without fetching
    /// (`ls-remote --heads <remote>`).
    async fn remote_branches(&self, dir: &Path, remote: &str) -> Result<Vec<String>>;

    // --- Branches ------------------------------------------------------------

    /// Whether the [`MergeCheck`]'s `branch` is fully merged into its `base`
    /// (`branch --merged <base>`). Build it as
    /// `MergeCheck::branch(RefName::new("feature")?).into_base(RevSpec::new("main")?)`
    /// so the two refs can't be transposed (a swap would invert the answer).
    async fn is_merged(&self, dir: &Path, spec: MergeCheck) -> Result<bool>;
    /// Set `branch`'s upstream to `upstream` (e.g. `origin/main`)
    /// (`branch --set-upstream-to=<upstream> <branch>`).
    async fn set_upstream(&self, dir: &Path, branch: &RefName, upstream: &RefName) -> Result<()>;
    /// Delete a local branch (`branch -d`, or `-D` when forced); see [`BranchDelete`].
    async fn delete_branch(&self, dir: &Path, spec: BranchDelete) -> Result<()>;
    /// Rename a local branch (`branch -m <old> <new>`).
    async fn rename_branch(&self, dir: &Path, old: &RefName, new: &RefName) -> Result<()>;
    /// Count commits in a range (`rev-list --count <range>`).
    async fn rev_list_count(&self, dir: &Path, range: &RevSpec) -> Result<usize>;
    /// Whether a diff range is empty (`diff --quiet <range>`).
    async fn diff_range_is_empty(&self, dir: &Path, range: &RevSpec) -> Result<bool>;
    /// Aggregate change stats for a range (`diff --shortstat <range>`). Named to
    /// match `vcs_jj::JjApi::diff_stat`.
    async fn diff_stat(&self, dir: &Path, range: &RevSpec) -> Result<DiffStat>;
    /// Raw git-format unified diff text for `spec`
    /// (`diff <spec> --no-color --no-ext-diff -M`) — stable machine output, returned
    /// **verbatim** (a trailing blank context line is preserved, so the last hunk
    /// stays in sync with its `@@` line count for a re-parse/re-apply).
    ///
    /// [`DiffSpec::Rev`] is a direct passthrough: the string becomes git's single
    /// positional diff argument verbatim (`git diff <rev>`) — this crate doesn't
    /// parse, classify, or rewrite it beyond the
    /// [`reject_flag_like`](vcs_cli_support::reject_flag_like) guard against a
    /// leading `-`. Whatever `git diff <rev>` would do at the shell for that exact
    /// string is what `Rev(rev)` does here.
    ///
    /// One consequence follows from plain `git diff`'s own rules: a *single*
    /// revision (no `..`/`...`) diffs the **working tree** against that revision,
    /// not the revision against its parent — when `HEAD` exists,
    /// `Rev("HEAD".into())` behaves exactly like [`DiffSpec::WorkingTree`], and
    /// `Rev("abc".into())` includes any uncommitted changes on top of `abc`. On
    /// an unborn repository the two differ: [`DiffSpec::WorkingTree`]
    /// deliberately diffs against the empty tree, while `Rev("HEAD".into())`
    /// passes the unresolved name through and errors. To compare two commits
    /// with the working tree excluded, put a range in the `Rev` string instead
    /// (`"abc..def"` / `"abc^..abc"`) — git's two-dot/three-dot forms diff
    /// commit-to-commit. None of this is `vcs-git` logic; it's inherited by
    /// passing the string straight to git, except for `WorkingTree`'s documented
    /// unborn fallback.
    ///
    /// How `DiffSpec` is interpreted here is stable behavior, not an implementation detail.
    /// Changing it would be a semver-breaking change.
    async fn diff_text(&self, dir: &Path, spec: DiffSpec) -> Result<String>;
    /// Parsed per-file unified diff for `spec`, layered on [`diff_text`](GitApi::diff_text).
    async fn diff(&self, dir: &Path, spec: DiffSpec) -> Result<Vec<FileDiff>>;
    /// Raw git-format unified diff comparing the tree at `from` with the tree at
    /// `to` (`git diff <from> <to> --no-color --no-ext-diff -M`). Each endpoint
    /// is a separately validated [`RevSpec`], so compound selectors stay in
    /// their own argv slot and the `from` → `to` direction is explicit.
    /// Unlike [`DiffSpec::Rev`], this operation never includes the working tree
    /// implicitly: only the two supplied endpoints are compared.
    ///
    /// The default implementation returns [`ErrorReason::Unsupported`] so an
    /// existing downstream implementor remains source-compatible; concrete
    /// [`Git`] clients override it with the real Git operation.
    async fn diff_text_between(
        &self,
        _dir: &Path,
        _from: &RevSpec,
        _to: &RevSpec,
    ) -> Result<String> {
        Err(Error::from(ErrorReason::Unsupported {
            operation: "GitApi::diff_text_between".into(),
        }))
    }
    /// Parsed per-file unified diff comparing the tree at `from` with the tree
    /// at `to`, layered on [`diff_text_between`](GitApi::diff_text_between).
    /// The default implementation uses the default text method, allowing an
    /// implementor to opt into the parsed operation by overriding only that
    /// method.
    async fn diff_between(
        &self,
        dir: &Path,
        from: &RevSpec,
        to: &RevSpec,
    ) -> Result<Vec<FileDiff>> {
        let text = self.diff_text_between(dir, from, to).await?;
        Ok(parse_diff(&text))
    }

    // --- In-progress state ---------------------------------------------------

    /// Whether the index has no staged changes (`diff --cached --quiet`).
    async fn staged_is_empty(&self, dir: &Path) -> Result<bool>;
    /// Whether a rebase is in progress (a `rebase-merge` dir, or a `rebase-apply` dir
    /// **not** left by `git am`, exists under the git dir).
    async fn is_rebase_in_progress(&self, dir: &Path) -> Result<bool>;
    /// Whether a merge is in progress (a `MERGE_HEAD` exists under the git dir).
    async fn is_merge_in_progress(&self, dir: &Path) -> Result<bool>;
    /// Whether a `git am` (mailbox apply) is in progress (`rebase-apply/applying`).
    /// Distinct from a rebase, which shares the `rebase-apply` dir but without the
    /// `applying` marker — aborting an am needs `am --abort`, not `rebase --abort`.
    async fn is_am_in_progress(&self, dir: &Path) -> Result<bool>;
    /// Whether a cherry-pick is in progress (`CHERRY_PICK_HEAD` under the git dir).
    /// A cherry-pick conflict writes `CHERRY_PICK_HEAD`, **not** `MERGE_HEAD`, so
    /// this is distinct from a merge and is aborted/continued with
    /// `cherry-pick --abort` / `--continue`, not `merge --abort`.
    async fn is_cherry_pick_in_progress(&self, dir: &Path) -> Result<bool>;
    /// Whether a revert is in progress (`REVERT_HEAD` under the git dir). Like a
    /// cherry-pick, a revert conflict writes its own head file, not `MERGE_HEAD`;
    /// it is driven with `revert --abort` / `--continue`.
    async fn is_revert_in_progress(&self, dir: &Path) -> Result<bool>;
    /// Whether a `git bisect` session is in progress (`BISECT_LOG` under the git
    /// dir). Ended with `bisect reset` (there is no `--continue`).
    async fn is_bisect_in_progress(&self, dir: &Path) -> Result<bool>;

    // --- Mutations -----------------------------------------------------------

    /// Fetch from the default remote (`fetch --quiet`), with `GIT_TERMINAL_PROMPT=0`.
    /// Transient (network) failures are retried (3 attempts, 500 ms backoff).
    async fn fetch(&self, dir: &Path) -> Result<()>;
    /// Fetch from the default remote while reporting process lifecycle and
    /// stdout/stderr lines. This observes one process attempt (no automatic
    /// replay), so [`ProcessEvent::Exited`] is always terminal.
    async fn fetch_with_progress<'a>(
        &self,
        dir: &Path,
        progress: &'a mut ProgressCallback<'a>,
    ) -> Result<()>;
    /// Fetch from a *named* remote (`fetch --quiet <remote>`), with
    /// `GIT_TERMINAL_PROMPT=0`. Transient failures are retried like
    /// [`fetch`](GitApi::fetch).
    async fn fetch_from(&self, dir: &Path, remote: &str) -> Result<()>;
    /// Fetch a single branch from `origin` into its remote-tracking ref
    /// (`fetch --quiet origin refs/heads/<b>:refs/remotes/origin/<b>`), with
    /// `GIT_TERMINAL_PROMPT=0`. Transient failures are retried (3×, 500 ms).
    async fn fetch_branch(&self, dir: &Path, branch: &RefName) -> Result<()>;
    /// Push to a remote (`push [-u] <remote> <refspec>`); see [`GitPush`].
    async fn push(&self, dir: &Path, spec: GitPush) -> Result<()>;
    /// Push while reporting process lifecycle and stdout/stderr lines. Uses
    /// git's `--progress` flag so progress is emitted even though output is piped.
    async fn push_with_progress<'a>(
        &self,
        dir: &Path,
        spec: GitPush,
        progress: &'a mut ProgressCallback<'a>,
    ) -> Result<()>;
    /// Stage a branch's changes without committing (`merge --squash <branch>`).
    async fn merge_squash(&self, dir: &Path, branch: &RevSpec) -> Result<()>;
    /// Merge a branch (`merge [--no-ff] [-m <msg> | --no-edit] <branch>`); with no
    /// message it takes the default merge message non-interactively (`--no-edit`).
    /// See [`MergeCommit`].
    async fn merge_commit(&self, dir: &Path, spec: MergeCommit) -> Result<()>;
    /// Merge a branch but stop before committing, so the result can be inspected
    /// (`merge --no-commit [--squash | --no-ff] <branch>`). With `no_ff` (and not
    /// `squash`) git records `MERGE_HEAD`, so the in-progress merge is abortable
    /// via [`merge_abort`](GitApi::merge_abort) — the dry-run pattern. With
    /// `squash`, git stages the squashed result but records **no** `MERGE_HEAD`,
    /// so it is *not* an abortable merge: undo it with
    /// [`reset_merge`](GitApi::reset_merge) / [`reset_hard`](GitApi::reset_hard),
    /// not `merge_abort`. See [`MergeNoCommit`].
    async fn merge_no_commit(&self, dir: &Path, spec: MergeNoCommit) -> Result<()>;
    /// Abort an in-progress merge (`merge --abort`).
    async fn merge_abort(&self, dir: &Path) -> Result<()>;
    /// Finish a merge after resolving conflicts (`commit --no-edit`).
    async fn merge_continue(&self, dir: &Path) -> Result<()>;
    /// Undo an in-progress (or just-staged) merge: `reset --merge` resets the
    /// index and the merge-touched working-tree files back to `HEAD` and drops
    /// `MERGE_HEAD`, **discarding the merge's changes** while keeping unrelated
    /// unstaged edits. Use it after `merge_squash` / `merge_no_commit(squash)`,
    /// where there is no `MERGE_HEAD` for `merge_abort` to act on.
    async fn reset_merge(&self, dir: &Path) -> Result<()>;
    /// Hard-reset the working tree to a revision (`reset --hard <rev>`).
    async fn reset_hard(&self, dir: &Path, rev: &RevSpec) -> Result<()>;
    /// Rebase the current branch onto `onto` (`rebase <onto>`); the editor is
    /// suppressed (`GIT_EDITOR=true`) so it never hangs a headless caller.
    async fn rebase(&self, dir: &Path, onto: &RevSpec) -> Result<()>;
    /// Abort an in-progress rebase (`rebase --abort`).
    async fn rebase_abort(&self, dir: &Path) -> Result<()>;
    /// Abort an in-progress `git am` (`am --abort`), restoring the pre-`am` HEAD.
    async fn am_abort(&self, dir: &Path) -> Result<()>;
    /// Continue a `git am` after resolving conflicts (`am --continue`); the editor
    /// is suppressed (`GIT_EDITOR=true`) so the patch's message-confirm never hangs
    /// a headless caller. On a multi-patch mailbox it can stop again on the next
    /// patch's conflict (exit non-zero) — a conflict, not a hard error, like the
    /// other sequencer `--continue`s.
    async fn am_continue(&self, dir: &Path) -> Result<()>;
    /// Continue a rebase after resolving conflicts (`rebase --continue`); the
    /// editor is suppressed (`GIT_EDITOR=true`) so the message-confirm never hangs.
    async fn rebase_continue(&self, dir: &Path) -> Result<()>;
    /// Stash the working tree (`stash push`, `--include-untracked` when asked) —
    /// e.g. to save state before a copy-on-write restore. See [`StashPush`].
    async fn stash_push(&self, dir: &Path, spec: StashPush) -> Result<()>;
    /// Restore the most recent stash and drop it (`stash pop`).
    async fn stash_pop(&self, dir: &Path) -> Result<()>;
    /// The stash list, most-recent first (`stash@{0}`), machine-parsed via
    /// `stash list -z --format=%gd%x1f%H%x1f%gs` into typed [`StashEntry`]
    /// records — a read, unlike [`stash_push`](GitApi::stash_push)/
    /// [`stash_pop`](GitApi::stash_pop).
    async fn stash_list(&self, dir: &Path) -> Result<Vec<StashEntry>>;
    /// Apply the stash at `index` (`stash@{<index>}`, [`StashEntry::index`])
    /// **without** dropping it (`stash apply stash@{<index>}`) — unlike
    /// [`stash_pop`](GitApi::stash_pop), the stash entry survives a successful
    /// apply, so it can be applied again or dropped explicitly with
    /// [`stash_drop`](GitApi::stash_drop).
    async fn stash_apply(&self, dir: &Path, index: usize) -> Result<()>;
    /// Drop the stash at `index` (`stash@{<index>}`, [`StashEntry::index`])
    /// **without** applying it (`stash drop stash@{<index>}`) — discards the
    /// stash entry; the working tree is untouched.
    async fn stash_drop(&self, dir: &Path, index: usize) -> Result<()>;
    /// Remove untracked files/directories from the working tree (`git clean`),
    /// per [`Clean`]. **Destructive unless [`Clean::dry_run`] is set** — with
    /// neither `dry_run` nor [`Clean::force`] picked, this refuses before
    /// spawning `git` at all (an [`Error::spawn`] carrying
    /// [`std::io::ErrorKind::InvalidInput`]), so deletion is never the default
    /// and never implied by omission (see the [`Clean`] type docs). Returns
    /// the typed list of paths removed (forced) or that would be removed (dry
    /// run) — see [`CleanEntry`].
    async fn clean(&self, dir: &Path, spec: Clean) -> Result<Vec<CleanEntry>>;

    // --- Worktrees -----------------------------------------------------------

    /// List worktrees (`worktree list --porcelain`).
    async fn worktree_list(&self, dir: &Path) -> Result<Vec<Worktree>>;
    /// Add a worktree (`worktree add [-b <branch>] <path> [<commitish>]`).
    async fn worktree_add(&self, dir: &Path, spec: WorktreeAdd) -> Result<()>;
    /// Remove a worktree (`worktree remove [--force] <path>`); see [`WorktreeRemove`].
    async fn worktree_remove(&self, dir: &Path, spec: WorktreeRemove) -> Result<()>;
    /// Move a worktree (`worktree move <from> <to>`).
    async fn worktree_move(&self, dir: &Path, from: &Path, to: &Path) -> Result<()>;
    /// Prune stale worktree admin entries (`worktree prune`).
    async fn worktree_prune(&self, dir: &Path) -> Result<()>;

    // --- Sparse checkout -----------------------------------------------------

    /// Set the sparse-checkout directories or patterns
    /// (`sparse-checkout set --cone|--no-cone -- <values>`); see
    /// [`SparseCheckoutSet`]. Cone mode is the default and is recommended for
    /// directory-oriented worktrees. Values are validated before spawning and
    /// pinned after `--`, so a caller cannot turn one into a git option.
    async fn sparse_checkout_set(&self, dir: &Path, spec: SparseCheckoutSet) -> Result<()>;
    /// List the currently configured sparse-checkout directories or patterns
    /// (`sparse-checkout list`) in git's emitted order. Pattern text is kept
    /// verbatim apart from the line terminator, including meaningful spaces.
    async fn sparse_checkout_list(&self, dir: &Path) -> Result<Vec<String>>;
    /// Disable sparse checkout and repopulate the working tree
    /// (`sparse-checkout disable`).
    async fn sparse_checkout_disable(&self, dir: &Path) -> Result<()>;

    // --- Submodules ----------------------------------------------------------

    /// The submodules declared in `<dir>/.gitmodules`, parsed from the
    /// machine-unambiguous `git config --file .gitmodules --list -z` source
    /// (**not** a hand-rolled scan of the ini-style file). `dir` must be the
    /// repository's top-level working directory, where `.gitmodules` lives.
    ///
    /// A repository with no submodules has no `.gitmodules` file; that is
    /// reported as an **empty list**, not an error — the absent file is probed
    /// before spawning, so the common no-submodule case does not even run git.
    /// See [`Submodule`]. This is a pure read: `git config --file` only parses
    /// the file, so it neither clones, fetches, nor executes any submodule's
    /// config — the safe way to inspect what a (possibly untrusted)
    /// `.gitmodules` declares before deciding whether to
    /// [`submodule_update`](GitApi::submodule_update).
    async fn submodule_list(&self, dir: &Path) -> Result<Vec<Submodule>>;

    /// The sync state of the superproject's submodules (`git submodule status`):
    /// the checked-out commit, path, and a typed [`SubmoduleState`] from the
    /// line's leading `-`/`+`/`U`/space prefix. See [`SubmoduleStatus`].
    ///
    /// A read: it inspects the recorded gitlink and each initialized submodule's
    /// HEAD (briefly running `git` inside each to compute the trailing
    /// `describe`), but performs no checkout, fetch, or working-tree
    /// materialization.
    async fn submodule_status(&self, dir: &Path) -> Result<Vec<SubmoduleStatus>>;

    /// Check out the submodules to the commits the superproject records
    /// (`git submodule update [--init] [--recursive] [--depth <n>] [-- <paths>]`);
    /// see [`SubmoduleUpdate`].
    ///
    /// **Security boundary — executes a nested repository's content.** Unlike
    /// [`submodule_list`](GitApi::submodule_list) /
    /// [`submodule_status`](GitApi::submodule_status), this **fetches from the
    /// URLs `.gitmodules` records and materializes each submodule's working
    /// tree**, so it runs that nested repo's checkout-time config (filter/smudge
    /// drivers) and network transport. On a [`hardened`](Git::hardened) client
    /// the hardened environment is inherited by the `git` subprocesses this
    /// spawns, but the residual repo-local-config vectors apply per nested repo
    /// too — for a fully untrusted superproject, run this only inside an OS-level
    /// sandbox, or vet `.gitmodules` via `submodule_list` first. Terminal
    /// prompts are pinned off (`GIT_TERMINAL_PROMPT=0`) so a submodule needing
    /// credentials fails fast rather than hanging. See the submodules section of
    /// the security guide.
    ///
    /// Positional submodule paths are flag-guarded and passed after a `--`
    /// terminator, so a caller-supplied path can never be parsed as an option.
    async fn submodule_update(&self, dir: &Path, spec: SubmoduleUpdate) -> Result<()>;

    // --- Clone / tags / inspection --------------------------------------------

    /// Clone `url` into `dest` (`git clone <url> <dest>` + [`CloneSpec`] flags).
    /// Runs without a working directory — pass an **absolute** `dest`.
    async fn clone_repo(&self, url: &str, dest: &Path, spec: CloneSpec) -> Result<()>;
    /// Clone while reporting process lifecycle and stdout/stderr lines. Uses
    /// git's `--progress` flag and preserves [`clone_repo`](GitApi::clone_repo)'s
    /// failed-destination cleanup contract.
    async fn clone_repo_with_progress<'a>(
        &self,
        url: &str,
        dest: &Path,
        spec: CloneSpec,
        progress: &'a mut ProgressCallback<'a>,
    ) -> Result<()>;
    /// Create a lightweight tag at `rev` (`tag <name> [<rev>]`; `None` = HEAD).
    async fn tag_create(&self, dir: &Path, name: &RefName, rev: Option<RevSpec>) -> Result<()>;
    /// Create an annotated tag (`tag -a <name> -m <message> [<rev>]`); see
    /// [`AnnotatedTag`].
    async fn tag_create_annotated(&self, dir: &Path, spec: AnnotatedTag) -> Result<()>;
    /// Tag names, sorted by git's default ordering (`tag --list`).
    async fn tag_list(&self, dir: &Path) -> Result<Vec<String>>;
    /// Delete a tag (`tag -d <name>`).
    async fn tag_delete(&self, dir: &Path, name: &RefName) -> Result<()>;
    /// A file's content at a revision (`git show <rev>:<path>`). `path` is
    /// repo-relative; backslashes are normalised to `/` (git requires it).
    /// Content is decoded **lossily** — binary files come back mangled rather
    /// than erroring — and returned **verbatim**: the blob's trailing newline(s)
    /// are preserved (not trimmed), so a read-modify-write round-trip is byte-exact.
    ///
    /// An **empty or whitespace-only** `path` is refused **before** `git` spawns,
    /// with an [`is_invalid_input`](vcs_cli_support::is_invalid_input) error: a
    /// bare `git show <rev>:` is not an error but the root **tree listing**, so
    /// an unguarded empty path would return a directory index as if it were a
    /// file's content. `vcs_jj::JjApi::file_show` refuses the same input in the
    /// same form (T-149).
    async fn show_file(&self, dir: &Path, rev: &RevSpec, path: &str) -> Result<String>;
    /// The value of a config key, or `None` when unset (`config --get <key>`,
    /// whose exit 1 covers both "unset" and "no such section" — git doesn't
    /// distinguish). A multi-valued key errors; read those via `run`.
    async fn config_get(&self, dir: &Path, key: &str) -> Result<Option<String>>;
    /// Set a config key in the repository's local config (`config -- <key> <value>`).
    ///
    /// The `--` option terminator pins both `key` and `value` as positionals, so a
    /// `value` that looks like a flag (`--global`, `--file=<path>`, or a plain `-1`)
    /// is written *literally* as the key's value — git can never reparse it as an
    /// option redirecting the write to another config file. `value` therefore keeps
    /// no flag-shape guard on purpose (a config value may legitimately start with
    /// `-`); it is the flag *parse* that is blocked, not the leading dash. `key`
    /// additionally can't be flag-shaped (guarded before the terminator is reached).
    ///
    /// **Trusted-input sink.** This still writes whatever key/value it's given —
    /// including code-execution keys like `core.sshCommand` or `filter.<drv>.clean`.
    /// The `--` guard stops a `value` being *misparsed* as a flag; it does **not**
    /// sanitise a genuinely dangerous *key* you choose to write. Never wire
    /// untrusted input into it; a `harden()`ed client does *not* protect against
    /// config *you* write.
    async fn config_set(&self, dir: &Path, key: &str, value: &str) -> Result<()>;
    /// Add a remote (`remote add <name> <url>`).
    async fn remote_add(&self, dir: &Path, name: &str, url: &str) -> Result<()>;
    /// Change a remote's URL (`remote set-url <name> <url>`).
    async fn remote_set_url(&self, dir: &Path, name: &str, url: &str) -> Result<()>;
    /// Per-line authorship of `path` (`blame --line-porcelain [<rev>] -- <path>`;
    /// `None` = the working tree's HEAD).
    ///
    /// Unlike [`show_file`](GitApi::show_file), `path` deliberately carries **no**
    /// pre-spawn emptiness guard: it occupies a pathspec slot of its own behind
    /// `--`, where git resolves an empty or whitespace-only value as an ordinary
    /// path and **fails loudly** (`fatal: no such path '' in HEAD`, exit 128)
    /// instead of quietly answering about something else. The T-149 investigation
    /// verified this on git 2.55.0; the live `blame_and_show_file_reject_empty_path`
    /// test pins it, so a future git that started accepting it would be caught.
    async fn blame(&self, dir: &Path, path: &str, rev: Option<RevSpec>) -> Result<Vec<BlameLine>>;

    // --- Sequencer -------------------------------------------------------------

    /// Apply a commit onto the current branch (`cherry-pick <rev>`). A conflict
    /// surfaces as an error classified by [`is_merge_conflict`].
    async fn cherry_pick(&self, dir: &Path, rev: &RevSpec) -> Result<()>;
    /// Revert a commit with the default message (`revert --no-edit <rev>`).
    async fn revert(&self, dir: &Path, rev: &RevSpec) -> Result<()>;
    /// Skip the current patch of a paused rebase (`rebase --skip`). Mainly for
    /// the `apply` backend's "nothing to commit" stop — the default `merge`
    /// backend auto-drops emptied patches on `--continue`.
    async fn rebase_skip(&self, dir: &Path) -> Result<()>;
    /// Abort an in-progress cherry-pick (`cherry-pick --abort`), restoring the
    /// pre-cherry-pick state.
    async fn cherry_pick_abort(&self, dir: &Path) -> Result<()>;
    /// Continue a cherry-pick after resolving conflicts (`cherry-pick --continue`);
    /// the editor is suppressed (`GIT_EDITOR=true`) so the message-confirm never
    /// hangs a headless caller. On a multi-commit pick it can stop again on the
    /// next commit's conflict (exit non-zero) — a conflict, not a hard error.
    async fn cherry_pick_continue(&self, dir: &Path) -> Result<()>;
    /// Abort an in-progress revert (`revert --abort`), restoring the pre-revert
    /// state.
    async fn revert_abort(&self, dir: &Path) -> Result<()>;
    /// Continue a revert after resolving conflicts (`revert --continue`); the
    /// editor is suppressed like [`cherry_pick_continue`](GitApi::cherry_pick_continue),
    /// and it too can stop on the next commit's conflict.
    async fn revert_continue(&self, dir: &Path) -> Result<()>;
    /// End a `git bisect` session (`bisect reset`), returning to the branch/commit
    /// that was checked out before it started. This is the "abort" for a bisect;
    /// bisect has no `--continue`.
    async fn bisect_reset(&self, dir: &Path) -> Result<()>;
    /// Start a bisect session with `bad` and `good` bounds
    /// (`bisect start <bad> <good>`), returning the next checkout or the first
    /// bad commit when Git can finish immediately. The consumer remains
    /// responsible for running its test at each checkout and classifying it
    /// with [`bisect_good`](Self::bisect_good), [`bisect_bad`](Self::bisect_bad),
    /// or [`bisect_skip`](Self::bisect_skip). Call [`bisect_reset`](Self::bisect_reset)
    /// when the session is complete or abandoned.
    async fn bisect_start(&self, dir: &Path, bad: &RevSpec, good: &RevSpec) -> Result<BisectStep>;
    /// Mark the currently checked-out bisect revision good (`bisect good`),
    /// returning the next checkout or the first bad commit. Git advances the
    /// session; this method does not run a consumer-supplied test.
    async fn bisect_good(&self, dir: &Path) -> Result<BisectStep>;
    /// Mark the currently checked-out bisect revision bad (`bisect bad`),
    /// returning the next checkout or the first bad commit. Git advances the
    /// session; this method does not run a consumer-supplied test.
    async fn bisect_bad(&self, dir: &Path) -> Result<BisectStep>;
    /// Skip the currently checked-out bisect revision (`bisect skip`),
    /// returning the next checkout or the first bad commit. If Git reports an
    /// ambiguous set of possible first bad commits, this returns
    /// [`ErrorReason::Parse`] rather than choosing one silently; the session is
    /// still owned by Git and may be reset or driven through the raw escape
    /// hatch by the consumer.
    async fn bisect_skip(&self, dir: &Path) -> Result<BisectStep>;
}

vcs_cli_support::managed_client! {
    /// The real Git client. Generic over the [`ProcessRunner`] so tests can inject a
    /// fake process executor; [`Git::new`] uses the real job-backed runner.
    ///
    /// Wraps a [`ManagedClient`](vcs_cli_support::ManagedClient): enable lock-contention retry with
    /// [`with_retry`](Git::with_retry) (opt-in; off by default).
    ///
    /// **Every** client (not just [`hardened`](Git::hardened)) scrubs the inherited
    /// repo-**redirector** environment variables below, so a `GIT_DIR` (etc.) leaking
    /// from the parent process — e.g. running inside a git hook, which exports
    /// `GIT_DIR`/`GIT_INDEX_FILE` — can't silently redirect commands at a *different*
    /// repository than the bound `dir`. (`harden()` additionally scrubs the
    /// command-hook vars and pins hooks/fsmonitor/sshCommand off.)
    pub struct Git => BINARY, scrub_env = [
        "GIT_DIR",
        "GIT_WORK_TREE",
        "GIT_INDEX_FILE",
        "GIT_COMMON_DIR",
        "GIT_OBJECT_DIRECTORY",
        "GIT_ALTERNATE_OBJECT_DIRECTORIES",
        "GIT_NAMESPACE",
    ]
}

impl<R: ProcessRunner> Git<R> {
    /// Set the resettable output-inactivity window for Git's progress-streaming
    /// fetch/push/clone methods. Disabled by default, preserving all existing
    /// command timing when it is not configured.
    pub fn default_inactivity_timeout(mut self, timeout: std::time::Duration) -> Self {
        self.core = self.core.default_inactivity_timeout(timeout);
        self
    }

    /// Retry **whole-repo lock-contention** failures (another process holds the
    /// repo's `index.lock`) per `policy` — opt-in, off by default. Safe even for
    /// mutating commands: that lock is acquired before any write, so a failure is
    /// pre-execution (git never ran) and a retry can't double-apply. Per-ref lock
    /// failures are *not* retried (a multi-ref op can fail a ref lock mid-way). See
    /// [`RetryPolicy`] and [`is_lock_contention`].
    pub fn with_retry(mut self, policy: RetryPolicy) -> Self {
        self.core = self.core.with_retry(policy);
        self
    }

    /// Supply credentials for **HTTPS** remote operations (`fetch`/`push`/`clone`/
    /// `ls-remote`) via a [`CredentialProvider`] — opt-in, off by default (ambient
    /// git credential helpers / SSH agent). When the provider yields a credential,
    /// each remote op runs with an inline `credential.helper` that feeds the secret
    /// from an environment variable, so the token never appears in `argv`. Local
    /// operations are unaffected. This covers HTTPS only — an **SSH** remote ignores
    /// the helper and authenticates via the ambient SSH agent, as before.
    #[must_use]
    pub fn with_credentials(mut self, provider: Arc<dyn CredentialProvider>) -> Self {
        self.core = self.core.with_credentials(provider);
        self
    }

    /// Convenience for the common case: authenticate HTTPS remotes with a single
    /// static `token` (a personal-access token; the default username
    /// `x-access-token` is used). Shorthand for
    /// `with_credentials(Arc::new(StaticCredential::token(token)))`. For a specific
    /// username, build a [`Credential::userpass`] and use
    /// [`with_credentials`](Git::with_credentials).
    #[must_use]
    pub fn with_token(self, token: impl Into<Secret>) -> Self {
        self.with_credentials(Arc::new(StaticCredential::token(token)))
    }

    /// Convenience: read the HTTPS token from environment variable `var` at request
    /// time; if `var` is unset/empty, fall back to ambient auth. Shorthand for
    /// `with_credentials(Arc::new(EnvToken::new(var)))`.
    #[must_use]
    pub fn with_env_token(self, var: impl Into<String>) -> Self {
        self.with_credentials(Arc::new(EnvToken::new(var)))
    }

    /// Resolve HTTPS credentials for a remote op into the leading `-c` config args
    /// (an inline `credential.helper`) and the secret env to set on the command.
    /// Both are empty when no provider is configured — ambient git auth, unchanged.
    /// The secret lives only in the returned env, never in the args.
    ///
    /// `expect_host` scopes the helper to a host (the secret is released only for
    /// that host, so a redirect/submodule to another host can't extract it).
    /// Callers that know the operation's target host — e.g. `clone` from its URL —
    /// pass it; the others pass `None` (the helper is ungated, as before).
    ///
    /// The same `expect_host` is **also** passed as the [`CredentialRequest`]'s host,
    /// so a **host-keyed** provider selects the secret for that host — one `Git`
    /// client cloning several hosts draws each host's own token, never a
    /// neighbour's. A `None` host lets such a provider defer to ambient auth rather
    /// than hand back the wrong host's secret (the fail-closed / ambient policy is
    /// on [`ManagedClient::resolve_credential`](vcs_cli_support::ManagedClient::resolve_credential)).
    async fn remote_credentials(
        &self,
        expect_host: Option<&str>,
    ) -> Result<(Vec<String>, Vec<(String, Secret)>)> {
        match self
            .core
            .resolve_credential(CredentialService::Git, expect_host)
            .await?
        {
            Some(cred) => {
                let helper = git_credential_helper(&cred, expect_host)?;
                Ok((helper.config_args, helper.env))
            }
            None => Ok((Vec::new(), Vec::new())),
        }
    }
}

impl<R: ProcessRunner> Git<R> {
    /// [`diff_text`](GitApi::diff_text) with an explicit per-call
    /// [`OutputBudget`], instead of this client's
    /// [`default_output_budget`](Git::default_output_budget). Use it to read a
    /// legitimately large diff past a tighter client default
    /// ([`OutputBudget::unlimited`], or a higher byte cap), or to tighten the cap
    /// for one call. Past the ceiling the read errors with
    /// [`ErrorReason::OutputTooLarge`] (actual and
    /// allowed sizes) rather than buffering an unbounded diff.
    pub async fn diff_text_within(
        &self,
        dir: &Path,
        spec: DiffSpec,
        budget: OutputBudget,
    ) -> Result<String> {
        self.diff_text_budgeted(dir, spec, budget).await
    }

    /// [`diff`](GitApi::diff) with an explicit per-call [`OutputBudget`] — the
    /// parsed-model counterpart of [`diff_text_within`](Git::diff_text_within).
    pub async fn diff_within(
        &self,
        dir: &Path,
        spec: DiffSpec,
        budget: OutputBudget,
    ) -> Result<Vec<FileDiff>> {
        let text = self.diff_text_budgeted(dir, spec, budget).await?;
        Ok(parse_diff(&text))
    }

    /// [`GitApi::diff_text_between`] with an explicit per-call
    /// [`OutputBudget`], instead of this client's default budget.
    pub async fn diff_text_between_within(
        &self,
        dir: &Path,
        from: &RevSpec,
        to: &RevSpec,
        budget: OutputBudget,
    ) -> Result<String> {
        self.diff_text_between_budgeted(dir, from, to, budget).await
    }

    /// [`GitApi::diff_between`] with an explicit per-call [`OutputBudget`].
    pub async fn diff_between_within(
        &self,
        dir: &Path,
        from: &RevSpec,
        to: &RevSpec,
        budget: OutputBudget,
    ) -> Result<Vec<FileDiff>> {
        let text = self
            .diff_text_between_budgeted(dir, from, to, budget)
            .await?;
        Ok(parse_diff(&text))
    }

    /// Shared body of [`diff_text`](GitApi::diff_text) /
    /// [`diff_text_within`](Git::diff_text_within): builds the `git diff` and runs
    /// it under `budget` (a fail-loud byte ceiling; unbounded when the budget is
    /// [`OutputBudget::unlimited`]).
    async fn diff_text_budgeted(
        &self,
        dir: &Path,
        spec: DiffSpec,
        budget: OutputBudget,
    ) -> Result<String> {
        // The target is a single positional arg: `HEAD` for the working tree, or
        // the caller's `Rev` string passed straight through, unparsed. `-M`
        // enables rename detection; `--no-color` / `--no-ext-diff` keep the
        // output stable and machine-parseable.
        //
        // That passthrough is why a lone `Rev` revision (no `..`/`...`) still
        // includes working-copy changes: `git diff <rev>` diffs the working tree
        // against `<rev>`. When `HEAD` exists that matches `WorkingTree`'s target;
        // on an unborn repository, `WorkingTree` selects the empty tree below
        // while a literal `Rev("HEAD")` remains unresolved and errors. See
        // `GitApi::diff_text`'s doc for the full explanation.
        let target = match spec {
            DiffSpec::WorkingTree => {
                // On an unborn repo `HEAD` doesn't resolve (`git diff HEAD` errors);
                // diff against the empty tree so a pre-first-commit working tree
                // still yields its additions instead of a hard failure. The empty
                // tree's id depends on the repo's object format (the SHA-1
                // `EMPTY_TREE_SHA1` doesn't exist in a SHA-256 repo), so resolve it
                // from git rather than hard-coding — see `empty_tree_oid`.
                if self.is_unborn(dir).await? {
                    self.empty_tree_oid(dir).await?
                } else {
                    "HEAD".to_string()
                }
            }
            DiffSpec::Rev(rev) => {
                reject_flag_like("revision", &rev)?;
                rev
            }
        };
        // The explicit prefixes pin the `a/`…`b/` form the shared parser extracts
        // paths from — a user's `diff.noprefix` / `diff.mnemonicPrefix` config
        // would otherwise change the headers and make every file silently vanish
        // from the parse. (Command-line prefixes override both config options.)
        // `run_untrimmed_within`: trimming the diff would drop a trailing blank
        // context line, desyncing the last hunk from its `@@` line count for a
        // consumer that re-applies or re-parses it (H7); the budget bounds it.
        // Trailing `--`: pin `target` as a revision, never a pathspec — without it
        // a `Rev` that happens to name a tracked path would diff the working tree
        // for that path instead of the intended commit (the C2/M13 collision
        // class). `reject_flag_like` already blocks a leading `-`; `--` closes the
        // path-collision half.
        self.core
            .run_untrimmed_within(
                self.core.command_in(
                    dir,
                    [
                        "diff",
                        target.as_str(),
                        "--no-color",
                        "--no-ext-diff",
                        "-M",
                        "--src-prefix=a/",
                        "--dst-prefix=b/",
                        "--",
                    ],
                ),
                budget,
            )
            .await
    }

    /// Shared body of [`GitApi::diff_text_between`] and
    /// [`Git::diff_text_between_within`]. Both endpoints are already validated
    /// by [`RevSpec`]; keeping them as separate argv values avoids turning a
    /// compound selector into a range string or allowing one endpoint to be
    /// reinterpreted as a pathspec.
    async fn diff_text_between_budgeted(
        &self,
        dir: &Path,
        from: &RevSpec,
        to: &RevSpec,
        budget: OutputBudget,
    ) -> Result<String> {
        // Keep the same stable output flags and explicit prefixes as the
        // one-endpoint diff. The trailing `--` makes both validated endpoints
        // unambiguously revisions, never pathspecs; it also keeps the endpoint
        // direction exactly `from` → `to`.
        self.core
            .run_untrimmed_within(
                self.core.command_in(
                    dir,
                    [
                        "diff",
                        from.as_str(),
                        to.as_str(),
                        "--no-color",
                        "--no-ext-diff",
                        "-M",
                        "--src-prefix=a/",
                        "--dst-prefix=b/",
                        "--",
                    ],
                ),
                budget,
            )
            .await
    }

    /// [`show_file`](GitApi::show_file) with an explicit per-call
    /// [`OutputBudget`], instead of this client's
    /// [`default_output_budget`](Git::default_output_budget). Reads a blob's bytes
    /// under `budget`: past the ceiling the read errors with
    /// [`ErrorReason::OutputTooLarge`] rather than
    /// buffering an unbounded file.
    ///
    /// Rejects an empty/whitespace-only `path` before spawning, exactly as
    /// [`show_file`](GitApi::show_file) documents (it delegates here).
    pub async fn show_file_within(
        &self,
        dir: &Path,
        rev: &RevSpec,
        path: &str,
        budget: OutputBudget,
    ) -> Result<String> {
        // An empty (or whitespace-only) `path` would reduce `spec` below to a bare
        // `<rev>:`, which git does NOT reject: it prints the root TREE LISTING and
        // exits 0, so the read would hand back a directory index dressed up as a
        // file's content. Refuse before spawning — see `reject_empty_path` for why
        // this slot takes an emptiness guard rather than `reject_flag_like`, and
        // for the (differently shaped, equally silent) jj half of the same bug.
        reject_empty_path("file path", path)?;
        let rev = rev.as_str();
        // git rejects backslash separators in the `<rev>:<path>` spec ("exists on
        // disk, but not in <rev>") — normalise for Windows callers. Only on Windows:
        // on Unix a backslash is a legal filename byte, and rewriting it would make
        // a literal `a\b.txt` unresolvable.
        #[cfg(windows)]
        let path = path.replace('\\', "/");
        let spec = format!("{rev}:{path}");
        // `run_untrimmed_within`: a blob's trailing newline(s) are part of its
        // content — trimming them corrupts a read-modify-write round-trip (H7); the
        // budget bounds it.
        self.core
            .run_untrimmed_within(self.core.command_in(dir, ["show", spec.as_str()]), budget)
            .await
    }
}

/// Set each secret environment variable on `cmd` (the values from
/// [`Git::remote_credentials`]). A no-op when `envs` is empty.
fn apply_secret_env(cmd: Command, envs: &[(String, Secret)]) -> Command {
    envs.iter()
        .fold(cmd, |cmd, (name, value)| cmd.env(name, value.expose()))
}

#[async_trait::async_trait]
impl<R: ProcessRunner> GitApi for Git<R> {
    async fn run(&self, args: &[String]) -> Result<String> {
        self.core.run(args).await
    }

    async fn run_raw(&self, args: &[String]) -> Result<ProcessResult<String>> {
        self.core.output_string(args).await
    }

    async fn version(&self) -> Result<String> {
        self.core.run(["--version"]).await
    }

    async fn capabilities(&self) -> Result<GitCapabilities> {
        let raw = self.version().await?;
        let version = parse::parse_git_version(&raw).ok_or_else(|| {
            Error::parse(
                BINARY,
                format!("unrecognisable `git --version` output: {raw:?}"),
            )
        })?;
        Ok(GitCapabilities { version })
    }

    async fn status(&self, dir: &Path) -> Result<Vec<StatusEntry>> {
        // `parse_bytes`: `-z` paths are raw bytes that may not be valid UTF-8 on
        // Unix, so parse from the byte stream — a lossy `String` decode would
        // corrupt a non-ASCII/non-UTF-8 filename before it reaches the caller.
        self.core
            .parse_bytes(
                self.core
                    .command_in(dir, ["status", "--porcelain=v1", "-z"]),
                parse::parse_porcelain,
            )
            .await
    }

    async fn status_text(&self, dir: &Path) -> Result<String> {
        self.core
            .run(self.core.command_in(dir, ["status", "--porcelain=v1"]))
            .await
    }

    async fn branch_status(&self, dir: &Path) -> Result<BranchStatus> {
        // `GIT_OPTIONAL_LOCKS=0`: skip the opportunistic index refresh-write a
        // `status` may otherwise persist. This is the snapshot/poll primitive —
        // a filesystem watcher re-querying through it must not have the query
        // itself dirty `.git/index` and re-trigger the watch (verified: with
        // optional locks off, a re-query writes nothing).
        self.core
            .parse(
                self.core
                    .command_in(dir, ["status", "--porcelain=v2", "--branch", "-z"])
                    .env("GIT_OPTIONAL_LOCKS", "0"),
                parse::parse_porcelain_v2,
            )
            .await
    }

    async fn status_tracked(&self, dir: &Path) -> Result<Vec<StatusEntry>> {
        self.core
            .parse_bytes(
                self.core.command_in(
                    dir,
                    ["status", "--porcelain=v1", "-z", "--untracked-files=no"],
                ),
                parse::parse_porcelain,
            )
            .await
    }

    async fn conflicted_files(&self, dir: &Path) -> Result<Vec<PathBuf>> {
        // `-z` keeps special-character paths literal (no C-style quoting); parse
        // from raw bytes so a non-UTF-8 conflicted path survives losslessly.
        self.core
            .parse_bytes(
                self.core
                    .command_in(dir, ["diff", "--name-only", "--diff-filter=U", "-z"]),
                parse::parse_nul_paths,
            )
            .await
    }

    async fn current_branch(&self, dir: &Path) -> Result<Option<String>> {
        // `symbolic-ref --quiet --short HEAD` is the one command that answers all
        // three head states correctly in a single spawn: it prints the branch name
        // (exit 0) for a normal **and an unborn** branch (a fresh `init`/`clone`
        // before the first commit — where `rev-parse --abbrev-ref HEAD` instead
        // *errors* with exit 128), and `--quiet` makes a detached HEAD a silent
        // exit 1 (HEAD isn't a symbolic ref) rather than a `fatal:`. So map exit
        // 0 → `Some(branch)`, exit 1 → `None` (detached), and anything else (e.g.
        // not a repository, exit 128) stays a real error.
        let res = self
            .core
            .output_string(
                self.core
                    .command_in(dir, ["symbolic-ref", "--quiet", "--short", "HEAD"]),
            )
            .await?;
        match res.code() {
            Some(0) => Ok(Some(res.stdout().trim().to_string())),
            Some(1) => Ok(None), // detached HEAD: no named branch
            _ => {
                let _ = res.ensure_success()?;
                Ok(None) // unreachable: a non-zero exit always errors above
            }
        }
    }

    async fn branches(&self, dir: &Path) -> Result<Vec<Branch>> {
        // `--no-column` + `--no-color`: `column.ui = always` would columnate
        // several names onto one line and `color.{ui,branch} = always` would inject
        // ANSI escapes — both even when piped, corrupting the line parser and the
        // returned names.
        self.core
            .parse(
                self.core
                    .command_in(dir, ["branch", "--no-column", "--no-color"]),
                parse::parse_branches,
            )
            .await
    }

    async fn log(&self, dir: &Path, revspec: &RevSpec, max: usize) -> Result<Vec<Commit>> {
        let n = format!("-n{max}");
        self.core
            .parse(
                self.core.command_in(
                    dir,
                    [
                        "log",
                        revspec.as_str(),
                        n.as_str(),
                        "-z",
                        "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s",
                        "--",
                    ],
                ),
                parse::parse_log,
            )
            .await
    }

    async fn log_paths(
        &self,
        dir: &Path,
        revspec: &RevSpec,
        max: usize,
        paths: &[String],
    ) -> Result<Vec<Commit>> {
        // An empty `paths` would build `git log <revspec> -n <max> -- ` — no
        // pathspecs after `--` is the same as no `--` at all, i.e. an
        // UNRESTRICTED log. That's the opposite of "scoped to these paths",
        // so refuse before spawning (mirrors `JjApi::commit_paths`'s
        // empty-fileset guard).
        if paths.is_empty() {
            return Err(Error::spawn(
                BINARY,
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "log_paths requires at least one path — an empty list would log \
                     unrestricted history, not history scoped to the named paths",
                ),
            ));
        }
        // R-05: a single path this long can never be transmitted at all — `git
        // log` has no `--pathspec-from-file`/NUL-safe transport to fall back
        // to (unlike `add`/`commit_paths`, verified against real git: the flag
        // is rejected with "unrecognized argument"), so no chunking scheme can
        // help it. Reject up front, before `chunk_pathspecs` would otherwise
        // emit it as an over-budget singleton chunk that `git`/the OS would
        // then fail on anyway, with a much less legible spawn error.
        if let Some(oversized) = paths.iter().find(|p| p.len() + 1 > ARGV_PATHSPEC_BUDGET) {
            return Err(Error::spawn(
                BINARY,
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    format!(
                        "log_paths: a single path is {} bytes, exceeding the \
                         {ARGV_PATHSPEC_BUDGET}-byte argv pathspec budget on its own — \
                         `git log` has no NUL-safe pathspec-from-file transport (unlike \
                         `add`/`commit_paths`), so this path cannot be transmitted at all: \
                         {oversized:?}",
                        oversized.len() + 1,
                    ),
                ),
            ));
        }
        let n = format!("-n{max}");
        let chunks = chunk_pathspecs(paths);
        if chunks.len() <= 1 {
            // The common case: everything fits one call — byte-identical to the
            // pre-T-052 behavior (order included). A single invocation can't
            // observe a moving repository state mid-operation, so `revspec` is
            // forwarded as-is — no R-04 resolution needed here.
            let command = self.log_paths_command(
                dir,
                [revspec.as_str()],
                &n,
                paths.iter().map(String::as_str),
            );
            return self.core.parse(command, parse::parse_log).await;
        }
        // Large path set (T-052): `git log` has no `--pathspec-from-file`
        // support (unlike `add`/`commit_paths`), so split the pathspecs across
        // multiple argv-budget-sized calls and merge the results: dedup by hash
        // (a commit can touch paths spread across more than one chunk), then
        // reorder and cap at `max`. Requesting `-n max` per chunk is enough to
        // guarantee the merged top-`max` is correct: any commit within the true
        // (merged) top `max` has at most `max - 1` newer commits in the *entire*
        // union of chunk results, so it has at most that many newer commits
        // within its own chunk too — i.e. it always ranks within that chunk's
        // own top `max`. This bound is about *how many* qualifying commits can
        // precede another, not about how they are ordered, so it holds
        // regardless of the ordering mechanism below.
        //
        // R-04: this branch makes several independent `git` invocations (one
        // per chunk, plus the order oracle below), each of which would
        // otherwise re-resolve `revspec` on its own — a symbolic name like
        // `HEAD` can move (or a range's endpoints can) between any two of
        // them. Resolve it exactly once, up front, into the fixed set of
        // commit ids `git log` would internally expand it to (a plain rev
        // resolves to one id; a range like `A..B` resolves to two tokens, the
        // excluded side `^`-prefixed — `git rev-parse` performs the same
        // expansion `git log` does internally, so forwarding its output
        // verbatim is behavior-preserving for what a single, hypothetical
        // unchunked call would have seen). Every call below then reuses this
        // one fixed snapshot, so no ref movement during the operation can make
        // two of them disagree about what "`revspec`" names.
        let resolved_revspec: Vec<String> = self
            .core
            .run(self.core.command_in(dir, ["rev-parse", revspec.as_str()]))
            .await?
            .lines()
            .map(str::trim)
            .filter(|line| !line.is_empty())
            .map(str::to_string)
            .collect();
        let mut merged: Vec<Commit> = Vec::new();
        let mut seen = std::collections::HashSet::new();
        for chunk in &chunks {
            let command = self.log_paths_command(
                dir,
                resolved_revspec.iter().map(String::as_str),
                &n,
                chunk.iter().copied(),
            );
            let commits = self.core.parse(command, parse::parse_log).await?;
            for commit in commits {
                if seen.insert(commit.hash.clone()) {
                    merged.push(commit);
                }
            }
        }
        // Merging per-chunk call results loses git's own single-call order, so
        // restore it (R-03) via a hash-order oracle: one extra, pathless `git
        // log <revspec> --format=%H` call over the *same*, now-frozen revspec
        // (cheap — no per-path diff computation, just hashes) gives the exact
        // relative order a single unchunked call would have produced, since
        // pathspec filtering only drops non-matching commits without
        // reordering the ones that remain. A commit absent from the oracle
        // (should not happen — it always names a commit `log_paths` itself
        // just returned as reachable from `revspec`) sorts after every ranked
        // commit rather than panicking.
        let order_command = self.log_paths_order_command(dir, &resolved_revspec);
        let order = self.core.parse(order_command, parse_commit_order).await?;
        let rank: std::collections::HashMap<&str, usize> = order
            .iter()
            .enumerate()
            .map(|(index, hash)| (hash.as_str(), index))
            .collect();
        merged.sort_by_key(|commit| {
            rank.get(commit.hash.as_str())
                .copied()
                .unwrap_or(usize::MAX)
        });
        merged.truncate(max);
        Ok(merged)
    }

    async fn rev_parse(&self, dir: &Path, rev: &RevSpec) -> Result<String> {
        // `--verify`: without it, `git rev-parse Makefile` echoes the *filename* back
        // as a fake object id (exit 0), so a caller resolving an untrusted revision
        // could get a non-hash. `--verify` requires `rev` to name exactly one object,
        // erroring otherwise — a valid revision still resolves to the same full hash
        // (M13; matches `rev_parse_short`/`resolve_commit`, which already `--verify`).
        self.core
            .run(
                self.core
                    .command_in(dir, ["rev-parse", "--verify", rev.as_str()]),
            )
            .await
    }

    async fn rev_parse_short(&self, dir: &Path, rev: &RevSpec) -> Result<String> {
        // `--verify` (matching `rev_parse`/`resolve_commit`): require `rev` to name
        // exactly one object, erroring otherwise. Unlike bare `rev-parse` — which
        // echoes a filename back as a fake id (the M13 bug) — `--short` already
        // rejects a plain path (`Needed a single revision`), so this is
        // consistency / defense-in-depth: it pins the single-object contract
        // explicitly instead of leaning on `--short`'s incidental rejection. A real
        // revision still abbreviates the same.
        self.core
            .run(
                self.core
                    .command_in(dir, ["rev-parse", "--verify", "--short", rev.as_str()]),
            )
            .await
    }

    async fn init(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(self.core.command_in(dir, ["init"]))
            .await
    }

    async fn add(&self, dir: &Path, paths: &[PathBuf]) -> Result<()> {
        if pathspec_argv_len(paths.iter().map(|p| p.as_os_str())) > ARGV_PATHSPEC_BUDGET {
            // Large path set (T-052): route over stdin instead of argv, so
            // there is no OS command-line limit left to exceed.
            // `--literal-pathspecs` matches each path byte-for-byte instead of
            // treating `*`/`?`/`[]` as pathspec glob magic.
            let stdin = processkit::Stdin::from_bytes(pathspec_nul_bytes(
                paths.iter().map(|p| p.as_os_str()),
            )?);
            let command = self
                .core
                .command_in(
                    dir,
                    [
                        "--literal-pathspecs",
                        "add",
                        "--pathspec-from-file=-",
                        "--pathspec-file-nul",
                    ],
                )
                .stdin(stdin);
            return self.core.run_unit(command).await;
        }
        // `--literal-pathspecs`: same "exactly these paths, literally" contract
        // as the stdin branch above — without it, a path containing `*`/`?`/`[]`
        // would be read as pathspec glob magic instead of matched byte-for-byte
        // (R-01). `--` separates the pathspecs so a path can never be read as an
        // option.
        let mut command = self
            .core
            .command_in(dir, ["--literal-pathspecs", "add", "--"]);
        for path in paths {
            command = command.arg(path);
        }
        self.core.run_unit(command).await
    }

    async fn commit(&self, dir: &Path, message: &str) -> Result<()> {
        // C locale: a failure's output feeds `is_nothing_to_commit`.
        self.core
            .run_unit(c_locale(
                self.core.command_in(dir, ["commit", "-m", message]),
            ))
            .await
    }

    async fn create_branch(&self, dir: &Path, name: &RefName) -> Result<()> {
        self.core
            .run_unit(self.core.command_in(dir, ["branch", name.as_str()]))
            .await
    }

    async fn checkout(&self, dir: &Path, target: &CheckoutTarget) -> Result<()> {
        // `target.as_arg()` is either a validated `RevSpec` or the fixed `-`
        // literal ([`CheckoutTarget::Previous`]) — never caller-controlled argv,
        // so no flag can be injected here. The trailing `--` marks the end of
        // revisions with no pathspecs following, so git resolves the target as a
        // ref *only*. Without it a target that doesn't name a ref but names a
        // tracked path silently falls into pathspec mode and restores that path
        // from the index, discarding unstaged edits (verified: `git checkout
        // notes.txt` → "Updated 1 path", exit 0; `git checkout notes.txt --` →
        // hard error).
        self.core
            .run_unit(
                self.core
                    .command_in(dir, ["checkout", target.as_arg(), "--"]),
            )
            .await
    }

    async fn checkout_detach(&self, dir: &Path, commit: &RevSpec) -> Result<()> {
        self.core
            .run_unit(
                self.core
                    .command_in(dir, ["checkout", "--detach", commit.as_str()]),
            )
            .await
    }

    async fn commit_paths(&self, dir: &Path, spec: CommitPaths) -> Result<()> {
        // `--only -- <paths>` commits exactly these paths' working-tree content
        // regardless of the index; `--` keeps a path from being read as an option.
        // C locale: a failure's output feeds `is_nothing_to_commit`.
        if pathspec_argv_len(spec.paths.iter().map(|p| p.as_os_str())) > ARGV_PATHSPEC_BUDGET {
            // Large path set (T-052): same NUL-safe stdin transport as `add`'s
            // twin branch. Still exactly one `git commit` invocation either
            // way — the atomic-commit contract never depends on the path
            // set's size, since no chunking is ever needed here.
            let stdin = processkit::Stdin::from_bytes(pathspec_nul_bytes(
                spec.paths.iter().map(|p| p.as_os_str()),
            )?);
            let mut command =
                c_locale(self.core.command_in(dir, ["--literal-pathspecs", "commit"]));
            if spec.amend {
                command = command.arg("--amend");
            }
            command = command
                .arg("-m")
                .arg(spec.message)
                .arg("--only")
                .arg("--pathspec-from-file=-")
                .arg("--pathspec-file-nul")
                .stdin(stdin);
            return self.core.run_unit(command).await;
        }
        // `--literal-pathspecs`: same "exactly these paths, literally" contract
        // as the stdin branch above — without it, a glob-magic character
        // (`*`/`?`/`[]`) in a path would be expanded as a pathspec pattern
        // instead of matched byte-for-byte, which could commit the wrong files
        // and violate `commit_paths`'s "exactly these paths" contract (R-01).
        let mut command = c_locale(self.core.command_in(dir, ["--literal-pathspecs", "commit"]));
        if spec.amend {
            command = command.arg("--amend");
        }
        command = command.arg("-m").arg(spec.message).arg("--only").arg("--");
        for path in &spec.paths {
            command = command.arg(path);
        }
        self.core.run_unit(command).await
    }

    async fn last_commit_message(&self, dir: &Path) -> Result<String> {
        self.core
            .run(self.core.command_in(dir, ["log", "-1", "--format=%B"]))
            .await
    }

    async fn is_unborn(&self, dir: &Path) -> Result<bool> {
        // `rev-parse --verify -q HEAD` resolves HEAD quietly: 0 = a commit exists
        // (not unborn), 1 = no commit yet (unborn). `probe` maps those to a bool
        // and surfaces anything else (e.g. 128, not a repo) as `ErrorReason::Exit`.
        Ok(!self
            .core
            .probe(
                self.core
                    .command_in(dir, ["rev-parse", "--verify", "-q", "HEAD"]),
            )
            .await?)
    }

    async fn diff_is_empty(&self, dir: &Path) -> Result<bool> {
        // `git diff --quiet` is an exit-code answer: 0 = clean (empty), 1 = dirty;
        // `probe` errors on any other code / timeout / signal.
        self.core
            .probe(self.core.command_in(dir, ["diff", "--quiet"]))
            .await
    }

    async fn common_dir(&self, dir: &Path) -> Result<PathBuf> {
        Ok(PathBuf::from(
            self.core
                .run(self.core.command_in(dir, ["rev-parse", "--git-common-dir"]))
                .await?,
        ))
    }

    async fn git_dir(&self, dir: &Path) -> Result<PathBuf> {
        Ok(PathBuf::from(
            self.core
                .run(self.core.command_in(dir, ["rev-parse", "--git-dir"]))
                .await?,
        ))
    }

    async fn resolve_commit(&self, dir: &Path, rev: &RevSpec) -> Result<String> {
        // `^{commit}` peels an annotated tag down to the commit it points at.
        let spec = format!("{}^{{commit}}", rev.as_str());
        self.core
            .run(
                self.core
                    .command_in(dir, ["rev-parse", "--verify", spec.as_str()]),
            )
            .await
    }

    async fn remote_head_branch(&self, dir: &Path) -> Result<Option<String>> {
        // `--quiet` makes an *unset* origin/HEAD a silent **exit 1** (no `fatal:`
        // on stderr); that's "no default branch", not an error. Map exit 0 → the
        // branch, exit 1 → `None`, and anything else (a real failure like "not a
        // repository" exit 128, or a timeout/signal with no exit code) surfaces via
        // `ensure_success` — mirroring `config_get`, rather than swallowing it.
        let res = self
            .core
            .output_string(
                self.core
                    .command_in(dir, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]),
            )
            .await?;
        match res.code() {
            Some(0) => {
                // "refs/remotes/origin/main" → "main"; strip the whole ref prefix so
                // a slashed default branch (e.g. "release/v2") survives intact.
                let out = res.stdout().trim();
                Ok(Some(
                    out.strip_prefix("refs/remotes/origin/")
                        .unwrap_or(out)
                        .to_string(),
                ))
            }
            Some(1) => Ok(None), // unset origin/HEAD
            _ => {
                let _ = res.ensure_success()?;
                Ok(None) // unreachable: a non-zero/no-code exit always errors above
            }
        }
    }

    async fn branch_exists(&self, dir: &Path, name: &RefName) -> Result<bool> {
        let refname = format!("refs/heads/{}", name.as_str());
        // `show-ref --verify --quiet` is an exit-code answer: 0 = exists, 1 = not.
        self.core
            .probe(
                self.core
                    .command_in(dir, ["show-ref", "--verify", "--quiet", refname.as_str()]),
            )
            .await
    }

    async fn remote_branch_exists(&self, dir: &Path, name: &RefName) -> Result<bool> {
        // `RefName` already forbids the glob/control/`:` characters this probe
        // must exclude (its `check-ref-format` rules are a strict superset), so
        // the value is safe to interpolate into the `refs/heads/<name>` ref below.
        let name = name.as_str();
        // No credential prompt, bounded wait: a missing helper or a flaky network
        // must not hang the call. `output_string` reports a timeout as a flagged result
        // (non-zero exit) rather than erroring, so an unreachable remote reads as
        // "absent" (`false`) — the best-effort answer a probe wants. A genuine
        // spawn failure (no `git`) still surfaces as an error.
        //
        // Query the *fully-qualified* ref: `ls-remote origin <name>` tail-matches
        // path components, so a bare `foo` would also match `refs/heads/bar/foo`.
        // `refs/heads/<name>` matches only the exact branch.
        let refname = format!("refs/heads/{name}");
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        args.extend(["ls-remote", "origin", refname.as_str()].map(String::from));
        let cmd = apply_secret_env(
            self.core
                .command_in(dir, &args)
                .env("GIT_TERMINAL_PROMPT", "0")
                .timeout(Duration::from_secs(10)),
            &envs,
        );
        let res = self.core.output_string(cmd).await?;
        Ok(res.code() == Some(0) && !res.stdout().trim().is_empty())
    }

    async fn remote_url(&self, dir: &Path, remote: &str) -> Result<String> {
        reject_flag_like("remote name", remote)?;
        self.core
            .run(self.core.command_in(dir, ["remote", "get-url", remote]))
            .await
    }

    async fn remote_list(&self, dir: &Path) -> Result<Vec<Remote>> {
        self.core
            .parse(
                self.core.command_in(dir, ["remote", "-v"]),
                parse::parse_remotes,
            )
            .await
    }

    async fn upstream(&self, dir: &Path) -> Result<Option<String>> {
        // Validate that HEAD is attached before asking for `@{u}`. Git otherwise
        // uses exit 128 both for "no upstream" and for detached HEAD/not-a-repo,
        // so the upstream query alone cannot distinguish those states.
        let head = self
            .core
            .output_string(
                self.core
                    .command_in(dir, ["symbolic-ref", "--quiet", "--short", "HEAD"]),
            )
            .await?;
        let _ = head.ensure_success()?;

        // Once HEAD is known to be an attached branch, exit 128 is the documented
        // "no upstream configured" case. Every other failure, including a timeout
        // or signal (which has no exit code), remains a real error.
        let res = self
            .core
            .output_string(self.core.command_in(
                dir,
                ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
            ))
            .await?;
        match res.code() {
            Some(0) => {
                let name = res.stdout().trim();
                Ok((!name.is_empty()).then(|| name.to_string()))
            }
            Some(128) => Ok(None),
            _ => {
                let _ = res.ensure_success()?;
                Ok(None) // unreachable: every remaining outcome is unsuccessful
            }
        }
    }

    async fn remote_branches(&self, dir: &Path, remote: &str) -> Result<Vec<String>> {
        reject_flag_like("remote name", remote)?;
        // `GIT_TERMINAL_PROMPT=0`: a remote needing credentials must fail fast,
        // never block on an interactive auth prompt. A provider, if set, supplies
        // the credential via an inline helper (token kept out of argv).
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        args.extend(["ls-remote", "--heads", remote].map(String::from));
        let cmd = apply_secret_env(
            self.core
                .command_in(dir, &args)
                .env("GIT_TERMINAL_PROMPT", "0"),
            &envs,
        );
        self.core.parse(cmd, parse::parse_ls_remote_heads).await
    }

    async fn is_merged(&self, dir: &Path, spec: MergeCheck) -> Result<bool> {
        // `--no-column` + `--no-color`: under `column.ui = always` git would pack
        // several names per line and under `color.{ui,branch} = always` it would
        // inject ANSI escapes — both even when piped, so the marker-stripping
        // compare below would never match (a false "not merged").
        let out = self
            .core
            .run(self.core.command_in(
                dir,
                [
                    "branch",
                    "--merged",
                    spec.base.as_str(),
                    "--no-column",
                    "--no-color",
                ],
            ))
            .await?;
        // Each line is a fixed 2-column marker (`  `/`* `/`+ `) then the name;
        // drop exactly those two columns rather than trimming a char class (which
        // would over-strip a name that legitimately began with the marker char).
        Ok(out
            .lines()
            .filter_map(|line| line.get(2..))
            .any(|b| b == spec.branch.as_str()))
    }

    async fn set_upstream(&self, dir: &Path, branch: &RefName, upstream: &RefName) -> Result<()> {
        let flag = format!("--set-upstream-to={}", upstream.as_str());
        self.core
            .run_unit(
                self.core
                    .command_in(dir, ["branch", flag.as_str(), branch.as_str()]),
            )
            .await
    }

    async fn delete_branch(&self, dir: &Path, spec: BranchDelete) -> Result<()> {
        let flag = if spec.force { "-D" } else { "-d" };
        self.core
            .run_unit(
                self.core
                    .command_in(dir, ["branch", flag, spec.name.as_str()]),
            )
            .await
    }

    async fn rename_branch(&self, dir: &Path, old: &RefName, new: &RefName) -> Result<()> {
        self.core
            .run_unit(
                self.core
                    .command_in(dir, ["branch", "-m", old.as_str(), new.as_str()]),
            )
            .await
    }

    async fn rev_list_count(&self, dir: &Path, range: &RevSpec) -> Result<usize> {
        self.core
            .try_parse(
                self.core
                    .command_in(dir, ["rev-list", "--count", range.as_str()]),
                |s| {
                    s.trim()
                        .parse::<usize>()
                        .map_err(|e| Error::parse(BINARY, e.to_string()))
                },
            )
            .await
    }

    async fn diff_range_is_empty(&self, dir: &Path, range: &RevSpec) -> Result<bool> {
        // `diff --quiet <range>`: 0 = empty range, 1 = has changes.
        // The trailing `--` forces `range` to be read as a revision/range, not a
        // pathspec: without it `git diff --quiet Makefile` diffs the *working
        // tree* limited to that path (exit 1 = "has changes"), so a caller string
        // that names a file returns a plausible-but-wrong bool instead of erroring
        // (the C2/M13 pathspec-collision class). With `--`, an unresolvable
        // revision exits 128, which `probe` surfaces as an honest error.
        self.core
            .probe(
                self.core
                    .command_in(dir, ["diff", "--quiet", range.as_str(), "--"]),
            )
            .await
    }

    async fn diff_stat(&self, dir: &Path, range: &RevSpec) -> Result<DiffStat> {
        // `LC_ALL=C`: git's `--shortstat` summary ("N file(s) changed, …") is
        // gettext-translated, but `parse_shortstat` keys on the English
        // "file"/"insertion"/"deletion" — without C locale a non-English git
        // returns an all-zero `DiffStat` rather than the real counts.
        // Trailing `--`: force `range` to resolve as a revision/range, never a
        // pathspec (see `diff_range_is_empty` — a path-named `range` would
        // otherwise stat the working tree for that path instead of erroring).
        self.core
            .parse(
                c_locale(
                    self.core
                        .command_in(dir, ["diff", "--shortstat", range.as_str(), "--"]),
                ),
                parse::parse_shortstat,
            )
            .await
    }

    async fn diff_text(&self, dir: &Path, spec: DiffSpec) -> Result<String> {
        self.diff_text_budgeted(dir, spec, self.core.output_budget())
            .await
    }

    async fn diff(&self, dir: &Path, spec: DiffSpec) -> Result<Vec<FileDiff>> {
        let text = self.diff_text(dir, spec).await?;
        Ok(parse_diff(&text))
    }

    async fn diff_text_between(&self, dir: &Path, from: &RevSpec, to: &RevSpec) -> Result<String> {
        self.diff_text_between_budgeted(dir, from, to, self.core.output_budget())
            .await
    }

    async fn diff_between(
        &self,
        dir: &Path,
        from: &RevSpec,
        to: &RevSpec,
    ) -> Result<Vec<FileDiff>> {
        let text = self.diff_text_between(dir, from, to).await?;
        Ok(parse_diff(&text))
    }

    async fn staged_is_empty(&self, dir: &Path) -> Result<bool> {
        // `diff --cached --quiet`: 0 = nothing staged, 1 = staged changes.
        self.core
            .probe(self.core.command_in(dir, ["diff", "--cached", "--quiet"]))
            .await
    }

    async fn is_rebase_in_progress(&self, dir: &Path) -> Result<bool> {
        let git_dir = self.resolved_git_dir(dir).await?;
        // `rebase-merge/` is a merge-backend rebase. `rebase-apply/` is shared by an
        // apply-backend rebase AND `git am` — but `git am` marks it with an `applying`
        // file, so exclude that (it's an am, aborted with `am --abort`, not
        // `rebase --abort`; see `is_am_in_progress`). M20.
        let rebase_apply = git_dir.join("rebase-apply");
        let is_rebase_apply = rebase_apply.exists() && !rebase_apply.join("applying").exists();
        Ok(git_dir.join("rebase-merge").exists() || is_rebase_apply)
    }

    async fn is_am_in_progress(&self, dir: &Path) -> Result<bool> {
        // `git am` uses `rebase-apply/` with an `applying` marker file (an
        // apply-backend rebase uses the same dir *without* it).
        Ok(self
            .resolved_git_dir(dir)
            .await?
            .join("rebase-apply")
            .join("applying")
            .exists())
    }

    async fn is_merge_in_progress(&self, dir: &Path) -> Result<bool> {
        Ok(self
            .resolved_git_dir(dir)
            .await?
            .join("MERGE_HEAD")
            .exists())
    }

    async fn is_cherry_pick_in_progress(&self, dir: &Path) -> Result<bool> {
        Ok(self
            .resolved_git_dir(dir)
            .await?
            .join("CHERRY_PICK_HEAD")
            .exists())
    }

    async fn is_revert_in_progress(&self, dir: &Path) -> Result<bool> {
        Ok(self
            .resolved_git_dir(dir)
            .await?
            .join("REVERT_HEAD")
            .exists())
    }

    async fn is_bisect_in_progress(&self, dir: &Path) -> Result<bool> {
        // `BISECT_LOG` is git's own canonical "a bisect is running" marker (it also
        // drives `git bisect log`); the other BISECT_* files are session details.
        Ok(self
            .resolved_git_dir(dir)
            .await?
            .join("BISECT_LOG")
            .exists())
    }

    async fn fetch(&self, dir: &Path) -> Result<()> {
        // `GIT_TERMINAL_PROMPT=0` so a remote needing credentials fails fast
        // rather than blocking on an interactive prompt — matching the other
        // remote ops (`fetch_branch`, `push`, `remote_branch_exists`).
        // Fetch is idempotent, so `retry` replays it on a transient failure
        // (DNS/timeout/dropped connection); a non-transient error fails at once.
        // C locale: the retry decision classifies the failure's message.
        // Leading `-c` credential.helper (+ secret env) when a provider is set.
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        args.extend(["fetch", "--quiet"].map(String::from));
        // `budget_diagnostics`: bound the retained failure/progress output (a
        // drop-oldest tail — never `OutputTooLarge`, so `is_transient_fetch_error`
        // still classifies the tail-preserved message). Unbounded by default.
        let cmd = self.core.budget_diagnostics(apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                c_locale(self.core.command_in(dir, &args))
                    .env("GIT_TERMINAL_PROMPT", "0")
                    // Unix uses its graceful signal; Windows opts console git into
                    // CTRL_BREAK when delivery is available, with the existing
                    // hard-kill fallback for every other child.
                    .retry(FETCH_ATTEMPTS, FETCH_BACKOFF, is_transient_fetch_error),
            ),
            &envs,
        ));
        self.core.run_unit(cmd).await
    }

    async fn fetch_with_progress<'a>(
        &self,
        dir: &Path,
        progress: &'a mut ProgressCallback<'a>,
    ) -> Result<()> {
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        // `--progress` forces git to emit transfer progress even though
        // processkit pipes stderr rather than attaching a terminal.
        args.extend(["fetch", "--progress"].map(String::from));
        let cmd = self.core.budget_diagnostics(apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                c_locale(self.core.command_in(dir, &args)).env("GIT_TERMINAL_PROMPT", "0"),
            ),
            &envs,
        ));
        self.core.run_with_progress(cmd, progress).await
    }

    async fn fetch_from(&self, dir: &Path, remote: &str) -> Result<()> {
        // A leading-`-` remote is a bare positional here — and a flag like
        // `--upload-pack=<cmd>` would run an arbitrary local program for a
        // local/ext transport, so this guard is load-bearing for security.
        reject_flag_like("remote", remote)?;
        // Same containment as `fetch` (prompt off, C locale, transient retry,
        // optional credential helper), with the remote named explicitly.
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        args.extend(["fetch", "--quiet", remote].map(String::from));
        let cmd = self.core.budget_diagnostics(apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                c_locale(self.core.command_in(dir, &args))
                    .env("GIT_TERMINAL_PROMPT", "0")
                    .retry(FETCH_ATTEMPTS, FETCH_BACKOFF, is_transient_fetch_error),
            ),
            &envs,
        ));
        self.core.run_unit(cmd).await
    }

    async fn fetch_branch(&self, dir: &Path, branch: &RefName) -> Result<()> {
        // `RefName` already forbids the glob/control/`:` characters this refspec
        // must exclude (a strict superset), so both interpolations below are safe.
        let branch = branch.as_str();
        let refspec = format!("refs/heads/{branch}:refs/remotes/origin/{branch}");
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        args.extend(["fetch", "--quiet", "origin", refspec.as_str()].map(String::from));
        let cmd = self.core.budget_diagnostics(apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                c_locale(self.core.command_in(dir, &args))
                    .env("GIT_TERMINAL_PROMPT", "0")
                    .retry(FETCH_ATTEMPTS, FETCH_BACKOFF, is_transient_fetch_error),
            ),
            &envs,
        ));
        self.core.run_unit(cmd).await
    }

    async fn push(&self, dir: &Path, spec: GitPush) -> Result<()> {
        reject_flag_like("remote", &spec.remote)?;
        reject_flag_like("refspec", &spec.refspec)?;
        // M16: `reject_flag_like` catches a leading `-`/empty/NUL, but not the refspec
        // metacharacters that silently change what a push *does* — a leading `+`
        // (force-push, overwriting the remote non-fast-forward) or an extra `:` (push
        // to an unexpected remote ref). A valid refspec here is `branch` or
        // `local:remote_branch` (the single `:` is API-constructed by
        // `GitPush::refspec`), so allow at most one `:` and no leading `+` on either
        // side. A caller who genuinely needs a force-push must do it explicitly via
        // `run(["push", "--force", …])`, not smuggle a `+` through a branch name.
        let sides: Vec<&str> = spec.refspec.split(':').collect();
        if sides.len() > 2 || sides.iter().any(|s| s.starts_with('+')) {
            return Err(processkit::Error::spawn(
                BINARY,
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    format!(
                        "push refspec {:?} contains a force (`+`) or multi-ref (`:`) \
                         metacharacter — pass a plain branch or `local:remote`, or use \
                         `run([\"push\", …])` for a force-push",
                        spec.refspec
                    ),
                ),
            ));
        }
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        args.push("push".to_string());
        if spec.set_upstream {
            args.push("-u".to_string());
        }
        args.push(spec.remote.clone());
        args.push(spec.refspec.clone());
        let cmd = apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                self.core
                    .command_in(dir, &args)
                    .env("GIT_TERMINAL_PROMPT", "0"),
            ),
            &envs,
        );
        self.core.run_unit(cmd).await
    }

    async fn push_with_progress<'a>(
        &self,
        dir: &Path,
        spec: GitPush,
        progress: &'a mut ProgressCallback<'a>,
    ) -> Result<()> {
        reject_flag_like("remote", &spec.remote)?;
        reject_flag_like("refspec", &spec.refspec)?;
        let sides: Vec<&str> = spec.refspec.split(':').collect();
        if sides.len() > 2 || sides.iter().any(|s| s.starts_with('+')) {
            return Err(processkit::Error::spawn(
                BINARY,
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    format!(
                        "push refspec {:?} contains a force (`+`) or multi-ref (`:`) \
                         metacharacter — pass a plain branch or `local:remote`, or use \
                         `run([\"push\", …])` for a force-push",
                        spec.refspec
                    ),
                ),
            ));
        }
        let (pre, envs) = self.remote_credentials(None).await?;
        let mut args: Vec<String> = pre;
        args.extend(["push", "--progress"].map(String::from));
        if spec.set_upstream {
            args.push("-u".to_string());
        }
        args.push(spec.remote);
        args.push(spec.refspec);
        let cmd = apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                self.core
                    .command_in(dir, &args)
                    .env("GIT_TERMINAL_PROMPT", "0"),
            ),
            &envs,
        );
        self.core.run_with_progress(cmd, progress).await
    }

    async fn merge_squash(&self, dir: &Path, branch: &RevSpec) -> Result<()> {
        // C locale: a conflict's output feeds `is_merge_conflict` (same reason as
        // `merge_commit`/`merge_no_commit`). `--squash` never commits, so no editor.
        self.core
            .run_unit(c_locale(
                self.core
                    .command_in(dir, ["merge", "--squash", branch.as_str()]),
            ))
            .await
    }

    async fn merge_commit(&self, dir: &Path, spec: MergeCommit) -> Result<()> {
        let mut args: Vec<&str> = vec!["merge"];
        if spec.no_ff {
            args.push("--no-ff");
        }
        if let Some(msg) = spec.message.as_deref() {
            args.push("-m");
            args.push(msg);
        } else {
            // No message → take the default merge message non-interactively
            // instead of opening `$EDITOR` (which would hang a headless caller).
            args.push("--no-edit");
        }
        args.push(spec.branch.as_str());
        // C locale: a conflict's output feeds `is_merge_conflict`.
        self.core
            .run_unit(c_locale(self.core.command_in(dir, args)))
            .await
    }

    async fn merge_no_commit(&self, dir: &Path, spec: MergeNoCommit) -> Result<()> {
        let mut args: Vec<&str> = vec!["merge", "--no-commit"];
        // `--squash` and `--no-ff` are mutually exclusive (git rejects the pair);
        // a squash never fast-forwards anyway, so it takes precedence.
        if spec.squash {
            args.push("--squash");
        } else if spec.no_ff {
            args.push("--no-ff");
        }
        args.push(spec.branch.as_str());
        // C locale: a conflict's output feeds `is_merge_conflict`.
        self.core
            .run_unit(c_locale(self.core.command_in(dir, args)))
            .await
    }

    async fn merge_abort(&self, dir: &Path) -> Result<()> {
        self.core.run_unit(self.merge_abort_command(dir)).await
    }

    async fn merge_continue(&self, dir: &Path) -> Result<()> {
        // `--no-edit` already reuses the prepared MERGE_MSG; `no_editor` is a
        // headless backstop so a commit hook re-opening the editor can't hang.
        // C locale: the failure output feeds the classifiers (a still-conflicted
        // tree reports "nothing to commit"-adjacent / conflict messages).
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["commit", "--no-edit"]),
            )))
            .await
    }

    async fn reset_merge(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(self.core.command_in(dir, ["reset", "--merge"]))
            .await
    }

    async fn reset_hard(&self, dir: &Path, rev: &RevSpec) -> Result<()> {
        self.core
            .run_unit(self.core.command_in(dir, ["reset", "--hard", rev.as_str()]))
            .await
    }

    async fn rebase(&self, dir: &Path, onto: &RevSpec) -> Result<()> {
        // Force a no-op editor so a rebase that would open `$EDITOR` (reword, or
        // the message-confirm on `--continue`) never hangs a headless caller.
        // C locale: a conflict's output feeds `is_merge_conflict`.
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["rebase", onto.as_str()]),
            )))
            .await
    }

    async fn rebase_abort(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(c_locale(self.core.command_in(dir, ["rebase", "--abort"])))
            .await
    }

    async fn am_abort(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(c_locale(self.core.command_in(dir, ["am", "--abort"])))
            .await
    }

    async fn am_continue(&self, dir: &Path) -> Result<()> {
        // `am --continue` re-applies the resolved patch and commits it; a patch's
        // message-confirm could open the editor — force a no-op editor so a headless
        // caller can't hang. C locale: a re-conflict's output feeds `is_merge_conflict`.
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["am", "--continue"]),
            )))
            .await
    }

    async fn rebase_continue(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["rebase", "--continue"]),
            )))
            .await
    }

    async fn stash_push(&self, dir: &Path, spec: StashPush) -> Result<()> {
        let mut command = self.core.command_in(dir, ["stash", "push"]);
        if spec.include_untracked {
            command = command.arg("--include-untracked");
        }
        self.core.run_unit(command).await
    }

    async fn stash_pop(&self, dir: &Path) -> Result<()> {
        // C locale: a conflicting `stash pop` emits git's merge-machinery
        // `CONFLICT (...)` output, which feeds `is_merge_conflict` (e.g. via
        // `switch_with_stash`) — a translated message would defeat it.
        self.core
            .run_unit(c_locale(self.core.command_in(dir, ["stash", "pop"])))
            .await
    }

    async fn stash_list(&self, dir: &Path) -> Result<Vec<StashEntry>> {
        self.core
            .parse(
                self.core
                    .command_in(dir, ["stash", "list", "-z", "--format=%gd%x1f%H%x1f%gs"]),
                parse::parse_stash_list,
            )
            .await
    }

    async fn stash_apply(&self, dir: &Path, index: usize) -> Result<()> {
        // `stash@{<index>}` — the selector always starts with the fixed literal
        // `stash@{`, so a `usize` index can never be parsed as a flag; no
        // injection guard is needed on top of that shape. C locale: a
        // conflicting apply emits the same merge-machinery output `stash_pop`
        // does, feeding `is_merge_conflict`.
        let command = self
            .core
            .command_in(dir, ["stash", "apply"])
            .arg(format!("stash@{{{index}}}"));
        self.core.run_unit(c_locale(command)).await
    }

    async fn stash_drop(&self, dir: &Path, index: usize) -> Result<()> {
        let command = self
            .core
            .command_in(dir, ["stash", "drop"])
            .arg(format!("stash@{{{index}}}"));
        self.core.run_unit(command).await
    }

    async fn clean(&self, dir: &Path, spec: Clean) -> Result<Vec<CleanEntry>> {
        // Neither `dry_run` nor `force`: refuse before spawning, rather than
        // either running a no-op-guarded `git clean` whose safety depends on
        // the caller's `clean.requireForce` config, or silently doing nothing.
        if !spec.dry_run && !spec.force {
            return Err(Error::spawn(
                BINARY,
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "clean requires either Clean::dry_run() or Clean::force() — refusing \
                     to run with neither, rather than depend on this repository's \
                     `clean.requireForce` config to guard the delete",
                ),
            ));
        }
        let mut command = self.core.command_in(dir, ["clean"]);
        // `dry_run` always wins: with it set, `-f` is never sent, so a spec
        // that (oddly) sets both can never actually delete.
        command = command.arg(if spec.dry_run { "-n" } else { "-f" });
        if spec.directories {
            command = command.arg("-d");
        }
        match spec.ignored {
            CleanIgnored::Exclude => {}
            CleanIgnored::Include => command = command.arg("-x"),
            CleanIgnored::Only => command = command.arg("-X"),
        }
        // C locale: `parse_clean_output` keys on the English "Would remove "/
        // "Removing " prefixes; git gettext-translates both under a non-English
        // locale. Unwrapped, a forced clean would still delete files but return
        // an empty `Vec<CleanEntry>` (losing the audit trail of what was
        // removed), and a dry run would falsely report nothing to remove — same
        // failure mode `diff_stat`'s `c_locale` wrap guards against above.
        self.core
            .parse(c_locale(command), parse::parse_clean_output)
            .await
    }

    async fn worktree_list(&self, dir: &Path) -> Result<Vec<Worktree>> {
        // `parse_bytes`: the porcelain `worktree <path>` value is a filesystem path
        // that need not be valid UTF-8 on Unix, so parse from raw stdout bytes — a
        // lossy `String` decode would corrupt a non-UTF-8 worktree name to `U+FFFD`
        // and leak a wrong path into the facade's `WorktreeInfo.path`. (Deliberately
        // no `-z`: `worktree list --porcelain -z` is git ≥ 2.36, above this crate's
        // 2.31 support floor; newline framing already covers the non-UTF-8 case.)
        self.core
            .parse_bytes(
                self.core
                    .command_in(dir, ["worktree", "list", "--porcelain"]),
                parse::parse_worktree_porcelain,
            )
            .await
    }

    async fn worktree_add(&self, dir: &Path, spec: WorktreeAdd) -> Result<()> {
        reject_flag_like_path("worktree path", &spec.path)?;
        let mut command = self.core.command_in(dir, ["worktree", "add"]);
        if let Some(name) = spec.new_branch.as_ref() {
            command = command.arg("-b").arg(name.as_str());
        }
        if spec.no_checkout {
            command = command.arg("--no-checkout");
        }
        command = command.arg(&spec.path);
        if let Some(commitish) = spec.commitish.as_ref() {
            command = command.arg(commitish.as_str());
        }
        self.core.run_unit(command).await
    }

    async fn worktree_remove(&self, dir: &Path, spec: WorktreeRemove) -> Result<()> {
        reject_flag_like_path("worktree path", &spec.path)?;
        let mut command = self.core.command_in(dir, ["worktree", "remove"]);
        if spec.force {
            command = command.arg("--force");
        }
        command = command.arg(&spec.path);
        self.core.run_unit(command).await
    }

    async fn worktree_move(&self, dir: &Path, from: &Path, to: &Path) -> Result<()> {
        reject_flag_like_path("worktree move source path", from)?;
        reject_flag_like_path("worktree move destination path", to)?;
        let command = self
            .core
            .command_in(dir, ["worktree", "move"])
            .arg(from)
            .arg(to);
        self.core.run_unit(command).await
    }

    async fn worktree_prune(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(self.core.command_in(dir, ["worktree", "prune"]))
            .await
    }

    async fn sparse_checkout_set(&self, dir: &Path, spec: SparseCheckoutSet) -> Result<()> {
        if spec.patterns.is_empty() {
            return Err(Error::spawn(
                BINARY,
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "sparse_checkout_set requires at least one directory or pattern",
                ),
            ));
        }
        // `--` pins every caller-provided value as a positional. Keep the
        // content guard as well: a leading dash is almost always an accidental
        // option-shaped path/pattern, and rejecting it gives the same clear
        // pre-spawn error as the other bare positional surfaces.
        for pattern in &spec.patterns {
            reject_flag_like("sparse-checkout pattern", pattern)?;
        }

        let mode = if spec.cone { "--cone" } else { "--no-cone" };
        let mut command = self
            .core
            .command_in(dir, ["sparse-checkout", "set", mode, "--"]);
        for pattern in &spec.patterns {
            command = command.arg(pattern);
        }
        self.core.run_unit(command).await
    }

    async fn sparse_checkout_list(&self, dir: &Path) -> Result<Vec<String>> {
        self.core
            .parse(
                self.core.command_in(dir, ["sparse-checkout", "list"]),
                parse_sparse_checkout_list,
            )
            .await
    }

    async fn sparse_checkout_disable(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(self.core.command_in(dir, ["sparse-checkout", "disable"]))
            .await
    }

    async fn submodule_list(&self, dir: &Path) -> Result<Vec<Submodule>> {
        // `.gitmodules` at the repo top is the registry of declared submodules; a
        // repo with none simply has no such file. Probe for it (relative to `dir`,
        // exactly where `git config --file .gitmodules` resolves it) first: an
        // absent file means "no submodules" — an empty list, not git's exit-128
        // "unable to read config file" error — and no process is spawned in the
        // common no-submodule case. A present-but-malformed file still surfaces as
        // a real error from the parse below.
        if !dir.join(".gitmodules").exists() {
            return Ok(Vec::new());
        }
        // `parse_bytes`: a submodule `path` value may not be valid UTF-8 on Unix,
        // so parse from raw stdout bytes (a lossy `String` decode would corrupt it
        // to `U+FFFD`). `-z` frames each `key\nvalue` record with a NUL, robust
        // against a value that contains `=` or whitespace.
        self.core
            .parse_bytes(
                self.core
                    .command_in(dir, ["config", "--file", ".gitmodules", "--list", "-z"]),
                parse::parse_gitmodules_config,
            )
            .await
    }

    async fn submodule_status(&self, dir: &Path) -> Result<Vec<SubmoduleStatus>> {
        // `parse_bytes`: the reported submodule path may not be valid UTF-8 on
        // Unix. `git submodule status` has no `-z` option (it is not a plumbing
        // command), so the parser splits the optional trailing ` (describe)` from
        // the path heuristically — see `parse_submodule_status`.
        self.core
            .parse_bytes(
                self.core.command_in(dir, ["submodule", "status"]),
                parse::parse_submodule_status,
            )
            .await
    }

    async fn submodule_update(&self, dir: &Path, spec: SubmoduleUpdate) -> Result<()> {
        // Guard each positional submodule path: a leading-`-` value after the
        // `--` terminator is already inert as a flag, but reject it up front for
        // a clear, uniform error (matching the other bare-positional slots).
        for path in &spec.paths {
            reject_flag_like("submodule path", path)?;
        }
        let mut command = self.core.command_in(dir, ["submodule", "update"]);
        if spec.init {
            command = command.arg("--init");
        }
        if spec.recursive {
            command = command.arg("--recursive");
        }
        if let Some(depth) = spec.depth {
            command = command.arg("--depth").arg(depth.to_string());
        }
        if !spec.paths.is_empty() {
            // `--` closes git's option grammar so every following path is a bare
            // positional, never reparsed as a flag.
            command = command.arg("--");
            for path in &spec.paths {
                command = command.arg(path);
            }
        }
        // `GIT_TERMINAL_PROMPT=0`: `update` fetches each submodule, so a missing
        // credential must fail fast rather than block on an interactive prompt —
        // matching `fetch`/`clone`.
        self.core
            .run_unit(command.env("GIT_TERMINAL_PROMPT", "0"))
            .await
    }

    async fn clone_repo(&self, url: &str, dest: &Path, spec: CloneSpec) -> Result<()> {
        // A leading-`-` url is a bare positional — `git clone --upload-pack=<cmd>`
        // would run an arbitrary local program. A real URL never leads with `-`,
        // so this guard has no false positives.
        reject_flag_like("url", url)?;
        validate_clone_spec(&spec)?;
        // No working directory: clone creates `dest` itself, so `dest` should
        // be absolute (a relative path would resolve against this process' cwd).
        // Leading `-c` credential.helper (+ secret env) when a provider is set,
        // scoped to the clone URL's host so a cross-host redirect/submodule during
        // the clone can't extract the token (the URL is often externally supplied).
        let (pre, envs) = self
            .remote_credentials(vcs_cli_support::https_host(url).as_deref())
            .await?;
        let mut initial: Vec<String> = pre;
        initial.extend(clone_args(&spec, false));
        let command = self.core.command(&initial);
        // `budget_diagnostics`: bound the retained clone progress/failure output
        // (a drop-oldest tail — never `OutputTooLarge`, so a real failure stays a
        // classifiable `ErrorReason::Exit`). Unbounded by default.
        let command = self.core.budget_diagnostics(apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                command.arg(url).arg(dest).env("GIT_TERMINAL_PROMPT", "0"),
            ),
            &envs,
        ));

        // R7: git populates `dest` incrementally, so a failed clone (timeout, network,
        // auth) can leave a **partial, non-empty** `dest` that blocks a retry with
        // "destination path already exists and is not empty". The completion
        // policy's soft trigger is best-effort on Windows (the child must share the
        // console and handle CTRL_BREAK), and the Unix grace is too short to delete
        // a multi-GB partial. So clean it ourselves,
        // via the shared `vcs_cli_support` helper (also used by `vcs_jj::git_clone`) —
        // see its docs for the "never touch a non-empty pre-existing dest" contract and
        // why `cleanable` must be computed before the clone runs.
        let cleanable = vcs_cli_support::clone_dest_cleanable(dest);
        let result = self.core.run_unit(command).await;
        if result.is_err() {
            vcs_cli_support::cleanup_failed_clone_dest(dest, cleanable);
        }
        result
    }

    async fn clone_repo_with_progress<'a>(
        &self,
        url: &str,
        dest: &Path,
        spec: CloneSpec,
        progress: &'a mut ProgressCallback<'a>,
    ) -> Result<()> {
        reject_flag_like("url", url)?;
        validate_clone_spec(&spec)?;
        let (pre, envs) = self
            .remote_credentials(vcs_cli_support::https_host(url).as_deref())
            .await?;
        let mut initial: Vec<String> = pre;
        initial.extend(clone_args(&spec, true));
        let command = self.core.command(&initial);
        let command = self.core.budget_diagnostics(apply_secret_env(
            vcs_cli_support::apply_fetch_completion_policy(
                command.arg(url).arg(dest).env("GIT_TERMINAL_PROMPT", "0"),
            ),
            &envs,
        ));
        let cleanable = vcs_cli_support::clone_dest_cleanable(dest);
        let result = self.core.run_with_progress(command, progress).await;
        if result.is_err() {
            vcs_cli_support::cleanup_failed_clone_dest(dest, cleanable);
        }
        result
    }

    async fn tag_create(&self, dir: &Path, name: &RefName, rev: Option<RevSpec>) -> Result<()> {
        let mut args = vec!["tag", name.as_str()];
        if let Some(rev) = rev.as_ref() {
            args.push(rev.as_str());
        }
        self.core.run_unit(self.core.command_in(dir, args)).await
    }

    async fn tag_create_annotated(&self, dir: &Path, spec: AnnotatedTag) -> Result<()> {
        let mut args = vec!["tag", "-a", spec.name.as_str(), "-m", &spec.message];
        if let Some(rev) = spec.rev.as_ref() {
            args.push(rev.as_str());
        }
        self.core.run_unit(self.core.command_in(dir, args)).await
    }

    async fn tag_list(&self, dir: &Path) -> Result<Vec<String>> {
        // `--no-column`: a user's `column.ui = always` would pack several tags
        // onto one line even when piped, corrupting the one-per-line split.
        let out = self
            .core
            .run(self.core.command_in(dir, ["tag", "--list", "--no-column"]))
            .await?;
        Ok(out.lines().map(str::to_string).collect())
    }

    async fn tag_delete(&self, dir: &Path, name: &RefName) -> Result<()> {
        self.core
            .run_unit(self.core.command_in(dir, ["tag", "-d", name.as_str()]))
            .await
    }

    async fn show_file(&self, dir: &Path, rev: &RevSpec, path: &str) -> Result<String> {
        self.show_file_within(dir, rev, path, self.core.output_budget())
            .await
    }

    async fn config_get(&self, dir: &Path, key: &str) -> Result<Option<String>> {
        reject_flag_like("config key", key)?;
        let res = self
            .core
            .output_string(self.core.command_in(dir, ["config", "--get", key]))
            .await?;
        match res.code() {
            // Exit 1 = unset (git lumps "no such key/section" in here too).
            Some(1) => Ok(None),
            // Strip only git's trailing line terminator (`\n`, or `\r\n`), not all
            // trailing whitespace: a config value can legitimately end in spaces or
            // a tab (e.g. a templated prefix), and `--get` returns a single line, so
            // it never itself ends in a newline.
            Some(0) => Ok(Some(
                res.stdout().trim_end_matches(['\r', '\n']).to_string(),
            )),
            _ => {
                let _ = res.ensure_success()?;
                Ok(None) // unreachable: a non-zero exit always errors above.
            }
        }
    }

    async fn config_set(&self, dir: &Path, key: &str, value: &str) -> Result<()> {
        reject_flag_like("config key", key)?;
        // `--` closes git's option grammar: `key` and `value` are pinned as bare
        // positionals, so a `value` shaped like a flag (`--global`, `--file=<path>`,
        // `--worktree`) is stored *literally* rather than reparsed by git as an
        // option that would redirect the write to another config file. `value`
        // deliberately keeps no `reject_flag_like` guard — a config value may
        // legitimately begin with `-` (e.g. `-1`); it is the flag *parse* that must
        // be blocked, not the leading dash. (`key` stays flag-guarded above, before
        // the terminator is even reached.) Verified on git 2.54; the `repo.rs`
        // integration round-trip re-checks it on the live binary. (T-083.)
        self.core
            .run_unit(self.core.command_in(dir, ["config", "--", key, value]))
            .await
    }

    async fn remote_add(&self, dir: &Path, name: &str, url: &str) -> Result<()> {
        reject_flag_like("remote name", name)?;
        reject_flag_like("url", url)?;
        self.core
            .run_unit(self.core.command_in(dir, ["remote", "add", name, url]))
            .await
    }

    async fn remote_set_url(&self, dir: &Path, name: &str, url: &str) -> Result<()> {
        reject_flag_like("remote name", name)?;
        reject_flag_like("url", url)?;
        self.core
            .run_unit(self.core.command_in(dir, ["remote", "set-url", name, url]))
            .await
    }

    async fn blame(&self, dir: &Path, path: &str, rev: Option<RevSpec>) -> Result<Vec<BlameLine>> {
        // No `reject_empty_path` here on purpose (T-149, the symmetric read this
        // task audited alongside `show_file`): `path` is its own pathspec behind
        // `--`, not text spliced into a `<rev>:<path>` spec, and git answers an
        // empty/whitespace-only pathspec with a hard `fatal: no such path …`
        // (exit 128) rather than a silently different result — the trait docs
        // record the finding, the live test pins it.
        let mut args = vec!["blame", "--line-porcelain"];
        if let Some(rev) = rev.as_ref() {
            args.push(rev.as_str());
        }
        args.push("--");
        args.push(path);
        self.core
            .parse(
                self.core.command_in(dir, args),
                parse::parse_blame_porcelain,
            )
            .await
    }

    async fn cherry_pick(&self, dir: &Path, rev: &RevSpec) -> Result<()> {
        // No editor opens non-interactively, but keep the headless backstop.
        // C locale: a conflict's output feeds `is_merge_conflict`.
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["cherry-pick", rev.as_str()]),
            )))
            .await
    }

    async fn revert(&self, dir: &Path, rev: &RevSpec) -> Result<()> {
        self.core
            .run_unit(no_editor(c_locale(
                self.core
                    .command_in(dir, ["revert", "--no-edit", rev.as_str()]),
            )))
            .await
    }

    async fn rebase_skip(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["rebase", "--skip"]),
            )))
            .await
    }

    async fn cherry_pick_abort(&self, dir: &Path) -> Result<()> {
        // No editor on --abort, but keep the C locale so any failure output still
        // feeds the classifiers uniformly with the rest of the sequencer.
        self.core
            .run_unit(c_locale(
                self.core.command_in(dir, ["cherry-pick", "--abort"]),
            ))
            .await
    }

    async fn cherry_pick_continue(&self, dir: &Path) -> Result<()> {
        // `--continue` re-commits the resolved pick and may open the editor to
        // confirm the message — force a no-op editor so a headless caller can't
        // hang. C locale: a re-conflict's output feeds `is_merge_conflict`.
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["cherry-pick", "--continue"]),
            )))
            .await
    }

    async fn revert_abort(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(c_locale(self.core.command_in(dir, ["revert", "--abort"])))
            .await
    }

    async fn revert_continue(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(no_editor(c_locale(
                self.core.command_in(dir, ["revert", "--continue"]),
            )))
            .await
    }

    async fn bisect_reset(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(c_locale(self.core.command_in(dir, ["bisect", "reset"])))
            .await
    }

    async fn bisect_start(&self, dir: &Path, bad: &RevSpec, good: &RevSpec) -> Result<BisectStep> {
        self.core
            .try_parse(
                c_locale(
                    self.core
                        .command_in(dir, ["bisect", "start", bad.as_str(), good.as_str()]),
                ),
                parse::parse_bisect_step,
            )
            .await
    }

    async fn bisect_good(&self, dir: &Path) -> Result<BisectStep> {
        self.core
            .try_parse(
                c_locale(self.core.command_in(dir, ["bisect", "good"])),
                parse::parse_bisect_step,
            )
            .await
    }

    async fn bisect_bad(&self, dir: &Path) -> Result<BisectStep> {
        self.core
            .try_parse(
                c_locale(self.core.command_in(dir, ["bisect", "bad"])),
                parse::parse_bisect_step,
            )
            .await
    }

    async fn bisect_skip(&self, dir: &Path) -> Result<BisectStep> {
        self.core
            .try_parse(
                c_locale(self.core.command_in(dir, ["bisect", "skip"])),
                parse::parse_bisect_step,
            )
            .await
    }
}

impl<R: ProcessRunner> Git<R> {
    /// Build one `git --literal-pathspecs log <revs...> -n<max> -z --format=…
    /// -- <paths>` call — used both for the common case (everything fits one
    /// invocation, the direct [`GitApi::log_paths`] call, where `revs` is the
    /// single, as-given `revspec.as_str()`) and for each chunk of its
    /// large-path-set fallback (T-052; the two need no different format,
    /// since chunked order is restored afterwards by
    /// [`Self::log_paths_order_command`], not by anything embedded in each
    /// chunk's own output — R-03). On the chunked path, `revs` is instead the
    /// caller's already-resolved, fixed commit-id tokens (T-052/R-04; see
    /// [`GitApi::log_paths`]) — one for a plain rev, two (tip + `^`-prefixed
    /// exclusion) for a range — reused verbatim across every chunk so none of
    /// them can observe a differently-moved ref than another.
    /// `--literal-pathspecs` matches a path containing `*`/`?`/`[]` literally
    /// rather than as pathspec glob magic (R-02).
    fn log_paths_command<'a>(
        &self,
        dir: &Path,
        revs: impl IntoIterator<Item = &'a str>,
        n: &str,
        paths: impl IntoIterator<Item = &'a str>,
    ) -> Command {
        let mut command = self.core.command_in(dir, ["--literal-pathspecs", "log"]);
        for rev in revs {
            command = command.arg(rev);
        }
        command = command
            .arg(n)
            .arg("-z")
            .arg("--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s")
            .arg("--");
        for path in paths {
            command = command.arg(path);
        }
        command
    }

    /// Build the pathless `git log <revs...> -z --format=%H` commit-order
    /// oracle used to restore git's own order across `log_paths`'s merged
    /// chunk results (T-052/R-03; see [`GitApi::log_paths`]). `revs` is the
    /// same already-resolved, fixed commit-id tokens the chunk calls used
    /// (T-052/R-04) — resolving the revspec independently here, after the
    /// chunk calls already ran, would reopen exactly the race that resolving
    /// it once up front closes. No `-n` cap: a commit surviving
    /// path-filtering into the merged top-`max` can sit arbitrarily far back
    /// in the *unrestricted* history (many untouched commits between it and
    /// the tip), so the oracle must be able to rank it — capping this call
    /// risks an unranked commit outside the map. No paths, so no
    /// `--literal-pathspecs` is needed here. Parsed by [`parse_commit_order`].
    fn log_paths_order_command(&self, dir: &Path, revs: &[String]) -> Command {
        let mut command = self.core.command_in(dir, ["log"]);
        for rev in revs {
            command = command.arg(rev);
        }
        command.arg("-z").arg("--format=%H")
    }

    /// Build the `merge --abort` command with the C locale forced (a failed
    /// abort's output feeds the same classifiers as the merge it undoes). Shared
    /// by the token-inheriting [`merge_abort`](GitApi::merge_abort) and the
    /// detached [`merge_abort_detached`](Self::merge_abort_detached) so the two
    /// argv/locale forms cannot drift.
    fn merge_abort_command(&self, dir: &Path) -> Command {
        c_locale(self.core.command_in(dir, ["merge", "--abort"]))
    }

    /// Turn a repo-scoped `command` into a rollback **cleanup** step: it drops
    /// this client's [`default_cancel_on`](Git::default_cancel_on) token for a
    /// fresh, never-fired one and applies the bounded
    /// [`MERGE_ABORT_CLEANUP_TIMEOUT`] deadline — the git analogue of jj's
    /// `rollback_cmd_in`. A command built this way runs even after the client
    /// token that governed the probe has already fired, so `Repo::try_merge`'s
    /// Ok/Err cleanup can both **decide** to roll back (the
    /// [`is_merge_in_progress_detached`](Self::is_merge_in_progress_detached)
    /// probe) and **perform** it
    /// ([`merge_abort_detached`](Self::merge_abort_detached)) despite a cancelled
    /// or timed-out probe merge — the *whole* decision-plus-command rollback path
    /// is detached, matching jj rather than only the final abort command.
    fn detached_cleanup(&self, command: Command) -> Command {
        command
            .cancel_on(CancellationToken::new())
            .timeout(MERGE_ABORT_CLEANUP_TIMEOUT)
    }

    /// Abort an in-progress merge (`merge --abort`) as a **rollback cleanup** that
    /// deliberately does **not** inherit this client's
    /// [`default_cancel_on`](Git::default_cancel_on) token and runs under its own
    /// bounded `MERGE_ABORT_CLEANUP_TIMEOUT` deadline — mirroring jj's
    /// `Jj::rollback_to`.
    ///
    /// The trait [`merge_abort`](GitApi::merge_abort) inherits the client's cancel
    /// token, so once that token has already fired — a cancelled or timed-out probe
    /// merge — the abort that should undo the half-staged trial merge would itself
    /// be cancelled, leaving the merge in the working tree. Building it through the
    /// internal `detached_cleanup` (a fresh, never-fired [`CancellationToken`] and a
    /// full fresh timeout budget) lets it complete regardless, so a probe's own
    /// cancellation no longer disables its rollback. Same `merge --abort` argv as
    /// [`merge_abort`](GitApi::merge_abort); used by the facade `Repo::try_merge`'s
    /// error-branch cleanup — paired with
    /// [`is_merge_in_progress_detached`](Self::is_merge_in_progress_detached) so the
    /// *decision* to abort is detached too, not just this command.
    pub async fn merge_abort_detached(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(self.detached_cleanup(self.merge_abort_command(dir)))
            .await
    }

    /// [`is_merge_in_progress`](GitApi::is_merge_in_progress) on the detached
    /// rollback-cleanup context (the internal `detached_cleanup`), so the
    /// **decision** of whether a trial merge is still staged survives an
    /// already-fired client [`default_cancel_on`](Git::default_cancel_on) token.
    ///
    /// The trait probe's underlying `rev-parse --git-dir` inherits the client
    /// token; once a probe merge's cancellation has fired, that probe's `?` would
    /// propagate `ErrorReason::Cancelled` **before** the abort that undoes the trial
    /// merge is ever reached, leaving it staged in the working tree. Resolving the
    /// git dir on a fresh token instead lets the decision complete, so it pairs
    /// with [`merge_abort_detached`](Self::merge_abort_detached) to make **both**
    /// halves of `Repo::try_merge`'s Ok/Err cleanup cancellation-safe — matching
    /// jj, whose op-log rollback probe also runs on the detached context.
    pub async fn is_merge_in_progress_detached(&self, dir: &Path) -> Result<bool> {
        Ok(self
            .resolved_git_dir_detached(dir)
            .await?
            .join("MERGE_HEAD")
            .exists())
    }
}

// --- Internal helpers --------------------------------------------------------
//
// The error classifiers (`is_merge_conflict`/`is_nothing_to_commit`/
// `is_transient_fetch_error`), the fetch-retry policy, and the argv injection
// guard now live in the shared `vcs-cli-support` crate (re-exported at the top of
// this module); what remains here is git-specific.

/// Git's well-known **SHA-1** empty-tree object id. This value exists **only in a
/// SHA-1 repository**: a repo created with `extensions.objectFormat=sha256` has a
/// different empty-tree id (and this SHA-1 one resolves to no object there), so
/// this constant is *not* a universal stand-in for `HEAD` when diffing an unborn
/// working tree. For the id that matches a repository's active object format, use
/// [`Git::empty_tree_oid`], which asks git for it — that is what
/// [`diff_text`](GitApi::diff_text)`(DiffSpec::WorkingTree)` uses on an unborn repo.
pub const EMPTY_TREE_SHA1: &str = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";

/// Total attempts / fixed backoff for a transient-retried `fetch` — the shared
/// policy from `vcs-cli-support`, aliased so the retry call sites read locally.
const FETCH_ATTEMPTS: u32 = vcs_cli_support::FETCH_ATTEMPTS;
const FETCH_BACKOFF: Duration = vcs_cli_support::FETCH_BACKOFF;

/// Bounded deadline for the detached rollback abort
/// ([`Git::merge_abort_detached`]) — the git analogue of jj's `ROLLBACK_TIMEOUT`.
/// Because that cleanup deliberately runs on a FRESH cancel token (so a cancelled
/// or timed-out probe merge cannot also cancel it), it needs its own explicit
/// deadline to stay bounded rather than inheriting one from the main operation.
const MERGE_ABORT_CLEANUP_TIMEOUT: Duration = Duration::from_secs(30);

/// Point git's editor at a no-op so any command that would open `$EDITOR`
/// (a rebase reword, the message-confirm on `rebase --continue`) succeeds
/// non-interactively instead of hanging a headless caller.
fn no_editor(cmd: processkit::Command) -> processkit::Command {
    cmd.env("GIT_EDITOR", "true")
        .env("GIT_SEQUENCE_EDITOR", "true")
}

/// Force the C locale on a command whose output feeds the error classifiers
/// (`is_merge_conflict`, `is_nothing_to_commit`, `is_transient_fetch_error`):
/// they match untranslated English substrings, and a localized git would emit
/// translated messages, silently turning a classified failure (conflict /
/// clean-tree / transient) into an unclassified one.
fn c_locale(cmd: processkit::Command) -> processkit::Command {
    cmd.env("LC_ALL", "C")
}

/// Injection guard for bare positional argv slots — delegates to the shared
/// [`vcs_cli_support::reject_flag_like`], naming this crate's binary so the
/// ~45 call sites stay `reject_flag_like(what, value)`.
fn reject_flag_like(what: &str, value: &str) -> Result<()> {
    vcs_cli_support::reject_flag_like(BINARY, what, value)
}

/// Validate the caller-controlled values that `clone` puts in option slots
/// before credential resolution or any runner call. `--origin` is a flag-value
/// position, but git treats another leading dash as a new option when the value
/// is missing or malformed, so keep it behind the same project guard as bare
/// positional names.
fn validate_clone_spec(spec: &CloneSpec) -> Result<()> {
    if let Some(origin) = spec.origin.as_deref() {
        reject_flag_like("origin name", origin)?;
    }
    Ok(())
}

/// Build the clone-specific argv suffix once for both clone surfaces. Keeping
/// this in one place prevents progress reporting from drifting away from the
/// ordinary clone's option order or omission rules.
fn clone_args(spec: &CloneSpec, progress: bool) -> Vec<String> {
    let mut args = vec!["clone".to_string()];
    if progress {
        args.push("--progress".to_string());
    }
    if let Some(branch) = spec.branch.as_deref() {
        args.push("--branch".to_string());
        args.push(branch.to_string());
    }
    if let Some(depth) = spec.depth {
        args.push("--depth".to_string());
        args.push(depth.to_string());
    }
    if let Some(filter) = spec.filter {
        args.push(format!("--filter={}", filter.cli_value()));
    }
    if spec.single_branch {
        args.push("--single-branch".to_string());
    }
    if let Some(origin) = spec.origin.as_deref() {
        args.push("--origin".to_string());
        args.push(origin.to_string());
    }
    if spec.bare {
        args.push("--bare".to_string());
    }
    args
}

/// [`reject_flag_like`] for a bare positional **path** argv slot (worktree
/// add/remove/move), whose values are typed `PathBuf`/`&Path` rather than
/// `&str` and so may be non-UTF-8 on Unix. Checks a lossy-UTF-8 rendering of
/// `path` — `to_string_lossy` never panics, so this never aborts on invalid
/// UTF-8 — for a leading `-` (after trim), emptiness, or an embedded NUL; a
/// leading `-`/NUL/emptiness is always ASCII and so survives the lossy
/// conversion unchanged regardless of any invalid bytes elsewhere in `path`.
/// Only the *check* is lossy: the value actually handed to `Command::arg`
/// stays the original `path`, byte-for-byte, so a legitimate non-UTF-8 path
/// with no leading `-` still reaches the child process unaltered.
fn reject_flag_like_path(what: &str, path: &Path) -> Result<()> {
    reject_flag_like(what, &path.to_string_lossy())
}

/// Parse `git sparse-checkout list` without trimming pattern content. Git emits
/// one directory/pattern per line; `split_terminator` drops only the final
/// framing newline, while the explicit CR removal keeps Windows output stable.
fn parse_sparse_checkout_list(output: &str) -> Vec<String> {
    output
        .split_terminator('\n')
        .map(|line| line.strip_suffix('\r').unwrap_or(line).to_string())
        .collect()
}

/// Emptiness guard for a caller-supplied file path that is **interpolated into a
/// larger argument** (`show_file`'s `<rev>:<path>` spec) instead of occupying an
/// argv slot of its own.
///
/// [`reject_flag_like`] is the wrong check for such a slot in both directions: a
/// leading `-` is inert inside `<rev>:<path>` (rejecting it would refuse a
/// perfectly legitimate `-dash.txt`), while emptiness — which `reject_flag_like`
/// happens to cover for *bare* positionals — is exactly what silently changes the
/// command's meaning here. `git show <rev>:` is not an error: git prints the
/// **root tree listing** and exits 0 (verified on git 2.55.0), so an unguarded
/// empty path returns a directory index as if it were the file's content.
///
/// `vcs_jj`'s `file_show` carries the mirror guard with a byte-identical message
/// (only the program name differs), so a cross-backend caller sees ONE error
/// form. Its empty-path degradation differs in shape but not in kind: an empty
/// path becomes the fileset `root-file:""`, which is a valid *existing* path
/// (the workspace root) matching no file, so `jj file show` exits 0 with **empty
/// output** — a file that "exists and is empty" (verified on jj 0.38.0).
///
/// Whitespace-only is refused with the empty string. A name made only of spaces
/// is legal on Unix, but at this boundary it is indistinguishable from the far
/// likelier caller bug (a blank/unset path variable), and refusing it keeps one
/// rule — and one error — across both backends.
///
/// An interior NUL needs no check here: it can only reach `Command::arg`, which
/// already fails the spawn with the same `io::ErrorKind::InvalidInput` this guard
/// raises, so the classification a caller sees is unchanged.
fn reject_empty_path(what: &str, path: &str) -> Result<()> {
    if path.trim().is_empty() {
        return Err(Error::spawn(
            BINARY,
            std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                format!(
                    "{what} {path:?} is empty or whitespace-only — an empty path silently \
                     re-targets the read at the repository root instead of a single file; \
                     refusing before spawning"
                ),
            ),
        ));
    }
    Ok(())
}

// --- Large path-set transport (T-052) ----------------------------------------
//
// `add`/`commit_paths` build one `git` argv per call whether their path set has
// three entries or three hundred thousand. Windows' `CreateProcess` rejects a
// command line longer than roughly 32,767 UTF-16 code units (`OS error 206`);
// POSIX's `ARG_MAX` is typically far larger but shared with the environment
// block. [`ARGV_PATHSPEC_BUDGET`] is a conservative byte budget for the *paths*
// portion of such a call (not counting the program name, subcommand, or
// flags — negligible next to this), chosen with a wide margin under the
// tighter Windows ceiling so an ordinary call (a handful of paths) never
// crosses it. Crossing it switches `add`/`commit_paths` to the NUL-safe
// `--pathspec-from-file=- --pathspec-file-nul` transport ([`pathspec_nul_bytes`])
// — unbounded, since the paths then never touch argv at all — and switches
// `log_paths` (for which git has no `--pathspec-from-file` support) to chunked
// invocations ([`chunk_pathspecs`]) merged back into one result.

/// Conservative byte budget for the *pathspec* portion of a `git` argv — see
/// the module-level comment above this constant for the reasoning.
const ARGV_PATHSPEC_BUDGET: usize = 6_000;

/// Sum of each path's encoded byte length plus one (a stand-in for the
/// separating argv-slot overhead), compared against [`ARGV_PATHSPEC_BUDGET`]
/// to decide whether a path set is too large for one plain-argv invocation.
fn pathspec_argv_len<'a>(paths: impl IntoIterator<Item = &'a std::ffi::OsStr>) -> usize {
    paths
        .into_iter()
        .map(|p| p.as_encoded_bytes().len() + 1)
        .sum()
}

/// Build the NUL-delimited pathspec payload for `--pathspec-from-file=-
/// --pathspec-file-nul` from `paths`, entirely in memory before anything is
/// spawned. A path embedding a NUL byte — impossible on a real filesystem, but
/// checked anyway as defense-in-depth — would silently split into two
/// pathspecs on that separator, one of them possibly matching an unintended
/// file; refusing it here, before the command is built, keeps input
/// preparation atomic: either every path is valid and the one `git` invocation
/// runs, or none of it does (no partially-applied result to unwind). Returns
/// the raw bytes (rather than a [`processkit::Stdin`] directly) so this pure
/// step stays unit-testable — wrap the result in
/// [`processkit::Stdin::from_bytes`] at the call site.
fn pathspec_nul_bytes<'a>(paths: impl IntoIterator<Item = &'a std::ffi::OsStr>) -> Result<Vec<u8>> {
    let mut buf = Vec::new();
    for path in paths {
        let bytes = path.as_encoded_bytes();
        if bytes.contains(&0) {
            return Err(Error::spawn(
                BINARY,
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "path contains an embedded NUL byte, which the \
                     --pathspec-file-nul transport uses as its separator — \
                     refusing before spawning rather than silently splitting \
                     it into two pathspecs",
                ),
            ));
        }
        buf.extend_from_slice(bytes);
        buf.push(0);
    }
    Ok(buf)
}

/// Split `paths` into groups whose combined length (each entry's byte length
/// plus one, matching [`pathspec_argv_len`]) stays within
/// [`ARGV_PATHSPEC_BUDGET`] — every group gets at least one path (a single path
/// already over budget still gets its own singleton group; nothing shorter is
/// possible). Preserves `paths`' order, both within and across groups.
fn chunk_pathspecs(paths: &[String]) -> Vec<Vec<&str>> {
    let mut chunks: Vec<Vec<&str>> = Vec::new();
    let mut current: Vec<&str> = Vec::new();
    let mut current_len = 0usize;
    for path in paths {
        let len = path.len() + 1;
        if !current.is_empty() && current_len + len > ARGV_PATHSPEC_BUDGET {
            chunks.push(std::mem::take(&mut current));
            current_len = 0;
        }
        current.push(path.as_str());
        current_len += len;
    }
    if !current.is_empty() {
        chunks.push(current);
    }
    chunks
}

/// Parse [`Git::log_paths_order_command`]'s `git log -z --format=%H` output
/// into an ordered list of hashes — git's own commit order for the queried
/// revspec, used as the ranking oracle that restores order across
/// `log_paths`'s merged chunk results (T-052/R-03; see [`GitApi::log_paths`]).
fn parse_commit_order(output: &str) -> Vec<String> {
    output
        .split('\0')
        .filter(|rec| !rec.is_empty())
        .map(str::to_string)
        .collect()
}

// The six raw escape-hatch helpers (`run_args`/`run_raw_args`/`run_in`/… and the
// `*_in` twins) are byte-identical forwards into `core` across all five CLI
// wrappers, so the shared macro in `vcs-cli-support` generates them (see
// `vcs_cli_support::raw_run_forwarders!`).
vcs_cli_support::raw_run_forwarders! {
    Git, "git", "\"status\", \"-s\"", "",
    "the same unguarded escape hatch — only the working directory is bound, \
     no `-C`/extra flag is injected"
}

impl<R: ProcessRunner> Git<R> {
    /// The empty-tree object id for the repository at `dir`, matching its **active
    /// object format** — the format-correct stand-in for `HEAD` when diffing/stat-ing
    /// the working tree of an unborn (no-commits-yet) repository.
    ///
    /// Computed with `git hash-object -t tree --stdin` fed an empty stdin: an empty
    /// tree object is empty content, so git returns its id under whichever hash the
    /// repo uses (`4b825dc…` for SHA-1, a 64-hex digest for `extensions.objectFormat=
    /// sha256`). This asks git rather than hard-coding [`EMPTY_TREE_SHA1`], which is
    /// wrong in a SHA-256 repo. `--stdin` (not `-w`) only *computes* the id — nothing
    /// is written to the object database.
    pub async fn empty_tree_oid(&self, dir: &Path) -> Result<String> {
        self.core
            .run(
                self.core
                    .command_in(dir, ["hash-object", "-t", "tree", "--stdin"])
                    .stdin(processkit::Stdin::empty()),
            )
            .await
    }

    /// Bind this client to `dir`, returning a [`GitAt`] handle whose methods omit
    /// the `dir` argument: `git.at(dir).status()` runs [`status`](GitApi::status)
    /// against `dir`. The dir-taking [`GitApi`] methods stay on [`Git`] for
    /// driving many directories (e.g. linked worktrees) from one client.
    pub fn at<'a>(&'a self, dir: &'a Path) -> GitAt<'a, R> {
        GitAt { git: self, dir }
    }

    /// Harden this client for driving repositories it didn't create: running
    /// `git` inside an untrusted checkout executes that repository's hooks and
    /// honours its config — arbitrary code execution by default. The profile
    /// (applied to **every** command this client runs):
    ///
    /// **⚠ Requires git ≥ 2.31.** The hook / `fsmonitor` / `sshCommand` pins ride
    /// git's env-based config (`GIT_CONFIG_COUNT`), which older git **silently
    /// ignores** — so on git < 2.31 `harden()` still scrubs the environment and
    /// turns prompts off, but repo-local hooks/fsmonitor/sshCommand are **not**
    /// disabled (no error is raised). [`capabilities().ensure_supported()`](GitCapabilities::ensure_supported)
    /// now enforces the **≥ 2.31 floor** (major.minor), so a too-old git is rejected
    /// up front with a clear message instead of silently no-op-ing the pins — call it
    /// before relying on `harden()` against a fully untrusted repo on a host you don't
    /// control, or add an OS-level sandbox. (`docs/audit-2026-07.md` H3, M29.)
    ///
    /// - **Disables hooks** — `core.hooksPath=/dev/null` pinned via git's
    ///   env-based config (`GIT_CONFIG_COUNT`/`KEY_n`/`VALUE_n`, git ≥ 2.31;
    ///   verified to suppress hooks on Windows too) — and `core.fsmonitor`
    ///   (a config-driven daemon launch). Env-config overrides even the
    ///   *repo-local* `.git/config` for the keys it names, so these pins beat a
    ///   poisoned `.git/config`.
    /// - **Neutralizes `core.sshCommand`** (pinned empty) — the config-key twin of
    ///   the scrubbed `GIT_SSH_COMMAND`, an arbitrary program git would run for the
    ///   SSH transport. Empty is falsy to git, so the default `ssh` (ambient
    ///   `~/.ssh/config`/agent) still works; only the repo's override is dropped.
    /// - **Removes inherited repo redirectors** so a poisoned parent
    ///   environment can't point commands at another repository: `GIT_DIR`,
    ///   `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_COMMON_DIR`,
    ///   `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES`,
    ///   `GIT_NAMESPACE`, `GIT_CEILING_DIRECTORIES`, `GIT_CONFIG_PARAMETERS`,
    ///   `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_SYSTEM`. (The first seven are also
    ///   scrubbed by *every* client — see the type-level doc — not just here.)
    /// - **Removes inherited command hooks** that make git spawn an arbitrary
    ///   program from the *environment* (a second code-execution path besides
    ///   repo hooks): `GIT_SSH_COMMAND`/`GIT_SSH` (transport), `GIT_ASKPASS`
    ///   (credential prompt), `GIT_EXTERNAL_DIFF` (diff driver), `GIT_PAGER`,
    ///   `GIT_EDITOR`/`GIT_SEQUENCE_EDITOR`, `GIT_PROXY_COMMAND` (a program for a
    ///   `git://` connection), `GIT_EXEC_PATH` (relocates git's own sub-commands),
    ///   and `GIT_TEMPLATE_DIR` (seeds hooks/config on `init`/`clone`). It also drops
    ///   the pathspec-mode vars (`GIT_LITERAL_PATHSPECS` / `GIT_GLOB_PATHSPECS` /
    ///   `GIT_NOGLOB_PATHSPECS` / `GIT_ICASE_PATHSPECS`), which silently change which
    ///   paths a command matches. The library's own auth seam
    ///   ([`with_credentials`](Git::with_credentials)) injects credentials via a
    ///   git `credential.helper` / token env, **not** these variables, so it keeps
    ///   working through a hardened client; an operator who deliberately relies on
    ///   an ambient `GIT_SSH_COMMAND`/`GIT_ASKPASS` should inject it per-call
    ///   instead of inheriting it into an untrusted-repo run.
    /// - **Skips system config** (`GIT_CONFIG_NOSYSTEM=1`) and keeps terminal
    ///   prompts off everywhere (`GIT_TERMINAL_PROMPT=0`).
    ///
    /// **Residual repo-local-config vectors (NOT neutralized).** `harden()` closes
    /// the *hooks*, `fsmonitor`, `core.sshCommand`, and the env redirector/command-
    /// hook paths — but a few **repo-local `.git/config` / `.gitattributes`** keys
    /// still run an arbitrary program and are not pinned: `filter.<drv>.clean`/
    /// `smudge` (run on any working-tree materialization — `checkout`, `stash pop`,
    /// `worktree add`), and `diff.<drv>.textconv` / `diff.external` (run when a diff
    /// is produced; [`diff_text`](GitApi::diff_text) defends itself with
    /// `--no-ext-diff`, but other diff/blame reads do not). So for a **fully
    /// untrusted** repo, do not materialize its working tree or run diffs through a
    /// hardened client without an OS-level sandbox — `harden()` is hardening, not a
    /// sandbox.
    ///
    /// What it does NOT do beyond that: sandbox the git binary itself, or stop the
    /// repo's *content* from being malicious. In a **colocated jj repo**, git hooks
    /// only run when *git* commands run — harden the `Git` client; `Jj` needs
    /// no equivalent (jj has no repo-local hooks; see the vcs-jj docs).
    ///
    /// Chainable — `Git::with_runner(rec).harden()` works in tests; use
    /// [`Git::hardened()`](Git::hardened) for the common case.
    pub fn harden(self) -> Self {
        let removed = [
            // Repo redirectors — point git at another repo/index/object store.
            // (`GIT_DIR`…`GIT_NAMESPACE` are also scrubbed by *every* client via the
            // `managed_client!` `scrub_env`; re-listed here so the hardened profile is
            // self-contained and its double-removal is harmless.)
            "GIT_DIR",
            "GIT_WORK_TREE",
            "GIT_INDEX_FILE",
            "GIT_COMMON_DIR",
            "GIT_OBJECT_DIRECTORY",
            "GIT_ALTERNATE_OBJECT_DIRECTORIES",
            "GIT_NAMESPACE",
            "GIT_CEILING_DIRECTORIES",
            "GIT_CONFIG_PARAMETERS",
            "GIT_CONFIG_GLOBAL",
            "GIT_CONFIG_SYSTEM",
            // Command hooks — make git spawn an arbitrary program from the env.
            "GIT_SSH_COMMAND",
            "GIT_SSH",
            "GIT_ASKPASS",
            "GIT_EXTERNAL_DIFF",
            "GIT_PAGER",
            "GIT_EDITOR",
            "GIT_SEQUENCE_EDITOR",
            // More env command-hooks (M14): `GIT_PROXY_COMMAND` runs an arbitrary
            // program for a `git://` connection; `GIT_EXEC_PATH` relocates where git
            // finds its own sub-commands (so `git-<x>` becomes attacker-chosen);
            // `GIT_TEMPLATE_DIR` seeds hooks/config into a repo on `init`/`clone`.
            "GIT_PROXY_COMMAND",
            "GIT_EXEC_PATH",
            "GIT_TEMPLATE_DIR",
            // Pathspec interpretation (M14) — not code-execution, but they silently
            // change which paths a command matches, so pin deterministic behavior.
            "GIT_LITERAL_PATHSPECS",
            "GIT_GLOB_PATHSPECS",
            "GIT_NOGLOB_PATHSPECS",
            "GIT_ICASE_PATHSPECS",
        ];
        let mut hardened = self;
        for key in removed {
            hardened = hardened.default_env_remove(key);
        }
        hardened
            .default_env("GIT_CONFIG_NOSYSTEM", "1")
            .default_env("GIT_TERMINAL_PROMPT", "0")
            // Env-config (`GIT_CONFIG_COUNT`/`KEY_n`/`VALUE_n`) overrides even the
            // *repo-local* `.git/config` for the keys it names — so these pins beat
            // a poisoned `.git/config`, which `GIT_CONFIG_NOSYSTEM` (system) and the
            // scrubbed `GIT_CONFIG_GLOBAL` (global) do not reach.
            .default_env("GIT_CONFIG_COUNT", "3")
            .default_env("GIT_CONFIG_KEY_0", "core.hooksPath")
            // `/dev/null` as the hooks dir disables hooks on every platform,
            // Windows included: git looks for `<hooksPath>/<hook-name>`, and no
            // such file can exist under `/dev/null` (it is not a directory), so the
            // lookup always misses and no hook runs. A literal POSIX path is fine
            // on Windows here — it is used as a path *prefix* to probe, never
            // opened — and it reads unambiguously as "nowhere."
            .default_env("GIT_CONFIG_VALUE_0", "/dev/null")
            .default_env("GIT_CONFIG_KEY_1", "core.fsmonitor")
            .default_env("GIT_CONFIG_VALUE_1", "false")
            // Neutralize a repo-local `core.sshCommand` (an arbitrary program git
            // runs for the SSH transport on fetch/push/clone) — the config-key twin
            // of the scrubbed `GIT_SSH_COMMAND` env var. An empty value is falsy to
            // git, so it falls back to the default `ssh` (ambient `~/.ssh/config` /
            // agent still work); only the repo's override is dropped.
            .default_env("GIT_CONFIG_KEY_2", "core.sshCommand")
            .default_env("GIT_CONFIG_VALUE_2", "")
    }

    /// Switch to `branch`, carrying uncommitted changes (tracked *and*
    /// untracked) across via the stash: `stash push -u` → `checkout` →
    /// `stash pop --index`. `--index` restores the staged/unstaged split faithfully
    /// (a bare `pop` returns everything unstaged). A clean tree skips the round-trip;
    /// and because `stash push` can exit 0 having saved **nothing** (e.g. a
    /// submodule-only change), the stash-list depth is checked around the push so a
    /// no-op push doesn't leave the later pop grabbing an older, unrelated stash.
    ///
    /// **Single-actor contract:** this assumes no other process pushes or pops a
    /// stash in the same repository between this call's own `stash push` and `pop`.
    ///
    /// Failure behaviour:
    /// - `checkout` fails (atomic — the working copy stays on the original
    ///   branch): the stash is popped back to restore the original state, and
    ///   the checkout error is returned. If that restoring pop *also* fails,
    ///   the changes stay safe in the stash (`git stash list`).
    /// - `stash pop` on the target branch conflicts: the error is returned with
    ///   the target branch checked out; git keeps the stash entry, so the
    ///   changes can be resolved or re-applied manually.
    ///
    /// Inherent (not on the object-safe trait): a composed operation, not a 1:1
    /// CLI verb — mock the underlying `status`/`stash_*`/`checkout` instead.
    pub async fn switch_with_stash(&self, dir: &Path, target: &CheckoutTarget) -> Result<()> {
        // Untracked-inclusive guard to match `stash push -u`: "dirty" must mean
        // the same thing to the guard and to the stash. Fast path for a clean tree.
        if self.status(dir).await?.is_empty() {
            return self.checkout(dir, target).await;
        }
        // `stash push` exits 0 having saved **nothing** when the only dirt is
        // unstashable (e.g. a submodule-only change that `status` still reports), so a
        // bare `stash pop` afterwards would splat an UNRELATED pre-existing stash — data
        // loss. Bracket the push with the stash-list depth to learn whether it actually
        // saved, and only pop when it did. (Single-actor contract: a concurrent
        // `stash push`/`pop` by another process between our two calls is out of scope.)
        let depth_before = self.stash_depth(dir).await?;
        self.stash_push(dir, StashPush::new().include_untracked())
            .await?;
        if self.stash_depth(dir).await? <= depth_before {
            // Nothing was stashed — switch as-is rather than pop someone else's entry.
            return self.checkout(dir, target).await;
        }
        // `--index` restores the staged/unstaged split faithfully; a bare `pop` would
        // bring everything back UNSTAGED, silently flattening the index.
        match self.checkout(dir, target).await {
            Ok(()) => self.stash_pop_index(dir).await,
            Err(err) => {
                // A failed checkout is atomic — we are still on the original branch, so
                // popping restores the exact pre-call state. If the pop fails too, the
                // stash entry is preserved for the caller.
                let _ = self.stash_pop_index(dir).await;
                Err(err)
            }
        }
    }

    /// The number of entries in the stash list (`git stash list`) — used by
    /// [`switch_with_stash`](Git::switch_with_stash) to tell whether a `stash push`
    /// actually saved anything.
    async fn stash_depth(&self, dir: &Path) -> Result<usize> {
        let out = self
            .core
            .run(self.core.command_in(dir, ["stash", "list"]))
            .await?;
        Ok(out.lines().filter(|l| !l.is_empty()).count())
    }

    /// `git stash pop --index` — restore the top stash *preserving* the staged/unstaged
    /// split (a bare `pop` returns everything unstaged). C locale so a conflicting pop's
    /// `CONFLICT (...)` output still feeds `is_merge_conflict`.
    async fn stash_pop_index(&self, dir: &Path) -> Result<()> {
        self.core
            .run_unit(c_locale(
                self.core.command_in(dir, ["stash", "pop", "--index"]),
            ))
            .await
    }

    /// `git_dir` resolved to an absolute path — `rev-parse --git-dir` may report
    /// it relative to `dir` (e.g. `.git`), which the filesystem probes need joined.
    async fn resolved_git_dir(&self, dir: &Path) -> Result<PathBuf> {
        self.resolve_git_dir(dir, self.core.command_in(dir, ["rev-parse", "--git-dir"]))
            .await
    }

    /// [`resolved_git_dir`](Self::resolved_git_dir) on the detached
    /// rollback-cleanup context (see [`detached_cleanup`](Self::detached_cleanup)):
    /// the `rev-parse --git-dir` behind the MERGE_HEAD probe runs on a fresh,
    /// never-fired cancel token, so a client cancellation that already fired during
    /// the probe merge cannot short-circuit the *decision* half of `try_merge`'s
    /// Ok/Err cleanup. Backs [`is_merge_in_progress_detached`](Self::is_merge_in_progress_detached).
    async fn resolved_git_dir_detached(&self, dir: &Path) -> Result<PathBuf> {
        self.resolve_git_dir(
            dir,
            self.detached_cleanup(self.core.command_in(dir, ["rev-parse", "--git-dir"])),
        )
        .await
    }

    /// Run a `rev-parse --git-dir` `command` and absolutise a relative git dir
    /// against `dir`. Shared by [`resolved_git_dir`](Self::resolved_git_dir) and
    /// its detached variant so the token-inheriting and detached probes cannot
    /// drift in how they resolve the path.
    async fn resolve_git_dir(&self, dir: &Path, command: Command) -> Result<PathBuf> {
        let git_dir = PathBuf::from(self.core.run(command).await?);
        Ok(if git_dir.is_absolute() {
            git_dir
        } else {
            dir.join(git_dir)
        })
    }
}

impl Git {
    /// A hardened real (job-backed) client — `Git::new().harden()`; see
    /// [`harden`](Git::harden) for what the profile does.
    pub fn hardened() -> Self {
        Self::new().harden()
    }
}

/// A [`Git`] client with a working directory bound, so calls drop the leading
/// `dir` argument — `git.at(dir).status()` is `git.status(dir)`. Construct one
/// with [`Git::at`] (or, through the facade, `vcs_core::Repo::git_at`). Cheap to
/// copy: it only borrows the client and the path.
pub struct GitAt<'a, R: ProcessRunner = processkit::JobRunner> {
    git: &'a Git<R>,
    dir: &'a Path,
}

// Hand-written rather than derived: the view only holds two references, so it is
// `Copy` for *every* runner. `#[derive(Copy)]` would add a spurious `R: Copy`
// bound that the real default `JobRunner` doesn't satisfy, silently dropping
// `Copy` on the production `Repo::git_at()` handle.
impl<R: ProcessRunner> Clone for GitAt<'_, R> {
    fn clone(&self) -> Self {
        *self
    }
}
impl<R: ProcessRunner> Copy for GitAt<'_, R> {}

// Generate [`GitAt`] forwarders from a method list: `bare` methods forward
// verbatim, `dir` methods inject `self.dir` as the first argument. The shared
// macro lives in `vcs-cli-support` (see `vcs_cli_support::at_forwarders!`).
vcs_cli_support::at_forwarders! {
    GitAt, git, "Git",
    bare {
        fn version() -> Result<String>;
        fn capabilities() -> Result<GitCapabilities>;
        fn clone_repo(url: &str, dest: &Path, spec: CloneSpec) -> Result<()>;
    }
    dir {
        fn status() -> Result<Vec<StatusEntry>>;
        fn status_text() -> Result<String>;
        fn status_tracked() -> Result<Vec<StatusEntry>>;
        fn branch_status() -> Result<BranchStatus>;
        fn conflicted_files() -> Result<Vec<PathBuf>>;
        fn current_branch() -> Result<Option<String>>;
        fn branches() -> Result<Vec<Branch>>;
        fn log(revspec: &RevSpec, max: usize) -> Result<Vec<Commit>>;
        fn log_paths(revspec: &RevSpec, max: usize, paths: &[String]) -> Result<Vec<Commit>>;
        fn rev_parse(rev: &RevSpec) -> Result<String>;
        fn rev_parse_short(rev: &RevSpec) -> Result<String>;
        fn init() -> Result<()>;
        fn add(paths: &[PathBuf]) -> Result<()>;
        fn commit(message: &str) -> Result<()>;
        fn create_branch(name: &RefName) -> Result<()>;
        fn checkout(target: &CheckoutTarget) -> Result<()>;
        fn checkout_detach(commit: &RevSpec) -> Result<()>;
        fn commit_paths(spec: CommitPaths) -> Result<()>;
        fn last_commit_message() -> Result<String>;
        fn is_unborn() -> Result<bool>;
        fn diff_is_empty() -> Result<bool>;
        fn common_dir() -> Result<PathBuf>;
        fn git_dir() -> Result<PathBuf>;
        fn resolve_commit(rev: &RevSpec) -> Result<String>;
        fn remote_head_branch() -> Result<Option<String>>;
        fn branch_exists(name: &RefName) -> Result<bool>;
        fn remote_branch_exists(name: &RefName) -> Result<bool>;
        fn remote_url(remote: &str) -> Result<String>;
        fn remote_list() -> Result<Vec<Remote>>;
        fn upstream() -> Result<Option<String>>;
        fn remote_branches(remote: &str) -> Result<Vec<String>>;
        fn is_merged(spec: MergeCheck) -> Result<bool>;
        fn set_upstream(branch: &RefName, upstream: &RefName) -> Result<()>;
        fn delete_branch(spec: BranchDelete) -> Result<()>;
        fn rename_branch(old: &RefName, new: &RefName) -> Result<()>;
        fn rev_list_count(range: &RevSpec) -> Result<usize>;
        fn diff_range_is_empty(range: &RevSpec) -> Result<bool>;
        fn diff_stat(range: &RevSpec) -> Result<DiffStat>;
        fn diff_text(spec: DiffSpec) -> Result<String>;
        fn diff(spec: DiffSpec) -> Result<Vec<FileDiff>>;
        fn diff_text_between(from: &RevSpec, to: &RevSpec) -> Result<String>;
        fn diff_between(from: &RevSpec, to: &RevSpec) -> Result<Vec<FileDiff>>;
        fn diff_text_between_within(
            from: &RevSpec,
            to: &RevSpec,
            budget: OutputBudget,
        ) -> Result<String>;
        fn diff_between_within(
            from: &RevSpec,
            to: &RevSpec,
            budget: OutputBudget,
        ) -> Result<Vec<FileDiff>>;
        fn staged_is_empty() -> Result<bool>;
        fn is_rebase_in_progress() -> Result<bool>;
        fn is_merge_in_progress() -> Result<bool>;
        fn is_am_in_progress() -> Result<bool>;
        fn is_cherry_pick_in_progress() -> Result<bool>;
        fn is_revert_in_progress() -> Result<bool>;
        fn is_bisect_in_progress() -> Result<bool>;
        fn fetch() -> Result<()>;
        fn fetch_from(remote: &str) -> Result<()>;
        fn fetch_branch(branch: &RefName) -> Result<()>;
        fn push(spec: GitPush) -> Result<()>;
        fn merge_squash(branch: &RevSpec) -> Result<()>;
        fn merge_commit(spec: MergeCommit) -> Result<()>;
        fn merge_no_commit(spec: MergeNoCommit) -> Result<()>;
        fn merge_abort() -> Result<()>;
        fn merge_continue() -> Result<()>;
        fn reset_merge() -> Result<()>;
        fn reset_hard(rev: &RevSpec) -> Result<()>;
        fn rebase(onto: &RevSpec) -> Result<()>;
        fn rebase_abort() -> Result<()>;
        fn am_abort() -> Result<()>;
        fn am_continue() -> Result<()>;
        fn rebase_continue() -> Result<()>;
        fn stash_push(spec: StashPush) -> Result<()>;
        fn stash_pop() -> Result<()>;
        fn stash_list() -> Result<Vec<StashEntry>>;
        fn stash_apply(index: usize) -> Result<()>;
        fn stash_drop(index: usize) -> Result<()>;
        fn clean(spec: Clean) -> Result<Vec<CleanEntry>>;
        fn switch_with_stash(target: &CheckoutTarget) -> Result<()>;
        fn worktree_list() -> Result<Vec<Worktree>>;
        fn worktree_add(spec: WorktreeAdd) -> Result<()>;
        fn worktree_remove(spec: WorktreeRemove) -> Result<()>;
        fn worktree_move(from: &Path, to: &Path) -> Result<()>;
        fn worktree_prune() -> Result<()>;
        fn sparse_checkout_set(spec: SparseCheckoutSet) -> Result<()>;
        fn sparse_checkout_list() -> Result<Vec<String>>;
        fn sparse_checkout_disable() -> Result<()>;
        fn submodule_list() -> Result<Vec<Submodule>>;
        fn submodule_status() -> Result<Vec<SubmoduleStatus>>;
        fn submodule_update(spec: SubmoduleUpdate) -> Result<()>;
        fn tag_create(name: &RefName, rev: Option<RevSpec>) -> Result<()>;
        fn tag_create_annotated(spec: AnnotatedTag) -> Result<()>;
        fn tag_list() -> Result<Vec<String>>;
        fn tag_delete(name: &RefName) -> Result<()>;
        fn show_file(rev: &RevSpec, path: &str) -> Result<String>;
        fn config_get(key: &str) -> Result<Option<String>>;
        fn config_set(key: &str, value: &str) -> Result<()>;
        fn remote_add(name: &str, url: &str) -> Result<()>;
        fn remote_set_url(name: &str, url: &str) -> Result<()>;
        fn blame(path: &str, rev: Option<RevSpec>) -> Result<Vec<BlameLine>>;
        fn cherry_pick(rev: &RevSpec) -> Result<()>;
        fn revert(rev: &RevSpec) -> Result<()>;
        fn rebase_skip() -> Result<()>;
        fn cherry_pick_abort() -> Result<()>;
        fn cherry_pick_continue() -> Result<()>;
        fn revert_abort() -> Result<()>;
        fn revert_continue() -> Result<()>;
        fn bisect_reset() -> Result<()>;
        fn bisect_start(bad: &RevSpec, good: &RevSpec) -> Result<BisectStep>;
        fn bisect_good() -> Result<BisectStep>;
        fn bisect_bad() -> Result<BisectStep>;
        fn bisect_skip() -> Result<BisectStep>;
    }
    // Raw escape hatches: bound to `self.dir` (forward to the client's `*_in`
    // twins) so `git.at(dir).run(…)` runs in the bound repo, not the process cwd.
    // For the process-cwd hatch call `run`/`run_raw`/… on `Git` directly.
    raw {
        fn run(args: &[String]) -> Result<String> => run_in;
        fn run_raw(args: &[String]) -> Result<ProcessResult<String>> => run_raw_in;
        fn run_args(args: &[&str]) -> Result<String> => run_args_in;
        fn run_raw_args(args: &[&str]) -> Result<ProcessResult<String>> => run_raw_args_in;
    }
}

/// Synchronous, best-effort helpers for contexts that cannot `.await`.
pub mod blocking;

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

    /// The [`ErrorReason`] behind a failed result. Since processkit 3.0 `Error` is
    /// an opaque wrapper, so the variant assertions below reach the reason through
    /// it instead of matching the error directly.
    fn err_reason<T>(out: &Result<T>) -> Option<&ErrorReason> {
        out.as_ref().err().map(Error::reason)
    }

    // Terse constructors for the validated newtypes in test call sites; the
    // literals here are always valid, so `unwrap` is fine in tests.
    fn rn(s: &str) -> RefName {
        RefName::new(s).unwrap()
    }
    fn rv(s: &str) -> RevSpec {
        RevSpec::new(s).unwrap()
    }
    fn ct(s: &str) -> CheckoutTarget {
        if s == "-" {
            CheckoutTarget::Previous
        } else {
            CheckoutTarget::Ref(rv(s))
        }
    }
    use processkit::testing::{RecordingRunner, Reply, ScriptedRunner};

    #[test]
    fn binary_name_is_git() {
        assert_eq!(BINARY, "git");
    }

    // Compile-time guard: the bound view must stay `Copy` for the *default*
    // `JobRunner` (the production `Repo::git_at()` handle), not just for the
    // `&RecordingRunner` the other tests use. A derived `Copy` would regress this.
    #[allow(dead_code)]
    fn bound_view_is_copy_for_default_runner() {
        fn assert_copy<T: Copy>() {}
        assert_copy::<GitAt<'static, processkit::JobRunner>>();
    }

    // The bound view (`git.at(dir)`) must produce byte-identical argv to the
    // dir-taking call (`git.method(dir, …)`) — the forwarder injects `self.dir`
    // in the right place and nothing else changes.
    #[tokio::test]
    async fn bound_view_matches_dir_taking_calls() {
        let dir = Path::new("/repo");
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);

        // A method with trailing args (dir injected first).
        git.merge_commit(dir, MergeCommit::branch(rv("feat")).no_ff())
            .await
            .unwrap();
        git.at(dir)
            .merge_commit(MergeCommit::branch(rv("feat")).no_ff())
            .await
            .unwrap();
        // A method taking a path arg after dir.
        git.worktree_remove(dir, WorktreeRemove::new("/wt").force())
            .await
            .unwrap();
        git.at(dir)
            .worktree_remove(WorktreeRemove::new("/wt").force())
            .await
            .unwrap();
        // One of the new query methods.
        git.conflicted_files(dir).await.unwrap();
        git.at(dir).conflicted_files().await.unwrap();
        // One of the §4 additions.
        git.tag_delete(dir, &rn("v1")).await.unwrap();
        git.at(dir).tag_delete(&rn("v1")).await.unwrap();

        let calls = rec.calls();
        assert_eq!(calls[0].args_str(), calls[1].args_str());
        assert_eq!(calls[2].args_str(), calls[3].args_str());
        assert_eq!(calls[4].args_str(), calls[5].args_str());
        assert_eq!(calls[6].args_str(), calls[7].args_str());
        // The bound calls also carried the bound dir as their working directory.
        assert_eq!(calls[1].cwd.as_deref(), Some(dir));
        assert_eq!(calls[3].cwd.as_deref(), Some(dir));
    }

    // T-035: the raw escape hatches reached *through* the bound view
    // (`git.at(dir).run…`) now run in the bound `dir`, while the same-named methods
    // on the client stay in the process cwd. Guards that a bound handle's raw call
    // can no longer silently target another repo, and that the explicit process-cwd
    // hatch is preserved.
    #[tokio::test]
    async fn bound_view_raw_hatch_runs_in_bound_dir() {
        let dir = Path::new("/repo");
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);

        // Through the bound view: every raw form carries the bound dir as its cwd.
        git.at(dir).run(&["status".to_string()]).await.unwrap();
        let _ = git.at(dir).run_raw(&["status".to_string()]).await.unwrap();
        git.at(dir).run_args(&["status"]).await.unwrap();
        let _ = git.at(dir).run_raw_args(&["status"]).await.unwrap();
        // On the client directly: the process-cwd escape hatch (no bound dir).
        git.run(&["status".to_string()]).await.unwrap();
        let _ = git.run_raw(&["status".to_string()]).await.unwrap();
        git.run_args(&["status"]).await.unwrap();
        let _ = git.run_raw_args(&["status"]).await.unwrap();

        let calls = rec.calls();
        for c in &calls[0..4] {
            assert_eq!(
                c.cwd.as_deref(),
                Some(dir),
                "raw call through the bound view runs in the bound dir"
            );
            assert_eq!(c.args_str(), ["status"]);
        }
        for c in &calls[4..8] {
            assert_eq!(
                c.cwd.as_deref(),
                None,
                "raw call on the client stays in the process cwd"
            );
            assert_eq!(c.args_str(), ["status"]);
        }
    }

    // Hermetic: the real status() command-building + porcelain parsing run
    // against a scripted runner — no `git` binary needed, so this runs on CI.
    #[tokio::test]
    async fn status_parses_scripted_output() {
        // `-z` output: NUL-delimited records, raw paths.
        let git = Git::with_runner(
            ScriptedRunner::new().on(["git", "status"], Reply::ok(" M a.rs\0?? b.rs\0")),
        );
        let entries = git.status(Path::new(".")).await.expect("status");
        assert_eq!(entries.len(), 2);
        assert_eq!(entries[0].code, " M");
        assert_eq!(entries[1].path, Path::new("b.rs"));
    }

    // `status_tracked` is `status` minus untracked files — same parser, extra flag.
    #[tokio::test]
    async fn status_tracked_excludes_untracked_flag() {
        let rec = RecordingRunner::replying(Reply::ok(" M a.rs\0"));
        let git = Git::with_runner(&rec);
        let entries = git.status_tracked(Path::new(".")).await.expect("status");
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].code, " M");
        assert_eq!(
            rec.only_call().args_str(),
            ["status", "--porcelain=v1", "-z", "--untracked-files=no"]
        );
    }

    // `branch_status` builds the porcelain v2 + branch + -z argv and parses the
    // combined header/entry output in one call.
    #[tokio::test]
    async fn branch_status_builds_v2_branch_args_and_parses() {
        let out = concat!(
            "# branch.oid abc\0",
            "# branch.head main\0",
            "# branch.upstream origin/main\0",
            "# branch.ab +1 -0\0",
            "1 .M N... 100644 100644 100644 1 2 a.rs\0",
            "? new.txt\0",
        );
        let rec = RecordingRunner::replying(Reply::ok(out));
        let git = Git::with_runner(&rec);
        let s = git
            .branch_status(Path::new("."))
            .await
            .expect("branch_status");
        assert_eq!(
            rec.only_call().args_str(),
            ["status", "--porcelain=v2", "--branch", "-z"]
        );
        // The poll primitive must not itself write the index (and re-trigger a
        // filesystem watcher re-querying through it).
        assert!(rec.only_call().envs.iter().any(|(k, v)| {
            k.to_str() == Some("GIT_OPTIONAL_LOCKS")
                && v.as_deref().and_then(|o| o.to_str()) == Some("0")
        }));
        assert_eq!(s.branch.as_deref(), Some("main"));
        assert_eq!(s.upstream.as_deref(), Some("origin/main"));
        assert_eq!((s.ahead, s.behind), (Some(1), Some(0)));
        assert_eq!(s.tracked_changes, 1);
        assert_eq!(s.untracked, 1);
        assert!(s.is_dirty());
    }

    // `conflicted_files` lists unmerged paths NUL-delimited (no quoting).
    #[tokio::test]
    async fn conflicted_files_builds_args_and_parses_nul_list() {
        let rec = RecordingRunner::replying(Reply::ok("a.rs\0sub/spaced name.rs\0"));
        let git = Git::with_runner(&rec);
        let paths = git
            .conflicted_files(Path::new("."))
            .await
            .expect("conflicted_files");
        assert_eq!(
            paths,
            [PathBuf::from("a.rs"), PathBuf::from("sub/spaced name.rs")]
        );
        assert_eq!(
            rec.only_call().args_str(),
            ["diff", "--name-only", "--diff-filter=U", "-z"]
        );
    }

    #[tokio::test]
    async fn rev_parse_short_builds_short_flag() {
        let rec = RecordingRunner::replying(Reply::ok("a1b2c3d\n"));
        let git = Git::with_runner(&rec);
        let out = git
            .rev_parse_short(Path::new("/r"), &rv("HEAD"))
            .await
            .unwrap();
        assert_eq!(out, "a1b2c3d");
        assert_eq!(
            rec.only_call().args_str(),
            ["rev-parse", "--verify", "--short", "HEAD"]
        );
    }

    // M13: `rev_parse` passes `--verify` so a non-revision (a filename) errors
    // instead of being echoed back as a fake object id.
    #[tokio::test]
    async fn rev_parse_verifies_the_revision() {
        let rec = RecordingRunner::replying(Reply::ok("deadbeef\n"));
        let git = Git::with_runner(&rec);
        let out = git.rev_parse(Path::new("/r"), &rv("HEAD")).await.unwrap();
        assert_eq!(out, "deadbeef");
        assert_eq!(
            rec.only_call().args_str(),
            ["rev-parse", "--verify", "HEAD"]
        );
    }

    // M20: `git am` and an apply-backend rebase share the `rebase-apply/` dir, but am
    // marks it with an `applying` file. `is_am_in_progress` must fire only for the am,
    // and `is_rebase_in_progress` must NOT (so an am isn't aborted with `rebase --abort`).
    #[tokio::test]
    async fn distinguishes_git_am_from_an_apply_backend_rebase() {
        use vcs_testkit::TempDir;
        let gd = TempDir::new("m20-am");
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "rev-parse", "--git-dir"],
            Reply::ok(gd.path().to_str().unwrap()),
        ));
        let apply = gd.path().join("rebase-apply");
        std::fs::create_dir_all(&apply).unwrap();

        // With the `applying` marker → a `git am`.
        std::fs::write(apply.join("applying"), b"").unwrap();
        assert!(
            git.is_am_in_progress(Path::new("/r")).await.unwrap(),
            "am detected"
        );
        assert!(
            !git.is_rebase_in_progress(Path::new("/r")).await.unwrap(),
            "a git am is NOT reported as a rebase"
        );

        // Without it → an apply-backend rebase.
        std::fs::remove_file(apply.join("applying")).unwrap();
        assert!(!git.is_am_in_progress(Path::new("/r")).await.unwrap());
        assert!(
            git.is_rebase_in_progress(Path::new("/r")).await.unwrap(),
            "a bare rebase-apply dir is a rebase"
        );
    }

    // T-044: the sequencer states each key off their own git-dir marker, and a
    // cherry-pick/revert conflict does NOT write `MERGE_HEAD` — so none of them is
    // mistaken for a merge (which would dispatch `merge --abort` on a real repo).
    #[tokio::test]
    async fn detects_cherry_pick_revert_and_bisect_markers() {
        use vcs_testkit::TempDir;
        let gd = TempDir::new("t044-seq");
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "rev-parse", "--git-dir"],
            Reply::ok(gd.path().to_str().unwrap()),
        ));
        let d = Path::new("/r");
        let touch = |name: &str| std::fs::write(gd.path().join(name), b"x\n").unwrap();
        let rm = |name: &str| std::fs::remove_file(gd.path().join(name)).unwrap();

        // A cherry-pick: CHERRY_PICK_HEAD present, and crucially NOT read as a merge.
        touch("CHERRY_PICK_HEAD");
        assert!(git.is_cherry_pick_in_progress(d).await.unwrap());
        assert!(!git.is_merge_in_progress(d).await.unwrap());
        assert!(!git.is_revert_in_progress(d).await.unwrap());
        assert!(!git.is_bisect_in_progress(d).await.unwrap());
        rm("CHERRY_PICK_HEAD");

        // A revert.
        touch("REVERT_HEAD");
        assert!(git.is_revert_in_progress(d).await.unwrap());
        assert!(!git.is_cherry_pick_in_progress(d).await.unwrap());
        assert!(!git.is_merge_in_progress(d).await.unwrap());
        rm("REVERT_HEAD");

        // A bisect (keyed off BISECT_LOG).
        touch("BISECT_LOG");
        assert!(git.is_bisect_in_progress(d).await.unwrap());
        assert!(!git.is_cherry_pick_in_progress(d).await.unwrap());
        assert!(!git.is_revert_in_progress(d).await.unwrap());
        rm("BISECT_LOG");

        // Clean git dir → none fire.
        assert!(!git.is_cherry_pick_in_progress(d).await.unwrap());
        assert!(!git.is_revert_in_progress(d).await.unwrap());
        assert!(!git.is_bisect_in_progress(d).await.unwrap());
    }

    #[tokio::test]
    async fn bisect_operations_parse_steps_and_build_safe_argv() {
        const GOOD: &str = "1111111111111111111111111111111111111111";
        const BAD: &str = "2222222222222222222222222222222222222222";
        const CANDIDATE_ONE: &str = "3333333333333333333333333333333333333333";
        const CANDIDATE_TWO: &str = "4444444444444444444444444444444444444444";
        const CANDIDATE_THREE: &str = "5555555555555555555555555555555555555555";
        const FIRST_BAD: &str = "6666666666666666666666666666666666666666";
        let dir = Path::new("/r");
        let rec = RecordingRunner::new(
            ScriptedRunner::new()
                .on(
                    ["git", "bisect", "start", BAD, GOOD],
                    Reply::ok(format!(
                        "Bisecting: 1 revision left\n[{CANDIDATE_ONE}] c1\n"
                    )),
                )
                .on(
                    ["git", "bisect", "good"],
                    Reply::ok(format!(
                        "Bisecting: 0 revisions left\n[{CANDIDATE_TWO}] c2\n"
                    )),
                )
                .on(
                    ["git", "bisect", "skip"],
                    Reply::ok(format!(
                        "Bisecting: 0 revisions left\n[{CANDIDATE_THREE}] c3\n"
                    )),
                )
                .on(
                    ["git", "bisect", "bad"],
                    Reply::ok(format!(
                        "{FIRST_BAD} is the first 'bad' commit\ncommit {FIRST_BAD}\n"
                    )),
                ),
        );
        let git = Git::with_runner(&rec);

        let start = git.bisect_start(dir, &rv(BAD), &rv(GOOD)).await.unwrap();
        assert_eq!(
            start,
            BisectStep::NextCandidate {
                revision: rv(CANDIDATE_ONE)
            }
        );

        let good = git.at(dir).bisect_good().await.unwrap();
        assert_eq!(good.revision().as_str(), CANDIDATE_TWO);
        assert!(!good.is_first_bad());

        let skip = git.bisect_skip(dir).await.unwrap();
        assert_eq!(skip.revision().as_str(), CANDIDATE_THREE);
        assert!(!skip.is_first_bad());

        let bad = git.bisect_bad(dir).await.unwrap();
        assert_eq!(bad.revision().as_str(), FIRST_BAD);
        assert!(bad.is_first_bad());

        let calls = rec.calls();
        assert_eq!(calls.len(), 4);
        assert_eq!(calls[0].args_str(), ["bisect", "start", BAD, GOOD]);
        assert_eq!(calls[1].args_str(), ["bisect", "good"]);
        assert_eq!(calls[2].args_str(), ["bisect", "skip"]);
        assert_eq!(calls[3].args_str(), ["bisect", "bad"]);
        assert_eq!(calls[1].cwd.as_deref(), Some(dir));
        assert!(calls.iter().all(|call| {
            call.envs.iter().any(|(name, value)| {
                name.to_str() == Some("LC_ALL")
                    && value.as_deref().and_then(|value| value.to_str()) == Some("C")
            })
        }));
    }

    #[tokio::test]
    async fn bisect_malformed_or_ambiguous_output_is_parse_error() {
        let malformed = Git::with_runner(ScriptedRunner::new().on(
            ["git", "bisect", "good"],
            Reply::ok("[not-an-object-id] candidate\n"),
        ));
        let err = malformed
            .bisect_good(Path::new("/r"))
            .await
            .expect_err("malformed object id must not be accepted");
        assert!(matches!(err.reason(), ErrorReason::Parse { .. }));

        let ambiguous = Git::with_runner(ScriptedRunner::new().on(
            ["git", "bisect", "skip"],
            Reply::ok(
                "There are only 'skip'ped commits left to test.\n\
                 [aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa] one\n\
                 [bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb] two\n",
            ),
        ));
        let err = ambiguous
            .bisect_skip(Path::new("/r"))
            .await
            .expect_err("multiple possible candidates must not choose one");
        assert!(matches!(err.reason(), ErrorReason::Parse { .. }));
    }

    #[tokio::test]
    async fn bisect_nonzero_exit_preserves_structured_error() {
        let git =
            Git::with_runner(ScriptedRunner::new().on(
                ["git", "bisect", "bad"],
                Reply::fail(128, "fatal: no bisect session").with_stdout(
                    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa is the first bad commit\n",
                ),
            ));
        let err = git
            .bisect_bad(Path::new("/r"))
            .await
            .expect_err("git's non-zero result must not be parsed as success");
        assert!(matches!(
            err.reason(),
            ErrorReason::Exit {
                code: 128,
                stderr,
                ..
            } if stderr.contains("no bisect session")
        ));
    }

    // A non-zero exit surfaces as a structured `ErrorReason::Exit`.
    #[tokio::test]
    async fn nonzero_exit_is_structured_error() {
        let git = Git::with_runner(
            ScriptedRunner::new().on(["git", "status"], Reply::fail(128, "not a git repository")),
        );
        match git.status(Path::new(".")).await.unwrap_err().into_reason() {
            ErrorReason::Exit { code, stderr, .. } => {
                assert_eq!(code, 128);
                assert!(stderr.contains("not a git repository"), "{stderr}");
            }
            other => panic!("expected Exit, got {other:?}"),
        }
    }

    // diff_is_empty maps the raw exit code itself: 0 → clean, 1 → dirty, and
    // anything else is a real failure surfaced as ErrorReason::Exit.
    #[tokio::test]
    async fn diff_is_empty_maps_exit_codes() {
        let clean =
            Git::with_runner(ScriptedRunner::new().on(["git", "diff", "--quiet"], Reply::ok("")));
        assert!(clean.diff_is_empty(Path::new(".")).await.unwrap());

        let dirty = Git::with_runner(
            ScriptedRunner::new().on(["git", "diff", "--quiet"], Reply::fail(1, "")),
        );
        assert!(!dirty.diff_is_empty(Path::new(".")).await.unwrap());

        let broken = Git::with_runner(ScriptedRunner::new().on(
            ["git", "diff", "--quiet"],
            Reply::fail(128, "fatal: not a repo"),
        ));
        assert!(matches!(
            broken
                .diff_is_empty(Path::new("."))
                .await
                .unwrap_err()
                .reason(),
            ErrorReason::Exit { code: 128, .. }
        ));
    }

    // `add` must insert `--` before the pathspecs so a path can never be parsed
    // as an option, and `--literal-pathspecs` so a glob-magic character in a
    // path matches literally (R-01). No fallback rule: the run only matches if
    // `--literal-pathspecs add --` was built.
    #[tokio::test]
    async fn add_inserts_pathspec_separator() {
        let git = Git::with_runner(
            ScriptedRunner::new().on(["git", "--literal-pathspecs", "add", "--"], Reply::ok("")),
        );
        git.add(Path::new("."), &[PathBuf::from("f.rs")])
            .await
            .expect("add should build `--literal-pathspecs add -- <paths>`");
    }

    // A path set whose combined length exceeds `ARGV_PATHSPEC_BUDGET` must route
    // through the NUL-safe `--pathspec-from-file=- --pathspec-file-nul`
    // transport instead of the plain `add -- <paths>` argv: no per-path argv
    // entries, the payload travels over stdin instead (T-052).
    #[tokio::test]
    async fn add_large_path_set_uses_pathspec_from_file_stdin() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let paths: Vec<PathBuf> = (0..2_000)
            .map(|i| PathBuf::from(format!("dir/file_{i:05}.txt")))
            .collect();
        git.add(Path::new("."), &paths).await.expect("add");
        let call = rec.only_call();
        assert_eq!(
            call.args_str(),
            [
                "--literal-pathspecs",
                "add",
                "--pathspec-from-file=-",
                "--pathspec-file-nul",
            ]
        );
        assert!(call.has_stdin, "paths must travel over stdin, not argv");
    }

    #[tokio::test]
    async fn worktree_list_parses_porcelain() {
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "worktree", "list"],
            Reply::ok("worktree /repo\nHEAD abc\nbranch refs/heads/main\n"),
        ));
        let wts = git.worktree_list(Path::new(".")).await.expect("list");
        assert_eq!(wts.len(), 1);
        assert_eq!(wts[0].branch.as_deref(), Some("main"));
        assert_eq!(wts[0].head.as_deref(), Some("abc"));
    }

    // `submodule_list` builds the machine-unambiguous `config --file .gitmodules
    // --list -z` argv and parses the `-z` records — but only after the on-disk
    // `.gitmodules` probe passes, so this test writes a real file into the bound
    // dir before scripting the runner.
    #[tokio::test]
    async fn submodule_list_builds_config_argv_and_parses() {
        use vcs_testkit::TempDir;
        let tmp = TempDir::new("t096-list");
        std::fs::write(
            tmp.path().join(".gitmodules"),
            "[submodule \"libs/sub\"]\n\tpath = libs/sub\n\turl = ../sub\n",
        )
        .unwrap();
        let rec = RecordingRunner::replying(Reply::ok(
            "submodule.libs/sub.path\nlibs/sub\0submodule.libs/sub.url\n../sub\0",
        ));
        let git = Git::with_runner(&rec);
        let subs = git.submodule_list(tmp.path()).await.expect("list");
        assert_eq!(
            rec.only_call().args_str(),
            ["config", "--file", ".gitmodules", "--list", "-z"]
        );
        assert_eq!(subs.len(), 1);
        assert_eq!(subs[0].name, "libs/sub");
        assert_eq!(subs[0].path, PathBuf::from("libs/sub"));
        assert_eq!(subs[0].url, "../sub");
    }

    // No `.gitmodules` on disk ⇒ an empty list, and git is never spawned (the
    // absent-file probe short-circuits before the runner).
    #[tokio::test]
    async fn submodule_list_without_gitmodules_is_empty_without_spawning() {
        use vcs_testkit::TempDir;
        let tmp = TempDir::new("t096-nolist");
        let rec = RecordingRunner::replying(Reply::ok("unused"));
        let git = Git::with_runner(&rec);
        let subs = git.submodule_list(tmp.path()).await.expect("list");
        assert!(subs.is_empty());
        assert!(
            rec.calls().is_empty(),
            "no `.gitmodules` must not spawn git"
        );
    }

    // `submodule_status` builds `submodule status` and parses the prefix states.
    #[tokio::test]
    async fn submodule_status_builds_argv_and_parses() {
        let rec = RecordingRunner::replying(Reply::ok(
            " 833caa0 libs/sub (heads/main)\n-deadbee other/sub\n",
        ));
        let git = Git::with_runner(&rec);
        let got = git
            .submodule_status(Path::new("/repo"))
            .await
            .expect("status");
        assert_eq!(rec.only_call().args_str(), ["submodule", "status"]);
        assert_eq!(got.len(), 2);
        assert_eq!(got[0].state, SubmoduleState::Current);
        assert_eq!(got[0].path, PathBuf::from("libs/sub"));
        assert_eq!(got[0].describe.as_deref(), Some("heads/main"));
        assert_eq!(got[1].state, SubmoduleState::Uninitialized);
        assert_eq!(got[1].sha, "deadbee");
    }

    // The full `submodule update` builder emits its flags in a fixed order, ends
    // the paths behind `--`, and pins terminal prompts off.
    #[tokio::test]
    async fn submodule_update_builds_all_flags_in_order() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.submodule_update(
            Path::new("/repo"),
            SubmoduleUpdate::new()
                .init()
                .recursive()
                .depth(1)
                .path("libs/sub"),
        )
        .await
        .expect("update");
        let call = rec.only_call();
        assert_eq!(
            call.args_str(),
            [
                "submodule",
                "update",
                "--init",
                "--recursive",
                "--depth",
                "1",
                "--",
                "libs/sub"
            ]
        );
        assert!(
            call.env_is("GIT_TERMINAL_PROMPT", "0"),
            "a fetching update must not block on a credential prompt"
        );
    }

    // A default spec is a bare `submodule update` — no flags, no `--`.
    #[tokio::test]
    async fn submodule_update_default_is_bare() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.submodule_update(Path::new("/repo"), SubmoduleUpdate::new())
            .await
            .expect("update");
        assert_eq!(rec.only_call().args_str(), ["submodule", "update"]);
    }

    // A flag-shaped positional path is refused before spawning — the `--`
    // terminator already makes it inert, but the guard gives a clean error.
    #[tokio::test]
    async fn submodule_update_rejects_flag_like_path() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .submodule_update(
                Path::new("/repo"),
                SubmoduleUpdate::new().path("--upload-pack=/bin/evil"),
            )
            .await
            .expect_err("a flag-like submodule path must be refused");
        assert!(vcs_cli_support::is_invalid_input(&err));
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    // The new-branch worktree must build `worktree add -b <name> <path> <base>`,
    // in that exact order; only the full argv is scripted (no fallback).
    #[tokio::test]
    async fn worktree_add_builds_branch_path_and_base() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.worktree_add(
            Path::new("/repo"),
            WorktreeAdd::create_branch("/wt", rn("feature"), rv("main")),
        )
        .await
        .expect("worktree add");
        assert_eq!(
            rec.only_call().args_str(),
            ["worktree", "add", "-b", "feature", "/wt", "main"]
        );
    }

    #[tokio::test]
    async fn worktree_remove_passes_force_then_path() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.worktree_remove(Path::new("/repo"), WorktreeRemove::new("/wt").force())
            .await
            .expect("remove");
        assert_eq!(
            rec.only_call().args_str(),
            ["worktree", "remove", "--force", "/wt"]
        );
    }

    // The default (un-forced) spec omits `--force`.
    #[tokio::test]
    async fn worktree_remove_default_omits_force() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.worktree_remove(Path::new("/repo"), WorktreeRemove::new("/wt"))
            .await
            .expect("remove");
        assert_eq!(rec.only_call().args_str(), ["worktree", "remove", "/wt"]);
    }

    // `--no-checkout` must land between `-b <name>` and the path.
    #[tokio::test]
    async fn worktree_add_no_checkout_inserts_flag() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.worktree_add(
            Path::new("/repo"),
            WorktreeAdd::checkout("/wt", rv("main")).no_checkout(),
        )
        .await
        .expect("worktree add");
        assert_eq!(
            rec.only_call().args_str(),
            ["worktree", "add", "--no-checkout", "/wt", "main"]
        );
    }

    // A flag-shaped `path` is refused before spawning — `worktree add -b <name>
    // -evil <base>` would otherwise let git reparse `-evil` as an unknown flag
    // rather than the intended path.
    #[tokio::test]
    async fn worktree_add_rejects_flag_like_path() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .worktree_add(
                Path::new("/repo"),
                WorktreeAdd::checkout("-evil", rv("main")),
            )
            .await
            .expect_err("a flag-like worktree path must be refused");
        assert!(vcs_cli_support::is_invalid_input(&err));
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    // Empty/whitespace-only paths are refused the same way.
    #[tokio::test]
    async fn worktree_add_rejects_empty_path() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .worktree_add(Path::new("/repo"), WorktreeAdd::checkout("  ", rv("main")))
            .await
            .expect_err("an empty worktree path must be refused");
        assert!(vcs_cli_support::is_invalid_input(&err));
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    #[tokio::test]
    async fn worktree_remove_rejects_flag_like_path() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .worktree_remove(Path::new("/repo"), WorktreeRemove::new("--force"))
            .await
            .expect_err("a flag-like worktree path must be refused");
        assert!(vcs_cli_support::is_invalid_input(&err));
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    #[tokio::test]
    async fn worktree_remove_rejects_empty_path() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .worktree_remove(Path::new("/repo"), WorktreeRemove::new(""))
            .await
            .expect_err("an empty worktree path must be refused");
        assert!(vcs_cli_support::is_invalid_input(&err));
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    // The valid-path case still builds the expected argv (no regression from
    // the new guard).
    #[tokio::test]
    async fn worktree_move_builds_from_then_to() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.worktree_move(
            Path::new("/repo"),
            Path::new("/wt-old"),
            Path::new("/wt-new"),
        )
        .await
        .expect("worktree move");
        assert_eq!(
            rec.only_call().args_str(),
            ["worktree", "move", "/wt-old", "/wt-new"]
        );
    }

    // Both positionals are guarded — a flag-like `from` is caught first.
    #[tokio::test]
    async fn worktree_move_rejects_flag_like_from() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .worktree_move(Path::new("/repo"), Path::new("-evil"), Path::new("/wt-new"))
            .await
            .expect_err("a flag-like `from` must be refused");
        assert!(vcs_cli_support::is_invalid_input(&err));
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    // A flag-like `to` is caught too, even when `from` is valid.
    #[tokio::test]
    async fn worktree_move_rejects_flag_like_to() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .worktree_move(Path::new("/repo"), Path::new("/wt-old"), Path::new("-evil"))
            .await
            .expect_err("a flag-like `to` must be refused");
        assert!(vcs_cli_support::is_invalid_input(&err));
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    #[tokio::test]
    async fn sparse_checkout_set_defaults_to_cone_and_pins_patterns() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.sparse_checkout_set(
            Path::new("/repo"),
            SparseCheckoutSet::new(["src", "Cargo.toml"]),
        )
        .await
        .expect("sparse checkout set");
        assert_eq!(
            rec.only_call().args_str(),
            [
                "sparse-checkout",
                "set",
                "--cone",
                "--",
                "src",
                "Cargo.toml"
            ]
        );
    }

    #[tokio::test]
    async fn sparse_checkout_set_non_cone_uses_only_no_cone_mode_flag() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.sparse_checkout_set(
            Path::new("/repo"),
            SparseCheckoutSet::new(["/*", "!/docs/"]).non_cone(),
        )
        .await
        .expect("sparse checkout set");
        assert_eq!(
            rec.only_call().args_str(),
            ["sparse-checkout", "set", "--no-cone", "--", "/*", "!/docs/"]
        );
    }

    #[tokio::test]
    async fn sparse_checkout_set_rejects_empty_and_flag_like_patterns_before_spawn() {
        let empty_rec = RecordingRunner::replying(Reply::ok("unused"));
        let empty_git = Git::with_runner(&empty_rec);
        let empty_err = empty_git
            .sparse_checkout_set(
                Path::new("/repo"),
                SparseCheckoutSet::new(std::iter::empty::<String>()),
            )
            .await
            .expect_err("an empty sparse set must be refused");
        assert!(vcs_cli_support::is_invalid_input(&empty_err));
        assert!(empty_rec.calls().is_empty(), "nothing may spawn");

        for pattern in ["--evil", " "] {
            let rec = RecordingRunner::replying(Reply::ok("unused"));
            let git = Git::with_runner(&rec);
            let err = git
                .sparse_checkout_set(Path::new("/repo"), SparseCheckoutSet::new([pattern]))
                .await
                .expect_err("an invalid sparse path/pattern must be refused");
            assert!(vcs_cli_support::is_invalid_input(&err));
            assert!(rec.calls().is_empty(), "nothing may spawn for {pattern:?}");
        }
    }

    #[tokio::test]
    async fn sparse_checkout_list_preserves_pattern_text_and_line_order() {
        let rec = RecordingRunner::replying(Reply::ok("src\r\n  !/docs \n"));
        let git = Git::with_runner(&rec);
        assert_eq!(
            git.sparse_checkout_list(Path::new("/repo"))
                .await
                .expect("sparse checkout list"),
            ["src".to_string(), "  !/docs ".to_string()]
        );
        assert_eq!(rec.only_call().args_str(), ["sparse-checkout", "list"]);
    }

    #[tokio::test]
    async fn sparse_checkout_disable_builds_the_typed_command() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.sparse_checkout_disable(Path::new("/repo"))
            .await
            .expect("sparse checkout disable");
        assert_eq!(rec.only_call().args_str(), ["sparse-checkout", "disable"]);
    }

    #[tokio::test]
    async fn checkout_detach_builds_args() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.checkout_detach(Path::new("."), &rv("abc123"))
            .await
            .expect("detach");
        assert_eq!(
            rec.only_call().args_str(),
            ["checkout", "--detach", "abc123"]
        );
    }

    // current_branch reads `symbolic-ref --quiet --short HEAD`: exit 0 → the branch
    // name (a normal *or* unborn branch), exit 1 → None (detached HEAD), and any
    // other non-zero (e.g. not a repository) stays a real error.
    #[tokio::test]
    async fn current_branch_reads_symbolic_ref_with_exit_mapping() {
        // A normal branch (exit 0) — and the argv is pinned.
        let rec = RecordingRunner::replying(Reply::ok("feature/x\n"));
        let on_branch = Git::with_runner(&rec);
        assert_eq!(
            on_branch.current_branch(Path::new(".")).await.unwrap(),
            Some("feature/x".to_string())
        );
        assert_eq!(
            rec.only_call().args_str(),
            ["symbolic-ref", "--quiet", "--short", "HEAD"]
        );
        // An unborn branch also exits 0 with the branch name (the bug this fixes:
        // the old `rev-parse --abbrev-ref HEAD` errored with exit 128 here).
        let unborn = Git::with_runner(
            ScriptedRunner::new().on(["git", "symbolic-ref"], Reply::ok("main\n")),
        );
        assert_eq!(
            unborn.current_branch(Path::new(".")).await.unwrap(),
            Some("main".to_string())
        );
        // A detached HEAD exits 1 silently → None.
        let detached =
            Git::with_runner(ScriptedRunner::new().on(["git", "symbolic-ref"], Reply::fail(1, "")));
        assert_eq!(detached.current_branch(Path::new(".")).await.unwrap(), None);
        // Any other non-zero (not a repository, exit 128) is a real error.
        let not_repo = Git::with_runner(ScriptedRunner::new().on(
            ["git", "symbolic-ref"],
            Reply::fail(128, "fatal: not a git repository"),
        ));
        assert!(not_repo.current_branch(Path::new(".")).await.is_err());
    }

    // Partial amend commit must build `--literal-pathspecs commit --amend -m
    // <msg> --only -- <paths>` — `--literal-pathspecs` so a glob-magic
    // character in a path matches literally (R-01).
    #[tokio::test]
    async fn commit_paths_builds_only_amend_args() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.commit_paths(
            Path::new("."),
            CommitPaths::new([PathBuf::from("a.rs"), PathBuf::from("b.rs")], "msg").amend(),
        )
        .await
        .expect("commit_paths");
        assert_eq!(
            rec.only_call().args_str(),
            [
                "--literal-pathspecs",
                "commit",
                "--amend",
                "-m",
                "msg",
                "--only",
                "--",
                "a.rs",
                "b.rs"
            ]
        );
    }

    // Same transport switch as `add`'s twin test: a path set over
    // `ARGV_PATHSPEC_BUDGET` commits through `--pathspec-from-file=-
    // --pathspec-file-nul` (paths over stdin) instead of a plain `-- <paths>`
    // argv tail — and it is still exactly **one** `git commit` call (T-052).
    #[tokio::test]
    async fn commit_paths_large_path_set_uses_pathspec_from_file_stdin() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let paths: Vec<PathBuf> = (0..2_000)
            .map(|i| PathBuf::from(format!("dir/file_{i:05}.txt")))
            .collect();
        git.commit_paths(Path::new("."), CommitPaths::new(paths, "msg").amend())
            .await
            .expect("commit_paths");
        let calls = rec.calls();
        assert_eq!(calls.len(), 1, "must be a single atomic commit invocation");
        let call = &calls[0];
        assert_eq!(
            call.args_str(),
            [
                "--literal-pathspecs",
                "commit",
                "--amend",
                "-m",
                "msg",
                "--only",
                "--pathspec-from-file=-",
                "--pathspec-file-nul",
            ]
        );
        assert!(call.has_stdin, "paths must travel over stdin, not argv");
    }

    // is_unborn maps the rev-parse exit code: 0 → has commits (false), 1 →
    // unborn (true), anything else is a structured error.
    #[tokio::test]
    async fn is_unborn_maps_exit_codes() {
        let born =
            Git::with_runner(ScriptedRunner::new().on(["git", "rev-parse"], Reply::ok("abc\n")));
        assert!(!born.is_unborn(Path::new(".")).await.unwrap());
        let unborn =
            Git::with_runner(ScriptedRunner::new().on(["git", "rev-parse"], Reply::fail(1, "")));
        assert!(unborn.is_unborn(Path::new(".")).await.unwrap());
        let broken = Git::with_runner(
            ScriptedRunner::new().on(["git", "rev-parse"], Reply::fail(128, "boom")),
        );
        assert!(matches!(
            broken.is_unborn(Path::new(".")).await.unwrap_err().reason(),
            ErrorReason::Exit { code: 128, .. }
        ));
    }

    #[tokio::test]
    async fn log_builds_revspec_and_format() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.log(Path::new("."), &rv("main..HEAD"), 5)
            .await
            .expect("log");
        assert_eq!(
            rec.only_call().args_str(),
            [
                "log",
                "main..HEAD",
                "-n5",
                "-z",
                "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s",
                "--"
            ]
        );
    }

    // `log_paths` must insert `--literal-pathspecs` (R-02) and `--` exactly
    // once, right before the pathspecs, after the same revspec/count/format
    // arguments `log` builds.
    #[tokio::test]
    async fn log_paths_builds_revspec_format_and_pathspec_separator() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.log_paths(
            Path::new("."),
            &rv("main..HEAD"),
            5,
            &["src/a.rs".to_string(), "src/b.rs".to_string()],
        )
        .await
        .expect("log_paths");
        let args = rec.only_call().args_str();
        assert_eq!(
            args,
            [
                "--literal-pathspecs",
                "log",
                "main..HEAD",
                "-n5",
                "-z",
                "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s",
                "--",
                "src/a.rs",
                "src/b.rs",
            ]
        );
        assert_eq!(args.iter().filter(|a| *a == "--").count(), 1);
    }

    // An empty `paths` slice must NOT degrade to an unrestricted `git log` —
    // it's refused before any spawn (mirrors `commit_paths_refuses_empty_*` in
    // vcs-jj).
    #[tokio::test]
    async fn log_paths_refuses_empty_paths_without_spawning() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let err = git
            .log_paths(Path::new("."), &rv("HEAD"), 5, &[])
            .await
            .expect_err("empty paths must be refused");
        assert!(
            matches!(err.reason(), ErrorReason::Spawn { .. }),
            "got {err:?}"
        );
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    // A path set whose combined length exceeds `ARGV_PATHSPEC_BUDGET` splits
    // `log` into per-chunk calls (`git log` has no `--pathspec-from-file`
    // support, unlike `add`/`commit_paths`; each chunk call also carries
    // `--literal-pathspecs`, R-02) and merges the results: dedup by hash (the
    // "shared" commit appears in both chunks' canned output), reordered to
    // match a separate, pathless oracle call's commit order, capped at `max`
    // (T-052/R-03).
    //
    // All three commits share the exact same (second-resolution) author date
    // — a date-based sort would have no signal to order them at all and
    // could only fall back to arbitrary/input order — yet the oracle still
    // produces a definite, correct order, because it comes from git's own
    // traversal rather than from parsed timestamps. This is exactly the case
    // R-03 flagged as unfixable by refining the date sort further.
    #[tokio::test]
    async fn log_paths_large_path_set_chunks_dedupes_and_reorders_by_oracle_order() {
        // Two paths, each already over budget alone once paired — `chunk_pathspecs`
        // puts each in its own singleton chunk.
        let path_a = "a".repeat(4_000);
        let path_b = "b".repeat(4_000);
        // R-04: the chunked path resolves `revspec` once via `git rev-parse`
        // before any chunk/oracle call, then reuses the resolved token
        // (deliberately distinct from the literal `"HEAD"` text) everywhere
        // below — proving every one of those calls used the frozen snapshot,
        // not the original symbolic name.
        let common = [
            "git",
            "--literal-pathspecs",
            "log",
            "resolved-head-sha",
            "-n5",
            "-z",
            "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s",
            "--",
        ];
        let mut chunk_a_args: Vec<String> = common.iter().map(|s| (*s).to_string()).collect();
        chunk_a_args.push(path_a.clone());
        let mut chunk_b_args: Vec<String> = common.iter().map(|s| (*s).to_string()).collect();
        chunk_b_args.push(path_b.clone());

        // Chunk A: "newer-a" + "shared", both dated 2026-01-02.
        let reply_a = Reply::ok(
            "aaa1\u{1f}aaa\u{1f}A\u{1f}2026-01-02T00:00:00Z\u{1f}newer-a\0\
             shar\u{1f}sha\u{1f}S\u{1f}2026-01-02T00:00:00Z\u{1f}shared\0"
                .to_string(),
        );
        // Chunk B: "newest-b" (also dated 2026-01-02) + the SAME "shared"
        // commit again (touches a path in both chunks).
        let reply_b = Reply::ok(
            "bbb1\u{1f}bbb\u{1f}B\u{1f}2026-01-02T00:00:00Z\u{1f}newest-b\0\
             shar\u{1f}sha\u{1f}S\u{1f}2026-01-02T00:00:00Z\u{1f}shared\0"
                .to_string(),
        );
        // The oracle: git's real, unrestricted commit order for the same
        // revspec — puts "shared" between the other two, an order no sort of
        // the (identical) merged timestamps could ever reproduce.
        let order_reply = Reply::ok("bbb1\0shar\0aaa1\0".to_string());

        let git = Git::with_runner(
            ScriptedRunner::new()
                .on(
                    ["git", "rev-parse", "HEAD"],
                    Reply::ok("resolved-head-sha\n".to_string()),
                )
                .on(chunk_a_args, reply_a)
                .on(chunk_b_args, reply_b)
                .on(
                    ["git", "log", "resolved-head-sha", "-z", "--format=%H"],
                    order_reply,
                ),
        );

        let commits = git
            .log_paths(Path::new("."), &rv("HEAD"), 5, &[path_a, path_b])
            .await
            .expect("log_paths");

        assert_eq!(
            commits.iter().map(|c| c.hash.as_str()).collect::<Vec<_>>(),
            ["bbb1", "shar", "aaa1"],
            "expected the oracle's commit order across chunks, with the shared \
             commit deduplicated"
        );
    }

    // The single-call path (small path sets) must return byte-identical order
    // to what a chunked call over the same commits produces via the oracle —
    // i.e. chunking never changes which order callers see for a path set
    // that happens to be small (T-052/R-03 regression guard).
    #[tokio::test]
    async fn log_paths_single_call_and_chunked_call_agree_on_order() {
        let single_reply = Reply::ok(
            "bbb1\u{1f}bbb\u{1f}B\u{1f}2026-01-03T00:00:00Z\u{1f}newest-b\0\
             aaa1\u{1f}aaa\u{1f}A\u{1f}2026-01-02T00:00:00Z\u{1f}newer-a\0",
        );
        let single_call_git = Git::with_runner(ScriptedRunner::new().on(
            [
                "git",
                "--literal-pathspecs",
                "log",
                "HEAD",
                "-n5",
                "-z",
                "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s",
                "--",
                "src/a.rs",
                "src/b.rs",
            ],
            single_reply,
        ));
        let single_commits = single_call_git
            .log_paths(
                Path::new("."),
                &rv("HEAD"),
                5,
                &["src/a.rs".to_string(), "src/b.rs".to_string()],
            )
            .await
            .expect("log_paths");

        let path_a = "a".repeat(4_000);
        let path_b = "b".repeat(4_000);
        let common = [
            "git",
            "--literal-pathspecs",
            "log",
            "HEAD",
            "-n5",
            "-z",
            "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s",
            "--",
        ];
        let mut chunk_a_args: Vec<String> = common.iter().map(|s| (*s).to_string()).collect();
        chunk_a_args.push(path_a.clone());
        let mut chunk_b_args: Vec<String> = common.iter().map(|s| (*s).to_string()).collect();
        chunk_b_args.push(path_b.clone());
        let reply_a =
            Reply::ok("aaa1\u{1f}aaa\u{1f}A\u{1f}2026-01-02T00:00:00Z\u{1f}newer-a\0".to_string());
        let reply_b =
            Reply::ok("bbb1\u{1f}bbb\u{1f}B\u{1f}2026-01-03T00:00:00Z\u{1f}newest-b\0".to_string());
        // The oracle agrees with the single-call order: "newest-b" before
        // "newer-a".
        let order_reply = Reply::ok("bbb1\0aaa1\0".to_string());
        let chunked_git = Git::with_runner(
            ScriptedRunner::new()
                // R-04: the chunked path resolves `revspec` once via `git
                // rev-parse` before the chunk/oracle calls below.
                .on(
                    ["git", "rev-parse", "HEAD"],
                    Reply::ok("HEAD\n".to_string()),
                )
                .on(chunk_a_args, reply_a)
                .on(chunk_b_args, reply_b)
                .on(["git", "log", "HEAD", "-z", "--format=%H"], order_reply),
        );
        let chunked_commits = chunked_git
            .log_paths(Path::new("."), &rv("HEAD"), 5, &[path_a, path_b])
            .await
            .expect("log_paths");

        assert_eq!(
            single_commits
                .iter()
                .map(|c| c.hash.as_str())
                .collect::<Vec<_>>(),
            chunked_commits
                .iter()
                .map(|c| c.hash.as_str())
                .collect::<Vec<_>>(),
            "single-call and chunked-call order must agree when the oracle \
             agrees with the single-call order"
        );
    }

    // R-04: a range revspec (`A..B`) resolves via `git rev-parse` to *two*
    // tokens — the tip and a `^`-prefixed exclusion — and both chunk calls
    // plus the oracle call must forward both tokens verbatim, not just the
    // original `"main..feature"` text. This is exactly the expansion `git
    // log` would perform internally, so it's behavior-preserving while also
    // fixing the moving-ref race (a concurrent `main` or `feature` move
    // between chunk/oracle calls can no longer change what any of them see,
    // since all of them now share the one resolution taken up front).
    #[tokio::test]
    async fn log_paths_range_revspec_is_resolved_once_and_reused_across_chunks() {
        let path_a = "a".repeat(4_000);
        let path_b = "b".repeat(4_000);
        let common = [
            "git",
            "--literal-pathspecs",
            "log",
            "feature-sha",
            "^main-sha",
            "-n5",
            "-z",
            "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s",
            "--",
        ];
        let mut chunk_a_args: Vec<String> = common.iter().map(|s| (*s).to_string()).collect();
        chunk_a_args.push(path_a.clone());
        let mut chunk_b_args: Vec<String> = common.iter().map(|s| (*s).to_string()).collect();
        chunk_b_args.push(path_b.clone());
        let reply_a =
            Reply::ok("aaa1\u{1f}aaa\u{1f}A\u{1f}2026-01-02T00:00:00Z\u{1f}newer-a\0".to_string());
        let reply_b =
            Reply::ok("bbb1\u{1f}bbb\u{1f}B\u{1f}2026-01-03T00:00:00Z\u{1f}newest-b\0".to_string());
        let order_reply = Reply::ok("bbb1\0aaa1\0".to_string());

        let git = Git::with_runner(
            ScriptedRunner::new()
                .on(
                    ["git", "rev-parse", "main..feature"],
                    Reply::ok("feature-sha\n^main-sha\n".to_string()),
                )
                .on(chunk_a_args, reply_a)
                .on(chunk_b_args, reply_b)
                .on(
                    [
                        "git",
                        "log",
                        "feature-sha",
                        "^main-sha",
                        "-z",
                        "--format=%H",
                    ],
                    order_reply,
                ),
        );

        let commits = git
            .log_paths(Path::new("."), &rv("main..feature"), 5, &[path_a, path_b])
            .await
            .expect("log_paths");
        assert_eq!(
            commits.iter().map(|c| c.hash.as_str()).collect::<Vec<_>>(),
            ["bbb1", "aaa1"]
        );
    }

    // R-05: `git log` has no NUL-safe fallback transport the way
    // `add`/`commit_paths` do, so a single path that alone exceeds the argv
    // budget must be refused up front — never spawned as an over-budget
    // singleton chunk.
    #[tokio::test]
    async fn log_paths_rejects_individually_oversized_path_without_spawning() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let huge = "z".repeat(ARGV_PATHSPEC_BUDGET + 1);
        let err = git
            .log_paths(Path::new("."), &rv("HEAD"), 5, &[huge])
            .await
            .expect_err("an individually oversized path must be refused");
        assert!(
            matches!(err.reason(), ErrorReason::Spawn { .. }),
            "got {err:?}"
        );
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    // --- T-052 pure-helper tests ----------------------------------------------

    #[test]
    fn pathspec_argv_len_sums_bytes_plus_one_per_path() {
        use std::ffi::OsStr;
        let paths = [OsStr::new("a.rs"), OsStr::new("dir/b.rs")];
        // "a.rs" (4) + 1, "dir/b.rs" (8) + 1.
        assert_eq!(pathspec_argv_len(paths), 5 + 9);
        assert_eq!(pathspec_argv_len(std::iter::empty()), 0);
    }

    // Each path lands verbatim between NUL separators, in order — including a
    // leading dash, embedded spaces, and a glob-magic character (the whole
    // point of the `--literal-pathspecs` + NUL transport: no argv/shell layer
    // to mis-parse them, and git is told not to treat them as pathspec magic
    // either).
    #[test]
    fn pathspec_nul_bytes_joins_paths_literally_in_order() {
        use std::ffi::OsStr;
        let paths = [
            OsStr::new("-weird.txt"),
            OsStr::new("has space.txt"),
            OsStr::new("glob[1].txt"),
        ];
        let bytes = pathspec_nul_bytes(paths).expect("no embedded NUL");
        assert_eq!(bytes, b"-weird.txt\0has space.txt\0glob[1].txt\0".to_vec());
    }

    // An embedded NUL byte would silently truncate a pathspec-file-nul entry,
    // splitting one path into two on the very separator the transport relies
    // on — refused before anything is built, so `commit_paths`'s "no partial
    // result" contract holds even for this input-prep failure.
    #[test]
    fn pathspec_nul_bytes_rejects_embedded_nul() {
        use std::ffi::OsStr;
        // A real filesystem path can't contain a NUL byte, but the guard must
        // still catch a pathological caller-constructed one.
        let bad = unsafe { OsStr::from_encoded_bytes_unchecked(b"a\0b") };
        let err = pathspec_nul_bytes([bad]).expect_err("embedded NUL must be refused");
        assert!(
            matches!(err.reason(), ErrorReason::Spawn { .. }),
            "got {err:?}"
        );
    }

    #[test]
    fn chunk_pathspecs_packs_under_budget_and_splits_over_it() {
        let short = vec!["a".to_string(), "b".to_string(), "c".to_string()];
        assert_eq!(chunk_pathspecs(&short), vec![vec!["a", "b", "c"]]);

        // Two paths that individually fit but together exceed the budget split
        // into two singleton chunks, in order.
        let big_a = "a".repeat(ARGV_PATHSPEC_BUDGET - 100);
        let big_b = "b".repeat(ARGV_PATHSPEC_BUDGET - 100);
        let big = vec![big_a.clone(), big_b.clone()];
        assert_eq!(
            chunk_pathspecs(&big),
            vec![vec![big_a.as_str()], vec![big_b.as_str()]]
        );

        // A single path already over budget on its own still gets a (singleton)
        // chunk — nothing shorter is possible.
        let huge = vec!["z".repeat(ARGV_PATHSPEC_BUDGET * 2)];
        assert_eq!(chunk_pathspecs(&huge), vec![vec![huge[0].as_str()]]);

        assert!(chunk_pathspecs(&[]).is_empty());
    }

    #[test]
    fn parse_commit_order_splits_on_nul_and_drops_trailing_empty() {
        assert_eq!(
            parse_commit_order("aaa1\0bbb2\0ccc3\0"),
            vec!["aaa1", "bbb2", "ccc3"]
        );
        assert!(parse_commit_order("").is_empty());
    }

    #[tokio::test]
    async fn stash_push_adds_include_untracked() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.stash_push(Path::new("."), StashPush::new().include_untracked())
            .await
            .expect("stash");
        assert_eq!(
            rec.only_call().args_str(),
            ["stash", "push", "--include-untracked"]
        );
    }

    // The default spec stashes tracked changes only — no `--include-untracked`.
    #[tokio::test]
    async fn stash_push_default_omits_include_untracked() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.stash_push(Path::new("."), StashPush::new())
            .await
            .expect("stash");
        assert_eq!(rec.only_call().args_str(), ["stash", "push"]);
    }

    #[tokio::test]
    async fn stash_list_builds_argv_and_parses_entries() {
        let rec = RecordingRunner::replying(Reply::ok(
            "stash@{0}\u{1f}aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\u{1f}\
             On feature: my label\0",
        ));
        let git = Git::with_runner(&rec);
        let entries = git.stash_list(Path::new(".")).await.expect("stash_list");
        assert_eq!(
            rec.only_call().args_str(),
            ["stash", "list", "-z", "--format=%gd%x1f%H%x1f%gs"]
        );
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].index, 0);
        assert_eq!(entries[0].branch.as_deref(), Some("feature"));
        assert_eq!(entries[0].message, "my label");
    }

    #[tokio::test]
    async fn stash_apply_builds_the_indexed_selector() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.stash_apply(Path::new("."), 2).await.expect("apply");
        assert_eq!(rec.only_call().args_str(), ["stash", "apply", "stash@{2}"]);
    }

    #[tokio::test]
    async fn stash_drop_builds_the_indexed_selector() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.stash_drop(Path::new("."), 0).await.expect("drop");
        assert_eq!(rec.only_call().args_str(), ["stash", "drop", "stash@{0}"]);
    }

    // `clean` must refuse to run at all — no spawn — when the spec has picked
    // neither `dry_run` nor `force`: the crate's own guard, independent of the
    // caller's `clean.requireForce` git config.
    #[tokio::test]
    async fn clean_refuses_with_neither_dry_run_nor_force_without_spawning() {
        let rec = RecordingRunner::replying(Reply::ok("unused"));
        let git = Git::with_runner(&rec);
        let err = git
            .clean(Path::new("."), Clean::new())
            .await
            .expect_err("neither dry_run nor force must be refused");
        assert!(
            matches!(err.reason(), ErrorReason::Spawn { .. }),
            "got {err:?}"
        );
        assert!(rec.calls().is_empty(), "nothing may spawn");
    }

    #[tokio::test]
    async fn clean_dry_run_builds_n_flag_and_parses_would_remove() {
        let rec =
            RecordingRunner::replying(Reply::ok("Would remove junk.txt\nWould remove sub/\n"));
        let git = Git::with_runner(&rec);
        let entries = git
            .clean(Path::new("."), Clean::new().dry_run())
            .await
            .expect("dry run");
        assert_eq!(rec.only_call().args_str(), ["clean", "-n"]);
        assert_eq!(entries.len(), 2);
        assert_eq!(entries[0].path, PathBuf::from("junk.txt"));
        assert!(!entries[0].is_dir);
        assert_eq!(entries[1].path, PathBuf::from("sub"));
        assert!(entries[1].is_dir);
    }

    #[tokio::test]
    async fn clean_force_builds_f_flag_and_parses_removing() {
        let rec = RecordingRunner::replying(Reply::ok("Removing junk.txt\n"));
        let git = Git::with_runner(&rec);
        let entries = git
            .clean(Path::new("."), Clean::new().force())
            .await
            .expect("force clean");
        assert_eq!(rec.only_call().args_str(), ["clean", "-f"]);
        assert_eq!(
            entries,
            vec![CleanEntry {
                path: PathBuf::from("junk.txt"),
                is_dir: false,
            }]
        );
    }

    // `parse_clean_output` keys on the English "Would remove "/"Removing "
    // prefixes, which git gettext-translates under a non-English locale; `clean`
    // must force `LC_ALL=C` so those prefixes are always present, the same way
    // `diff_stat` forces it for `parse_shortstat`'s English keys.
    #[tokio::test]
    async fn clean_forces_c_locale() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.clean(Path::new("."), Clean::new().dry_run())
            .await
            .expect("dry run");
        assert!(
            rec.only_call().envs.iter().any(|(k, v)| {
                k.to_str() == Some("LC_ALL") && v.as_deref().and_then(|o| o.to_str()) == Some("C")
            }),
            "clean should force LC_ALL=C"
        );
    }

    // `dry_run` must win when a spec (oddly) sets both: `-f` is never sent, so
    // the call can never actually delete while also asking for a preview.
    #[tokio::test]
    async fn clean_dry_run_takes_priority_over_force() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.clean(Path::new("."), Clean::new().force().dry_run())
            .await
            .expect("dry run wins");
        assert_eq!(rec.only_call().args_str(), ["clean", "-n"]);
    }

    #[tokio::test]
    async fn clean_directories_inserts_d_flag() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.clean(Path::new("."), Clean::new().dry_run().directories())
            .await
            .expect("dry run + directories");
        assert_eq!(rec.only_call().args_str(), ["clean", "-n", "-d"]);
    }

    #[tokio::test]
    async fn clean_include_ignored_inserts_x_flag() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.clean(Path::new("."), Clean::new().dry_run().include_ignored())
            .await
            .expect("dry run + include ignored");
        assert_eq!(rec.only_call().args_str(), ["clean", "-n", "-x"]);
    }

    #[tokio::test]
    async fn clean_only_ignored_inserts_capital_x_flag() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.clean(Path::new("."), Clean::new().dry_run().only_ignored())
            .await
            .expect("dry run + only ignored");
        assert_eq!(rec.only_call().args_str(), ["clean", "-n", "-X"]);
    }

    // Every option combined: force + directories + include-ignored, in the
    // order the builder emits them.
    #[tokio::test]
    async fn clean_combines_force_directories_and_ignored_in_order() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.clean(
            Path::new("."),
            Clean::new().force().directories().include_ignored(),
        )
        .await
        .expect("combined flags");
        assert_eq!(rec.only_call().args_str(), ["clean", "-f", "-d", "-x"]);
    }

    // `diff_text` for the working tree must build `diff HEAD` plus the stable
    // machine-output flags, in order.
    #[tokio::test]
    async fn diff_text_builds_working_tree_args() {
        // The `rev-parse` unborn probe replies exit 0 (HEAD resolves), so the diff
        // targets HEAD. The probe is the first call; the diff is the last.
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.diff_text(Path::new("."), DiffSpec::WorkingTree)
            .await
            .expect("diff_text");
        assert_eq!(
            rec.calls().last().unwrap().args_str(),
            [
                "diff",
                "HEAD",
                "--no-color",
                "--no-ext-diff",
                "-M",
                // Pin the parser's `a/`…`b/` headers against a user's
                // `diff.noprefix`/`diff.mnemonicPrefix` config.
                "--src-prefix=a/",
                "--dst-prefix=b/",
                // End-of-revisions: `HEAD` is a revision, never a pathspec.
                "--",
            ]
        );
    }

    // Two endpoint selectors stay independent argv values, preserving both the
    // from -> to direction and compound-selector contents without constructing a
    // range string that Git could parse differently.
    #[tokio::test]
    async fn diff_text_between_builds_explicit_endpoint_args() {
        let from = rv("main | release");
        let to = rv("feature | hotfix");
        let diff = "diff --git a/m b/m\n@@ -1 +1 @@\n-a\n+b\n";
        let rec = RecordingRunner::replying(Reply::ok(diff));
        let git = Git::with_runner(&rec);
        git.diff_text_between(Path::new("."), &from, &to)
            .await
            .expect("diff_text_between");

        assert_eq!(
            rec.only_call().args_str(),
            [
                "diff",
                "main | release",
                "feature | hotfix",
                "--no-color",
                "--no-ext-diff",
                "-M",
                "--src-prefix=a/",
                "--dst-prefix=b/",
                "--",
            ]
        );
    }

    #[tokio::test]
    async fn diff_between_reuses_parser_and_bound_view() {
        let from = rv("base");
        let to = rv("tip");
        let out = "diff --git a/m b/m\n--- a/m\n+++ b/m\n@@ -1 +1 @@\n-a\n+b\n";
        let rec = RecordingRunner::replying(Reply::ok(out));
        let git = Git::with_runner(&rec);
        let files = git
            .at(Path::new("/repo"))
            .diff_between(&from, &to)
            .await
            .expect("diff_between");
        assert_eq!(files.len(), 1);
        assert_eq!(files[0].path, Path::new("m"));
        assert_eq!(rec.only_call().cwd.as_deref(), Some(Path::new("/repo")));
    }

    // On an unborn repo the working-tree diff targets the empty tree instead of
    // the unresolvable `HEAD`, so it returns additions rather than erroring. The
    // empty-tree id is resolved from git (`hash-object`, so it is object-format
    // correct — not the hard-coded SHA-1 id), and the diff rule only matches that
    // resolved argv, so a `HEAD` target would miss it.
    #[tokio::test]
    async fn diff_text_working_tree_uses_empty_tree_when_unborn() {
        // A stand-in id `empty_tree_oid` "computes"; the diff must target exactly it.
        let oid = "6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321";
        let git = Git::with_runner(
            ScriptedRunner::new()
                .on(["git", "rev-parse"], Reply::fail(1, "")) // unborn: HEAD doesn't resolve
                .on(["git", "hash-object"], Reply::ok(format!("{oid}\n")))
                .on(["git", "diff", oid], Reply::ok("EMPTY")),
        );
        let out = git
            .diff_text(Path::new("."), DiffSpec::WorkingTree)
            .await
            .expect("diff_text");
        assert_eq!(out, "EMPTY");
    }

    // `empty_tree_oid` asks git to hash an empty tree (`hash-object -t tree
    // --stdin`), so the id tracks the repo's object format instead of being a
    // hard-coded SHA-1 constant. The `--stdin` (not `-w`) form only computes it.
    #[tokio::test]
    async fn empty_tree_oid_hashes_an_empty_tree() {
        let rec = RecordingRunner::replying(Reply::ok(format!("{EMPTY_TREE_SHA1}\n")));
        let git = Git::with_runner(&rec);
        let oid = git
            .empty_tree_oid(Path::new("."))
            .await
            .expect("empty_tree_oid");
        assert_eq!(oid, EMPTY_TREE_SHA1);
        assert_eq!(
            rec.only_call().args_str(),
            ["hash-object", "-t", "tree", "--stdin"]
        );
    }

    // Hermetic: real diff() arg-building (`Rev`) + the ported parser against
    // canned git-format output.
    #[tokio::test]
    async fn diff_parses_scripted_output() {
        let out = "diff --git a/m b/m\n--- a/m\n+++ b/m\n@@ -1 +1 @@\n-a\n+b\n";
        let git = Git::with_runner(ScriptedRunner::new().on(["git", "diff"], Reply::ok(out)));
        let files = git
            .diff(Path::new("."), DiffSpec::Rev("HEAD~1".into()))
            .await
            .expect("diff");
        assert_eq!(files.len(), 1);
        assert_eq!(files[0].path, Path::new("m"));
        assert_eq!(files[0].change, ChangeKind::Modified);
    }

    #[tokio::test]
    async fn branch_exists_maps_exit_codes() {
        let yes = Git::with_runner(ScriptedRunner::new().on(["git", "show-ref"], Reply::ok("")));
        assert!(
            yes.branch_exists(Path::new("."), &rn("main"))
                .await
                .unwrap()
        );
        let no =
            Git::with_runner(ScriptedRunner::new().on(["git", "show-ref"], Reply::fail(1, "")));
        assert!(!no.branch_exists(Path::new("."), &rn("nope")).await.unwrap());
    }

    // The full ref prefix is stripped but a slashed default branch survives; an
    // unset origin/HEAD (non-zero exit) is `None`, not an error.
    #[tokio::test]
    async fn remote_head_branch_strips_prefix_and_keeps_slashes() {
        let simple = Git::with_runner(ScriptedRunner::new().on(
            ["git", "symbolic-ref"],
            Reply::ok("refs/remotes/origin/main\n"),
        ));
        assert_eq!(
            simple
                .remote_head_branch(Path::new("."))
                .await
                .unwrap()
                .as_deref(),
            Some("main")
        );

        let slashed = Git::with_runner(ScriptedRunner::new().on(
            ["git", "symbolic-ref"],
            Reply::ok("refs/remotes/origin/release/v2\n"),
        ));
        assert_eq!(
            slashed
                .remote_head_branch(Path::new("."))
                .await
                .unwrap()
                .as_deref(),
            Some("release/v2")
        );

        let unset =
            Git::with_runner(ScriptedRunner::new().on(["git", "symbolic-ref"], Reply::fail(1, "")));
        assert!(
            unset
                .remote_head_branch(Path::new("."))
                .await
                .unwrap()
                .is_none()
        );
    }

    // remote_branch_exists must pass `GIT_TERMINAL_PROMPT=0` and treat empty
    // stdout as "absent".
    #[tokio::test]
    async fn remote_branch_exists_sets_env_and_reads_stdout() {
        let rec = RecordingRunner::replying(Reply::ok("abc123\trefs/heads/main\n"));
        let git = Git::with_runner(&rec);
        assert!(
            git.remote_branch_exists(Path::new("/repo"), &rn("main"))
                .await
                .unwrap()
        );
        let call = rec.only_call();
        assert!(call.envs.iter().any(|(k, v)| {
            k.to_str() == Some("GIT_TERMINAL_PROMPT")
                && v.as_deref().and_then(|o| o.to_str()) == Some("0")
        }));
        // Exact-ref query — a bare `main` would tail-match `bar/main`.
        assert_eq!(call.args_str(), ["ls-remote", "origin", "refs/heads/main"]);

        let empty = Git::with_runner(ScriptedRunner::new().on(["git", "ls-remote"], Reply::ok("")));
        assert!(
            !empty
                .remote_branch_exists(Path::new("."), &rn("x"))
                .await
                .unwrap()
        );
    }

    // The glob/control/`:`/space names `remote_branch_exists` must exclude are now
    // refused at `RefName` construction — an invalid value can't reach the method
    // at all, so the exclusion is enforced by the type rather than an ad-hoc guard.
    #[test]
    fn remote_branch_invalid_names_rejected_at_refname() {
        for name in [
            "",
            "feature/*",
            "feature/?",
            "feature/[a]",
            "a:b",
            "two words",
            "bad\nname",
        ] {
            let err = RefName::new(name).expect_err("invalid remote branch name must be rejected");
            assert!(vcs_cli_support::is_invalid_input(&err), "{name:?}");
        }
    }

    #[tokio::test]
    async fn remote_branch_exists_accepts_valid_names() {
        let rec = RecordingRunner::replying(Reply::ok("abc123\trefs/heads/feature/T-010_fix\n"));
        let git = Git::with_runner(&rec);

        assert!(
            git.remote_branch_exists(Path::new("/repo"), &rn("feature/T-010_fix"))
                .await
                .expect("valid remote branch name")
        );
        assert_eq!(
            rec.only_call().args_str(),
            ["ls-remote", "origin", "refs/heads/feature/T-010_fix"]
        );
    }

    // `remote_branch_exists` sets a per-command `Command::timeout` (10 s) so an
    // unreachable or hung remote can't wedge the call — the "bounded wait" its own
    // doc-comment promises. That bound is only hermetically testable because of the
    // processkit 2.1 guarantee that a `ScriptedRunner` **pending** reply on a bulk
    // verb (`output_string`) now honors `Command::timeout`; under the old 1.2.x
    // semantics a pending reply parked forever regardless of the deadline. On a
    // paused clock the command's 10 s deadline elapses in virtual time, so a hung
    // `ls-remote` resolves as "absent" (`false`, empty output) instead of hanging.
    // The outer 1 h guard turns a regression (pending parking forever) into a clear
    // failure rather than a wedged suite; the command's own 10 s bound fires first.
    #[tokio::test(start_paused = true)]
    async fn remote_branch_exists_bounded_wait_resolves_a_hung_remote() {
        let git =
            Git::with_runner(ScriptedRunner::new().on(["git", "ls-remote"], Reply::pending()));
        let name = rn("main");
        let probe = git.remote_branch_exists(Path::new("/r"), &name);
        let exists = tokio::time::timeout(std::time::Duration::from_secs(3600), probe)
            .await
            .expect("the per-command 10 s timeout must resolve a hung ls-remote")
            .expect("a timed-out best-effort probe is `Ok(false)`, not an error");
        assert!(!exists, "an unreachable remote reads as absent");
    }

    #[tokio::test]
    async fn diff_stat_parses_counts() {
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "diff", "--shortstat"],
            Reply::ok(" 2 files changed, 5 insertions(+), 1 deletion(-)\n"),
        ));
        let stat = git
            .diff_stat(Path::new("."), &rv("main..HEAD"))
            .await
            .unwrap();
        assert_eq!(
            (stat.files_changed, stat.insertions, stat.deletions),
            (2, 5, 1)
        );
    }

    // The range-taking diff verbs terminate their argv with `--` so a `range`
    // that names a tracked path resolves as a revision (and errors) rather than
    // silently degrading into a pathspec-scoped working-tree diff (C2/M13).
    #[tokio::test]
    async fn diff_range_verbs_terminate_revisions_with_dashes() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.diff_range_is_empty(Path::new("/r"), &rv("main..HEAD"))
            .await
            .expect("diff_range_is_empty");
        assert_eq!(
            rec.only_call().args_str(),
            ["diff", "--quiet", "main..HEAD", "--"]
        );

        let rec = RecordingRunner::replying(Reply::ok(" 0 files changed\n"));
        let git = Git::with_runner(&rec);
        git.diff_stat(Path::new("/r"), &rv("main..HEAD"))
            .await
            .expect("diff_stat");
        assert_eq!(
            rec.only_call().args_str(),
            ["diff", "--shortstat", "main..HEAD", "--"]
        );
    }

    #[tokio::test]
    async fn status_text_returns_raw_porcelain() {
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "status", "--porcelain=v1"],
            Reply::ok(" M a.rs\n?? b.rs\n"),
        ));
        let text = git.status_text(Path::new(".")).await.expect("status_text");
        assert!(text.contains(" M a.rs") && text.contains("?? b.rs"));
    }

    #[tokio::test]
    async fn run_args_forwards_str_slices() {
        let git =
            Git::with_runner(ScriptedRunner::new().on(["git", "status", "-s"], Reply::ok("ok\n")));
        assert_eq!(git.run_args(&["status", "-s"]).await.unwrap(), "ok");
    }

    #[tokio::test]
    async fn merge_commit_builds_no_ff_and_message() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.merge_commit(
            Path::new("/r"),
            MergeCommit::branch(rv("feature"))
                .no_ff()
                .message("merge it"),
        )
        .await
        .unwrap();
        assert_eq!(
            rec.only_call().args_str(),
            ["merge", "--no-ff", "-m", "merge it", "feature"]
        );
    }

    // No message → `--no-edit` (default message, non-interactive) instead of `$EDITOR`.
    #[tokio::test]
    async fn merge_commit_without_message_uses_no_edit() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.merge_commit(Path::new("/r"), MergeCommit::branch(rv("feature")))
            .await
            .unwrap();
        assert_eq!(
            rec.only_call().args_str(),
            ["merge", "--no-edit", "feature"]
        );
    }

    // rebase/rebase_continue force a no-op editor so a headless caller never hangs.
    #[tokio::test]
    async fn rebase_suppresses_editor() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.rebase(Path::new("/r"), &rv("main")).await.unwrap();
        let call = rec.only_call();
        assert_eq!(call.args_str(), ["rebase", "main"]);
        assert!(call.envs.iter().any(|(k, v)| {
            k.to_str() == Some("GIT_EDITOR")
                && v.as_deref().and_then(|o| o.to_str()) == Some("true")
        }));
    }

    #[tokio::test]
    async fn push_builds_set_upstream_remote_refspec() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.push(
            Path::new("/r"),
            GitPush::refspec(&rn("feat"), &rn("feature")).set_upstream(),
        )
        .await
        .unwrap();
        assert_eq!(
            rec.only_call().args_str(),
            ["push", "-u", "origin", "feat:feature"]
        );
    }

    // The common bare-branch push: `push origin <branch>` (no `-u`), with prompts
    // off so a credential-needing remote fails fast instead of hanging.
    #[tokio::test]
    async fn push_bare_branch_builds_origin_branch_prompt_off() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.push(Path::new("/r"), GitPush::branch(rn("feature")))
            .await
            .unwrap();
        let call = rec.only_call();
        assert_eq!(call.args_str(), ["push", "origin", "feature"]);
        assert!(call.envs.iter().any(|(k, v)| {
            k.to_str() == Some("GIT_TERMINAL_PROMPT")
                && v.as_deref().and_then(|o| o.to_str()) == Some("0")
        }));
    }

    // M16: a `+` (force-push) or an extra `:` (multi-ref) smuggled into a branch name
    // is refused before spawning — force-pushing must be explicit via `run`.
    #[tokio::test]
    async fn push_rejects_force_and_multiref_metacharacters() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        // A `:` (an extra ref) is not a legal `RefName` character, so a multi-ref
        // refspec is refused at construction — it can never reach `GitPush`.
        for bad in ["+main:main", "a:b:c", "main:prod"] {
            assert!(RefName::new(bad).is_err(), "{bad:?} carries a `:`");
        }
        // A leading `+` (force) IS a legal ref character, so it passes `RefName` —
        // but the push refspec guard still refuses it before spawning. A force-push
        // must be explicit via `run`.
        assert!(
            git.push(Path::new("/r"), GitPush::branch(rn("+main")))
                .await
                .is_err(),
            "a force refspec must be refused before spawning"
        );
        // A legitimate `local:remote` refspec still works (the single `:` is the
        // API-inserted separator between two validated `RefName`s).
        assert!(
            git.push(Path::new("/r"), GitPush::refspec(&rn("main"), &rn("prod")))
                .await
                .is_ok()
        );
        assert!(
            rec.calls()
                .iter()
                .all(|c| c.args_str().last().unwrap() != "+main")
        );
    }

    // `.remote()` swaps the remote token in place.
    #[tokio::test]
    async fn push_remote_override_swaps_remote() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.push(
            Path::new("/r"),
            GitPush::branch(rn("feature")).remote("upstream"),
        )
        .await
        .unwrap();
        assert_eq!(rec.only_call().args_str(), ["push", "upstream", "feature"]);
    }

    // With a credential provider, a remote op gets a leading `-c credential.helper`
    // pair (the secret referenced by env-var NAME) plus the secret in the env — and
    // the token value never appears in argv. Covers push (mutating) and fetch.
    #[tokio::test]
    async fn with_credentials_injects_helper_and_secret_env_for_remote_ops() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec)
            .with_credentials(Arc::new(StaticCredential::token("ghp_secret123")));
        git.push(Path::new("/r"), GitPush::branch(rn("feature")))
            .await
            .unwrap();
        let call = rec.only_call();
        let args = call.args_str();
        // A leading helper-reset + inline helper precede the subcommand.
        assert_eq!(args[0], "-c", "config flag leads the argv");
        assert!(
            args.iter().any(|a| a == "credential.helper="),
            "inherited helpers are cleared first: {args:?}"
        );
        assert!(
            args.iter()
                .any(|a| a.contains("credential.helper=!f()")
                    && a.contains("VCS_TOOLKIT_GIT_PASSWORD")),
            "inline helper references the secret by env-var name: {args:?}"
        );
        assert!(
            args.contains(&"push".to_string()) && args.contains(&"feature".to_string()),
            "the real subcommand still runs: {args:?}"
        );
        // The secret value is NEVER in argv.
        assert!(
            !args.iter().any(|a| a.contains("ghp_secret123")),
            "secret leaked into argv: {args:?}"
        );
        // The secret lives in the env, under the helper's var name.
        let pw = call
            .envs
            .iter()
            .find(|(k, _)| k.to_str() == Some("VCS_TOOLKIT_GIT_PASSWORD"))
            .and_then(|(_, v)| v.as_ref())
            .and_then(|v| v.to_str());
        assert_eq!(pw, Some("ghp_secret123"), "secret carried in env");
    }

    // Without a provider, remote ops are byte-identical to before — no `-c`
    // credential helper, no secret env (ambient git auth, unchanged).
    #[tokio::test]
    async fn default_client_injects_no_credential_helper() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.push(Path::new("/r"), GitPush::branch(rn("feature")))
            .await
            .unwrap();
        let call = rec.only_call();
        assert_eq!(
            call.args_str(),
            ["push", "origin", "feature"],
            "no credential `-c` args without a provider"
        );
        assert!(
            !call
                .envs
                .iter()
                .any(|(k, _)| k.to_str() == Some("VCS_TOOLKIT_GIT_PASSWORD")),
            "no secret env without a provider"
        );
    }

    // `clone_repo` builds its argv via a different path (`command()` + `.arg()`
    // chaining, not `command_in` + extend), so verify the `-c` credential args
    // still LEAD it and the real clone flags/url/dest follow the subcommand.
    #[tokio::test]
    async fn with_credentials_clone_puts_config_flags_before_subcommand() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git =
            Git::with_runner(&rec).with_credentials(Arc::new(StaticCredential::token("s3cr3t")));
        git.clone_repo(
            "https://example.com/r.git",
            Path::new("/dest"),
            CloneSpec::default().branch("main"),
        )
        .await
        .unwrap();
        let call = rec.only_call();
        let args = call.args_str();
        assert_eq!(args[0], "-c", "config flags lead the clone argv");
        let clone_at = args
            .iter()
            .position(|a| a == "clone")
            .expect("clone present");
        // Only credential `-c` flags precede the `clone` subcommand.
        assert!(
            args[..clone_at]
                .iter()
                .all(|a| a == "-c" || a.starts_with("credential.helper")),
            "only credential -c flags precede `clone`: {args:?}"
        );
        // The real clone flags/url/dest follow the subcommand.
        let tail = &args[clone_at..];
        assert!(tail.iter().any(|a| a == "--branch") && tail.iter().any(|a| a == "main"));
        assert!(tail.iter().any(|a| a == "https://example.com/r.git"));
        assert!(
            !args.iter().any(|a| a.contains("s3cr3t")),
            "secret not in argv"
        );
        // H5: clone scopes the helper to the URL's host (in env, never argv), so a
        // cross-host redirect/submodule during the clone can't extract the token.
        let host = call
            .envs
            .iter()
            .find(|(k, _)| k.to_str() == Some("VCS_TOOLKIT_GIT_HOST"))
            .and_then(|(_, v)| v.as_ref())
            .and_then(|v| v.to_str());
        assert_eq!(
            host,
            Some("example.com"),
            "the clone URL's host scopes the credential helper"
        );
        // The host scoping travels in env; the credential `-c` flags that precede
        // `clone` must not bake the host into the helper config.
        assert!(
            args[..clone_at].iter().all(|a| !a.contains("example.com")),
            "host stays in env, not the credential config args: {:?}",
            &args[..clone_at]
        );
    }

    // A `Credential::userpass` username threads through to the helper's env on a
    // remote op (here `fetch`) — the non-default-username path, end-to-end.
    #[tokio::test]
    async fn with_credentials_userpass_threads_username_through_env() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec).with_credentials(Arc::new(StaticCredential::new(
            Credential::userpass("alice", "s3cr3t"),
        )));
        git.fetch(Path::new("/r")).await.unwrap();
        let call = rec.only_call();
        let user = call
            .envs
            .iter()
            .find(|(k, _)| k.to_str() == Some("VCS_TOOLKIT_GIT_USERNAME"))
            .and_then(|(_, v)| v.as_ref())
            .and_then(|v| v.to_str());
        assert_eq!(user, Some("alice"), "userpass username reaches the env");
        assert_eq!(call.args_str()[0], "-c", "helper `-c` leads fetch too");
        assert!(call.args_str().contains(&"fetch".to_string()));
    }

    // ONE client, several hosts: a host-keyed provider hands each clone only its OWN
    // host's secret — routed by the URL's host, which now reaches the
    // `CredentialRequest` — and the inline helper is gated to that host, so a
    // neighbouring instance's token can never leak into another host's clone. (T-045)
    #[tokio::test]
    async fn one_client_host_keyed_provider_isolates_tokens_across_hosts() {
        let provider = Arc::new(provider_fn(|r: &CredentialRequest<'_>| {
            Ok(match r.host {
                Some("github.com") => Some(Credential::token("gh-secret")),
                Some("gitlab.example") => Some(Credential::token("gl-secret")),
                _ => None,
            })
        }));
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec).with_credentials(provider);

        // The same client clones two different hosts, back to back.
        git.clone_repo(
            "https://github.com/o/r.git",
            Path::new("/dest-gh"),
            CloneSpec::default(),
        )
        .await
        .unwrap();
        git.clone_repo(
            "https://gitlab.example/o/r.git",
            Path::new("/dest-gl"),
            CloneSpec::default(),
        )
        .await
        .unwrap();

        let calls = rec.calls();
        assert_eq!(calls.len(), 2, "two clones recorded");
        // Clone #1 (github.com) → the github.com secret, gated to github.com.
        assert!(calls[0].env_is("VCS_TOOLKIT_GIT_PASSWORD", "gh-secret"));
        assert!(calls[0].env_is("VCS_TOOLKIT_GIT_HOST", "github.com"));
        // Clone #2 (gitlab.example) → the gitlab secret, gated to gitlab.example.
        assert!(calls[1].env_is("VCS_TOOLKIT_GIT_PASSWORD", "gl-secret"));
        assert!(calls[1].env_is("VCS_TOOLKIT_GIT_HOST", "gitlab.example"));
        // No cross-contamination: neither host's secret bleeds into the other's
        // clone, and no secret ever reaches argv.
        assert!(!calls[0].env_is("VCS_TOOLKIT_GIT_PASSWORD", "gl-secret"));
        assert!(!calls[1].env_is("VCS_TOOLKIT_GIT_PASSWORD", "gh-secret"));
        for c in calls.iter() {
            assert!(
                !c.args_str()
                    .iter()
                    .any(|a| a.contains("gh-secret") || a.contains("gl-secret")),
                "secrets stay out of argv"
            );
        }
    }

    // Fallback policy on the git helper path, read (`fetch`) vs write (`push`):
    // `Ok(None)` → ambient (no inline credential helper, no secret env); `Err` →
    // fail-closed abort (git never spawns). (T-045)
    #[tokio::test]
    async fn git_credential_fallback_policy_for_read_and_write() {
        // Ok(None): ambient — no helper `-c` flags lead the argv, no secret env.
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec)
            .with_credentials(Arc::new(provider_fn(|_r: &CredentialRequest<'_>| Ok(None))));
        git.fetch(Path::new("/r")).await.unwrap();
        git.push(Path::new("/r"), GitPush::branch(rn("feature")))
            .await
            .unwrap();
        for c in rec.calls().iter() {
            assert!(
                !c.has_env("VCS_TOOLKIT_GIT_PASSWORD"),
                "ambient: no secret env on {:?}",
                c.args_str()
            );
            assert_ne!(
                c.args_str().first().map(String::as_str),
                Some("-c"),
                "ambient: no leading credential -c flags"
            );
        }

        // Err: fail-closed — the op aborts and git is never spawned, for read & write.
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec).with_credentials(Arc::new(provider_fn(
            |_r: &CredentialRequest<'_>| {
                Err(Error::spawn(
                    BINARY,
                    std::io::Error::new(std::io::ErrorKind::ConnectionRefused, "vault down"),
                ))
            },
        )));
        assert!(
            git.fetch(Path::new("/r")).await.is_err(),
            "read aborts on provider error"
        );
        assert!(
            git.push(Path::new("/r"), GitPush::branch(rn("feature")))
                .await
                .is_err(),
            "write aborts on provider error"
        );
        assert!(
            rec.calls().is_empty(),
            "git never spawns when the provider errored"
        );
    }

    // No-provider is byte-identical for the read/clone arg-construction paths too,
    // not only `push` (fetch uses `command_in`+extend; clone uses `command`+chain).
    #[tokio::test]
    async fn default_client_no_helper_on_fetch_and_clone() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        Git::with_runner(&rec).fetch(Path::new("/r")).await.unwrap();
        assert_eq!(
            rec.only_call().args_str(),
            ["fetch", "--quiet"],
            "fetch unchanged without a provider"
        );

        let rec = RecordingRunner::replying(Reply::ok(""));
        Git::with_runner(&rec)
            .clone_repo(
                "https://example.com/r.git",
                Path::new("/dest"),
                CloneSpec::default(),
            )
            .await
            .unwrap();
        assert_eq!(
            rec.only_call().args_str()[0],
            "clone",
            "clone leads with the subcommand (no `-c`) without a provider"
        );
    }

    // The `with_token` convenience drives the same HTTPS credential.helper path as
    // `with_credentials` (secret in env, helper `-c` leads, not in argv).
    #[tokio::test]
    async fn with_token_convenience_authenticates_https_remote() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec).with_token("ghp_conv");
        git.fetch(Path::new("/r")).await.unwrap();
        let call = rec.only_call();
        assert_eq!(call.args_str()[0], "-c", "helper `-c` leads");
        let pw = call
            .envs
            .iter()
            .find(|(k, _)| k.to_str() == Some("VCS_TOOLKIT_GIT_PASSWORD"))
            .and_then(|(_, v)| v.as_ref())
            .and_then(|v| v.to_str());
        assert_eq!(pw, Some("ghp_conv"), "secret carried in env");
        assert!(
            !call.args_str().iter().any(|a| a.contains("ghp_conv")),
            "secret not in argv"
        );
    }

    #[tokio::test]
    async fn upstream_distinguishes_no_upstream_from_errors() {
        let set = Git::with_runner(
            ScriptedRunner::new()
                .on(["git", "symbolic-ref"], Reply::ok("main\n"))
                .on(["git", "rev-parse"], Reply::ok("origin/main\n")),
        );
        assert_eq!(
            set.upstream(Path::new(".")).await.unwrap().as_deref(),
            Some("origin/main")
        );
        // On a valid attached branch, exit 128 from `@{u}` means no upstream.
        let unset = Git::with_runner(
            ScriptedRunner::new()
                .on(["git", "symbolic-ref"], Reply::ok("main\n"))
                .on(["git", "rev-parse"], Reply::fail(128, "")),
        );
        assert!(unset.upstream(Path::new(".")).await.unwrap().is_none());

        // Detached HEAD is rejected by the attached-branch probe.
        let detached =
            Git::with_runner(ScriptedRunner::new().on(["git", "symbolic-ref"], Reply::fail(1, "")));
        assert!(detached.upstream(Path::new(".")).await.is_err());

        // A directory outside a repository is a real error too.
        let not_repo = Git::with_runner(ScriptedRunner::new().on(
            ["git", "symbolic-ref"],
            Reply::fail(128, "fatal: not a git repository"),
        ));
        assert!(not_repo.upstream(Path::new(".")).await.is_err());

        // Other numeric failures and no-code outcomes must not read as "unset".
        let broken = Git::with_runner(
            ScriptedRunner::new()
                .on(["git", "symbolic-ref"], Reply::ok("main\n"))
                .on(["git", "rev-parse"], Reply::fail(1, "corrupt config")),
        );
        assert!(broken.upstream(Path::new(".")).await.is_err());

        let timed_out = Git::with_runner(
            ScriptedRunner::new()
                .on(["git", "symbolic-ref"], Reply::ok("main\n"))
                .on(["git", "rev-parse"], Reply::timeout()),
        );
        assert!(timed_out.upstream(Path::new(".")).await.is_err());

        let signalled = Git::with_runner(
            ScriptedRunner::new()
                .on(["git", "symbolic-ref"], Reply::ok("main\n"))
                .on(["git", "rev-parse"], Reply::signalled(Some(9))),
        );
        assert!(signalled.upstream(Path::new(".")).await.is_err());
    }

    // remote_head_branch maps the `symbolic-ref --quiet` exit code: 0 → the branch
    // (ref prefix stripped), 1 → None (unset origin/HEAD), and anything else (a real
    // failure / timeout) surfaces rather than being swallowed as "no default branch".
    #[tokio::test]
    async fn remote_head_branch_maps_exit_codes() {
        let set = Git::with_runner(ScriptedRunner::new().on(
            ["git", "symbolic-ref"],
            Reply::ok("refs/remotes/origin/release/v2\n"),
        ));
        assert_eq!(
            set.remote_head_branch(Path::new("."))
                .await
                .unwrap()
                .as_deref(),
            Some("release/v2"),
            "the full ref prefix is stripped, slashes preserved"
        );
        let unset =
            Git::with_runner(ScriptedRunner::new().on(["git", "symbolic-ref"], Reply::fail(1, "")));
        assert!(
            unset
                .remote_head_branch(Path::new("."))
                .await
                .unwrap()
                .is_none()
        );
        // A real failure (exit 128, not the silent --quiet exit 1) surfaces.
        let err = Git::with_runner(ScriptedRunner::new().on(
            ["git", "symbolic-ref"],
            Reply::fail(128, "fatal: not a git repository"),
        ));
        assert!(err.remote_head_branch(Path::new(".")).await.is_err());
        // A timeout surfaces too.
        let timed_out =
            Git::with_runner(ScriptedRunner::new().on(["git", "symbolic-ref"], Reply::timeout()));
        assert!(timed_out.remote_head_branch(Path::new(".")).await.is_err());
    }

    #[tokio::test]
    async fn set_upstream_builds_branch_flag() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.set_upstream(Path::new("/r"), &rn("feat"), &rn("origin/feature"))
            .await
            .unwrap();
        assert_eq!(
            rec.only_call().args_str(),
            ["branch", "--set-upstream-to=origin/feature", "feat"]
        );
    }

    #[tokio::test]
    async fn remote_branches_parses_ls_remote() {
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "ls-remote"],
            Reply::ok("aaa\trefs/heads/main\nbbb\trefs/heads/feat/x\n"),
        ));
        let branches = git.remote_branches(Path::new("."), "origin").await.unwrap();
        assert_eq!(branches, ["main", "feat/x"]);
    }

    #[tokio::test]
    async fn remote_list_runs_remote_v_and_prefers_fetch_url() {
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "remote", "-v"],
            Reply::ok(
                "origin https://example.test/fetch.git (fetch)\n\
                 origin https://example.test/push.git (push)\n",
            ),
        ));
        assert_eq!(
            git.remote_list(Path::new("/repo")).await.unwrap(),
            vec![Remote {
                name: "origin".into(),
                url: "https://example.test/fetch.git".into(),
            }]
        );
    }

    #[tokio::test]
    async fn delete_branch_force_uses_capital_d() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.delete_branch(Path::new("/r"), BranchDelete::new(rn("old")).force())
            .await
            .unwrap();
        assert_eq!(rec.only_call().args_str(), ["branch", "-D", "old"]);
    }

    // The default (un-forced) spec uses lowercase `-d`.
    #[tokio::test]
    async fn delete_branch_default_uses_lowercase_d() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.delete_branch(Path::new("/r"), BranchDelete::new(rn("old")))
            .await
            .unwrap();
        assert_eq!(rec.only_call().args_str(), ["branch", "-d", "old"]);
    }

    // `branch --merged` marks the current branch with `*` and a branch checked out
    // in another worktree with `+`; both must still match after marker stripping.
    #[tokio::test]
    async fn is_merged_strips_branch_markers() {
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "branch", "--merged"],
            Reply::ok("  main\n* feature\n+ wt-branch\n"),
        ));
        for name in ["main", "feature", "wt-branch"] {
            assert!(
                git.is_merged(
                    Path::new("."),
                    MergeCheck::branch(rn(name)).into_base(rv("main"))
                )
                .await
                .unwrap(),
                "{name} should be reported merged"
            );
        }
        assert!(
            !git.is_merged(
                Path::new("."),
                MergeCheck::branch(rn("absent")).into_base(rv("main"))
            )
            .await
            .unwrap()
        );
    }

    // A5: the `MergeCheck` builder lands branch/base in the right slots, and
    // `is_merged` queries `branch --merged <base>` — so a transposed pair would
    // change the emitted command, not silently invert a same-shaped call.
    #[tokio::test]
    async fn merge_check_names_branch_and_base_without_transposition() {
        use processkit::testing::RecordingRunner;
        let spec = MergeCheck::branch(rn("feature")).into_base(rv("main"));
        assert_eq!(spec.branch.as_str(), "feature");
        assert_eq!(spec.base.as_str(), "main");

        let rec = RecordingRunner::replying(Reply::ok("  feature\n* main\n"));
        let merged = Git::with_runner(&rec)
            .is_merged(
                Path::new("/repo"),
                MergeCheck::branch(rn("feature")).into_base(rv("main")),
            )
            .await
            .unwrap();
        // `feature` appears under `branch --merged main`, so it reports merged — and
        // the emitted args put `base` (main) in the `--merged` slot, not `branch`.
        assert!(merged, "feature is listed as merged into main");
        assert_eq!(
            rec.only_call().args_str(),
            ["branch", "--merged", "main", "--no-column", "--no-color"]
        );
    }

    // `fetch` must disable the credential prompt so it fails fast (never hangs) on
    // a remote needing auth — matching the other remote ops.
    #[tokio::test]
    async fn fetch_disables_terminal_prompt() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.fetch(Path::new("/r")).await.unwrap();
        let call = rec.only_call();
        assert_eq!(call.args_str(), ["fetch", "--quiet"]);
        assert!(call.envs.iter().any(|(k, v)| {
            k.to_str() == Some("GIT_TERMINAL_PROMPT")
                && v.as_deref().and_then(|o| o.to_str()) == Some("0")
        }));
    }

    #[tokio::test]
    async fn network_progress_variants_stream_scripted_lifecycles() {
        use std::sync::{Arc, Mutex};

        let runner = ScriptedRunner::new()
            .on(
                ["git", "fetch", "--progress"],
                Reply::ok("fetch-out").with_stderr("fetch-progress"),
            )
            .on(
                ["git", "push", "--progress", "-u", "origin", "main"],
                Reply::ok("push-out").with_stderr("push-progress"),
            )
            .on(
                ["git", "clone", "--progress", "https://x/r", "/dest"],
                Reply::ok("clone-out").with_stderr("clone-progress"),
            );
        let git = Git::with_runner(runner);

        for operation in 0..3 {
            let names = Arc::new(Mutex::new(Vec::new()));
            let sink = Arc::clone(&names);
            let mut progress = move |event: ProcessEvent| {
                sink.lock().unwrap().push(event.name());
            };
            match operation {
                0 => git
                    .fetch_with_progress(Path::new("/repo"), &mut progress)
                    .await
                    .unwrap(),
                1 => git
                    .push_with_progress(
                        Path::new("/repo"),
                        GitPush::branch(rn("main")).set_upstream(),
                        &mut progress,
                    )
                    .await
                    .unwrap(),
                2 => git
                    .clone_repo_with_progress(
                        "https://x/r",
                        Path::new("/dest"),
                        CloneSpec::new(),
                        &mut progress,
                    )
                    .await
                    .unwrap(),
                _ => unreachable!(),
            }
            drop(progress);
            let names = names.lock().unwrap();
            assert_eq!(names.first(), Some(&"started"));
            assert!(names.contains(&"stdout"));
            assert!(names.contains(&"stderr"));
            assert_eq!(names.last(), Some(&"exited"));
        }
    }

    #[tokio::test(start_paused = true)]
    async fn fetch_progress_watchdog_is_opt_in_and_reports_inactivity() {
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "fetch", "--progress"],
            Reply::lines(["late"]).with_line_delay(std::time::Duration::from_secs(10)),
        ))
        .default_inactivity_timeout(std::time::Duration::from_secs(3));
        let mut progress = |_event: ProcessEvent| {};

        let err = git
            .fetch_with_progress(Path::new("/repo"), &mut progress)
            .await
            .expect_err("a silent git progress stream should trip the opt-in watchdog");
        assert!(matches!(
            err.reason(),
            ErrorReason::Timeout {
                timeout,
                inactivity: true,
                ..
            } if *timeout == std::time::Duration::from_secs(3)
        ));
    }

    #[tokio::test]
    async fn streamed_clone_failure_keeps_the_cleanup_contract() {
        use vcs_testkit::TempDir;

        let root = TempDir::new("stream-clone-cleanup");
        let dest = root.path().join("dest");
        std::fs::create_dir(&dest).unwrap();
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "clone", "--progress"],
            Reply::fail(128, "network failed"),
        ));
        let mut progress = |_event: ProcessEvent| {};
        assert!(
            git.clone_repo_with_progress("https://x/r", &dest, CloneSpec::new(), &mut progress)
                .await
                .is_err()
        );
        assert!(!dest.exists(), "a cleanable partial destination is removed");
    }

    // A transient failure (DNS/network) is retried up to FETCH_ATTEMPTS times.
    #[tokio::test]
    async fn fetch_retries_transient_failures() {
        let rec = RecordingRunner::replying(Reply::fail(
            128,
            "fatal: unable to access: Could not resolve host: example.com",
        ));
        let git = Git::with_runner(&rec);
        assert!(git.fetch(Path::new("/r")).await.is_err());
        assert_eq!(rec.calls().len(), FETCH_ATTEMPTS as usize);
    }

    // R6 (a `fetch` timeout is NOT retried) is pinned at the unit level by
    // `vcs_cli_support`'s `classifies_nothing_to_commit_and_transient_fetch`
    // (`is_transient_fetch_error(&Timeout) == false`); together with
    // `fetch_retries_transient_failures` above (the loop retries exactly what the
    // predicate accepts) that proves the timeout is terminal for the fetch-retry. A
    // faithful end-to-end timeout is awkward to simulate hermetically (a paused-clock
    // `Reply::pending()` doesn't auto-fire the per-command deadline), so it isn't
    // duplicated here.

    // Opt-in lock-contention retry: a mutation that fails because another process
    // holds `index.lock` is retried and succeeds — the command never ran, so the
    // retry is safe. `RetryPolicy::none().attempts(3)` keeps the backoff at zero so
    // the test never sleeps.
    #[tokio::test]
    async fn with_retry_retries_lock_contention_on_a_mutation() {
        let rec = RecordingRunner::new(ScriptedRunner::new().on_sequence(
            ["git", "commit"],
            [
                Reply::fail(
                    128,
                    "fatal: Unable to create '/r/.git/index.lock': File exists.",
                ),
                Reply::ok(""),
            ],
        ));
        let git = Git::with_runner(&rec).with_retry(RetryPolicy::none().attempts(3));
        git.commit(Path::new("/r"), "msg")
            .await
            .expect("retried past the lock");
        assert_eq!(rec.calls().len(), 2, "one retry after the lock failure");
    }

    // Retry is off by default — the same lock failure propagates without `with_retry`.
    #[tokio::test]
    async fn default_client_does_not_retry_lock_contention() {
        let rec = RecordingRunner::new(ScriptedRunner::new().on_sequence(
            ["git", "commit"],
            [
                Reply::fail(
                    128,
                    "fatal: Unable to create '/r/.git/index.lock': File exists.",
                ),
                Reply::ok(""),
            ],
        ));
        let git = Git::with_runner(&rec);
        assert!(git.commit(Path::new("/r"), "msg").await.is_err());
        assert_eq!(rec.calls().len(), 1, "no retry without with_retry");
    }

    // Even with retry on, a real (non-lock) failure is returned immediately — only
    // lock contention is retried, so a genuine error is never silently repeated.
    #[tokio::test]
    async fn with_retry_does_not_retry_a_real_failure() {
        let rec = RecordingRunner::new(ScriptedRunner::new().on_sequence(
            ["git", "commit"],
            [
                Reply::fail(1, "error: pathspec 'x' did not match"),
                Reply::ok(""),
            ],
        ));
        let git = Git::with_runner(&rec).with_retry(RetryPolicy::none().attempts(3));
        assert!(git.commit(Path::new("/r"), "msg").await.is_err());
        assert_eq!(rec.calls().len(), 1, "a non-lock failure is not retried");
    }

    // A non-transient failure fails fast — no retry.
    #[tokio::test]
    async fn fetch_does_not_retry_permanent_failures() {
        let rec = RecordingRunner::replying(Reply::fail(1, "fatal: couldn't find remote ref"));
        let git = Git::with_runner(&rec);
        assert!(git.fetch(Path::new("/r")).await.is_err());
        assert_eq!(rec.calls().len(), 1);
    }

    // Client-level cancellation (processkit 0.8 `cancellation` feature) on a
    // *retried* op: a `fetch` built on a client with `default_cancel_on(token)`
    // parks until the token fires, then surfaces `ErrorReason::Cancelled` — and because
    // cancellation is **terminal** (not transient), the fetch-retry does NOT
    // replay it (one spawn, not FETCH_ATTEMPTS). Hermetic via `Reply::pending()`
    // on a paused clock.
    #[tokio::test(start_paused = true)]
    async fn fetch_cancels_and_does_not_retry() {
        use processkit::CancellationToken;
        let token = CancellationToken::new();
        let rec =
            RecordingRunner::new(ScriptedRunner::new().on(["git", "fetch"], Reply::pending()));
        let git = Git::with_runner(&rec).default_cancel_on(token.clone());
        let call = git.fetch(Path::new("/r"));
        tokio::pin!(call);
        assert!(
            tokio::time::timeout(std::time::Duration::from_secs(3600), &mut call)
                .await
                .is_err(),
            "fetch must park until the token fires"
        );
        token.cancel();
        assert!(matches!(
            call.await.unwrap_err().reason(),
            ErrorReason::Cancelled { .. }
        ));
        assert_eq!(
            rec.calls().len(),
            1,
            "cancellation is terminal — the fetch-retry must not replay it"
        );
    }

    // The injection barrier now has two tiers:
    //  1. ref-name / revision inputs are validated NEWTYPES, so a flag-like or
    //     malformed value is rejected at *construction* — it can never reach an
    //     argv slot (migration tests below); and
    //  2. the remaining bare-positional `&str` inputs that are not refs/revisions
    //     (remote names, URLs, config keys) keep the internal `reject_flag_like`
    //     guard, refused before anything spawns.

    // Tier 1 — the newtypes reject the flag-like / malformed values the typed ops
    // would otherwise have received, as a classifiable invalid-input error.
    #[test]
    fn validated_ref_and_rev_newtypes_reject_bad_values() {
        // RefName: the load-bearing core of `check-ref-format`.
        for ok in ["main", "feature/x", "origin/main", "v1.2.3", "a-b_c"] {
            assert!(RefName::new(ok).is_ok(), "{ok}");
        }
        for bad in [
            "", "-evil", "--force", "-D", "-bad", ".hidden", "a..b", "a b", "a~b", "a^b", "a:b",
            "a?b", "a*b", "a[b", "a\\b", "end/", "x.lock",
        ] {
            let err = RefName::new(bad).expect_err(&format!("{bad:?} must be rejected"));
            assert!(
                vcs_cli_support::is_invalid_input(&err),
                "{bad:?} must classify as invalid input"
            );
        }
        // RevSpec: non-empty and not flag-shaped (git's revision grammar is
        // otherwise too rich to validate here), so `-` special values are refused.
        for ok in ["HEAD", "HEAD~2", "main..feature", "@{-1}", "abc123"] {
            assert!(RevSpec::new(ok).is_ok(), "{ok}");
        }
        for bad in ["", "-evil", "-i", "-n", "-s"] {
            let err = RevSpec::new(bad).expect_err(&format!("{bad:?} must be rejected"));
            assert!(vcs_cli_support::is_invalid_input(&err), "{bad:?}");
        }
    }

    // Tier 2 — the ops that still take a bare `&str` (remote names, URLs, config
    // keys) refuse a flag-like value BEFORE anything spawns. `DiffSpec::Rev` is a
    // shared cross-backend `String`, so it keeps the same internal guard.
    #[tokio::test]
    async fn str_positionals_are_rejected_before_spawning() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let dir = Path::new("/r");

        assert!(git.config_set(dir, "-evil", "v").await.is_err());
        assert!(git.config_get(dir, "-evil").await.is_err());
        assert!(git.remote_url(dir, "-evil").await.is_err());
        assert!(git.remote_branches(dir, "-evil").await.is_err());
        assert!(git.fetch_from(dir, "--upload-pack=x").await.is_err());
        assert!(git.remote_add(dir, "-evil", "url").await.is_err());
        assert!(git.remote_add(dir, "ok", "--upload-pack=x").await.is_err());
        assert!(git.remote_set_url(dir, "-evil", "url").await.is_err());
        assert!(git.remote_set_url(dir, "ok", "-evil").await.is_err());
        // A leading-`-` url is an RCE-class flag injection.
        assert!(
            git.clone_repo("--upload-pack=x", Path::new("/d"), CloneSpec::new())
                .await
                .is_err()
        );
        // `DiffSpec::Rev` carries a raw (internally-guarded) revision string.
        assert!(
            git.diff_text(dir, DiffSpec::Rev("-evil".into()))
                .await
                .is_err()
        );

        assert!(
            rec.calls().is_empty(),
            "nothing may spawn: {:?}",
            rec.calls()
        );
    }

    // A legitimate ref/revision still flows through the typed path unchanged (with
    // the trailing `--` that keeps a path-like ref out of pathspec mode — C2), and
    // git's `-` "previous branch" is carried safely as `CheckoutTarget::Previous`
    // (a fixed literal, not caller-controlled argv).
    #[tokio::test]
    async fn typed_checkout_targets_pass_through() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.checkout(Path::new("/r"), &CheckoutTarget::Ref(rv("feature/x")))
            .await
            .expect("checkout");
        assert_eq!(rec.only_call().args_str(), ["checkout", "feature/x", "--"]);

        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.checkout(Path::new("/r"), &CheckoutTarget::Previous)
            .await
            .expect("checkout -");
        assert_eq!(rec.only_call().args_str(), ["checkout", "-", "--"]);
    }

    // The hardened profile lands its env pairs/removals on EVERY command, and
    // composes with per-command env like GIT_TERMINAL_PROMPT.
    #[tokio::test]
    async fn harden_applies_env_profile_to_every_command() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec).harden();
        git.status(Path::new("/r")).await.expect("status");
        git.fetch(Path::new("/r")).await.expect("fetch");

        for call in rec.calls() {
            let has = |k: &str, v: &str| {
                call.envs.iter().any(|(key, val)| {
                    key.to_str() == Some(k) && val.as_deref().and_then(|o| o.to_str()) == Some(v)
                })
            };
            let removed = |k: &str| {
                call.envs
                    .iter()
                    .any(|(key, val)| key.to_str() == Some(k) && val.is_none())
            };
            assert!(has("GIT_CONFIG_NOSYSTEM", "1"), "{:?}", call.args_str());
            assert!(has("GIT_CONFIG_COUNT", "3"));
            assert!(has("GIT_CONFIG_KEY_0", "core.hooksPath"));
            assert!(has("GIT_CONFIG_VALUE_0", "/dev/null"));
            assert!(has("GIT_CONFIG_KEY_1", "core.fsmonitor"));
            // The repo-local core.sshCommand kill-switch (pinned empty).
            assert!(has("GIT_CONFIG_KEY_2", "core.sshCommand"));
            assert!(has("GIT_CONFIG_VALUE_2", ""));
            assert!(has("GIT_TERMINAL_PROMPT", "0"));
            assert!(removed("GIT_DIR"), "GIT_DIR scrubbed");
            assert!(removed("GIT_CONFIG_GLOBAL"), "global config scrubbed");
            // Command-hook env vectors are scrubbed too.
            assert!(removed("GIT_SSH_COMMAND"), "GIT_SSH_COMMAND scrubbed");
            assert!(removed("GIT_ASKPASS"), "GIT_ASKPASS scrubbed");
            assert!(removed("GIT_EXTERNAL_DIFF"), "GIT_EXTERNAL_DIFF scrubbed");
            assert!(removed("GIT_PAGER"), "GIT_PAGER scrubbed");
            // M14: the additional code-execution vectors + pathspec-mode vars.
            assert!(removed("GIT_PROXY_COMMAND"), "GIT_PROXY_COMMAND scrubbed");
            assert!(removed("GIT_EXEC_PATH"), "GIT_EXEC_PATH scrubbed");
            assert!(removed("GIT_TEMPLATE_DIR"), "GIT_TEMPLATE_DIR scrubbed");
            assert!(
                removed("GIT_ICASE_PATHSPECS"),
                "GIT_ICASE_PATHSPECS scrubbed"
            );
        }
    }

    // H4: EVERY git client (not just `harden()`) scrubs the repo-**redirector** env
    // vars, so a `GIT_DIR`/`GIT_INDEX_FILE` leaking from the parent (e.g. running
    // inside a git hook, which exports them) can't silently retarget a command at a
    // different repository than the bound `dir`. The command-hook scrubs and config
    // pins stay `harden()`-only.
    #[tokio::test]
    async fn default_client_scrubs_repo_redirector_env() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec); // NOT hardened
        git.status(Path::new("/r")).await.expect("status");
        let call = rec.only_call();
        let removed = |k: &str| {
            call.envs
                .iter()
                .any(|(key, val)| key.to_str() == Some(k) && val.is_none())
        };
        let has_key = |k: &str| call.envs.iter().any(|(key, _)| key.to_str() == Some(k));
        for var in [
            "GIT_DIR",
            "GIT_WORK_TREE",
            "GIT_INDEX_FILE",
            "GIT_COMMON_DIR",
            "GIT_OBJECT_DIRECTORY",
            "GIT_ALTERNATE_OBJECT_DIRECTORIES",
            "GIT_NAMESPACE",
        ] {
            assert!(removed(var), "{var} must be scrubbed on the default client");
        }
        // `harden()`-only surface is absent on a plain client.
        assert!(
            !has_key("GIT_SSH_COMMAND"),
            "command-hook scrub is harden()-only"
        );
        assert!(
            !has_key("GIT_CONFIG_NOSYSTEM"),
            "config pins are harden()-only"
        );
    }

    // RefName/RevSpec accept/reject tables.
    #[test]
    fn ref_name_and_rev_spec_validate() {
        for ok in ["main", "feature/x", "v1.2.3", "a-b_c"] {
            assert!(RefName::new(ok).is_ok(), "{ok}");
        }
        for bad in [
            "", "-evil", ".hidden", "a..b", "a b", "a~b", "a^b", "a:b", "a?b", "a*b", "a[b",
            "a\\b", "end/", "x.lock",
        ] {
            assert!(RefName::new(bad).is_err(), "{bad:?} must be rejected");
        }
        assert!(RevSpec::new("HEAD~2").is_ok());
        assert!(RevSpec::new("main..feature").is_ok());
        assert!(RevSpec::new("-evil").is_err());
        assert!(RevSpec::new("").is_err());
    }

    // capabilities parses real-world version shapes (incl. the Windows build
    // trailer) and gates on the real (2, 31) major.minor floor.
    #[tokio::test]
    async fn capabilities_parse_and_gate_versions() {
        let gh = Git::with_runner(ScriptedRunner::new().on(
            ["git", "--version"],
            Reply::ok("git version 2.54.0.windows.1\n"),
        ));
        let caps = gh.capabilities().await.expect("capabilities");
        assert_eq!(caps.version.to_string(), "2.54.0");
        assert!(caps.is_supported());
        caps.ensure_supported().expect("supported");

        // Two-part versions parse (patch defaults to 0); an ancient major fails
        // the gate with a clear message.
        let old = Git::with_runner(
            ScriptedRunner::new().on(["git", "--version"], Reply::ok("git version 1.9\n")),
        );
        let caps = old.capabilities().await.expect("capabilities");
        assert_eq!(
            caps.version,
            GitVersion {
                major: 1,
                minor: 9,
                patch: 0
            }
        );
        let err = caps.ensure_supported().expect_err("unsupported");
        // The message must name the floor and the found version.
        let ErrorReason::Spawn { source, .. } = err.reason() else {
            panic!("expected Spawn, got {err:?}");
        };
        let message = source.to_string();
        assert!(message.contains(">= 2"), "names the floor: {message}");
        assert!(
            message.contains("1.9.0"),
            "names the found version: {message}"
        );

        // M29: a 2.x git BELOW the 2.31 minor floor is now rejected too — the crate's
        // argv (harden's GIT_CONFIG_COUNT, porcelain=v2, stash push) needs ≥ 2.31, so a
        // major-only gate that passed 2.7 then failed later with a cryptic argv error.
        let mid = Git::with_runner(
            ScriptedRunner::new().on(["git", "--version"], Reply::ok("git version 2.7.4\n")),
        );
        let caps = mid.capabilities().await.expect("capabilities");
        assert!(!caps.is_supported(), "2.7.4 is below the 2.31 floor");
        let err = caps.ensure_supported().expect_err("2.7.4 unsupported");
        let ErrorReason::Spawn { source, .. } = err.reason() else {
            panic!("expected Spawn, got {err:?}");
        };
        assert!(
            source.to_string().contains(">= 2.31"),
            "names the 2.31 floor"
        );

        // Garbage output is a parse error, not a silent zero version.
        let garbage = Git::with_runner(
            ScriptedRunner::new().on(["git", "--version"], Reply::ok("not a version")),
        );
        assert!(matches!(
            garbage.capabilities().await.unwrap_err().reason(),
            ErrorReason::Parse { .. }
        ));
    }

    // clone_repo is dir-less and appends only the requested flags.
    #[tokio::test]
    async fn clone_repo_builds_flags_and_runs_dirless() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.clone_repo(
            "https://example.com/r.git",
            Path::new("/dest"),
            CloneSpec::new().branch("main").depth(1).bare(),
        )
        .await
        .expect("clone");
        let call = rec.only_call();
        assert_eq!(
            call.args_str(),
            [
                "clone",
                "--branch",
                "main",
                "--depth",
                "1",
                "--bare",
                "https://example.com/r.git",
                "/dest"
            ]
        );
        assert_eq!(call.cwd, None, "clone runs without a working directory");

        let bare = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&bare);
        git.clone_repo("u", Path::new("/d"), CloneSpec::new())
            .await
            .expect("clone");
        assert_eq!(bare.only_call().args_str(), ["clone", "u", "/d"]);
    }

    #[tokio::test]
    async fn clone_surfaces_share_typed_large_repo_flags_and_order() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let spec = CloneSpec::new()
            .branch("main")
            .depth(2)
            .filter(CloneFilter::BlobNone)
            .single_branch()
            .origin("upstream")
            .bare();
        git.clone_repo("https://example.com/r.git", Path::new("/dest"), spec)
            .await
            .expect("clone");

        let mut progress = |_event: ProcessEvent| {};
        git.clone_repo_with_progress(
            "https://example.com/r.git",
            Path::new("/dest-progress"),
            CloneSpec::new()
                .branch("main")
                .depth(2)
                .filter(CloneFilter::TreeZero)
                .single_branch()
                .origin("upstream")
                .bare(),
            &mut progress,
        )
        .await
        .expect("progress clone");

        let calls = rec.calls();
        assert_eq!(
            calls[0].args_str(),
            [
                "clone",
                "--branch",
                "main",
                "--depth",
                "2",
                "--filter=blob:none",
                "--single-branch",
                "--origin",
                "upstream",
                "--bare",
                "https://example.com/r.git",
                "/dest"
            ]
        );
        assert_eq!(
            calls[1].args_str(),
            [
                "clone",
                "--progress",
                "--branch",
                "main",
                "--depth",
                "2",
                "--filter=tree:0",
                "--single-branch",
                "--origin",
                "upstream",
                "--bare",
                "https://example.com/r.git",
                "/dest-progress"
            ]
        );
    }

    #[tokio::test]
    async fn clone_rejects_invalid_origin_before_runner_for_both_surfaces() {
        for origin in ["", " ", "--upload-pack=evil", "bad\0name"] {
            let rec = RecordingRunner::replying(Reply::ok(""));
            let git = Git::with_runner(&rec);
            let result = git
                .clone_repo(
                    "https://example.com/r.git",
                    Path::new("/dest"),
                    CloneSpec::new().origin(origin),
                )
                .await;
            assert!(matches!(
                err_reason(&result),
                Some(ErrorReason::Spawn { source, .. })
                    if source.kind() == std::io::ErrorKind::InvalidInput
            ));
            assert!(rec.calls().is_empty(), "invalid origin must not spawn");

            let rec = RecordingRunner::replying(Reply::ok(""));
            let git = Git::with_runner(&rec);
            let mut progress = |_event: ProcessEvent| {};
            let result = git
                .clone_repo_with_progress(
                    "https://example.com/r.git",
                    Path::new("/dest"),
                    CloneSpec::new().origin(origin),
                    &mut progress,
                )
                .await;
            assert!(matches!(
                err_reason(&result),
                Some(ErrorReason::Spawn { source, .. })
                    if source.kind() == std::io::ErrorKind::InvalidInput
            ));
            assert!(
                rec.calls().is_empty(),
                "invalid origin must not spawn through progress"
            );
        }
    }

    // R7: a failed clone cleans a `dest` it could have *created* (absent or empty) so
    // a retry isn't blocked by "destination already exists and is not empty" — but it
    // must NEVER delete a non-empty pre-existing dir (git would have refused, so the
    // caller's data is untouched). Scripted-fail clone + real temp dirs (only the fs
    // cleanup is real; nothing spawns).
    #[tokio::test]
    async fn clone_failure_cleans_only_a_dest_it_could_have_created() {
        use vcs_testkit::TempDir;
        let tmp = TempDir::new("r7-clone");
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "clone"],
            Reply::fail(
                128,
                "fatal: could not read Username for 'https://x': prompts disabled",
            ),
        ));

        // A non-empty caller dir must survive a failed clone.
        let occupied = tmp.path().join("occupied");
        std::fs::create_dir(&occupied).unwrap();
        std::fs::write(occupied.join("keep.txt"), b"caller data").unwrap();
        assert!(
            git.clone_repo("https://x/r", &occupied, CloneSpec::new())
                .await
                .is_err()
        );
        assert!(
            occupied.join("keep.txt").exists(),
            "a non-empty caller dir must survive a failed clone"
        );

        // An empty dest we could have populated is removed on failure.
        let empty = tmp.path().join("empty");
        std::fs::create_dir(&empty).unwrap();
        assert!(
            git.clone_repo("https://x/r", &empty, CloneSpec::new())
                .await
                .is_err()
        );
        assert!(
            !empty.exists(),
            "an empty dest is cleaned so a retry isn't blocked"
        );

        // A pre-existing FILE at `dest` must survive (read_dir errs → cleanable, but
        // remove_dir_all refuses a non-dir). Pins that a future "also remove a file"
        // change can't slip in unnoticed.
        let file_dest = tmp.path().join("a-file");
        std::fs::write(&file_dest, b"caller file").unwrap();
        assert!(
            git.clone_repo("https://x/r", &file_dest, CloneSpec::new())
                .await
                .is_err()
        );
        assert!(
            file_dest.exists() && std::fs::read(&file_dest).unwrap() == b"caller file",
            "a caller's file at dest must survive a failed clone"
        );

        // A symlink `dest` → an EMPTY dir the caller owns: `read_dir` follows the
        // link and sees empty, so `cleanable` is true and `remove_dir_all` DOES run on
        // the link — it must unlink only the symlink, never delete THROUGH it. The
        // target dir (and a sibling sentinel) must survive.
        #[cfg(unix)]
        {
            let target = tmp.path().join("link-target"); // stays empty → cleanable path
            std::fs::create_dir(&target).unwrap();
            let sentinel = tmp.path().join("sibling.txt");
            std::fs::write(&sentinel, b"untouched").unwrap();
            let link = tmp.path().join("a-symlink");
            std::os::unix::fs::symlink(&target, &link).unwrap();
            assert!(
                git.clone_repo("https://x/r", &link, CloneSpec::new())
                    .await
                    .is_err()
            );
            assert!(
                target.exists() && sentinel.exists(),
                "a failed clone must unlink at most the symlink, never delete through it"
            );
        }
    }

    #[tokio::test]
    async fn tag_methods_build_args() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.tag_create(Path::new("/r"), &rn("v1"), None)
            .await
            .unwrap();
        git.tag_create(Path::new("/r"), &rn("v1"), Some(rv("abc")))
            .await
            .unwrap();
        git.tag_create_annotated(Path::new("/r"), AnnotatedTag::new(rn("v2"), "notes"))
            .await
            .unwrap();
        git.tag_delete(Path::new("/r"), &rn("v1")).await.unwrap();
        let calls = rec.calls();
        assert_eq!(calls[0].args_str(), ["tag", "v1"]);
        assert_eq!(calls[1].args_str(), ["tag", "v1", "abc"]);
        assert_eq!(calls[2].args_str(), ["tag", "-a", "v2", "-m", "notes"]);
        assert_eq!(calls[3].args_str(), ["tag", "-d", "v1"]);
    }

    #[tokio::test]
    async fn tag_list_splits_lines() {
        let git = Git::with_runner(
            ScriptedRunner::new().on(["git", "tag", "--list"], Reply::ok("v1\nv2.0\n")),
        );
        assert_eq!(git.tag_list(Path::new(".")).await.unwrap(), ["v1", "v2.0"]);
    }

    // The line-parsed list commands must pass `--no-column`: a user's
    // `column.ui = always` would pack several names per line, and
    // `color.{ui,branch} = always` would inject ANSI escapes — both even when
    // piped. Branch listings disable both; `git tag` isn't colorized, so it only
    // needs `--no-column`.
    #[tokio::test]
    async fn list_commands_disable_column_and_color() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.branches(Path::new(".")).await.unwrap();
        git.is_merged(
            Path::new("."),
            MergeCheck::branch(rn("b")).into_base(rv("main")),
        )
        .await
        .unwrap();
        git.tag_list(Path::new(".")).await.unwrap();
        let calls = rec.calls();
        assert_eq!(calls[0].args_str(), ["branch", "--no-column", "--no-color"]);
        assert_eq!(
            calls[1].args_str(),
            ["branch", "--merged", "main", "--no-column", "--no-color"]
        );
        assert_eq!(calls[2].args_str(), ["tag", "--list", "--no-column"]);
    }

    // Commands whose failure output feeds the error classifiers must force the
    // C locale — a translated message would defeat the substring matching.
    #[tokio::test]
    async fn classified_commands_force_c_locale() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.commit(Path::new("."), "msg").await.unwrap();
        git.merge_commit(Path::new("."), MergeCommit::branch(rv("b")))
            .await
            .unwrap();
        git.merge_squash(Path::new("."), &rv("b")).await.unwrap();
        git.merge_no_commit(Path::new("."), MergeNoCommit::branch(rv("b")))
            .await
            .unwrap();
        git.cherry_pick(Path::new("."), &rv("abc")).await.unwrap();
        git.stash_pop(Path::new(".")).await.unwrap();
        git.fetch(Path::new(".")).await.unwrap();
        for call in rec.calls() {
            assert!(
                call.envs.iter().any(|(k, v)| {
                    k.to_str() == Some("LC_ALL")
                        && v.as_deref().and_then(|o| o.to_str()) == Some("C")
                }),
                "{:?} should force LC_ALL=C",
                call.args_str()
            );
        }
    }

    // `merge_abort_detached` is the rollback-cleanup abort the facade's `try_merge`
    // uses: it emits the same `merge --abort` as `merge_abort`, but on a FRESH
    // cancel token, so an already-fired client `default_cancel_on` (a cancelled or
    // timed-out probe merge) cannot also cancel the cleanup. The bare `merge_abort`
    // on the same client IS cancelled — proving the fired token is genuinely live
    // and the detached path deliberately steps around it, not that the token is
    // inert. The git mirror of jj's `rollback_to_survives_fired_cancellation`.
    #[tokio::test]
    async fn merge_abort_detached_survives_fired_cancellation() {
        use processkit::CancellationToken;
        let token = CancellationToken::new();
        token.cancel(); // as a cancelled/deadline-hit probe merge would leave it
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec).default_cancel_on(token);
        let dir = Path::new("/r");

        git.merge_abort_detached(dir)
            .await
            .expect("the detached cleanup must run despite the fired client token");
        assert_eq!(rec.only_call().args_str(), ["merge", "--abort"]);

        // Sanity: the token-inheriting `merge_abort` on the same (fired) client IS
        // cancelled, so the detached path really did side-step a live token.
        let bare = git.merge_abort(dir).await;
        assert!(
            matches!(err_reason(&bare), Some(ErrorReason::Cancelled { .. })),
            "a bare merge_abort must inherit the fired token: {bare:?}"
        );
    }

    // `is_merge_in_progress_detached` is the rollback-cleanup DECISION probe the
    // facade's `try_merge` gates its abort on: it answers "is a trial merge still
    // staged?" via `rev-parse --git-dir` on a FRESH cancel token, so an
    // already-fired client `default_cancel_on` (a cancelled/timed-out probe merge)
    // cannot short-circuit the decision and thereby skip the abort. The bare
    // token-inheriting `is_merge_in_progress` on the same client IS cancelled —
    // proving the fired token is live and the detached probe deliberately steps
    // around it. Pairs with `merge_abort_detached_survives_fired_cancellation`: both
    // halves of the git cleanup survive, matching jj's op-log-probe-plus-restore.
    #[tokio::test]
    async fn is_merge_in_progress_detached_survives_fired_cancellation() {
        use processkit::CancellationToken;
        use vcs_testkit::TempDir;
        let gd = TempDir::new("merge-in-progress-detached");
        std::fs::write(gd.path().join("MERGE_HEAD"), "deadbeef\n").unwrap();
        let token = CancellationToken::new();
        token.cancel(); // as a cancelled/deadline-hit probe merge would leave it
        let git = Git::with_runner(ScriptedRunner::new().on(
            ["git", "rev-parse", "--git-dir"],
            Reply::ok(gd.path().to_str().unwrap()),
        ))
        .default_cancel_on(token);
        let dir = Path::new("/r");

        assert!(
            git.is_merge_in_progress_detached(dir)
                .await
                .expect("the detached probe must resolve the git dir despite the fired token"),
            "MERGE_HEAD exists, so the detached probe must report a merge in progress"
        );

        // Sanity: the token-inheriting `is_merge_in_progress` on the same (fired)
        // client IS cancelled, so the detached probe really did side-step a live
        // token rather than the token being inert.
        let bare = git.is_merge_in_progress(dir).await;
        assert!(
            matches!(err_reason(&bare), Some(ErrorReason::Cancelled { .. })),
            "a bare is_merge_in_progress must inherit the fired token: {bare:?}"
        );
    }

    // T-149: an empty / whitespace-only `path` is refused BEFORE `git show`
    // spawns. `git show <rev>:` is not an error — git prints the root TREE
    // LISTING and exits 0 (verified on git 2.55.0), so without this guard the
    // read hands back a directory index as if it were a file's content. The
    // runner is scripted to reply with exactly that listing, so a regression
    // fails on the returned value, not merely on the missing error.
    #[tokio::test]
    async fn show_file_rejects_empty_path_before_spawn() {
        for path in ["", " ", "   ", "\t", "\n", " \t \n "] {
            let rec = RecordingRunner::replying(Reply::ok("tree HEAD:\n\nf.txt\nsub/\n"));
            let git = Git::with_runner(&rec);

            let err = git
                .show_file(Path::new("/r"), &rv("HEAD"), path)
                .await
                .expect_err(&format!("show_file must refuse {path:?}"));
            assert!(
                vcs_cli_support::is_invalid_input(&err),
                "{path:?} must classify as invalid input: {err:?}"
            );
            assert!(
                err.to_string().contains("empty or whitespace-only"),
                "the refusal names the cause: {err}"
            );

            // The budgeted entry point is the one carrying the guard; the
            // per-call override must not be a way around it.
            let err = git
                .show_file_within(
                    Path::new("/r"),
                    &rv("HEAD"),
                    path,
                    OutputBudget::unlimited(),
                )
                .await
                .expect_err(&format!("show_file_within must refuse {path:?}"));
            assert!(
                vcs_cli_support::is_invalid_input(&err),
                "{path:?} must classify as invalid input: {err:?}"
            );

            assert!(
                rec.calls().is_empty(),
                "nothing may spawn for {path:?}: {:?}",
                rec.calls()
            );
        }
    }

    // The guard rejects *emptiness*, not a leading dash or interior whitespace:
    // a `-dash.txt` is inert inside the `<rev>:<path>` spec, and a name that
    // merely contains (or is padded by) spaces is a legitimate file.
    #[tokio::test]
    async fn show_file_accepts_dash_leading_and_space_bearing_paths() {
        for path in ["-dash.txt", "--force", "a b.txt", " padded.txt "] {
            let rec = RecordingRunner::replying(Reply::ok("content\n"));
            let git = Git::with_runner(&rec);
            git.show_file(Path::new("/r"), &rv("HEAD"), path)
                .await
                .unwrap_or_else(|e| panic!("{path:?} must be accepted: {e:?}"));
            let spec = format!("HEAD:{path}");
            assert_eq!(rec.only_call().args_str(), ["show", spec.as_str()]);
        }
    }

    // The `<rev>:<path>` spec requires forward slashes — Windows callers may
    // hand in backslashes. The normalisation is Windows-only.
    #[cfg(windows)]
    #[tokio::test]
    async fn show_file_normalises_path_separators() {
        let rec = RecordingRunner::replying(Reply::ok("content\n"));
        let git = Git::with_runner(&rec);
        let out = git
            .show_file(Path::new("/r"), &rv("HEAD"), "sub\\dir\\f.txt")
            .await
            .expect("show_file");
        // The blob's trailing newline is preserved verbatim (H7) — not trimmed.
        assert_eq!(out, "content\n");
        assert_eq!(rec.only_call().args_str(), ["show", "HEAD:sub/dir/f.txt"]);
    }

    // H7: content verbs return git's output byte-for-byte — the round-trip-corrupting
    // cases are multiple trailing newlines and a missing final newline.
    #[tokio::test]
    async fn content_verbs_preserve_exact_trailing_bytes() {
        for raw in ["a\nb\n\n", "no-final-newline", "trailing spaces   \n"] {
            let rec = RecordingRunner::replying(Reply::ok(raw));
            let git = Git::with_runner(&rec);
            let out = git
                .show_file(Path::new("/r"), &rv("HEAD"), "f.txt")
                .await
                .expect("show_file");
            assert_eq!(out, raw, "show_file returns bytes verbatim");
        }
        // diff_text is verbatim too (its trailing blank context line must survive so
        // the last hunk stays in sync with its `@@` count).
        let diff = "diff --git a/f b/f\n@@ -1,2 +1,2 @@\n-x\n+y\n \n";
        let rec = RecordingRunner::replying(Reply::ok(diff));
        let git = Git::with_runner(&rec);
        assert_eq!(
            git.diff_text(Path::new("/r"), DiffSpec::Rev("HEAD".into()))
                .await
                .expect("diff_text"),
            diff
        );
    }

    // On Unix a backslash is a legal filename byte — the spec must pass through
    // verbatim so a literal `a\b.txt` stays resolvable.
    #[cfg(not(windows))]
    #[tokio::test]
    async fn show_file_keeps_backslashes_on_unix() {
        let rec = RecordingRunner::replying(Reply::ok("content\n"));
        let git = Git::with_runner(&rec);
        git.show_file(Path::new("/r"), &rv("HEAD"), "sub\\dir\\f.txt")
            .await
            .expect("show_file");
        assert_eq!(rec.only_call().args_str(), ["show", "HEAD:sub\\dir\\f.txt"]);
    }

    // T-049: a content read (`diff_text`) whose output exceeds the client's default
    // OutputBudget is refused with a structured `OutputTooLarge` carrying the actual
    // (`total_bytes`) and allowed (`max_bytes`) sizes — never a silently truncated
    // diff handed back as if complete. The huge output is drained but NOT retained
    // (the error carries only counts, not the multi-KiB blob): the bounded-memory
    // contract.
    // T-130: audited against processkit 3.0's raw-pipe-byte accounting and kept as
    // is. A content read captures RAW stdout, whose byte accounting 3.0 did not
    // change (only the line-pumped streams were re-based), and the fixture is ~2x
    // the ceiling under either unit — so this still asserts the contract it states
    // rather than passing on a coincidence. The exact boundary, and the stderr
    // stream that DID shift, are pinned in `vcs_cli_support`'s `content_budget_*`
    // tests; see `OutputBudget::bytes` for the per-stream unit.
    #[tokio::test]
    async fn diff_text_over_budget_errors_output_too_large() {
        let big = "diff --git a/f b/f\n".to_string() + &"+padding line\n".repeat(10_000);
        assert!(big.len() > 64 * 1024, "fixture must exceed the budget");
        let git = Git::with_runner(ScriptedRunner::new().on(["git", "diff"], Reply::ok(&big)))
            .default_output_budget(OutputBudget::bytes(64 * 1024));
        match git
            .diff_text(Path::new("/r"), DiffSpec::Rev("HEAD".into()))
            .await
            .map_err(Error::into_reason)
        {
            Err(ErrorReason::OutputTooLarge {
                program,
                max_bytes,
                total_bytes,
                ..
            }) => {
                assert_eq!(program, "git");
                assert_eq!(max_bytes, Some(64 * 1024), "the allowed ceiling");
                assert!(
                    total_bytes > 64 * 1024,
                    "the actual size ({total_bytes}) exceeds the allowed cap"
                );
            }
            other => panic!("expected OutputTooLarge, got {other:?}"),
        }
    }

    // Below the budget the full diff comes back verbatim — the ceiling only fires on
    // an over-cap read, so ordinary diffs are unaffected.
    #[tokio::test]
    async fn diff_text_under_budget_returns_full_output() {
        let diff = "diff --git a/f b/f\n@@ -1,2 +1,2 @@\n-x\n+y\n \n";
        let git = Git::with_runner(ScriptedRunner::new().on(["git", "diff"], Reply::ok(diff)))
            .default_output_budget(OutputBudget::bytes(64 * 1024));
        assert_eq!(
            git.diff_text(Path::new("/r"), DiffSpec::Rev("HEAD".into()))
                .await
                .expect("under-budget diff_text"),
            diff
        );
    }

    // The per-call override reads a legitimately large diff past a tight client
    // default: `diff_text_within(..., unlimited())` returns the full output the
    // default budget would have refused.
    #[tokio::test]
    async fn diff_text_within_override_reads_past_the_default() {
        let big = "diff --git a/f b/f\n".to_string() + &"+padding line\n".repeat(10_000);
        let git = Git::with_runner(ScriptedRunner::new().on(["git", "diff"], Reply::ok(&big)))
            .default_output_budget(OutputBudget::bytes(64 * 1024));
        // The default budget would refuse it…
        assert!(matches!(
            err_reason(
                &git.diff_text(Path::new("/r"), DiffSpec::Rev("HEAD".into()))
                    .await
            ),
            Some(ErrorReason::OutputTooLarge { .. })
        ));
        // …but an explicit unlimited override reads it in full.
        let got = git
            .diff_text_within(
                Path::new("/r"),
                DiffSpec::Rev("HEAD".into()),
                OutputBudget::unlimited(),
            )
            .await
            .expect("override reads the large diff");
        assert_eq!(got, big);
    }

    #[tokio::test]
    async fn diff_text_between_within_honours_output_budget() {
        let from = rv("base");
        let to = rv("tip");
        let big = "diff --git a/f b/f\n".to_string() + &"+padding line\n".repeat(10_000);
        let git = Git::with_runner(ScriptedRunner::new().on(["git", "diff"], Reply::ok(&big)))
            .default_output_budget(OutputBudget::bytes(64 * 1024));
        assert!(matches!(
            err_reason(&git.diff_text_between(Path::new("/r"), &from, &to).await),
            Some(ErrorReason::OutputTooLarge { .. })
        ));

        let got = git
            .diff_text_between_within(Path::new("/r"), &from, &to, OutputBudget::unlimited())
            .await
            .expect("unlimited override reads the large diff");
        assert_eq!(got, big);
    }

    // A blob read (`show_file`) honours the same budget and its per-call override.
    #[tokio::test]
    async fn show_file_over_budget_errors_and_override_reads() {
        let big = "x".repeat(200_000);
        let git = Git::with_runner(ScriptedRunner::new().on(["git", "show"], Reply::ok(&big)))
            .default_output_budget(OutputBudget::bytes(64 * 1024));
        assert!(matches!(
            err_reason(&git.show_file(Path::new("/r"), &rv("HEAD"), "big.bin").await),
            Some(ErrorReason::OutputTooLarge { .. })
        ));
        let got = git
            .show_file_within(
                Path::new("/r"),
                &rv("HEAD"),
                "big.bin",
                OutputBudget::unlimited(),
            )
            .await
            .expect("override reads the large blob");
        assert_eq!(got, big);
    }

    // A client with no budget set keeps the pre-budget behaviour: even a huge diff
    // is returned in full (the default is unlimited, never `OutputTooLarge`).
    #[tokio::test]
    async fn default_client_has_no_budget() {
        let big = "diff --git a/f b/f\n".to_string() + &"+padding line\n".repeat(10_000);
        let git = Git::with_runner(ScriptedRunner::new().on(["git", "diff"], Reply::ok(&big)));
        assert_eq!(
            git.diff_text(Path::new("/r"), DiffSpec::Rev("HEAD".into()))
                .await
                .expect("unbudgeted client returns the full diff"),
            big
        );
    }

    // config --get: exit 0 → Some(value), exit 1 → None (unset), other → error.
    #[tokio::test]
    async fn config_get_maps_exit_codes() {
        let set = Git::with_runner(
            ScriptedRunner::new().on(["git", "config", "--get"], Reply::ok("Alice\n")),
        );
        assert_eq!(
            set.config_get(Path::new("."), "user.name").await.unwrap(),
            Some("Alice".to_string())
        );
        // Only git's trailing newline (here `\r\n`) is stripped — a value's own
        // trailing spaces are preserved (they can be meaningful).
        let spaced = Git::with_runner(
            ScriptedRunner::new().on(["git", "config", "--get"], Reply::ok("prefix:  \r\n")),
        );
        assert_eq!(
            spaced.config_get(Path::new("."), "x.y").await.unwrap(),
            Some("prefix:  ".to_string())
        );
        let unset = Git::with_runner(
            ScriptedRunner::new().on(["git", "config", "--get"], Reply::fail(1, "")),
        );
        assert_eq!(
            unset.config_get(Path::new("."), "user.name").await.unwrap(),
            None
        );
        // A multi-valued key (exit 2) or worse is a real error.
        let multi = Git::with_runner(ScriptedRunner::new().on(
            ["git", "config", "--get"],
            Reply::fail(2, "multiple values"),
        ));
        assert!(
            multi
                .config_get(Path::new("."), "remote.all")
                .await
                .is_err()
        );
    }

    // T-083: `config_set` pins `key` and `value` behind a `--` option terminator,
    // so a `value` shaped like a flag (`--global`, `--file=<path>`) sits in argv
    // where git can only read it as a positional value — never as an option
    // redirecting the write to another config file. The exact argv is pinned here;
    // `repo.rs`'s round-trip re-checks the effect on the live git binary.
    #[tokio::test]
    async fn config_set_pins_value_behind_option_terminator() {
        // A flag-shaped value must land *after* `--`, verbatim.
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.config_set(Path::new("/r"), "user.name", "--file=/etc/evil")
            .await
            .unwrap();
        assert_eq!(
            rec.only_call().args_str(),
            ["config", "--", "user.name", "--file=/etc/evil"],
            "value must sit after `--`, unreachable to git's option parser"
        );

        // A legitimately `-`-leading value is passed through untouched — the guard
        // blocks the flag *parse*, not the leading dash, so `-1` is not rejected.
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.config_set(Path::new("/r"), "gc.auto", "-1")
            .await
            .unwrap();
        assert_eq!(
            rec.only_call().args_str(),
            ["config", "--", "gc.auto", "-1"]
        );
    }

    #[tokio::test]
    async fn blame_builds_rev_before_pathspec_separator() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.blame(Path::new("/r"), "src/lib.rs", Some(rv("HEAD~1")))
            .await
            .unwrap();
        git.blame(Path::new("/r"), "src/lib.rs", None)
            .await
            .unwrap();
        let calls = rec.calls();
        assert_eq!(
            calls[0].args_str(),
            ["blame", "--line-porcelain", "HEAD~1", "--", "src/lib.rs"]
        );
        assert_eq!(
            calls[1].args_str(),
            ["blame", "--line-porcelain", "--", "src/lib.rs"]
        );
    }

    // revert must never open an editor: --no-edit plus the env backstop.
    #[tokio::test]
    async fn sequencer_methods_suppress_editors() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.revert(Path::new("/r"), &rv("abc")).await.unwrap();
        git.cherry_pick(Path::new("/r"), &rv("abc")).await.unwrap();
        git.rebase_skip(Path::new("/r")).await.unwrap();
        let calls = rec.calls();
        assert_eq!(calls[0].args_str(), ["revert", "--no-edit", "abc"]);
        assert_eq!(calls[1].args_str(), ["cherry-pick", "abc"]);
        assert_eq!(calls[2].args_str(), ["rebase", "--skip"]);
        for call in &calls {
            assert!(
                call.envs
                    .iter()
                    .any(|(k, _)| k.to_str() == Some("GIT_EDITOR")),
                "editor suppressed on {:?}",
                call.args_str()
            );
        }
    }

    // T-044: each sequencer abort/continue/reset issues its OWN git subcommand, and
    // the two `--continue` variants (which can re-open the commit-message editor)
    // suppress it so a headless caller never hangs.
    #[tokio::test]
    async fn sequencer_abort_continue_reset_commands() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let d = Path::new("/r");
        git.cherry_pick_abort(d).await.unwrap();
        git.cherry_pick_continue(d).await.unwrap();
        git.revert_abort(d).await.unwrap();
        git.revert_continue(d).await.unwrap();
        git.bisect_reset(d).await.unwrap();
        let calls = rec.calls();
        assert_eq!(calls[0].args_str(), ["cherry-pick", "--abort"]);
        assert_eq!(calls[1].args_str(), ["cherry-pick", "--continue"]);
        assert_eq!(calls[2].args_str(), ["revert", "--abort"]);
        assert_eq!(calls[3].args_str(), ["revert", "--continue"]);
        assert_eq!(calls[4].args_str(), ["bisect", "reset"]);
        // Only the `--continue` commits can prompt an editor; those must suppress it.
        let has_editor = |idx: usize| {
            calls[idx]
                .envs
                .iter()
                .any(|(k, _)| k.to_str() == Some("GIT_EDITOR"))
        };
        assert!(has_editor(1), "cherry-pick --continue suppresses editor");
        assert!(has_editor(3), "revert --continue suppresses editor");
    }

    // T-065: `git am` gets both drivers — `am --abort` and `am --continue`. The
    // continue re-applies the resolved patch and may prompt to confirm the message,
    // so it suppresses the editor like the other sequencer `--continue`s; the abort
    // does not prompt, so it does not.
    #[tokio::test]
    async fn am_abort_and_continue_commands() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        let d = Path::new("/r");
        git.am_abort(d).await.unwrap();
        git.am_continue(d).await.unwrap();
        let calls = rec.calls();
        assert_eq!(calls[0].args_str(), ["am", "--abort"]);
        assert_eq!(calls[1].args_str(), ["am", "--continue"]);
        let has_editor = |idx: usize| {
            calls[idx]
                .envs
                .iter()
                .any(|(k, _)| k.to_str() == Some("GIT_EDITOR"))
        };
        assert!(
            !has_editor(0),
            "am --abort does not prompt, no editor override"
        );
        assert!(has_editor(1), "am --continue suppresses editor");
    }

    // harden() scrubs GIT_EDITOR/GIT_SEQUENCE_EDITOR from the inherited
    // environment, but a sequencer command sets its own `GIT_EDITOR=true` per call
    // (no_editor). `command_in` applies the client-level removal eagerly, so the env
    // list ends up `[…, (GIT_EDITOR, None), …, (GIT_EDITOR, "true")]` — and at spawn
    // each op is applied in order (processkit's `Command` does `env_remove` then
    // `env`), so the LAST write wins. The effective value MUST be `true`, else a
    // hardened `revert`/`cherry-pick`/`rebase` would lose its no-op editor and hang
    // a headless caller. Pin that effective-precedence (fold in spawn order).
    #[tokio::test]
    async fn hardened_sequencer_keeps_its_no_op_editor() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec).harden();
        git.revert(Path::new("/r"), &rv("abc")).await.unwrap();
        let call = rec.only_call();
        // Resolve each editor var the way the OS does: last op for the key wins.
        let effective = |var: &str| {
            call.envs
                .iter()
                .rfind(|(k, _)| k.to_str() == Some(var))
                .and_then(|(_, v)| v.as_deref())
                .and_then(|v| v.to_str())
        };
        // Both no-op editors must survive harden()'s scrub (symmetric precedence),
        // else a hardened sequencer command hangs a headless caller.
        assert_eq!(
            effective("GIT_EDITOR"),
            Some("true"),
            "the per-command no-op editor must survive harden()'s scrub"
        );
        assert_eq!(
            effective("GIT_SEQUENCE_EDITOR"),
            Some("true"),
            "the per-command no-op sequence editor must survive harden()'s scrub"
        );
    }

    #[tokio::test]
    async fn remote_add_and_set_url_build_args() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.remote_add(Path::new("/r"), "up", "https://x/y.git")
            .await
            .unwrap();
        git.remote_set_url(Path::new("/r"), "up", "https://x/z.git")
            .await
            .unwrap();
        let calls = rec.calls();
        assert_eq!(
            calls[0].args_str(),
            ["remote", "add", "up", "https://x/y.git"]
        );
        assert_eq!(
            calls[1].args_str(),
            ["remote", "set-url", "up", "https://x/z.git"]
        );
    }

    // Dirty tree that stashes: status → list(before) → push → list(after, deeper) →
    // checkout → pop --index, in that order.
    #[tokio::test]
    async fn switch_with_stash_round_trips_dirty_tree() {
        let rec = RecordingRunner::new(
            ScriptedRunner::new()
                .on(["git", "status"], Reply::ok(" M a.rs\0"))
                // Stash-list depth goes 0 → 1, so the push is known to have saved.
                .on_sequence(
                    ["git", "stash", "list"],
                    [Reply::ok(""), Reply::ok("stash@{0}: WIP on main\n")],
                )
                .on(["git", "stash", "push"], Reply::ok(""))
                .on(["git", "checkout"], Reply::ok(""))
                .on(["git", "stash", "pop"], Reply::ok("")),
        );
        let git = Git::with_runner(&rec);
        git.switch_with_stash(Path::new("/r"), &ct("feature"))
            .await
            .expect("switch");
        let calls = rec.calls();
        assert_eq!(calls.len(), 6);
        assert_eq!(
            calls[2].args_str(),
            ["stash", "push", "--include-untracked"]
        );
        assert_eq!(calls[4].args_str(), ["checkout", "feature", "--"]);
        // `--index` restores the staged/unstaged split (M12).
        assert_eq!(calls[5].args_str(), ["stash", "pop", "--index"]);
    }

    // M12: a dirty tree whose dirt `stash push` can't save (e.g. a submodule-only
    // change) — the stash-list depth is unchanged, so we must NOT pop an unrelated
    // pre-existing stash. Switch as-is.
    #[tokio::test]
    async fn switch_with_stash_does_not_pop_when_push_saved_nothing() {
        let rec = RecordingRunner::new(
            ScriptedRunner::new()
                .on(["git", "status"], Reply::ok(" M sub\0"))
                // Depth stays 1 across the push → nothing was actually stashed.
                .on(
                    ["git", "stash", "list"],
                    Reply::ok("stash@{0}: someone else's WIP\n"),
                )
                .on(
                    ["git", "stash", "push"],
                    Reply::ok("No local changes to save\n"),
                )
                .on(["git", "checkout"], Reply::ok("")),
        );
        let git = Git::with_runner(&rec);
        git.switch_with_stash(Path::new("/r"), &ct("feature"))
            .await
            .expect("switch");
        assert!(
            rec.calls()
                .iter()
                .all(|c| c.args_str() != ["stash", "pop", "--index"]
                    && c.args_str() != ["stash", "pop"]),
            "must not pop an unrelated stash when the push saved nothing"
        );
    }

    // A clean tree skips the stash round-trip — a no-op `stash push` would make
    // the later pop grab an older, unrelated stash.
    #[tokio::test]
    async fn switch_with_stash_skips_stash_on_clean_tree() {
        let rec = RecordingRunner::new(
            ScriptedRunner::new()
                .on(["git", "status"], Reply::ok(""))
                .on(["git", "checkout"], Reply::ok("")),
        );
        let git = Git::with_runner(&rec);
        git.switch_with_stash(Path::new("/r"), &ct("feature"))
            .await
            .expect("switch");
        let calls = rec.calls();
        assert_eq!(calls.len(), 2);
        assert!(calls.iter().all(|c| c.args_str()[0] != "stash"));
    }

    // A failed checkout pops the stash back (we are still on the original
    // branch) and surfaces the checkout error.
    #[tokio::test]
    async fn switch_with_stash_restores_on_checkout_failure() {
        let rec = RecordingRunner::new(
            ScriptedRunner::new()
                .on(["git", "status"], Reply::ok(" M a.rs\0"))
                .on_sequence(
                    ["git", "stash", "list"],
                    [Reply::ok(""), Reply::ok("stash@{0}: WIP on main\n")],
                )
                .on(["git", "stash", "push"], Reply::ok(""))
                .on(
                    ["git", "checkout"],
                    Reply::fail(1, "error: pathspec 'nope'"),
                )
                .on(["git", "stash", "pop"], Reply::ok("")),
        );
        let git = Git::with_runner(&rec);
        let err = git
            .switch_with_stash(Path::new("/r"), &ct("nope"))
            .await
            .expect_err("checkout error must surface");
        assert!(matches!(err.reason(), ErrorReason::Exit { .. }));
        let calls = rec.calls();
        assert_eq!(
            calls.last().unwrap().args_str(),
            ["stash", "pop", "--index"],
            "restoring pop ran with --index"
        );
    }

    // `fetch_from` names the remote, keeps the prompt off, and shares the
    // transient retry.
    #[tokio::test]
    async fn fetch_from_builds_args_and_retries() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);
        git.fetch_from(Path::new("/r"), "upstream")
            .await
            .expect("fetch_from");
        let call = rec.only_call();
        assert_eq!(call.args_str(), ["fetch", "--quiet", "upstream"]);
        assert!(call.envs.iter().any(|(k, v)| {
            k.to_str() == Some("GIT_TERMINAL_PROMPT")
                && v.as_deref().and_then(|o| o.to_str()) == Some("0")
        }));

        let failing = RecordingRunner::replying(Reply::fail(128, "fatal: Connection timed out"));
        let git = Git::with_runner(&failing);
        assert!(git.fetch_from(Path::new("/r"), "upstream").await.is_err());
        assert_eq!(failing.calls().len(), FETCH_ATTEMPTS as usize);
    }

    // As with `remote_branch_exists`, the names `fetch_branch` must exclude are now
    // refused at `RefName` construction, before the refspec is ever built.
    #[test]
    fn fetch_branch_invalid_names_rejected_at_refname() {
        for branch in [
            "",
            "feature/*",
            "feature/?",
            "feature/[a]",
            "a:b",
            "two words",
            "bad\tname",
        ] {
            let err = RefName::new(branch).expect_err("invalid fetch branch name must be rejected");
            assert!(vcs_cli_support::is_invalid_input(&err), "{branch:?}");
        }
    }

    #[tokio::test]
    async fn fetch_branch_accepts_valid_names() {
        let rec = RecordingRunner::replying(Reply::ok(""));
        let git = Git::with_runner(&rec);

        git.fetch_branch(Path::new("/repo"), &rn("feature/T-010_fix"))
            .await
            .expect("valid fetch branch name");
        assert_eq!(
            rec.only_call().args_str(),
            [
                "fetch",
                "--quiet",
                "origin",
                "refs/heads/feature/T-010_fix:refs/remotes/origin/feature/T-010_fix"
            ]
        );
    }

    // The consumer-facing mock seam: a function depending on `&dyn GitApi` is
    // tested with a generated mock.
    #[cfg(feature = "mock")]
    #[tokio::test]
    async fn consumer_mocks_the_interface() {
        async fn on_branch(git: &dyn GitApi, want: &str) -> bool {
            git.current_branch(Path::new(".")).await.unwrap().as_deref() == Some(want)
        }
        let mut mock = MockGitApi::new();
        mock.expect_current_branch()
            .returning(|_| Ok(Some("main".to_string())));
        assert!(on_branch(&mock, "main").await);

        let from = rv("base");
        let to = rv("tip");
        mock.expect_diff_text_between()
            .returning(|_, _, _| Ok(String::new()));
        assert!(
            mock.diff_text_between(Path::new("."), &from, &to)
                .await
                .is_ok()
        );
    }
}

// Long-form how-to guides, rendered from this crate's docs/*.md on docs.rs.
#[doc = include_str!("../docs/git.md")]
#[allow(rustdoc::broken_intra_doc_links)]
pub mod guide {
    #[doc = include_str!("../docs/security.md")]
    #[allow(rustdoc::broken_intra_doc_links)]
    pub mod security {}
    #[doc = include_str!("../docs/conflicts.md")]
    #[allow(rustdoc::broken_intra_doc_links)]
    pub mod conflicts {}
}