rch 2.1.12

//! Cargo shim management (`rch shim install|status|uninstall`).
//!
//! rch auto-intercepts builds via the Claude Code PreToolUse hook, but that only
//! covers Claude Code. Codex, plain shells, scripts, and CI invoke `cargo`
//! directly — with no hook to catch them — so their builds run locally on the
//! box, defeating the whole point of rch on an orchestrator/dispatcher.
//!
//! rch already honors a cargo-wrapper contract: when it re-execs cargo on local
//! fallback it sets `RCH_CARGO_WRAPPER_BYPASS=1` (see [`crate::hook`]). It just
//! never shipped the wrapper, so every box hand-rolled one (or had none). This
//! command installs the ONE canonical wrapper, so every agent offloads.
//!
//! The shim is deliberately conservative:
//! - loop-safe: honors `RCH_CARGO_WRAPPER_BYPASS=1` (rch's own re-exec) → real cargo;
//! - fail-open: if `rch` is not on `PATH`, run the real cargo unchanged;
//! - IDE-safe: rust-analyzer's `--message-format=json-diagnostic-{rendered-ansi,short}`
//!   → real cargo, local. A plain `--message-format=json` (scripts, CI, lint
//!   gates) still offloads; treating every `--message-format` as an IDE was the bug
//!   that silently kept script-driven builds on the dev box;
//! - wrapper-safe: a caller-set `RUSTC_WORKSPACE_WRAPPER` (how `cargo clippy`
//!   drives its inner `cargo check`) → real cargo, local, so the wrapper is
//!   never dropped by offloading the inner invocation;
//! - escape hatch: `RCH_SHIM_LOCAL_IDE=1` forces any single build local, with
//!   the real cargo resolved in tiers (`resolve_real` in the generated body)
//!   so a renamed toolchain cargo still works;
//! - only the artifact/test subcommands are offloaded; everything else is local.
//!
//! A companion `cargo-clippy` shim catches direct invocations of that binary,
//! which never pass through `cargo` and so cannot be caught by the cargo shim.

use anyhow::{Context, Result};
use serde::Serialize;
use std::path::{Path, PathBuf};

use crate::state::primitives::atomic_write;
use crate::ui::context::OutputContext;
use crate::ui::theme::StatusIndicator;

/// Bumped whenever the embedded shim body changes so `shim status` can detect a
/// stale on-disk copy and prompt a reinstall.
///
/// `2` narrowed the `--message-format` bail-out (v1 sent EVERY such build local,
/// which silently kept script/CI builds on the dev box), added the
/// `RUSTC_WORKSPACE_WRAPPER` guard, and introduced the `cargo-clippy` shim.
///
/// `3` caps parallelism on every LOCAL fallback path (`exec_local`). Local builds
/// skip rch's slot accounting entirely, so nothing bounded their `-j`: a repo's
/// own `.cargo/config.toml` outranks `~/.cargo/config.toml`, and one setting
/// `jobs = -1` (= nproc-1) produced 127 concurrent rustc on a 128-thread host,
/// each forking a ~1GB `rust-lld` — 202GB of linkers, RAM and swap exhausted,
/// and the box wedged at 100% disk utilization for hours.
///
/// `4` makes every local fallback resolve a WORKING real cargo instead of
/// hardcoding `$HOME/.cargo/bin/cargo` (the rustup proxy). On a host whose
/// active toolchain cargo was renamed to `cargo-rch-real` (rch toolchain
/// wrapping, or a rustup update over it), that proxy cannot dispatch — rustup
/// answers "the 'cargo' binary ... is not applicable to the '<toolchain>'
/// toolchain" — so `RCH_SHIM_LOCAL_IDE=1`, the escape hatch for exactly that
/// moment, died instead (2026-08-30 fleet rollout of 943b8e29 on a
/// nightly-default dispatcher). Resolution order, first executable wins:
/// `$RCH_REAL_CARGO` → `$RCH_SHIM_REAL_CARGO` (toolchain wrapper handoff) →
/// `<active toolchain>/bin/cargo-rch-real` (discovered via
/// `rustc --print sysroot`) → `$HOME/.cargo/bin/cargo`; a resolved
/// `cargo-rch-real` gets its bin dir prepended to PATH so the build's rustc /
/// clippy-driver come from the same toolchain (repo `-Z` flags need it).
///
/// `5` recognizes Cargo's leading global options and toolchain selector without
/// rewriting argv, and routes the already-supported run/zigbuild/xwin commands
/// through ordinary RCH admission (bd-g2ppt). Test/program arguments after `--`
/// are not IDE routing instructions. Direct clippy uses the same install policy.
///
/// `6` preserves an explicit `+toolchain` on every local/IDE/bypass path.
/// Rustup owns that syntax: it selects the named installation before invoking
/// real Cargo. Passing `+nightly` to an ambient `cargo-rch-real` cannot select
/// nightly, and dropping it would silently compile with a different toolchain.
const SHIM_VERSION: &str = "6";

/// Marker line embedded in the generated shim, used to recognize an rch-managed
/// file (vs. a hand-rolled or unrelated `cargo` on `PATH`) and read its version.
const SHIM_MARKER: &str = "# rch-shim-version:";

/// Directory the shim is installed into. Deliberately NOT `~/.local/bin` (which
/// `acfs`/installers manage and could clobber) — a dedicated dir rch owns.
fn shim_dir() -> Result<PathBuf> {
    dirs::home_dir()
        .map(|h| h.join(".rch").join("shims"))
        .context("Could not determine home directory")
}

/// Path to the installed cargo shim.
fn cargo_shim_path() -> Result<PathBuf> {
    Ok(shim_dir()?.join("cargo"))
}

/// Path to the installed `cargo-clippy` shim.
fn cargo_clippy_shim_path() -> Result<PathBuf> {
    Ok(shim_dir()?.join("cargo-clippy"))
}

/// Render the `cargo-clippy` shim.
///
/// The `cargo` shim alone does not catch `cargo clippy`: build scripts, CI and
/// lint gates routinely invoke the `cargo-clippy` BINARY directly, which
/// resolves through `PATH` without ever passing through `cargo`. Those builds
/// then compile locally no matter how correctly `cargo` is shimmed.
///
/// Two entry shapes must be told apart:
///   * `cargo clippy ...` → cargo execs `cargo-clippy clippy ...` (argv[1] is
///     the literal subcommand). That outer `cargo` was already intercepted, so
///     re-entering `rch` here would double-offload; pass it straight through.
///   * `cargo-clippy ...` → invoked directly by a script. This is the leak, and
///     it is normalized to `cargo clippy ...` and offloaded.
fn cargo_clippy_shim_body(require_remote: bool) -> String {
    let offload = if require_remote {
        "exec env RCH_REQUIRE_REMOTE=1 RCH_QUEUE_WHEN_BUSY=1 rch exec -- cargo clippy \"$@\""
    } else {
        "exec rch exec -- cargo clippy \"$@\""
    };
    format!(
        r##"#!/bin/sh
# rch cargo-clippy shim — MANAGED FILE, edit via `rch shim install`.
{marker} {version}
#
# Catches DIRECT `cargo-clippy` invocations (scripts, Makefiles, lint gates)
# that bypass the `cargo` shim entirely by never going through cargo.
REAL="${{RCH_SHIM_REAL_CARGO_CLIPPY:-$HOME/.cargo/bin/cargo-clippy}}"
# Cap parallelism on every LOCAL fallback. Local builds never reach rch's slot
# accounting, so nothing else bounds them — and a repo's own .cargo/config.toml
# outranks ~/.cargo/config.toml, so a committed `jobs = -1` (= nproc-1) wins over
# any global default. CARGO_BUILD_JOBS outranks every config file, so setting it
# here is the only reliable cap. An explicitly-set CARGO_BUILD_JOBS always wins;
# tune the default with RCH_LOCAL_MAX_JOBS.
exec_local() {{
  if [ -z "${{CARGO_BUILD_JOBS:-}}" ]; then
    CARGO_BUILD_JOBS="${{RCH_LOCAL_MAX_JOBS:-8}}"
    export CARGO_BUILD_JOBS
  fi
  exec "$REAL" "$@"
}}
# Loop-break + fail-open, identical contract to the cargo shim.
if [ "${{RCH_CARGO_WRAPPER_BYPASS:-}}" = "1" ] || [ "${{RCH_SHIM_LOCAL_IDE:-}}" = "1" ] \
   || ! command -v rch >/dev/null 2>&1 || [ ! -x "$REAL" ]; then
  exec_local "$@"
fi
# Invoked BY cargo as a subcommand (`cargo-clippy clippy ...`): the outer cargo
# already made the offload decision, so never re-enter rch here.
if [ "${{1:-}}" = "clippy" ]; then
  exec_local "$@"
fi
# Direct invocation — normalize to `cargo clippy` and offload.
{offload}
"##,
        marker = SHIM_MARKER,
        version = SHIM_VERSION,
        offload = offload,
    )
}

/// Render the canonical cargo shim.
///
/// `require_remote` bakes fail-closed (queue-for-a-worker, never local rustc)
/// vs. fail-open (attempt offload, fall back to local under load) into the file.
/// A dispatcher box wants fail-closed; that is the default on install.
fn cargo_shim_body(require_remote: bool) -> String {
    // The offload line differs only by the strict-remote policy. Keeping the
    // rest identical makes drift detection a simple version-marker check.
    let offload = if require_remote {
        // Fail-closed: queue for a worker, never fall back to local rustc.
        "exec env RCH_REQUIRE_REMOTE=1 RCH_QUEUE_WHEN_BUSY=1 rch exec -- cargo \"$@\""
    } else {
        // Fail-open: attempt offload but allow local fallback (rch default).
        "exec rch exec -- cargo \"$@\""
    };
    format!(
        r##"#!/bin/sh
# rch cargo shim — MANAGED FILE, edit via `rch shim install`.
{marker} {version}
#
# Harness-agnostic build offload: any agent (codex/scripts/CI, not only Claude
# Code) that runs `cargo build|test|check|...` is routed through `rch exec` to
# the worker fleet instead of compiling locally on this box. See `rch shim`.
# Every LOCAL path (RCH_SHIM_LOCAL_IDE=1, wrapper bypass, IDE diagnostics, the
# catch-all arm) must exec a WORKING real cargo. On hosts where the active
# toolchain's cargo was renamed to `cargo-rch-real` (rch toolchain wrapping, or
# a rustup update over it), the rustup proxy at ~/.cargo/bin/cargo can no
# longer dispatch — rustup answers "the 'cargo' binary ... is not applicable
# to the '<toolchain>' toolchain" — so a single hardcoded fallback dies exactly
# when the escape hatch is needed most. The real cargo is resolved in tiers,
# first executable wins:
#   1. $RCH_REAL_CARGO       explicit operator override;
#   2. $RCH_SHIM_REAL_CARGO  set by the rch toolchain wrapper (preserves the
#                            caller's toolchain identity through the handoff);
#   3. <active-toolchain>/bin/cargo-rch-real, the active toolchain discovered
#                            via `rustc --print sysroot` (honors RUSTUP_TOOLCHAIN
#                            and rust-toolchain.toml, i.e. the toolchain this
#                            build would actually use);
#   4. $HOME/.cargo/bin/cargo — the stock rustup proxy, correct wherever rch
#                            never renamed anything.
resolve_real() {{
  if [ -n "${{RCH_REAL_CARGO:-}}" ] && [ -x "$RCH_REAL_CARGO" ]; then
    REAL="$RCH_REAL_CARGO"
    return 0
  fi
  if [ -n "${{RCH_SHIM_REAL_CARGO:-}}" ] && [ -x "$RCH_SHIM_REAL_CARGO" ]; then
    REAL="$RCH_SHIM_REAL_CARGO"
    return 0
  fi
  if command -v rustc >/dev/null 2>&1; then
    sysroot=$(rustc --print sysroot 2>/dev/null)
    if [ -n "$sysroot" ] && [ -x "$sysroot/bin/cargo-rch-real" ]; then
      REAL="$sysroot/bin/cargo-rch-real"
      return 0
    fi
  fi
  if [ -x "$HOME/.cargo/bin/cargo" ]; then
    REAL="$HOME/.cargo/bin/cargo"
    return 0
  fi
  echo "rch shim: no working real cargo found for local execution" >&2
  echo "  tried: \$RCH_REAL_CARGO, \$RCH_SHIM_REAL_CARGO, <active toolchain>/bin/cargo-rch-real, \$HOME/.cargo/bin/cargo" >&2
  echo "  fix: set RCH_REAL_CARGO=/path/to/real/cargo (e.g. \$HOME/.rustup/toolchains/<tc>/bin/cargo-rch-real)" >&2
  echo "       or restore the stock layout with: rch shim uninstall" >&2
  exit 127
}}
# Cap parallelism on every LOCAL fallback. Local builds never reach rch's slot
# accounting, so nothing else bounds them — and a repo's own .cargo/config.toml
# outranks ~/.cargo/config.toml, so a committed `jobs = -1` (= nproc-1) wins over
# any global default. CARGO_BUILD_JOBS outranks every config file, so setting it
# here is the only reliable cap. An explicitly-set CARGO_BUILD_JOBS always wins;
# tune the default with RCH_LOCAL_MAX_JOBS.
exec_local() {{
  if [ -z "${{CARGO_BUILD_JOBS:-}}" ]; then
    CARGO_BUILD_JOBS="${{RCH_LOCAL_MAX_JOBS:-8}}"
    export CARGO_BUILD_JOBS
  fi
  # +toolchain is rustup syntax, not a real Cargo subcommand. The command-line
  # selection outranks the ambient toolchain and any inherited handoff path.
  # Re-enter rustup with the selected installation and an explicit loop break:
  # its cargo may itself be an RCH toolchain wrapper.
  case "${{1:-}}" in
    +*)
      selected_toolchain="${{1#+}}"
      shift
      if [ -z "$selected_toolchain" ]; then
        echo "rch shim: an empty +toolchain selector cannot select Cargo" >&2
        exit 2
      fi
      if ! command -v rustup >/dev/null 2>&1; then
        echo "rch shim: rustup is required for the selected +$selected_toolchain; refusing to use another Cargo" >&2
        exit 127
      fi
      RCH_CARGO_WRAPPER_BYPASS=1
      export RCH_CARGO_WRAPPER_BYPASS
      exec rustup run "$selected_toolchain" cargo "$@" ;;
  esac
  resolve_real
  # A renamed toolchain cargo runs with its own bin dir FIRST on PATH, or the
  # build's rustc/clippy-driver resolve through the rustup proxy's default
  # toolchain instead of the one being built with (breaks -Z flags in a repo's
  # .cargo/config.toml when default != requested toolchain).
  case "$REAL" in
    */cargo-rch-real)
      PATH="${{REAL%/*}}:$PATH"
      export PATH
      ;;
  esac
  exec "$REAL" "$@"
}}
# Loop-break: rch sets RCH_CARGO_WRAPPER_BYPASS=1 on its own local-fallback exec.
# Also fail open if rch is unavailable — never block a build.
if [ "${{RCH_CARGO_WRAPPER_BYPASS:-}}" = "1" ] || ! command -v rch >/dev/null 2>&1; then
  exec_local "$@"
fi
# Explicit operator escape hatch: force this one build local.
if [ "${{RCH_SHIM_LOCAL_IDE:-}}" = "1" ]; then
  exec_local "$@"
fi
# `cargo clippy` runs as: set RUSTC_WORKSPACE_WRAPPER=clippy-driver, then exec an
# inner `cargo check`. Offloading that INNER cargo would drop the wrapper and
# silently return plain check results instead of lints, so it stays local — the
# OUTER `cargo clippy` is the invocation that offloads. Same for any other
# caller-chosen rustc wrapper.
if [ -n "${{RUSTC_WORKSPACE_WRAPPER:-}}" ]; then
  exec_local "$@"
fi
# rust-analyzer must stay local (streaming JSON + local state). It is identified
# by its distinctive rendered-ansi/short diagnostic formats. A PLAIN
# `--message-format=json` is what scripts, CI and build tooling pass, and those
# must still offload — treating every --message-format as an IDE was the bug
# that silently kept script-driven builds on the dev box.
format_value=0
for a in "$@"; do
  if [ "$format_value" = "1" ]; then
    case "$a" in
      json-diagnostic-rendered-ansi*|json-diagnostic-short*) exec_local "$@" ;;
    esac
    format_value=0
    continue
  fi
  case "$a" in
    --) break ;;
    --message-format) format_value=1 ;;
    --message-format=json-diagnostic-rendered-ansi*|--message-format=json-diagnostic-short*)
      exec_local "$@" ;;
  esac
done
# Inspect a function-local copy of argv. Never shift the caller's arguments or
# reconstruct a shell command: option values can contain spaces, quotes, and
# names such as "build". RCH still owns eligibility, topology and placement.
# Only the first argument can be rustup's +toolchain selector. Unknown options
# stay local rather than guessing. Recognizing -C does not change cwd here:
# RCH's source-closure preflight must still approve or refuse that request.
find_subcommand() {{
  rch_subcommand=
  case "${{1:-}}" in +?*) shift ;; esac
  while [ "$#" -gt 0 ]; do
    case "$1" in
      -v|-vv|-vvv|--verbose|-q|--quiet|--locked|--offline|--frozen) shift ;;
      --color|--config|-Z|-C)
        [ "$#" -ge 2 ] || return 0
        shift 2 ;;
      --color=?*|--config=?*|-Z?*|-C?*) shift ;;
      --) shift; break ;;
      -*) return 0 ;;
      *) break ;;
    esac
  done
  rch_subcommand="${{1:-}}"
}}
find_subcommand "$@"
case "$rch_subcommand" in
  build|b|test|t|check|c|clippy|bench|doc|nextest|run|r|zigbuild|xwin)
    {offload} ;;
  *)
    exec_local "$@" ;;
esac
"##,
        marker = SHIM_MARKER,
        version = SHIM_VERSION,
        offload = offload,
    )
}

/// Read the `SHIM_VERSION` recorded in an installed shim, if it is rch-managed.
fn installed_shim_version(path: &Path) -> Option<String> {
    let content = std::fs::read_to_string(path).ok()?;
    content.lines().find_map(|line| {
        line.trim()
            .strip_prefix(SHIM_MARKER)
            .map(|v| v.trim().to_string())
    })
}

/// How `cargo` actually resolves on this box right now.
///
/// Comparing raw `PATH` order against `shim_dir` is not sufficient: installers
/// (and rch's own docs) legitimately place a *delegating* `cargo` earlier on
/// `PATH` — a tiny script whose only job is to `exec` the canonical shim. That
/// still intercepts, so reporting "not intercepted" for it is a false alarm
/// that sends operators off reordering `PATH` for no reason.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
enum Interception {
    /// `PATH` resolves straight to the rch shim.
    Direct,
    /// `PATH` resolves to a wrapper that delegates to the rch shim.
    Delegated,
    /// `PATH` resolves to a real cargo binary — builds run locally.
    None,
}

impl Interception {
    fn intercepts(self) -> bool {
        matches!(self, Self::Direct | Self::Delegated)
    }
}

/// True if `path` is a small text file that hands off to the rch shim.
///
/// Recognize legacy shim references and marked standalone copies. This small
/// text-file heuristic does not interpret arbitrary shell control flow.
fn delegates_to_shim(path: &Path, target_executable: bool) -> bool {
    let Ok(meta) = std::fs::metadata(path) else {
        return false;
    };
    // A real cargo is megabytes; a delegating shell wrapper is a few hundred
    // bytes. Bail early so we never slurp a binary.
    if meta.len() > 8 * 1024 {
        return false;
    }
    let Ok(content) = std::fs::read_to_string(path) else {
        return false;
    };
    // Marked standalone shim copies intercept themselves. Legacy delegators
    // instead test the canonical target's executable bit before handing off.
    (target_executable && content.contains(".rch/shims/cargo")) || content.contains(SHIM_MARKER)
}

/// Resolve the first `cargo` on this process's `PATH` and classify it.
fn cargo_interception(shim: &Path) -> Interception {
    let Some(path) = std::env::var_os("PATH") else {
        return Interception::None;
    };
    let Ok(cwd) = std::env::current_dir() else {
        return Interception::None;
    };
    cargo_interception_in(&path, shim, &cwd)
}

/// Resolve external commands with an explicit PATH and absolute working
/// directory, without changing process-global environment or cwd. Normalize
/// candidates before using `which` so a literal `~` in PATH stays literal.
fn cargo_interception_in(path: &std::ffi::OsStr, shim: &Path, cwd: &Path) -> Interception {
    if !cwd.is_absolute() {
        return Interception::None;
    }
    let Ok(shim) = cwd.join(shim).canonicalize() else {
        return Interception::None;
    };
    // Legacy delegators use `test -x` before handing off. An installed but
    // non-executable target sends them to real cargo instead.
    let shim_executable = which::which(&shim).is_ok();
    for entry in std::env::split_paths(path) {
        // Joining also maps empty entries to cwd, exactly where an external
        // shell lookup searches. Non-executable files do not shadow later hits.
        let candidate = cwd.join(entry).join("cargo");
        let Ok(candidate) = which::which(candidate) else {
            continue;
        };
        // Resolve symlink identity before applying the bounded legacy wrapper
        // heuristic; a symlink to this shim is direct interception.
        if candidate.canonicalize().ok().as_ref() == Some(&shim) {
            return Interception::Direct;
        }
        if delegates_to_shim(&candidate, shim_executable) {
            return Interception::Delegated;
        }
        return Interception::None;
    }
    Interception::None
}

// ---------------------------------------------------------------------------
// Toolchain wrapping
//
// The PATH shim only catches PATH lookups. Scripts, Makefiles, build drivers
// and agents routinely invoke `~/.rustup/toolchains/<tc>/bin/cargo` by ABSOLUTE
// path (rustup's own `cargo +nightly ...` re-exec does too), which bypasses
// PATH entirely. Wrapping the toolchain binary itself is the one layer an
// absolute-path call cannot dodge, so `shim install` does it too.
//
// Mechanism, per toolchain:
//   cargo           -> wrapper script (delegates to the canonical shim)
//   cargo-rch-real  -> the original binary, preserved by hardlinking it first
// Linking (rather than moving) the original means `cargo` never stops existing
// for even an instant, copies no bytes, and leaves the code signature intact.
// The swap-in is an atomic rename, so a concurrent exec sees either the old or
// the new file, never a missing one. (After the rename the two names no longer
// share a link count: `cargo` is the new wrapper inode and `cargo-rch-real` is
// the sole remaining name for the original inode — which is the point.)
// ---------------------------------------------------------------------------

/// Bumped whenever the toolchain wrapper body changes.
///
/// Version `1` is also what the predecessor `wrap_toolchain_cargo.sh` emitted,
/// and hosts wrapped by that script are already in the field. The two bodies are
/// behaviourally identical (same bypass check, same shim handoff, same
/// `RCH_SHIM_REAL_CARGO` export) and differ only in a comment, so they
/// legitimately share a version and `install` leaves them alone. Bump this the
/// moment the body changes semantically, which will also converge those hosts.
///
/// `3` prepends the toolchain's own bin dir to PATH in the wrapper's local
/// fallback, so a bypassed build resolves rustc/clippy-driver from THAT
/// toolchain instead of the rustup proxy's default — mirroring the tiered
/// resolution of shim v4 (same 2026-08-30 nightly-renamed-cargo incident).
const TOOLCHAIN_WRAP_VERSION: &str = "3";

/// Marker identifying an rch-managed toolchain wrapper (vs. the real binary).
const TOOLCHAIN_MARKER: &str = "# rch-toolchain-wrap-version:";

/// Filename the original toolchain cargo is preserved under.
const REAL_CARGO_NAME: &str = "cargo-rch-real";

/// `~/.rustup/toolchains`, honoring `RUSTUP_HOME`.
fn rustup_toolchains_dir() -> Option<PathBuf> {
    if let Some(home) = std::env::var_os("RUSTUP_HOME") {
        return Some(PathBuf::from(home).join("toolchains"));
    }
    dirs::home_dir().map(|h| h.join(".rustup").join("toolchains"))
}

/// Every installed toolchain's `bin/cargo`, sorted for stable output.
fn toolchain_cargos() -> Vec<PathBuf> {
    let Some(root) = rustup_toolchains_dir() else {
        return Vec::new();
    };
    let Ok(entries) = std::fs::read_dir(&root) else {
        return Vec::new();
    };
    let mut out: Vec<PathBuf> = entries
        .flatten()
        .map(|e| e.path().join("bin").join("cargo"))
        .filter(|p| p.is_file())
        .collect();
    out.sort();
    out
}

/// Render the toolchain wrapper.
///
/// `$0` is the toolchain's own `bin/cargo`, so the wrapper can find its sibling
/// `cargo-rch-real` without hardcoding a toolchain name. Exporting
/// `RCH_SHIM_REAL_CARGO` preserves *toolchain identity* through any local
/// fallback — otherwise rch's fallback would silently build with the rustup
/// default toolchain instead of the one the caller explicitly asked for.
fn toolchain_wrap_body() -> String {
    format!(
        r##"#!/bin/sh
# rch toolchain cargo wrapper — MANAGED FILE, edit via `rch shim install`.
{marker} {version}
#
# Routes ABSOLUTE-path toolchain cargo calls through the canonical rch shim.
# Scripts/Makefiles/agents invoking ~/.rustup/toolchains/<tc>/bin/cargo directly
# bypass PATH; this is the one layer they cannot dodge.
SELF_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
REAL="$SELF_DIR/{real}"
SHIM="$HOME/.rch/shims/cargo"
# Same local-parallelism cap as the cargo shim: this path runs the real toolchain
# cargo directly, so it must not inherit an unbounded `-j` from a repo config.
exec_local() {{
  if [ -z "${{CARGO_BUILD_JOBS:-}}" ]; then
    CARGO_BUILD_JOBS="${{RCH_LOCAL_MAX_JOBS:-8}}"
    export CARGO_BUILD_JOBS
  fi
  # The real cargo is a toolchain binary: its children (rustc, clippy-driver,
  # rust-lld) must resolve from THIS toolchain's bin, not from whatever the
  # rustup proxy default happens to be — same rule as the shim's local fallback.
  PATH="$SELF_DIR:$PATH"
  export PATH
  exec "$REAL" "$@"
}}
# Loop-break + fail-open: rch sets RCH_CARGO_WRAPPER_BYPASS=1 on its own local
# fallback exec. Never block a build if the shim or rch is missing.
if [ "${{RCH_CARGO_WRAPPER_BYPASS:-}}" = "1" ] || [ ! -x "$SHIM" ] || ! command -v rch >/dev/null 2>&1; then
  exec_local "$@"
fi
# Preserve toolchain identity through any local fallback.
RCH_SHIM_REAL_CARGO="$REAL"
export RCH_SHIM_REAL_CARGO
exec "$SHIM" "$@"
"##,
        marker = TOOLCHAIN_MARKER,
        version = TOOLCHAIN_WRAP_VERSION,
        real = REAL_CARGO_NAME,
    )
}

/// Version recorded in an installed toolchain wrapper, if it is rch-managed.
fn toolchain_wrap_version(path: &Path) -> Option<String> {
    // Only ever read small files; a real cargo binary is megabytes.
    let meta = std::fs::metadata(path).ok()?;
    if meta.len() > 8 * 1024 {
        return None;
    }
    let content = std::fs::read_to_string(path).ok()?;
    content.lines().find_map(|line| {
        line.trim()
            .strip_prefix(TOOLCHAIN_MARKER)
            .map(|v| v.trim().to_string())
    })
}

fn is_toolchain_wrapped(path: &Path) -> bool {
    toolchain_wrap_version(path).is_some()
}

/// Outcome of wrapping a single toolchain, for reporting.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WrapOutcome {
    Wrapped,
    Refreshed,
    AlreadyCurrent,
}

/// Wrap one toolchain's `cargo`.
#[cfg(unix)]
fn wrap_toolchain_cargo(cargo: &Path) -> Result<WrapOutcome> {
    use std::os::unix::fs::PermissionsExt;

    let dir = cargo
        .parent()
        .context("toolchain cargo has no parent directory")?;
    let real = dir.join(REAL_CARGO_NAME);

    if let Some(v) = toolchain_wrap_version(cargo) {
        if v == TOOLCHAIN_WRAP_VERSION && real.exists() {
            return Ok(WrapOutcome::AlreadyCurrent);
        }
        // Wrapper present but stale (or its real binary vanished): rewrite the
        // wrapper in place. `real` is already the original, so do NOT re-link
        // from `cargo` — that would hardlink the wrapper onto itself.
        if !real.exists() {
            anyhow::bail!(
                "{} is an rch wrapper but {} is missing — cannot recover the real cargo; \
                 reinstall this toolchain with `rustup toolchain install --force`",
                cargo.display(),
                real.display()
            );
        }
        atomic_write(cargo, toolchain_wrap_body().as_bytes())
            .with_context(|| format!("Failed to refresh wrapper at {}", cargo.display()))?;
        let mut perms = std::fs::metadata(cargo)?.permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(cargo, perms)?;
        return Ok(WrapOutcome::Refreshed);
    }

    // `cargo` is the real binary here. A leftover `cargo-rch-real` means rustup
    // replaced the toolchain after a previous wrap; drop the stale copy so we
    // preserve the NEW binary rather than resurrecting the old one.
    if real.exists() {
        std::fs::remove_file(&real)
            .with_context(|| format!("Failed to remove stale real cargo at {}", real.display()))?;
    }
    std::fs::hard_link(cargo, &real).with_context(|| {
        format!(
            "Failed to hardlink {} -> {}",
            cargo.display(),
            real.display()
        )
    })?;
    // Guard the TOCTOU window: if a concurrent `shim install` swapped in its
    // wrapper between our not-wrapped check and this link, we just preserved a
    // WRAPPER as the "real" cargo — and writing our wrapper over `cargo` next
    // would destroy the toolchain's only real binary. Undo and fail loudly
    // instead; the other run already did the work correctly.
    if is_toolchain_wrapped(&real) {
        let _ = std::fs::remove_file(&real);
        anyhow::bail!(
            "concurrent wrap detected for {}: refusing to preserve a wrapper as the real cargo",
            cargo.display()
        );
    }
    // Atomic rename over `cargo`; a concurrent exec sees old or new, never gone.
    if let Err(e) = atomic_write(cargo, toolchain_wrap_body().as_bytes()) {
        // Roll back so the toolchain is never left without its real cargo.
        let _ = std::fs::remove_file(&real);
        return Err(e).with_context(|| format!("Failed to write wrapper at {}", cargo.display()));
    }
    let mut perms = std::fs::metadata(cargo)?.permissions();
    perms.set_mode(0o755);
    std::fs::set_permissions(cargo, perms)?;
    Ok(WrapOutcome::Wrapped)
}

#[cfg(not(unix))]
fn wrap_toolchain_cargo(_cargo: &Path) -> Result<WrapOutcome> {
    anyhow::bail!("toolchain wrapping is only supported on Unix")
}

/// Restore one toolchain's original `cargo`.
fn unwrap_toolchain_cargo(cargo: &Path) -> Result<bool> {
    if !is_toolchain_wrapped(cargo) {
        return Ok(false);
    }
    let dir = cargo
        .parent()
        .context("toolchain cargo has no parent directory")?;
    let real = dir.join(REAL_CARGO_NAME);
    if !real.exists() {
        anyhow::bail!(
            "refusing to remove wrapper at {}: {} is missing (no real cargo to restore)",
            cargo.display(),
            real.display()
        );
    }
    std::fs::rename(&real, cargo)
        .with_context(|| format!("Failed to restore real cargo at {}", cargo.display()))?;
    Ok(true)
}

/// Wrapped/total counts across all installed toolchains.
fn toolchain_wrap_counts() -> (usize, usize) {
    let cargos = toolchain_cargos();
    let wrapped = cargos.iter().filter(|c| is_toolchain_wrapped(c)).count();
    (wrapped, cargos.len())
}

fn toolchain_wrappers_current() -> bool {
    toolchain_cargos().iter().all(|cargo| {
        toolchain_wrap_version(cargo).as_deref() == Some(TOOLCHAIN_WRAP_VERSION)
            && which::which(cargo).is_ok()
            && which::which(cargo.with_file_name(REAL_CARGO_NAME)).is_ok()
    })
}

/// Count `rustc`/`cargo` processes running on this box right now (best-effort,
/// Unix only). A dispatcher with the shim working should see ~0 (aside from
/// rust-analyzer's short-lived probes).
#[cfg(unix)]
fn local_build_process_count() -> Option<usize> {
    let out = std::process::Command::new("pgrep")
        .args(["-x", "rustc"])
        .output()
        .ok()?;
    if !out.status.success() && out.stdout.is_empty() {
        return Some(0);
    }
    Some(
        out.stdout
            .split(|b| *b == b'\n')
            .filter(|l| !l.is_empty())
            .count(),
    )
}

#[cfg(not(unix))]
fn local_build_process_count() -> Option<usize> {
    None
}

/// Machine-readable result for `--json`.
#[derive(Debug, Serialize)]
struct ShimStatus {
    installed: bool,
    /// Whether the companion `cargo-clippy` shim is present. Without it, a
    /// script invoking the `cargo-clippy` binary directly bypasses offload
    /// entirely, so agents need to see this separately from `installed`.
    clippy_shim_installed: bool,
    path: String,
    version: Option<String>,
    embedded_version: String,
    up_to_date: bool,
    /// Kept for compatibility: true when `cargo` resolves to the shim by any
    /// route (directly or via a delegating wrapper).
    on_path_ahead_of_cargo: bool,
    /// How `cargo` actually resolves: direct / delegated / none.
    interception: Interception,
    local_builds_running: Option<usize>,
    /// Rustup toolchains whose `bin/cargo` is wrapped, and the total installed.
    toolchains_wrapped: usize,
    toolchains_total: usize,
    /// Per-toolchain failures from the last wrap/unwrap attempt. Without this a
    /// `--json` consumer sees `wrapped < total` with no way to learn why, which
    /// matters because this output is meant for agents.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    toolchain_errors: Vec<String>,
}

/// `rch shim install` — write (or refresh) the canonical cargo shim, and wrap
/// the rustup toolchain cargos so absolute-path invocations are caught too.
pub fn shim_install(
    require_remote: bool,
    wrap_toolchains: bool,
    ctx: &OutputContext,
) -> Result<()> {
    // bd-wywsj: a WORKER box is the compute — shimming cargo to
    // offload from it is a configuration error, refused loudly.
    if let Ok(config) = crate::config::load_config()
        && config.general.role == rch_common::BoxRole::Worker
    {
        anyhow::bail!(
            "refusing to install the cargo shim: general.role = \"worker\" — this box IS \
             the compute. Set role = \"dispatcher\" or \"hybrid\" in config.toml if this \
             machine should offload builds."
        );
    }
    let style = ctx.theme();
    let path = cargo_shim_path()?;
    let body = cargo_shim_body(require_remote);

    let existed = path.exists();
    atomic_write(&path, body.as_bytes())
        .with_context(|| format!("Failed to write cargo shim to {}", path.display()))?;
    // atomic_write does not preserve mode; make it executable.
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = std::fs::metadata(&path)?.permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&path, perms)?;
    }

    // `cargo-clippy` is a separate binary on PATH; a script calling it directly
    // never touches the cargo shim, so it needs its own.
    let clippy_path = cargo_clippy_shim_path()?;
    atomic_write(
        &clippy_path,
        cargo_clippy_shim_body(require_remote).as_bytes(),
    )
    .with_context(|| {
        format!(
            "Failed to write cargo-clippy shim to {}",
            clippy_path.display()
        )
    })?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = std::fs::metadata(&clippy_path)?.permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&clippy_path, perms)?;
    }

    // Wrap the rustup toolchains too — the PATH shim alone cannot catch an
    // absolute-path `~/.rustup/toolchains/<tc>/bin/cargo` invocation, which is
    // how scripts, Makefiles and `cargo +toolchain` re-execs reach cargo.
    let mut wrapped_now = 0usize;
    let mut refreshed = 0usize;
    let mut already = 0usize;
    let mut wrap_errors: Vec<String> = Vec::new();
    if wrap_toolchains {
        for cargo in toolchain_cargos() {
            match wrap_toolchain_cargo(&cargo) {
                Ok(WrapOutcome::Wrapped) => wrapped_now += 1,
                Ok(WrapOutcome::Refreshed) => refreshed += 1,
                Ok(WrapOutcome::AlreadyCurrent) => already += 1,
                // One bad toolchain must not abort the rest; report and move on.
                Err(e) => wrap_errors.push(format!("{}: {e:#}", cargo.display())),
            }
        }
    }

    let interception = cargo_interception(&path);
    let ahead = interception.intercepts();
    let (tc_wrapped, tc_total) = toolchain_wrap_counts();

    if ctx.is_json() {
        let status = ShimStatus {
            installed: true,
            clippy_shim_installed: cargo_clippy_shim_path()
                .map(|p| p.exists())
                .unwrap_or(false),
            path: path.display().to_string(),
            version: Some(SHIM_VERSION.to_string()),
            embedded_version: SHIM_VERSION.to_string(),
            up_to_date: true,
            on_path_ahead_of_cargo: ahead,
            interception,
            local_builds_running: local_build_process_count(),
            toolchains_wrapped: tc_wrapped,
            toolchains_total: tc_total,
            toolchain_errors: wrap_errors.clone(),
        };
        let _ = ctx.json(&status);
        return Ok(());
    }

    println!(
        "{} {} cargo shim at {}",
        StatusIndicator::Success.display(style),
        if existed { "Updated" } else { "Installed" },
        style.highlight(&path.display().to_string())
    );
    println!(
        "  policy: {}",
        if require_remote {
            "fail-closed (queue for a worker; never build locally)"
        } else {
            "fail-open (offload, but fall back to local under load)"
        }
    );
    println!(
        "  local fallback resolves real cargo: $RCH_REAL_CARGO → $RCH_SHIM_REAL_CARGO → <active toolchain>/bin/cargo-rch-real → ~/.cargo/bin/cargo"
    );
    if wrap_toolchains {
        if tc_total == 0 {
            println!(
                "  {} no rustup toolchains found to wrap",
                StatusIndicator::Info.display(style)
            );
        } else {
            println!(
                "  {} toolchains: {tc_wrapped}/{tc_total} wrapped ({wrapped_now} new, {refreshed} refreshed, {already} already current)",
                StatusIndicator::Success.display(style)
            );
        }
        for err in &wrap_errors {
            println!("  {} {err}", StatusIndicator::Warning.display(style));
        }
    }

    match interception {
        Interception::None => {
            let dir = shim_dir()?;
            println!(
                "\n{} The shim is not yet ahead of ~/.cargo/bin on PATH. Add this to your shell rc:",
                StatusIndicator::Warning.display(style)
            );
            println!("    export PATH=\"{}:$PATH\"", dir.display());
            println!("  then restart your shells (or `hash -r`).");
            if tc_wrapped > 0 {
                println!(
                    "  {} toolchain wrappers still catch absolute-path cargo calls meanwhile.",
                    StatusIndicator::Info.display(style)
                );
            }
        }
        Interception::Direct => println!(
            "  {} PATH already resolves this shim ahead of ~/.cargo/bin.",
            StatusIndicator::Info.display(style)
        ),
        Interception::Delegated => println!(
            "  {} PATH resolves a wrapper that delegates to this shim — cargo is intercepted.",
            StatusIndicator::Info.display(style)
        ),
    }
    Ok(())
}

/// Read-only checks shared with the dispatcher's doctor report.
pub(crate) fn dispatcher_shim_problems() -> Result<Vec<String>> {
    let mut problems = Vec::new();
    let cargo = cargo_shim_path()?;
    let clippy = cargo_clippy_shim_path()?;
    for (name, path) in [("cargo", &cargo), ("cargo-clippy", &clippy)] {
        if which::which(path).is_err() {
            problems.push(format!("{name} shim is missing or not executable"));
        } else if installed_shim_version(path).as_deref() != Some(SHIM_VERSION) {
            problems.push(format!("{name} shim is stale or unmanaged"));
        }
    }
    if !cargo_interception(&cargo).intercepts() {
        problems.push("PATH does not resolve Cargo through the RCH shim".to_string());
    }
    let (wrapped, total) = toolchain_wrap_counts();
    if wrapped != total {
        problems.push(format!(
            "only {wrapped}/{total} toolchain Cargo binaries are wrapped"
        ));
    } else if !toolchain_wrappers_current() {
        problems.push("toolchain Cargo wrappers are stale or not executable".to_string());
    }
    Ok(problems)
}

/// Report shim install state without changing shell or toolchain files.
pub fn shim_status(ctx: &OutputContext) -> Result<()> {
    let style = ctx.theme();
    let path = cargo_shim_path()?;
    let installed = path.exists();
    let version = if installed {
        installed_shim_version(&path)
    } else {
        None
    };
    let up_to_date = version.as_deref() == Some(SHIM_VERSION)
        && which::which(&path).is_ok()
        && cargo_clippy_shim_path().is_ok_and(|clippy| {
            installed_shim_version(&clippy).as_deref() == Some(SHIM_VERSION)
                && which::which(clippy).is_ok()
        })
        && toolchain_wrappers_current();
    let interception = if installed {
        cargo_interception(&path)
    } else {
        Interception::None
    };
    let ahead = interception.intercepts();
    let local_builds = local_build_process_count();
    let (tc_wrapped, tc_total) = toolchain_wrap_counts();
    let clippy_installed = cargo_clippy_shim_path()
        .map(|p| p.exists())
        .unwrap_or(false);

    if ctx.is_json() {
        let status = ShimStatus {
            installed,
            clippy_shim_installed: clippy_installed,
            path: path.display().to_string(),
            version,
            embedded_version: SHIM_VERSION.to_string(),
            up_to_date,
            on_path_ahead_of_cargo: ahead,
            interception,
            local_builds_running: local_builds,
            toolchains_wrapped: tc_wrapped,
            toolchains_total: tc_total,
            // `status` never mutates, so it has no failures of its own.
            toolchain_errors: Vec::new(),
        };
        let _ = ctx.json(&status);
        return Ok(());
    }

    // Surfaced separately from the cargo shim: a box can have a perfect cargo
    // shim and still leak every `cargo-clippy` call a lint gate makes.
    let clippy_note = if clippy_installed {
        None
    } else {
        Some(format!(
            "{} cargo-clippy shim missing — direct `cargo-clippy` calls (lint \
             gates, CI scripts) will build LOCALLY. Run `rch shim install`.",
            StatusIndicator::Warning.display(style)
        ))
    };

    if !installed {
        if let Some(note) = &clippy_note {
            println!("  {note}");
        }
        println!(
            "{} cargo shim not installed. Run `rch shim install`.",
            StatusIndicator::Warning.display(style)
        );
        return Ok(());
    }
    println!(
        "{} cargo shim installed at {}",
        StatusIndicator::Success.display(style),
        style.highlight(&path.display().to_string())
    );
    if up_to_date {
        println!("  version: {SHIM_VERSION} (current)");
    } else {
        println!(
            "  {} version: {} (embedded {SHIM_VERSION}) — run `rch shim install` to refresh",
            StatusIndicator::Warning.display(style),
            version.as_deref().unwrap_or("unknown")
        );
    }
    match &clippy_note {
        Some(note) => println!("  {note}"),
        None => println!(
            "  {} cargo-clippy shim installed — direct clippy calls offload too",
            StatusIndicator::Success.display(style)
        ),
    }
    match interception {
        Interception::Direct => println!(
            "  {} PATH resolves the shim ahead of ~/.cargo/bin",
            StatusIndicator::Info.display(style)
        ),
        Interception::Delegated => println!(
            "  {} PATH resolves a wrapper that delegates to this shim — cargo IS intercepted",
            StatusIndicator::Info.display(style)
        ),
        Interception::None => println!(
            "  {} PATH does NOT resolve the shim first — cargo is not being intercepted",
            StatusIndicator::Warning.display(style)
        ),
    }
    if tc_total == 0 {
        println!(
            "  {} no rustup toolchains installed",
            StatusIndicator::Info.display(style)
        );
    } else if tc_wrapped == tc_total {
        println!(
            "  {} toolchains: {tc_wrapped}/{tc_total} wrapped (absolute-path cargo is intercepted)",
            StatusIndicator::Info.display(style)
        );
    } else {
        println!(
            "  {} toolchains: {tc_wrapped}/{tc_total} wrapped — {} unwrapped toolchain(s) can still build locally via absolute path; run `rch shim install`",
            StatusIndicator::Warning.display(style),
            tc_total - tc_wrapped
        );
    }
    if let Some(n) = local_builds {
        if n == 0 {
            println!(
                "  {} no local rustc running",
                StatusIndicator::Info.display(style)
            );
        } else {
            println!(
                "  {} {n} local rustc running — builds are compiling on this box (check PATH order / unwrapped toolchains above)",
                StatusIndicator::Warning.display(style)
            );
        }
    }
    Ok(())
}

/// `rch shim uninstall` — remove the cargo shim.
pub fn shim_uninstall(ctx: &OutputContext) -> Result<()> {
    let style = ctx.theme();
    let path = cargo_shim_path()?;

    // Always restore toolchains, even if the PATH shim is already gone —
    // otherwise a half-uninstalled box keeps wrappers pointing at a missing
    // shim. (They fail open, but leaving them is still a surprise.)
    let mut restored = 0usize;
    let mut unwrap_errors: Vec<String> = Vec::new();
    for cargo in toolchain_cargos() {
        match unwrap_toolchain_cargo(&cargo) {
            Ok(true) => restored += 1,
            Ok(false) => {}
            Err(e) => unwrap_errors.push(format!("{}: {e:#}", cargo.display())),
        }
    }

    let had_shim = path.exists();
    if had_shim {
        std::fs::remove_file(&path)
            .with_context(|| format!("Failed to remove cargo shim at {}", path.display()))?;
    }

    // Remove the companion cargo-clippy shim too; leaving it behind would keep
    // routing clippy through an rch that the operator just opted out of.
    let clippy_path = cargo_clippy_shim_path()?;
    if clippy_path.exists() {
        std::fs::remove_file(&clippy_path).with_context(|| {
            format!(
                "Failed to remove cargo-clippy shim at {}",
                clippy_path.display()
            )
        })?;
    }

    if ctx.is_json() {
        let (tc_wrapped, tc_total) = toolchain_wrap_counts();
        let status = ShimStatus {
            installed: false,
            clippy_shim_installed: false,
            path: path.display().to_string(),
            version: None,
            embedded_version: SHIM_VERSION.to_string(),
            up_to_date: false,
            on_path_ahead_of_cargo: false,
            interception: Interception::None,
            local_builds_running: local_build_process_count(),
            toolchains_wrapped: tc_wrapped,
            toolchains_total: tc_total,
            toolchain_errors: unwrap_errors.clone(),
        };
        let _ = ctx.json(&status);
        return Ok(());
    }

    if had_shim {
        println!(
            "{} Removed cargo shim at {}",
            StatusIndicator::Success.display(style),
            style.highlight(&path.display().to_string())
        );
    } else {
        println!(
            "{} cargo shim not installed; nothing to remove.",
            StatusIndicator::Info.display(style)
        );
    }
    if restored > 0 {
        println!(
            "  {} restored {restored} toolchain cargo binaries",
            StatusIndicator::Success.display(style)
        );
    }
    for err in &unwrap_errors {
        println!("  {} {err}", StatusIndicator::Warning.display(style));
    }
    Ok(())
}

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

    #[test]
    fn shim_body_is_loop_safe_and_fail_open() {
        let body = cargo_shim_body(true);
        // Honors rch's own bypass and the missing-rch case up front.
        assert!(body.contains("RCH_CARGO_WRAPPER_BYPASS"));
        assert!(body.contains("command -v rch"));
        // rust-analyzer's JSON checks stay local.
        assert!(body.contains("--message-format"));
        // Offload set present.
        assert!(body.contains("build|b|test|t|check|c|clippy|bench|doc|nextest"));
        // Version marker present and parseable.
        assert_eq!(
            installed_shim_version_from_str(&body).as_deref(),
            Some(SHIM_VERSION)
        );
    }

    #[test]
    fn require_remote_toggles_fail_closed() {
        let closed = cargo_shim_body(true);
        let open = cargo_shim_body(false);
        assert!(closed.contains("RCH_REQUIRE_REMOTE=1"));
        assert!(closed.contains("RCH_QUEUE_WHEN_BUSY=1"));
        assert!(!open.contains("RCH_REQUIRE_REMOTE=1"));
        assert!(open.contains("rch exec -- cargo"));
    }

    #[test]
    fn shim_only_offloads_build_subcommands() {
        let body = cargo_shim_body(true);
        // The catch-all arm runs the real cargo for everything else.
        assert!(body.contains("*)\n    exec_local \"$@\" ;;"));
    }

    /// Execute a rendered shim body under `/bin/sh` in a sandbox and report
    /// whether it offloaded or ran the real cargo.
    ///
    /// String assertions cannot tell us what the script actually *does* — and a
    /// shell syntax error in a generated file would ship silently — so these
    /// tests run it for real against stub `rch` / `cargo` executables.
    #[cfg(unix)]
    fn write_exe(p: &Path, contents: &str) {
        use std::io::Write;
        use std::os::unix::fs::PermissionsExt;
        let mut f = std::fs::File::create(p).unwrap();
        f.write_all(contents.as_bytes()).unwrap();
        let mut perms = std::fs::metadata(p).unwrap().permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(p, perms).unwrap();
    }

    /// `Command::output()` that retries `ETXTBSY`.
    ///
    /// `write_exe` closes its handle before returning, but a sibling test
    /// thread can fork while that handle is still open; until the child
    /// execs, the inherited descriptor keeps the file "busy" and executing
    /// it fails with `ExecutableFileBusy`. The window is microseconds and
    /// belongs to an unrelated test, so retry briefly instead of failing
    /// this one (seen as a different shim test each run on rch workers).
    #[cfg(unix)]
    fn output_retrying_text_busy(cmd: &mut std::process::Command) -> std::process::Output {
        let mut attempts = 0;
        loop {
            match cmd.output() {
                Err(e) if e.kind() == std::io::ErrorKind::ExecutableFileBusy && attempts < 50 => {
                    attempts += 1;
                    std::thread::sleep(std::time::Duration::from_millis(10));
                }
                // The shim itself execs freshly written stubs (`rch`,
                // `real-cargo`), so the same race also surfaces inside the
                // child shell as exit 126 "Text file busy" (bd-04yji).
                Ok(output)
                    if output.status.code() == Some(126)
                        && String::from_utf8_lossy(&output.stderr).contains("Text file busy")
                        && attempts < 50 =>
                {
                    attempts += 1;
                    std::thread::sleep(std::time::Duration::from_millis(10));
                }
                result => return result.expect("spawn sandboxed shim"),
            }
        }
    }

    /// Create a unique sandbox carrying the shim plus the standard stubs
    /// (`rch` announces OFFLOAD, `real-cargo` announces LOCAL and the job cap),
    /// and return its dir. Tests needing more elaborate hosts (fake toolchains,
    /// a broken rustup proxy, a stub `rustc` for sysroot discovery) add their
    /// own stubs before [`exec_shim`].
    ///
    /// Sandboxes MUST be unique per invocation. Keying on (name, pid, args)
    /// alone collides whenever two tests exercise the same argv -- and since
    /// tests run in parallel threads of ONE process, the loser has its stub
    /// `real-cargo` deleted mid-run and fails with ENOENT/exit 127.
    #[cfg(unix)]
    fn shim_sandbox(body: &str, name: &str, args: &[&str]) -> PathBuf {
        static SEQ: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
        let seq = SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        let dir = std::env::temp_dir().join(format!(
            "rch-shim-test-{}-{}-{}-{}",
            name,
            std::process::id(),
            args.join("_").replace(['/', '=', '-', ' '], ""),
            seq
        ));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();

        write_exe(&dir.join(name), body);
        // Stubs: each announces which path was taken.
        // Each stub also reports the resolved job cap, so tests can prove the
        // local-parallelism guard fires on local paths and NOT on offload.
        // Existing assertions use starts_with(), so the suffix is safe.
        write_exe(
            &dir.join("rch"),
            "#!/bin/sh\necho OFFLOAD \"$@\" jobs=${CARGO_BUILD_JOBS:-unset}\n",
        );
        write_exe(
            &dir.join("real-cargo"),
            "#!/bin/sh\necho LOCAL \"$@\" jobs=${CARGO_BUILD_JOBS:-unset}\n",
        );
        dir
    }

    /// Run the sandboxed shim. `home` overrides $HOME so tier-4 resolution
    /// (`$HOME/.cargo/bin/cargo`) can be aimed at a stub instead of the real
    /// host layout. Hermetic: RCH_* hints and job knobs are scrubbed unless a
    /// test sets them via `env` (set-but-empty disables a tier).
    #[cfg(unix)]
    fn exec_shim(
        dir: &Path,
        name: &str,
        args: &[&str],
        env: &[(&str, &str)],
        home: Option<&Path>,
    ) -> std::process::Output {
        let mut cmd = std::process::Command::new(dir.join(name));
        cmd.args(args)
            .env("PATH", format!("{}:/usr/bin:/bin", dir.display()))
            .env_remove("RCH_CARGO_WRAPPER_BYPASS")
            .env_remove("RCH_SHIM_LOCAL_IDE")
            .env_remove("RUSTC_WORKSPACE_WRAPPER")
            .env_remove("RCH_REAL_CARGO")
            .env_remove("RCH_SHIM_REAL_CARGO")
            .env_remove("RCH_SHIM_REAL_CARGO_CLIPPY")
            // Hosts set CARGO_BUILD_JOBS in /etc/environment; inheriting it
            // would make these assertions depend on where the suite runs.
            .env_remove("CARGO_BUILD_JOBS")
            .env_remove("RCH_LOCAL_MAX_JOBS");
        if let Some(h) = home {
            cmd.env("HOME", h);
        }
        for (k, v) in env {
            cmd.env(k, v);
        }
        output_retrying_text_busy(&mut cmd)
    }

    /// Execute a rendered shim body under `/bin/sh` in a sandbox with the
    /// standard stub real-cargo pre-registered as both RCH_SHIM_REAL_CARGO
    /// targets (the toolchain-wrapper handoff), assert success, and return
    /// trimmed stdout.
    #[cfg(unix)]
    fn run_shim(body: &str, name: &str, args: &[&str], env: &[(&str, &str)]) -> String {
        let dir = shim_sandbox(body, name, args);
        let real = dir.join("real-cargo");
        let mut full: Vec<(&str, &str)> = vec![
            ("RCH_SHIM_REAL_CARGO", real.to_str().unwrap()),
            ("RCH_SHIM_REAL_CARGO_CLIPPY", real.to_str().unwrap()),
        ];
        full.extend_from_slice(env);
        let out = exec_shim(&dir, name, args, &full, None);
        let _ = std::fs::remove_dir_all(&dir);
        assert!(
            out.status.success(),
            "shim exited {:?}; stderr: {}",
            out.status.code(),
            String::from_utf8_lossy(&out.stderr)
        );
        String::from_utf8_lossy(&out.stdout).trim().to_string()
    }

    /// The regression this whole change exists for: a plain
    /// `--message-format=json` is what scripts, CI and lint gates pass, and
    /// shim v1 sent every one of them to a LOCAL build.
    #[cfg(unix)]
    #[test]
    fn plain_message_format_json_still_offloads() {
        let body = cargo_shim_body(true);
        let out = run_shim(&body, "cargo", &["check", "--message-format=json"], &[]);
        assert!(out.starts_with("OFFLOAD"), "expected offload, got: {out}");
    }

    /// rust-analyzer keeps its local build — it is identified by the rendered
    /// diagnostic formats, not by `--message-format` alone.
    #[cfg(unix)]
    #[test]
    fn rust_analyzer_diagnostic_formats_stay_local() {
        let body = cargo_shim_body(true);
        for fmt in [
            "--message-format=json-diagnostic-rendered-ansi",
            "--message-format=json-diagnostic-short",
        ] {
            let out = run_shim(&body, "cargo", &["check", fmt], &[]);
            assert!(out.starts_with("LOCAL"), "{fmt} should stay local: {out}");
        }
    }

    /// Offloading the inner `cargo check` that `cargo clippy` drives would drop
    /// the wrapper and silently produce check results instead of lints.
    #[cfg(unix)]
    #[test]
    fn workspace_wrapper_forces_local_so_clippy_lints_survive() {
        let body = cargo_shim_body(true);
        let out = run_shim(
            &body,
            "cargo",
            &["check"],
            &[("RUSTC_WORKSPACE_WRAPPER", "/usr/bin/clippy-driver")],
        );
        assert!(out.starts_with("LOCAL"), "expected local, got: {out}");
    }

    /// The trj meltdown of 2026-08-28: a repo `.cargo/config.toml` carrying
    /// `jobs = -1` outranks `~/.cargo/config.toml`, so a bypassed local build
    /// ran 127-wide on a 128-thread host and held 202GB of `rust-lld`. Every
    /// local fallback must cap `-j`; CARGO_BUILD_JOBS outranks all config files.
    #[cfg(unix)]
    #[test]
    fn local_fallbacks_cap_parallelism() {
        let body = cargo_shim_body(true);
        for (args, env) in [
            (vec!["build"], vec![("RCH_CARGO_WRAPPER_BYPASS", "1")]),
            (vec!["build"], vec![("RCH_SHIM_LOCAL_IDE", "1")]),
            (
                vec!["check"],
                vec![("RUSTC_WORKSPACE_WRAPPER", "/usr/bin/clippy-driver")],
            ),
            (
                vec!["check", "--message-format=json-diagnostic-short"],
                vec![],
            ),
            // Non-build subcommands still use the capped local path. `run`
            // now reaches RCH's existing cargo-run classification instead of bypassing it.
            (vec!["metadata"], vec![]),
        ] {
            let out = run_shim(&body, "cargo", &args, &env);
            assert!(out.starts_with("LOCAL"), "{args:?} should be local: {out}");
            assert!(
                out.ends_with("jobs=8"),
                "{args:?} must cap local parallelism, got: {out}"
            );
        }
    }

    /// The cap must NOT leak onto the offload path — workers do their own slot
    /// accounting and capping them at 8 would throttle the whole fleet.
    #[cfg(unix)]
    #[test]
    fn offload_path_is_not_capped() {
        let body = cargo_shim_body(true);
        let out = run_shim(&body, "cargo", &["build"], &[]);
        assert!(out.starts_with("OFFLOAD"), "expected offload, got: {out}");
        assert!(
            out.ends_with("jobs=unset"),
            "offload must not inherit the local cap, got: {out}"
        );
    }

    /// An explicit CARGO_BUILD_JOBS is the operator's call and always wins;
    /// RCH_LOCAL_MAX_JOBS retunes the default without editing the shim.
    #[cfg(unix)]
    #[test]
    fn explicit_job_settings_win_over_the_default_cap() {
        let body = cargo_shim_body(true);
        let out = run_shim(
            &body,
            "cargo",
            &["build"],
            &[
                ("RCH_CARGO_WRAPPER_BYPASS", "1"),
                ("CARGO_BUILD_JOBS", "64"),
            ],
        );
        assert!(out.ends_with("jobs=64"), "explicit value must win: {out}");

        let out = run_shim(
            &body,
            "cargo",
            &["build"],
            &[
                ("RCH_CARGO_WRAPPER_BYPASS", "1"),
                ("RCH_LOCAL_MAX_JOBS", "16"),
            ],
        );
        assert!(out.ends_with("jobs=16"), "override must apply: {out}");
    }

    /// The clippy shim has the same two local paths and the same obligation.
    #[cfg(unix)]
    #[test]
    fn clippy_shim_local_paths_cap_parallelism() {
        let body = cargo_clippy_shim_body(true);
        for (args, env) in [
            (vec!["--version"], vec![("RCH_CARGO_WRAPPER_BYPASS", "1")]),
            // Invoked BY cargo as a subcommand: outer cargo already decided.
            (vec!["clippy", "--workspace"], vec![]),
        ] {
            let out = run_shim(&body, "cargo-clippy", &args, &env);
            assert!(out.starts_with("LOCAL"), "{args:?} should be local: {out}");
            assert!(out.ends_with("jobs=8"), "{args:?} must cap: {out}");
        }
    }

    #[cfg(unix)]
    #[test]
    fn local_ide_escape_hatch_forces_local() {
        let body = cargo_shim_body(true);
        let out = run_shim(&body, "cargo", &["build"], &[("RCH_SHIM_LOCAL_IDE", "1")]);
        assert!(out.starts_with("LOCAL"), "expected local, got: {out}");
    }

    #[cfg(unix)]
    fn selected_local_output(args: &[&str], extras: &[(&str, &str)]) -> std::process::Output {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &[]);
        write_exe(
            &dir.join("rustup"),
            "#!/bin/sh\nprintf '%s\\000' \"${RCH_CARGO_WRAPPER_BYPASS:-unset}\" \"${CARGO_BUILD_JOBS:-unset}\" \"$@\"\nexit \"${RUSTUP_STATUS:-0}\"\n",
        );
        let wrong = dir.join("real-cargo");
        let mut env = vec![
            ("RCH_REAL_CARGO", wrong.to_str().unwrap()),
            ("RCH_SHIM_REAL_CARGO", wrong.to_str().unwrap()),
            ("RUSTUP_TOOLCHAIN", "wrong-ambient"),
        ];
        env.extend_from_slice(extras);
        exec_shim(&dir, "cargo", args, &env, Some(&dir))
    }

    #[cfg(unix)]
    #[test]
    fn selected_toolchain_survives_every_explicit_local_escape() {
        let args = [
            "+nightly",
            "--offline",
            "test",
            "--",
            "",
            "a\nb",
            "$(false)",
        ];
        for cause in [
            ("RCH_CARGO_WRAPPER_BYPASS", "1"),
            ("RCH_SHIM_LOCAL_IDE", "1"),
            ("RUSTC_WORKSPACE_WRAPPER", "/clippy-driver"),
        ] {
            for (setting, cap) in [
                (("RCH_LOCAL_MAX_JOBS", "8"), "8"),
                (("RCH_LOCAL_MAX_JOBS", "3"), "3"),
                (("CARGO_BUILD_JOBS", "19"), "19"),
            ] {
                let out = selected_local_output(&args, &[cause, setting]);
                assert!(out.status.success(), "{cause:?}: {:?}", out.stderr);
                let mut expected = vec!["1", cap, "run", "nightly", "cargo"];
                expected.extend_from_slice(&args[1..]);
                expected.push("");
                assert_eq!(out.stdout, expected.join("\0").as_bytes());
            }
        }
    }

    #[cfg(unix)]
    #[test]
    fn selected_toolchain_handles_local_queries_and_preserves_rustup_failure() {
        for tail in [
            vec!["--version"],
            vec!["check", "--message-format=json-diagnostic-short"],
        ] {
            let mut args = vec!["+custom"];
            args.extend_from_slice(&tail);
            let out = selected_local_output(&args, &[]);
            assert!(out.status.success());
            let mut expected = vec!["1", "8", "run", "custom", "cargo"];
            expected.extend(tail);
            expected.push("");
            assert_eq!(out.stdout, expected.join("\0").as_bytes());
        }
        let out = selected_local_output(
            &["+absent", "build"],
            &[("RCH_SHIM_LOCAL_IDE", "1"), ("RUSTUP_STATUS", "67")],
        );
        assert_eq!(out.status.code(), Some(67));
        assert_eq!(out.stdout, b"1\x008\x00run\x00absent\x00cargo\x00build\x00");
    }

    #[cfg(unix)]
    #[test]
    fn unavailable_rustup_or_empty_selector_cannot_use_the_default_compiler() {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &[]);
        for (selector, expected_code) in [("+nightly", 127), ("+", 2)] {
            let out = std::process::Command::new("/bin/sh")
                .arg(dir.join("cargo"))
                .args([selector, "build"])
                .env_clear()
                .env("PATH", &dir)
                .env("HOME", &dir)
                .env("RCH_SHIM_LOCAL_IDE", "1")
                .env("RCH_REAL_CARGO", dir.join("real-cargo"))
                .output()
                .unwrap();
            assert_eq!(out.status.code(), Some(expected_code));
            assert!(
                out.stdout.is_empty(),
                "an unrelated real Cargo was executed"
            );
            assert!(!out.stderr.is_empty());
        }
    }

    #[cfg(unix)]
    #[test]
    fn selected_local_toolchain_reentry_uses_the_real_wrapped_toolchain() {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &[]);
        let toolchain = dir.join(".rustup/toolchains/selected/bin");
        let canonical = dir.join(".rch/shims");
        std::fs::create_dir_all(&toolchain).unwrap();
        std::fs::create_dir_all(&canonical).unwrap();
        write_exe(&canonical.join("cargo"), &cargo_shim_body(true));
        write_exe(&toolchain.join("cargo"), &toolchain_wrap_body());
        write_exe(
            &toolchain.join("cargo-rch-real"),
            "#!/bin/sh\nexec rustc \"$@\"\n",
        );
        write_exe(
            &toolchain.join("rustc"),
            "#!/bin/sh\nprintf '%s\\000' SELECTED \"${RCH_CARGO_WRAPPER_BYPASS:-unset}\" \"${CARGO_BUILD_JOBS:-unset}\" \"$@\"\n",
        );
        write_exe(
            &dir.join("rustc"),
            "#!/bin/sh\necho WRONG-COMPILER\nexit 91\n",
        );
        write_exe(
            &dir.join("rustup"),
            r#"#!/bin/sh
[ "$1" = run ] && [ "$2" = selected ] && [ "$3" = cargo ] || exit 92
shift 3
exec "$HOME/.rustup/toolchains/selected/bin/cargo" "$@"
"#,
        );
        let out = exec_shim(
            &dir,
            "cargo",
            &["+selected", "build", "--locked"],
            &[
                ("RCH_SHIM_LOCAL_IDE", "1"),
                ("RUSTUP_TOOLCHAIN", "wrong-ambient"),
            ],
            Some(&dir),
        );
        assert!(out.status.success(), "{:?}", out.stderr);
        assert_eq!(out.stdout, b"SELECTED\x001\x008\x00build\x00--locked\x00");
        assert!(out.stderr.is_empty());
    }

    /// Exercise the generated POSIX shell, not a second routing model. The
    /// boundary stubs record NUL-delimited arguments and policy; no compiler,
    /// installed shim, worker, or process-global environment is touched.
    #[cfg(unix)]
    fn record_shim(
        body: &str,
        args: &[std::ffi::OsString],
        env: &[(&str, &str)],
    ) -> std::process::Output {
        let directory = tempfile::tempdir().unwrap();
        let root = directory.path();
        write_exe(&root.join("shim"), body);
        write_exe(
            &root.join("rch"),
            concat!(
                "#!/bin/sh\n",
                "printf '%s\\0' RCH \"${RCH_REQUIRE_REMOTE:-unset}\" ",
                "\"${RCH_QUEUE_WHEN_BUSY:-unset}\" \"${CARGO_BUILD_JOBS:-unset}\"\n",
                "printf '%s\\0' \"$@\"\n",
                "exit \"${STUB_RCH_EXIT:-0}\"\n",
            ),
        );
        write_exe(
            &root.join("real-cargo"),
            "#!/bin/sh\nprintf '%s\\0' LOCAL \"${CARGO_BUILD_JOBS:-unset}\"\nif [ \"$#\" -gt 0 ]; then printf '%s\\0' \"$@\"; fi\n",
        );
        // Model only Rustup's explicit handoff, without inspecting installed
        // toolchains. The selected Cargo receives no +toolchain pseudo-command.
        write_exe(
            &root.join("rustup"),
            "#!/bin/sh\n[ \"$1\" = run ] && [ \"$3\" = cargo ] || exit 92\nRUSTUP_TOOLCHAIN=$2\nexport RUSTUP_TOOLCHAIN\nshift 3\nexec \"$HOME/real-cargo\" \"$@\"\n",
        );
        let mut command = std::process::Command::new("/bin/sh");
        command
            .arg(root.join("shim"))
            .args(args)
            .env_clear()
            .env("PATH", format!("{}:/usr/bin:/bin", root.display()))
            .env("HOME", root)
            .env("RCH_SHIM_REAL_CARGO", root.join("real-cargo"))
            .env("RCH_SHIM_REAL_CARGO_CLIPPY", root.join("real-cargo"));
        for (name, value) in env {
            command.env(name, value);
        }
        output_retrying_text_busy(&mut command)
    }

    #[cfg(unix)]
    fn argv_bytes(args: &[&str]) -> Vec<std::ffi::OsString> {
        args.iter()
            .map(|arg| std::ffi::OsString::from(*arg))
            .collect()
    }

    #[cfg(unix)]
    fn recorded_fields(output: &std::process::Output) -> Vec<&[u8]> {
        let mut fields: Vec<_> = output.stdout.split(|byte| *byte == 0).collect();
        assert_eq!(fields.pop(), Some(&b""[..]), "unterminated argument record");
        fields
    }

    #[cfg(unix)]
    #[test]
    fn global_options_and_toolchain_selectors_reach_rch_with_original_arguments() {
        let cases: &[&[&str]] = &[
            &["+nightly", "build", "--release"],
            &["+1.90.0", "--offline", "test", "--", "--nocapture"],
            &["--color", "never", "--locked", "check"],
            &["--config", "build.jobs=2", "build"],
            &["--config=build.jobs=2", "-vvv", "clippy"],
            &["+nightly", "-Z", "unstable-options", "build"],
            &[
                "+nightly",
                "-Zunstable-options",
                "-C",
                "/selected/project",
                "build",
            ],
            &["--", "build"],
        ];
        for args in cases {
            let command = shell_words::join(std::iter::once("cargo").chain(args.iter().copied()));
            assert!(
                rch_common::classify_command(&command).is_compilation,
                "{command}"
            );
            let output = record_shim(&cargo_shim_body(true), &argv_bytes(args), &[]);
            assert!(output.status.success(), "{:?}: {:?}", args, output);
            let fields = recorded_fields(&output);
            assert_eq!(
                &fields[..7],
                &[
                    b"RCH".as_slice(),
                    b"1",
                    b"1",
                    b"unset",
                    b"exec",
                    b"--",
                    b"cargo"
                ]
            );
            assert_eq!(
                &fields[7..],
                args.iter().map(|arg| arg.as_bytes()).collect::<Vec<_>>()
            );
        }
    }

    #[cfg(unix)]
    #[test]
    fn opaque_global_values_and_local_aliases_are_not_build_commands() {
        let cases: &[&[&str]] = &[
            &["--config", "build", "metadata"],
            &["--color", "test", "--version"],
            &["--config", "alias.ltest=\"test --lib\"", "ltest"],
            &["+nightly", "fmt", "--check"],
            &["+nightly", "--help", "build"],
            &["--unknown", "build"],
            &["--config"],
            &["--color", "build"],
            &["-Z", "build"],
            &["+nightly"],
        ];
        for args in cases {
            let output = record_shim(&cargo_shim_body(true), &argv_bytes(args), &[]);
            assert!(output.status.success(), "{:?}: {:?}", args, output);
            let fields = recorded_fields(&output);
            assert_eq!(&fields[..2], &[b"LOCAL".as_slice(), b"8"]);
            let expected: &[&str] = if args.first().is_some_and(|arg| arg.starts_with('+')) {
                &args[1..]
            } else {
                args
            };
            assert_eq!(
                &fields[2..],
                expected
                    .iter()
                    .map(|arg| arg.as_bytes())
                    .collect::<Vec<_>>()
            );
        }
    }

    #[cfg(unix)]
    #[test]
    fn additional_supported_build_entrypoints_no_longer_bypass_rch() {
        for args in [
            vec!["run"],
            vec!["r"],
            vec!["zigbuild"],
            vec!["xwin", "build"],
        ] {
            let command = shell_words::join(std::iter::once("cargo").chain(args.iter().copied()));
            assert!(
                rch_common::classify_command(&command).is_compilation,
                "{command}"
            );
            let output = record_shim(&cargo_shim_body(true), &argv_bytes(&args), &[]);
            assert!(output.status.success());
            assert_eq!(recorded_fields(&output)[0], b"RCH");
        }
    }

    #[cfg(unix)]
    #[test]
    fn separate_ide_format_is_local_but_payload_format_is_not_a_routing_option() {
        for format in ["json-diagnostic-rendered-ansi", "json-diagnostic-short"] {
            let args = argv_bytes(&["check", "--message-format", format]);
            let output = record_shim(&cargo_shim_body(true), &args, &[]);
            assert_eq!(recorded_fields(&output)[0], b"LOCAL");
            for args in [
                vec![
                    "test".to_owned(),
                    "--".to_owned(),
                    format!("--message-format={format}"),
                ],
                vec![
                    "test".to_owned(),
                    "--".to_owned(),
                    "--message-format".to_owned(),
                    format.to_owned(),
                ],
            ] {
                let args: Vec<_> = args.into_iter().map(std::ffi::OsString::from).collect();
                let output = record_shim(&cargo_shim_body(true), &args, &[]);
                assert_eq!(recorded_fields(&output)[0], b"RCH");
            }
        }
        let output = record_shim(
            &cargo_shim_body(true),
            &argv_bytes(&["check", "--message-format", "json"]),
            &[],
        );
        assert_eq!(recorded_fields(&output)[0], b"RCH");
    }

    #[cfg(unix)]
    #[test]
    fn shim_handoff_preserves_literal_and_non_utf8_arguments() {
        use std::os::unix::ffi::{OsStrExt, OsStringExt};
        let mut args = argv_bytes(&[
            "+nightly",
            "--config",
            "build.rustflags=['--cfg', 'feature=\"a b\"']",
            "test",
            "--",
            "",
            "with space",
            "literal'quote",
            "$(not-executed)",
            "*.rs",
            "line\nbreak",
            "--message-format=json-diagnostic-short",
        ]);
        args.push(std::ffi::OsString::from_vec(b"raw-\xff\xfe".to_vec()));
        let output = record_shim(&cargo_shim_body(true), &args, &[]);
        assert!(output.status.success());
        let fields = recorded_fields(&output);
        assert_eq!(fields[0], b"RCH");
        assert_eq!(
            &fields[7..],
            args.iter().map(|arg| arg.as_bytes()).collect::<Vec<_>>()
        );
    }

    #[cfg(unix)]
    #[test]
    fn cargo_and_direct_clippy_share_install_policy_without_a_local_job_cap() {
        for strict in [false, true] {
            for (body, args, clippy) in [
                (
                    cargo_shim_body(strict),
                    vec!["--locked", "clippy", "--all-targets"],
                    false,
                ),
                (
                    cargo_clippy_shim_body(strict),
                    vec!["--all-targets", "--", "-D", "warnings"],
                    true,
                ),
            ] {
                let output = record_shim(&body, &argv_bytes(&args), &[]);
                assert!(output.status.success());
                let fields = recorded_fields(&output);
                let policy = if strict {
                    b"1".as_slice()
                } else {
                    b"unset".as_slice()
                };
                assert_eq!(&fields[..4], &[b"RCH".as_slice(), policy, policy, b"unset"]);
                let mut expected = vec![b"exec".as_slice(), b"--", b"cargo"];
                if clippy {
                    expected.push(b"clippy");
                }
                expected.extend(args.iter().map(|arg| arg.as_bytes()));
                assert_eq!(&fields[4..], expected);
            }
        }
    }

    #[cfg(unix)]
    #[test]
    fn routing_failure_preserves_exit_and_never_runs_the_local_stub() {
        for (body, args) in [
            (
                cargo_shim_body(true),
                vec!["+nightly", "--locked", "clippy"],
            ),
            (cargo_clippy_shim_body(true), vec!["--all-targets"]),
        ] {
            for exit in ["1", "101", "103", "137"] {
                let output = record_shim(&body, &argv_bytes(&args), &[("STUB_RCH_EXIT", exit)]);
                assert_eq!(output.status.code(), Some(exit.parse().unwrap()));
                assert_eq!(recorded_fields(&output)[0], b"RCH");
            }
        }
    }

    #[cfg(unix)]
    #[test]
    fn explicit_local_controls_still_bypass_prefixed_builds() {
        for control in [
            "RCH_CARGO_WRAPPER_BYPASS",
            "RCH_SHIM_LOCAL_IDE",
            "RUSTC_WORKSPACE_WRAPPER",
        ] {
            let output = record_shim(
                &cargo_shim_body(true),
                &argv_bytes(&["+nightly", "--offline", "build"]),
                &[(control, "1")],
            );
            assert!(output.status.success());
            assert_eq!(&recorded_fields(&output)[..2], &[b"LOCAL".as_slice(), b"8"]);
        }
    }

    // --- tiered real-cargo resolution (shim v4) -----------------------------

    /// The v3 shim body as shipped in v1.0.60/v1.0.61, kept verbatim as the
    /// regression fixture for the 2026-08-30 nightly-renamed-cargo incident:
    /// its local fallback hardcoded `$HOME/.cargo/bin/cargo` — the rustup
    /// proxy — which cannot dispatch once the active toolchain's cargo was
    /// renamed to `cargo-rch-real`, so `RCH_SHIM_LOCAL_IDE=1` died with
    /// rustup's "not applicable" error exactly when the escape hatch was
    /// needed most.
    const V3_SHIM_BODY: &str = r#"#!/bin/sh
# rch cargo shim — MANAGED FILE, edit via `rch shim install`.
# rch-shim-version: 3
#
# Harness-agnostic build offload: any agent (codex/scripts/CI, not only Claude
# Code) that runs `cargo build|test|check|...` is routed through `rch exec` to
# the worker fleet instead of compiling locally on this box. See `rch shim`.
REAL="${RCH_SHIM_REAL_CARGO:-$HOME/.cargo/bin/cargo}"
# Cap parallelism on every LOCAL fallback. Local builds never reach rch's slot
# accounting, so nothing else bounds them — and a repo's own .cargo/config.toml
# outranks ~/.cargo/config.toml, so a committed `jobs = -1` (= nproc-1) wins over
# any global default. CARGO_BUILD_JOBS outranks every config file, so setting it
# here is the only reliable cap. An explicitly-set CARGO_BUILD_JOBS always wins;
# tune the default with RCH_LOCAL_MAX_JOBS.
exec_local() {
  if [ -z "${CARGO_BUILD_JOBS:-}" ]; then
    CARGO_BUILD_JOBS="${RCH_LOCAL_MAX_JOBS:-8}"
    export CARGO_BUILD_JOBS
  fi
  exec "$REAL" "$@"
}
# Loop-break: rch sets RCH_CARGO_WRAPPER_BYPASS=1 on its own local-fallback exec.
# Also fail open if rch is unavailable — never block a build.
if [ "${RCH_CARGO_WRAPPER_BYPASS:-}" = "1" ] || ! command -v rch >/dev/null 2>&1; then
  exec_local "$@"
fi
# Explicit operator escape hatch: force this one build local.
if [ "${RCH_SHIM_LOCAL_IDE:-}" = "1" ]; then
  exec_local "$@"
fi
# `cargo clippy` runs as: set RUSTC_WORKSPACE_WRAPPER=clippy-driver, then exec an
# inner `cargo check`. Offloading that INNER cargo would drop the wrapper and
# silently return plain check results instead of lints, so it stays local — the
# OUTER `cargo clippy` is the invocation that offloads. Same for any other
# caller-chosen rustc wrapper.
if [ -n "${RUSTC_WORKSPACE_WRAPPER:-}" ]; then
  exec_local "$@"
fi
# rust-analyzer must stay local (streaming JSON + local state). It is identified
# by its distinctive rendered-ansi/short diagnostic formats. A PLAIN
# `--message-format=json` is what scripts, CI and build tooling pass, and those
# must still offload — treating every --message-format as an IDE was the bug
# that silently kept script-driven builds on the dev box.
for a in "$@"; do
  case "$a" in
    --message-format=json-diagnostic-rendered-ansi*|--message-format=json-diagnostic-short*)
      exec_local "$@" ;;
  esac
done
case "${1:-}" in
  build|b|test|t|check|c|clippy|bench|doc|nextest)
    exec env RCH_REQUIRE_REMOTE=1 RCH_QUEUE_WHEN_BUSY=1 rch exec -- cargo "$@" ;;
  *)
    exec_local "$@" ;;
esac
"#;

    #[test]
    fn shim_body_documents_tiered_real_cargo_resolution() {
        let body = cargo_shim_body(true);
        for needle in [
            "resolve_real",
            "RCH_REAL_CARGO",
            "RCH_SHIM_REAL_CARGO",
            "cargo-rch-real",
            "rustc --print sysroot",
            "rch shim uninstall",
        ] {
            assert!(body.contains(needle), "shim body must carry {needle}");
        }
    }

    /// Tier 1: an explicit RCH_REAL_CARGO outranks every other candidate —
    /// the operator's one-word escape on a broken host.
    #[cfg(unix)]
    #[test]
    fn real_cargo_tier1_explicit_env_override_wins() {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &["build"]);
        let over = dir.join("override-cargo");
        write_exe(
            &over,
            "#!/bin/sh\necho OVERRIDE \"$@\" jobs=${CARGO_BUILD_JOBS:-unset}\n",
        );
        let out = exec_shim(
            &dir,
            "cargo",
            &["build"],
            &[
                ("RCH_SHIM_LOCAL_IDE", "1"),
                ("RCH_REAL_CARGO", over.to_str().unwrap()),
                // The wrapper-handoff hint also works — the override must win.
                (
                    "RCH_SHIM_REAL_CARGO",
                    dir.join("real-cargo").to_str().unwrap(),
                ),
            ],
            None,
        );
        let _ = std::fs::remove_dir_all(&dir);
        assert!(out.status.success());
        let stdout = String::from_utf8_lossy(&out.stdout);
        assert!(stdout.starts_with("OVERRIDE"), "tier 1 must win: {stdout}");
    }

    /// Tier 2: the toolchain wrapper's RCH_SHIM_REAL_CARGO handoff beats the
    /// plain proxy even when the proxy works — toolchain identity rules.
    #[cfg(unix)]
    #[test]
    fn real_cargo_tier2_wrapper_handoff_beats_plain_proxy() {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &["build"]);
        let home = dir.join("home");
        std::fs::create_dir_all(home.join(".cargo").join("bin")).unwrap();
        write_exe(
            &home.join(".cargo").join("bin").join("cargo"),
            "#!/bin/sh\necho PROXY \"$@\"\n",
        );
        let out = exec_shim(
            &dir,
            "cargo",
            &["build"],
            &[
                ("RCH_SHIM_LOCAL_IDE", "1"),
                (
                    "RCH_SHIM_REAL_CARGO",
                    dir.join("real-cargo").to_str().unwrap(),
                ),
            ],
            Some(&home),
        );
        let _ = std::fs::remove_dir_all(&dir);
        assert!(out.status.success());
        let stdout = String::from_utf8_lossy(&out.stdout);
        assert!(
            stdout.starts_with("LOCAL"),
            "tier 2 must beat the plain proxy: {stdout}"
        );
    }

    /// Tier 3: no env hints — the shim discovers `cargo-rch-real` in the
    /// ACTIVE toolchain via `rustc --print sysroot` and prepends that bin dir
    /// to PATH so the build's rustc/clippy resolve from the same toolchain.
    #[cfg(unix)]
    #[test]
    fn real_cargo_tier3_sysroot_discovery_and_path_prepend() {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &["build"]);
        let tc = dir.join("fake-tc");
        std::fs::create_dir_all(tc.join("bin")).unwrap();
        write_exe(
            &tc.join("bin").join("cargo-rch-real"),
            "#!/bin/sh\necho TC-REAL \"$@\" jobs=${CARGO_BUILD_JOBS:-unset} first=${PATH%%:*}\n",
        );
        // Stub rustc answers `--print sysroot` with the fake toolchain root.
        write_exe(
            &dir.join("rustc"),
            &format!("#!/bin/sh\necho {}\n", tc.display()),
        );
        // A working plain proxy must NOT be reached when tier 3 hits.
        let home = dir.join("home");
        std::fs::create_dir_all(home.join(".cargo").join("bin")).unwrap();
        write_exe(
            &home.join(".cargo").join("bin").join("cargo"),
            "#!/bin/sh\necho PROXY \"$@\"\n",
        );
        let out = exec_shim(
            &dir,
            "cargo",
            &["build"],
            &[("RCH_SHIM_LOCAL_IDE", "1"), ("RCH_SHIM_REAL_CARGO", "")],
            Some(&home),
        );
        let _ = std::fs::remove_dir_all(&dir);
        assert!(out.status.success());
        let stdout = String::from_utf8_lossy(&out.stdout);
        assert!(
            stdout.starts_with("TC-REAL"),
            "tier 3 must resolve the renamed real cargo: {stdout}"
        );
        assert!(
            stdout.contains(&format!("first={}", tc.join("bin").display())),
            "tier 3 must prepend the toolchain bin to PATH: {stdout}"
        );
    }

    /// Tier 4: nothing renamed — the stock `~/.cargo/bin/cargo` proxy is used
    /// as-is, with the local-parallelism cap intact (stable-host behavior).
    #[cfg(unix)]
    #[test]
    fn real_cargo_tier4_plain_proxy_when_nothing_renamed() {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &["build"]);
        let home = dir.join("home");
        std::fs::create_dir_all(home.join(".cargo").join("bin")).unwrap();
        write_exe(
            &home.join(".cargo").join("bin").join("cargo"),
            "#!/bin/sh\necho PROXY \"$@\" jobs=${CARGO_BUILD_JOBS:-unset}\n",
        );
        // rustc exists but its toolchain holds no renamed real cargo.
        write_exe(
            &dir.join("rustc"),
            &format!("#!/bin/sh\necho {}\n", dir.join("no-tc").display()),
        );
        let out = exec_shim(
            &dir,
            "cargo",
            &["build"],
            &[("RCH_SHIM_LOCAL_IDE", "1"), ("RCH_SHIM_REAL_CARGO", "")],
            Some(&home),
        );
        let _ = std::fs::remove_dir_all(&dir);
        assert!(out.status.success());
        let stdout = String::from_utf8_lossy(&out.stdout).trim().to_string();
        assert!(
            stdout.starts_with("PROXY"),
            "tier 4 must use the plain proxy: {stdout}"
        );
        assert!(
            stdout.ends_with("jobs=8"),
            "tier 4 keeps the local cap: {stdout}"
        );
    }

    /// Every tier empty: fail loudly with an error naming the escape hatches
    /// and exit 127 (the command-not-found class), never a silent hang.
    #[cfg(unix)]
    #[test]
    fn real_cargo_resolution_failure_names_the_fix() {
        let dir = shim_sandbox(&cargo_shim_body(true), "cargo", &["build"]);
        let home = dir.join("home"); // no .cargo/bin here
        std::fs::create_dir_all(&home).unwrap();
        write_exe(
            &dir.join("rustc"),
            &format!("#!/bin/sh\necho {}\n", dir.join("no-tc").display()),
        );
        let out = exec_shim(
            &dir,
            "cargo",
            &["build"],
            &[("RCH_SHIM_LOCAL_IDE", "1"), ("RCH_SHIM_REAL_CARGO", "")],
            Some(&home),
        );
        let _ = std::fs::remove_dir_all(&dir);
        assert_eq!(out.status.code(), Some(127));
        let stderr = String::from_utf8_lossy(&out.stderr);
        assert!(
            stderr.contains("RCH_REAL_CARGO"),
            "must name the env override: {stderr}"
        );
        assert!(
            stderr.contains("rch shim uninstall"),
            "must name the recovery path: {stderr}"
        );
    }

    /// THE incident (2026-08-30 fleet rollout of 943b8e29): nightly-default
    /// dispatcher, the active toolchain's bin holds ONLY `cargo-rch-real`
    /// (no `cargo`), so the rustup proxy fails to dispatch. The sandbox
    /// mirrors that host exactly; v3 must die with the proxy's error while v4
    /// resolves the renamed real cargo and puts its bin dir first on PATH.
    #[cfg(unix)]
    #[test]
    fn nightly_renamed_cargo_local_ide_v3_broke_v4_works() {
        for (label, body) in [("v3", V3_SHIM_BODY), ("v4", cargo_shim_body(true).as_str())] {
            let dir = shim_sandbox(body, "cargo", &["build"]);
            let tc = dir.join("nightly-tc");
            std::fs::create_dir_all(tc.join("bin")).unwrap();
            write_exe(
                &tc.join("bin").join("cargo-rch-real"),
                "#!/bin/sh\necho TC-REAL \"$@\" first=${PATH%%:*}\n",
            );
            write_exe(
                &dir.join("rustc"),
                &format!("#!/bin/sh\necho {}\n", tc.display()),
            );
            let home = dir.join("home");
            std::fs::create_dir_all(home.join(".cargo").join("bin")).unwrap();
            // The rustup proxy, failing exactly as rustup does on this host.
            write_exe(
                &home.join(".cargo").join("bin").join("cargo"),
                concat!(
                    "#!/bin/sh\n",
                    "echo \"error: the 'cargo' binary, normally provided by the 'cargo' component, is not applicable to the 'nightly' toolchain\" >&2\n",
                    "exit 1\n"
                ),
            );
            let out = exec_shim(
                &dir,
                "cargo",
                &["build"],
                &[("RCH_SHIM_LOCAL_IDE", "1"), ("RCH_SHIM_REAL_CARGO", "")],
                Some(&home),
            );
            let stdout = String::from_utf8_lossy(&out.stdout).trim().to_string();
            let stderr = String::from_utf8_lossy(&out.stderr).to_string();
            let _ = std::fs::remove_dir_all(&dir);
            if label == "v3" {
                assert_eq!(
                    out.status.code(),
                    Some(1),
                    "v3 must die with the proxy's error, stderr: {stderr}"
                );
                assert!(
                    stderr.contains("not applicable"),
                    "v3 proxies straight into the broken rustup dispatch: {stderr}"
                );
            } else {
                assert!(
                    out.status.success(),
                    "v4 must build locally via cargo-rch-real, stderr: {stderr}"
                );
                assert!(
                    stdout.starts_with("TC-REAL"),
                    "v4 must resolve the renamed real cargo: {stdout}"
                );
                assert!(
                    stdout.contains(&format!("first={}", tc.join("bin").display())),
                    "v4 must prepend the toolchain bin so children get nightly rustc: {stdout}"
                );
            }
        }
    }

    #[cfg(unix)]
    #[test]
    fn bypass_still_breaks_the_loop() {
        let body = cargo_shim_body(true);
        let out = run_shim(
            &body,
            "cargo",
            &["build"],
            &[("RCH_CARGO_WRAPPER_BYPASS", "1")],
        );
        assert!(out.starts_with("LOCAL"), "expected local, got: {out}");
    }

    /// A direct `cargo-clippy` call is the leak; it must offload.
    #[cfg(unix)]
    #[test]
    fn direct_cargo_clippy_offloads() {
        let body = cargo_clippy_shim_body(true);
        let out = run_shim(&body, "cargo-clippy", &["--all-targets"], &[]);
        assert!(out.starts_with("OFFLOAD"), "expected offload, got: {out}");
        assert!(
            out.contains("cargo clippy"),
            "should normalize to `cargo clippy`: {out}"
        );
    }

    /// Invoked BY cargo as `cargo-clippy clippy ...` the outer cargo already
    /// decided; re-entering rch here would double-offload.
    #[cfg(unix)]
    #[test]
    fn cargo_clippy_as_subcommand_passes_through() {
        let body = cargo_clippy_shim_body(true);
        let out = run_shim(&body, "cargo-clippy", &["clippy", "--all-targets"], &[]);
        assert!(out.starts_with("LOCAL"), "expected passthrough, got: {out}");
    }

    #[test]
    fn clippy_shim_carries_the_version_marker() {
        let body = cargo_clippy_shim_body(true);
        assert_eq!(
            installed_shim_version_from_str(&body).as_deref(),
            Some(SHIM_VERSION)
        );
    }

    // Test helper mirroring installed_shim_version over an in-memory string.
    fn installed_shim_version_from_str(body: &str) -> Option<String> {
        body.lines().find_map(|line| {
            line.trim()
                .strip_prefix(SHIM_MARKER)
                .map(|v| v.trim().to_string())
        })
    }

    // --- toolchain wrapping -------------------------------------------------

    #[test]
    fn toolchain_wrapper_is_loop_safe_and_fail_open() {
        let body = toolchain_wrap_body();
        // Same loop-break contract rch honors on its own local-fallback exec.
        assert!(body.contains("RCH_CARGO_WRAPPER_BYPASS"));
        // Fail open when the shim is absent or rch is not installed.
        assert!(body.contains(r#"[ ! -x "$SHIM" ]"#));
        assert!(body.contains("command -v rch"));
        // Toolchain identity must survive a local fallback, else rch would
        // rebuild with the rustup default rather than the requested toolchain.
        assert!(body.contains("RCH_SHIM_REAL_CARGO=\"$REAL\""));
        assert!(body.contains("export RCH_SHIM_REAL_CARGO"));
        // Resolves its sibling real binary relative to $0, not a hardcoded path.
        assert!(body.contains(r#"SELF_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"#));
        assert!(body.contains(REAL_CARGO_NAME));
        // Its own local fallback must put the toolchain bin FIRST on PATH so
        // the bypassed build's rustc/clippy-driver come from THAT toolchain
        // (mirrors the shim's tiered resolution).
        assert!(body.contains(r#"PATH="$SELF_DIR:$PATH""#));
    }

    /// Executed for real: a bypassed toolchain-wrapper build runs the sibling
    /// real cargo with the toolchain's bin dir leading PATH.
    #[cfg(unix)]
    #[test]
    fn toolchain_wrapper_local_fallback_prepends_its_bin() {
        let dir = tempfile::tempdir().unwrap();
        let bin = dir.path().join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        write_exe(&bin.join("cargo"), &toolchain_wrap_body());
        write_exe(
            &bin.join(REAL_CARGO_NAME),
            "#!/bin/sh\necho TC-REAL \"$@\" jobs=${CARGO_BUILD_JOBS:-unset} first=${PATH%%:*}\n",
        );
        let mut cmd = std::process::Command::new(bin.join("cargo"));
        cmd.arg("build")
            .env("PATH", format!("{}:/usr/bin:/bin", dir.path().display()))
            .env("RCH_CARGO_WRAPPER_BYPASS", "1")
            .env_remove("CARGO_BUILD_JOBS")
            .env_remove("RCH_LOCAL_MAX_JOBS");
        let out = output_retrying_text_busy(&mut cmd);
        assert!(
            out.status.success(),
            "stderr: {}",
            String::from_utf8_lossy(&out.stderr)
        );
        let stdout = String::from_utf8_lossy(&out.stdout).trim().to_string();
        assert!(
            stdout.starts_with("TC-REAL"),
            "must exec the real cargo: {stdout}"
        );
        assert!(
            stdout.contains(&format!("first={}", bin.display())),
            "toolchain bin must lead PATH for child rustc: {stdout}"
        );
        assert!(stdout.contains("jobs=8"), "local cap must hold: {stdout}");
    }

    #[test]
    fn toolchain_wrapper_version_is_detectable() {
        let body = toolchain_wrap_body();
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("cargo");
        std::fs::write(&p, &body).unwrap();
        assert_eq!(
            toolchain_wrap_version(&p).as_deref(),
            Some(TOOLCHAIN_WRAP_VERSION)
        );
        assert!(is_toolchain_wrapped(&p));
    }

    #[test]
    fn a_real_cargo_binary_is_not_mistaken_for_a_wrapper() {
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("cargo");
        // Oversized, non-UTF8 payload: stands in for a real multi-MB binary.
        std::fs::write(&p, vec![0u8; 16 * 1024]).unwrap();
        assert!(!is_toolchain_wrapped(&p));
        assert!(!delegates_to_shim(&p, true));
    }

    #[cfg(unix)]
    #[test]
    fn wrap_then_unwrap_restores_the_original_bytes() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let bin = dir.path().join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        let cargo = bin.join("cargo");
        let original = b"#!/bin/sh\necho i-am-the-real-cargo\n";
        std::fs::write(&cargo, original).unwrap();
        std::fs::set_permissions(&cargo, std::fs::Permissions::from_mode(0o755)).unwrap();

        assert_eq!(wrap_toolchain_cargo(&cargo).unwrap(), WrapOutcome::Wrapped);
        assert!(is_toolchain_wrapped(&cargo));
        // The real binary is preserved beside it, byte-for-byte.
        let real = bin.join(REAL_CARGO_NAME);
        assert_eq!(std::fs::read(&real).unwrap(), original);
        // Wrapper must be executable or every build breaks.
        assert_eq!(
            std::fs::metadata(&cargo).unwrap().permissions().mode() & 0o111,
            0o111
        );

        // Idempotent: a second install is a no-op, not a double-wrap.
        assert_eq!(
            wrap_toolchain_cargo(&cargo).unwrap(),
            WrapOutcome::AlreadyCurrent
        );
        assert_eq!(std::fs::read(&real).unwrap(), original);

        assert!(unwrap_toolchain_cargo(&cargo).unwrap());
        assert_eq!(std::fs::read(&cargo).unwrap(), original);
        assert!(!real.exists());
        // Unwrapping an already-plain cargo is a no-op, not an error.
        assert!(!unwrap_toolchain_cargo(&cargo).unwrap());
    }

    #[cfg(unix)]
    #[test]
    fn rustup_replacing_a_toolchain_rewraps_the_new_binary() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let bin = dir.path().join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        let cargo = bin.join("cargo");
        std::fs::write(&cargo, b"old-cargo").unwrap();
        std::fs::set_permissions(&cargo, std::fs::Permissions::from_mode(0o755)).unwrap();
        wrap_toolchain_cargo(&cargo).unwrap();

        // rustup overwrites `cargo` with a fresh binary, leaving the stale
        // `cargo-rch-real` behind. The new binary must win.
        std::fs::write(&cargo, b"new-cargo-from-rustup").unwrap();
        assert_eq!(wrap_toolchain_cargo(&cargo).unwrap(), WrapOutcome::Wrapped);
        assert_eq!(
            std::fs::read(bin.join(REAL_CARGO_NAME)).unwrap(),
            b"new-cargo-from-rustup"
        );
        assert!(unwrap_toolchain_cargo(&cargo).unwrap());
        assert_eq!(std::fs::read(&cargo).unwrap(), b"new-cargo-from-rustup");
    }

    #[cfg(unix)]
    #[test]
    fn unwrap_refuses_when_the_real_binary_is_missing() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let bin = dir.path().join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        let cargo = bin.join("cargo");
        std::fs::write(&cargo, b"real").unwrap();
        std::fs::set_permissions(&cargo, std::fs::Permissions::from_mode(0o755)).unwrap();
        wrap_toolchain_cargo(&cargo).unwrap();
        std::fs::remove_file(bin.join(REAL_CARGO_NAME)).unwrap();
        // Deleting the wrapper here would destroy cargo entirely.
        assert!(unwrap_toolchain_cargo(&cargo).is_err());
        assert!(cargo.exists());
    }

    // --- interception classification ---------------------------------------

    #[cfg(unix)]
    #[test]
    fn concurrent_wrap_never_preserves_a_wrapper_as_the_real_cargo() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let bin = dir.path().join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        let cargo = bin.join("cargo");
        // Simulate losing the race: `cargo` is already another run's wrapper,
        // but no `cargo-rch-real` exists yet, so the not-wrapped path would
        // otherwise link the wrapper over itself and lose the real binary.
        // (is_toolchain_wrapped is true here, so we take the refresh path and
        // must refuse because the real binary is absent.)
        std::fs::write(&cargo, toolchain_wrap_body()).unwrap();
        std::fs::set_permissions(&cargo, std::fs::Permissions::from_mode(0o755)).unwrap();
        assert!(wrap_toolchain_cargo(&cargo).is_err());
        // cargo is untouched, and nothing bogus was left behind.
        assert!(is_toolchain_wrapped(&cargo));
        assert!(!bin.join(REAL_CARGO_NAME).exists());
    }

    fn write_path_candidate(path: &Path, contents: &[u8], executable: bool) {
        std::fs::write(path, contents).unwrap();
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = if executable { 0o755 } else { 0o644 };
            std::fs::set_permissions(path, std::fs::Permissions::from_mode(mode)).unwrap();
        }
        #[cfg(not(unix))]
        let _ = executable;
    }

    #[cfg(unix)]
    fn shell_cargo_output(path: &std::ffi::OsStr, cwd: &Path) -> String {
        let output = output_retrying_text_busy(
            std::process::Command::new("/bin/sh")
                .args(["-c", "cargo"])
                .env_clear()
                .env("PATH", path)
                .env("HOME", cwd)
                .current_dir(cwd),
        );
        assert!(
            output.status.success(),
            "shell lookup failed: stdout={} stderr={}",
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
        String::from_utf8(output.stdout).unwrap().trim().to_owned()
    }

    // Shell-script fixtures model POSIX execution. Windows coverage below uses
    // real PE images because extensionless shebang files are not executables.
    #[cfg(unix)]
    #[test]
    fn empty_path_entries_resolve_cargo_from_cwd_in_order() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join("shims");
        std::fs::create_dir_all(&shim_dir).unwrap();
        let shim = shim_dir.join("cargo");
        write_path_candidate(&shim, b"#!/bin/sh\nprintf SHIM\n", true);
        write_path_candidate(
            &dir.path().join("cargo"),
            b"#!/bin/sh\nprintf LOCAL\n",
            true,
        );

        let with_empty =
            std::env::join_paths([std::path::PathBuf::new(), shim_dir.clone()]).unwrap();
        assert_eq!(
            cargo_interception_in(&with_empty, &shim, dir.path()),
            Interception::None
        );
        let trailing_empty = std::env::join_paths([shim_dir, std::path::PathBuf::new()]).unwrap();
        assert_eq!(
            cargo_interception_in(&trailing_empty, &shim, dir.path()),
            Interception::Direct
        );
        assert_eq!(shell_cargo_output(&with_empty, dir.path()), "LOCAL");
        assert_eq!(shell_cargo_output(&trailing_empty, dir.path()), "SHIM");
        assert_eq!(shell_cargo_output("".as_ref(), dir.path()), "LOCAL");
        assert_eq!(
            cargo_interception_in("".as_ref(), &shim, dir.path()),
            Interception::None
        );
    }

    #[cfg(unix)]
    #[test]
    fn first_cargo_on_path_decides_and_a_real_binary_reports_none() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join("shims");
        let real_dir = dir.path().join("cargo-bin");
        std::fs::create_dir_all(&shim_dir).unwrap();
        std::fs::create_dir_all(&real_dir).unwrap();
        let shim = shim_dir.join("cargo");
        write_path_candidate(&shim, cargo_shim_body(true).as_bytes(), true);
        // Stand-in for the real multi-MB cargo binary.
        write_path_candidate(&real_dir.join("cargo"), &vec![0u8; 16 * 1024], true);

        // Real cargo first => shadowed shim, correctly reported as not intercepted.
        let real_first = std::env::join_paths([real_dir.clone(), shim_dir.clone()]).unwrap();
        assert_eq!(
            cargo_interception_in(&real_first, &shim, dir.path()),
            Interception::None
        );

        // Shim first => intercepted.
        let shim_first = std::env::join_paths([shim_dir, real_dir]).unwrap();
        assert_eq!(
            cargo_interception_in(&shim_first, &shim, dir.path()),
            Interception::Direct
        );
    }

    #[cfg(unix)]
    #[test]
    fn delegating_wrapper_earlier_on_path_is_still_interception() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join("shims");
        let deleg_dir = dir.path().join("local-bin");
        std::fs::create_dir_all(&shim_dir).unwrap();
        std::fs::create_dir_all(&deleg_dir).unwrap();
        let shim = shim_dir.join("cargo");
        write_path_candidate(&shim, cargo_shim_body(true).as_bytes(), true);
        // The real-world ~/.local/bin/cargo that execs the shim. This is the
        // case the old PATH-order check reported as "not intercepted".
        write_path_candidate(
            &deleg_dir.join("cargo"),
            b"#!/bin/sh\nSHIM=\"$HOME/.rch/shims/cargo\"\nexec \"$SHIM\" \"$@\"\n",
            true,
        );

        let deleg_first = std::env::join_paths([deleg_dir, shim_dir]).unwrap();
        assert_eq!(
            cargo_interception_in(&deleg_first, &shim, dir.path()),
            Interception::Delegated
        );
    }

    #[test]
    fn delegating_wrapper_counts_as_interception() {
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("cargo");
        std::fs::write(
            &p,
            b"#!/bin/sh\nSHIM=\"$HOME/.rch/shims/cargo\"\nexec \"$SHIM\" \"$@\"\n",
        )
        .unwrap();
        assert!(delegates_to_shim(&p, true));
        assert!(!delegates_to_shim(&p, false));
    }

    #[cfg(windows)]
    #[test]
    fn windows_path_eligibility_rejects_shebang_files_and_resolves_real_pe_images() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join("shims");
        let earlier_dir = dir.path().join("earlier");
        std::fs::create_dir_all(&shim_dir).unwrap();
        std::fs::create_dir_all(&earlier_dir).unwrap();
        let shim = shim_dir.join("cargo");
        let earlier = earlier_dir.join("cargo");
        let executable = std::env::current_exe().unwrap();
        // Copy an actual native PE image. These files are only inspected;
        // neither a compiler nor the copied test binary is executed.
        std::fs::copy(&executable, &shim).unwrap();
        write_path_candidate(
            &earlier,
            b"#!/bin/sh\nexec \"$HOME/.rch/shims/cargo\" \"$@\"\n",
            true,
        );
        let earlier_first = std::env::join_paths([&earlier_dir, &shim_dir]).unwrap();
        assert!(
            which::which(&earlier).is_err(),
            "a shebang is not a native PE image"
        );
        assert_eq!(
            cargo_interception_in(&earlier_first, &shim, dir.path()),
            Interception::Direct
        );
        std::fs::copy(&executable, &earlier).unwrap();
        assert_eq!(
            cargo_interception_in(&earlier_first, &shim, dir.path()),
            Interception::None
        );
        let shim_first = std::env::join_paths([&shim_dir, &earlier_dir]).unwrap();
        assert_eq!(
            cargo_interception_in(&shim_first, &shim, dir.path()),
            Interception::Direct
        );
        write_path_candidate(&shim, cargo_shim_body(true).as_bytes(), true);
        assert_eq!(
            cargo_interception_in(&shim_first, &shim, dir.path()),
            Interception::None,
            "an extensionless POSIX shim cannot authorize native interception"
        );
    }

    #[cfg(windows)]
    #[test]
    fn windows_relative_candidates_use_explicit_cwd_with_real_pe_images() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join("shims");
        std::fs::create_dir_all(&shim_dir).unwrap();
        let shim = shim_dir.join("cargo");
        let executable = std::env::current_exe().unwrap();
        std::fs::copy(&executable, &shim).unwrap();
        std::fs::copy(executable, dir.path().join("cargo")).unwrap();
        let cwd_first = std::env::join_paths([Path::new("."), Path::new("shims")]).unwrap();
        let shim_first = std::env::join_paths([Path::new("shims"), Path::new(".")]).unwrap();
        assert_eq!(
            cargo_interception_in(&cwd_first, &shim, dir.path()),
            Interception::None
        );
        assert_eq!(
            cargo_interception_in(&shim_first, &shim, dir.path()),
            Interception::Direct
        );
    }

    #[cfg(unix)]
    #[test]
    fn path_lookup_skips_nonexecutables_and_legacy_target_must_execute() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join(".rch/shims");
        let real_dir = dir.path().join(".cargo/bin");
        let wrapper_dir = dir.path().join("local-bin");
        for path in [&shim_dir, &real_dir, &wrapper_dir] {
            std::fs::create_dir_all(path).unwrap();
        }
        let shim = shim_dir.join("cargo");
        let real = real_dir.join("cargo");
        let wrapper = wrapper_dir.join("cargo");
        write_path_candidate(&shim, b"#!/bin/sh\nprintf SHIM\n", true);
        write_path_candidate(&real, b"#!/bin/sh\nprintf LOCAL\n", false);
        let real_first = std::env::join_paths([&real_dir, &shim_dir]).unwrap();
        assert_eq!(
            cargo_interception_in(&real_first, &shim, dir.path()),
            Interception::Direct
        );
        assert_eq!(shell_cargo_output(&real_first, dir.path()), "SHIM");

        let legacy = b"#!/bin/sh\nSHIM=\"$HOME/.rch/shims/cargo\"\nif [ -x \"$SHIM\" ]; then exec \"$SHIM\" \"$@\"; fi\nexec \"$HOME/.cargo/bin/cargo\" \"$@\"\n";
        write_path_candidate(&wrapper, legacy, false);
        write_path_candidate(&real, b"#!/bin/sh\nprintf LOCAL\n", true);
        let wrapper_first = std::env::join_paths([&wrapper_dir, &real_dir, &shim_dir]).unwrap();
        assert_eq!(
            cargo_interception_in(&wrapper_first, &shim, dir.path()),
            Interception::None
        );
        assert_eq!(shell_cargo_output(&wrapper_first, dir.path()), "LOCAL");

        write_path_candidate(&wrapper, legacy, true);
        assert_eq!(
            cargo_interception_in(&wrapper_first, &shim, dir.path()),
            Interception::Delegated
        );
        assert_eq!(shell_cargo_output(&wrapper_first, dir.path()), "SHIM");

        write_path_candidate(&shim, b"#!/bin/sh\nprintf SHIM\n", false);
        assert_eq!(
            cargo_interception_in(&wrapper_first, &shim, dir.path()),
            Interception::None
        );
        assert_eq!(shell_cargo_output(&wrapper_first, dir.path()), "LOCAL");
        let shim_first = std::env::join_paths([&shim_dir, &real_dir]).unwrap();
        assert_eq!(
            cargo_interception_in(&shim_first, &shim, dir.path()),
            Interception::None
        );
        assert_eq!(shell_cargo_output(&shim_first, dir.path()), "LOCAL");
    }

    #[cfg(unix)]
    #[test]
    fn relative_path_and_literal_tilde_follow_cwd_and_symlink_identity() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join("shims");
        let real_dir = dir.path().join("bin");
        let literal_tilde = dir.path().join("~/bin");
        for path in [&shim_dir, &real_dir, &literal_tilde] {
            std::fs::create_dir_all(path).unwrap();
        }
        let shim = shim_dir.join("cargo");
        write_path_candidate(&shim, b"#!/bin/sh\nprintf SHIM\n", true);
        write_path_candidate(&real_dir.join("cargo"), b"#!/bin/sh\nprintf LOCAL\n", true);
        std::os::unix::fs::symlink(&shim, literal_tilde.join("cargo")).unwrap();
        for (path, expected, output) in [
            ("bin:./shims", Interception::None, "LOCAL"),
            ("./shims:bin", Interception::Direct, "SHIM"),
            ("~/bin:bin", Interception::Direct, "SHIM"),
        ] {
            assert_eq!(
                cargo_interception_in(path.as_ref(), &shim, dir.path()),
                expected,
                "{path}"
            );
            assert_eq!(
                shell_cargo_output(path.as_ref(), dir.path()),
                output,
                "{path}"
            );
        }
        assert_eq!(
            cargo_interception_in("shims".as_ref(), &shim, Path::new("relative-cwd")),
            Interception::None
        );
    }

    #[cfg(unix)]
    #[test]
    fn standalone_marked_copy_does_not_need_executable_canonical_target() {
        let dir = tempfile::tempdir().unwrap();
        let shim_dir = dir.path().join("shims");
        let copy_dir = dir.path().join("copy");
        std::fs::create_dir_all(&shim_dir).unwrap();
        std::fs::create_dir_all(&copy_dir).unwrap();
        let shim = shim_dir.join("cargo");
        write_path_candidate(&shim, cargo_shim_body(true).as_bytes(), false);
        let marked = format!("#!/bin/sh\n{SHIM_MARKER}{SHIM_VERSION}\nprintf STANDALONE\n");
        write_path_candidate(&copy_dir.join("cargo"), marked.as_bytes(), true);
        let path = std::env::join_paths([&copy_dir, &shim_dir]).unwrap();
        assert_eq!(
            cargo_interception_in(&path, &shim, dir.path()),
            Interception::Delegated
        );
        assert_eq!(shell_cargo_output(&path, dir.path()), "STANDALONE");
    }

    #[test]
    fn interception_intercepts_predicate() {
        assert!(Interception::Direct.intercepts());
        assert!(Interception::Delegated.intercepts());
        assert!(!Interception::None.intercepts());
    }
}