Skip to content

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

fix(trace): route every command spawn through one CommandTrace chokepoint (#3134)

Maximilian Roos9dcf41f437eb
diff --git a/CLAUDE.md b/CLAUDE.md
index 36b9b4580..479b776d4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -65,13 +65,15 @@ Full inventory: FAQ [What files does Worktrunk create?](docs/content/faq.md#what
### All Commands Through `shell_exec::Cmd`
-Every external command goes through `shell_exec::Cmd` for consistent debug logging (`$ git status [worktree-name]`) and `[wt-trace]` timing. Never call `cmd.output()` directly. For git, prefer `Repository::run_command()` (wraps `Cmd` with worktree context). Pipe stdin via `.stdin_bytes(...)`. The `[wt-trace]` grammar is owned by `src/trace/emit.rs` — emit new trace records through that module, not ad-hoc `log::debug!("[wt-trace] …")` strings.
+Every external command goes through `shell_exec::Cmd` for consistent debug logging (`$ git status [worktree-name]`) and `[wt-trace]` timing. Never call `cmd.output()` directly. For git, prefer `Repository::run_command()` (wraps `Cmd` with worktree context). `Cmd` has four execution modes — `run` (capture), `stream` (inherit stdio), `delayed_stream` (buffer then stream to stderr, for slow ops like `git worktree add`), and `pipe_into` (two-stage pipe). Pipe stdin via `.stdin_bytes(...)`.
```rust
Cmd::new("git").args(["status", "--porcelain"]).current_dir(&wt).context("worktree-name").run()?;
Cmd::new("gh").args(["pr", "list"]).run()?; // no context for standalone tools
```
+**The `[wt-trace]` command record has one emitter: `CommandTrace` in `src/trace/emit.rs`.** The grammar lives there too (don't hand-write `log::debug!("[wt-trace] …")`). `CommandTrace::{complete,fail}` are the only callers of the private `command_completed`/`command_errored` writers, so a subprocess is either traced through the guard or produces no command record. Most spawns get this for free via `Cmd`. A few spawn sites have I/O shapes `Cmd` can't model and construct a `CommandTrace` directly: the concurrent-command runner (`output/concurrent.rs`), pipeline steps (`commands/run_pipeline.rs`), `wt step tether`, and the fsmonitor daemon launch. **Any new spawn site that runs an in-process command must construct a `CommandTrace` (start it just before spawn; `complete(success)` after wait, `fail(err)` on spawn/wait error)** — otherwise the command shows up as an unattributed gap in `wt-perf timeline`. The guard is `#[must_use]` and trips a debug-build assertion if dropped unresolved, so a forgotten `complete`/`fail` fails tests rather than silently going untraced. Detached background children (`commands/process.rs`) and interactive helpers (pagers, shell probes) are intentionally untraced — they outlive the invocation or aren't part of its timeline.
+
### Real-time Output Streaming
Stream command output line-by-line rather than buffering. Responsiveness is a priority.
diff --git a/src/commands/custom.rs b/src/commands/custom.rs
index 31aeb84b4..4e2fe3166 100644
--- a/src/commands/custom.rs
+++ b/src/commands/custom.rs
@@ -30,6 +30,7 @@ use std::process::Command;
use anyhow::{Context, Result};
use worktrunk::git::WorktrunkError;
+use worktrunk::trace::CommandTrace;
use crate::cli::build_command;
use crate::commands::{
@@ -133,9 +134,17 @@ fn run_custom(path: &Path, args: &[OsString], working_dir: Option<&Path>) -> Res
cmd.current_dir(dir);
}
- let status = cmd
- .status()
- .with_context(|| format!("failed to execute {}", path.display()))?;
+ let mut trace = CommandTrace::new(None, &path.display().to_string());
+ let status = match cmd.status() {
+ Ok(status) => {
+ trace.complete(status.success());
+ status
+ }
+ Err(e) => {
+ trace.fail(&e);
+ return Err(e).with_context(|| format!("failed to execute {}", path.display()));
+ }
+ };
if status.success() {
return Ok(());
@@ -255,4 +264,16 @@ mod tests {
other => panic!("unexpected WorktrunkError variant: {other:?}"),
}
}
+
+ #[test]
+ fn run_custom_spawn_failure_resolves_trace() {
+ // A non-existent binary fails at spawn, exercising the `trace.fail` arm
+ // (the success path is covered by the signal test above).
+ let err = run_custom(Path::new("/no/such/wt-custom-7f3a9b2c"), &[], None)
+ .expect_err("spawning a missing binary should fail");
+ assert!(
+ err.to_string().contains("failed to execute"),
+ "expected spawn-failure context, got: {err}"
+ );
+ }
}
diff --git a/src/commands/run_pipeline.rs b/src/commands/run_pipeline.rs
index 614e34949..a7d1bd711 100644
--- a/src/commands/run_pipeline.rs
+++ b/src/commands/run_pipeline.rs
@@ -63,6 +63,7 @@ use anyhow::Context;
use worktrunk::git::{Repository, WorktrunkError};
use worktrunk::shell_exec::ShellConfig;
+use worktrunk::trace::CommandTrace;
use super::command_executor::{expand_shell_template, wait_first_error};
use super::pipeline_spec::{PipelineSpec, PipelineStepSpec};
@@ -107,9 +108,9 @@ pub fn run_pipeline() -> anyhow::Result<()> {
let expanded = expand_shell_template(template, &step_ctx, &repo, template_name)?;
let step_json = serde_json::to_string(&*step_ctx)
.context("failed to serialize step context")?;
- let mut child =
+ let (mut child, mut trace) =
spawn_shell_command(&expanded, &spec.worktree_path, &step_json, log_file)?;
- let status = child.wait().context("failed to wait for child process")?;
+ let status = wait_resolving(&mut child, &mut trace, &expanded)?;
if !status.success() {
return Err(failure_error(&status, name.as_deref().unwrap_or(&expanded)));
}
@@ -153,19 +154,28 @@ fn spawn_shell_command(
worktree_path: &Path,
context_json: &str,
log_file: fs::File,
-) -> anyhow::Result<Child> {
+) -> anyhow::Result<(Child, CommandTrace)> {
let shell = ShellConfig::get()?;
let log_err = log_file
.try_clone()
.context("failed to clone log file handle")?;
- let mut child = shell
+ // Start the trace just before spawning; the caller resolves it once the
+ // child is waited on (see `wait_resolving`).
+ let mut trace = CommandTrace::new(None, expanded);
+ let mut child = match shell
.command(expanded)
.current_dir(worktree_path)
.stdin(Stdio::piped())
.stdout(Stdio::from(log_file))
.stderr(Stdio::from(log_err))
.spawn()
- .with_context(|| format!("failed to spawn: {expanded}"))?;
+ {
+ Ok(child) => child,
+ Err(e) => {
+ trace.fail(&e);
+ return Err(e).with_context(|| format!("failed to spawn: {expanded}"));
+ }
+ };
// Write context JSON to stdin, then drop to close the pipe.
if let Some(mut stdin) = child.stdin.take() {
@@ -174,7 +184,27 @@ fn spawn_shell_command(
let _ = stdin.write_all(context_json.as_bytes());
}
- Ok(child)
+ Ok((child, trace))
+}
+
+/// Wait for a pipeline child, resolving its [`CommandTrace`], and surface a
+/// wait-IO failure with context. Returns the child's exit status; the caller
+/// decides whether a non-zero status is a pipeline failure.
+fn wait_resolving(
+ child: &mut Child,
+ trace: &mut CommandTrace,
+ expanded: &str,
+) -> anyhow::Result<ExitStatus> {
+ match child.wait() {
+ Ok(status) => {
+ trace.complete(status.success());
+ Ok(status)
+ }
+ Err(e) => {
+ trace.fail(&e);
+ Err(e).with_context(|| format!("failed to wait for: {expanded}"))
+ }
+ }
}
/// Spawn all commands in a concurrent group, then wait for all.
@@ -195,38 +225,53 @@ fn run_concurrent_group(
cmd_index: &mut usize,
) -> anyhow::Result<()> {
let serial = super::force_serial_concurrent();
- let mut children = Vec::with_capacity(if serial { 0 } else { commands.len() });
+ let mut children: Vec<(Option<String>, String, Child, CommandTrace)> =
+ Vec::with_capacity(if serial { 0 } else { commands.len() });
- for cmd in commands {
- let log_name = command_log_name(cmd.name.as_deref(), *cmd_index);
- let log_file = create_command_log(spec, &log_name)?;
- let cmd_ctx = step_context(&spec.context, cmd.name.as_deref());
- let expanded = expand_shell_template(&cmd.template, &cmd_ctx, repo, &cmd.template_name)?;
- let cmd_json =
- serde_json::to_string(&*cmd_ctx).context("failed to serialize step context")?;
- let mut child = spawn_shell_command(&expanded, &spec.worktree_path, &cmd_json, log_file)?;
- *cmd_index += 1;
+ // Spawn (and, in serial mode, run) each command. Wrapped so that a mid-loop
+ // error — a setup `?` or a spawn failure for a later command — tears down
+ // the children already spawned this group rather than dropping them with
+ // unresolved trace guards (and as unreaped orphans).
+ let spawn_result = (|| -> anyhow::Result<()> {
+ for cmd in commands {
+ let log_name = command_log_name(cmd.name.as_deref(), *cmd_index);
+ let log_file = create_command_log(spec, &log_name)?;
+ let cmd_ctx = step_context(&spec.context, cmd.name.as_deref());
+ let expanded =
+ expand_shell_template(&cmd.template, &cmd_ctx, repo, &cmd.template_name)?;
+ let cmd_json =
+ serde_json::to_string(&*cmd_ctx).context("failed to serialize step context")?;
+ let (mut child, mut trace) =
+ spawn_shell_command(&expanded, &spec.worktree_path, &cmd_json, log_file)?;
+ *cmd_index += 1;
- if serial {
- let status = child
- .wait()
- .with_context(|| format!("failed to wait for: {expanded}"))?;
- if !status.success() {
- return Err(failure_error(
- &status,
- cmd.name.as_deref().unwrap_or(&expanded),
- ));
+ if serial {
+ let status = wait_resolving(&mut child, &mut trace, &expanded)?;
+ if !status.success() {
+ return Err(failure_error(
+ &status,
+ cmd.name.as_deref().unwrap_or(&expanded),
+ ));
+ }
+ } else {
+ children.push((cmd.name.clone(), expanded, child, trace));
}
- } else {
- children.push((cmd.name.clone(), expanded, child));
}
+ Ok(())
+ })();
+
+ if let Err(e) = spawn_result {
+ for (_, _, mut child, mut trace) in children {
+ let _ = child.kill();
+ let _ = child.wait();
+ trace.complete(false);
+ }
+ return Err(e);
}
wait_first_error(children.into_iter().map(
- |(name, expanded, mut child)| -> anyhow::Result<()> {
- let status = child
- .wait()
- .with_context(|| format!("failed to wait for: {expanded}"))?;
+ |(name, expanded, mut child, mut trace)| -> anyhow::Result<()> {
+ let status = wait_resolving(&mut child, &mut trace, &expanded)?;
if !status.success() {
return Err(failure_error(&status, name.as_deref().unwrap_or(&expanded)));
}
diff --git a/src/commands/step/tether.rs b/src/commands/step/tether.rs
index a9dfe994a..f184e56ef 100644
--- a/src/commands/step/tether.rs
+++ b/src/commands/step/tether.rs
@@ -30,6 +30,7 @@ use std::path::Path;
use std::time::Duration;
use anyhow::{Context, Result};
+use worktrunk::trace::CommandTrace;
/// How often the reaper re-checks whether the worktree still exists. Teardown
/// of an already-orphaned server within this bound is imperceptible next to a
@@ -52,9 +53,14 @@ pub(crate) fn step_tether(command: &[String]) -> Result<()> {
// shell's cd/exec directive files.
worktrunk::shell_exec::scrub_directive_env_vars(&mut cmd);
set_new_process_group(&mut cmd);
- let mut child = cmd
- .spawn()
- .with_context(|| format!("spawn tethered command: {}", command[0]))?;
+ let mut trace = CommandTrace::new(None, &command.join(" "));
+ let mut child = match cmd.spawn() {
+ Ok(child) => child,
+ Err(e) => {
+ trace.fail(&e);
+ return Err(e).with_context(|| format!("spawn tethered command: {}", command[0]));
+ }
+ };
let id = child.id();
// Reaper: polls until the worktree is gone, then kills the tree so the
@@ -71,7 +77,10 @@ pub(crate) fn step_tether(command: &[String]) -> Result<()> {
}
// Block until the child exits — killed by the reaper, or on its own.
- let _ = child.wait();
+ match child.wait() {
+ Ok(status) => trace.complete(status.success()),
+ Err(e) => trace.fail(&e),
+ }
// Final sweep: on a self-exit, descendants may still be running (Unix:
// reparented but in this pgid; Windows: while the tree is intact). On a
@@ -137,3 +146,22 @@ fn kill_process_tree(pid: u32) {
.stderr(std::process::Stdio::null())
.status();
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn step_tether_spawn_failure_resolves_trace() {
+ // A non-existent program fails at spawn, before the reaper thread is
+ // started — exercising the `trace.fail` arm. (The success path, where
+ // the child runs and is reaped, is covered by the `step_tether`
+ // integration tests.)
+ let err = step_tether(&["worktrunk-nonexistent-binary-7f3a9b2c".to_string()])
+ .expect_err("spawning a missing binary should fail");
+ assert!(
+ err.to_string().contains("spawn tethered command"),
+ "expected spawn-failure context, got: {err}"
+ );
+ }
+}
diff --git a/src/git/error.rs b/src/git/error.rs
index 0a94abd48..16e625ec5 100644
--- a/src/git/error.rs
+++ b/src/git/error.rs
@@ -194,10 +194,10 @@ pub struct FailedCommand {
///
/// `Display` is intentionally a single-line summary — `format_with_gutter`
/// in `print_command_error` renders [`Self::combined_output`] separately for
-/// the multi-line body. The streaming path (`run_command_delayed_stream`)
-/// uses a sibling crate-private `StreamCommandError` for the same role,
-/// where stdout/stderr are interleaved and a string body is the most we can
-/// recover.
+/// the multi-line body. The delayed-stream path (`Cmd::delayed_stream`) uses
+/// [`StreamCommandError`](crate::shell_exec::StreamCommandError) for the same
+/// role, where stdout/stderr are interleaved and a string body is the most we
+/// can recover.
#[derive(Debug, Clone)]
pub struct CommandError {
/// Program name, e.g., `"git"`.
diff --git a/src/git/repository/mod.rs b/src/git/repository/mod.rs
index ba66e00a1..47573d0df 100644
--- a/src/git/repository/mod.rs
+++ b/src/git/repository/mod.rs
@@ -82,20 +82,15 @@
//! The picker also maintains a `PreviewCache` (`Arc<DashMap>` in `commands/picker/items.rs`)
//! for rendered preview output, scoped to a single picker session.
-use std::io::{BufRead, BufReader, Write};
use std::path::{Path, PathBuf};
use std::process::Stdio;
-use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::{Arc, LazyLock, Mutex, OnceLock};
-use std::thread;
-use std::time::{Duration, Instant};
+use std::sync::{Arc, LazyLock, OnceLock};
use crate::shell_exec::Cmd;
use color_print::cformat;
use dashmap::DashMap;
use once_cell::sync::OnceCell;
-use wait_timeout::ChildExt;
use anyhow::{Context, bail};
use dunce::canonicalize;
@@ -131,52 +126,6 @@ pub use ref_snapshot::RefSnapshot;
pub(super) use working_tree::path_to_logging_context;
pub use working_tree::{TempIndex, WorkingTree};
-/// Structured error from [`Repository::run_command_delayed_stream`].
-///
-/// Separates command output from command identity so callers can format
-/// each part with appropriate styling (e.g., bold command, gray exit code).
-#[derive(Debug)]
-pub(crate) struct StreamCommandError {
- /// Lines of output from the command (may be empty)
- pub output: String,
- /// The command string, e.g., "git worktree add /path -b fix main"
- pub command: String,
- /// Exit information, e.g., "exit code 255" or "killed by signal"
- pub exit_info: String,
-}
-
-impl std::fmt::Display for StreamCommandError {
- fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
- // Callers use Repository::extract_failed_command() to access fields directly.
- // This Display impl exists only to satisfy the Error trait bound.
- write!(f, "{}", self.output)
- }
-}
-
-impl std::error::Error for StreamCommandError {}
-
-/// Convert a child exit status into `Ok(())` or a [`StreamCommandError`].
-fn stream_exit_result(
- status: std::process::ExitStatus,
- buffer: &Arc<Mutex<Vec<String>>>,
- cmd_str: &str,
-) -> anyhow::Result<()> {
- if status.success() {
- return Ok(());
- }
- let lines = buffer.lock().unwrap();
- let exit_info = status
- .code()
- .map(|c| format!("exit code {c}"))
- .unwrap_or_else(|| "killed by signal".to_string());
- Err(StreamCommandError {
- output: lines.join("\n"),
- command: cmd_str.to_string(),
- exit_info,
- }
- .into())
-}
-
// ============================================================================
// Repository Cache
// ============================================================================
@@ -1230,7 +1179,9 @@ impl Repository {
/// indefinitely. `read_to_end()` in `Command::output()` then blocks forever
/// waiting for EOF that never comes.
pub fn start_fsmonitor_daemon_at(&self, path: &Path) {
- log::debug!("$ git fsmonitor--daemon start [{}]", path.display());
+ let context = path_to_logging_context(path);
+ let cmd_str = "git fsmonitor--daemon start";
+ log::debug!("$ {cmd_str} [{context}]");
let mut cmd = std::process::Command::new("git");
cmd.args(["fsmonitor--daemon", "start"])
.current_dir(path)
@@ -1238,15 +1189,22 @@ impl Repository {
.stdout(Stdio::null())
.stderr(Stdio::null());
crate::shell_exec::scrub_directive_env_vars(&mut cmd);
+ // Trace the daemon launch so it's attributed in the timeline rather than
+ // appearing as a gap on the switch hot path. Uses `status()` (not
+ // `Cmd::run`) deliberately — see the doc comment.
+ let mut trace = crate::trace::CommandTrace::new(Some(&context), cmd_str);
let result = cmd.status();
match result {
- Ok(status) if !status.success() => {
- log::debug!("fsmonitor daemon start exited {status} (usually fine)");
+ Ok(status) => {
+ trace.complete(status.success());
+ if !status.success() {
+ log::debug!("fsmonitor daemon start exited {status} (usually fine)");
+ }
}
Err(e) => {
+ trace.fail(&e);
log::debug!("fsmonitor daemon start failed (usually fine): {e}");
}
- _ => {}
}
}
@@ -1394,122 +1352,23 @@ impl Repository {
/// Run a git command with delayed output streaming.
///
- /// Buffers output initially, then streams if the command takes longer than
- /// `delay_ms`. This provides a quiet experience for fast operations while
- /// still showing progress for slow ones (like `worktree add` on large repos).
- /// Pass `-1` to never switch to streaming (always buffer).
- ///
- /// If `progress_message` is provided, it will be printed to stderr when
- /// streaming starts (i.e., when the delay threshold is exceeded).
- ///
- /// All output (both stdout and stderr from the child) is sent to stderr
- /// to keep stdout clean for commands like `wt switch`.
+ /// Thin wrapper over [`Cmd::delayed_stream`](crate::shell_exec::Cmd::delayed_stream):
+ /// buffers output initially, then streams to stderr if the command takes
+ /// longer than `delay_ms` (quiet for fast operations, progress for slow
+ /// ones like `worktree add` on large repos). Routing through `Cmd` is what
+ /// gives the command its `[wt-trace]` record and directive scrubbing — see
+ /// that method for the full contract.
pub fn run_command_delayed_stream(
&self,
args: &[&str],
delay_ms: i64,
progress_message: Option<String>,
) -> anyhow::Result<()> {
- // Allow tests to override delay threshold (-1 to disable, 0 for immediate)
- let delay_ms = std::env::var("WORKTRUNK_TEST_DELAYED_STREAM_MS")
- .ok()
- .and_then(|s| s.parse().ok())
- .unwrap_or(delay_ms);
-
- let cmd_str = format!("git {}", args.join(" "));
- log::debug!(
- "$ {} [{}] (delayed stream, {}ms)",
- cmd_str,
- self.logging_context(),
- delay_ms
- );
-
- let mut cmd = std::process::Command::new("git");
- cmd.args(args)
+ Cmd::new("git")
+ .args(args.iter().copied())
.current_dir(&self.discovery_path)
- .stdin(Stdio::null())
- .stdout(Stdio::piped())
- .stderr(Stdio::piped());
- crate::shell_exec::scrub_directive_env_vars(&mut cmd);
- let mut child = cmd
- .spawn()
- .with_context(|| format!("Failed to spawn: {}", cmd_str))?;
-
- let stdout = child.stdout.take().expect("stdout was piped");
- let stderr = child.stderr.take().expect("stderr was piped");
-
- // Shared state: when true, output streams directly; when false, buffers
- let streaming = Arc::new(AtomicBool::new(false));
- let buffer = Arc::new(Mutex::new(Vec::new()));
-
- // Reader threads for stdout and stderr (both go to stderr)
- let stdout_handle = {
- let streaming = streaming.clone();
- let buffer = buffer.clone();
- thread::spawn(move || {
- let reader = BufReader::new(stdout);
- for line in reader.lines().map_while(Result::ok) {
- if streaming.load(Ordering::Relaxed) {
- let _ = writeln!(std::io::stderr(), "{}", line);
- let _ = std::io::stderr().flush();
- } else {
- buffer.lock().unwrap().push(line);
- }
- }
- })
- };
-
- let stderr_handle = {
- let streaming = streaming.clone();
- let buffer = buffer.clone();
- thread::spawn(move || {
- let reader = BufReader::new(stderr);
- for line in reader.lines().map_while(Result::ok) {
- if streaming.load(Ordering::Relaxed) {
- let _ = writeln!(std::io::stderr(), "{}", line);
- let _ = std::io::stderr().flush();
- } else {
- buffer.lock().unwrap().push(line);
- }
- }
- })
- };
-
- let start = Instant::now();
-
- // Phase 1: If delay threshold is enabled, wait that long for the child to
- // exit. If it finishes before the threshold, output stays buffered (quiet).
- if delay_ms >= 0 {
- let delay = Duration::from_millis(delay_ms as u64);
- let remaining = delay.saturating_sub(start.elapsed());
-
- // Zero delay means "stream immediately", not "try a zero-timeout reap".
- if !remaining.is_zero()
- && let Some(status) = child
- .wait_timeout(remaining)
- .context("Failed to wait for command")?
- {
- let _ = stdout_handle.join();
- let _ = stderr_handle.join();
- return stream_exit_result(status, &buffer, &cmd_str);
- }
-
- // Delay threshold exceeded — switch to streaming
- streaming.store(true, Ordering::Relaxed);
- if let Some(ref msg) = progress_message {
- let _ = writeln!(std::io::stderr(), "{}", msg);
- }
- for line in buffer.lock().unwrap().drain(..) {
- let _ = writeln!(std::io::stderr(), "{}", line);
- }
- let _ = std::io::stderr().flush();
- }
-
- // Phase 2: Block until the child exits (no polling).
- let status = child.wait().context("Failed to wait for command")?;
- let _ = stdout_handle.join();
- let _ = stderr_handle.join();
- stream_exit_result(status, &buffer, &cmd_str)
+ .context(self.logging_context())
+ .delayed_stream(delay_ms, progress_message)
}
/// Run a git command and return the raw Output (for inspecting exit codes).
@@ -1528,14 +1387,14 @@ impl Repository {
/// Extract structured failure info from a command-runner error.
///
/// Returns `(output, Some(FailedCommand))` when the chain carries
- /// either a `StreamCommandError` (from `run_command_delayed_stream`)
- /// or a [`super::error::CommandError`] (from `run_command` /
- /// `WorkingTree::run_command`). Falls back to `(error_string, None)`
- /// for other error types (e.g., spawn failures).
+ /// either a [`StreamCommandError`](crate::shell_exec::StreamCommandError)
+ /// (from `run_command_delayed_stream`) or a [`super::error::CommandError`]
+ /// (from `run_command` / `WorkingTree::run_command`). Falls back to
+ /// `(error_string, None)` for other error types (e.g., spawn failures).
pub fn extract_failed_command(
err: &anyhow::Error,
) -> (String, Option<super::error::FailedCommand>) {
- if let Some(e) = err.downcast_ref::<StreamCommandError>() {
+ if let Some(e) = err.downcast_ref::<crate::shell_exec::StreamCommandError>() {
return (
e.output.clone(),
Some(super::error::FailedCommand {
diff --git a/src/git/repository/tests.rs b/src/git/repository/tests.rs
index c42caf181..79486a863 100644
--- a/src/git/repository/tests.rs
+++ b/src/git/repository/tests.rs
@@ -581,7 +581,7 @@ fn worktree_config_enabled_detects_extension() {
#[test]
fn extract_failed_command_from_stream_error() {
- use super::StreamCommandError;
+ use crate::shell_exec::StreamCommandError;
let err: anyhow::Error = StreamCommandError {
output: "fatal: ref exists".into(),
diff --git a/src/output/concurrent.rs b/src/output/concurrent.rs
index a84bf4bc9..cfa27fa66 100644
--- a/src/output/concurrent.rs
+++ b/src/output/concurrent.rs
@@ -52,6 +52,7 @@ use worktrunk::shell_exec::{
#[cfg(unix)]
use worktrunk::signal_forwarder::ForegroundSignals;
use worktrunk::styling::stderr;
+use worktrunk::trace::CommandTrace;
use super::handlers::DirectivePassthrough;
@@ -109,6 +110,9 @@ pub fn run_concurrent_commands(
for mut prior in children {
let _ = prior.child.kill();
let _ = prior.child.wait();
+ // Spawned but torn down because a sibling failed to spawn —
+ // record it rather than leaving the trace guard unresolved.
+ prior.trace.complete(false);
}
return Err(e);
}
@@ -270,6 +274,10 @@ struct SpawnedChild {
cmd_str: String,
log_label: Option<String>,
started_at: Instant,
+ /// `[wt-trace]` record for this child, captured at spawn time and resolved
+ /// in `collect_outcome`. Held across the output-draining window so the
+ /// recorded duration is the full spawn → wait span, not just the wait.
+ trace: CommandTrace,
}
fn spawn_child(
@@ -308,9 +316,17 @@ fn spawn_child(
shell.name
);
- let mut child = command
- .spawn()
- .with_context(|| format!("failed to spawn concurrent command '{}'", cmd.label))?;
+ // Start the trace just before spawning so its duration brackets the real
+ // spawn → wait span (the child keeps running while we drain its output).
+ let mut trace = CommandTrace::new(None, cmd.expanded);
+ let mut child = match command.spawn() {
+ Ok(child) => child,
+ Err(e) => {
+ trace.fail(&e);
+ return Err(e)
+ .with_context(|| format!("failed to spawn concurrent command '{}'", cmd.label));
+ }
+ };
if let Some(mut stdin) = child.stdin.take() {
// Ignore BrokenPipe — child may exit or close stdin early.
@@ -322,6 +338,7 @@ fn spawn_child(
cmd_str: cmd.expanded.to_string(),
log_label: cmd.log_label.map(str::to_string),
started_at: Instant::now(),
+ trace,
})
}
@@ -378,11 +395,18 @@ fn collect_outcome(spawned: SpawnedChild, cmd: &ConcurrentCommand<'_>) -> anyhow
cmd_str,
log_label,
started_at,
+ mut trace,
} = spawned;
- let status = child
- .wait()
- .with_context(|| format!("failed to wait for concurrent command '{}'", cmd.label))?;
+ let status = match child.wait() {
+ Ok(status) => status,
+ Err(e) => {
+ trace.fail(&e);
+ return Err(e)
+ .with_context(|| format!("failed to wait for concurrent command '{}'", cmd.label));
+ }
+ };
+ trace.complete(status.success());
let duration = started_at.elapsed();
let exit_code = status.code();
diff --git a/src/shell_exec.rs b/src/shell_exec.rs
index 337921a3a..53bd1d5ec 100644
--- a/src/shell_exec.rs
+++ b/src/shell_exec.rs
@@ -42,16 +42,19 @@
use std::ffi::{OsStr, OsString};
use std::fs::Metadata;
-use std::io::{ErrorKind, Read, Write};
+use std::io::{BufRead, BufReader, ErrorKind, Read, Write};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
-use std::sync::OnceLock;
-use std::time::Instant;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::{Duration, Instant};
+use anyhow::Context;
use wait_timeout::ChildExt;
use crate::git::{GitError, WorktrunkError};
use crate::sync::Semaphore;
+use crate::trace::CommandTrace;
/// Semaphore to limit concurrent command execution.
/// Prevents resource exhaustion when spawning many parallel git commands.
@@ -455,7 +458,6 @@ pub fn shell_escape_for(mode: ShellEscapeMode, s: &str) -> String {
// ============================================================================
use std::cell::Cell;
-use std::time::Duration;
thread_local! {
/// Thread-local command timeout. When set, all commands executed via `run()` on this
@@ -747,75 +749,95 @@ impl ExternalCommandLog {
}
}
-/// Per-subprocess `[wt-trace]` recorder used by `Cmd::run`, `Cmd::pipe_into`,
-/// and `Cmd::stream`.
+/// Resolve a [`CommandTrace`] from a finished `run`/`pipe_into` invocation and
+/// surface the captured stdout/stderr to the debug log.
///
-/// Captures `ts`/`tid`/`started_at` at construction; callers invoke
-/// `completed` / `errored` at each exit point. `record_result` is a
-/// convenience wrapper used by `run`/`pipe_into` (which have a single
-/// `Result<Output>` exit each, plus captured stdout/stderr to surface).
-/// `stream` has multiple exit points and uses the lower-level methods.
-struct WtTraceLog<'a> {
- context: Option<&'a str>,
- cmd_str: &'a str,
- started_at: Instant,
- ts: u64,
- tid: u64,
-}
-
-impl<'a> WtTraceLog<'a> {
- fn new(context: Option<&'a str>, cmd_str: &'a str) -> Self {
- let started_at = Instant::now();
- let ts = started_at
- .duration_since(crate::trace::emit::trace_epoch())
- .as_micros() as u64;
- let tid = crate::trace::emit::thread_id();
- Self {
- context,
- cmd_str,
- started_at,
- ts,
- tid,
+/// The buffered counterpart to calling `complete`/`fail` directly: `run` and
+/// `pipe_into` capture output, so on success they also feed it to
+/// [`log_output`]. `stream`/`delayed_stream` inherit or stream stdio and resolve
+/// their `CommandTrace` directly at each exit point.
+fn record_captured(trace: &mut CommandTrace, result: &std::io::Result<std::process::Output>) {
+ match result {
+ Ok(output) => {
+ trace.complete(output.status.success());
+ log_output(output);
}
+ Err(e) => trace.fail(e),
}
+}
- fn completed(&self, success: bool) {
- let dur_us = self.started_at.elapsed().as_micros() as u64;
- crate::trace::emit::command_completed(
- self.context,
- self.cmd_str,
- self.ts,
- self.tid,
- dur_us,
- success,
- );
- }
+/// Structured error from [`Cmd::delayed_stream`].
+///
+/// Separates command output from command identity so callers can format each
+/// part with appropriate styling (e.g., bold command, gray exit code). The
+/// streaming counterpart to [`crate::git::CommandError`]: the delayed-stream
+/// path interleaves stdout/stderr into a single buffer, so a string body is
+/// the most it can recover. `Repository::extract_failed_command` downcasts
+/// this to render git's failure to the user.
+#[derive(Debug)]
+pub struct StreamCommandError {
+ /// Lines of output from the command (may be empty).
+ pub output: String,
+ /// The command string, e.g., "git worktree add /path -b fix main".
+ pub command: String,
+ /// Exit information, e.g., "exit code 255" or "killed by signal".
+ pub exit_info: String,
+}
- fn errored(&self, err: impl std::fmt::Display) {
- let dur_us = self.started_at.elapsed().as_micros() as u64;
- crate::trace::emit::command_errored(
- self.context,
- self.cmd_str,
- self.ts,
- self.tid,
- dur_us,
- err,
- );
+impl std::fmt::Display for StreamCommandError {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ // Callers use Repository::extract_failed_command() to access fields
+ // directly. This Display impl exists only to satisfy the Error trait
+ // bound.
+ write!(f, "{}", self.output)
}
+}
+
+impl std::error::Error for StreamCommandError {}
+
+/// Convert a finished child's exit status into `Ok(())` or a
+/// [`StreamCommandError`] carrying the buffered output.
+fn stream_exit_result(
+ status: std::process::ExitStatus,
+ buffer: &Arc<Mutex<Vec<String>>>,
+ cmd_str: &str,
+) -> anyhow::Result<()> {
+ if status.success() {
+ return Ok(());
+ }
+ let lines = buffer.lock().unwrap();
+ let exit_info = status
+ .code()
+ .map(|c| format!("exit code {c}"))
+ .unwrap_or_else(|| "killed by signal".to_string());
+ Err(StreamCommandError {
+ output: lines.join("\n"),
+ command: cmd_str.to_string(),
+ exit_info,
+ }
+ .into())
+}
- /// Emit a trace record for a finished `run`/`pipe_into` invocation and
- /// surface the captured stdout/stderr to the debug log. `stream` doesn't
- /// capture output (it inherits stdio), so it uses `completed`/`errored`
- /// directly.
- fn record_result(&self, result: &std::io::Result<std::process::Output>) {
- match result {
- Ok(output) => {
- self.completed(output.status.success());
- log_output(output);
+/// Spawn a reader thread for [`Cmd::delayed_stream`]: each line is written to
+/// stderr live once `streaming` is set, or buffered (for the quiet-fast and
+/// pre-threshold cases) until then. Both the child's stdout and stderr use
+/// this; everything routes to stderr to keep our stdout clean.
+fn spawn_delayed_reader<R: Read + Send + 'static>(
+ stream: R,
+ streaming: Arc<AtomicBool>,
+ buffer: Arc<Mutex<Vec<String>>>,
+) -> std::thread::JoinHandle<()> {
+ std::thread::spawn(move || {
+ let reader = BufReader::new(stream);
+ for line in reader.lines().map_while(Result::ok) {
+ if streaming.load(Ordering::Relaxed) {
+ let _ = writeln!(std::io::stderr(), "{}", line);
+ let _ = std::io::stderr().flush();
+ } else {
+ buffer.lock().unwrap().push(line);
}
- Err(e) => self.errored(e),
}
- }
+ })
}
impl Cmd {
@@ -934,6 +956,13 @@ impl Cmd {
}
}
+ fn log_delayed_stream_start(&self, cmd_str: &str, delay_ms: i64) {
+ match &self.context {
+ Some(ctx) => log::debug!("$ {} [{}] (delayed stream, {}ms)", cmd_str, ctx, delay_ms),
+ None => log::debug!("$ {} (delayed stream, {}ms)", cmd_str, delay_ms),
+ }
+ }
+
/// Add a single argument.
pub fn arg(mut self, arg: impl Into<String>) -> Self {
self.args.push(arg.into());
@@ -1138,10 +1167,10 @@ impl Cmd {
// Acquire semaphore to limit concurrent commands
let _guard = semaphore().acquire();
- let trace_log = WtTraceLog::new(self.context.as_deref(), &cmd_str);
+ let mut trace = CommandTrace::new(self.context.as_deref(), &cmd_str);
if let Err(e) = self.check_spawn_preconditions() {
- trace_log.errored(&e);
+ trace.fail(&e);
external_log.record(None);
return Err(e);
}
@@ -1152,7 +1181,10 @@ impl Cmd {
// Determine effective timeout: explicit > thread-local > none
let effective_timeout = self.timeout.or_else(|| COMMAND_TIMEOUT.with(|t| t.get()));
- // Execute with or without stdin
+ // Execute with or without stdin. Every branch produces a single
+ // `Result<Output>` so spawn/write failures resolve the trace through
+ // `record_captured` rather than `?`-ing past it (which would leave the
+ // command unattributed and trip CommandTrace's drop assertion).
let result = if let Some(stdin_data) = self.stdin_data {
// Stdin piping requires spawn/write/wait
// Note: stdin path doesn't support timeout (would need async I/O)
@@ -1160,17 +1192,23 @@ impl Cmd {
.stdout(Stdio::piped())
.stderr(Stdio::piped());
- let mut child = cmd.spawn()?;
-
- // Write stdin data (ignore BrokenPipe - some commands exit early)
- if let Some(mut stdin) = child.stdin.take()
- && let Err(e) = stdin.write_all(&stdin_data)
- && e.kind() != std::io::ErrorKind::BrokenPipe
- {
- return Err(e);
+ match cmd.spawn() {
+ Ok(mut child) => {
+ // Write stdin data in an inner scope so the handle DROPS
+ // (closing the pipe) before `wait_with_output` — otherwise a
+ // child that reads stdin to EOF (e.g. `git … --stdin`) blocks
+ // forever. (ignore BrokenPipe - some commands exit early)
+ let write_result = {
+ let mut stdin = child.stdin.take().expect("stdin was configured as piped");
+ stdin.write_all(&stdin_data)
+ };
+ match write_result {
+ Err(e) if e.kind() != std::io::ErrorKind::BrokenPipe => Err(e),
+ _ => child.wait_with_output(),
+ }
+ }
+ Err(e) => Err(e),
}
-
- child.wait_with_output()
} else if let Some(timeout_duration) = effective_timeout {
// Timeout handling uses the existing impl
run_with_timeout_impl(&mut cmd, timeout_duration)
@@ -1179,7 +1217,7 @@ impl Cmd {
cmd.output()
};
- trace_log.record_result(&result);
+ record_captured(&mut trace, &result);
let exit_code = result.as_ref().ok().and_then(|output| output.status.code());
external_log.record(exit_code);
@@ -1244,15 +1282,15 @@ impl Cmd {
let _guard = semaphore().acquire();
- let first_log = WtTraceLog::new(self.context.as_deref(), &first_cmd_str);
- let second_log = WtTraceLog::new(next.context.as_deref(), &second_cmd_str);
-
+ // Validate both commands before spawning either. Nothing has spawned
+ // yet, so a precondition failure emits a one-shot failed record rather
+ // than holding a guard across an execution that never happens.
if let Err(e) = self.check_spawn_preconditions() {
- first_log.errored(&e);
+ CommandTrace::record_failed(self.context.as_deref(), &first_cmd_str, &e);
return Err(e);
}
if let Err(e) = next.check_spawn_preconditions() {
- second_log.errored(&e);
+ CommandTrace::record_failed(next.context.as_deref(), &second_cmd_str, &e);
return Err(e);
}
@@ -1269,7 +1307,16 @@ impl Cmd {
.stdout(Stdio::piped())
.stderr(Stdio::piped());
- let mut first_child = first.spawn()?;
+ // Trace each command from just before its own spawn so the duration
+ // brackets the real spawn → wait span.
+ let mut first_trace = CommandTrace::new(self.context.as_deref(), &first_cmd_str);
+ let mut first_child = match first.spawn() {
+ Ok(child) => child,
+ Err(e) => {
+ first_trace.fail(&e);
+ return Err(e);
+ }
+ };
let first_stdout = first_child
.stdout
.take()
@@ -1296,11 +1343,17 @@ impl Cmd {
// Spawn `next` before waiting on either child so `self`'s stdout keeps
// flowing through the pipe (otherwise a full pipe buffer would wedge
// `self`). If the spawn itself fails, clean up `self` before returning.
+ let mut second_trace = CommandTrace::new(next.context.as_deref(), &second_cmd_str);
let second_child = match second.spawn() {
Ok(child) => child,
Err(e) => {
+ second_trace.fail(&e);
let _ = first_child.kill();
let _ = first_child.wait();
+ // `first` spawned but is being torn down because the pipeline
+ // can't run — record it as a non-success rather than leaving
+ // the guard unresolved.
+ first_trace.complete(false);
return Err(e);
}
};
@@ -1336,7 +1389,7 @@ impl Cmd {
// Drain `next` first (its `wait_with_output` reads its own
// stdout/stderr), so `first`'s writes can complete.
let second_result = second_child.wait_with_output();
- second_log.record_result(&second_result);
+ record_captured(&mut second_trace, &second_result);
// Reap `first`. Its stderr is already being drained; combine
// the captured stderr with the exit status into an Output.
@@ -1350,7 +1403,7 @@ impl Cmd {
stderr,
})
});
- first_log.record_result(&first_result);
+ record_captured(&mut first_trace, &first_result);
(first_result, second_result)
});
@@ -1411,10 +1464,10 @@ impl Cmd {
cmd.env(DIRECTIVE_FILE_ENV_VAR, path);
}
- let trace_log = WtTraceLog::new(self.context.as_deref(), &cmd_str);
-
if let Err(e) = self.check_spawn_preconditions() {
- trace_log.errored(&e);
+ // Nothing spawned yet — emit a one-shot failed record (the trace
+ // guard is constructed just before spawn, below).
+ CommandTrace::record_failed(self.context.as_deref(), &cmd_str, &e);
return Err(anyhow::Error::from(GitError::Other {
message: format!("Failed to execute command ({}): {}", exec_mode, e),
}));
@@ -1463,10 +1516,14 @@ impl Cmd {
// Prevent vergen "overridden" warning in nested cargo builds
.env_remove("VERGEN_GIT_DESCRIBE");
+ // Start the trace immediately before spawn, after the fallible
+ // signal-handler install — so a pre-spawn early return can't drop the
+ // guard unresolved, and the duration brackets the child.
+ let mut trace = CommandTrace::new(self.context.as_deref(), &cmd_str);
let mut child = match cmd.spawn() {
Ok(child) => child,
Err(e) => {
- trace_log.errored(&e);
+ trace.fail(&e);
return Err(anyhow::Error::from(GitError::Other {
message: format!("Failed to execute command ({}): {}", exec_mode, e),
}));
@@ -1479,7 +1536,7 @@ impl Cmd {
&& let Err(e) = stdin.write_all(content)
&& e.kind() != std::io::ErrorKind::BrokenPipe
{
- trace_log.errored(&e);
+ trace.fail(&e);
return Err(e.into());
}
// stdin handle is dropped here, closing the pipe
@@ -1501,7 +1558,7 @@ impl Cmd {
let status = match wait_result {
Ok(status) => status,
Err(e) => {
- trace_log.errored(&e);
+ trace.fail(&e);
return Err(anyhow::Error::from(GitError::Other {
message: format!("Failed to wait for command: {}", e),
}));
@@ -1522,7 +1579,7 @@ impl Cmd {
if let Some(sig) = seen_signal
&& !status.success()
{
- trace_log.completed(false);
+ trace.complete(false);
external_log.record(Some(128 + sig));
return Err(WorktrunkError::ChildProcessExited {
code: 128 + sig,
@@ -1537,11 +1594,11 @@ impl Cmd {
// SIGPIPE (13) is expected when a pager (less, bat) exits before the
// child finishes writing — not an error from the user's perspective.
if sig == SIGPIPE {
- trace_log.completed(true);
+ trace.complete(true);
external_log.record(Some(0));
return Ok(());
}
- trace_log.completed(false);
+ trace.complete(false);
external_log.record(Some(128 + sig));
return Err(WorktrunkError::ChildProcessExited {
code: 128 + sig,
@@ -1553,7 +1610,7 @@ impl Cmd {
if !status.success() {
let code = status.code().unwrap_or(1);
- trace_log.completed(false);
+ trace.complete(false);
external_log.record(status.code());
return Err(WorktrunkError::ChildProcessExited {
code,
@@ -1563,11 +1620,142 @@ impl Cmd {
.into());
}
- trace_log.completed(true);
+ trace.complete(true);
external_log.record(Some(0));
Ok(())
}
+
+ /// Execute the command with delayed output streaming.
+ ///
+ /// Buffers stdout/stderr initially; if the command runs longer than
+ /// `delay_ms`, switches to streaming both to **stderr** live (keeping our
+ /// stdout clean for callers like `wt switch`). Fast commands stay quiet;
+ /// slow ones (`git worktree add` on a large repo) show progress. Pass `-1`
+ /// to never switch to streaming (always buffer); `0` streams immediately.
+ ///
+ /// `progress_message`, when set, prints to stderr at the moment streaming
+ /// starts (the delay threshold is crossed).
+ ///
+ /// Like [`Cmd::stream`], this does **not** acquire the concurrency
+ /// semaphore: a delayed-stream command runs in the foreground and would
+ /// only ever contend with itself (and acquiring a permit while one is held
+ /// could deadlock under `concurrency = 1`). On a non-zero exit it returns a
+ /// [`StreamCommandError`] carrying the buffered output so callers can render
+ /// the failure (e.g. git's `fatal: …`).
+ ///
+ /// # Panics
+ ///
+ /// Panics if called on a shell-wrapped command (`Cmd::shell()`); the
+ /// delayed-stream path runs a program directly.
+ pub fn delayed_stream(
+ self,
+ delay_ms: i64,
+ progress_message: Option<String>,
+ ) -> anyhow::Result<()> {
+ assert!(
+ !self.shell_wrap,
+ "Cmd::delayed_stream() runs a program directly; Cmd::shell() is not supported"
+ );
+ debug_assert!(
+ self.stdin_data.is_none()
+ && self.timeout.is_none()
+ && self.external_label.is_none()
+ && self.directive_cd_file.is_none()
+ && self.directive_exec_file.is_none()
+ && self.directive_legacy_file.is_none(),
+ "delayed_stream does not support stdin/timeout/external/directive options"
+ );
+
+ // Allow tests to override the delay threshold (-1 to disable, 0 for
+ // immediate streaming).
+ let delay_ms = std::env::var("WORKTRUNK_TEST_DELAYED_STREAM_MS")
+ .ok()
+ .and_then(|s| s.parse().ok())
+ .unwrap_or(delay_ms);
+
+ let cmd_str = self.command_string();
+ self.log_delayed_stream_start(&cmd_str, delay_ms);
+
+ let mut trace = CommandTrace::new(self.context.as_deref(), &cmd_str);
+
+ let mut cmd = self.direct_command();
+ self.apply_common_settings(&mut cmd);
+ cmd.stdin(Stdio::null())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::piped());
+
+ let mut child = match cmd.spawn() {
+ Ok(child) => child,
+ Err(e) => {
+ trace.fail(&e);
+ return Err(e).with_context(|| format!("Failed to spawn: {}", cmd_str));
+ }
+ };
+
+ let stdout = child.stdout.take().expect("stdout was piped");
+ let stderr = child.stderr.take().expect("stderr was piped");
+
+ // Shared state: when true, output streams directly; when false, buffers.
+ let streaming = Arc::new(AtomicBool::new(false));
+ let buffer = Arc::new(Mutex::new(Vec::new()));
+ let stdout_handle = spawn_delayed_reader(stdout, streaming.clone(), buffer.clone());
+ let stderr_handle = spawn_delayed_reader(stderr, streaming.clone(), buffer.clone());
+
+ let start = Instant::now();
+
+ // Phase 1: If the delay threshold is enabled, wait that long for the
+ // child to exit. If it finishes before the threshold, output stays
+ // buffered (quiet).
+ if delay_ms >= 0 {
+ let delay = Duration::from_millis(delay_ms as u64);
+ let remaining = delay.saturating_sub(start.elapsed());
+
+ // Zero delay means "stream immediately", not "try a zero-timeout reap".
+ if !remaining.is_zero() {
+ match child.wait_timeout(remaining) {
+ Ok(Some(status)) => {
+ let _ = stdout_handle.join();
+ let _ = stderr_handle.join();
+ trace.complete(status.success());
+ return stream_exit_result(status, &buffer, &cmd_str);
+ }
+ // Threshold exceeded — fall through to streaming.
+ Ok(None) => {}
+ Err(e) => {
+ let _ = stdout_handle.join();
+ let _ = stderr_handle.join();
+ trace.fail(&e);
+ return Err(e).context("Failed to wait for command");
+ }
+ }
+ }
+
+ // Delay threshold exceeded — switch to streaming.
+ streaming.store(true, Ordering::Relaxed);
+ if let Some(ref msg) = progress_message {
+ let _ = writeln!(std::io::stderr(), "{}", msg);
+ }
+ for line in buffer.lock().unwrap().drain(..) {
+ let _ = writeln!(std::io::stderr(), "{}", line);
+ }
+ let _ = std::io::stderr().flush();
+ }
+
+ // Phase 2: Block until the child exits (no polling).
+ let wait_result = child.wait();
+ let _ = stdout_handle.join();
+ let _ = stderr_handle.join();
+ let status = match wait_result {
+ Ok(status) => status,
+ Err(e) => {
+ trace.fail(&e);
+ return Err(e).context("Failed to wait for command");
+ }
+ };
+ trace.complete(status.success());
+ stream_exit_result(status, &buffer, &cmd_str)
+ }
}
// ============================================================================
@@ -2102,6 +2290,130 @@ mod tests {
);
}
+ // Fault-injection coverage for the `CommandTrace` resolution arms across
+ // `Cmd`'s execution modes. A non-existent *relative* program slips past
+ // `check_spawn_preconditions` (which only stats absolute paths) and fails at
+ // `spawn()`, exercising the `trace.fail` spawn-error arms; a non-existent
+ // *absolute* program is caught by preconditions, exercising the
+ // `record_failed` arms. None set `.context()`, so the no-context logging
+ // branches are covered too.
+ const MISSING_CMD: &str = "worktrunk-nonexistent-binary-7f3a9b2c";
+
+ #[test]
+ fn test_cmd_run_spawn_failure_resolves_trace() {
+ let err = Cmd::new(MISSING_CMD).run().unwrap_err();
+ assert_eq!(err.kind(), ErrorKind::NotFound);
+ }
+
+ #[test]
+ #[cfg(unix)]
+ fn test_cmd_run_with_stdin_closes_pipe() {
+ // `cat` reads stdin to EOF; it can only exit once the pipe is closed,
+ // so this pins the "drop stdin before wait" behavior (a regression here
+ // hangs forever rather than failing).
+ let output = Cmd::new("cat").stdin_bytes("piped body").run().unwrap();
+ assert!(output.status.success());
+ assert_eq!(String::from_utf8_lossy(&output.stdout), "piped body");
+ }
+
+ #[test]
+ #[cfg(unix)]
+ fn test_cmd_delayed_stream_quiet_success() {
+ // A fast command under a generous threshold exits during phase 1
+ // (wait_timeout returns Some) and stays buffered/quiet.
+ Cmd::new("true").delayed_stream(5_000, None).unwrap();
+ }
+
+ #[test]
+ #[cfg(unix)]
+ fn test_cmd_delayed_stream_streams_then_reports_failure() {
+ // delay_ms=0 streams immediately (phase-1 threshold crossed → progress
+ // message + buffer drain), and a non-zero exit surfaces as a
+ // StreamCommandError carrying the buffered output.
+ let err = Cmd::new("sh")
+ .args(["-c", "echo to-stderr 1>&2; exit 3"])
+ .delayed_stream(0, Some("working…".to_string()))
+ .unwrap_err();
+ let stream_err = err
+ .downcast_ref::<StreamCommandError>()
+ .expect("non-zero delayed_stream exit should be a StreamCommandError");
+ assert_eq!(stream_err.exit_info, "exit code 3");
+ }
+
+ #[test]
+ fn test_cmd_delayed_stream_spawn_failure_resolves_trace() {
+ // delay_ms=-1 disables phase 1; the spawn failure resolves the trace
+ // via `fail` rather than dropping it unresolved.
+ let err = Cmd::new(MISSING_CMD).delayed_stream(-1, None).unwrap_err();
+ assert!(err.to_string().contains("Failed to spawn"), "{err}");
+ }
+
+ #[test]
+ #[cfg(unix)]
+ fn test_cmd_pipe_into_succeeds() {
+ let (source, sink) = Cmd::new("printf")
+ .arg("hello")
+ .pipe_into(Cmd::new("cat"))
+ .unwrap();
+ assert!(source.status.success() && sink.status.success());
+ assert_eq!(String::from_utf8_lossy(&sink.stdout), "hello");
+ }
+
+ #[test]
+ fn test_cmd_pipe_into_source_spawn_failure_resolves_trace() {
+ let err = Cmd::new(MISSING_CMD)
+ .pipe_into(Cmd::new("cat"))
+ .unwrap_err();
+ assert_eq!(err.kind(), ErrorKind::NotFound);
+ }
+
+ #[test]
+ #[cfg(unix)]
+ fn test_cmd_pipe_into_sink_spawn_failure_resolves_both_traces() {
+ // The sink fails to spawn after the source is already running: the sink
+ // trace fails and the source is torn down with complete(false).
+ let err = Cmd::new("printf")
+ .arg("hello")
+ .pipe_into(Cmd::new(MISSING_CMD))
+ .unwrap_err();
+ assert_eq!(err.kind(), ErrorKind::NotFound);
+ }
+
+ // An *absolute* non-existent program is rejected by
+ // `check_spawn_preconditions` (which stats absolute paths) before any spawn,
+ // exercising the `record_failed` precondition arms rather than the
+ // spawn-error arms above.
+ #[test]
+ fn test_cmd_pipe_into_source_precondition_failure_resolves_trace() {
+ let err = Cmd::new("/no/such/abs-source-7f3a9b2c")
+ .pipe_into(Cmd::new("cat"))
+ .unwrap_err();
+ assert_eq!(err.kind(), ErrorKind::NotFound);
+ }
+
+ #[test]
+ #[cfg(unix)]
+ fn test_cmd_pipe_into_sink_precondition_failure_resolves_trace() {
+ // Source preconditions pass (relative program); the sink's fail.
+ let err = Cmd::new("printf")
+ .arg("x")
+ .pipe_into(Cmd::new("/no/such/abs-sink-7f3a9b2c"))
+ .unwrap_err();
+ assert_eq!(err.kind(), ErrorKind::NotFound);
+ }
+
+ #[test]
+ fn test_stream_command_error_display_is_the_output() {
+ // The Display impl exists only for the Error bound; callers read fields
+ // via Repository::extract_failed_command, so nothing else exercises it.
+ let err = StreamCommandError {
+ output: "fatal: ref exists".to_string(),
+ command: "git worktree add /x".to_string(),
+ exit_info: "exit code 128".to_string(),
+ };
+ assert_eq!(err.to_string(), "fatal: ref exists");
+ }
+
#[test]
#[cfg(unix)]
fn test_cmd_shell_stream_with_stdin() {
diff --git a/src/trace/emit.rs b/src/trace/emit.rs
index c8172552f..0bdb08c38 100644
--- a/src/trace/emit.rs
+++ b/src/trace/emit.rs
@@ -30,6 +30,25 @@
//! at the layer — means the wire format lives in one place
//! (`logging.rs`) and emit sites carry no string-formatting noise.
//!
+//! # The subprocess chokepoint: [`CommandTrace`]
+//!
+//! Every subprocess command record (`cmd=…`) is emitted by exactly one type:
+//! [`CommandTrace`]. The underlying `command_completed` / `command_errored`
+//! writers are private to this module, so the *only* way to produce a command
+//! record is to construct a `CommandTrace` and resolve it with `complete` /
+//! `fail`. This is deliberate: subprocesses are spawned from many places
+//! (`shell_exec::Cmd::{run, stream, delayed_stream, pipe_into}`, the
+//! concurrent-command runner, pipeline steps, `wt step tether`, the fsmonitor
+//! daemon launch), and before this chokepoint each path emitted — or, more
+//! often, silently *forgot* to emit — its own record. Routing them all through
+//! one guard means a path either traces or doesn't compile a record at all,
+//! rather than skipping tracing by omission.
+//!
+//! `CommandTrace` is `#[must_use]` and asserts on drop that it was resolved
+//! (debug builds only), so a future spawn site that constructs a guard but
+//! forgets to call `complete`/`fail` trips in tests rather than leaving an
+//! unattributed gap in the timeline.
+//!
//! # Timing
//!
//! In-process spans (everything that isn't a subprocess) use [`Span`], an
@@ -38,9 +57,12 @@
//! in code paths subprocess records can't see (config load, repo open,
//! template render).
//!
-//! Subprocess emission lives in `shell_exec::WtTraceLog`, which captures
-//! `Instant::now()` at `Cmd::run` entry — `tracing` spans can't carry this
-//! across the sync subprocess wait, so the timing stays manual.
+//! Subprocess timing lives in [`CommandTrace`], which captures
+//! `Instant::now()` just before the spawn — `tracing` spans can't carry this
+//! across the sync subprocess wait, so the timing stays manual. The duration
+//! is snapshotted at the moment `complete`/`fail` is called (the command's
+//! resolution point), so a streamed command whose duration isn't known until
+//! the stream finishes still records the correct spawn → wait span.
//!
//! # Routing
//!
@@ -87,14 +109,11 @@ pub fn thread_id() -> u64 {
}
/// Emit a completed-command record (`ok=true`/`ok=false`).
-pub fn command_completed(
- context: Option<&str>,
- cmd: &str,
- ts: u64,
- tid: u64,
- dur_us: u64,
- ok: bool,
-) {
+///
+/// Private: the sole caller is [`CommandTrace::complete`]. Keeping the writer
+/// module-private makes [`CommandTrace`] the only way to emit a command
+/// record — see the module-level "subprocess chokepoint" note.
+fn command_completed(context: Option<&str>, cmd: &str, ts: u64, tid: u64, dur_us: u64, ok: bool) {
match context {
Some(ctx) => tracing::debug!(
target: WT_TRACE_TARGET,
@@ -119,7 +138,9 @@ pub fn command_completed(
}
/// Emit a failed-command record (the command didn't run to completion).
-pub fn command_errored(
+///
+/// Private: the sole caller is [`CommandTrace::fail`]. See [`command_completed`].
+fn command_errored(
context: Option<&str>,
cmd: &str,
ts: u64,
@@ -151,6 +172,111 @@ pub fn command_errored(
}
}
+/// The single emitter for subprocess command records — every `[wt-trace]`
+/// `cmd=…` line comes from here.
+///
+/// Construct one immediately before spawning a child, then call
+/// [`complete`](Self::complete) (the child exited — `ok=` reflects its status)
+/// or [`fail`](Self::fail) (the command never ran to completion — spawn error,
+/// wait error) exactly once. The record is emitted at that call; the duration
+/// is the elapsed time from construction to resolution, so it brackets the
+/// real spawn → wait span even for streamed commands whose duration isn't
+/// known until the stream finishes.
+///
+/// # Why a guard rather than a free function
+///
+/// Subprocesses are spawned from many code paths with incompatible I/O shapes
+/// (capture, inherit, buffer-then-stream, two-stage pipe, N concurrent
+/// children). They can't share one spawn primitive, but they can share one
+/// *trace* primitive. Centralizing emission here — with the writers private to
+/// this module — means a path either resolves a `CommandTrace` or emits no
+/// record at all, instead of each path re-deriving (and routinely forgetting)
+/// the emit logic.
+///
+/// The `#[must_use]` and the debug-build drop assertion catch the remaining
+/// failure mode: a guard that is constructed but never resolved (a spawn site
+/// that forgot to wire up `complete`/`fail`) trips a test-time assertion rather
+/// than silently producing an unattributed gap in the timeline. The assertion
+/// is suppressed while the thread is panicking so an unrelated panic between
+/// construction and resolution unwinds cleanly instead of aborting.
+#[must_use = "a CommandTrace must be resolved with complete() or fail() to emit its record"]
+pub struct CommandTrace {
+ context: Option<String>,
+ cmd: String,
+ start_ts_us: u64,
+ start: Instant,
+ tid: u64,
+ resolved: bool,
+}
+
+impl CommandTrace {
+ /// Begin tracing a command. Call immediately before spawning the child so
+ /// the captured start time brackets the subprocess.
+ pub fn new(context: Option<&str>, cmd: &str) -> Self {
+ Self {
+ context: context.map(ToOwned::to_owned),
+ cmd: cmd.to_owned(),
+ start_ts_us: now_us(),
+ start: Instant::now(),
+ tid: thread_id(),
+ resolved: false,
+ }
+ }
+
+ /// The child ran to completion; `success` is its exit status. Emits an
+ /// `ok=true`/`ok=false` record with the elapsed duration.
+ pub fn complete(&mut self, success: bool) {
+ let dur_us = self.start.elapsed().as_micros() as u64;
+ command_completed(
+ self.context.as_deref(),
+ &self.cmd,
+ self.start_ts_us,
+ self.tid,
+ dur_us,
+ success,
+ );
+ self.resolved = true;
+ }
+
+ /// Emit a failed record for a command that never produced a child to hold
+ /// a guard against — a precondition failure before spawn, where there is
+ /// nothing to time. Equivalent to `new` immediately followed by `fail`.
+ pub fn record_failed(context: Option<&str>, cmd: &str, err: impl Display) {
+ let mut trace = Self::new(context, cmd);
+ trace.fail(err);
+ }
+
+ /// The command never ran to completion (spawn failure, wait failure).
+ /// Emits an `err=…` record with the elapsed duration.
+ pub fn fail(&mut self, err: impl Display) {
+ let dur_us = self.start.elapsed().as_micros() as u64;
+ command_errored(
+ self.context.as_deref(),
+ &self.cmd,
+ self.start_ts_us,
+ self.tid,
+ dur_us,
+ err,
+ );
+ self.resolved = true;
+ }
+}
+
+impl Drop for CommandTrace {
+ fn drop(&mut self) {
+ // A guard reaching drop unresolved means a spawn path forgot to call
+ // complete()/fail() — catch it in tests. Suppress while panicking so an
+ // unrelated panic between construction and resolution doesn't abort by
+ // double-panicking during unwind.
+ debug_assert!(
+ self.resolved || std::thread::panicking(),
+ "CommandTrace for `{}` dropped without complete()/fail(); \
+ every spawn must resolve its trace (see src/trace/emit.rs)",
+ self.cmd
+ );
+ }
+}
+
/// Emit an instant (milestone) event with no duration. Computes `ts` and
/// `tid` internally — use for one-off markers inside a thread's execution.
///
@@ -222,3 +348,37 @@ impl Drop for Span {
span_completed(&self.name, self.start_ts_us, thread_id(), dur_us);
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ // Resolution (complete/fail) marks the guard so its drop is a no-op. No
+ // tracing subscriber is installed, so the records themselves are dropped —
+ // the point is that the drop-time tripwire does not fire on a resolved
+ // guard. (The wire grammar is locked separately by
+ // `logging::tests::format_wt_trace_renders_each_kind`.)
+ #[test]
+ fn resolved_trace_drops_cleanly() {
+ let mut completed = CommandTrace::new(Some("ctx"), "git status");
+ completed.complete(true);
+ drop(completed);
+
+ let mut failed = CommandTrace::new(None, "git nope");
+ failed.fail(std::io::Error::other("boom"));
+ drop(failed);
+
+ CommandTrace::record_failed(None, "git nope", "precondition");
+ }
+
+ // A guard that reaches drop without complete()/fail() is a spawn site that
+ // forgot to resolve its trace — the debug-build tripwire turns that into a
+ // test failure rather than a silent unattributed gap.
+ #[cfg(debug_assertions)]
+ #[test]
+ #[should_panic(expected = "dropped without complete()/fail()")]
+ fn unresolved_trace_panics_on_drop() {
+ let _trace = CommandTrace::new(None, "git unresolved");
+ // No complete()/fail() — drop here trips the assertion.
+ }
+}
diff --git a/src/trace/mod.rs b/src/trace/mod.rs
index 343bfcb8a..3b71b8c18 100644
--- a/src/trace/mod.rs
+++ b/src/trace/mod.rs
@@ -43,5 +43,5 @@ pub mod parse;
// Re-export main types for convenience
pub use chrome::to_chrome_trace;
-pub use emit::{Span, WT_TRACE_TARGET, instant};
+pub use emit::{CommandTrace, Span, WT_TRACE_TARGET, instant};
pub use parse::{TraceEntry, TraceEntryKind, TraceResult, parse_lines};
diff --git a/tests/integration_tests/switch.rs b/tests/integration_tests/switch.rs
index d0254e993..07250ed50 100644
--- a/tests/integration_tests/switch.rs
+++ b/tests/integration_tests/switch.rs
@@ -76,6 +76,47 @@ fn test_switch_create_shows_progress_when_forced(repo: TestRepo) {
});
}
+/// `git worktree add` runs through the delayed-stream path (`Cmd::delayed_stream`),
+/// which historically spawned a raw child and emitted no `[wt-trace]` record — it
+/// surfaced only as an unattributed gap in the `wt-perf` timeline. Assert the
+/// streamed command is now traced, pinning the `CommandTrace` chokepoint
+/// (`src/trace/emit.rs`) against regression. The record is emitted whether the
+/// command buffers or streams, so no delay threshold is forced.
+#[rstest]
+fn test_switch_create_traces_worktree_add(repo: TestRepo) {
+ use worktrunk::trace::{TraceEntryKind, parse_lines};
+
+ // RUST_LOG=debug routes `[wt-trace]` records to stderr (the same channel
+ // `wt-perf timeline` reads).
+ let output = repo
+ .wt_command()
+ .args(["switch", "--create", "feature-traced", "--no-cd"])
+ .env("RUST_LOG", "debug")
+ .output()
+ .expect("wt switch should run");
+ assert!(
+ output.status.success(),
+ "switch failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ let commands: Vec<String> = parse_lines(&stderr)
+ .into_iter()
+ .filter_map(|e| match e.kind {
+ TraceEntryKind::Command { command, .. } => Some(command),
+ _ => None,
+ })
+ .collect();
+
+ assert!(
+ commands.iter().any(|c| c.contains("worktree add")),
+ "expected a [wt-trace] command record for `git worktree add`; \
+ got command records:\n{}",
+ commands.join("\n")
+ );
+}
+
#[rstest]
fn test_switch_create_existing_branch_error(mut repo: TestRepo) {
// Create a branch first