fix(xtask): stop nested cargo from rebuilding the TLS stack every run (bd-awchm8w7)

Every xtask subcommand that shells out to a nested cargo (stage-doc-examples,
verify, build-all, test) inherits the outer `cargo xtask` process's package
env vars — most importantly CARGO_MANIFEST_DIR=.../crates/xtask. The `ring`
build script (base of q2's rustls/reqwest TLS stack) fingerprints
CARGO_MANIFEST_DIR, so the inherited value marks it dirty and forces a full
multi-minute rebuild of that dependency closure on every nested invocation
whenever the prior build came from a plain shell or `cargo build --workspace`.

Diagnosed while investigating a "stage-doc-examples hangs" report: the hang
was this rebuild, hidden by the `--quiet` flag on the nested `cargo run`.
Fingerprint log: EnvVarChanged { name: "CARGO_MANIFEST_DIR", old_value: None,
new_value: Some(".../crates/xtask") }.

- Add util::strip_inherited_cargo_env / util::nested_command, which mark the
  package-scoped CARGO_* vars (CARGO_MANIFEST_DIR, CARGO_PKG_*, OUT_DIR, …)
  for removal so a nested cargo fingerprints as a fresh shell would. PATH,
  CARGO_HOME, RUSTFLAGS, etc. are left untouched.
- Route stage_doc_examples, verify (run_command), build_all (run_command),
  and test through it. Drop `--quiet` from the stage-doc render so a genuine
  compile or lock-wait is visible instead of a silent hang.

Verified end-to-end with CARGO_LOG fingerprint logging: after a clean-shell
`cargo build --workspace`, the nested xtask builds show 0 TLS-stack rebuilds,
stable in both directions. 80/80 xtask tests pass; clean -D warnings build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cscheid

crates/xtask/src/build_all.rs

@@ -201,6 +201,11 @@ fn run_command(
 ) -> Result<()> {
     let mut cmd = Command::new(program);
     cmd.args(args).current_dir(dir);
+    // Nested cargo/npm: strip the outer `cargo xtask`'s package env vars so a
+    // child cargo doesn't spuriously rebuild q2's TLS-stack closure (an
+    // inherited CARGO_MANIFEST_DIR flips the `ring` build script dirty). See
+    // `util::strip_inherited_cargo_env` (bd-awchm8w7).
+    crate::util::strip_inherited_cargo_env(&mut cmd);
 
     if let Some(flags) = rustflags {
         cmd.env("RUSTFLAGS", flags);

crates/xtask/src/stage_doc_examples.rs

@@ -29,7 +29,6 @@ use anyhow::{Context, Result};
 use serde::Deserialize;
 use std::fs;
 use std::path::Path;
-use std::process::Command;
 
 use crate::create_worktree::repo_root;
 
@@ -116,10 +115,16 @@ fn stage_one(
 
 /// Render a single example project in place with `q2`.
 fn render_project(root: &Path, project: &Path) -> Result<()> {
-    let status = Command::new("cargo")
-        .current_dir(root)
-        .args(["run", "--quiet", "--bin", "q2", "--", "render"])
-        .arg(project)
+    // We are a nested `cargo` invocation; strip the outer `cargo xtask`'s
+    // package env vars so the child cargo fingerprints q2 as a fresh shell
+    // would. Without this, an inherited `CARGO_MANIFEST_DIR` forces a full
+    // rebuild of q2's TLS-stack dependency closure on every run. See
+    // `util::strip_inherited_cargo_env` (bd-awchm8w7).
+    let mut cmd = crate::util::nested_command("cargo");
+    cmd.current_dir(root)
+        .args(["run", "--bin", "q2", "--", "render"])
+        .arg(project);
+    let status = cmd
         .status()
         .context("spawning `cargo run --bin q2 -- render`")?;
     if !status.success() {

crates/xtask/src/test.rs

@@ -32,6 +32,11 @@ pub fn run(extra_args: &[String], rustflags: Option<&str>) -> Result<()> {
 
     let mut cmd = Command::new("cargo");
     cmd.args(&args_refs).current_dir(&project_root);
+    // Nested cargo: strip the outer `cargo xtask`'s package env vars so a child
+    // cargo doesn't spuriously rebuild q2's TLS-stack closure (an inherited
+    // CARGO_MANIFEST_DIR flips the `ring` build script dirty). See
+    // `crate::util::strip_inherited_cargo_env` (bd-awchm8w7).
+    crate::util::strip_inherited_cargo_env(&mut cmd);
 
     if let Some(flags) = rustflags {
         cmd.env("RUSTFLAGS", flags);

crates/xtask/src/util.rs

@@ -1,6 +1,7 @@
 //! Small shared utilities for xtask subcommands.
 
 use std::path::{Path, PathBuf};
+use std::process::Command;
 
 /// Return a copy of `path` with forward slashes replaced by the platform's
 /// main separator. No-op on POSIX where `MAIN_SEPARATOR == '/'`.
@@ -18,9 +19,128 @@ pub fn with_native_separators(path: &Path) -> PathBuf {
     PathBuf::from(s.replace('/', std::path::MAIN_SEPARATOR_STR))
 }
 
+/// The package-scoped environment variables that `cargo` injects into a
+/// process it runs — including `cargo xtask` itself. When an xtask subcommand
+/// shells out to a *nested* `cargo`, these leak from the outer invocation into
+/// the child unless stripped.
+///
+/// This matters because some build scripts fingerprint these vars. Most
+/// importantly, `ring` (the base of q2's rustls/reqwest TLS stack) fingerprints
+/// `CARGO_MANIFEST_DIR`: when the nested cargo inherits
+/// `CARGO_MANIFEST_DIR=.../crates/xtask` from the outer `cargo xtask`, the
+/// build script reads as dirty (`EnvVarChanged { name: "CARGO_MANIFEST_DIR",
+/// old_value: None, new_value: Some(".../crates/xtask") }`) and the entire
+/// dependency closure rebuilds — a multi-minute compile on *every* nested
+/// invocation whenever the previous build came from a plain shell or
+/// `cargo build --workspace`. Stripping these vars makes the nested cargo
+/// fingerprint exactly as a fresh shell would. Cargo sets the correct
+/// per-crate values for the crates it actually builds. See bd-awchm8w7.
+///
+/// Only package-scoped vars are listed; environment essentials the child still
+/// needs (`PATH`, `CARGO_HOME`, `RUSTUP_*`, `RUSTFLAGS`, …) are deliberately
+/// left untouched.
+const INHERITED_CARGO_PKG_VARS: &[&str] = &[
+    "CARGO_MANIFEST_DIR",
+    "CARGO_MANIFEST_PATH",
+    "CARGO_PKG_NAME",
+    "CARGO_PKG_VERSION",
+    "CARGO_PKG_VERSION_MAJOR",
+    "CARGO_PKG_VERSION_MINOR",
+    "CARGO_PKG_VERSION_PATCH",
+    "CARGO_PKG_VERSION_PRE",
+    "CARGO_PKG_AUTHORS",
+    "CARGO_PKG_DESCRIPTION",
+    "CARGO_PKG_REPOSITORY",
+    "CARGO_PKG_HOMEPAGE",
+    "CARGO_PKG_LICENSE",
+    "CARGO_PKG_LICENSE_FILE",
+    "CARGO_PKG_RUST_VERSION",
+    "CARGO_PKG_README",
+    "CARGO_CRATE_NAME",
+    "CARGO_BIN_NAME",
+    "CARGO_PRIMARY_PACKAGE",
+    "OUT_DIR",
+];
+
+/// Mark the inherited cargo package env vars (see [`INHERITED_CARGO_PKG_VARS`])
+/// for removal on `cmd`, so a *nested* `cargo`/`npm` invocation spawned from an
+/// xtask subcommand fingerprints exactly as a fresh shell would — avoiding the
+/// spurious full rebuild of the TLS-stack dependency closure that an inherited
+/// `CARGO_MANIFEST_DIR` triggers.
+///
+/// Use this for any nested tool invocation from xtask; prefer
+/// [`nested_command`] when constructing the `Command` from scratch.
+pub fn strip_inherited_cargo_env(cmd: &mut Command) -> &mut Command {
+    for var in INHERITED_CARGO_PKG_VARS {
+        cmd.env_remove(var);
+    }
+    cmd
+}
+
+/// Construct a [`Command`] for `program` with the inherited cargo package env
+/// vars already stripped (see [`strip_inherited_cargo_env`]). This is the
+/// preferred constructor for any nested `cargo`/`npm` invocation from an xtask
+/// subcommand.
+pub fn nested_command(program: &str) -> Command {
+    let mut cmd = Command::new(program);
+    strip_inherited_cargo_env(&mut cmd);
+    cmd
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::collections::HashMap;
+
+    /// Collect a `Command`'s env overrides into a map of name -> Option<value>,
+    /// where `None` means the variable is marked for removal in the child.
+    fn env_overrides(cmd: &Command) -> HashMap<String, Option<String>> {
+        cmd.get_envs()
+            .map(|(k, v)| {
+                (
+                    k.to_string_lossy().into_owned(),
+                    v.map(|v| v.to_string_lossy().into_owned()),
+                )
+            })
+            .collect()
+    }
+
+    #[test]
+    fn strip_marks_inherited_cargo_pkg_vars_for_removal() {
+        let mut cmd = Command::new("cargo");
+        strip_inherited_cargo_env(&mut cmd);
+        let env = env_overrides(&cmd);
+        // The variable that actually caused the ring/rustls rebuild thrash.
+        assert_eq!(env.get("CARGO_MANIFEST_DIR"), Some(&None));
+        // A representative sample of the rest of the package-scoped vars.
+        for var in ["CARGO_PKG_NAME", "CARGO_PKG_VERSION", "OUT_DIR"] {
+            assert_eq!(
+                env.get(var),
+                Some(&None),
+                "{var} should be marked for removal"
+            );
+        }
+    }
+
+    #[test]
+    fn strip_does_not_touch_unrelated_or_cargo_home() {
+        // CARGO_HOME / PATH must survive — only package-scoped vars are stripped.
+        let mut cmd = Command::new("cargo");
+        strip_inherited_cargo_env(&mut cmd);
+        let env = env_overrides(&cmd);
+        assert!(
+            !env.contains_key("CARGO_HOME"),
+            "CARGO_HOME must not be stripped"
+        );
+        assert!(!env.contains_key("PATH"), "PATH must not be stripped");
+    }
+
+    #[test]
+    fn nested_command_strips_pkg_vars() {
+        let cmd = nested_command("cargo");
+        let env = env_overrides(&cmd);
+        assert_eq!(env.get("CARGO_MANIFEST_DIR"), Some(&None));
+    }
 
     #[test]
     fn with_native_separators_is_noop_on_posix_like_paths() {

crates/xtask/src/verify.rs

@@ -470,6 +470,11 @@ fn run_command(
 ) -> Result<()> {
     let mut cmd = Command::new(program);
     cmd.args(args).current_dir(dir);
+    // Nested cargo/npm: strip the outer `cargo xtask`'s package env vars so a
+    // child cargo doesn't spuriously rebuild q2's TLS-stack closure (an
+    // inherited CARGO_MANIFEST_DIR flips the `ring` build script dirty). See
+    // `util::strip_inherited_cargo_env` (bd-awchm8w7).
+    crate::util::strip_inherited_cargo_env(&mut cmd);
 
     if let Some(flags) = rustflags {
         cmd.env("RUSTFLAGS", flags);