Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

169 KB
Raw Blame
//! Cross-platform shell execution
//!
//! Provides a unified interface for executing shell commands across platforms:
//! - Unix: Uses `sh -c` (resolved via PATH)
//! - Windows: Uses Git Bash (requires Git for Windows)
//!
//! This enables hooks and commands to use the same bash syntax on all platforms.
//! On Windows, Git for Windows must be installed — this is nearly universal among
//! Windows developers since git itself is required.
//!
//! ## Spawning children
//!
//! Worktrunk's command spawns use [`spawn`] or [`spawn_shared_child`]. Their
//! Unix process owner receives INT/TERM and runs process creation and foreground
//! admission on the same thread. [`init_startup`] establishes that owner before
//! application threads exist; workers inherit blocked signals, while the owner
//! and its children retain the caller's original mask. Requests serialize
//! creation, never child waits, so children still execute concurrently.
//!
//! On macOS, the standard library creates pipes and sockets before marking them
//! close-on-exec. A separate lock serializes descriptor setup with raw spawns,
//! preventing children from retaining unrelated output or wake endpoints. That
//! lock is never held while a caller waits for the process owner.
//!
//! ## Process groups and signal handling (Unix, `Cmd::stream`)
//!
//! Foreground children share the caller's process group, including concurrent
//! hooks with piped output and closed stdin. Group membership is independent
//! of input allocation: programs may still open `/dev/tty` for terminal control.
//! The shell owns the foreground job and the kernel delivers Ctrl-C, Ctrl-Z
//! and hangup to it. No terminal handoff or private foreground group is needed.
//!
//! [`Cmd::forward_signals`] observes direct exit while waiting. A terminal
//! Ctrl-C that wt itself receives meanwhile cancels the command once the child
//! exits, whatever status the child chose; [`Cmd::hand_off_terminal`] leaves
//! the key to a final interactive child instead (see [`TerminalInterrupt`]).
//! SIGTERM addressed only to wt is forwarded
//! to owned direct children and cancels the command. Child signal exits propagate
//! through `WorktrunkError::ChildProcessExited` to stop foreground loops.
//! Detached background commands and timeout-bounded captures have separate
//! ownership: those commands may create a private group for tree cancellation.
//!
//! ## Cancelling background children
//!
//! `wt` exiting ends its own threads but not the children they spawned, which
//! keep running as orphans. [`cancel_background_commands`] lets the foreground
//! thread stop that work — both what is running and what has yet to start —
//! once nobody is left to read its results.
//!
//! ## Timed waits
//!
//! [`wait_shared_child`] is the canonical wait for shared child handles. macOS
//! kernel exit events avoid SharedChild's stop-sensitive `waitid` path while
//! retaining its synchronized reaping and PID-safe signal delivery. Other
//! platforms use SharedChild's native waits and deadlines. macOS waits do not
//! change SIGCHLD dispositions or masks, including when a deadline expires.
//! Foreground waits publish native INT/TERM to current foreground scopes.
//! Captures and pagers do not publish cancellation themselves; command consumers
//! decide whether to propagate their typed failures to the foreground operation.
//!
//! **Why not `wait-timeout`.** wt used it until #3856. Its `SIGCHLD` handler
//! pokes an `AF_UNIX` socketpair with `send()` and `panic!`s on any errno but
//! `WouldBlock`; the handler is `extern "C"`, so that panic cannot unwind and
//! goes straight to `abort()`. Under a sandbox that denies the send (the Codex
//! CLI's `workspace-write` mode) every timed wait in wt became an uncatchable
//! `SIGABRT` with no diagnostic. `shared_child` reaches the same signal through
//! `signal_hook`, whose wake deliberately discards write errors — a missed
//! wakeup costs at worst a wait that runs to its deadline, which is what a
//! deadline is for. It also probes the wake fd and falls back to `write()` on a
//! pipe, so the syscall that sandbox denies is not even on the path.
//!
//! **When a timed wait fails.** A wall-clock deadline failure retires the
//! owned child. An advisory output-delay failure switches to streaming and
//! retries the canonical wait; if that wait also fails, it retires the child
//! before joining output readers and returns the underlying error.

use std::collections::BTreeSet;
use std::ffi::{OsStr, OsString};
use std::fs::Metadata;
use std::io::{BufRead, BufReader, ErrorKind, Read, Seek, Write};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use std::time::{Duration, Instant};

use anyhow::Context;
use shared_child::SharedChild;

use crate::git::WorktrunkError;
use crate::path::format_path_for_display;
use crate::styling::eprintln;
use crate::sync::Semaphore;
use crate::trace::CommandTrace;

#[cfg(unix)]
pub mod pipe;
#[cfg(unix)]
mod process_owner;

/// Prepare complete input before spawning, with no producer that can block.
///
/// On Unix, input that fits in a pipe's buffer is written there before spawn,
/// so it needs no temporary storage and works with an unusable `TMPDIR`.
/// Larger input, and all input on Windows, goes through an anonymous file,
/// removed when its last handle closes, even on interruption.
pub fn buffered_stdin(bytes: &[u8]) -> std::io::Result<Stdio> {
    #[cfg(unix)]
    {
        let (reader, mut writer) = with_process_creation_guard(std::io::pipe)?;
        pipe::set_nonblocking(&writer)?;
        // Writing to a fresh pipe whose reader we hold fails only with
        // `WouldBlock`, once the input outgrows the buffer.
        if writer.write_all(bytes).is_ok() {
            return Ok(reader.into());
        }
    }
    let mut file = tempfile::tempfile()?;
    file.write_all(bytes)?;
    file.rewind()?;
    Ok(file.into())
}

// Published Linux/Windows targets use atomic descriptors or std's spawn lock.
#[cfg(target_vendor = "apple")]
static PROCESS_CREATION_LOCK: Mutex<()> = Mutex::new(());

/// Serialize process creation with descriptor creation that sets close-on-exec
/// after its native syscall. Otherwise a concurrent spawn can inherit endpoints
/// between creation and CLOEXEC, keeping unrelated output or wakeups alive.
pub(crate) fn with_process_creation_guard<T>(
    create: impl FnOnce() -> std::io::Result<T>,
) -> std::io::Result<T> {
    #[cfg(target_vendor = "apple")]
    let _guard = PROCESS_CREATION_LOCK
        .lock()
        .unwrap_or_else(|error| error.into_inner());
    create()
}

/// Spawn a child under the shared process-creation guard.
pub fn spawn(command: &mut Command) -> std::io::Result<std::process::Child> {
    let spawned = with_process_owner(command, |command| {
        with_process_creation_guard(|| command.spawn())
    })?;
    spawned.map_err(|error| spawn_error(command, error))
}

/// Spawn a shared child under the same process-creation lock as [`spawn`].
pub fn spawn_shared_child(command: &mut Command) -> std::io::Result<SharedChild> {
    with_process_owner(command, spawn_shared_child_here)?
}

/// Raw creation on the process owner, also used inside foreground admission.
pub(crate) fn spawn_shared_child_here(command: &mut Command) -> std::io::Result<SharedChild> {
    // SharedChild::new calls try_wait and can reap a short-lived child here.
    // Keep SharedChild::spawn's unreaped ownership for process-tree cleanup.
    with_process_creation_guard(|| SharedChild::spawn(command))
        .map_err(|error| spawn_error(command, error))
}

/// Run process creation and any admission checks on the signal-receiving owner.
pub(crate) fn with_process_owner<T: Send + 'static>(
    command: &mut Command,
    create: impl FnOnce(&mut Command) -> T + Send + 'static,
) -> std::io::Result<T> {
    #[cfg(unix)]
    return process_owner::with_command(command, create);
    #[cfg(not(unix))]
    Ok(create(command))
}

/// Retire a signal scope after the signal owner's pending receipt completes.
#[cfg(unix)]
pub(crate) fn on_process_owner<T: Send + 'static>(
    operation: impl FnOnce() -> T + Send + 'static,
) -> std::io::Result<T> {
    process_owner::run(operation)
}

/// Create wakeup endpoints under the same guard as process creation.
#[cfg(unix)]
pub fn socket_pair() -> std::io::Result<(
    std::os::unix::net::UnixStream,
    std::os::unix::net::UnixStream,
)> {
    with_process_creation_guard(std::os::unix::net::UnixStream::pair)
}

/// Create a stream socket without holding the spawn guard during connection I/O.
pub fn stream_socket(domain: socket2::Domain) -> std::io::Result<socket2::Socket> {
    with_process_creation_guard(|| socket2::Socket::new(domain, socket2::Type::STREAM, None))
}

/// Semaphore to limit concurrent command execution.
/// Prevents resource exhaustion when spawning many parallel git commands.
///
/// Only background threads consume permits. The foreground thread runs
/// commands one at a time, so it can't contribute to fan-out — and it is what
/// the user is waiting on: were it to queue here, background work that
/// saturates the permits (per-row preview diffs in the picker, each holding a
/// permit for seconds on a large repo) would stall the accept path of
/// `wt switch` until the pool drained. The cap is deliberately approximate:
/// a work-stealing pool (rayon) can run a capped closure on the foreground
/// thread, briefly exceeding the limit.
static CMD_SEMAPHORE: OnceLock<Semaphore> = OnceLock::new();

/// The thread that entered `main()`, captured by [`init_startup`]. Commands
/// on this thread bypass [`CMD_SEMAPHORE`] (see there). Unset when `wt` runs
/// as a library (unit tests), where every thread is capped.
static FOREGROUND_THREAD: OnceLock<std::thread::ThreadId> = OnceLock::new();

fn is_foreground_thread() -> bool {
    FOREGROUND_THREAD.get() == Some(&std::thread::current().id())
}

/// PIDs of capture-mode commands currently running on background threads, so
/// the foreground thread can cancel them once nobody will read their results.
///
/// A background thread dies with the process, but the `git` child it spawned
/// does not — it keeps running, orphaned, against a repo `wt` has already
/// left. The picker is where this bites: accepting a row abandons one preview
/// diff per worktree, each able to churn disk for seconds on a large repo,
/// filling an in-memory cache that no longer exists.
///
/// Only cancellable threads register ([`is_cancellable_thread`]): the
/// foreground thread is the one that cancels, and is never itself inside a
/// tracked command while doing so, so the work the user is actually waiting
/// on is never a target; an [`uninterruptible`] thread finishes what it
/// started. A command marked [`Cmd::finish_once_started`] doesn't register
/// either, so it runs to completion once spawned.
static BACKGROUND_PIDS: Mutex<BTreeSet<u32>> = Mutex::new(BTreeSet::new());

/// Deregisters a background command's PID however the command finishes.
///
/// The child is reaped inside the `wait` this guard outlives, so for the few
/// instructions between that reap and this `drop` a freed PID is still listed,
/// and a sweep landing in that window would signal whatever the kernel handed
/// the number to next. Signalling by PID can't close this — the reap and the
/// deregistration are not one operation — and deregistering before the wait
/// instead is not a fix but a removal: the wait *is* the command's lifetime,
/// so nothing would ever be cancellable. Accepted rather than mitigated:
/// PID allocation is incremental up to `pid_max`, which makes reuse inside a
/// microsecond window require wrapping the entire PID space first.
struct BackgroundPid(u32);

impl Drop for BackgroundPid {
    fn drop(&mut self) {
        BACKGROUND_PIDS.lock().unwrap().remove(&self.0);
    }
}

std::thread_local! {
    /// Whether this thread is running work cancellation must not touch. See
    /// [`uninterruptible`].
    static UNINTERRUPTIBLE: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// Run `f` with this thread's commands exempt from cancellation, for work the
/// user has already asked for rather than work done on spec.
///
/// Cancelling is safe for a preview because its only effect is a cache entry
/// nobody will read. It is not safe for a mutation: the picker runs an `alt-x`
/// worktree removal on a background thread so the UI stays live, and a SIGTERM
/// landing between `git worktree remove` and the branch delete would leave the
/// user half-removed. Such a thread finishes what it started; only its result
/// is discardable, not its effects.
pub fn uninterruptible<T>(f: impl FnOnce() -> T) -> T {
    struct Restore(bool);
    impl Drop for Restore {
        fn drop(&mut self) {
            UNINTERRUPTIBLE.with(|flag| flag.set(self.0));
        }
    }

    let _restore = Restore(UNINTERRUPTIBLE.with(|flag| flag.replace(true)));
    f()
}

/// Whether this thread's commands are subject to cancellation: background (the
/// foreground thread is the one doing the cancelling, and goes on to run the
/// switch itself) and not marked [`uninterruptible`].
fn is_cancellable_thread() -> bool {
    !is_foreground_thread() && !UNINTERRUPTIBLE.with(std::cell::Cell::get)
}

/// Register a freshly spawned child as cancellable for as long as the returned
/// guard lives. Returns `None` when this thread's commands aren't subject to
/// cancellation (see [`is_cancellable_thread`]).
fn track_if_cancellable(pid: u32) -> Option<BackgroundPid> {
    is_cancellable_thread().then(|| {
        BACKGROUND_PIDS.lock().unwrap().insert(pid);
        let guard = BackgroundPid(pid);
        // Re-read after publishing the PID, closing the window between this
        // command's pre-spawn check and its registration. Either the sweep
        // takes the set lock after the insert and signals this PID itself, or
        // it ran first — in which case the store it followed is visible here
        // and the signal it couldn't deliver is delivered now. A child spawned
        // into that window is exactly the orphan the sweep exists to prevent.
        if BACKGROUND_CANCELLED.load(Ordering::SeqCst) {
            signal_background_pid(pid);
        }
        guard
    })
}

/// What a terminal Ctrl-C that wt itself receives means while a foreground
/// child runs. Either way the child handles the key its own way; wt never
/// signals it for INT.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TerminalInterrupt {
    /// The child is one step of the command, such as a hook, an alias step or
    /// a `for-each` visit. Once it exits the command starts nothing more and
    /// exits interrupted, whatever status the child chose.
    Cancels,
    /// The command hands the terminal to its final, interactive child: a pager,
    /// an `--execute` program, a custom subcommand, an alias's last serial step.
    /// The key is that child's input, and its own exit status stands.
    ChildInput,
}

/// Whether a cancellation would signal `pid` right now.
#[cfg(all(test, unix))]
pub(crate) fn is_cancellable_pid(pid: u32) -> bool {
    BACKGROUND_PIDS.lock().unwrap().contains(&pid)
}

/// Set once the foreground thread has cancelled background work, so commands
/// that haven't spawned yet never do.
///
/// Cancellation has to be a state, not a one-shot sweep over
/// [`BACKGROUND_PIDS`]. A task that already cleared its caller's own
/// supersede check and then parked on [`CMD_SEMAPHORE`] holds no PID for a
/// sweep to find, and would spawn the moment a permit frees — precisely the
/// permits the sweep just freed by signalling everything holding one.
static BACKGROUND_CANCELLED: AtomicBool = AtomicBool::new(false);

/// Whether the calling thread's commands have been cancelled.
fn background_cancelled() -> bool {
    is_cancellable_thread() && BACKGROUND_CANCELLED.load(Ordering::SeqCst)
}

fn cancelled_error() -> std::io::Error {
    std::io::Error::new(ErrorKind::Interrupted, "background command cancelled")
}

/// Abandon background work: nothing further spawns, and whatever is already
/// running is signalled rather than left to finish as an orphan — except
/// commands marked [`Cmd::finish_once_started`], which run to completion.
///
/// Callers see either as an ordinary command failure, which every background
/// caller already treats as "no result".
pub fn cancel_background_commands() {
    BACKGROUND_CANCELLED.store(true, Ordering::SeqCst);
    for &pid in BACKGROUND_PIDS.lock().unwrap().iter() {
        signal_background_pid(pid);
    }
}

/// SIGTERM rather than SIGKILL: git's lockfile handlers run on the former, so
/// a diff interrupted mid-index-refresh cleans up after itself instead of
/// stranding an `index.lock` in a worktree the user is about to work in.
#[cfg(unix)]
fn signal_background_pid(pid: u32) {
    terminate_pid(pid as i32);
}

/// Windows has no signal to deliver to an unrelated PID, so a command already
/// running there runs to completion; the latch still stops everything that
/// hasn't spawned, which is the bulk of a large fan-out.
#[cfg(windows)]
fn signal_background_pid(_pid: u32) {}

/// The working directory at `wt` startup. Captured once so relative `GIT_*`
/// path variables inherited from a parent `git` process can be resolved to
/// absolute paths regardless of each subsequent child command's `current_dir`.
static STARTUP_CWD: OnceLock<Option<PathBuf>> = OnceLock::new();

/// `GIT_*` environment variables that name paths used by git for repository
/// discovery and I/O. When git invokes shell aliases (`alias.x = "!cmd"`) it
/// may set some of these to *relative* paths (e.g. `GIT_DIR=.git`), which
/// then resolve against whatever `current_dir` a child process happens to
/// run in — not the directory where `wt` was invoked. Normalizing them to
/// absolute paths keeps git's alias context without breaking discovery.
///
/// Also consumed by [`crate::testing::scrub_git_path_vars`] so test/bench
/// helpers strip the same list before spawning a `git` subprocess that
/// targets an explicit path.
pub const INHERITED_GIT_PATH_VARS: &[&str] = &[
    "GIT_DIR",
    "GIT_WORK_TREE",
    "GIT_COMMON_DIR",
    "GIT_INDEX_FILE",
    "GIT_OBJECT_DIRECTORY",
];

/// Initialize the Unix process owner and record startup facts: the current
/// directory (so [`Cmd`] can resolve inherited relative `GIT_*` paths) and the
/// calling thread (exempt from `CMD_SEMAPHORE`).
///
/// Call once from `main()`, before any code changes the process's working
/// directory or spawns threads. Workers inherit blocked INT/TERM; the process
/// owner and its children retain the original mask. Subsequent calls are no-ops.
pub fn init_startup() -> std::io::Result<()> {
    #[cfg(unix)]
    process_owner::init()?;
    STARTUP_CWD.get_or_init(|| std::env::current_dir().ok());
    FOREGROUND_THREAD.get_or_init(|| std::thread::current().id());
    Ok(())
}

fn startup_cwd() -> Option<&'static PathBuf> {
    STARTUP_CWD
        .get_or_init(|| std::env::current_dir().ok())
        .as_ref()
}

/// Pure helper: given a base directory and a lookup function for environment
/// variables, compute the `(var, absolute_value)` overrides that should be
/// applied to a child process's environment to shadow any inherited relative
/// `GIT_*` path variables. Absolute values and unset variables are skipped.
///
/// Factored out from [`inherited_git_env_overrides`] so it can be unit-tested
/// without touching process-wide state.
fn compute_git_env_overrides<F>(base: &std::path::Path, lookup: F) -> Vec<(&'static str, OsString)>
where
    F: Fn(&str) -> Option<OsString>,
{
    let mut overrides = Vec::new();
    for var in INHERITED_GIT_PATH_VARS {
        let Some(value) = lookup(var) else {
            continue;
        };
        let path = std::path::Path::new(&value);
        if path.is_absolute() {
            continue;
        }
        overrides.push((*var, base.join(path).into_os_string()));
    }
    overrides
}

/// Cached absolute forms of any inherited relative `GIT_*` path variables.
/// Computed once from the startup cwd and process environment, since neither
/// changes during the process lifetime.
static GIT_ENV_OVERRIDES: OnceLock<Vec<(&'static str, OsString)>> = OnceLock::new();

/// For each inherited `GIT_*` path variable that is set to a *relative* path,
/// produce an absolute form resolved against the startup cwd. Returns the
/// `(var, absolute_value)` pairs that should be applied to a child process's
/// environment to shadow the inherited relative values.
fn inherited_git_env_overrides() -> &'static [(&'static str, OsString)] {
    GIT_ENV_OVERRIDES.get_or_init(|| {
        let Some(cwd) = startup_cwd() else {
            return Vec::new();
        };
        compute_git_env_overrides(cwd, |var| std::env::var_os(var))
    })
}

fn ensure_executable_path(path: &Path) -> std::io::Result<()> {
    let metadata = std::fs::metadata(path)?;
    if !metadata.is_file() {
        return Err(std::io::Error::new(
            ErrorKind::PermissionDenied,
            format!("{} is not an executable file", path.display()),
        ));
    }
    if !is_executable(&metadata) {
        return Err(std::io::Error::new(
            ErrorKind::PermissionDenied,
            format!("{} is not executable", path.display()),
        ));
    }
    Ok(())
}

#[cfg(unix)]
fn is_executable(metadata: &Metadata) -> bool {
    use std::os::unix::fs::PermissionsExt;

    metadata.permissions().mode() & 0o111 != 0
}

#[cfg(not(unix))]
fn is_executable(_metadata: &Metadata) -> bool {
    true
}

/// Default concurrent external commands. Tuned to avoid hitting OS limits
/// (file descriptors, process limits) while maintaining good parallelism.
const DEFAULT_CONCURRENT_COMMANDS: usize = 32;

/// Parse the concurrency limit from a string value.
/// Returns None if invalid (not a number), otherwise applies the 0 = unlimited rule.
fn parse_concurrent_limit(value: &str) -> Option<usize> {
    value
        .parse::<usize>()
        .ok()
        // 0 = no limit (use usize::MAX as effectively unlimited)
        .map(|n| if n == 0 { usize::MAX } else { n })
}

fn max_concurrent_commands() -> usize {
    std::env::var("WORKTRUNK_MAX_CONCURRENT_COMMANDS")
        .ok()
        .and_then(|s| parse_concurrent_limit(&s))
        .unwrap_or(DEFAULT_CONCURRENT_COMMANDS)
}

fn semaphore() -> &'static Semaphore {
    CMD_SEMAPHORE.get_or_init(|| Semaphore::new(max_concurrent_commands()))
}

/// Cached shell configuration for the current platform
static SHELL_CONFIG: OnceLock<Result<ShellConfig, String>> = OnceLock::new();

/// POSIX shell configuration for command execution (sh or Git Bash).
#[derive(Debug, Clone)]
pub struct ShellConfig {
    /// Path to the shell executable
    pub executable: PathBuf,
    /// Arguments to pass before the command (e.g., ["-c"] for sh)
    pub args: Vec<String>,
    /// Human-readable name for error messages
    pub name: String,
}

impl ShellConfig {
    /// Get the shell configuration for the current platform
    ///
    /// On Unix, returns sh. On Windows, returns Git Bash or an error if not installed.
    pub fn get() -> anyhow::Result<&'static ShellConfig> {
        SHELL_CONFIG
            .get_or_init(detect_shell)
            .as_ref()
            .map_err(|e| anyhow::anyhow!("{e}"))
    }

    /// Create a Command configured for shell execution
    ///
    /// The command string will be passed to the shell for interpretation.
    pub fn command(&self, shell_command: &str) -> Command {
        let mut cmd = Command::new(&self.executable);
        for arg in &self.args {
            cmd.arg(arg);
        }
        cmd.arg(shell_command);
        cmd
    }
}

/// Detect the best available shell for the current platform
fn detect_shell() -> Result<ShellConfig, String> {
    #[cfg(unix)]
    {
        Ok(ShellConfig {
            executable: PathBuf::from("sh"),
            args: vec!["-c".to_string()],
            name: "sh".to_string(),
        })
    }

    #[cfg(windows)]
    {
        detect_windows_shell()
    }
}

/// Detect Git Bash on Windows
///
/// Returns an error if Git for Windows is not installed, since hooks require
/// bash syntax.
#[cfg(windows)]
fn detect_windows_shell() -> Result<ShellConfig, String> {
    if let Some(bash_path) = find_git_bash() {
        return Ok(ShellConfig {
            executable: bash_path,
            args: vec!["-c".to_string()],
            name: "Git Bash".to_string(),
        });
    }

    Err("Git for Windows is required but not found.\n\
         Install from https://git-scm.com/download/win"
        .to_string())
}

/// Find Git Bash executable on Windows
///
/// Finds `git.exe` in PATH and derives the bash.exe location from the Git installation.
/// We avoid `which bash` because on systems with WSL, `C:\Windows\System32\bash.exe`
/// (WSL launcher) often comes before Git Bash in PATH.
#[cfg(windows)]
fn find_git_bash() -> Option<PathBuf> {
    // Ask Git itself so PATH shims resolve to the installation they launch.
    let git_path = which::which("git").ok()?;
    let output = Cmd::new(git_path.to_string_lossy())
        .arg("--exec-path")
        .env_remove("GIT_EXEC_PATH") // User overrides name helpers, not the install.
        .run()
        .ok()?;
    if !output.status.success() {
        return None;
    }
    let exec_path = std::str::from_utf8(&output.stdout).ok()?;
    git_bash_from_exec_path(Path::new(exec_path.trim_end()))
}

/// Git for Windows reports `<install>/<runtime>/libexec/git-core` for --exec-path.
/// The runtime name varies by architecture; Bash belongs to the install root.
#[cfg(any(windows, test))]
fn git_bash_from_exec_path(exec_path: &Path) -> Option<PathBuf> {
    if !exec_path.ends_with(Path::new("libexec").join("git-core")) {
        return None;
    }
    let root = exec_path.parent()?.parent()?.parent()?;
    [root.join("bin"), root.join("usr").join("bin")]
        .into_iter()
        .map(|dir| dir.join("bash.exe"))
        .find(|bash_path| bash_path.is_file())
}

/// Environment variable naming the directive file for `cd` path changes.
///
/// Shell wrappers set this to a temp file; wt writes a raw absolute path to
/// it (one line, no shell escaping). The wrapper `cd`s to that path after wt
/// exits. Because the file contents are a literal path, there is no shell
/// injection surface — this is safe to pass through to alias/hook shell bodies.
pub const DIRECTIVE_CD_FILE_ENV_VAR: &str = "WORKTRUNK_DIRECTIVE_CD_FILE";

/// Retired shell-command directive variable.
///
/// Current wrappers no longer set it. Its presence tells `--execute` that the
/// live shell still has an old wrapper loaded, and subprocesses must not
/// inherit it: an older parent wrapper would source anything written there
/// after wt exits.
pub const DIRECTIVE_EXEC_FILE_ENV_VAR: &str = "WORKTRUNK_DIRECTIVE_EXEC_FILE";

/// Retired single-file directive env var.
///
/// wt never writes to or passes this file through, but still removes the
/// variable from child environments so an old wrapper cannot expose a file
/// that its parent shell will source.
pub const RETIRED_DIRECTIVE_FILE_ENV_VAR: &str = "WORKTRUNK_DIRECTIVE_FILE";

/// Environment variable carrying the directory the user's shell is in.
///
/// A top-level `wt` reads that directory from its own process cwd, which is
/// what subdirectory preservation resolves the user's position against (from
/// `monorepo.feature/subproject/`, `wt switch main` lands in
/// `monorepo/subproject/`). A `wt` nested inside an alias or hook body cannot:
/// those bodies run with a wt-chosen working directory (the worktree root), so
/// the nested process would resolve the user to that root and drop them there.
///
/// [`apply_cd_directive_env`] therefore sets this alongside the CD directive
/// file — the same children that are allowed to move the user's shell are the
/// ones that need to know where it currently is. Nesting composes because
/// [`shell_cwd`] prefers the inherited value over the process cwd, so each
/// layer forwards the shell's directory rather than its own. See issue #3723.
///
/// Private, unlike the directive-file vars above: the setter, the scrubber and
/// the reader all live in this module, and a name spells the coupling between
/// them that a repeated literal would leave to a spelling match.
const SHELL_CWD_ENV_VAR: &str = "WORKTRUNK_SHELL_CWD";

/// The directory the user's shell is in: the inherited `WORKTRUNK_SHELL_CWD`
/// when a parent `wt` set it, otherwise this process's own startup cwd.
///
/// Callers that ask "where is the user physically standing?" use this rather
/// than [`std::env::current_dir`]. `-C` is deliberately not consulted: it sets
/// git's discovery path without moving the shell.
pub fn shell_cwd() -> Option<PathBuf> {
    shell_cwd_from(std::env::var_os(SHELL_CWD_ENV_VAR), startup_cwd())
}

/// Pure form of [`shell_cwd`], split out so the relative-value fall-through is
/// unit-testable without mutating process-wide state — the same split
/// [`compute_git_env_overrides`] makes for [`inherited_git_env_overrides`].
fn shell_cwd_from(inherited: Option<OsString>, fallback: Option<&PathBuf>) -> Option<PathBuf> {
    if let Some(value) = inherited {
        let path = PathBuf::from(value);
        // A relative value can't name the shell's position from a child that
        // runs elsewhere, so fall through to the process cwd. A stale absolute
        // one needs no guard here: the subdirectory it resolves to has to exist
        // in the destination before anything `cd`s there.
        if path.is_absolute() {
            return Some(path);
        }
    }
    fallback.cloned()
}

/// Scrub all directive file env vars from a `std::process::Command`.
///
/// Prevents child processes from writing to the parent shell's directive
/// files. Called by every code path that spawns external commands (Cmd,
/// help pager, picker pager, background hooks, git credential helpers).
///
/// `WORKTRUNK_SHELL_CWD` goes with them: it is meaningful only to a child that
/// can act on the shell's position, and those children get it back from
/// [`apply_cd_directive_env`].
pub fn scrub_directive_env_vars(cmd: &mut std::process::Command) {
    cmd.env_remove(DIRECTIVE_CD_FILE_ENV_VAR);
    cmd.env_remove(DIRECTIVE_EXEC_FILE_ENV_VAR);
    cmd.env_remove(RETIRED_DIRECTIVE_FILE_ENV_VAR);
    cmd.env_remove(SHELL_CWD_ENV_VAR);
}

/// Re-add the CD directive file to a trusted child's environment, together
/// with the shell cwd that makes its `cd` land where the user actually is.
///
/// The two travel together by construction: a child that can redirect the
/// parent shell resolves the user's subdirectory against [`shell_cwd`], and
/// without it every nested `wt switch` / `wt remove` inside an alias or hook
/// body would `cd` to a worktree root (issue #3723).
pub fn apply_cd_directive_env(cmd: &mut std::process::Command, cd_file: &std::path::Path) {
    cmd.env(DIRECTIVE_CD_FILE_ENV_VAR, cd_file);
    if let Some(cwd) = shell_cwd() {
        cmd.env(SHELL_CWD_ENV_VAR, cwd);
    }
}

/// Scrub the git-discovery path vars ([`INHERITED_GIT_PATH_VARS`]) from a child
/// `Command`, so the spawned process discovers its repository from its working
/// directory rather than a `GIT_DIR`/`GIT_WORK_TREE` that `wt` inherited.
///
/// Git resolves these vars **before** walking up from the cwd, so an inherited
/// value silently overrides whatever working directory the child was given.
/// Whether a child keeps them is decided by who chose its cwd:
///
/// - **`wt` relocated a user command into a worktree it selected** — hooks
///   (run in the operation's worktree), `wt step for-each` (run in each
///   worktree in turn), and the `--execute` program (run in the switch target)
///   — the cwd carries `wt`'s intent, so the inherited context is scrubbed and
///   the command's `git` calls discover the worktree from the cwd. The inherited
///   context is common, not exotic: `git` exports an absolute `GIT_DIR`
///   pinned to the invoking worktree's private gitdir when `wt` runs as a
///   `!wt` alias from a **linked worktree**, and git itself exports discovery
///   vars (e.g. `GIT_INDEX_FILE`) to the hooks it spawns. Forwarding those
///   into a relocated command misdirects every `git` call in it; with both
///   `GIT_DIR` and `GIT_WORK_TREE` present, a `git init` even writes
///   `core.worktree` into the *inherited* repo's config, silently redirecting
///   every later plain git command there. See issue #3373. Detached children
///   (`spawn_detached_exec`: hook pipelines, trash drains) are relocated the
///   same way, and outlive the parent, so removing the invoking worktree would
///   also leave an inherited `GIT_DIR` naming a pruned gitdir.
///
/// - **The child runs where the user already was** — aliases (the user's own
///   top-level command, run from the invoking worktree) and `commit.generation`
///   commands (spawned with no `current_dir`) — the inherited context *is* the
///   user's context, so it is forwarded untouched.
///
/// - **`wt`'s own git plumbing** splits on the same question. Repo-level
///   ([`Cmd`] via `Repository::run_command`) keeps the inherited context on
///   purpose (relative values absolutized, see issue #1914): `wt` honoring
///   the context it was handed is the point of running `wt` under `git`. Its
///   cwd is `discovery_path`, which is often but not always where the user
///   invoked `wt` — `Repository::at` is handed a `wt`-chosen worktree at
///   several sites (the post-switch hook repo, the pipeline repo, `finish`'s
///   destination repo, the `pre-remove` render repo). The exemption rests on
///   scope rather than cwd: repo-level questions are worktree-agnostic within
///   one repository, and every worktree-scoped answer routes through
///   [`crate::git::WorkingTree`], which scrubs.
///   **Worktree-local** plumbing — [`crate::git::WorkingTree::run_command`],
///   `TempIndex::command`, `list_ignored_entries` — relocates git into a
///   worktree `wt` resolved, so it scrubs, the same way hooks and `for-each`
///   do. Otherwise a `!wt` alias from a linked worktree (`GIT_DIR` pinned to
///   that worktree's private gitdir) makes `status` / `read-tree` on a
///   *different* worktree use the invoking tree's index.
///
/// Every site uses this one list; a site that needs its own value for a
/// scrubbed var sets it *after* the scrub rather than subsetting the list
/// ([`Cmd::scrub_git_discovery_env`]). That includes `GIT_OBJECT_DIRECTORY`:
/// a redirected repository re-sets its own immediately after, so the only
/// value a worktree-local scrub drops is an **inherited** one — which git
/// supplies to push-quarantine hooks, and which is pinned to the invoking
/// context exactly as `GIT_DIR` is. Dropping it is the deliberate call, not
/// an artifact of reusing the list.
///
/// Any new spawn site whose cwd names a `wt`-chosen worktree must apply this
/// scrub, via this helper or [`Cmd::scrub_git_discovery_env`].
pub fn scrub_git_discovery_env_vars(cmd: &mut std::process::Command) {
    for var in INHERITED_GIT_PATH_VARS {
        cmd.env_remove(var);
    }
}

/// The hermetic git-config floor for test processes: the deny pair points
/// global and system config at a path that does not exist (git reads a
/// missing config file as empty), and `GIT_CONFIG_COUNT` with its numbered
/// keys and values — git's environment spelling of `-c` — supplies the two
/// settings the suite needs in the denied config's place. What each entry is
/// for, and why `-c` precedence keeps this list short: `tests/AGENTS.md` →
/// Git Config Isolation.
pub const HERMETIC_TEST_GIT_ENV: [(&str, &str); 7] = [
    ("GIT_CONFIG_GLOBAL", "/nonexistent/wt/gitconfig"),
    ("GIT_CONFIG_SYSTEM", "/nonexistent/wt/gitconfig"),
    ("GIT_CONFIG_COUNT", "2"),
    ("GIT_CONFIG_KEY_0", "user.useConfigOnly"),
    ("GIT_CONFIG_VALUE_0", "true"),
    ("GIT_CONFIG_KEY_1", "rerere.enabled"),
    ("GIT_CONFIG_VALUE_1", "false"),
];

/// When latched, every child spawned through [`Cmd`] gets
/// [`HERMETIC_TEST_GIT_ENV`] — including the git that *production* code
/// spawns while a test drives it in-process, which no per-command harness
/// hook can reach. The test harness latches it before the first fixture;
/// production code never does. An in-process test cannot set its own
/// environment instead — `std::env::set_var` races the other test threads —
/// but an atomic latch is sound from any thread.
///
/// TODO(hermetic-env): a test-serving switch in production code, accepted as
/// the pragmatic middle over its alternatives — a pre-`main` constructor
/// crate every test target must link, or threading an explicit env value
/// through `Repository`, which is the structural fix.
static HERMETIC_TEST_ENV_LATCHED: AtomicBool = AtomicBool::new(false);

/// Latch [`HERMETIC_TEST_GIT_ENV`] onto every future [`Cmd`] child in this
/// process. Called by the `worktrunk::testing` harness; idempotent.
pub fn enable_hermetic_test_env() {
    HERMETIC_TEST_ENV_LATCHED.store(true, Ordering::Relaxed);
}

/// Apply [`HERMETIC_TEST_GIT_ENV`] to `cmd` if the latch is set. The unlatched
/// path is production's: one relaxed load, no env writes.
pub fn apply_hermetic_test_env(cmd: &mut std::process::Command) {
    if HERMETIC_TEST_ENV_LATCHED.load(Ordering::Relaxed) {
        for (key, val) in HERMETIC_TEST_GIT_ENV {
            cmd.env(key, val);
        }
    }
}

// ============================================================================
// Shell Escaping
// ============================================================================

/// How to expand a value into a command template.
///
/// Hooks and aliases are POSIX shell command lines. Filesystem paths and
/// `--execute` argv elements use literal expansion because no shell parses
/// them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ShellEscapeMode {
    /// Substitute values verbatim — used for filesystem paths.
    Literal,
    /// POSIX single-quoting (`'it'\''s'`) for hooks and aliases.
    Posix,
}

/// Shell-escape `s` for the given [`ShellEscapeMode`].
///
/// The single dispatcher every directive-payload escaper routes through.
pub fn shell_escape_for(mode: ShellEscapeMode, s: &str) -> String {
    match mode {
        ShellEscapeMode::Literal => s.to_string(),
        ShellEscapeMode::Posix => {
            shell_escape::unix::escape(std::borrow::Cow::Borrowed(s)).into_owned()
        }
    }
}

/// Maximum lines of the bounded subprocess preview per stream. Exceeded
/// content is elided with a `… (N more lines, M bytes elided)` marker; the
/// full output is still written to `subprocess.log` via
/// [`SUBPROCESS_FULL_TARGET`].
const LOG_OUTPUT_MAX_LINES: usize = 200;

/// Maximum bytes of the bounded subprocess preview per stream. Applied in
/// addition to [`LOG_OUTPUT_MAX_LINES`].
const LOG_OUTPUT_MAX_BYTES: usize = 64 * 1024;

/// Log target used for *full* subprocess stdin/stdout/stderr (and the per-command
/// `$ cmd … seq=N` header `log_output` prepends to each block). The
/// tracing-subscriber `subprocess.log` layer filters on this target, so raw
/// subprocess bodies (diffs, `git log -p`, patch-id pipelines) never reach
/// stderr or `trace.log`.
pub const SUBPROCESS_FULL_TARGET: &str = "worktrunk::subprocess_full";

/// Log target used for the *bounded* preview of subprocess output (capped
/// at `LOG_OUTPUT_MAX_LINES` / `LOG_OUTPUT_MAX_BYTES` with an elision
/// marker). Shares the routing of all non-full records: stderr at `-v`
/// (or `RUST_LOG=debug` without `-vv`), `trace.log` at `-vv`. The
/// uncapped version is captured via [`SUBPROCESS_FULL_TARGET`].
pub const SUBPROCESS_BOUNDED_TARGET: &str = "worktrunk::subprocess_bounded";

/// The `$ <cmd> [<context>]` command header. Shared by the stderr/`trace.log`
/// start line ([`Cmd::log_run_start`] and friends) and the per-command header
/// that [`log_output`] prepends to each block in `subprocess.log`, so the two
/// render the command identically.
fn command_header(cmd: &str, context: Option<&str>) -> String {
    let context = crate::trace::emit::diagnostic_context().or(context);
    match context {
        Some(ctx) => format!("$ {cmd} [{ctx}]"),
        None => format!("$ {cmd}"),
    }
}

/// Log a command's captured stdin, stdout, and stderr to the debug targets.
///
/// At `tracing::DEBUG` (`-vv`) each stream is emitted twice, and the
/// tracing-subscriber layers route the two targets:
///   - [`SUBPROCESS_FULL_TARGET`] → `subprocess.log`: uncapped, one record per
///     line. Each command with I/O opens with a `$ cmd … [seq=N tid=T]` header
///     over its stdin (`  < `), stdout (`  `), and stderr (`  ! `) lines, so the
///     otherwise-undelimited bytes segment into blocks and `seq` joins each
///     block to its `[wt-trace]` record.
///   - [`SUBPROCESS_BOUNDED_TARGET`] → `trace.log` at `-vv` (else stderr):
///     capped at [`LOG_OUTPUT_MAX_LINES`] / [`LOG_OUTPUT_MAX_BYTES`] with an
///     elision marker, under the `$ cmd` start line `trace.log` already carries.
///
/// One record per line keeps a command's own output contiguous but lets
/// concurrent commands interleave by line; `tid` groups a block and the atomic
/// header recovers the `seq` join.
///
/// `output` is `None` for a command that never produced any (spawn or wait
/// failure); its header and stdin still emit, so the input survives in the deep
/// log even when nothing ran. Sensitive commands emit only a redaction marker
/// to each target, regardless of outcome.
///
/// Below Debug both targets are disabled and this is a no-op.
fn log_output(
    trace: &CommandTrace,
    stdin: Option<&[u8]>,
    output: Option<&std::process::Output>,
    sensitive: bool,
) {
    // Either sink can be active without the other (for example, if opening
    // subprocess.log failed). Avoid formatting bytes unless one consumes them.
    if !tracing::enabled!(target: SUBPROCESS_FULL_TARGET, tracing::Level::DEBUG)
        && !tracing::enabled!(target: SUBPROCESS_BOUNDED_TARGET, tracing::Level::DEBUG)
    {
        return;
    }
    if sensitive {
        tracing::debug!(
            target: SUBPROCESS_FULL_TARGET,
            "{}  [seq={} tid={}]\n  [redacted]",
            command_header(trace.cmd(), trace.context()),
            trace.seq(),
            trace.tid(),
        );
        tracing::debug!(target: SUBPROCESS_BOUNDED_TARGET, "  [redacted]");
        return;
    }
    let stdin = stdin.unwrap_or_default();
    // `None` when the command never produced output (spawn/wait failure); stdin
    // is still logged so the input survives in the deep log.
    let (stdout, stderr) = output
        .map(|o| (o.stdout.as_slice(), o.stderr.as_slice()))
        .unwrap_or_default();
    if !stdin.is_empty() || !stdout.is_empty() || !stderr.is_empty() {
        tracing::debug!(
            target: SUBPROCESS_FULL_TARGET,
            "{}  [seq={} tid={}]",
            command_header(trace.cmd(), trace.context()),
            trace.seq(),
            trace.tid(),
        );
    }
    for line in format_stream_full(stdin, "  < ") {
        tracing::debug!(target: SUBPROCESS_FULL_TARGET, "{}", line);
    }
    for line in format_stream_full(stdout, "  ") {
        tracing::debug!(target: SUBPROCESS_FULL_TARGET, "{}", line);
    }
    for line in format_stream_full(stderr, "  ! ") {
        tracing::debug!(target: SUBPROCESS_FULL_TARGET, "{}", line);
    }
    for line in format_stream_bounded(stdout, "  ") {
        tracing::debug!(target: SUBPROCESS_BOUNDED_TARGET, "{}", line);
    }
    for line in format_stream_bounded(stderr, "  ! ") {
        tracing::debug!(target: SUBPROCESS_BOUNDED_TARGET, "{}", line);
    }
}

/// Split captured bytes into prefixed lines — full output, no cap.
fn format_stream_full(bytes: &[u8], prefix: &str) -> Vec<String> {
    if bytes.is_empty() {
        return Vec::new();
    }
    String::from_utf8_lossy(bytes)
        .lines()
        .map(|line| format!("{}{}", prefix, line))
        .collect()
}

/// Split captured bytes into prefixed lines with at most [`LOG_OUTPUT_MAX_LINES`]
/// and [`LOG_OUTPUT_MAX_BYTES`] emitted; remainder replaced by a single
/// `… (N more lines, M bytes elided — <hint>)` marker. The hint text tracks
/// whether `subprocess.log` is collecting the full bodies, asked through
/// `tracing::enabled!` against [`SUBPROCESS_FULL_TARGET`] — true iff the
/// `subprocess.log` layer is registered and accepting that target (`-vv` opened
/// the file successfully).
///
/// Preview lines are emitted raw here; control bytes (most commonly NUL from
/// `-z`/`--null` git output) are escaped downstream at the single point that
/// feeds both human-facing sinks — `render_event_message` in the binary's
/// logging layer, which renders this target's records to stderr and `trace.log`.
/// The uncapped [`SUBPROCESS_FULL_TARGET`] copy bypasses that escape and keeps
/// the bytes verbatim in `subprocess.log`.
fn format_stream_bounded(bytes: &[u8], prefix: &str) -> Vec<String> {
    if bytes.is_empty() {
        return Vec::new();
    }
    let text = String::from_utf8_lossy(bytes);
    let total_bytes = bytes.len();

    let mut out = Vec::new();
    let mut bytes_emitted = 0;
    let mut lines = text.lines().enumerate();
    for (lines_emitted, line) in &mut lines {
        if lines_emitted >= LOG_OUTPUT_MAX_LINES || bytes_emitted >= LOG_OUTPUT_MAX_BYTES {
            let remaining_lines = 1 + lines.count();
            let remaining_bytes = total_bytes.saturating_sub(bytes_emitted);
            let hint = if tracing::enabled!(target: SUBPROCESS_FULL_TARGET, tracing::Level::DEBUG) {
                "full output in subprocess.log"
            } else {
                "rerun with -vv for full output"
            };
            out.push(format!(
                "{}… ({} more lines, {} bytes elided — {})",
                prefix, remaining_lines, remaining_bytes, hint
            ));
            return out;
        }
        out.push(format!("{}{}", prefix, line));
        bytes_emitted += line.len() + 1;
    }
    out
}

/// Implementation of timeout-based command execution.
///
/// Spawns reader threads to drain stdout/stderr concurrently (preventing deadlock when
/// output exceeds the OS pipe buffer), then waits with timeout. On timeout, tears down
/// the still-owned child's process tree; scoped readers share the same deadline,
/// including when an exited child's descendants retain its pipes.
///
/// **The teardown reaches the tree, not just the child, because otherwise the timeout
/// doesn't bound anything.** A grandchild inherits the child's stderr pipe, so a
/// surviving one holds the write end open and `read_to_end` blocks until it exits —
/// making this function return `TimedOut` only after the *grandchild's* full runtime.
/// The case that matters is the one this timeout exists for: `git ls-remote` against an
/// unreachable host spawns `git-remote-https`, which sits in `connect()` for ~127 s per
/// address on Linux and does not notice that git died. So the child is spawned into its
/// own process group and [`kill_timed_out_tree`] signals the group.
///
/// Isolating the group costs the kernel's tty broadcast: a Ctrl-C no longer reaches a
/// timed child directly, so the user waits out the remaining timeout instead of
/// interrupting it. That is bounded by the timeout the caller chose (seconds), whereas
/// the orphan the alternative leaves behind — kill the child, stop waiting on the
/// readers — holds a pipe for as long as its own operation takes, once per spawn.
fn run_with_timeout_impl(
    cmd: &mut Command,
    timeout: std::time::Duration,
    cancellable: bool,
) -> std::io::Result<std::process::Output> {
    #[cfg(unix)]
    {
        use std::os::unix::process::CommandExt;
        cmd.process_group(0);
    }

    let child = spawn_shared_child(cmd)?;
    let _tracked = cancellable
        .then(|| track_if_cancellable(child.id()))
        .flatten();

    let deadline = Instant::now() + timeout;
    let child_stdout = child.take_stdout();
    let child_stderr = child.take_stderr();
    #[cfg(unix)]
    let readers = (|| {
        Ok::<_, std::io::Error>((
            child_stdout
                .map(|stream| pipe::PipeReader::new(stream, Some(deadline), None))
                .transpose()?,
            child_stderr
                .map(|stream| pipe::PipeReader::new(stream, Some(deadline), None))
                .transpose()?,
        ))
    })();
    #[cfg(not(unix))]
    let readers = Ok::<_, std::io::Error>((child_stdout, child_stderr));
    let (mut child_stdout, mut child_stderr) = match readers {
        Ok(readers) => readers,
        Err(error) => {
            kill_timed_out_tree(child.id());
            let _ = child.kill();
            let _ = child.wait();
            return Err(error);
        }
    };

    std::thread::scope(|s| {
        let stdout_thread = s.spawn(|| {
            let mut buf = Vec::new();
            child_stdout
                .as_mut()
                .map(|h| h.read_to_end(&mut buf))
                .transpose()?;
            Ok::<_, std::io::Error>(buf)
        });
        let stderr_thread = s.spawn(|| {
            let mut buf = Vec::new();
            child_stderr
                .as_mut()
                .map(|h| h.read_to_end(&mut buf))
                .transpose()?;
            Ok::<_, std::io::Error>(buf)
        });

        let collect = || {
            let stdout = output_reader_result(stdout_thread.join());
            let stderr = output_reader_result(stderr_thread.join());
            Ok::<_, std::io::Error>((stdout?, stderr?))
        };
        // Keep the group leader unreaped until bounded EOF. A descendant-held
        // pipe can then time out without surrendering the identity used by cleanup.
        #[cfg(unix)]
        let output = match collect() {
            Ok(output) => output,
            Err(error) => {
                // A child already ended by a native INT/TERM stays cancelled even
                // when a descendant holding its pipes ran the readers to the
                // deadline; reporting `TimedOut` would let callers fall back as
                // if the command were merely slow. The probe leaves the leader
                // unreaped for the teardown, and signalling its zombie cannot
                // change the status the final `wait` then reports.
                let interrupted = exited_by_native_interrupt(child.id());
                kill_timed_out_tree(child.id());
                let _ = child.kill();
                return match child.wait() {
                    Ok(status) if interrupted => Ok(std::process::Output {
                        status,
                        stdout: Vec::new(),
                        stderr: Vec::new(),
                    }),
                    _ => Err(error),
                };
            }
        };
        let status = match wait_shared_child(&child, Some(deadline)) {
            Ok(status) => status,
            Err(error) => {
                kill_timed_out_tree(child.id());
                let _ = child.kill();
                let _ = child.wait();
                return Err(error);
            }
        };
        #[cfg(not(unix))]
        let output = collect()?;
        Ok(std::process::Output {
            status,
            stdout: output.0,
            stderr: output.1,
        })
    })
}

/// Whether SIGINT/SIGTERM already ended `pid`, read with `WNOWAIT` so the
/// child stays unreaped and keeps pinning its pgid for the teardown.
#[cfg(target_os = "linux")]
fn exited_by_native_interrupt(pid: u32) -> bool {
    use nix::sys::signal::Signal;
    use nix::sys::wait::{Id, WaitPidFlag, WaitStatus, waitid};
    matches!(
        waitid(
            Id::Pid(nix::unistd::Pid::from_raw(pid as i32)),
            WaitPidFlag::WEXITED | WaitPidFlag::WNOWAIT | WaitPidFlag::WNOHANG,
        ),
        Ok(WaitStatus::Signaled(_, Signal::SIGINT | Signal::SIGTERM, _))
    )
}

/// Darwin's `waitid` with the same flags; nix doesn't wrap it there. Darwin
/// leaves `siginfo` untouched for a running child, hence the zeroed buffer,
/// and can report a stop through `WEXITED`, hence matching `CLD_KILLED` only.
#[cfg(target_vendor = "apple")]
#[allow(unsafe_code)]
fn exited_by_native_interrupt(pid: u32) -> bool {
    use nix::libc;
    // SAFETY: `siginfo_t` is plain data; all-zero is a valid value.
    let mut info: libc::siginfo_t = unsafe { std::mem::zeroed() };
    // SAFETY: `info` is a valid, exclusively borrowed `siginfo_t`.
    let ret = unsafe {
        libc::waitid(
            libc::P_PID,
            pid as libc::id_t,
            &mut info,
            libc::WEXITED | libc::WNOWAIT | libc::WNOHANG,
        )
    };
    ret == 0
        && info.si_signo == libc::SIGCHLD
        && info.si_code == libc::CLD_KILLED
        && matches!(info.si_status, libc::SIGINT | libc::SIGTERM)
}

/// No unreaped status probe here: a deadline-bound cancellation stays `TimedOut`.
#[cfg(all(unix, not(target_os = "linux"), not(target_vendor = "apple")))]
fn exited_by_native_interrupt(_pid: u32) -> bool {
    false
}

/// Tear down the process tree of a child that outlived its timeout.
///
/// `run_with_timeout_impl` made the child its own process-group leader, so its
/// pid is the pgid and the TERM → KILL escalation reaches every member. SIGTERM
/// first for the same reason [`signal_background_pid`] uses it: git's lockfile
/// handlers run on TERM, so an interrupted git cleans up after itself.
///
/// Signalling by pid is safe here because the caller still holds an unreaped
/// [`shared_child::SharedChild`]: bounded readers finish before waiting/reaping,
/// and an expired direct wait leaves the child unreaped. An exited child stays
/// a zombie reserving its pid until the caller's own `wait()`. It cannot name a different
/// process group by the time the signal lands.
///
/// The same unreaped zombie means the escalation's liveness probe reads the
/// group as alive for the entire grace, so its final SIGKILL fires even when
/// every member exited on the TERM. Accepted: that sweep is a no-op against a
/// dead group (see [`terminate_process_group`]), and holding the zombie
/// is what pins the pgid.
#[cfg(unix)]
fn kill_timed_out_tree(pid: u32) {
    terminate_process_group(pid as i32);
}

/// `taskkill /T` walks the child tree Windows has no process group for; `/F`
/// forces. Best-effort — the pid may already be gone, or have left children
/// that detached from it.
#[cfg(windows)]
fn kill_timed_out_tree(pid: u32) {
    let mut command = Command::new("taskkill");
    command
        .args(["/T", "/F", "/PID", &pid.to_string()])
        .stdout(Stdio::null())
        .stderr(Stdio::null());
    let _ = spawn(&mut command).and_then(|mut child| child.wait());
}

// ============================================================================
// Builder-style command execution
// ============================================================================

/// Builder for executing commands with two modes of operation.
///
/// - `.run()` — captures output, provides logging/semaphore/tracing
/// - `.stream()` — inherits stdout/stderr for TTY preservation (hooks, interactive);
///   stdin defaults to null unless configured with `.stdin(Stdio)` or `.stdin_bytes()`
///
/// # Examples
///
/// Capture output:
/// ```no_run
/// use worktrunk::shell_exec::Cmd;
/// # fn example(repo_path: std::path::PathBuf) -> Result<(), Box<dyn std::error::Error>> {
/// let output = Cmd::new("git")
///     .args(["status", "--porcelain"])
///     .current_dir(&repo_path)
///     .context("my-worktree")
///     .run()?;
/// # let _ = output;
/// # Ok(())
/// # }
/// ```
///
/// Stream output (hooks, interactive):
/// ```no_run
/// use std::process::Stdio;
/// use worktrunk::shell_exec::Cmd;
/// # fn example(repo_path: std::path::PathBuf) -> Result<(), Box<dyn std::error::Error>> {
/// Cmd::shell("npm run build")
///     .current_dir(&repo_path)
///     .stdout(Stdio::from(std::io::stderr()))
///     .forward_signals()
///     .stream()?;
/// # Ok(())
/// # }
/// ```
pub struct Cmd {
    /// Program name or shell command string (if shell_wrap is true)
    program: String,
    args: Vec<OsString>,
    current_dir: Option<std::path::PathBuf>,
    context: Option<String>,
    stdin_data: Option<Vec<u8>>,
    /// Redact captured stdin/stdout/stderr in both subprocess log targets.
    sensitive_output: bool,
    timeout: Option<std::time::Duration>,
    /// Environment mutations in call order: `Some(value)` sets, `None`
    /// removes. One ordered list rather than a set list plus a remove list, so
    /// the last builder call naming a variable wins — the property
    /// [`Cmd::scrub_git_discovery_env`] relies on when a caller drops the whole
    /// inherited git context and then supplies its own value for one of those
    /// vars (`TempIndex`'s `GIT_INDEX_FILE`, a redirected repository's
    /// `GIT_OBJECT_DIRECTORY`).
    env_ops: Vec<(OsString, Option<OsString>)>,
    /// If true, wrap command through ShellConfig (for stream())
    shell_wrap: bool,
    /// Stdout configuration for stream() (defaults to inherit)
    stdout_cfg: Option<std::process::Stdio>,
    /// Stdin configuration for stream() (defaults to null; stdin_data takes precedence)
    stdin_cfg: Option<std::process::Stdio>,
    /// Observe terminal signals and forward PID-targeted cancellation during stream().
    forward_signals: Option<TerminalInterrupt>,
    /// If true, treat a SIGPIPE exit as success. This is the default for pager
    /// producers, where the consumer closing early is expected. Direct user
    /// programs can opt out with [`Cmd::propagate_sigpipe`].
    ignore_sigpipe: bool,
    /// When set, log this command to the command log after execution.
    /// The label identifies what triggered the command (e.g., "pre-merge user:lint").
    external_label: Option<String>,
    /// When set, re-adds `WORKTRUNK_DIRECTIVE_CD_FILE` after the security scrub
    /// in `apply_common_settings`. Used by aliases and foreground hooks — their
    /// shell bodies may emit cd directives (the file holds a raw path, no shell
    /// injection surface).
    directive_cd_file: Option<std::path::PathBuf>,
    /// If true, cancellation stops this command from spawning but never
    /// signals it once running. Set via [`Cmd::finish_once_started`].
    finish_once_started: bool,
}

struct ExternalCommandLog {
    label: Option<String>,
    cmd_str: String,
    started_at: Option<Instant>,
}

impl ExternalCommandLog {
    fn new(label: Option<String>, cmd_str: String) -> Self {
        let started_at = label.as_ref().map(|_| Instant::now());
        Self {
            label,
            cmd_str,
            started_at,
        }
    }

    fn record(&self, exit_code: Option<i32>) {
        if let Some(label) = &self.label {
            let duration = self.started_at.as_ref().map(Instant::elapsed);
            crate::command_log::log_command(label, &self.cmd_str, exit_code, duration);
        }
    }
}

/// Resolve a [`CommandTrace`] from a finished `run`/`pipe_into` invocation and
/// surface the command's captured stdin/stdout/stderr to the debug log.
///
/// The buffered counterpart to calling `complete`/`fail` directly: `run` and
/// `pipe_into` capture output, so they also feed it to [`log_output`] — stdin
/// regardless of outcome, stdout/stderr when the command produced any.
/// `stream`/`delayed_stream` inherit or stream stdio and resolve their
/// `CommandTrace` directly at each exit point.
fn record_captured(
    trace: &mut CommandTrace,
    stdin: Option<&[u8]>,
    result: &std::io::Result<std::process::Output>,
    sensitive: bool,
) {
    match result {
        Ok(output) => trace.complete(output.status.success()),
        Err(e) => trace.fail(e),
    }
    // Redact every stream together, including input when spawning failed.
    log_output(trace, stdin, result.as_ref().ok(), sensitive);
}

/// A child from [`Cmd::spawn_captured`], traced from spawn until
/// [`Self::wait`] reaps it.
struct CapturedChild {
    child: std::process::Child,
    trace: CommandTrace,
    sensitive_output: bool,
    _tracked: Option<BackgroundPid>,
}

impl CapturedChild {
    fn wait(self) -> std::io::Result<std::process::Output> {
        let CapturedChild {
            child,
            mut trace,
            sensitive_output,
            _tracked,
        } = self;
        let result = child.wait_with_output();
        record_captured(&mut trace, None, &result, sensitive_output);
        result
    }
}

/// A spawn failure identifies the program and cwd actually supplied to the OS.
/// `NotFound` can mean a missing program, cwd, or interpreter, so it does not
/// establish which is absent. Keep the original I/O error as the source.
#[derive(Debug)]
struct SpawnError {
    program: std::ffi::OsString,
    cwd: Option<std::path::PathBuf>,
    source: std::io::Error,
}

impl std::fmt::Display for SpawnError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Failed to execute {}", self.program.to_string_lossy())?;
        if let Some(cwd) = &self.cwd {
            write!(f, " @ {}", format_path_for_display(cwd))?;
        }
        Ok(())
    }
}

impl std::error::Error for SpawnError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.source)
    }
}

/// Enrich an OS spawn failure without changing its kind or guessing its cause.
fn spawn_error(command: &std::process::Command, source: std::io::Error) -> std::io::Error {
    let cwd = command.get_current_dir().map(std::path::Path::to_path_buf);
    std::io::Error::new(
        source.kind(),
        SpawnError {
            program: command.get_program().to_os_string(),
            cwd,
            source,
        },
    )
}

/// Structured error from [`Cmd::delayed_stream`].
///
/// Separates command output from command identity so callers can format each
/// part with appropriate styling (e.g., bold command, gray exit code). The
/// streaming counterpart to [`crate::git::CommandError`]: the delayed-stream
/// path interleaves stdout/stderr into a single buffer, so a string body is
/// the most it can recover. `Repository::extract_failed_command` downcasts
/// this to render git's failure to the user.
#[derive(Debug)]
pub struct StreamCommandError {
    /// Lines of output from the command (may be empty).
    pub output: String,
    /// The command string, e.g., "git worktree add /path -b fix main".
    pub command: String,
    /// Native status, retaining signal identity for cancellation and rendering.
    pub status: std::process::ExitStatus,
}

impl std::fmt::Display for StreamCommandError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Callers use Repository::extract_failed_command() to access fields
        // directly. This Display impl exists only to satisfy the Error trait
        // bound.
        write!(f, "{}", self.output)
    }
}

impl StreamCommandError {
    pub fn exit_info(&self) -> String {
        #[cfg(unix)]
        let signal = std::os::unix::process::ExitStatusExt::signal(&self.status);
        #[cfg(not(unix))]
        let signal = None;
        crate::git::process_exit_description(self.status.code(), signal)
    }
}

impl std::error::Error for StreamCommandError {}

/// Shared state between [`Cmd::delayed_stream`] and its two reader threads.
///
/// `streaming` lives *inside* the mutex rather than beside it as an atomic so
/// that a reader cannot consult it without also holding the buffer. The
/// ordering guarantee this type exists for depends on the check and the write
/// being one critical section (see [`spawn_delayed_reader`]), and an atomic
/// makes a lock-free read the natural thing to write.
#[derive(Default)]
struct DelayedOutput {
    /// Once set, readers write to stderr instead of buffering.
    streaming: bool,
    /// Lines held back before the switch: drained to stderr behind the
    /// progress message, or joined into the error body when the command fails
    /// before streaming ever starts.
    lines: Vec<String>,
}

/// Convert a finished child's exit status into `Ok(())` or a
/// [`StreamCommandError`] carrying the buffered output.
fn stream_exit_result(
    status: std::process::ExitStatus,
    state: &Arc<Mutex<DelayedOutput>>,
    cmd_str: &str,
) -> anyhow::Result<()> {
    if status.success() {
        return Ok(());
    }
    let lines = &state.lock().unwrap().lines;
    Err(StreamCommandError {
        output: lines.join("\n"),
        command: cmd_str.to_string(),
        status,
    }
    .into())
}

/// Decode a streamed line, trimming a trailing newline/carriage return and
/// replacing invalid UTF-8 without dropping later command diagnostics.
pub fn output_line(bytes: &[u8]) -> std::borrow::Cow<'_, str> {
    let bytes = bytes.strip_suffix(b"\n").unwrap_or(bytes);
    let bytes = bytes.strip_suffix(b"\r").unwrap_or(bytes);
    String::from_utf8_lossy(bytes)
}

/// Spawn a reader thread for [`Cmd::delayed_stream`]: each line is written to
/// stderr live once the switch to streaming has happened, or buffered (for the
/// quiet-fast and pre-threshold cases) until then. Both the child's stdout and
/// stderr use this; everything routes to stderr to keep our stdout clean.
///
/// One [`DelayedOutput`] guard covers both reading `streaming` and writing the
/// line, and the switch sets that same field under that same lock. So each
/// line lands on one side of the switch or the other: it is either buffered,
/// and so drained in order behind the progress message, or written after that
/// drain has finished. Were the flag readable without the lock, a reader could
/// observe the flip and print between the progress message and the drain — or
/// ahead of the progress message entirely, which is what a zero delay makes
/// routine, since nothing has to be buffered first.
fn spawn_delayed_reader<R: Read + Send + 'static>(
    stream: R,
    state: Arc<Mutex<DelayedOutput>>,
) -> std::thread::JoinHandle<std::io::Result<()>> {
    std::thread::spawn(move || {
        let mut reader = BufReader::new(stream);
        let mut bytes = Vec::new();
        while reader.read_until(b'\n', &mut bytes)? != 0 {
            let line = output_line(&bytes);
            let mut state = state
                .lock()
                .map_err(|_| std::io::Error::other("Command output state poisoned"))?;
            if state.streaming {
                eprintln!("{}", line);
            } else {
                state.lines.push(line.into_owned());
            }
            bytes.clear();
        }
        Ok(())
    })
}

/// Convert a reader's thread panic or I/O failure into the output error channel.
fn output_reader_result<T>(joined: std::thread::Result<std::io::Result<T>>) -> std::io::Result<T> {
    joined
        .map_err(|_| std::io::Error::other("Command output reader panicked"))
        .and_then(|result| result)
}

/// Join every reader before returning the first I/O or thread failure.
fn join_delayed_readers(
    handles: [std::thread::JoinHandle<std::io::Result<()>>; 2],
) -> std::io::Result<()> {
    let mut result = Ok(());
    for handle in handles {
        let reader_result = output_reader_result(handle.join());
        result = result.and(reader_result);
    }
    result
}

/// The batch launcher a bare program name resolves to on PATH, if any.
///
/// `std::process::Command` resolves a bare name like `az` to `az.exe` only: it
/// neither walks `PATHEXT` nor falls back to `az.cmd`. Some CLIs ship only a
/// batch launcher — Azure CLI's WinGet install has `az.cmd` plus an
/// extensionless bash script, and no `az.exe` — so a bare spawn fails with
/// `NotFound` although the shell runs them. `which` follows `PATHEXT` and skips
/// files Windows can't execute; when what it finds is a `.cmd` or `.bat`, its
/// full path is what to spawn, and std then applies its batch-file argument
/// quoting. Any other result keeps the bare name and std's own search order.
///
/// Resolved once per name: PATH doesn't change during a run, and the search
/// stats every `PATHEXT` candidate in every PATH directory.
#[cfg(windows)]
fn windows_batch_launcher(program: &str) -> Option<PathBuf> {
    use std::collections::HashMap;

    static RESOLVED: OnceLock<Mutex<HashMap<String, Option<PathBuf>>>> = OnceLock::new();

    let path = Path::new(program);
    if path.extension().is_some() || path.components().count() != 1 {
        return None;
    }
    let mut resolved = RESOLVED
        .get_or_init(Default::default)
        .lock()
        .unwrap_or_else(|e| e.into_inner());
    resolved
        .entry(program.to_string())
        .or_insert_with(|| {
            which::which(program).ok().filter(|found| {
                found.extension().is_some_and(|ext| {
                    ext.eq_ignore_ascii_case("cmd") || ext.eq_ignore_ascii_case("bat")
                })
            })
        })
        .clone()
}

impl Cmd {
    fn builder(program: impl Into<String>, shell_wrap: bool) -> Self {
        Self {
            program: program.into(),
            args: Vec::new(),
            current_dir: None,
            context: None,
            stdin_data: None,
            sensitive_output: false,
            timeout: None,
            env_ops: Vec::new(),
            shell_wrap,
            stdout_cfg: None,
            stdin_cfg: None,
            forward_signals: None,
            ignore_sigpipe: true,
            external_label: None,
            directive_cd_file: None,
            finish_once_started: false,
        }
    }

    /// Create a new command builder for the given program.
    ///
    /// The program is executed directly without shell interpretation.
    /// For shell commands (with pipes, redirects, etc.), use [`Cmd::shell()`].
    pub fn new(program: impl Into<String>) -> Self {
        Self::builder(program, false)
    }

    /// Create a command builder for a shell command string.
    ///
    /// The command is executed through the platform's shell (`sh -c` on Unix,
    /// Git Bash on Windows), enabling shell features like pipes and redirects.
    ///
    /// Only valid with `.stream()` — shell commands cannot use `.run()`.
    pub fn shell(command: impl Into<String>) -> Self {
        Self::builder(command, true)
    }

    fn command_string(&self) -> String {
        if self.shell_wrap || self.args.is_empty() {
            self.program.clone()
        } else {
            format!(
                "{} {}",
                self.program,
                self.args
                    .iter()
                    .map(|arg| arg.to_string_lossy())
                    .collect::<Vec<_>>()
                    .join(" ")
            )
        }
    }

    fn direct_command(&self) -> Command {
        #[cfg(windows)]
        let mut cmd = match windows_batch_launcher(&self.program) {
            Some(launcher) => Command::new(launcher),
            None => Command::new(&self.program),
        };
        #[cfg(not(windows))]
        let mut cmd = Command::new(&self.program);
        cmd.args(&self.args);
        cmd
    }

    /// [`Self::check_spawn_preconditions`], after checking that this thread's
    /// commands haven't been cancelled. Background callers check after taking
    /// their semaphore permit: a command can be cancelled while parked on the
    /// semaphore, and that is the common case in a large fan-out.
    fn check_before_spawn(&self, command: &Command) -> std::io::Result<()> {
        if background_cancelled() {
            return Err(cancelled_error());
        }
        self.check_spawn_preconditions(command)
    }

    fn check_spawn_preconditions(&self, command: &Command) -> std::io::Result<()> {
        (|| {
            if let Some(dir) = &self.current_dir {
                let metadata = std::fs::metadata(dir)?;
                if !metadata.is_dir() {
                    return Err(std::io::Error::new(
                        ErrorKind::NotADirectory,
                        format!("{} is not a directory", dir.display()),
                    ));
                }
            }

            let program = Path::new(&self.program);
            if !self.shell_wrap && program.is_absolute() {
                ensure_executable_path(program)?;
            }

            Ok(())
        })()
        .map_err(|error| spawn_error(command, error))
    }

    fn apply_common_settings(&self, cmd: &mut Command) {
        if let Some(dir) = &self.current_dir {
            cmd.current_dir(dir);
        }

        // Normalize inherited relative `GIT_*` path variables (e.g. the
        // `GIT_DIR=.git` git sets for shell aliases) to absolute paths
        // resolved against the startup cwd, so they don't re-resolve against
        // the child's `current_dir`. See issue #1914.
        for (key, val) in inherited_git_env_overrides() {
            cmd.env(key, val);
        }

        // Before `self.env_ops`, so a per-command env can override the floor.
        apply_hermetic_test_env(cmd);

        // In builder-call order, so the last mutation naming a variable wins.
        for (key, val) in &self.env_ops {
            match val {
                Some(val) => cmd.env(key, val),
                None => cmd.env_remove(key),
            };
        }

        // Prevent subprocesses from writing shell directives (security).
        // Applied last so it can't be re-added by user-provided envs.
        // `stream()` selectively re-adds `WORKTRUNK_DIRECTIVE_CD_FILE` for
        // trusted contexts.
        scrub_directive_env_vars(cmd);
    }

    fn log_run_start(&self, cmd_str: &str) {
        tracing::debug!("{}", command_header(cmd_str, self.context.as_deref()));
    }

    fn log_stream_start(&self, cmd_str: &str, exec_mode: &str) {
        tracing::debug!(
            "{} (streaming, {})",
            command_header(cmd_str, self.context.as_deref()),
            exec_mode
        );
    }

    fn log_delayed_stream_start(&self, cmd_str: &str, delay_ms: i64) {
        tracing::debug!(
            "{} (delayed stream, {}ms)",
            command_header(cmd_str, self.context.as_deref()),
            delay_ms
        );
    }

    /// Add a single argument.
    pub fn arg(mut self, arg: impl AsRef<OsStr>) -> Self {
        self.args.push(arg.as_ref().to_os_string());
        self
    }

    /// Add multiple arguments.
    pub fn args<I, S>(mut self, args: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: AsRef<OsStr>,
    {
        self.args
            .extend(args.into_iter().map(|arg| arg.as_ref().to_os_string()));
        self
    }

    /// Set the working directory for the command.
    pub fn current_dir(mut self, dir: impl Into<std::path::PathBuf>) -> Self {
        self.current_dir = Some(dir.into());
        self
    }

    /// Set the logging context (typically worktree name for git commands).
    pub fn context(mut self, ctx: impl Into<String>) -> Self {
        self.context = Some(ctx.into());
        self
    }

    /// Set complete input bytes, prepared by [`buffered_stdin`] before spawn.
    ///
    /// The child reads these bytes followed by EOF, without a pipe writer that
    /// can block on an unread input. This takes precedence over `.stdin(Stdio)`.
    pub fn stdin_bytes(mut self, data: impl Into<Vec<u8>>) -> Self {
        self.stdin_data = Some(data.into());
        self
    }

    /// Redact captured stdin, stdout, and stderr from debug logs.
    ///
    /// Status and timing are still traced, and callers receive the original
    /// output. In a pipeline, both commands' captured output is redacted.
    /// Command arguments remain visible; streaming output is unaffected.
    pub fn sensitive_output(mut self) -> Self {
        self.sensitive_output = true;
        self
    }

    /// Set a timeout for command execution (only applies to `.run()`).
    ///
    /// Note: Timeout is not supported by `.stream()` since streaming commands
    /// are interactive and should not be time-limited.
    ///
    /// A timed command runs in its own process group so expiry can tear down
    /// its whole tree, which also means Ctrl-C no longer reaches it — see
    /// `run_with_timeout_impl` for both halves of that.
    pub fn timeout(mut self, duration: std::time::Duration) -> Self {
        self.timeout = Some(duration);
        self
    }

    /// Let this command run to completion once spawned, even if background
    /// work is cancelled meanwhile ([`cancel_background_commands`]). A
    /// cancelled command that hasn't spawned yet still never does.
    ///
    /// For commands whose interruption leaves debris SIGTERM doesn't clean:
    /// `git merge-tree` writes its external merge driver's inputs as
    /// `.merge_file_XXXXXX` files in its cwd and removes them only on a normal
    /// return, so a signal mid-driver strands them in the user's worktree.
    ///
    /// Only affects `.run()`.
    pub fn finish_once_started(mut self) -> Self {
        self.finish_once_started = true;
        self
    }

    /// [`track_if_cancellable`], unless [`Cmd::finish_once_started`] opted out.
    fn track_if_cancellable(&self, pid: u32) -> Option<BackgroundPid> {
        (!self.finish_once_started)
            .then(|| track_if_cancellable(pid))
            .flatten()
    }

    /// Set an environment variable.
    ///
    /// Accepts the same types as [`Command::env`]: string literals, `String`,
    /// `&Path`, `PathBuf`, `OsString`, etc.
    pub fn env(mut self, key: impl AsRef<OsStr>, val: impl AsRef<OsStr>) -> Self {
        self.env_ops.push((
            key.as_ref().to_os_string(),
            Some(val.as_ref().to_os_string()),
        ));
        self
    }

    /// Remove an environment variable.
    ///
    /// A later [`Cmd::env`] for the same variable overrides this.
    pub fn env_remove(mut self, key: impl AsRef<OsStr>) -> Self {
        self.env_ops.push((key.as_ref().to_os_string(), None));
        self
    }

    /// Scrub inherited git-discovery vars ([`INHERITED_GIT_PATH_VARS`]) from the
    /// child environment. Applied by every spawn site whose `current_dir` names
    /// a worktree `wt` chose — relocated user commands (hooks, `wt step
    /// for-each`, the `--execute` program) and `wt`'s own worktree-local
    /// plumbing ([`crate::git::WorkingTree::run_command`], `TempIndex`) alike —
    /// so git discovers the repository from that working directory, not a
    /// `GIT_DIR`/`GIT_WORK_TREE` `wt` inherited. See
    /// [`scrub_git_discovery_env_vars`] for the site classification (issue #3373).
    ///
    /// Applied after the inherited-`GIT_*` absolutization in
    /// `apply_common_settings`, so it also drops the relative-path
    /// absolutization that would otherwise re-add these vars.
    ///
    /// A site that supplies its own value for one of the scrubbed vars calls
    /// [`Cmd::env`] *after* this: `env_ops` is call-ordered, so the set wins.
    pub fn scrub_git_discovery_env(mut self) -> Self {
        for var in INHERITED_GIT_PATH_VARS {
            self.env_ops.push((OsString::from(*var), None));
        }
        self
    }

    /// Set stdout configuration for `.stream()`.
    ///
    /// Defaults to `Stdio::inherit()`. Use `Stdio::from(io::stderr())` to redirect
    /// stdout to stderr for deterministic output ordering.
    ///
    /// Only affects `.stream()`. For `.run()`, output is always captured separately.
    pub fn stdout(mut self, cfg: std::process::Stdio) -> Self {
        self.stdout_cfg = Some(cfg);
        self
    }

    /// Set stdin configuration for `.stream()`.
    ///
    /// Defaults to `Stdio::null()`. For interactive commands that need the
    /// parent's input, use [`Cmd::inherit_stdin()`] instead. Foreground group
    /// membership and access to `/dev/tty` are independent of stdin.
    ///
    /// Only affects `.stream()`. For `.run()`, stdin defaults to null unless
    /// data is provided via `.stdin_bytes()`.
    pub fn stdin(mut self, cfg: std::process::Stdio) -> Self {
        self.stdin_cfg = Some(cfg);
        self
    }

    /// Inherit the parent's stdin for interactive input.
    ///
    /// Foreground group membership is independent of this setting.
    pub fn inherit_stdin(mut self) -> Self {
        self.stdin_cfg = Some(std::process::Stdio::inherit());
        self
    }

    /// Preserve terminal Ctrl-C delivery and forward SIGTERM to live children.
    ///
    /// The child shares the caller's foreground group, so it receives the key
    /// alongside wt. wt's own receipt of SIGINT cancels the command once the
    /// child exits ([`TerminalInterrupt::Cancels`]); signal exits do too.
    /// Only affects `.stream()` on Unix. No-op on Windows.
    pub fn forward_signals(mut self) -> Self {
        self.forward_signals = Some(TerminalInterrupt::Cancels);
        self
    }

    /// [`Cmd::forward_signals`] for the command's final, interactive child,
    /// which owns a terminal Ctrl-C as input ([`TerminalInterrupt::ChildInput`]).
    pub fn hand_off_terminal(mut self) -> Self {
        self.forward_signals = Some(TerminalInterrupt::ChildInput);
        self
    }

    /// Preserve SIGPIPE as exit status 141 instead of treating it as pager
    /// completion.
    ///
    /// `Cmd::stream()` historically ignores SIGPIPE because many callers feed
    /// a pager that may quit before consuming all output. Use this for a child
    /// whose status belongs to the user, such as `wt switch --execute`.
    pub fn propagate_sigpipe(mut self) -> Self {
        self.ignore_sigpipe = false;
        self
    }

    /// Mark this command as an external (user-configured) command for logging.
    ///
    /// When set, the command execution is logged to `.git/wt/logs/commands.jsonl`
    /// with the given label (e.g., "pre-merge user:lint", "commit.generation").
    pub fn external(mut self, label: impl Into<String>) -> Self {
        self.external_label = Some(label.into());
        self
    }

    /// Pass the CD directive file through to the child process.
    ///
    /// By default, `Cmd` scrubs all directive file env vars from child
    /// processes. This re-adds `WORKTRUNK_DIRECTIVE_CD_FILE` for trusted
    /// contexts (aliases, foreground hooks) where the child should be able
    /// to request a directory change. It is always safe to pass through: the
    /// file holds a raw path, not shell, so there is no injection surface.
    pub fn directive_cd_file(mut self, path: impl Into<std::path::PathBuf>) -> Self {
        self.directive_cd_file = Some(path.into());
        self
    }

    /// Execute the command and return its output.
    ///
    /// Captures stdout/stderr and returns them in `Output`. For interactive
    /// commands or hooks where output should stream to the terminal, use
    /// `.stream()` instead.
    ///
    /// # Panics
    ///
    /// Panics if called on a shell-wrapped command (created via `Cmd::shell()`).
    /// Shell commands must use `.stream()` because they need TTY preservation.
    pub fn run(self) -> std::io::Result<std::process::Output> {
        assert!(
            !self.shell_wrap,
            "Cmd::shell() commands must use .stream(), not .run()"
        );
        debug_assert!(
            self.directive_cd_file.is_none(),
            "directive_*_file is only applied by .stream(), not .run()"
        );

        let cmd_str = self.command_string();
        let external_log = ExternalCommandLog::new(self.external_label.clone(), cmd_str.clone());
        self.log_run_start(&cmd_str);

        // Limit concurrent commands (background threads only; see CMD_SEMAPHORE)
        let _guard = (!is_foreground_thread()).then(|| semaphore().acquire());

        let mut trace = CommandTrace::new(self.context.as_deref(), &cmd_str)
            .reads_stdin(self.stdin_data.is_some());

        let mut cmd = self.direct_command();
        self.apply_common_settings(&mut cmd);

        if let Err(e) = self.check_before_spawn(&cmd) {
            trace.fail(&e);
            external_log.record(None);
            return Err(e);
        }

        // Preparation failures and child outcomes resolve the same trace.
        let result = (|| {
            let stdin = self
                .stdin_data
                .as_deref()
                .map(buffered_stdin)
                .transpose()?
                .unwrap_or_else(Stdio::null);
            cmd.stdin(stdin)
                .stdout(Stdio::piped())
                .stderr(Stdio::piped());
            if let Some(timeout) = self.timeout {
                run_with_timeout_impl(&mut cmd, timeout, !self.finish_once_started)
            } else {
                let child = spawn(&mut cmd)?;
                let _tracked = self.track_if_cancellable(child.id());
                child.wait_with_output()
            }
        })();

        record_captured(
            &mut trace,
            self.stdin_data.as_deref(),
            &result,
            self.sensitive_output,
        );

        let exit_code = result.as_ref().ok().and_then(|output| output.status.code());
        external_log.record(exit_code);

        result
    }

    /// Run `cmds` as concurrent child processes and return each one's output,
    /// in input order.
    ///
    /// Every child is spawned before any is waited on, so a batch of short
    /// commands costs about one command's latency without a thread per
    /// command. Outputs are read one child at a time, in order, so a child
    /// that writes more than a pipe buffer blocks until its turn: use this
    /// for commands with small output.
    ///
    /// The caller waits only on its own children, which makes this safe where
    /// a thread pool is not: inside a cache initializer that pool jobs also
    /// read. A rayon thread that waits runs other pool jobs, and a job that
    /// reads the cache being initialized then deadlocks.
    ///
    /// On a background thread the batch takes one semaphore permit, as
    /// [`Self::pipe_into`] does: one permit per child could deadlock two
    /// batches that each hold part of the pool. A batch runs at most
    /// `max_concurrent_commands()` children at once; other threads' commands
    /// are not counted against it. Stdin, timeouts,
    /// `external()` logging and shell commands are not supported.
    pub fn run_concurrently(cmds: &[Cmd]) -> Vec<std::io::Result<std::process::Output>> {
        assert!(
            cmds.iter().all(|cmd| !cmd.shell_wrap
                && cmd.stdin_data.is_none()
                && cmd.timeout.is_none()
                && cmd.external_label.is_none()),
            "run_concurrently supports captured commands without stdin, timeout, external() or shell"
        );

        let _guard = (!is_foreground_thread()).then(|| semaphore().acquire());

        let mut results = Vec::with_capacity(cmds.len());
        for chunk in cmds.chunks(max_concurrent_commands()) {
            let children: Vec<_> = chunk.iter().map(Cmd::spawn_captured).collect();
            results.extend(
                children
                    .into_iter()
                    .map(|child| child.and_then(CapturedChild::wait)),
            );
        }
        results
    }

    /// Spawn `self` with piped stdout/stderr and null stdin, without waiting.
    /// A failure to spawn resolves the trace before returning.
    fn spawn_captured(&self) -> std::io::Result<CapturedChild> {
        let cmd_str = self.command_string();
        self.log_run_start(&cmd_str);
        let mut trace = CommandTrace::new(self.context.as_deref(), &cmd_str);

        let mut cmd = self.direct_command();
        self.apply_common_settings(&mut cmd);

        if let Err(e) = self.check_before_spawn(&cmd) {
            trace.fail(&e);
            return Err(e);
        }

        cmd.stdin(Stdio::null())
            .stdout(Stdio::piped())
            .stderr(Stdio::piped());
        match spawn(&mut cmd) {
            Ok(child) => {
                let tracked = self.track_if_cancellable(child.id());
                Ok(CapturedChild {
                    child,
                    trace,
                    sensitive_output: self.sensitive_output,
                    _tracked: tracked,
                })
            }
            Err(e) => {
                trace.fail(&e);
                Err(e)
            }
        }
    }

    /// Run `self` with its stdout piped directly into `next`'s stdin, and
    /// return both children's captured output.
    ///
    /// The intermediate data (`self`'s stdout) flows between the two child
    /// processes via an OS pipe — it never lands in our process memory or
    /// debug logs. This keeps large intermediate outputs (for example
    /// `git diff-tree -p | git patch-id`) out of the `-vv` trace stream, where
    /// `log_output` would otherwise dump every line of the raw diff.
    ///
    /// The source's *own* stdin (`stdin_bytes`, e.g. the `git rev-list` commit
    /// list) is logged under `  < ` like any `.run()` command — only the
    /// intermediate stream above is suppressed.
    ///
    /// Each command is logged and traced individually (same format as
    /// `.run()`), so `-vv` still shows both commands and their exit status.
    /// The returned tuple is `(source_output, sink_output)` — callers can
    /// inspect either child's exit status and stderr. `source_output.stdout`
    /// is empty (it was routed to the sink via OS pipe).
    ///
    /// `stdin_bytes` on the source feeds the pipeline's input (the sink's
    /// stdin always comes from the source). Timeouts and `external()` logging
    /// are not supported on either side. On a background thread the pipeline
    /// consumes one semaphore permit even though it runs two processes
    /// concurrently — acquiring two would deadlock under `concurrency = 1`;
    /// the foreground thread is exempt (see `CMD_SEMAPHORE`).
    pub fn pipe_into(
        mut self,
        next: Cmd,
    ) -> std::io::Result<(std::process::Output, std::process::Output)> {
        assert!(
            !self.shell_wrap && !next.shell_wrap,
            "Cmd::shell() commands cannot be used with pipe_into"
        );
        assert!(
            next.stdin_data.is_none(),
            "pipe_into sink cannot use stdin_bytes (stdin comes from source)"
        );
        assert!(
            self.timeout.is_none() && next.timeout.is_none(),
            "pipe_into does not support timeouts"
        );
        assert!(
            self.external_label.is_none() && next.external_label.is_none(),
            "pipe_into does not support external() logging"
        );
        debug_assert!(
            self.directive_cd_file.is_none() && next.directive_cd_file.is_none(),
            "directive_*_file is only applied by .stream(), not pipe_into"
        );

        let first_cmd_str = self.command_string();
        let second_cmd_str = next.command_string();
        let sensitive = self.sensitive_output || next.sensitive_output;
        self.log_run_start(&first_cmd_str);
        next.log_run_start(&second_cmd_str);

        let _guard = (!is_foreground_thread()).then(|| semaphore().acquire());

        let mut first = self.direct_command();
        self.apply_common_settings(&mut first);
        let mut second = next.direct_command();
        next.apply_common_settings(&mut second);

        // Validate both commands before spawning either. Nothing has spawned
        // yet, so a cancellation or precondition failure emits a one-shot
        // failed record rather than holding a guard across an execution that
        // never happens.
        if let Err(e) = self.check_before_spawn(&first) {
            // stdin_data is still owned here (taken below), so it reflects
            // whether the source would have read a buffer; the sink always reads
            // the upstream pipe.
            CommandTrace::record_failed(
                self.context.as_deref(),
                &first_cmd_str,
                self.stdin_data.is_some(),
                &e,
            );
            return Err(e);
        }
        if let Err(e) = next.check_spawn_preconditions(&second) {
            CommandTrace::record_failed(next.context.as_deref(), &second_cmd_str, true, &e);
            return Err(e);
        }

        let source_stdin = self.stdin_data.take();

        let mut first_trace = CommandTrace::new(self.context.as_deref(), &first_cmd_str)
            .reads_stdin(source_stdin.is_some());
        let input = source_stdin
            .as_deref()
            .map(buffered_stdin)
            .transpose()
            .inspect_err(|error| {
                first_trace.fail(error);
            })?
            .unwrap_or_else(Stdio::null);
        first
            .stdin(input)
            .stdout(Stdio::piped())
            .stderr(Stdio::piped());
        let mut first_child = match spawn(&mut first) {
            Ok(child) => child,
            Err(e) => {
                first_trace.fail(&e);
                return Err(e);
            }
        };
        let _first_tracked = track_if_cancellable(first_child.id());
        let first_stdout = first_child
            .stdout
            .take()
            .expect("stdout was configured as piped");
        second
            .stdin(Stdio::from(first_stdout))
            .stdout(Stdio::piped())
            .stderr(Stdio::piped());

        // Spawn `next` before waiting on either child so `self`'s stdout keeps
        // flowing through the pipe (otherwise a full pipe buffer would wedge
        // `self`). If the spawn itself fails, clean up `self` before returning.
        let mut second_trace =
            CommandTrace::new(next.context.as_deref(), &second_cmd_str).reads_stdin(true);
        let second_child = match spawn(&mut second) {
            Ok(child) => child,
            Err(e) => {
                second_trace.fail(&e);
                let _ = first_child.kill();
                let _ = first_child.wait();
                // `first` spawned but is being torn down because the pipeline
                // can't run — record it as a non-success rather than leaving
                // the guard unresolved.
                first_trace.complete(false);
                return Err(e);
            }
        };
        let _second_tracked = track_if_cancellable(second_child.id());

        // `first`'s stderr must be drained concurrently with `second`'s
        // execution; otherwise pathological stderr volume (~64 KiB pipe
        // buffer) could block `first` on write, which then never closes its
        // stdout, which wedges `second`. Scoped thread drains in parallel.
        let mut first_stderr_pipe = first_child
            .stderr
            .take()
            .expect("stderr was configured as piped");

        let (first_result, second_result) = std::thread::scope(|s| {
            let stderr_thread = s.spawn(move || {
                let mut buf = Vec::new();
                first_stderr_pipe.read_to_end(&mut buf).map(|_| buf)
            });

            // Drain `next` first (its `wait_with_output` reads its own
            // stdout/stderr), so `first`'s writes can complete. Its stdin is the
            // source's stdout (the OS pipe), not its own input, so it is logged
            // with `None` — the intermediate stream stays out of the deep log.
            let second_result = second_child.wait_with_output();
            record_captured(&mut second_trace, None, &second_result, sensitive);

            // Reap `first`. Its stderr is already being drained; combine
            // the captured stderr with the exit status into an Output.
            let first_status = first_child.wait();
            let first_stderr = stderr_thread.join().unwrap();

            let first_result = first_status.and_then(|status| {
                first_stderr.map(|stderr| std::process::Output {
                    status,
                    stdout: Vec::new(),
                    stderr,
                })
            });
            // The source's own stdin (the commit list) is logged under `  < `,
            // symmetric with `run`. Only the intermediate diff stream — the
            // source's stdout, routed to the sink via OS pipe — stays out.
            record_captured(
                &mut first_trace,
                source_stdin.as_deref(),
                &first_result,
                sensitive,
            );

            (first_result, second_result)
        });

        Ok((first_result?, second_result?))
    }

    /// Execute the command with streaming output (inherits stdio).
    ///
    /// Unlike `.run()`, this method:
    /// - Inherits stderr to preserve TTY behavior (colors, progress bars)
    /// - Optionally redirects stdout to stderr (via `.stdout(Stdio::from(io::stderr()))`)
    /// - Optionally inherits stdin for interactive commands (via `.stdin(Stdio::inherit())`)
    /// - Optionally observes terminal signals and forwards cancellation (`.forward_signals()`)
    /// - Does not use concurrency limiting (streaming commands run sequentially by nature)
    /// - Does not support timeout (interactive commands should not be time-limited)
    ///
    /// Shell commands created via `Cmd::shell()` are executed through the platform's
    /// shell (`sh -c` on Unix, Git Bash on Windows).
    ///
    /// Returns error if command exits with non-zero status.
    pub fn stream(mut self) -> anyhow::Result<()> {
        #[cfg(unix)]
        use signal_hook::consts::SIGPIPE;

        // Shell-wrapped commands don't use args (the command string is the full command)
        assert!(
            !self.shell_wrap || self.args.is_empty(),
            "Cmd::shell() cannot use .arg() - include arguments in the shell command string"
        );

        // Build the command - either shell-wrapped or direct
        let (mut cmd, exec_mode) = if self.shell_wrap {
            let shell = ShellConfig::get()?;
            let mode = format!("shell: {}", shell.name);
            (shell.command(&self.program), mode)
        } else {
            (self.direct_command(), "direct".to_string())
        };

        let cmd_str = self.command_string();
        let external_log = ExternalCommandLog::new(self.external_label.take(), cmd_str.clone());
        self.log_stream_start(&cmd_str, &exec_mode);
        self.apply_common_settings(&mut cmd);

        // Re-add directive files after security scrub for trusted contexts.
        // The CD file is safe to pass through because it contains a raw path.
        if let Some(ref path) = self.directive_cd_file {
            apply_cd_directive_env(&mut cmd, path);
        }

        if let Err(e) = self.check_spawn_preconditions(&cmd) {
            // Nothing spawned yet — emit a one-shot failed record (the trace
            // guard is constructed just before spawn, below).
            CommandTrace::record_failed(
                self.context.as_deref(),
                &cmd_str,
                self.stdin_data.is_some(),
                &e,
            );
            return Err(e.into());
        }

        #[cfg(not(unix))]
        let _ = self.forward_signals;

        // Determine stdout handling (default: inherit)
        let stdout_mode = self.stdout_cfg.unwrap_or_else(std::process::Stdio::inherit);

        let stdin = match self.stdin_data.as_deref() {
            Some(data) => buffered_stdin(data)
                .inspect_err(|error| {
                    CommandTrace::record_failed(self.context.as_deref(), &cmd_str, true, error);
                })
                .context("Failed to prepare command input")?,
            None => self.stdin_cfg.unwrap_or_else(Stdio::null),
        };
        cmd.stdin(stdin);

        // Install the SIGINT/SIGTERM handler BEFORE spawn so a signal arriving
        // mid-spawn is queued, not default-killed.
        #[cfg(unix)]
        let signals = match self.forward_signals {
            Some(mode) => Some(crate::signal_forwarder::ForegroundSignals::install(mode)?),
            None => None,
        };

        // Apply environment and spawn
        cmd.stdout(stdout_mode)
            .stderr(std::process::Stdio::inherit()) // Preserve TTY for errors
            // Prevent vergen "overridden" warning in nested cargo builds
            .env_remove("VERGEN_GIT_DESCRIBE");

        // Start the trace immediately before spawn, after the fallible
        // signal-handler install — so a pre-spawn early return can't drop the
        // guard unresolved, and the duration brackets the child.
        let mut trace = CommandTrace::new(self.context.as_deref(), &cmd_str)
            .reads_stdin(self.stdin_data.is_some());
        #[cfg(unix)]
        let spawned = match &signals {
            Some(signals) => signals.spawn(&mut cmd),
            None => spawn_shared_child(&mut cmd).map_err(anyhow::Error::from),
        };
        #[cfg(not(unix))]
        let spawned = spawn_shared_child(&mut cmd).map_err(anyhow::Error::from);
        let child = match spawned {
            Ok(child) => Arc::new(child),
            Err(error) => {
                trace.fail(error.as_ref());
                return Err(error);
            }
        };

        #[cfg(unix)]
        let waited = match signals {
            Some(signals) => signals
                .wait(&child)
                .map(|outcome| (outcome.status, outcome.cancellation)),
            None => wait_shared_child(&child, None).map(|status| (status, None)),
        };
        #[cfg(not(unix))]
        let waited = wait_shared_child(&child, None).map(|status| (status, None::<i32>));
        let (status, cancellation) = waited
            .inspect_err(|error| {
                let _ = child.kill();
                let _ = child.wait();
                trace.fail(error);
            })
            .context("Failed to wait for command")?;
        #[cfg(unix)]
        let child_signal = std::os::unix::process::ExitStatusExt::signal(&status);

        // SIGPIPE is expected when a pager exits before its producer finishes.
        #[cfg(unix)]
        if child_signal == Some(SIGPIPE) && self.ignore_sigpipe && cancellation.is_none() {
            trace.complete(true);
            external_log.record(Some(0));
            return Ok(());
        }

        if !status.success() || cancellation.is_some() {
            let error = WorktrunkError::from_child_status(&status, cancellation);
            trace.complete(status.success());
            external_log.record(error.exit_code());
            return Err(error.into());
        }

        trace.complete(true);
        external_log.record(Some(0));

        Ok(())
    }

    /// Execute the command with delayed output streaming.
    ///
    /// Buffers stdout/stderr initially; if the command runs longer than
    /// `delay_ms`, switches to streaming both to **stderr** live (keeping our
    /// stdout clean for callers like `wt switch`). Fast commands stay quiet;
    /// slow ones (`git worktree add` on a large repo) show progress. Pass `-1`
    /// to never switch to streaming (always buffer); `0` streams immediately.
    ///
    /// `progress_message`, when set, prints to stderr at the moment streaming
    /// starts. It arrives pre-rendered with its ANSI already in it, so — like
    /// every relayed line — it goes out through [`crate::styling`]'s
    /// `eprintln!` rather than a raw handle: anstream is the only thing that
    /// strips those escapes when stderr is redirected and honors `NO_COLOR`,
    /// and a single raw write here is enough to make one line of a log
    /// disagree with the rest. No `flush()` follows, and none did any work
    /// before: `AutoStream<Stderr>` writes through a locked `std::io::Stderr`,
    /// which is unbuffered. anstream's macro does not flush either, so a
    /// buffered stream would still need one.
    ///
    /// Like [`Cmd::stream`], this does **not** acquire the concurrency
    /// semaphore: a delayed-stream command runs in the foreground and would
    /// only ever contend with itself (and acquiring a permit while one is held
    /// could deadlock under `concurrency = 1`). On a non-zero exit it returns a
    /// [`StreamCommandError`] carrying the buffered output so callers can render
    /// the failure (e.g. git's `fatal: …`).
    ///
    /// # Panics
    ///
    /// Panics if called on a shell-wrapped command (`Cmd::shell()`); the
    /// delayed-stream path runs a program directly.
    pub fn delayed_stream(
        self,
        delay_ms: i64,
        progress_message: Option<String>,
    ) -> anyhow::Result<()> {
        assert!(
            !self.shell_wrap,
            "Cmd::delayed_stream() runs a program directly; Cmd::shell() is not supported"
        );
        debug_assert!(
            self.stdin_data.is_none()
                && self.timeout.is_none()
                && self.external_label.is_none()
                && self.directive_cd_file.is_none(),
            "delayed_stream does not support stdin/timeout/external/directive options"
        );

        // Allow tests to override the delay threshold (-1 to disable, 0 for
        // immediate streaming).
        let delay_ms = std::env::var("WORKTRUNK_TEST_DELAYED_STREAM_MS")
            .ok()
            .and_then(|s| s.parse().ok())
            .unwrap_or(delay_ms);

        let cmd_str = self.command_string();
        self.log_delayed_stream_start(&cmd_str, delay_ms);

        let mut trace = CommandTrace::new(self.context.as_deref(), &cmd_str);

        let mut cmd = self.direct_command();
        self.apply_common_settings(&mut cmd);
        cmd.stdin(Stdio::null())
            .stdout(Stdio::piped())
            .stderr(Stdio::piped());

        let child = match spawn_shared_child(&mut cmd) {
            Ok(child) => child,
            Err(e) => {
                trace.fail(&e);
                return Err(e.into());
            }
        };

        let stdout = child.take_stdout().expect("stdout was piped");
        let stderr = child.take_stderr().expect("stderr was piped");
        #[cfg(unix)]
        let prepared = (|| {
            let (control, cancel) = socket_pair()?;
            let control = Arc::new(control);
            Ok::<_, std::io::Error>((
                pipe::PipeReader::new(stdout, None, Some(control.clone()))?,
                pipe::PipeReader::new(stderr, None, Some(control))?,
                cancel,
            ))
        })();
        #[cfg(unix)]
        let (stdout, stderr, cancel) = match prepared {
            Ok(prepared) => prepared,
            Err(error) => {
                let _ = child.kill();
                let _ = child.wait();
                trace.fail(&error);
                return Err(error).context("Failed to prepare command output");
            }
        };
        #[cfg(unix)]
        let mut cancel = Some(cancel);

        // Shared state: readers stream directly once `streaming` is set, and
        // buffer until then.
        let state = Arc::new(Mutex::new(DelayedOutput::default()));
        let stdout_handle = spawn_delayed_reader(stdout, state.clone());
        let stderr_handle = spawn_delayed_reader(stderr, state.clone());

        let start = Instant::now();

        let wait_result = 'wait: {
            // Phase 1: wait up to the presentation threshold; an early exit stays quiet.
            if delay_ms >= 0 {
                let delay = Duration::from_millis(delay_ms as u64);
                let remaining = delay.saturating_sub(start.elapsed());

                // Zero delay streams immediately, without a zero-timeout reap.
                if !remaining.is_zero() {
                    match wait_shared_child(&child, Some(Instant::now() + remaining)) {
                        Ok(status) => break 'wait Ok(status),
                        // This deadline controls presentation, not child lifetime.
                        // On a timeout or wait-setup error, stream output and retry.
                        outcome => {
                            tracing::debug!(?outcome, "No exit status yet; switching to streaming");
                        }
                    }
                }

                // Switch to streaming under the readers' lock so no line can
                // print between the progress message and the buffered output.
                let mut state = state.lock().unwrap();
                state.streaming = true;
                if let Some(ref msg) = progress_message {
                    eprintln!("{}", msg);
                }
                for line in state.lines.drain(..) {
                    eprintln!("{}", line);
                }
            }

            // Phase 2: block until the child exits.
            wait_shared_child(&child, None)
        };
        #[cfg(unix)]
        if match &wait_result {
            Ok(status) => matches!(
                std::os::unix::process::ExitStatusExt::signal(status),
                Some(signal_hook::consts::SIGINT | signal_hook::consts::SIGTERM)
            ),
            Err(_) => true,
        } {
            cancel.take();
        }
        if wait_result.is_err() {
            let _ = child.kill();
            let _ = child.wait();
        }
        let output_result = join_delayed_readers([stdout_handle, stderr_handle]);
        let status = match wait_result {
            Ok(status) => status,
            Err(e) => {
                trace.fail(&e);
                return Err(e).context("Failed to wait for command");
            }
        };
        if let Err(error) = output_result {
            trace.fail(&error);
            return Err(error).context("Failed to read command output");
        }
        trace.complete(status.success());
        stream_exit_result(status, &state, &cmd_str)
    }
}

// ============================================================================
// Signal forwarding helpers (Unix only)
// ============================================================================

/// Wait for a shared child without holding its signaling lock while stopped.
///
/// Darwin can return a stop from SharedChild's waitid(WEXITED) path. Its
/// subsequent blocking Child::wait holds that lock, preventing CONT and kill.
/// On macOS, subscribe to kernel exit events before try_wait so exit cannot
/// be lost between check and sleep. Other platforms use SharedChild directly.
/// A deadline returns TimedOut without reaping a still-running child.
pub fn wait_shared_child(
    child: &SharedChild,
    deadline: Option<Instant>,
) -> std::io::Result<std::process::ExitStatus> {
    #[cfg(target_os = "macos")]
    let status = wait_macos_child(child, deadline)?;
    #[cfg(not(target_os = "macos"))]
    let status = match deadline {
        Some(deadline) => child.wait_deadline(deadline)?,
        None => Some(child.wait()?),
    };
    let status =
        status.ok_or_else(|| std::io::Error::new(ErrorKind::TimedOut, "command timed out"))?;
    Ok(status)
}

/// Wait for a foreground child and publish native cancellation to current scopes.
/// Captures and diff-preview pagers use the neutral wait instead; their command
/// consumers decide whether to propagate typed cancellation.
pub fn wait_foreground_child(child: &SharedChild) -> std::io::Result<std::process::ExitStatus> {
    let status = wait_shared_child(child, None)?;
    #[cfg(unix)]
    if let Some(signal @ (signal_hook::consts::SIGINT | signal_hook::consts::SIGTERM)) =
        std::os::unix::process::ExitStatusExt::signal(&status)
    {
        crate::signal_forwarder::cancel_foreground(signal);
    }
    Ok(status)
}

#[cfg(target_os = "macos")]
fn wait_macos_child(
    child: &SharedChild,
    deadline: Option<Instant>,
) -> std::io::Result<Option<std::process::ExitStatus>> {
    use nix::errno::Errno;
    use nix::sys::event::{EvFlags, EventFilter, FilterFlag, KEvent, Kqueue};
    let queue = Kqueue::new()?;
    let exit = KEvent::new(
        child.id() as usize,
        EventFilter::EVFILT_PROC,
        EvFlags::EV_ADD | EvFlags::EV_ONESHOT,
        FilterFlag::NOTE_EXIT,
        0,
        0,
    );
    loop {
        let subscribe = queue.kevent(
            &[exit],
            &mut [],
            Some(nix::libc::timespec {
                tv_sec: 0,
                tv_nsec: 0,
            }),
        );
        // A cached status wins over ESRCH if another waiter reaped the child.
        if let Some(status) = child.try_wait()? {
            return Ok(Some(status));
        }
        match subscribe {
            Err(Errno::EINTR) => continue,
            // Darwin can remove the owned process from kqueue lookup before
            // its exit is waitable. Like NOTE_EXIT below, ESRCH means it can
            // no longer stop; finish synchronized reaping rather than fail.
            Err(Errno::ESRCH) => return child.wait().map(Some),
            Err(error) => return Err(error.into()),
            Ok(_) => break,
        }
    }
    let mut events = [exit];
    loop {
        let timeout = deadline.map(|deadline| {
            let duration = deadline.saturating_duration_since(Instant::now());
            nix::libc::timespec {
                tv_sec: duration.as_secs().min(i64::MAX as u64) as _,
                tv_nsec: duration.subsec_nanos().into(),
            }
        });
        let count = match queue.kevent(&[], &mut events, timeout) {
            Ok(count) => count,
            Err(Errno::EINTR) => continue,
            Err(e) => return Err(e.into()),
        };
        let observed = child.try_wait()?;
        if let Some(status) = observed {
            return Ok(Some(status));
        }
        if count == 0 {
            return Ok(None);
        }
        if events[0].flags().contains(EvFlags::EV_ERROR) {
            return Err(Errno::from_raw(events[0].data() as i32).into());
        }
        // NOTE_EXIT precedes waitable zombie state on Darwin. Once exit has
        // begun, this child cannot stop again; the ordinary synchronized wait
        // is now safe and closes the exit-event vs waitable-status gap.
        return child.wait().map(Some);
    }
}

/// Probe whether an owned background process group still exists.
#[cfg(unix)]
fn process_group_alive(pgid: i32) -> bool {
    match nix::sys::signal::killpg(nix::unistd::Pid::from_raw(pgid), None) {
        Ok(_) => true,
        Err(nix::errno::Errno::ESRCH) => false,
        Err(_) => true,
    }
}

/// Poll [`process_group_alive`] until the group is gone or `grace` expires,
/// returning `true` when the group died within the grace. The first probe is
/// immediate, so an already-empty group costs no sleep at all, and a group
/// whose members exit (and are reaped) mid-grace is noticed within one poll
/// interval rather than at the deadline.
#[cfg(unix)]
fn group_died_within(pgid: i32, grace: Duration) -> bool {
    const POLL_INTERVAL: Duration = Duration::from_millis(20);
    let deadline = Instant::now() + grace;
    loop {
        if !process_group_alive(pgid) {
            return true;
        }
        let remaining = deadline.saturating_duration_since(Instant::now());
        if remaining.is_zero() {
            return false;
        }
        std::thread::sleep(remaining.min(POLL_INTERVAL));
    }
}

/// Request cancellation of a recorded background worker by PID. Foreground
/// delivery instead uses SharedChild's synchronized signaling ownership.
#[cfg(unix)]
pub fn terminate_pid(pid: i32) {
    let _ = nix::sys::signal::kill(
        nix::unistd::Pid::from_raw(pid),
        nix::sys::signal::Signal::SIGTERM,
    );
}

/// Terminate an owned timeout or tether group: TERM, 200 ms grace, then KILL.
/// Foreground cancellation uses native job delivery instead of this teardown.
///
/// The group probe counts unreaped exits as alive. Capture timeouts retain
/// their leader, so they always use the full grace; signaling an already dead
/// group cannot change its exit status. Live survivors, including stopped or
/// TERM-ignoring processes, are killed at the deadline.
///
/// Tether may have reaped its leader, allowing an early return once the group
/// disappears. Reaping unpins the numeric pgid, leaving the existing recycling
/// exposure between the group probe and the subsequent signal.
#[cfg(unix)]
pub fn terminate_process_group(pgid: i32) {
    use nix::sys::signal::Signal;

    let pgid = nix::unistd::Pid::from_raw(pgid);
    let _ = nix::sys::signal::killpg(pgid, Signal::SIGTERM);
    if !group_died_within(pgid.as_raw(), Duration::from_millis(200)) {
        let _ = nix::sys::signal::killpg(pgid, Signal::SIGKILL);
    }
}

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

    /// macOS sets close-on-exec after creating stdio pipes and wakeup sockets.
    /// Concurrent spawns must not inherit these endpoints and delay EOF.
    #[cfg(target_os = "macos")]
    #[test]
    fn test_parallel_commands_do_not_inherit_sibling_descriptors() {
        const SCRIPT: &str = "
import errno, os, stat
counts = [0, 0]
for name in os.listdir('/dev/fd'):
    fd = int(name)
    if fd <= 2:
        continue
    try:
        mode = os.fstat(fd).st_mode
    except OSError as error:
        if error.errno != errno.EBADF:
            raise
        continue
    counts[0] += stat.S_ISFIFO(mode)
    counts[1] += stat.S_ISSOCK(mode)
print(*counts)
";
        let inspect = || Cmd::new("/usr/bin/python3").args(["-c", SCRIPT]).run();
        let descriptor_counts = |output: std::io::Result<std::process::Output>| {
            let output = output.unwrap();
            assert!(output.status.success(), "{output:?}");
            String::from_utf8(output.stdout)
                .unwrap()
                .split_whitespace()
                .map(|count| count.parse::<usize>().unwrap())
                .collect::<Vec<_>>()
        };
        // A test runner may itself have passed inheritable descriptors.
        let inherited = descriptor_counts(inspect());
        let barrier = std::sync::Barrier::new(16);
        let stop = AtomicBool::new(false);
        struct StopCreators<'a>(&'a AtomicBool);
        impl Drop for StopCreators<'_> {
            fn drop(&mut self) {
                self.0.store(true, Ordering::Relaxed);
            }
        }
        let results = std::thread::scope(|scope| {
            // Stop creators before scope joins its threads, including on panic.
            let _stop_creators = StopCreators(&stop);
            for index in 0..8 {
                let stop = &stop;
                scope.spawn(move || {
                    while !stop.load(Ordering::Relaxed) {
                        match index % 3 {
                            0 => drop(socket_pair().unwrap()),
                            1 => drop(stream_socket(socket2::Domain::UNIX).unwrap()),
                            _ => drop(stream_socket(socket2::Domain::IPV4).unwrap()),
                        }
                    }
                });
            }
            let workers: Vec<_> = (0..16)
                .map(|_| {
                    scope.spawn(|| {
                        (0..32)
                            .map(|_| {
                                barrier.wait();
                                inspect()
                            })
                            .collect::<Vec<_>>()
                    })
                })
                .collect();
            workers
                .into_iter()
                .flat_map(|worker| worker.join().unwrap())
                .collect::<Vec<_>>()
        });
        for output in results {
            assert_eq!(
                descriptor_counts(output),
                inherited,
                "inherited sibling pipe or wakeup socket"
            );
        }
    }

    /// The property the worktree-local scrub sites rest on: `TempIndex` and a
    /// redirected repository's object store scrub the whole
    /// [`INHERITED_GIT_PATH_VARS`] list and then set their own value for one of
    /// those vars. If `Cmd` ever applies removes after sets again, that set is
    /// silently dropped and those sites fall back to the ambient index / object
    /// store — so pin call order rather than the split-vector shape.
    #[test]
    fn test_env_mutations_apply_in_call_order() {
        let scrubbed = Cmd::new("child")
            .scrub_git_discovery_env()
            .env("GIT_INDEX_FILE", "chosen-index");
        let mut cmd = std::process::Command::new("child");
        scrubbed.apply_common_settings(&mut cmd);

        let env = |var: &str| {
            cmd.get_envs()
                .find(|(key, _)| *key == std::ffi::OsStr::new(var))
                .map(|(_, value)| value)
        };

        assert_eq!(
            env("GIT_INDEX_FILE"),
            Some(Some(std::ffi::OsStr::new("chosen-index"))),
            "a set after the scrub must win"
        );
        for var in INHERITED_GIT_PATH_VARS
            .iter()
            .filter(|var| **var != "GIT_INDEX_FILE")
        {
            assert_eq!(
                env(var),
                Some(None),
                "{var} should be removed from the child environment"
            );
        }

        // And the reverse order still removes, so `env_remove` isn't inert.
        let set_then_removed = Cmd::new("child")
            .env("GIT_INDEX_FILE", "chosen-index")
            .scrub_git_discovery_env();
        let mut cmd = std::process::Command::new("child");
        set_then_removed.apply_common_settings(&mut cmd);
        assert_eq!(
            cmd.get_envs()
                .find(|(key, _)| *key == std::ffi::OsStr::new("GIT_INDEX_FILE"))
                .map(|(_, value)| value),
            Some(None),
            "a scrub after the set must win"
        );
    }

    #[test]
    fn test_scrub_directive_env_vars_covers_every_directive_variable() {
        assert_eq!(RETIRED_DIRECTIVE_FILE_ENV_VAR, "WORKTRUNK_DIRECTIVE_FILE");
        assert_eq!(DIRECTIVE_EXEC_FILE_ENV_VAR, "WORKTRUNK_DIRECTIVE_EXEC_FILE");

        let mut cmd = std::process::Command::new("child");
        for var in [
            DIRECTIVE_CD_FILE_ENV_VAR,
            DIRECTIVE_EXEC_FILE_ENV_VAR,
            RETIRED_DIRECTIVE_FILE_ENV_VAR,
            SHELL_CWD_ENV_VAR,
        ] {
            cmd.env(var, "directive");
        }

        scrub_directive_env_vars(&mut cmd);

        for var in [
            DIRECTIVE_CD_FILE_ENV_VAR,
            DIRECTIVE_EXEC_FILE_ENV_VAR,
            RETIRED_DIRECTIVE_FILE_ENV_VAR,
            SHELL_CWD_ENV_VAR,
        ] {
            assert!(
                cmd.get_envs()
                    .any(|(key, value)| { key == std::ffi::OsStr::new(var) && value.is_none() }),
                "{var} should be removed from the child environment"
            );
        }
    }

    #[test]
    fn test_shell_cwd_from_prefers_absolute_inherited_value() {
        // Built from `temp_dir()` rather than platform literals: `/shell/cwd`
        // isn't absolute on Windows (no prefix), and a `cfg!(windows)` pair
        // would leave whichever arm this platform didn't take uncovered.
        // Neither path is touched — the predicate only inspects its shape.
        let root = std::env::temp_dir();
        let fallback = root.join("wt-shell-cwd-fallback");
        let absolute = root.join("wt-shell-cwd");
        assert!(absolute.is_absolute(), "temp_dir() should be absolute");

        // An absolute inherited value wins over the process cwd.
        assert_eq!(
            shell_cwd_from(Some(OsString::from(&absolute)), Some(&fallback)),
            Some(absolute.clone())
        );
        // A relative one names nothing from a child that runs elsewhere.
        assert_eq!(
            shell_cwd_from(Some(OsString::from("apps/gateway")), Some(&fallback)),
            Some(fallback.clone())
        );
        assert_eq!(
            shell_cwd_from(None, Some(&fallback)),
            Some(fallback.clone())
        );
        assert_eq!(
            shell_cwd_from(Some(OsString::from("apps/gateway")), None),
            None
        );
    }

    /// The only test allowed to set `FOREGROUND_THREAD` (a process-wide
    /// set-once): with it unset, `is_foreground_thread()` is false everywhere,
    /// which is the state every other test runs under.
    #[test]
    fn test_foreground_thread_exempt() {
        assert!(!is_foreground_thread());
        FOREGROUND_THREAD.get_or_init(|| std::thread::current().id());
        assert!(is_foreground_thread());
        // Threads other than the initializing one stay capped.
        let from_spawned = std::thread::spawn(is_foreground_thread).join().unwrap();
        assert!(!from_spawned);
    }

    #[test]
    fn test_shell_escape_for_dispatch() {
        // Literal passes the value through untouched.
        assert_eq!(shell_escape_for(ShellEscapeMode::Literal, "can't"), "can't");
        // Posix uses the `'\''` idiom for an embedded quote.
        assert_eq!(
            shell_escape_for(ShellEscapeMode::Posix, "can't"),
            r"'can'\''t'"
        );
    }

    #[test]
    fn test_compute_git_env_overrides() {
        // Use a platform-appropriate absolute base path so `Path::is_absolute`
        // behaves the same on Windows and Unix (Unix-style `/abs/...` paths
        // are not absolute on Windows).
        let base_buf = std::env::temp_dir().join("wt-test-startup-cwd");
        let base = base_buf.as_path();
        let abs_work = std::env::temp_dir().join("wt-test-abs-work");
        let env: std::collections::HashMap<&str, OsString> = [
            // relative — should be resolved against base
            ("GIT_DIR", OsString::from(".git")),
            // absolute — should be skipped
            ("GIT_WORK_TREE", abs_work.clone().into_os_string()),
            // relative with parent traversal
            ("GIT_INDEX_FILE", OsString::from("../index")),
            // unrelated var — should not appear
            ("GIT_AUTHOR_NAME", OsString::from("Test User")),
        ]
        .into_iter()
        .collect();

        let overrides = compute_git_env_overrides(base, |var| env.get(var).cloned());

        // Unset GIT_COMMON_DIR / GIT_OBJECT_DIRECTORY are skipped, absolute
        // GIT_WORK_TREE is skipped, unrelated vars are never consulted.
        assert_eq!(overrides.len(), 2);
        let as_map: std::collections::HashMap<_, _> = overrides.into_iter().collect();
        assert_eq!(
            as_map.get("GIT_DIR"),
            Some(&base.join(".git").into_os_string())
        );
        assert_eq!(
            as_map.get("GIT_INDEX_FILE"),
            Some(&base.join("../index").into_os_string())
        );
    }

    #[test]
    fn test_compute_git_env_overrides_all_absolute() {
        let base_buf = std::env::temp_dir().join("wt-test-startup-cwd");
        let abs_git = std::env::temp_dir().join("wt-test-abs.git");
        let env: std::collections::HashMap<&str, OsString> =
            [("GIT_DIR", abs_git.into_os_string())]
                .into_iter()
                .collect();

        let overrides = compute_git_env_overrides(base_buf.as_path(), |var| env.get(var).cloned());
        assert!(overrides.is_empty());
    }

    #[test]
    fn test_compute_git_env_overrides_all_unset() {
        let base_buf = std::env::temp_dir().join("wt-test-startup-cwd");
        let overrides = compute_git_env_overrides(base_buf.as_path(), |_| None);
        assert!(overrides.is_empty());
    }

    #[test]
    fn test_max_concurrent_commands_defaults() {
        // When no env var is set, default should be used
        assert!(max_concurrent_commands() >= 1, "Default should be >= 1");
        assert_eq!(
            max_concurrent_commands(),
            DEFAULT_CONCURRENT_COMMANDS,
            "Without env var, should use default"
        );
    }

    #[test]
    fn test_parse_concurrent_limit() {
        // Normal values pass through unchanged
        assert_eq!(parse_concurrent_limit("1"), Some(1));
        assert_eq!(parse_concurrent_limit("32"), Some(32));
        assert_eq!(parse_concurrent_limit("100"), Some(100));

        // 0 means unlimited (maps to usize::MAX)
        assert_eq!(parse_concurrent_limit("0"), Some(usize::MAX));

        // Invalid values return None
        assert_eq!(parse_concurrent_limit(""), None);
        assert_eq!(parse_concurrent_limit("abc"), None);
        assert_eq!(parse_concurrent_limit("-1"), None);
        assert_eq!(parse_concurrent_limit("1.5"), None);
    }

    #[test]
    fn test_shell_config_is_available() {
        let config = ShellConfig::get().unwrap();
        assert!(!config.name.is_empty());
        assert!(!config.args.is_empty());
    }

    #[test]
    #[cfg(unix)]
    fn test_unix_shell_is_sh() {
        let config = ShellConfig::get().unwrap();
        assert_eq!(config.name, "sh");
    }

    #[test]
    fn test_command_creation() {
        let config = ShellConfig::get().unwrap();
        let cmd = config.command("echo hello");
        // Just verify it doesn't panic
        let _ = format!("{:?}", cmd);
    }

    #[test]
    fn test_shell_command_execution() {
        let config = ShellConfig::get().unwrap();
        let output = config
            .command("echo hello")
            .output()
            .expect("Failed to execute shell command");
        let stdout = String::from_utf8_lossy(&output.stdout);
        let stderr = String::from_utf8_lossy(&output.stderr);
        assert!(
            output.status.success(),
            "echo should succeed. Shell: {} ({:?}), exit: {:?}, stdout: '{}', stderr: '{}'",
            config.name,
            config.executable,
            output.status.code(),
            stdout.trim(),
            stderr.trim()
        );
        assert!(
            stdout.contains("hello"),
            "stdout should contain 'hello', got: '{}'",
            stdout.trim()
        );
    }

    #[test]
    fn test_git_bash_from_exec_path() {
        let dir = crate::testing::tempdir().unwrap();
        let root = dir.path().join("Git");
        let bin_bash = root.join("bin/bash.exe");
        let usr_bash = root.join("usr/bin/bash.exe");
        std::fs::create_dir_all(bin_bash.parent().unwrap()).unwrap();
        std::fs::create_dir_all(usr_bash.parent().unwrap()).unwrap();
        std::fs::write(&bin_bash, "").unwrap();
        std::fs::write(&usr_bash, "").unwrap();

        // ARM uses a different runtime prefix; discovery must not enumerate them.
        let exec_path = root.join("clangarm64/libexec/git-core");
        assert_eq!(git_bash_from_exec_path(&exec_path), Some(bin_bash.clone()));
        assert_eq!(git_bash_from_exec_path(&root.join("x/y/z")), None);
        std::fs::remove_file(&bin_bash).unwrap();
        assert_eq!(git_bash_from_exec_path(&exec_path), Some(usr_bash.clone()));

        // MinGit can report the same layout without shipping Bash. Never climb
        // outside that installation to select an unrelated executable.
        std::fs::remove_file(&usr_bash).unwrap();
        std::fs::create_dir(dir.path().join("bin")).unwrap();
        std::fs::write(dir.path().join("bin/bash.exe"), "outside install").unwrap();
        assert_eq!(git_bash_from_exec_path(&exec_path), None);
    }

    #[test]
    #[cfg(windows)]
    fn test_windows_uses_git_bash() {
        let config = ShellConfig::get().unwrap();
        assert_eq!(config.name, "Git Bash");
        assert!(
            config.args.contains(&"-c".to_string()),
            "Git Bash should use -c flag"
        );
    }

    #[test]
    #[cfg(windows)]
    fn test_windows_echo_command() {
        let config = ShellConfig::get().unwrap();
        let output = config
            .command("echo test_output")
            .output()
            .expect("Failed to execute echo");

        let stdout = String::from_utf8_lossy(&output.stdout);
        assert!(output.status.success());
        assert!(
            stdout.contains("test_output"),
            "stdout should contain 'test_output', got: '{}'",
            stdout.trim()
        );
    }

    #[test]
    #[cfg(windows)]
    fn test_windows_posix_redirection() {
        let config = ShellConfig::get().unwrap();
        // Test POSIX-style redirection: stdout redirected to stderr
        let output = config
            .command("echo redirected 1>&2")
            .output()
            .expect("Failed to execute redirection test");

        let stderr = String::from_utf8_lossy(&output.stderr);
        assert!(output.status.success());
        assert!(
            stderr.contains("redirected"),
            "stderr should contain 'redirected' (stdout redirected to stderr), got: '{}'",
            stderr.trim()
        );
    }

    #[test]
    fn test_shell_config_clone() {
        let config = ShellConfig::get().unwrap();
        let cloned = config.clone();
        assert_eq!(config.name, cloned.name);
        assert_eq!(config.args, cloned.args);
    }

    // ========================================================================
    // Cmd and timeout tests
    // ========================================================================

    /// Captured secrets reach callers, never either debug target. The plain
    /// command is a positive control for the scoped subscriber's output capture.
    #[test]
    #[cfg(all(feature = "cli", unix))]
    fn test_sensitive_captured_output() {
        const SECRET: &str = "fake-captured-token-4b8ad2";
        for mode in ["run", "timeout", "concurrent", "source", "sink"] {
            let log = crate::testing::named_tempfile().unwrap();
            let subscriber = tracing_subscriber::fmt()
                .without_time()
                .with_ansi(false)
                .with_max_level(tracing::Level::DEBUG)
                .with_writer(Arc::new(log.reopen().unwrap()))
                .finish();
            tracing::subscriber::with_default(subscriber, || {
                let command = || {
                    Cmd::new("sh")
                        .args(["-c", "cat; printf '%s' \"$TOKEN\" >&2; exit 1"])
                        .env("TOKEN", SECRET)
                };
                // Log ordinary I/O first, then clear it before testing redaction.
                command().stdin_bytes(SECRET).run().unwrap();
                assert!(
                    std::fs::read_to_string(log.path())
                        .unwrap()
                        .contains(SECRET)
                );
                log.as_file().set_len(0).unwrap();

                let output = match mode {
                    "run" => command().stdin_bytes(SECRET).sensitive_output().run(),
                    "timeout" => command()
                        .stdin_bytes(SECRET)
                        .sensitive_output()
                        .timeout(Duration::from_secs(10))
                        .run(),
                    "concurrent" => Cmd::run_concurrently(&[command().sensitive_output()])
                        .pop()
                        .unwrap(),
                    "source" => {
                        let (source, sink) = command()
                            .stdin_bytes(SECRET)
                            .sensitive_output()
                            .pipe_into(Cmd::new("cat"))
                            .unwrap();
                        assert_eq!(sink.stdout, SECRET.as_bytes());
                        Ok(source)
                    }
                    "sink" => {
                        let (source, sink) = Cmd::new("cat")
                            .stdin_bytes(SECRET)
                            .pipe_into(command().sensitive_output())
                            .unwrap();
                        assert!(source.status.success());
                        Ok(sink)
                    }
                    _ => unreachable!(),
                }
                .unwrap();
                assert_eq!(output.status.code(), Some(1), "{mode}");
                assert_eq!(output.stderr, SECRET.as_bytes(), "{mode}");
                if matches!(mode, "run" | "timeout" | "sink") {
                    assert_eq!(output.stdout, SECRET.as_bytes(), "{mode}");
                }
                // Spawn failure still has input, which must also be redacted.
                assert!(
                    Cmd::new("/no/such/sensitive-program")
                        .stdin_bytes(SECRET)
                        .sensitive_output()
                        .run()
                        .is_err()
                );
            });
            let captured = std::fs::read_to_string(log.path()).unwrap();
            assert!(!captured.contains(SECRET), "{mode}: {captured}");
            for target in [SUBPROCESS_FULL_TARGET, SUBPROCESS_BOUNDED_TARGET] {
                assert!(
                    captured.lines().any(|line| line.contains(target)),
                    "{mode}: missing {target}: {captured}"
                );
            }
            assert!(captured.contains("[redacted]"), "{mode}: {captured}");
            assert!(captured.contains("dur_us="), "{mode}: {captured}");
        }
    }

    #[test]
    fn test_cmd_completes_fast_command() {
        let result = Cmd::new("echo")
            .arg("hello")
            .timeout(Duration::from_secs(5))
            .run();
        assert!(result.is_ok());
        let output = result.unwrap();
        assert!(output.status.success());
        assert!(String::from_utf8_lossy(&output.stdout).contains("hello"));
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_timeout_kills_slow_command() {
        let result = Cmd::new("sleep")
            .arg("10")
            .stdin_bytes("unconsumed input")
            .timeout(Duration::from_millis(50))
            .run();
        assert!(result.is_err());
        assert_eq!(result.unwrap_err().kind(), std::io::ErrorKind::TimedOut);
    }

    /// The `wait-timeout` crate has to stay out of the dependency graph, however
    /// it gets there.
    ///
    /// Its `SIGCHLD` handler pokes a socketpair with `send()` and `panic!`s on any
    /// errno but `WouldBlock`. That handler is `extern "C"`, so the panic cannot
    /// unwind — it goes straight to `abort()`. Under a sandbox that denies the send
    /// (the Codex CLI's `workspace-write` mode), every timed wait in `wt` became an
    /// uncatchable `SIGABRT` with no diagnostic (#3856). `shared_child` wakes
    /// through `signal_hook`, which discards wake-write errors by design.
    ///
    /// The lockfile is read at runtime, not `include_str!`d: a compile-time embed
    /// has to ship in every packaged build, which `embedded_assets_ship_in_package`
    /// enforces and `Cargo.lock` doesn't satisfy. Tests only ever run from the
    /// source tree, so the manifest dir is always there.
    #[test]
    fn test_wait_timeout_crate_stays_out_of_the_dependency_graph() {
        let lockfile = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("Cargo.lock");
        let lockfile = std::fs::read_to_string(&lockfile).expect("read Cargo.lock");
        assert!(
            !lockfile.contains("name = \"wait-timeout\""),
            "wait-timeout is back in the dependency graph; its SIGCHLD handler \
             aborts wt when the self-pipe write fails (#3856)"
        );
    }

    /// A command that can't be spawned at all fails as a spawn error, not as a
    /// timeout — the deadline path never starts, so the caller doesn't wait it out.
    #[test]
    fn test_cmd_timeout_surfaces_a_spawn_failure() {
        let err = Cmd::new("worktrunk-no-such-program-3856")
            .timeout(Duration::from_secs(30))
            .run()
            .unwrap_err();
        assert_ne!(err.kind(), std::io::ErrorKind::TimedOut);
    }

    /// The timeout has to bound wall-clock, not just signal the direct child.
    /// A grandchild inherits the child's stderr pipe, so one that survives the
    /// kill holds the write end open and the output readers block on it — which
    /// used to make `run()` return `TimedOut` only once the *grandchild* exited
    /// (30 s here, ~127 s for the `git-remote-https` case this bound exists
    /// for). `; :` keeps the shell from `exec`ing sleep, so there really is a
    /// grandchild to leave behind.
    #[test]
    #[cfg(unix)]
    fn test_cmd_timeout_bounds_wall_clock_with_surviving_grandchild() {
        let start = std::time::Instant::now();
        let err = Cmd::new("sh")
            .args(["-c", "sleep 30; :"])
            .timeout(Duration::from_millis(200))
            .run()
            .unwrap_err();
        let elapsed = start.elapsed();

        assert_eq!(err.kind(), std::io::ErrorKind::TimedOut);
        assert!(
            elapsed < Duration::from_secs(10),
            "timeout waited on the grandchild: {elapsed:?}"
        );
    }

    /// A child that INT/TERM already ended keeps that status when a descendant
    /// holds its pipes past the deadline, instead of reading as `TimedOut`.
    #[test]
    #[cfg(unix)]
    fn test_cmd_timeout_keeps_native_interrupt_with_pipe_holding_descendant() {
        use signal_hook::consts::{SIGINT, SIGTERM};
        use std::os::unix::process::ExitStatusExt;
        for (name, signal) in [("INT", SIGINT), ("TERM", SIGTERM)] {
            let start = std::time::Instant::now();
            let output = Cmd::new("sh")
                .args(["-c", &format!("sleep 30 & kill -{name} $$")])
                // Long enough that `kill` lands first even under suite load.
                .timeout(Duration::from_secs(2))
                .run()
                .unwrap();
            assert_eq!(output.status.signal(), Some(signal));
            assert!(start.elapsed() < Duration::from_secs(20));
        }
    }

    #[test]
    fn test_cmd_without_timeout_completes() {
        let result = Cmd::new("echo").arg("no timeout").run();
        assert!(result.is_ok());
    }

    #[test]
    fn test_cmd_with_context() {
        let result = Cmd::new("echo")
            .arg("with context")
            .context("test-context")
            .run();
        assert!(result.is_ok());
    }

    #[test]
    fn test_cmd_with_stdin() {
        // A complete buffer can exceed both input and output pipe capacity.
        // Empty input must still supply EOF rather than inherit the caller.
        for input in [Vec::new(), b"hello from stdin\n".repeat(100_000)] {
            let output = Cmd::new("cat").stdin_bytes(input.as_slice()).run().unwrap();
            assert!(output.status.success());
            assert_eq!(output.stdout, input);
        }
    }

    // ========================================================================
    // Cmd::stream() tests
    // ========================================================================

    #[test]
    fn test_cmd_shell_stream_succeeds() {
        let result = Cmd::shell("echo hello").stream();
        assert!(result.is_ok());
    }

    #[test]
    fn test_cmd_shell_stream_fails_on_nonzero_exit() {
        use crate::git::WorktrunkError;

        let result = Cmd::shell("exit 42").stream();
        assert!(result.is_err());

        let err = result.unwrap_err();
        let wt_err = err.downcast_ref::<WorktrunkError>().unwrap();
        match wt_err {
            WorktrunkError::ChildProcessExited { code, .. } => {
                assert_eq!(*code, 42);
            }
            _ => panic!("Expected ChildProcessExited error"),
        }
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_stream_sigpipe_is_not_an_error() {
        // Simulates pager quit: the child is killed by SIGPIPE, same as when
        // `git diff` writes to a pager and the user presses `q`.
        // `sh -c 'kill -PIPE $$'` sends SIGPIPE to itself, terminating with signal 13.
        let result = Cmd::new("sh").args(["-c", "kill -PIPE $$"]).stream();
        assert!(
            result.is_ok(),
            "SIGPIPE should not be treated as an error: {result:?}"
        );
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_stream_can_propagate_sigpipe() {
        use crate::git::WorktrunkError;

        let err = Cmd::new("sh")
            .args(["-c", "kill -PIPE $$"])
            .propagate_sigpipe()
            .stream()
            .unwrap_err();
        let wt_err = err.downcast_ref::<WorktrunkError>().unwrap();
        assert!(matches!(
            wt_err,
            WorktrunkError::ChildProcessExited {
                code: 141,
                physical_signal: Some(13),
                ..
            }
        ));
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_stream_other_signals_are_errors() {
        use crate::git::WorktrunkError;

        // Non-SIGPIPE signals (like SIGTERM) should still be treated as errors.
        let result = Cmd::new("sh").args(["-c", "kill -TERM $$"]).stream();
        assert!(result.is_err());

        let err = result.unwrap_err();
        let wt_err = err.downcast_ref::<WorktrunkError>().unwrap();
        match wt_err {
            WorktrunkError::ChildProcessExited { code, .. } => {
                assert_eq!(*code, 128 + 15); // SIGTERM = 15
            }
            _ => panic!("Expected ChildProcessExited error"),
        }
    }

    #[test]
    #[cfg(unix)]
    fn test_real_process_failure_descriptions() {
        for (script, description) in [
            ("exit 7", "exit code 7"),
            ("kill -9 $$", "killed by signal 9"),
        ] {
            let output = Cmd::new("sh").args(["-c", script]).run().unwrap();
            let error =
                crate::git::CommandError::from_failed_output("sh", &["-c", script], &output);
            assert!(
                error
                    .to_string()
                    .ends_with(&format!("failed ({description})"))
            );
            let error = Cmd::new("sh").args(["-c", script]).stream().unwrap_err();
            assert_eq!(error.to_string(), description);
            let error = Cmd::new("sh")
                .args(["-c", script])
                .delayed_stream(1000, None)
                .unwrap_err();
            let (_, command) = crate::git::Repository::extract_failed_command(&error);
            assert_eq!(command.unwrap().exit_info, description);
        }
    }

    #[test]
    #[cfg(unix)]
    fn test_spawn_errors_identify_program_and_cwd_without_guessing_cause() {
        use crate::git::ErrorExt;
        use std::os::unix::fs::PermissionsExt;
        let dir = crate::testing::tempdir().unwrap();
        let script = dir.path().join("broken-interpreter");
        std::fs::write(&script, "#!/no/such/interpreter-7f3a9b2c\n").unwrap();
        std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
        let missing_cwd = dir.path().join("missing");
        for (program, cwd) in [
            ("missing-program-7f3a9b2c".to_string(), dir.path()),
            ("/bin/sh".to_string(), missing_cwd.as_path()),
            (script.to_string_lossy().into_owned(), dir.path()),
        ] {
            for command in [
                Cmd::new(&program).current_dir(cwd),
                Cmd::new(&program).current_dir(cwd).stdin_bytes("{}"),
                Cmd::new(&program)
                    .current_dir(cwd)
                    .timeout(Duration::from_secs(1)),
            ] {
                let error = command.run().unwrap_err();
                assert_eq!(error.kind(), ErrorKind::NotFound);
                assert!(error.to_string().contains(&program), "{error}");
                assert!(
                    error
                        .to_string()
                        .contains(&cwd.to_string_lossy().to_string()),
                    "{error}"
                );
                let source = std::error::Error::source(error.get_ref().unwrap()).unwrap();
                assert_eq!(
                    source
                        .downcast_ref::<std::io::Error>()
                        .unwrap()
                        .raw_os_error(),
                    Some(2)
                );
                let cause = source.to_string();
                // The borrowed detail used by captured-command traces and the
                // embedded Git-failure detail both retain the OS cause once.
                let trace_detail = crate::git::error_chain_message(&error);
                let error: anyhow::Error = error.into();
                let detail = error.display_message();
                assert_eq!(detail, trace_detail);
                assert_eq!(detail.matches(&cause).count(), 1, "{detail}");
                let (extracted, command) = crate::git::Repository::extract_failed_command(&error);
                assert_eq!(extracted, detail);
                assert!(command.is_none());
            }
            let error = Cmd::new(&program).current_dir(cwd).stream().unwrap_err();
            assert!(error.to_string().contains(&program), "{error}");
            assert!(
                error
                    .to_string()
                    .contains(&cwd.to_string_lossy().to_string()),
                "{error}"
            );
            assert_eq!(error.exit_code(), None);
            assert!(
                error
                    .chain()
                    .any(|source| source.downcast_ref::<std::io::Error>().is_some())
            );
        }
    }

    #[test]
    fn test_cmd_run_spawn_failure_is_errored() {
        let err = Cmd::new("/no/such/binary-7f3a9b2c").run().unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotFound);
    }

    /// Every runner reports the native OS cause once through the same trace owner.
    /// A scoped subscriber records real failures without changing the process logger.
    #[test]
    #[cfg(all(feature = "cli", unix))]
    fn test_spawn_trace_retains_io_cause_once_in_every_execution_mode() {
        let log = crate::testing::named_tempfile().unwrap();
        let subscriber = tracing_subscriber::fmt()
            .without_time()
            .with_ansi(false)
            .with_max_level(tracing::Level::DEBUG)
            .with_writer(std::sync::Arc::new(log.reopen().unwrap()))
            .finish();
        let causes = tracing::subscriber::with_default(subscriber, || {
            let missing = "worktrunk-no-such-program-trace";
            [
                Cmd::new(missing).run().unwrap_err().into(),
                Cmd::new(missing)
                    .stdin_bytes("{}")
                    .run()
                    .unwrap_err()
                    .into(),
                Cmd::new(missing)
                    .timeout(Duration::from_secs(1))
                    .run()
                    .unwrap_err()
                    .into(),
                Cmd::new(missing).stream().unwrap_err(),
                Cmd::new(missing).delayed_stream(-1, None).unwrap_err(),
                Cmd::new(missing)
                    .pipe_into(Cmd::new("cat"))
                    .unwrap_err()
                    .into(),
                Cmd::new("true")
                    .pipe_into(Cmd::new(missing))
                    .unwrap_err()
                    .into(),
            ]
            .into_iter()
            .map(|error: anyhow::Error| error.root_cause().to_string())
            .collect::<Vec<_>>()
        });
        let output = std::fs::read_to_string(log.path()).unwrap();
        let events: Vec<_> = output
            .lines()
            .filter(|line| line.contains("cmd_errored"))
            .collect();
        assert_eq!(events.len(), causes.len(), "{output}");
        for (event, cause) in events.into_iter().zip(causes) {
            assert!(event.contains("Failed to execute worktrunk-no-such-program-trace"));
            assert_eq!(event.matches(&cause).count(), 1, "{event}");
        }
    }

    #[test]
    fn test_cmd_run_missing_current_dir_is_errored() {
        let err = Cmd::new("sh")
            .args(["-c", "true"])
            .current_dir("/no/such/dir-7f3a9b2c")
            .run()
            .unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotFound);
    }

    #[test]
    fn test_cmd_run_file_current_dir_is_errored() {
        // Any existing non-directory path will do, and the test binary is one,
        // so this creates nothing in the system temp directory — a shared
        // namespace where Windows can deny a fresh temp name outright ("Access
        // is denied.") rather than report a collision tempfile would retry.
        let err = Cmd::new("sh")
            .args(["-c", "true"])
            .current_dir(std::env::current_exe().unwrap())
            .run()
            .unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotADirectory);
    }

    #[test]
    fn test_cmd_run_directory_program_path_is_errored() {
        let dir = crate::testing::tempdir().unwrap();
        let err = Cmd::new(dir.path().to_string_lossy()).run().unwrap_err();
        assert_eq!(err.kind(), ErrorKind::PermissionDenied);
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_run_non_executable_program_path_is_errored() {
        use std::os::unix::fs::PermissionsExt;

        let file = crate::testing::named_tempfile().unwrap();
        std::fs::set_permissions(file.path(), std::fs::Permissions::from_mode(0o644)).unwrap();

        let err = Cmd::new(file.path().to_string_lossy()).run().unwrap_err();
        assert_eq!(err.kind(), ErrorKind::PermissionDenied);
    }

    #[test]
    fn test_cmd_stream_spawn_failure_is_errored() {
        // A non-existent absolute binary path should surface as a command
        // execution failure before the child can report only exit status 127.
        let result = Cmd::new("/no/such/binary-7f3a9b2c").stream();
        assert!(result.is_err());
        let msg = result.unwrap_err().to_string();
        assert!(
            msg.contains("Failed to execute /no/such/binary"),
            "expected spawn-failure message, got: {msg}"
        );
    }

    // Fault-injection coverage for the `CommandTrace` resolution arms across
    // `Cmd`'s execution modes. A non-existent *relative* program slips past
    // `check_spawn_preconditions` (which only stats absolute paths) and fails at
    // `spawn()`, exercising the `trace.fail` spawn-error arms; a non-existent
    // *absolute* program is caught by preconditions, exercising the
    // `record_failed` arms. None set `.context()`, so the no-context logging
    // branches are covered too.
    const MISSING_CMD: &str = "worktrunk-nonexistent-binary-7f3a9b2c";

    #[test]
    fn test_cmd_run_spawn_failure_resolves_trace() {
        let err = Cmd::new(MISSING_CMD).run().unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotFound);
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_delayed_stream_quiet_success() {
        // A fast command under a generous threshold exits during phase 1
        // (wait_timeout returns Some) and stays buffered/quiet.
        Cmd::new("true").delayed_stream(5_000, None).unwrap();
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_delayed_stream_retains_output_after_invalid_utf8() {
        let error = Cmd::new("python3")
            .args([
                "-c",
                "import sys; sys.stdout.buffer.write(b'\\xffinvalid\\r\\n' + b'x' * 250000 + b'\\nTAIL'); sys.stdout.flush(); sys.exit(17)",
            ])
            .delayed_stream(-1, None)
            .unwrap_err();
        let command = error.downcast_ref::<StreamCommandError>().unwrap();
        assert_eq!(command.status.code(), Some(17), "{error:?}");
        assert_eq!(
            command.output,
            format!("�invalid\n{}\nTAIL", "x".repeat(250000)),
        );
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_delayed_stream_crosses_the_threshold() {
        // A command that outlives the threshold leaves phase 1 with no status
        // (`wait_timeout` returns `Ok(None)`), which switches the readers to
        // streaming, and phase 2 then reports the real exit.
        //
        // What pins the switch is where the late output goes: a streamed line
        // is written to stderr instead of the buffer, so the error carries
        // none of it. Had phase 1 returned a status instead, `late` would
        // still be buffered and would show up here. The other thresholds never
        // reach this arm — `0` streams without waiting, `-1` skips phase 1.
        //
        // The child writes 450 ms after the threshold passes. Only the switch
        // has to land in that window, and it follows the wait immediately, so
        // the margin covers a deschedule far longer than anything the suite
        // produces. The threshold stays well above zero for the opposite
        // reason: were `remaining` to reach it already spent, phase 1 would
        // skip the wait entirely and the test would pass without reaching the
        // arm it exists to cover.
        let err = Cmd::new("sh")
            .args(["-c", "sleep 0.5; echo late 1>&2; exit 3"])
            .delayed_stream(50, None)
            .unwrap_err();
        let stream_err = err
            .downcast_ref::<StreamCommandError>()
            .expect("non-zero delayed_stream exit should be a StreamCommandError");
        assert_eq!(stream_err.exit_info(), "exit code 3");
        assert_eq!(
            stream_err.output, "",
            "output written after the switch must stream, not buffer"
        );
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_delayed_stream_flushes_what_it_buffered() {
        // Output written *before* the threshold is buffered, and the switch to
        // streaming drains that buffer to stderr before phase 2 begins. This
        // ordering is what reaches the drain loop:
        // `test_cmd_delayed_stream_crosses_the_threshold` writes after the
        // switch, so its line streams from the reader thread and the buffer
        // stays empty throughout.
        //
        // The error's `output` is empty either way — the reader relays a line
        // it picks up after the switch, and the drain empties one it picked up
        // before — so the assertion pins the switch, not the drain itself. A
        // unit test cannot capture stderr, so the window is the only lever on
        // which of the two runs; the integration test next door
        // (`test_delayed_stream_progress_strips_ansi_when_piped`) is what
        // asserts on the relayed text.
        //
        // The threshold is the whole window the reader has to get `early` into
        // the buffer: spawning `sh` and reading its first line has to land
        // inside it, or the switch goes first and the drain runs over nothing.
        // 250 ms absorbs a slow spawn on a loaded runner, and the child's
        // 500 ms still outlasts the threshold by the same margin.
        let err = Cmd::new("sh")
            .args(["-c", "echo early 1>&2; sleep 0.5; exit 3"])
            .delayed_stream(250, None)
            .unwrap_err();
        let stream_err = err
            .downcast_ref::<StreamCommandError>()
            .expect("non-zero delayed_stream exit should be a StreamCommandError");
        assert_eq!(stream_err.exit_info(), "exit code 3");
        assert_eq!(
            stream_err.output, "",
            "output buffered before the switch must be drained to stderr, not reported"
        );
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_delayed_stream_streams_then_reports_failure() {
        // delay_ms=0 streams immediately (phase-1 threshold crossed → progress
        // message + buffer drain), and a non-zero exit surfaces as a
        // StreamCommandError carrying the buffered output.
        let err = Cmd::new("sh")
            .args(["-c", "echo to-stderr 1>&2; exit 3"])
            .delayed_stream(0, Some("working…".to_string()))
            .unwrap_err();
        let stream_err = err
            .downcast_ref::<StreamCommandError>()
            .expect("non-zero delayed_stream exit should be a StreamCommandError");
        assert_eq!(stream_err.exit_info(), "exit code 3");
    }

    #[test]
    fn test_cmd_delayed_stream_spawn_failure_resolves_trace() {
        // delay_ms=-1 disables phase 1; the spawn failure resolves the trace
        // via `fail` rather than dropping it unresolved.
        let err = Cmd::new(MISSING_CMD).delayed_stream(-1, None).unwrap_err();
        assert!(err.to_string().contains("Failed to execute"), "{err}");
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_run_concurrently_overlaps_children_and_keeps_order() {
        // The first child waits for a file that only the last child creates, so
        // it succeeds only if both run at once. A spawn failure in between
        // stays in its own slot rather than shifting the results after it.
        let dir = crate::testing::tempdir().unwrap();
        let flag = dir.path().join("flag");
        let wait_for_flag = format!(
            "for _ in $(seq 500); do [ -e '{}' ] && exit 0; sleep 0.01; done; exit 1",
            flag.display()
        );
        let results = Cmd::run_concurrently(&[
            Cmd::new("sh").args(["-c", wait_for_flag.as_str()]),
            Cmd::new(MISSING_CMD),
            Cmd::new("sh").args(["-c", "exit 3"]),
            Cmd::new("touch").arg(flag.to_str().unwrap()),
        ]);
        let [waiter, missing, exit3, toucher]: [_; 4] = results.try_into().unwrap();
        assert!(
            waiter.unwrap().status.success(),
            "children ran one at a time"
        );
        assert_eq!(missing.unwrap_err().kind(), ErrorKind::NotFound);
        assert_eq!(exit3.unwrap().status.code(), Some(3));
        assert!(toucher.unwrap().status.success());
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_pipe_into_succeeds() {
        let (source, sink) = Cmd::new("printf")
            .arg("hello")
            .pipe_into(Cmd::new("cat"))
            .unwrap();
        assert!(source.status.success() && sink.status.success());
        assert_eq!(String::from_utf8_lossy(&sink.stdout), "hello");
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_pipe_into_feeds_source_stdin() {
        // The source's stdin must flow through to the sink: `cat` echoes its
        // stdin to stdout, piped into a second `cat`, so the bytes round-trip.
        let (source, sink) = Cmd::new("cat")
            .stdin_bytes(b"piped stdin".to_vec())
            .pipe_into(Cmd::new("cat"))
            .unwrap();
        assert!(source.status.success() && sink.status.success());
        assert_eq!(String::from_utf8_lossy(&sink.stdout), "piped stdin");
    }

    #[test]
    fn test_cmd_pipe_into_source_spawn_failure_resolves_trace() {
        let err = Cmd::new(MISSING_CMD)
            .pipe_into(Cmd::new("cat"))
            .unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotFound);
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_pipe_into_sink_spawn_failure_resolves_both_traces() {
        // The sink fails to spawn after the source is already running: the sink
        // trace fails and the source is torn down with complete(false).
        let err = Cmd::new("printf")
            .arg("hello")
            .pipe_into(Cmd::new(MISSING_CMD))
            .unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotFound);
    }

    // An *absolute* non-existent program is rejected by
    // `check_spawn_preconditions` (which stats absolute paths) before any spawn,
    // exercising the `record_failed` precondition arms rather than the
    // spawn-error arms above.
    #[test]
    fn test_cmd_pipe_into_source_precondition_failure_resolves_trace() {
        let err = Cmd::new("/no/such/abs-source-7f3a9b2c")
            .pipe_into(Cmd::new("cat"))
            .unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotFound);
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_pipe_into_sink_precondition_failure_resolves_trace() {
        // Source preconditions pass (relative program); the sink's fail.
        let err = Cmd::new("printf")
            .arg("x")
            .pipe_into(Cmd::new("/no/such/abs-sink-7f3a9b2c"))
            .unwrap_err();
        assert_eq!(err.kind(), ErrorKind::NotFound);
    }

    #[test]
    fn test_stream_command_error_display_is_the_output() {
        #[cfg(unix)]
        use std::os::unix::process::ExitStatusExt;
        #[cfg(windows)]
        use std::os::windows::process::ExitStatusExt;

        // The Display impl exists only for the Error bound; callers read fields
        // via Repository::extract_failed_command, so nothing else exercises it.
        let err = StreamCommandError {
            output: "fatal: ref exists".to_string(),
            command: "git worktree add /x".to_string(),
            status: std::process::ExitStatus::from_raw(if cfg!(unix) { 128 << 8 } else { 128 }),
        };
        assert_eq!(err.to_string(), "fatal: ref exists");
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_shell_stream_with_stdin() {
        // cat should echo stdin content (output goes to inherited stdout, we can't capture it,
        // but we can verify no error)
        let result = Cmd::shell("cat").stdin_bytes("test content").stream();
        assert!(result.is_ok());
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_new_stream_succeeds() {
        // Non-shell command via stream() (uses direct execution, not shell wrapping)
        let result = Cmd::new("echo").arg("hello").stream();
        assert!(result.is_ok());
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_shell_stream_with_stdout_redirect() {
        use std::process::Stdio;
        // Redirect stdout to stderr (common pattern for hooks)
        let result = Cmd::shell("echo redirected")
            .stdout(Stdio::from(std::io::stderr()))
            .stream();
        assert!(result.is_ok());
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_shell_stream_with_stdin_inherit() {
        use std::process::Stdio;
        // Test stdin configuration (true immediately exits, doesn't actually read stdin)
        let result = Cmd::shell("true").stdin(Stdio::inherit()).stream();
        assert!(result.is_ok());
    }

    #[test]
    #[cfg(unix)]
    fn test_cmd_shell_stream_with_env() {
        // Test .env() and .env_remove() with stream()
        let result = Cmd::shell("printenv TEST_VAR")
            .env("TEST_VAR", "test_value")
            .env_remove("SOME_NONEXISTENT_VAR")
            .stream();
        assert!(result.is_ok());
    }

    #[test]
    fn test_background_pid_deregisters_on_drop() {
        // Not a live PID: this exercises the registry bookkeeping only, and
        // nothing in this test signals anything.
        let pid = u32::MAX;
        {
            BACKGROUND_PIDS.lock().unwrap().insert(pid);
            let _guard = BackgroundPid(pid);
            assert!(BACKGROUND_PIDS.lock().unwrap().contains(&pid));
        }
        assert!(
            !BACKGROUND_PIDS.lock().unwrap().contains(&pid),
            "the guard should deregister its PID once the command finishes"
        );
    }

    #[test]
    #[cfg(unix)]
    fn test_process_group_alive_with_current_process() {
        // Current process group should be alive
        let pgid = nix::unistd::getpgrp().as_raw();
        assert!(super::process_group_alive(pgid));
    }

    #[test]
    #[cfg(unix)]
    fn test_process_group_alive_with_nonexistent_pgid() {
        // Very high PGID unlikely to exist
        assert!(!super::process_group_alive(999_999_999));
    }

    #[test]
    #[cfg(unix)]
    fn test_group_died_within_immediate_for_reaped_group() {
        // A reaped child leaves an empty group: the first (immediate) probe
        // reads ESRCH and the grace loop returns without sleeping. This pins
        // the early exit that keeps escalation cheap for the callers whose
        // children are reaped concurrently (tether).
        use std::os::unix::process::CommandExt;
        let mut cmd = std::process::Command::new("sh");
        cmd.args(["-c", ":"]).process_group(0);
        let mut child = cmd.spawn().unwrap();
        let pgid = child.id() as i32;
        child.wait().unwrap();

        let start = Instant::now();
        // Grace far longer than any plausible scheduling stall, so returning
        // early is structurally distinguishable from having slept it, and the
        // bound below is a safety net rather than a race.
        assert!(super::group_died_within(pgid, Duration::from_secs(30)));
        assert!(
            start.elapsed() < Duration::from_secs(5),
            "an empty group must exit the grace loop on the first probe; took {:?}",
            start.elapsed()
        );
    }

    #[test]
    #[cfg(unix)]
    fn test_group_died_within_times_out_on_live_group() {
        // Probing our own (live) process group runs the full grace and
        // reports the group still alive.
        let pgid = nix::unistd::getpgrp().as_raw();
        let grace = Duration::from_millis(50);
        let start = Instant::now();
        assert!(!super::group_died_within(pgid, grace));
        assert!(start.elapsed() >= grace);
    }

    #[test]
    #[cfg(unix)]
    fn test_escalation_full_grace_and_inert_sweep_when_leader_unreaped() {
        // Replays `kill_timed_out_tree`'s position: the caller holds the group
        // leader unreaped while escalating. The child has already exited when
        // escalation starts (stdout EOF is the barrier — the pipe closes when
        // the process exits, so this needs no scheduling assumptions), but
        // nobody reaps it, so the liveness probe counts the zombie, the grace
        // runs to its deadline, and the final group SIGKILL fires against the
        // dead group. The recorded exit must come through untouched — signals
        // to a fully-exited group are discarded.
        use std::os::unix::process::CommandExt;
        let mut cmd = std::process::Command::new("sh");
        cmd.args(["-c", "exit 7"])
            .stdout(std::process::Stdio::piped())
            .process_group(0);
        let mut child = cmd.spawn().unwrap();
        let pid = child.id() as i32;
        let mut eof = Vec::new();
        child.stdout.take().unwrap().read_to_end(&mut eof).unwrap();

        let start = Instant::now();
        super::terminate_process_group(pid);
        assert!(
            start.elapsed() >= Duration::from_millis(200),
            "with the leader unreaped the group must read alive for the whole grace"
        );

        let status = child.wait().unwrap();
        assert_eq!(
            status.code(),
            Some(7),
            "the TERM and the post-grace SIGKILL must not alter the recorded exit"
        );
    }

    #[test]
    fn test_format_stream_full_empty() {
        assert!(format_stream_full(b"", "  ").is_empty());
    }

    #[test]
    fn test_format_stream_full_prefixes_each_line() {
        let lines = format_stream_full(b"alpha\nbeta\ngamma\n", "  ");
        assert_eq!(lines, vec!["  alpha", "  beta", "  gamma"]);
    }

    #[test]
    fn test_format_stream_full_stderr_prefix() {
        let lines = format_stream_full(b"err1\nerr2\n", "  ! ");
        assert_eq!(lines, vec!["  ! err1", "  ! err2"]);
    }

    #[test]
    fn test_format_stream_bounded_empty() {
        assert!(format_stream_bounded(b"", "  ").is_empty());
    }

    #[test]
    fn test_format_stream_bounded_below_caps_emits_all() {
        let lines = format_stream_bounded(b"one\ntwo\nthree\n", "  ");
        assert_eq!(lines, vec!["  one", "  two", "  three"]);
    }

    #[test]
    fn test_format_stream_bounded_line_cap_triggers_elision() {
        // Build LOG_OUTPUT_MAX_LINES + 5 short lines so the line cap trips first.
        let input: String = (0..LOG_OUTPUT_MAX_LINES + 5)
            .map(|i| format!("line{i}\n"))
            .collect();
        let lines = format_stream_bounded(input.as_bytes(), "  ");

        assert_eq!(lines.len(), LOG_OUTPUT_MAX_LINES + 1, "cap + 1 marker");
        let marker = lines.last().unwrap();
        assert!(
            marker.starts_with("  … (5 more lines, "),
            "marker should count the 5 lines past the cap: {marker}"
        );
        // No tracing subscriber is installed in unit tests, so
        // `tracing::enabled!(SUBPROCESS_FULL_TARGET, DEBUG)` is false and the
        // marker suggests `-vv`.
        assert!(marker.contains("rerun with -vv"));
    }

    #[test]
    fn test_format_stream_bounded_byte_cap_triggers_elision() {
        // One long line past the byte cap, then extra lines.
        let long = "x".repeat(LOG_OUTPUT_MAX_BYTES + 100);
        let input = format!("{long}\nafter1\nafter2\n");
        let lines = format_stream_bounded(input.as_bytes(), "  ");

        // The long first line gets emitted (bytes_emitted==0 at entry); the
        // byte cap trips on the next iteration and the remaining 2 lines are elided.
        assert_eq!(lines.len(), 2);
        assert_eq!(lines[0].len(), 2 + long.len());
        let marker = &lines[1];
        assert!(
            marker.starts_with("  … (2 more lines, "),
            "marker should count after1 + after2: {marker}"
        );
    }
}