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.mdindex 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(...)`.```rustCmd::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 StreamingStream command output line-by-line rather than buffering. Responsiveness is a priority.diff --git a/src/commands/custom.rs b/src/commands/custom.rsindex 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>) -> Rescmd.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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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<'_>) -> anyhowcmd_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.rsindex 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 commandslet _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 > nonelet 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 implrun_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.rsindex 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.rsindex 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 conveniencepub 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.rsindex 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