From a0ed5cb69c42db078b8ac250f3dfc7a8e410ccf1 Mon Sep 17 00:00:00 2001
From: Colin McDonnell <3084745+colinhacks@users.noreply.github.com>
Date: Sat, 15 Aug 2026 11:43:53 -0700
Subject: [PATCH 1/5] run: signal every concurrent child on Ctrl-C, and make
 --color take effect
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A recursive run executes members on concurrent worker threads — concurrency
defaults to min(4, cpus), so this is the default shape, not only --parallel.
Four defects in that shape, all reported in #685.

Ctrl-C reached exactly one child. The signal forwarder held a single
AtomicI32 target, so each spawn overwrote the last and untrack_child()
zeroed the slot when the first member finished. Interrupting a multi-server
dev run signalled one script (which one was a race), orphaned the rest
holding their ports, and left nub blocked waiting on children it could no
longer signal. The target is now a set: each child adds its own group and
removes only its own on exit. group_on_spawn is untouched, so the
own-process-group behavior #26, #27 and #463 rely on still holds — pnpm's
shared-group model is deliberately not copied.

--color=always did nothing at all. Cli::color had no readers, and the
pre-subcommand scan stripped the token before clap could see it, so a flag
listed in `nub --help` was inert. It now records the choice, colors nub's
own output, and exports FORCE_COLOR to each script: 1 for --color=always,
0 for --no-color, matching pnpm 10.15.1. Default auto still forces nothing,
so prefixed output is unchanged unless asked.

Two predicate bugs sat in the same place. NO_COLOR was never consulted on
the stream-prefix path despite --help promising it, and FORCE_COLOR=0 read
as "present, therefore on" — which would have inverted --no-color for a
nested nub. Both now resolve through one color_enabled predicate.

--reporter-hide-prefix stripped the label from nub's own Done/exit/error
line too, so a run ended in identical unattributable `Done`s. pnpm keeps
the label on its status line; nub now does the same. The flag still hides
the child's per-line prefix, which is what CI annotation matchers need.

Closes #685
---
 crates/nub-cli/src/cli.rs                     | 161 ++++++++--
 crates/nub-cli/src/pm_engine/mod.rs           |  10 +-
 crates/nub-cli/tests/integration.rs           | 139 +++++++++
 crates/nub-core/src/node/spawn.rs             | 275 ++++++++++++++----
 site/content/docs/runner/run.mdx              |  24 +-
 .../monorepo-deps/packages/core/package.json  |   2 +-
 .../monorepo-deps/packages/utils/package.json |   2 +-
 7 files changed, 527 insertions(+), 86 deletions(-)

diff --git a/crates/nub-cli/src/cli.rs b/crates/nub-cli/src/cli.rs
index 74d8709cc..fce87a6d7 100644
--- a/crates/nub-cli/src/cli.rs
+++ b/crates/nub-cli/src/cli.rs
@@ -4,7 +4,7 @@ use std::collections::{BTreeMap, BTreeSet, HashMap};
 use std::env;
 use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
 
 use anyhow::{Context, Result, bail};
 #[cfg(feature = "compile")]
@@ -39,10 +39,23 @@ static SILENT: AtomicBool = AtomicBool::new(false);
 static REPORTER_NDJSON: AtomicBool = AtomicBool::new(false);
 /// `--reporter-hide-prefix`: drop the `<dir> <script>:` lead from each streamed
 /// output line so CI annotation matchers (e.g. GitHub Actions, which parse
-/// `error: file:line`) see the child's raw output. Affects the per-line prefix
-/// only; the `$ <cmd>` echo is left intact.
+/// `error: file:line`) see the child's raw output. Affects the CHILD's per-line
+/// prefix only — Nub's own framing (the `$ <cmd>` echo and the trailing
+/// `Done`/`exit`/`error` status) keeps its label, matching pnpm. Stripping the
+/// status line too left a run emitting several unattributable bare `Done`s.
 static HIDE_STREAM_PREFIX: AtomicBool = AtomicBool::new(false);
 
+/// The resolved `--color` / `--no-color` choice, as a [`ColorWhen`] discriminant.
+/// Set once at startup from the flag; read by [`color_enabled`] at every ANSI
+/// decision and by the script launcher when it exports `FORCE_COLOR` to a child.
+/// A process-global (rather than a threaded-through parameter) because the same
+/// answer has to reach Nub's own output, the PM engine's warnings, and the
+/// per-child environment, and it is decided before any of them run.
+static COLOR_MODE: AtomicU8 = AtomicU8::new(COLOR_AUTO);
+const COLOR_AUTO: u8 = 0;
+const COLOR_ALWAYS: u8 = 1;
+const COLOR_NEVER: u8 = 2;
+
 /// `nubx`-only: turn on the `npx`/`pnpm dlx` fallback in [`run_exec`]. Set once
 /// in [`run_nubx`] before it desugars to the `exec` dispatch; read in `run_exec`
 /// when the bin is absent from `node_modules/.bin`. Plain `nub exec` leaves this
@@ -1457,13 +1470,60 @@ pub enum NodeCommand {
     },
 }
 
-#[derive(Debug, Clone, Copy, ValueEnum)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
 pub enum ColorWhen {
     Auto,
     Always,
     Never,
 }
 
+/// Record the resolved `--color` choice. Called from the pre-subcommand argv scan
+/// and again from the parsed clap `Cli`, so either spelling position takes effect.
+pub(crate) fn set_color_mode(when: ColorWhen) {
+    let raw = match when {
+        ColorWhen::Auto => COLOR_AUTO,
+        ColorWhen::Always => COLOR_ALWAYS,
+        ColorWhen::Never => COLOR_NEVER,
+    };
+    COLOR_MODE.store(raw, Ordering::Relaxed);
+}
+
+pub(crate) fn color_mode() -> ColorWhen {
+    match COLOR_MODE.load(Ordering::Relaxed) {
+        COLOR_ALWAYS => ColorWhen::Always,
+        COLOR_NEVER => ColorWhen::Never,
+        _ => ColorWhen::Auto,
+    }
+}
+
+/// The one place Nub decides whether to emit ANSI to a stream. Precedence, highest
+/// first: an explicit `--color`/`--no-color`, then `NO_COLOR`, then `FORCE_COLOR`,
+/// then whether the stream is really a terminal.
+///
+/// Two things this gets right that the open-coded
+/// `is_terminal() || var_os("FORCE_COLOR").is_some()` did not. `NO_COLOR` was not
+/// consulted at all on the stream-prefix path, so `NO_COLOR=1` still produced a
+/// colored prefix despite `--help` promising otherwise. And `FORCE_COLOR=0` means
+/// OFF — mere presence read as ON, which inverts the request, and matters directly
+/// here because `--no-color` exports exactly `FORCE_COLOR=0` to children for pnpm
+/// parity, so a nested `nub` would have colorized on its parent's opt-OUT.
+pub(crate) fn color_enabled(stream_is_tty: bool) -> bool {
+    match color_mode() {
+        ColorWhen::Always => return true,
+        ColorWhen::Never => return false,
+        ColorWhen::Auto => {}
+    }
+    // The NO_COLOR convention is "present and non-empty", so an empty value is
+    // explicitly NOT an opt-out.
+    if std::env::var_os("NO_COLOR").is_some_and(|v| !v.is_empty()) {
+        return false;
+    }
+    if let Some(v) = std::env::var_os("FORCE_COLOR") {
+        return !matches!(v.to_str(), Some("") | Some("0"));
+    }
+    stream_is_tty
+}
+
 /// `nub compile`'s power set. Grouping it under its own `--help` heading (the
 /// shape esbuild uses) is what keeps the common six flags readable while the
 /// bundler knobs stay discoverable.
@@ -1893,6 +1953,7 @@ fn run_nub() -> Result<i32> {
     let mut help_verbose = false;
     let mut show_warnings = false;
     let mut silent = false;
+    let mut color_when: Option<ColorWhen> = None;
     // Pre-verb PM output flags (`nub --reporter=silent install`,
     // `nub --loglevel=error add foo`): captured here and recorded as process
     // defaults below so the per-verb `OutputFlags` resolution can fall back to
@@ -1965,8 +2026,28 @@ fn run_nub() -> Result<i32> {
                     cwd = Some(PathBuf::from(&raw_args[i]));
                 }
             }
+            // `--color` (bare = always), `--color=<when>`, `--no-color`: consumed
+            // here so they never reach Node as unknown flags, and RECORDED so the
+            // choice actually takes effect. Dropping the value on the floor left
+            // `--color=always` a documented no-op (#685): it is listed in
+            // `nub --help`, and the only test covering it drove clap directly, which
+            // never sees these tokens because this scan strips them first.
             s if s == "--color" || s.starts_with("--color=") || s == "--no-color" => {
-                // --color (no value), --color=always, --no-color: all consumed, not forwarded
+                color_when = Some(if s == "--no-color" {
+                    ColorWhen::Never
+                } else {
+                    match s.split_once('=').map(|(_, v)| v) {
+                        // Bare `--color` means always, matching clap's
+                        // `default_missing_value` for the same flag.
+                        None | Some("always") => ColorWhen::Always,
+                        Some("never") => ColorWhen::Never,
+                        // `auto`, and anything unrecognized: fall back to the
+                        // default rather than failing. This scan runs before the
+                        // command is even known and has no error channel, and the
+                        // post-verb spelling still gets clap's value validation.
+                        _ => ColorWhen::Auto,
+                    }
+                });
             }
             // Pre-verb PM output flags. `--reporter`/`--loglevel` only appear
             // here BEFORE a subcommand (after the verb they belong to the
@@ -2184,6 +2265,9 @@ fn run_nub() -> Result<i32> {
 
     SHOW_WARNINGS.store(show_warnings, Ordering::Relaxed);
     SILENT.store(silent, Ordering::Relaxed);
+    if let Some(when) = color_when {
+        set_color_mode(when);
+    }
 
     // Record the pre-verb PM output flags as process defaults so a PM verb
     // dispatched below (`nub --silent install`, `nub --reporter=silent add foo`)
@@ -2686,6 +2770,11 @@ fn dispatch_subcommand(rest: Vec<String>) -> Result<i32> {
     if cli.verbose > 0 {
         SHOW_WARNINGS.store(true, Ordering::Relaxed);
     }
+    // Only a non-default value, so `nub --color=never run build` (recorded by the
+    // position-1 scan) isn't reset to Auto by clap's default on this second pass.
+    if cli.color != ColorWhen::Auto {
+        set_color_mode(cli.color);
+    }
     if let Some(ref dir) = cli.cwd {
         env::set_current_dir(dir)?;
     }
@@ -5077,19 +5166,25 @@ fn run_one_workspace_script(
             leaf.exec,
             leaf.aggregate,
         ) {
+            // Nub's own per-member status line KEEPS its label even under
+            // `--reporter-hide-prefix`, matching pnpm (measured on 10.15.1: it emits
+            // `packages/a hello: Done` with the flag set). The flag exists to hand a
+            // CI annotation matcher the child's raw output; these three lines are
+            // Nub's framing, not the child's, and stripping them turned a workspace
+            // run into a stack of identical unattributable `Done`s.
             Ok(0) => {
                 // pnpm prints a per-package "Done" suffix on success.
-                let done_prefix = format_stream_prefix(&prefix, script, leaf.color_idx);
+                let done_prefix = format_status_prefix(&prefix, script, leaf.color_idx);
                 eprintln!("{done_prefix}Done");
                 MemberOutcome::Ran(0)
             }
             Ok(code) => {
-                let err_prefix = format_stream_prefix(&prefix, script, leaf.color_idx);
+                let err_prefix = format_status_prefix(&prefix, script, leaf.color_idx);
                 eprintln!("{err_prefix}exit {code}");
                 MemberOutcome::Ran(code)
             }
             Err(e) => {
-                let err_prefix = format_stream_prefix(&prefix, script, leaf.color_idx);
+                let err_prefix = format_status_prefix(&prefix, script, leaf.color_idx);
                 eprintln!("{err_prefix}error: {e}");
                 MemberOutcome::Ran(1)
             }
@@ -5602,6 +5697,25 @@ fn build_script_command(
         command.env("NODE_COMPAT", "1");
     }
 
+    // An explicit `--color` has to reach the CHILD, not just Nub's own framing —
+    // that is the whole point of asking for it. A workspace run pipes child stdio
+    // to prefix each line, which hides the TTY from the child, so tools that
+    // autodetect (tsc, vite, vitest, …) turn their own color off; `FORCE_COLOR` is
+    // the switch they already honor. Measured against pnpm 10.15.1, which resolves
+    // the flag exactly this way: `--color=always` gives the child `FORCE_COLOR=1`
+    // and `--no-color` gives it `FORCE_COLOR=0`. Default `auto` sets nothing, so
+    // the deliberate refusal to force color unasked (see aube's run_output.rs) is
+    // preserved — this is the opt-in escape hatch, not a new default.
+    match color_mode() {
+        ColorWhen::Always => {
+            command.env("FORCE_COLOR", "1");
+        }
+        ColorWhen::Never => {
+            command.env("FORCE_COLOR", "0");
+        }
+        ColorWhen::Auto => {}
+    }
+
     if let StreamMode::Prefixed = stream {
         command.stdout(std::process::Stdio::piped());
         command.stderr(std::process::Stdio::piped());
@@ -6206,11 +6320,14 @@ fn spawn_script_prefixed(
     let mut child = nub_core::node::spawn::spawn_with_eagain_retry(&mut command)?;
     // Relay docker stop / Ctrl-C to the streamed child's whole process group too
     // (workspace `-r` runs) — the `sh -c` won't pass a forwarded signal to node.
-    nub_core::node::spawn::track_child_group(child.id());
+    // This is the ONLY multi-child caller: `-r` runs members on concurrent worker
+    // threads, so several groups are tracked at once and each unregisters its own.
+    let child_pid = child.id();
+    nub_core::node::spawn::track_child_group(child_pid);
     // SIGKILL-on-the-leader backstop (#480) — macOS-only inside; held across
     // the wait below, dropped (disarmed) on return.
     #[cfg(unix)]
-    let _reaper = nub_core::node::spawn::spawn_group_reaper(child.id());
+    let _reaper = nub_core::node::spawn::spawn_group_reaper(child_pid);
 
     let stdout = child.stdout.take();
     let stderr = child.stderr.take();
@@ -6250,7 +6367,7 @@ fn spawn_script_prefixed(
     .drain();
 
     let status = child.wait()?;
-    nub_core::node::spawn::untrack_child();
+    nub_core::node::spawn::untrack_child(child_pid);
     let exit_code = nub_core::node::spawn::exit_code_from_status(&status);
     if ndjson {
         emit_ndjson(
@@ -6316,10 +6433,18 @@ fn format_stream_prefix(dir: &str, script: &str, idx: usize) -> String {
     format_stream_prefix_sep(dir, script, idx, ": ")
 }
 
+/// Prefix for Nub's OWN per-member status line (`Done` / `exit N` / `error: …`).
+/// Unlike [`format_stream_prefix`] this ignores `--reporter-hide-prefix`: that flag
+/// hides the label on the CHILD's output so a CI matcher sees raw lines, and pnpm
+/// likewise keeps the label on its own status line. Without the label a workspace
+/// run ends in N identical bare `Done`s that name no package.
+fn format_status_prefix(dir: &str, script: &str, idx: usize) -> String {
+    format_stream_prefix_sep(dir, script, idx, ": ")
+}
+
 fn format_stream_prefix_sep(dir: &str, script: &str, idx: usize, sep: &str) -> String {
     const DIR_COLORS: &[u8] = &[36, 35, 34, 33, 32, 31];
-    let use_color = std::io::IsTerminal::is_terminal(&std::io::stderr())
-        || std::env::var_os("FORCE_COLOR").is_some();
+    let use_color = color_enabled(std::io::IsTerminal::is_terminal(&std::io::stderr()));
     if use_color {
         let c = DIR_COLORS[idx % DIR_COLORS.len()];
         format!("\x1b[{c}m{dir}\x1b[39m \x1b[96m{script}\x1b[39m{sep}")
@@ -8572,13 +8697,11 @@ fn run_help(command: Option<&str>, verbose: bool) {
     }
 }
 
-/// Bold a header for the help pages when stdout is a TTY (or FORCE_COLOR is set)
-/// and NO_COLOR is unset. Plain text otherwise — same predicate family as the
-/// stream-prefix coloring, so piped/redirected help stays clean.
+/// Bold a header for the help pages when color is on for stdout. Plain text
+/// otherwise, so piped/redirected help stays clean. Shares [`color_enabled`] with
+/// the stream-prefix coloring so one `--color` answers for every surface.
 fn help_bold(s: &str) -> String {
-    let color = (std::io::IsTerminal::is_terminal(&std::io::stdout())
-        || std::env::var_os("FORCE_COLOR").is_some())
-        && std::env::var_os("NO_COLOR").is_none();
+    let color = color_enabled(std::io::IsTerminal::is_terminal(&std::io::stdout()));
     if color {
         format!("\x1b[1m{s}\x1b[0m")
     } else {
diff --git a/crates/nub-cli/src/pm_engine/mod.rs b/crates/nub-cli/src/pm_engine/mod.rs
index 3cd4ca956..dcea02be5 100644
--- a/crates/nub-cli/src/pm_engine/mod.rs
+++ b/crates/nub-cli/src/pm_engine/mod.rs
@@ -1511,14 +1511,12 @@ fn emit_scope_warnings(role: config_scope::Role, ignored: &[config_scope::Ignore
     }
 }
 
-/// Whether the scoping warning should be dim-styled: stderr is a terminal
-/// (or `FORCE_COLOR` is set) AND `NO_COLOR` is unset.
+/// Whether the scoping warning should be dim-styled. Delegates to the CLI's single
+/// color predicate so an explicit `--color`/`--no-color` governs the engine's
+/// warnings too, and so `FORCE_COLOR=0` reads as OFF rather than as merely set.
 pub(crate) fn scope_warning_uses_dim() -> bool {
     use std::io::IsTerminal;
-    if std::env::var_os("NO_COLOR").is_some() {
-        return false;
-    }
-    std::io::stderr().is_terminal() || std::env::var_os("FORCE_COLOR").is_some()
+    crate::cli::color_enabled(std::io::stderr().is_terminal())
 }
 
 /// The pnpm version the role-first UA advertises for a pnpm-role project with
diff --git a/crates/nub-cli/tests/integration.rs b/crates/nub-cli/tests/integration.rs
index e8722d7d5..47937f6d4 100644
--- a/crates/nub-cli/tests/integration.rs
+++ b/crates/nub-cli/tests/integration.rs
@@ -4697,6 +4697,145 @@ fn reporter_hide_prefix_strips_per_line_prefix() {
     }
 }
 
+/// `--reporter-hide-prefix` hides the CHILD's per-line label, not Nub's own framing.
+/// pnpm 10.15.1 still emits `<dir> <script>: Done` with the flag set, and a bare
+/// `Done` names no package — a workspace run ended in a stack of identical,
+/// unattributable lines (#685).
+#[test]
+fn reporter_hide_prefix_keeps_the_label_on_nubs_status_line() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let output = Command::new(nub_binary())
+        .args(["run", "-r", "--stream", "--reporter-hide-prefix", "build"])
+        .current_dir(&fixture)
+        .output()
+        .expect("spawn nub");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.lines().any(|l| l.contains("build: Done")),
+        "the per-member status line must keep its `<dir> <script>: ` label: {stderr}"
+    );
+    assert!(
+        !stderr.lines().any(|l| l.trim() == "Done"),
+        "no unattributable bare `Done` may remain: {stderr}"
+    );
+}
+
+/// `--color=always` has to reach the CHILD, not just Nub's own framing — that is the
+/// whole point of asking for it. A workspace run pipes child stdio to prefix each
+/// line, so the child sees no TTY and disables its own color; `FORCE_COLOR` is the
+/// override tools honor. Measured parity: pnpm 10.15.1 exports `FORCE_COLOR=1` here.
+/// Before #685 the flag parsed into a field nothing ever read.
+#[test]
+fn color_always_exports_force_color_to_the_script() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let output = Command::new(nub_binary())
+        .args(["--color=always", "run", "-r", "color-probe"])
+        .current_dir(&fixture)
+        .env_remove("FORCE_COLOR")
+        .env_remove("NO_COLOR")
+        .output()
+        .expect("spawn nub");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("FC=1"),
+        "--color=always must export FORCE_COLOR=1 to the script: {stdout}"
+    );
+}
+
+/// The opt-OUT half, and pnpm's exact spelling: `--no-color` exports `FORCE_COLOR=0`
+/// (10.15.1 measured), not an unset var — a child that inherited an ambient
+/// `FORCE_COLOR=1` must still be told to stop.
+#[test]
+fn no_color_exports_force_color_zero_to_the_script() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let output = Command::new(nub_binary())
+        .args(["--no-color", "run", "-r", "color-probe"])
+        .current_dir(&fixture)
+        .env("FORCE_COLOR", "1")
+        .output()
+        .expect("spawn nub");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("FC=0"),
+        "--no-color must export FORCE_COLOR=0, overriding the ambient value: {stdout}"
+    );
+}
+
+/// Default `auto` forces nothing either way, so a plain run stays byte-identical to
+/// pnpm's (which also leaves the child's `FORCE_COLOR` unset). This is the control
+/// that keeps the two tests above from passing for the wrong reason.
+#[test]
+fn color_auto_leaves_the_scripts_force_color_untouched() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let output = Command::new(nub_binary())
+        .args(["run", "-r", "color-probe"])
+        .current_dir(&fixture)
+        .env_remove("FORCE_COLOR")
+        .env_remove("NO_COLOR")
+        .output()
+        .expect("spawn nub");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("FC=unset"),
+        "a default run must not force color on the child: {stdout}"
+    );
+}
+
+/// `nub --help` advertises `NO_COLOR`, but the stream-prefix path never consulted it,
+/// so a colored prefix survived the opt-out. `FORCE_COLOR=1` stands in for a TTY here
+/// (the test harness has none), which is also what makes this a real control: the
+/// first case proves the prefix CAN be colored, so the second failing to color is
+/// attributable to `NO_COLOR` rather than to there being no color anywhere.
+#[test]
+fn no_color_env_suppresses_nubs_own_prefix_color() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let colored = Command::new(nub_binary())
+        .args(["run", "-r", "--stream", "build"])
+        .current_dir(&fixture)
+        .env("FORCE_COLOR", "1")
+        .env_remove("NO_COLOR")
+        .output()
+        .expect("spawn nub");
+    assert!(
+        String::from_utf8_lossy(&colored.stderr).contains('\x1b'),
+        "positive control: FORCE_COLOR=1 must colorize the prefix"
+    );
+
+    let plain = Command::new(nub_binary())
+        .args(["run", "-r", "--stream", "build"])
+        .current_dir(&fixture)
+        .env("FORCE_COLOR", "1")
+        .env("NO_COLOR", "1")
+        .output()
+        .expect("spawn nub");
+    assert!(
+        !String::from_utf8_lossy(&plain.stderr).contains('\x1b'),
+        "NO_COLOR must win over FORCE_COLOR: {}",
+        String::from_utf8_lossy(&plain.stderr)
+    );
+}
+
+/// `FORCE_COLOR=0` means OFF. The old predicate tested only for the variable's
+/// PRESENCE, so the conventional disable spelling switched color on — and that now
+/// matters directly, because `--no-color` exports exactly `FORCE_COLOR=0` to
+/// children, so a nested `nub` would have colorized on its parent's opt-out.
+#[test]
+fn force_color_zero_disables_nubs_own_prefix_color() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let output = Command::new(nub_binary())
+        .args(["run", "-r", "--stream", "build"])
+        .current_dir(&fixture)
+        .env("FORCE_COLOR", "0")
+        .env_remove("NO_COLOR")
+        .output()
+        .expect("spawn nub");
+    assert!(
+        !String::from_utf8_lossy(&output.stderr).contains('\x1b'),
+        "FORCE_COLOR=0 must disable color: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
 #[test]
 fn ndjson_reporter_emits_valid_json_events() {
     // `--reporter=ndjson` emits one JSON object per line on stdout, covering
diff --git a/crates/nub-core/src/node/spawn.rs b/crates/nub-core/src/node/spawn.rs
index 012385c9a..841e9028b 100644
--- a/crates/nub-core/src/node/spawn.rs
+++ b/crates/nub-core/src/node/spawn.rs
@@ -177,19 +177,33 @@ fn libc_enomem() -> i32 {
 /// processes stay alive — exactly as if `node` had received the signal directly.
 #[cfg(unix)]
 mod ctrl_c {
-    use std::sync::Once;
-    use std::sync::atomic::{AtomicBool, AtomicI32, Ordering};
-
-    // The forward TARGET, as the argument to `kill(2)`: a POSITIVE pid signals one
-    // process (the file-run path's `node`, which IS the leaf); a NEGATIVE value
-    // signals the whole PROCESS GROUP `-value` (the script path's `sh -c` child,
-    // made a group leader via `setpgid`, so the signal reaches `sh` AND the `node`
-    // it forks — a non-interactive `sh -c` does NOT relay signals to a forked
-    // child, so single-pid delivery left the workload orphaned under dash). 0 = no
-    // child tracked.
-    static CURRENT_TARGET: AtomicI32 = AtomicI32::new(0);
+    use std::sync::atomic::{AtomicBool, Ordering};
+    use std::sync::{Mutex, MutexGuard, Once};
+
+    // The forward TARGETS, each an argument to `kill(2)`: a POSITIVE pid signals one
+    // process (a bare leaf); a NEGATIVE value signals the whole PROCESS GROUP
+    // `-value` (the script path's `sh -c` child, made a group leader via `setpgid`,
+    // so the signal reaches `sh` AND the `node` it forks — a non-interactive `sh -c`
+    // does NOT relay signals to a forked child, so single-pid delivery left the
+    // workload orphaned under dash). Empty = no child tracked.
+    //
+    // A SET, not one slot: a workspace run executes N members CONCURRENTLY on worker
+    // threads, and its concurrency defaults to `min(4, cpus)` — so several children
+    // are live at once even without `--parallel`. With a single slot each spawn
+    // overwrote the last, so one Ctrl-C reached exactly one child (which one was a
+    // race), every sibling was orphaned, and nub then blocked forever waiting on
+    // them (#685).
+    static TARGETS: Mutex<Vec<i32>> = Mutex::new(Vec::new());
     static REGISTERED: Once = Once::new();
 
+    /// Lock [`TARGETS`], recovering from poisoning. A poisoned lock only means some
+    /// thread panicked while holding it; the payload is a plain `Vec<i32>` with no
+    /// invariant a panic can break, and bailing out here would leave a live child
+    /// unsignalled — the exact failure this module exists to prevent.
+    fn targets() -> MutexGuard<'static, Vec<i32>> {
+        TARGETS.lock().unwrap_or_else(|e| e.into_inner())
+    }
+
     // When the controlling terminal's FOREGROUND process group has been handed to
     // the child (the interactive TTY path — see `foreground_child` in spawn.rs),
     // the kernel delivers a terminal Ctrl-C straight to the child. nub is no longer
@@ -217,10 +231,11 @@ mod ctrl_c {
         SUPPRESS_SIGINT_FORWARD.load(Ordering::SeqCst)
     }
 
-    /// Record the `kill(2)` target (see [`CURRENT_TARGET`]), registering the signal
-    /// handler on the first call. Later calls just update the target.
+    /// Add a `kill(2)` target (see [`TARGETS`]), registering the signal handler on
+    /// the first call. Every live target is signalled, so concurrent children each
+    /// add their own on spawn and remove it again on exit.
     pub(super) fn track(target: i32) {
-        CURRENT_TARGET.store(target, Ordering::SeqCst);
+        targets().push(target);
         REGISTERED.call_once(|| {
             use signal_hook::consts::{SIGHUP, SIGINT, SIGQUIT, SIGTERM, SIGUSR1, SIGUSR2};
             use signal_hook::iterator::Signals;
@@ -255,12 +270,15 @@ mod ctrl_c {
                             if signo == SIGINT && SUPPRESS_SIGINT_FORWARD.load(Ordering::SeqCst) {
                                 continue;
                             }
-                            let target = CURRENT_TARGET.load(Ordering::SeqCst);
-                            if target != 0 {
+                            // Snapshot, then signal outside the lock: a worker thread
+                            // may be adding or removing a target concurrently, and
+                            // nothing here needs the whole fan-out to be atomic.
+                            let live: Vec<i32> = targets().clone();
+                            for target in live {
                                 // SAFETY: kill(2) with a stored-live target + the received
                                 // signal. A positive target signals one process; a negative
                                 // one signals process group `-target`. Benign if the
-                                // child/group already exited (ESRCH); cleared to 0 on exit.
+                                // child/group already exited (ESRCH); removed on exit.
                                 unsafe {
                                     libc::kill(target, signo);
                                 }
@@ -271,14 +289,25 @@ mod ctrl_c {
         });
     }
 
-    /// Clear the current target after the child exits.
-    pub(super) fn untrack() {
-        CURRENT_TARGET.store(0, Ordering::SeqCst);
+    /// Drop ONE target once its child exits, leaving every sibling still tracked.
+    /// Removes a single occurrence, so two entries that happen to share a value
+    /// (a recycled pid) can't disarm each other early.
+    pub(super) fn untrack(target: i32) {
+        let mut live = targets();
+        if let Some(pos) = live.iter().rposition(|&t| t == target) {
+            live.remove(pos);
+        }
+    }
+
+    /// Drop every target. Test-only — each production path removes its own.
+    #[cfg(test)]
+    pub(super) fn reset() {
+        targets().clear();
     }
 
     #[cfg(test)]
-    pub(super) fn current() -> i32 {
-        CURRENT_TARGET.load(Ordering::SeqCst)
+    pub(super) fn tracked() -> Vec<i32> {
+        targets().clone()
     }
 }
 
@@ -296,10 +325,19 @@ pub fn track_child_group(pid: u32) {
     let _ = pid;
 }
 
-/// Clear the tracked child/group after it exits — pair with [`track_child_group`].
-pub fn untrack_child() {
+/// Stop forwarding to ONE child's group after it exits — pair with
+/// [`track_child_group`], passing the same pid.
+///
+/// Takes the pid rather than clearing a single global slot because a workspace run
+/// holds several children tracked at once: zeroing the slot when the FIRST one
+/// finished disarmed the forward for every still-running sibling, so a later Ctrl-C
+/// reached nothing and nub hung waiting on children it could no longer signal
+/// (#685).
+pub fn untrack_child(pid: u32) {
     #[cfg(unix)]
-    ctrl_c::untrack();
+    ctrl_c::untrack(-(pid as i32));
+    #[cfg(not(unix))]
+    let _ = pid;
 }
 
 /// Hand the controlling terminal's FOREGROUND process group to a just-spawned
@@ -665,7 +703,8 @@ pub fn run_pdeath_watch(args: &[String]) -> i32 {
 pub fn status_forwarding_signals(cmd: &mut Command) -> std::io::Result<ExitStatus> {
     group_on_spawn(cmd);
     let mut child = spawn_with_eagain_retry(cmd)?;
-    track_child_group(child.id());
+    let pid = child.id();
+    track_child_group(pid);
     // SIGKILL-on-the-leader backstop (#480) — macOS-only inside; see
     // `spawn_group_reaper`. Held across the wait, dropped (disarmed) after.
     #[cfg(unix)]
@@ -677,7 +716,7 @@ pub fn status_forwarding_signals(cmd: &mut Command) -> std::io::Result<ExitStatu
     #[cfg(unix)]
     let _fg = foreground_child(child.id());
     let status = child.wait();
-    untrack_child();
+    untrack_child(pid);
     status
 }
 
@@ -1333,7 +1372,8 @@ pub fn spawn_node(config: &SpawnConfig<'_>) -> Result<SpawnResult> {
     // The child is its own group leader (see `group_on_spawn` above), so the
     // negative target signals the child and its descendants exactly once.
     // (No-op off Unix.)
-    track_child_group(child.id());
+    let child_pid = child.id();
+    track_child_group(child_pid);
 
     // SIGKILL-on-the-leader backstop (#480) — macOS-only inside; see
     // `spawn_group_reaper`. Held across the wait, dropped (disarmed) after.
@@ -1350,7 +1390,7 @@ pub fn spawn_node(config: &SpawnConfig<'_>) -> Result<SpawnResult> {
     let status = child.wait().with_context(|| "waiting for Node child")?;
 
     // Stop forwarding to this (now-exited) group before returning. (No-op off Unix.)
-    untrack_child();
+    untrack_child(child_pid);
 
     Ok(SpawnResult { status })
 }
@@ -3760,26 +3800,32 @@ mod tests {
 
     #[cfg(unix)]
     #[test]
-    fn ctrl_c_forwards_to_the_latest_child_not_the_first() {
+    fn ctrl_c_forwards_to_every_live_child_not_just_the_latest() {
         let _serial = CTRL_C_TEST_GUARD.lock().unwrap_or_else(|e| e.into_inner());
-        // The bug A20 fixes: a second spawn's set_handler no-op'd, so the single
-        // handler kept the first (dead) pid. Now the global pid updates per spawn,
-        // so the handler always targets the current child; untrack clears it so a
-        // stray SIGINT after exit is a no-op rather than a kill of a reused pid.
-        ctrl_c::untrack(); // reset the shared global before asserting on it
+        // Two bugs meet here. A20: a second spawn's set_handler no-op'd, so the lone
+        // handler kept the FIRST (dead) pid — a later spawn has to be reachable.
+        // #685: a single slot then meant a later spawn EVICTED the earlier one, so a
+        // `nub run -r` Ctrl-C signalled one member and orphaned its concurrent
+        // siblings. Only a set satisfies both — every live child is a target, and
+        // each removes exactly its own on exit.
+        ctrl_c::reset();
         ctrl_c::track(111);
-        assert_eq!(ctrl_c::current(), 111);
         ctrl_c::track(222);
         assert_eq!(
-            ctrl_c::current(),
-            222,
-            "a later spawn must become the forwarded target"
+            ctrl_c::tracked(),
+            vec![111, 222],
+            "both concurrent children stay reachable — a later spawn adds, never evicts"
         );
-        ctrl_c::untrack();
+        ctrl_c::untrack(111);
         assert_eq!(
-            ctrl_c::current(),
-            0,
-            "untrack clears the pid after the child exits"
+            ctrl_c::tracked(),
+            vec![222],
+            "one child exiting must leave its still-running sibling tracked"
+        );
+        ctrl_c::untrack(222);
+        assert!(
+            ctrl_c::tracked().is_empty(),
+            "a stray signal after the last child exits must find no target"
         );
     }
 
@@ -3791,7 +3837,7 @@ mod tests {
         // must return the child's real status AND leave the global untracked, so a
         // stray signal after the script exits can't kill a reused pid.
         let _serial = CTRL_C_TEST_GUARD.lock().unwrap_or_else(|e| e.into_inner());
-        ctrl_c::untrack();
+        ctrl_c::reset();
         let status = status_forwarding_signals(Command::new("sh").arg("-c").arg("exit 7"))
             .expect("spawn sh");
         assert_eq!(
@@ -3799,10 +3845,9 @@ mod tests {
             7,
             "the child's code passes through"
         );
-        assert_eq!(
-            ctrl_c::current(),
-            0,
-            "the tracked pid is cleared once the child exits"
+        assert!(
+            ctrl_c::tracked().is_empty(),
+            "the tracked group is removed once the child exits"
         );
     }
 
@@ -3813,11 +3858,18 @@ mod tests {
         // process GROUP (sh + the node it forks), not just sh — the orphan the
         // single-pid path left under a dash that forks its `sh -c` child.
         let _serial = CTRL_C_TEST_GUARD.lock().unwrap_or_else(|e| e.into_inner());
-        ctrl_c::untrack();
+        ctrl_c::reset();
         track_child_group(4321);
-        assert_eq!(ctrl_c::current(), -4321, "group target is the negated pid");
-        untrack_child();
-        assert_eq!(ctrl_c::current(), 0);
+        assert_eq!(
+            ctrl_c::tracked(),
+            vec![-4321],
+            "group target is the negated pid"
+        );
+        untrack_child(4321);
+        assert!(
+            ctrl_c::tracked().is_empty(),
+            "untrack_child takes the same pid and removes that group"
+        );
     }
 
     #[cfg(unix)]
@@ -3839,7 +3891,7 @@ mod tests {
         // interactive TTY Ctrl-C is not reproducible in CI without a pty; this pins
         // the own-group + single-forward invariant that makes it correct.)
         let _serial = CTRL_C_TEST_GUARD.lock().unwrap_or_else(|e| e.into_inner());
-        ctrl_c::untrack();
+        ctrl_c::reset();
 
         let marker = env::temp_dir().join(format!(
             "nub-sigint-count-{}-{}.marker",
@@ -3864,7 +3916,8 @@ mod tests {
 
         // Forward to the child's GROUP — the single, sole delivery path now that the
         // child is in its own group (nothing else signals it).
-        track_child_group(child.id());
+        let child_pid = child.id();
+        track_child_group(child_pid);
 
         // Let the trap install before delivering.
         std::thread::sleep(std::time::Duration::from_millis(200));
@@ -3876,7 +3929,7 @@ mod tests {
         }
 
         let status = loop_wait(&mut child, std::time::Duration::from_secs(5));
-        untrack_child();
+        untrack_child(child_pid);
 
         let deliveries = fs::read_to_string(&marker)
             .map(|s| s.lines().count())
@@ -3930,7 +3983,8 @@ mod tests {
 
         // Register nub's forwarder for this child (installs the SIGUSR2 handler that
         // overrides the parent's terminate-on-USR2 default and relays to the child).
-        ctrl_c::track(child.id() as i32);
+        let tracked_pid = child.id() as i32;
+        ctrl_c::track(tracked_pid);
 
         // Give the child's `trap` a moment to install before we deliver the signal.
         std::thread::sleep(std::time::Duration::from_millis(150));
@@ -3945,7 +3999,7 @@ mod tests {
         // The relay is async (signal-hook self-pipe → forwarder thread → kill child),
         // so poll for the marker / child exit rather than racing it.
         let status = loop_wait(&mut child, std::time::Duration::from_secs(5));
-        ctrl_c::untrack();
+        ctrl_c::untrack(tracked_pid);
 
         let marker_written = marker.exists();
         let _ = fs::remove_file(&marker);
@@ -3965,6 +4019,111 @@ mod tests {
         // never runs these assertions.
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn one_signal_reaches_every_concurrently_tracked_child() {
+        let _serial = CTRL_C_TEST_GUARD.lock().unwrap_or_else(|e| e.into_inner());
+        // Regression for #685. `nub run -r` runs members on concurrent worker threads
+        // — its concurrency defaults to `min(4, cpus)`, so this is the DEFAULT shape,
+        // not just `--parallel`. Each spawn used to overwrite a single global target
+        // slot, so one Ctrl-C reached whichever child happened to be tracked last
+        // (a race), every sibling was orphaned holding its port, and nub then blocked
+        // forever waiting on children it could no longer signal.
+        //
+        // Two own-group children, both tracked, ONE signal delivered to this process:
+        // both must run their trap. SIGUSR2 rather than SIGINT because it exercises
+        // the same fan-out through the identical forwarder path without perturbing the
+        // test harness's own interrupt handling — the defect is in which TARGETS get
+        // signalled, which is signal-agnostic.
+        let stamp = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let markers: Vec<_> = (0..2)
+            .map(|i| {
+                env::temp_dir().join(format!(
+                    "nub-fanout-{}-{}-{i}.marker",
+                    std::process::id(),
+                    stamp
+                ))
+            })
+            .collect();
+        for m in &markers {
+            let _ = fs::remove_file(m);
+        }
+
+        ctrl_c::reset();
+        let mut children = Vec::new();
+        for m in &markers {
+            let mut cmd = Command::new("sh");
+            cmd.arg("-c").arg(format!(
+                "trap 'echo got >{m}; exit 0' USR2; sleep 5 & wait",
+                m = m.display()
+            ));
+            // Own process group, exactly as the real `-r` script path does.
+            group_on_spawn(&mut cmd);
+            let child = cmd.spawn().expect("spawn fan-out child");
+            track_child_group(child.id());
+            children.push(child);
+        }
+
+        // Let both traps install before delivering.
+        std::thread::sleep(std::time::Duration::from_millis(250));
+
+        // SAFETY: kill(2) on our own pid with a signal nub has a handler for.
+        unsafe {
+            libc::kill(std::process::id() as i32, libc::SIGUSR2);
+        }
+
+        let codes: Vec<_> = children
+            .iter_mut()
+            .map(|c| loop_wait(c, std::time::Duration::from_secs(5)).and_then(|s| s.code()))
+            .collect();
+        for c in &mut children {
+            let _ = c.kill();
+            let _ = c.wait();
+        }
+        let written: Vec<bool> = markers.iter().map(|m| m.exists()).collect();
+        for m in &markers {
+            let _ = fs::remove_file(m);
+        }
+        for c in &children {
+            untrack_child(c.id());
+        }
+
+        assert_eq!(
+            written,
+            vec![true, true],
+            "ONE signal must reach BOTH tracked children — {written:?} means a sibling \
+             was orphaned, which is the #685 defect"
+        );
+        assert_eq!(
+            codes,
+            vec![Some(0), Some(0)],
+            "each child must exit 0 through its OWN trap, not be hard-killed"
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn a_child_exiting_leaves_its_siblings_signalable() {
+        let _serial = CTRL_C_TEST_GUARD.lock().unwrap_or_else(|e| e.into_inner());
+        // The second half of #685, and the one a set alone doesn't buy: `untrack` used
+        // to CLEAR the slot, so the first member of a `-r` run to finish disarmed
+        // forwarding for everyone still running. A later Ctrl-C then reached nothing
+        // at all. Removing only its own entry is what keeps the survivors reachable.
+        ctrl_c::reset();
+        track_child_group(4321);
+        track_child_group(8765);
+        untrack_child(4321);
+        assert_eq!(
+            ctrl_c::tracked(),
+            vec![-8765],
+            "the finished child must remove only ITS OWN group and leave the sibling"
+        );
+        ctrl_c::reset();
+    }
+
     // ---- issue #27: terminal-foreground hand-off to an interactive child ----
 
     /// The PTY-scenario worker, run as its OWN fresh process (NOT a fork of the
@@ -4195,7 +4354,7 @@ mod tests {
 
         // The full nub topology: register the forwarder (the #26 double-delivery
         // path) AND hand the terminal foreground to the child (tcsetpgrp + suppress).
-        ctrl_c::untrack();
+        ctrl_c::reset();
         track_child_group(child_pid);
         let _fg = foreground_child(child_pid);
 
diff --git a/site/content/docs/runner/run.mdx b/site/content/docs/runner/run.mdx
index 278c2174f..6424238de 100644
--- a/site/content/docs/runner/run.mdx
+++ b/site/content/docs/runner/run.mdx
@@ -350,7 +350,7 @@ nub run --workspace @org/api --workspace @org/web build
 
 ## `--stream`, `--aggregate-output`
 
-On a TTY, Nub streams interleaved, per-package-prefixed output (`<pkg> | <line>`, matching `pnpm -r`). On CI / non-TTY it buffers per package and flushes on finish. Override either default explicitly.
+On a TTY, Nub streams interleaved output, leading each line with the package directory and the script name (`packages/api build: <line>`, matching `pnpm -r`). On CI / non-TTY it buffers per package and flushes on finish. Override either default explicitly.
 
 ```bash
 nub run -r --stream build            # force interleaved live output
@@ -358,12 +358,34 @@ nub run -r --aggregate-output build  # force per-package buffering
 nub run -r --reporter ndjson build   # one JSON event per line, for CI parsing
 ```
 
+To drop the per-line label — so a CI annotation matcher reads the script's own `error: file:line` output — add `--reporter-hide-prefix`. Nub's own framing keeps its label, so you can still tell which package finished:
+
+```bash
+nub run -r --stream --reporter-hide-prefix build
+```
+
 And `--silent` (or `-s`) suppresses Nub's `$ <command>` preamble (it does not suppress the script's own stdout):
 
 ```bash
 nub run --silent build
 ```
 
+## `--color`
+
+Prefixing each line means piping the script's output, and a piped tool sees no terminal, so most of them switch their own color off. Ask for it back with `--color`, and the scripts keep their colors under prefixing:
+
+```bash
+nub run -r --parallel --color=always dev  # scripts stay colored, prefixes too
+nub run -r --no-color build               # plain text from Nub and from the scripts
+```
+
+Nub passes the choice down as `FORCE_COLOR`, the variable those tools already read — `1` for `--color=always`, `0` for `--no-color`. This matches pnpm. Without the flag Nub forces nothing either way, and the usual environment signals decide:
+
+```bash
+NO_COLOR=1 nub run -r build      # off, whatever the terminal says
+FORCE_COLOR=1 nub run -r build   # on, even when the output is piped
+```
+
 ## `--node`
 
 By default, the `nub` executable is aliased as `node` for the duration of a `nub run` call, so any subprocess that spawns `node` (a script shebang, `child_process.spawn("node", …)`) gets Nub's augmentation too. Pass `--node` to turn that off for one invocation — see [the runtime overview](/docs/runtime#--node) for the full contract.
diff --git a/tests/fixtures/monorepo-deps/packages/core/package.json b/tests/fixtures/monorepo-deps/packages/core/package.json
index 683c8d35f..130e26869 100644
--- a/tests/fixtures/monorepo-deps/packages/core/package.json
+++ b/tests/fixtures/monorepo-deps/packages/core/package.json
@@ -1 +1 @@
-{"name":"@mono/core","scripts":{"build":"echo core-built","test":"echo core-tested","lint":"echo core-linted","slow":"node -e \"setTimeout(()=>console.log('core-done'),1000)\"","slow-stamp":"node -e \"const fs=require('fs'),p=require('path'),t=Date.now(),d=process.env.NUB_STAMP_DIR;if(d){fs.writeFileSync(p.join(d,'core-start'),''+t)};setTimeout(()=>{if(d){fs.writeFileSync(p.join(d,'core-end'),''+Date.now())};console.log('core-done')},1000)\""}}
\ No newline at end of file
+{"name":"@mono/core","scripts":{"build":"echo core-built","color-probe":"node -e \"console.log('core FC=' + (process.env.FORCE_COLOR ?? 'unset'))\"","test":"echo core-tested","lint":"echo core-linted","slow":"node -e \"setTimeout(()=>console.log('core-done'),1000)\"","slow-stamp":"node -e \"const fs=require('fs'),p=require('path'),t=Date.now(),d=process.env.NUB_STAMP_DIR;if(d){fs.writeFileSync(p.join(d,'core-start'),''+t)};setTimeout(()=>{if(d){fs.writeFileSync(p.join(d,'core-end'),''+Date.now())};console.log('core-done')},1000)\""}}
\ No newline at end of file
diff --git a/tests/fixtures/monorepo-deps/packages/utils/package.json b/tests/fixtures/monorepo-deps/packages/utils/package.json
index a9736a75f..30cc06fd0 100644
--- a/tests/fixtures/monorepo-deps/packages/utils/package.json
+++ b/tests/fixtures/monorepo-deps/packages/utils/package.json
@@ -1 +1 @@
-{"name":"@mono/utils","dependencies":{"@mono/core":"*"},"scripts":{"build":"echo utils-built","test":"echo utils-tested","slow":"node -e \"setTimeout(()=>console.log('utils-done'),1000)\"","slow-stamp":"node -e \"const fs=require('fs'),p=require('path'),t=Date.now(),d=process.env.NUB_STAMP_DIR;if(d){fs.writeFileSync(p.join(d,'utils-start'),''+t)};setTimeout(()=>{if(d){fs.writeFileSync(p.join(d,'utils-end'),''+Date.now())};console.log('utils-done')},1000)\""}}
\ No newline at end of file
+{"name":"@mono/utils","dependencies":{"@mono/core":"*"},"scripts":{"build":"echo utils-built","color-probe":"node -e \"console.log('utils FC=' + (process.env.FORCE_COLOR ?? 'unset'))\"","test":"echo utils-tested","slow":"node -e \"setTimeout(()=>console.log('utils-done'),1000)\"","slow-stamp":"node -e \"const fs=require('fs'),p=require('path'),t=Date.now(),d=process.env.NUB_STAMP_DIR;if(d){fs.writeFileSync(p.join(d,'utils-start'),''+t)};setTimeout(()=>{if(d){fs.writeFileSync(p.join(d,'utils-end'),''+Date.now())};console.log('utils-done')},1000)\""}}
\ No newline at end of file

From eb004fb169b6f471cdc111b8decb6c2c99af44fb Mon Sep 17 00:00:00 2001
From: Colin McDonnell <3084745+colinhacks@users.noreply.github.com>
Date: Sat, 15 Aug 2026 12:25:04 -0700
Subject: [PATCH 2/5] run: accept --no-color after the verb, and follow Node's
 FORCE_COLOR table
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two findings from review on #744.

--no-color was only caught by the pre-subcommand argv scan, which stops at
the first verb, so `nub run -r --no-color build` exited 2 with "unexpected
argument" while the pre-verb spelling worked. pnpm accepts it in both
positions (measured on 10.15.1). Declare it to clap as a global as well,
and list it in `nub --help`, where it appeared nowhere. A flag after the
script name still forwards to the script, so the three-position rule holds.

color_enabled read an empty FORCE_COLOR as OFF. Node's getColorDepth lists
`case ''` alongside '1' and 'true', so empty is its shortest spelling of
ON — and the point of this predicate is that nub agrees with the children
it hands the variable to, which made that arm invert the one convention it
existed to match. Follow Node's table exactly: '', '1', 'true', '2' and '3'
enable; everything else, 'false' and unrecognized values included, is
monochrome. Checked against a live getColorDepth across all eight values.
---
 crates/nub-cli/src/cli.rs           | 45 +++++++++++++++++-----
 crates/nub-cli/tests/integration.rs | 60 +++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+), 10 deletions(-)

diff --git a/crates/nub-cli/src/cli.rs b/crates/nub-cli/src/cli.rs
index fce87a6d7..24981d761 100644
--- a/crates/nub-cli/src/cli.rs
+++ b/crates/nub-cli/src/cli.rs
@@ -741,6 +741,15 @@ pub struct Cli {
     #[arg(long, global = true, default_value = "auto", default_missing_value = "always", num_args = 0..=1, require_equals = true)]
     pub color: ColorWhen,
 
+    /// Disable color. The pnpm-compatible spelling of `--color=never`.
+    ///
+    /// Declared to clap as well as caught by the pre-subcommand argv scan, because
+    /// pnpm accepts it in BOTH positions and the scan only sees tokens before the
+    /// verb: without this, `nub run -r --no-color build` exited 2 with `unexpected
+    /// argument` while the pre-verb spelling worked.
+    #[arg(long = "no-color", global = true, conflicts_with = "color")]
+    pub no_color: bool,
+
     /// Enable watch mode (alias for `nub watch`).
     #[arg(long)]
     pub watch: bool,
@@ -1500,13 +1509,16 @@ pub(crate) fn color_mode() -> ColorWhen {
 /// first: an explicit `--color`/`--no-color`, then `NO_COLOR`, then `FORCE_COLOR`,
 /// then whether the stream is really a terminal.
 ///
-/// Two things this gets right that the open-coded
-/// `is_terminal() || var_os("FORCE_COLOR").is_some()` did not. `NO_COLOR` was not
-/// consulted at all on the stream-prefix path, so `NO_COLOR=1` still produced a
-/// colored prefix despite `--help` promising otherwise. And `FORCE_COLOR=0` means
-/// OFF — mere presence read as ON, which inverts the request, and matters directly
-/// here because `--no-color` exports exactly `FORCE_COLOR=0` to children for pnpm
-/// parity, so a nested `nub` would have colorized on its parent's opt-OUT.
+/// It replaces an open-coded `is_terminal() || var_os("FORCE_COLOR").is_some()`,
+/// which never consulted `NO_COLOR` on the stream-prefix path (so `NO_COLOR=1`
+/// still produced a colored prefix, despite `--help` promising otherwise) and read
+/// a mere presence as ON (so `FORCE_COLOR=0` switched color on).
+///
+/// One deliberate divergence from Node: when `FORCE_COLOR` and `NO_COLOR` are BOTH
+/// set, Node lets `FORCE_COLOR` win and warns; Nub lets `NO_COLOR` win. That keeps
+/// the promise `--help` prints and matches what the engine's own warning path
+/// already did. Either way an explicit flag outranks both, which is the case a user
+/// actually hits.
 pub(crate) fn color_enabled(stream_is_tty: bool) -> bool {
     match color_mode() {
         ColorWhen::Always => return true,
@@ -1514,12 +1526,22 @@ pub(crate) fn color_enabled(stream_is_tty: bool) -> bool {
         ColorWhen::Auto => {}
     }
     // The NO_COLOR convention is "present and non-empty", so an empty value is
-    // explicitly NOT an opt-out.
+    // explicitly NOT an opt-out. Node spells the same check in `getColorDepth`.
     if std::env::var_os("NO_COLOR").is_some_and(|v| !v.is_empty()) {
         return false;
     }
     if let Some(v) = std::env::var_os("FORCE_COLOR") {
-        return !matches!(v.to_str(), Some("") | Some("0"));
+        // Mirror Node's `getColorDepth` value table (lib/internal/tty.js): only
+        // '', '1', 'true', '2' and '3' enable color — every other value, '0' and
+        // 'false' included, falls through to its 2-color monochrome branch. The
+        // exact set matters because Nub hands `FORCE_COLOR` to the children whose
+        // output it prefixes, so a value Nub read as ON while Node read it as OFF
+        // would split the two apart. An EMPTY value is Node's shortest way to say
+        // ON, which is why it cannot be lumped in with '0'.
+        return matches!(
+            v.to_str(),
+            Some("") | Some("1") | Some("true") | Some("2") | Some("3")
+        );
     }
     stream_is_tty
 }
@@ -2772,7 +2794,9 @@ fn dispatch_subcommand(rest: Vec<String>) -> Result<i32> {
     }
     // Only a non-default value, so `nub --color=never run build` (recorded by the
     // position-1 scan) isn't reset to Auto by clap's default on this second pass.
-    if cli.color != ColorWhen::Auto {
+    if cli.no_color {
+        set_color_mode(ColorWhen::Never);
+    } else if cli.color != ColorWhen::Auto {
         set_color_mode(cli.color);
     }
     if let Some(ref dir) = cli.cwd {
@@ -8868,6 +8892,7 @@ nub {v} — the all-in-one Node.js toolkit
   -s, --silent         suppress nub's non-error output
   --verbose            increase nub's log verbosity (repeatable)
   --color[=<when>]     color mode: auto (default), always, never
+  --no-color           disable color (same as --color=never)
   --env-file <file>    load environment variables from <file>
   --env-file-if-exists <file>  like --env-file, but skip silently if <file> is absent
   --no-env-file        load no env files: no `.env*` auto-discovery, no --env-file
diff --git a/crates/nub-cli/tests/integration.rs b/crates/nub-cli/tests/integration.rs
index 47937f6d4..ed37d02cf 100644
--- a/crates/nub-cli/tests/integration.rs
+++ b/crates/nub-cli/tests/integration.rs
@@ -4836,6 +4836,66 @@ fn force_color_zero_disables_nubs_own_prefix_color() {
     );
 }
 
+/// pnpm accepts `--no-color` both before and after the verb; Nub's pre-subcommand
+/// scan only sees the pre-verb position, so the post-verb spelling used to exit 2
+/// with `unexpected argument`. Both must work, and both must actually disable color.
+#[test]
+fn no_color_is_accepted_before_and_after_the_verb() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    for args in [
+        vec!["--no-color", "run", "-r", "--stream", "build"],
+        vec!["run", "-r", "--stream", "--no-color", "build"],
+    ] {
+        let output = Command::new(nub_binary())
+            .args(&args)
+            .current_dir(&fixture)
+            .env("FORCE_COLOR", "1")
+            .output()
+            .expect("spawn nub");
+        assert!(
+            output.status.success(),
+            "`nub {}` must parse: {}",
+            args.join(" "),
+            String::from_utf8_lossy(&output.stderr)
+        );
+        assert!(
+            !String::from_utf8_lossy(&output.stderr).contains('\x1b'),
+            "`nub {}` must disable color: {}",
+            args.join(" "),
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+}
+
+/// An EMPTY `FORCE_COLOR` is Node's shortest spelling of ON — `getColorDepth` lists
+/// `case ''` alongside `'1'` and `'true'` (lib/internal/tty.js). Reading it as OFF
+/// split Nub from the very children it hands the variable to. `'false'` is the other
+/// half of the same table: Node falls through to monochrome, so Nub must too.
+#[test]
+fn force_color_values_follow_nodes_table() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    for (value, want_color) in [
+        ("", true),
+        ("1", true),
+        ("true", true),
+        ("0", false),
+        ("false", false),
+    ] {
+        let output = Command::new(nub_binary())
+            .args(["run", "-r", "--stream", "build"])
+            .current_dir(&fixture)
+            .env("FORCE_COLOR", value)
+            .env_remove("NO_COLOR")
+            .output()
+            .expect("spawn nub");
+        let got = String::from_utf8_lossy(&output.stderr).contains('\x1b');
+        assert_eq!(
+            got, want_color,
+            "FORCE_COLOR={value:?} should give color={want_color}, matching Node's getColorDepth"
+        );
+    }
+}
+
 #[test]
 fn ndjson_reporter_emits_valid_json_events() {
     // `--reporter=ndjson` emits one JSON object per line on stdout, covering

From f32f0285d6c032dcb48312861f8211e48d638f2f Mon Sep 17 00:00:00 2001
From: Colin McDonnell <3084745+colinhacks@users.noreply.github.com>
Date: Sat, 15 Aug 2026 12:51:02 -0700
Subject: [PATCH 3/5] run: keep a contradictory color env from splitting nub
 from its child
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-up on #744.

Nub resolves NO_COLOR over FORCE_COLOR; Node resolves them the other way.
With both set the two answers disagreed inside a single run: nub's label
went plain while the child colorized, so a workspace run emitted colored
lines wrapped in uncolored labels. Measured before the fix — the child's
getColorDepth returned 4 under `NO_COLOR=1 FORCE_COLOR=1`.

In auto mode the launcher now exports FORCE_COLOR=0 for exactly that
contradictory pair, pinning the child to nub's answer. Auto still forces
nothing when neither variable is set or only one of them is, which is every
ordinary invocation; the two added tests cover the split case and that
control. The precedence itself is unchanged — NO_COLOR still wins, keeping
the promise `nub --help` prints.

Also factor Node's FORCE_COLOR value table into one helper now that both
the predicate and the launcher read it, so they cannot drift, and clear
NO_COLOR in the --no-color position test: it set FORCE_COLOR=1 without
clearing NO_COLOR, so an ambient NO_COLOR would have satisfied its
"color is off" assertion whether or not the flag did anything.
---
 crates/nub-cli/src/cli.rs           | 49 ++++++++++++++++++++-------
 crates/nub-cli/tests/integration.rs | 52 +++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 12 deletions(-)

diff --git a/crates/nub-cli/src/cli.rs b/crates/nub-cli/src/cli.rs
index 24981d761..4f74786c3 100644
--- a/crates/nub-cli/src/cli.rs
+++ b/crates/nub-cli/src/cli.rs
@@ -1519,6 +1519,11 @@ pub(crate) fn color_mode() -> ColorWhen {
 /// the promise `--help` prints and matches what the engine's own warning path
 /// already did. Either way an explicit flag outranks both, which is the case a user
 /// actually hits.
+///
+/// That divergence would otherwise split a run against itself — Nub's label plain,
+/// the child's lines colored, because the child applies Node's order to the same two
+/// variables. The script launcher closes it by exporting `FORCE_COLOR=0` for exactly
+/// that contradictory pair; see the `ColorWhen::Auto` arm in `build_script_command`.
 pub(crate) fn color_enabled(stream_is_tty: bool) -> bool {
     match color_mode() {
         ColorWhen::Always => return true,
@@ -1531,21 +1536,27 @@ pub(crate) fn color_enabled(stream_is_tty: bool) -> bool {
         return false;
     }
     if let Some(v) = std::env::var_os("FORCE_COLOR") {
-        // Mirror Node's `getColorDepth` value table (lib/internal/tty.js): only
-        // '', '1', 'true', '2' and '3' enable color — every other value, '0' and
-        // 'false' included, falls through to its 2-color monochrome branch. The
-        // exact set matters because Nub hands `FORCE_COLOR` to the children whose
-        // output it prefixes, so a value Nub read as ON while Node read it as OFF
-        // would split the two apart. An EMPTY value is Node's shortest way to say
-        // ON, which is why it cannot be lumped in with '0'.
-        return matches!(
-            v.to_str(),
-            Some("") | Some("1") | Some("true") | Some("2") | Some("3")
-        );
+        return force_color_enables(&v);
     }
     stream_is_tty
 }
 
+/// Whether a `FORCE_COLOR` value turns color ON, per Node's `getColorDepth` table
+/// (lib/internal/tty.js): only '', '1', 'true', '2' and '3' enable — every other
+/// value, '0' and 'false' included, falls through to its 2-color monochrome branch.
+/// An EMPTY value is Node's shortest spelling of ON, which is why it cannot be
+/// lumped in with '0'.
+///
+/// Shared by [`color_enabled`] and the script launcher so the two can never drift:
+/// Nub hands this variable to the children whose output it prefixes, and a value
+/// Nub read as ON while Node read it as OFF would split the two apart.
+fn force_color_enables(v: &std::ffi::OsStr) -> bool {
+    matches!(
+        v.to_str(),
+        Some("") | Some("1") | Some("true") | Some("2") | Some("3")
+    )
+}
+
 /// `nub compile`'s power set. Grouping it under its own `--help` heading (the
 /// shape esbuild uses) is what keeps the common six flags readable while the
 /// bundler knobs stay discoverable.
@@ -5737,7 +5748,21 @@ fn build_script_command(
         ColorWhen::Never => {
             command.env("FORCE_COLOR", "0");
         }
-        ColorWhen::Auto => {}
+        // `auto` forces nothing — with one exception, which exists to stop Nub's
+        // framing and the child's own output from contradicting each other inside a
+        // single run. Nub resolves NO_COLOR over FORCE_COLOR; Node resolves them the
+        // other way. With BOTH set, Nub's prefix went plain while the child still
+        // colorized (measured: the child's `getColorDepth` returned 4 under
+        // `NO_COLOR=1 FORCE_COLOR=1`), so a run emitted colored lines inside
+        // uncolored labels. Pin the child to Nub's answer for that one contradictory
+        // pair. Neither variable set, or only one of them, still exports nothing.
+        ColorWhen::Auto => {
+            let child_would_color =
+                std::env::var_os("FORCE_COLOR").is_some_and(|v| force_color_enables(&v));
+            if child_would_color && !color_enabled(true) {
+                command.env("FORCE_COLOR", "0");
+            }
+        }
     }
 
     if let StreamMode::Prefixed = stream {
diff --git a/crates/nub-cli/tests/integration.rs b/crates/nub-cli/tests/integration.rs
index ed37d02cf..6acaefd81 100644
--- a/crates/nub-cli/tests/integration.rs
+++ b/crates/nub-cli/tests/integration.rs
@@ -4849,7 +4849,12 @@ fn no_color_is_accepted_before_and_after_the_verb() {
         let output = Command::new(nub_binary())
             .args(&args)
             .current_dir(&fixture)
+            // FORCE_COLOR=1 makes the run colored to begin with, so the assertion
+            // below can only pass because `--no-color` turned it off. Clearing
+            // NO_COLOR matters for the same reason: an ambient one would satisfy it
+            // without the flag doing anything.
             .env("FORCE_COLOR", "1")
+            .env_remove("NO_COLOR")
             .output()
             .expect("spawn nub");
         assert!(
@@ -4896,6 +4901,53 @@ fn force_color_values_follow_nodes_table() {
     }
 }
 
+/// Nub resolves `NO_COLOR` over `FORCE_COLOR`; Node resolves them the other way. With
+/// both set, that split a run against itself — Nub's label plain while the child
+/// colorized, because the child applied Node's order to the same two variables. In
+/// `auto` Nub now exports `FORCE_COLOR=0` for exactly that contradictory pair, so
+/// both halves of a line agree. The `FC=` probe reads what the child actually got.
+#[test]
+fn contradictory_color_env_does_not_split_nub_from_its_child() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let output = Command::new(nub_binary())
+        .args(["run", "-r", "--stream", "color-probe"])
+        .current_dir(&fixture)
+        .env("FORCE_COLOR", "1")
+        .env("NO_COLOR", "1")
+        .output()
+        .expect("spawn nub");
+    assert!(
+        !String::from_utf8_lossy(&output.stderr).contains('\x1b'),
+        "NO_COLOR keeps Nub's own prefix plain: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert!(
+        String::from_utf8_lossy(&output.stdout).contains("FC=0"),
+        "the child must be pinned to Nub's answer, not left to resolve the pair \
+         with Node's opposite precedence: {}",
+        String::from_utf8_lossy(&output.stdout)
+    );
+}
+
+/// The control for the case above: with only ONE of the two set there is no
+/// contradiction, so `auto` must go on forcing nothing on the child.
+#[test]
+fn auto_still_forces_nothing_when_only_no_color_is_set() {
+    let fixture = fixtures_dir().join("monorepo-deps");
+    let output = Command::new(nub_binary())
+        .args(["run", "-r", "color-probe"])
+        .current_dir(&fixture)
+        .env("NO_COLOR", "1")
+        .env_remove("FORCE_COLOR")
+        .output()
+        .expect("spawn nub");
+    assert!(
+        String::from_utf8_lossy(&output.stdout).contains("FC=unset"),
+        "NO_COLOR alone already disables the child; nothing needs forcing: {}",
+        String::from_utf8_lossy(&output.stdout)
+    );
+}
+
 #[test]
 fn ndjson_reporter_emits_valid_json_events() {
     // `--reporter=ndjson` emits one JSON object per line on stdout, covering

From fd5d532ec9ec7013e777029b2f84f59279db7656 Mon Sep 17 00:00:00 2001
From: Colin McDonnell <3084745+colinhacks@users.noreply.github.com>
Date: Sat, 15 Aug 2026 13:14:22 -0700
Subject: [PATCH 4/5] run: scope the contradictory-color repair to the prefixed
 path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-up on #744, fixing a regression the previous commit
introduced.

build_script_command is shared by every stream mode, and the auto-mode
FORCE_COLOR=0 export sat above the StreamMode::Prefixed branch, so it also
fired for inherited-stdio runs: plain `nub run <script>`, `-w`, and
`-r --sequential`. Nothing is prefixed on those paths, so the contradiction
the export exists to repair cannot arise there — and overriding the pair
diverged from everyone else. Measured under `NO_COLOR=1 FORCE_COLOR=1`:
pnpm, npm and a bare shell all hand the script FORCE_COLOR=1, while nub had
started handing it 0.

Gate the arm on StreamMode::Prefixed. A prefixed run still repairs the
split; an un-prefixed one passes both variables through untouched. An
explicit --color/--no-color is unaffected and still reaches the child in
either mode, which is what the user asked for.

Adds the missing row: a test driving the contradictory pair through the
inherited path. Also corrects the docs, which claimed nub forces nothing
without a flag — true again for every un-prefixed run, and now stated
precisely for the prefixed one.
---
 crates/nub-cli/src/cli.rs           | 21 +++++++++++++--------
 crates/nub-cli/tests/integration.rs | 22 ++++++++++++++++++++++
 site/content/docs/runner/run.mdx    |  2 ++
 3 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/crates/nub-cli/src/cli.rs b/crates/nub-cli/src/cli.rs
index 4f74786c3..5bd319367 100644
--- a/crates/nub-cli/src/cli.rs
+++ b/crates/nub-cli/src/cli.rs
@@ -5748,21 +5748,26 @@ fn build_script_command(
         ColorWhen::Never => {
             command.env("FORCE_COLOR", "0");
         }
-        // `auto` forces nothing — with one exception, which exists to stop Nub's
-        // framing and the child's own output from contradicting each other inside a
-        // single run. Nub resolves NO_COLOR over FORCE_COLOR; Node resolves them the
-        // other way. With BOTH set, Nub's prefix went plain while the child still
+        // `auto` forces nothing — with one exception, scoped to the prefixed path
+        // alone. Nub resolves NO_COLOR over FORCE_COLOR; Node resolves them the other
+        // way, so with BOTH set Nub's label went plain while the child still
         // colorized (measured: the child's `getColorDepth` returned 4 under
-        // `NO_COLOR=1 FORCE_COLOR=1`), so a run emitted colored lines inside
-        // uncolored labels. Pin the child to Nub's answer for that one contradictory
-        // pair. Neither variable set, or only one of them, still exports nothing.
-        ColorWhen::Auto => {
+        // `NO_COLOR=1 FORCE_COLOR=1`) and a run emitted colored text inside uncolored
+        // labels. Pinning the child to Nub's answer repairs that.
+        //
+        // ONLY under `StreamMode::Prefixed`, because only there does Nub pipe the
+        // child and wrap its lines — an inherited-stdio run puts nothing around the
+        // child's output, so there is no contradiction to repair and overriding the
+        // pair would just diverge from everyone else: on plain `nub run <script>`,
+        // pnpm, npm and a bare shell all hand the script `FORCE_COLOR=1` here.
+        ColorWhen::Auto if matches!(stream, StreamMode::Prefixed) => {
             let child_would_color =
                 std::env::var_os("FORCE_COLOR").is_some_and(|v| force_color_enables(&v));
             if child_would_color && !color_enabled(true) {
                 command.env("FORCE_COLOR", "0");
             }
         }
+        ColorWhen::Auto => {}
     }
 
     if let StreamMode::Prefixed = stream {
diff --git a/crates/nub-cli/tests/integration.rs b/crates/nub-cli/tests/integration.rs
index 6acaefd81..cf52a2e4b 100644
--- a/crates/nub-cli/tests/integration.rs
+++ b/crates/nub-cli/tests/integration.rs
@@ -4929,6 +4929,28 @@ fn contradictory_color_env_does_not_split_nub_from_its_child() {
     );
 }
 
+/// The scope control for the case above. Nub only wraps a child's output on the
+/// prefixed path; a plain `nub run <script>` inherits stdio and frames nothing, so
+/// there is no contradiction to repair and the script must receive the environment
+/// it was given. pnpm, npm and a bare shell all pass `FORCE_COLOR=1` straight
+/// through here, and briefly nub did not.
+#[test]
+fn an_unprefixed_run_passes_the_color_env_through_untouched() {
+    let fixture = fixtures_dir().join("monorepo-deps").join("packages/core");
+    let output = Command::new(nub_binary())
+        .args(["run", "color-probe"])
+        .current_dir(&fixture)
+        .env("FORCE_COLOR", "1")
+        .env("NO_COLOR", "1")
+        .output()
+        .expect("spawn nub");
+    assert!(
+        String::from_utf8_lossy(&output.stdout).contains("FC=1"),
+        "an inherited-stdio run must not rewrite the script's FORCE_COLOR: {}",
+        String::from_utf8_lossy(&output.stdout)
+    );
+}
+
 /// The control for the case above: with only ONE of the two set there is no
 /// contradiction, so `auto` must go on forcing nothing on the child.
 #[test]
diff --git a/site/content/docs/runner/run.mdx b/site/content/docs/runner/run.mdx
index 6424238de..03090e29b 100644
--- a/site/content/docs/runner/run.mdx
+++ b/site/content/docs/runner/run.mdx
@@ -386,6 +386,8 @@ NO_COLOR=1 nub run -r build      # off, whatever the terminal says
 FORCE_COLOR=1 nub run -r build   # on, even when the output is piped
 ```
 
+Setting both is contradictory, and the two variables disagree about which should win: Nub honors `NO_COLOR`, Node honors `FORCE_COLOR`. On a prefixed run Nub settles it for the scripts as well, so the labels and the lines they wrap can't end up disagreeing. A run that isn't prefixed passes both through untouched.
+
 ## `--node`
 
 By default, the `nub` executable is aliased as `node` for the duration of a `nub run` call, so any subprocess that spawns `node` (a script shebang, `child_process.spawn("node", …)`) gets Nub's augmentation too. Pass `--node` to turn that off for one invocation — see [the runtime overview](/docs/runtime#--node) for the full contract.

From d0d7b7bd692a7bd82d9b8bb59a8fde2c88d198ac Mon Sep 17 00:00:00 2001
From: Colin McDonnell <3084745+colinhacks@users.noreply.github.com>
Date: Sat, 15 Aug 2026 17:51:43 -0700
Subject: [PATCH 5/5] run: keep the parser's rejection wording out of --help

The --no-color doc comment quoted the phrase clap prints when it refuses an
argument, to explain what the flag fixes. clap renders a doc comment into
--help, and the arg is global, so that sentence appeared in EVERY
subcommand's help page.

cli_grammar_parity decides whether a form was refused by spawning
`nub <form> --help` and grepping the output for exactly that wording. With
the phrase now sitting in every help page, all three of its suites read
every documented pnpm form as rejected: `nub install -D`, `-r`, `--filter`,
the whole table. Six Test jobs went red across both platforms.

Demote the rationale to a plain comment, which clap never renders, and
leave a one-line doc comment as the help text. No behavior change; the
grammar suites pass again.
---
 crates/nub-cli/src/cli.rs | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/crates/nub-cli/src/cli.rs b/crates/nub-cli/src/cli.rs
index 5bd319367..107da93d3 100644
--- a/crates/nub-cli/src/cli.rs
+++ b/crates/nub-cli/src/cli.rs
@@ -741,12 +741,17 @@ pub struct Cli {
     #[arg(long, global = true, default_value = "auto", default_missing_value = "always", num_args = 0..=1, require_equals = true)]
     pub color: ColorWhen,
 
+    // Declared to clap as well as caught by the pre-subcommand argv scan, because
+    // pnpm accepts it in BOTH positions and the scan only sees tokens before the
+    // verb: without this, `nub run -r --no-color build` was refused by the parser
+    // while the pre-verb spelling worked.
+    //
+    // Kept as a plain comment, NOT a doc comment: clap renders a doc comment into
+    // `--help`, and a `global` arg's text lands in EVERY subcommand's help — where
+    // `cli_grammar_parity` greps for the parser's rejection wording to decide
+    // whether a form was refused. Quoting that wording here made every probe in
+    // that suite read as a rejection.
     /// Disable color. The pnpm-compatible spelling of `--color=never`.
-    ///
-    /// Declared to clap as well as caught by the pre-subcommand argv scan, because
-    /// pnpm accepts it in BOTH positions and the scan only sees tokens before the
-    /// verb: without this, `nub run -r --no-color build` exited 2 with `unexpected
-    /// argument` while the pre-verb spelling worked.
     #[arg(long = "no-color", global = true, conflicts_with = "color")]
     pub no_color: bool,