Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Simplify stdout-to-stderr redirect using OS-level Stdio (#132)
Maximilian Roos809021e8bb9f
diff --git a/ISSUE.md b/ISSUE.mdnew file mode 100644index 000000000..80e923fb0--- /dev/null+++ b/ISSUE.md@@ -0,0 +1,328 @@+# Intermittent Ctrl-C (SIGINT) Not Working Through Shell Wrapper++## Problem Summary++When running `cargo nextest` through worktrunk's shell wrapper (via `wt hook pre-merge`), Ctrl-C occasionally fails to terminate the running tests. The issue is intermittent — sometimes Ctrl-C works correctly, sometimes it appears to be ignored.++## Goals++1. Understand whether worktrunk's shell wrapping is causing the signal delivery issue+2. Determine if the same behavior would occur running `cargo nextest` directly+3. Identify the root cause and potential fixes++## System Context++- **Platform**: macOS (Darwin 25.0.0)+- **Shell**: `/bin/sh -c` (POSIX shell)+- **Tool chain**: Rust CLI tool (`wt`) executing shell commands++## Architecture Overview++### Process Tree When Running `wt hook pre-merge`++```+wt (worktrunk binary)+└── sh -c "{ cargo nextest run ...\n} 1>&2"+ └── cargo nextest run ...+ └── test runner process+ └── individual test processes+```++### How Commands Are Executed++Worktrunk uses a shell wrapper pattern to execute hook commands. The relevant code flow is:++1. `wt hook pre-merge` calls `execute_command_in_worktree()`+2. This calls `execute_streaming()` with `redirect_stdout_to_stderr=true`+3. `execute_streaming()` wraps the command and spawns via `/bin/sh -c`++### Key Code: Shell Execution (`src/output/handlers.rs`)++```rust+pub(crate) fn execute_streaming(+ command: &str,+ working_dir: &std::path::Path,+ redirect_stdout_to_stderr: bool,+ stdin_content: Option<&str>,+) -> anyhow::Result<()> {+ use std::io::Write;+ use worktrunk::git::WorktrunkError;+ use worktrunk::shell_exec::ShellConfig;++ let shell = ShellConfig::get();++ // Determine stdout handling based on shell and redirect flag+ let (command_to_run, stdout_mode) = if redirect_stdout_to_stderr {+ if shell.is_posix() {+ // POSIX: wrap command to redirect stdout to stderr at shell level+ // Use newline instead of semicolon before closing brace to support+ // multi-line commands with control structures (if/fi, for/done, etc.)+ (+ format!("{{ {}\n}} 1>&2", command),+ std::process::Stdio::inherit(),+ )+ } else {+ // Non-POSIX (PowerShell): redirect stdout to stderr at OS level+ (+ command.to_string(),+ std::process::Stdio::from(std::io::stderr()),+ )+ }+ } else {+ (command.to_string(), std::process::Stdio::inherit())+ };++ let stdin_mode = if stdin_content.is_some() {+ std::process::Stdio::piped()+ } else {+ std::process::Stdio::null()+ };++ let mut cmd = shell.command(&command_to_run);+ let mut child = cmd+ .current_dir(working_dir)+ .stdin(stdin_mode)+ .stdout(stdout_mode)+ .stderr(std::process::Stdio::inherit()) // Preserve TTY for errors+ .env_remove("VERGEN_GIT_DESCRIBE")+ .spawn()+ .map_err(|e| {+ anyhow::Error::from(worktrunk::git::GitError::Other {+ message: format!("Failed to execute command with {}: {}", shell.name, e),+ })+ })?;++ // Write stdin content if provided (used for hook context JSON)+ if let Some(content) = stdin_content+ && let Some(mut stdin) = child.stdin.take()+ {+ // Write and close stdin immediately so the child doesn't block waiting for more input+ let _ = stdin.write_all(content.as_bytes());+ // stdin is dropped here, closing the pipe+ }++ // Wait for command to complete+ let status = child.wait().map_err(|e| {+ anyhow::Error::from(worktrunk::git::GitError::Other {+ message: format!("Failed to wait for command: {}", e),+ })+ })?;++ // Check if child was killed by a signal (Unix only)+ // This handles Ctrl-C: when SIGINT is sent, the child receives it and terminates,+ // and we propagate the signal exit code (128 + signal number, e.g., 130 for SIGINT)+ #[cfg(unix)]+ if let Some(sig) = std::os::unix::process::ExitStatusExt::signal(&status) {+ return Err(WorktrunkError::ChildProcessExited {+ code: 128 + sig,+ message: format!("terminated by signal {}", sig),+ }+ .into());+ }++ if !status.success() {+ let code = status.code().unwrap_or(1);+ return Err(WorktrunkError::ChildProcessExited {+ code,+ message: format!("exit status: {}", code),+ }+ .into());+ }++ Ok(())+}+```++### Key Code: Shell Configuration (`src/shell_exec.rs`)++```rust+fn detect_shell() -> ShellConfig {+ #[cfg(unix)]+ {+ ShellConfig {+ executable: PathBuf::from("sh"),+ args: vec!["-c".to_string()],+ is_posix: true,+ name: "sh".to_string(),+ }+ }+}++impl ShellConfig {+ pub fn command(&self, shell_command: &str) -> Command {+ let mut cmd = Command::new(&self.executable);+ for arg in &self.args {+ cmd.arg(arg);+ }+ cmd.arg(shell_command);+ cmd+ }+}+```++## What We Know++### Signal Flow (Expected Behavior)++1. User presses Ctrl-C+2. Terminal sends SIGINT to the **foreground process group**+3. All processes in that group should receive SIGINT:+ - `wt` (blocking in `child.wait()`)+ - `sh` (waiting for its child)+ - `cargo nextest` (running tests)+ - Individual test processes+4. Each process handles SIGINT (usually terminates)+5. Exit codes propagate back up++### Stdio Configuration++- **stdin**: `Stdio::piped()` when stdin_content is provided (hook JSON context), otherwise `Stdio::null()`+- **stdout**: `Stdio::inherit()` (shares parent's stdout/TTY)+- **stderr**: `Stdio::inherit()` (shares parent's stderr/TTY)++### The Shell Wrapper Pattern++The command transformation for stdout→stderr redirection:++```+Input: cargo nextest run --all-targets+Output: { cargo nextest run --all-targets+} 1>&2+```++This gets executed as:+```bash+sh -c '{ cargo nextest run --all-targets+} 1>&2'+```++### Process Group Considerations++- By default, child processes inherit the parent's process group+- `sh -c` does NOT create a new process group+- With `Stdio::inherit()`, child processes share the controlling terminal+- SIGINT from Ctrl-C goes to the foreground process group++### What nextest Does++Nextest is known to create separate process groups for test isolation:+> "Each test runs in its own process. By default, nextest creates a new process group for each test to isolate tests from each other."++This means:+- `cargo nextest` receives SIGINT+- Individual test processes may be in different process groups+- Nextest must forward signals to its children++## Hypotheses++### Hypothesis 1: The `sh -c` Wrapper Interferes++The `{ ... } 1>&2` wrapper requires `sh` to stay resident (it can't `exec` directly because it needs to handle the redirection). This adds an extra process layer.++**Potential issue**: When `sh` is running a compound command, it waits for the inner command. If the inner command doesn't die from SIGINT (or handles it specially), `sh` keeps waiting.++### Hypothesis 2: Nextest's Process Groups++Nextest creates new process groups for test isolation. When SIGINT arrives:+1. SIGINT goes to the foreground process group (wt, sh, cargo-nextest)+2. But nextest's test child processes are in different process groups+3. Nextest's signal forwarding may race or fail depending on timing++### Hypothesis 3: No Signal Handler in Worktrunk++Worktrunk does NOT install any signal handlers. It relies entirely on:+1. The OS default behavior (SIGINT terminates the process)+2. `Stdio::inherit()` to let children receive signals from the TTY+3. Checking `ExitStatusExt::signal()` after `wait()` returns++This means while worktrunk is blocked in `child.wait()`:+- SIGINT arrives at worktrunk+- Default handler would terminate worktrunk+- But worktrunk might terminate before the child properly handles the signal++### Hypothesis 4: Stdin Pipe Timing++When `stdin_content` is provided:+1. stdin is `Stdio::piped()`+2. We write JSON content to the pipe+3. We close the pipe (drop the handle)+4. Then we `wait()`++If SIGINT arrives during the brief window where we're writing to stdin, there could be unexpected behavior.++## Open Questions++1. **Does the issue reproduce without worktrunk?**+ - Test: `sh -c '{ cargo nextest run --all-targets\n} 1>&2'`+ - If this also fails to respond to Ctrl-C, the issue is not worktrunk-specific++2. **Does the issue reproduce without the shell wrapper?**+ - Test: `cargo nextest run --all-targets` directly+ - If this works correctly, the `sh -c` wrapper is contributing++3. **What shell is `/bin/sh` on macOS?**+ - On modern macOS, `/bin/sh` is actually `zsh` in POSIX mode (or `bash` on older versions)+ - Different shells may handle signals in compound commands differently++4. **Does nextest have known signal handling issues?**+ - Are there GitHub issues about Ctrl-C not working with nextest?+ - Does nextest's `--no-capture` mode affect signal handling?++5. **Would installing a SIGINT handler in worktrunk help?**+ - Could explicitly forward SIGINT to the child process group+ - But this adds complexity and may interfere with other signal handling++6. **Does the `1>&2` redirection affect signal handling?**+ - The shell must stay resident to handle redirection+ - Does this change how the shell handles signals?++7. **Is there a timing component?**+ - Does the issue occur more often at certain points (test startup, between tests, during output)?+ - Could this be a race condition in nextest's signal forwarding?++## Research Questions for External Sources++1. **POSIX signal handling in shell compound commands**: How does `sh` handle SIGINT when running `{ cmd; } 1>&2`? Does it forward signals to the child? Does it wait for the child to exit first?++2. **Rust `std::process::Command` and signals**: When using `Stdio::inherit()`, how are signals delivered to child processes? Does the child receive SIGINT directly from the terminal?++3. **Process groups with `sh -c`**: Does `sh -c "command"` create a new process group? How does this interact with job control and signal delivery?++4. **cargo-nextest signal handling**: How does nextest handle SIGINT? Does it use process groups for test isolation? Are there known issues with signal forwarding?++5. **macOS `/bin/sh` behavior**: What shell is `/bin/sh` on modern macOS? How does it handle signals differently from Linux `dash` or `bash`?++6. **Best practices for CLI tools executing subprocesses**: What's the recommended way for a Rust CLI to execute shell commands while preserving proper Ctrl-C handling?++## Potential Solutions to Explore++1. **Avoid the shell wrapper**: Find an alternative to `{ cmd } 1>&2` that doesn't require `sh` to stay resident (e.g., use `Stdio::from(io::stderr())` for stdout like we do for non-POSIX shells)++2. **Install a signal handler**: Use the `ctrlc` crate or `signal-hook` to catch SIGINT and explicitly forward it to children++3. **Use `exec` in the shell command**: Change to `exec sh -c 'cmd'` or similar to reduce process layers++4. **Process group management**: Explicitly put the child in our process group using `setpgid`++5. **Document the limitation**: If this is a nextest issue, document it and suggest workarounds++## Test Commands++To help diagnose the issue, these commands can be compared:++```bash+# Direct execution (baseline)+cargo nextest run --all-targets++# With sh wrapper (matches worktrunk's pattern)+sh -c '{ cargo nextest run --all-targets+} 1>&2'++# Without redirection (simpler wrapper)+sh -c 'cargo nextest run --all-targets'++# With exec (reduces process layers)+sh -c 'exec cargo nextest run --all-targets'+```++Press Ctrl-C during each and observe whether termination is immediate or delayed/ignored.diff --git a/src/output/handlers.rs b/src/output/handlers.rsindex e4332b4bc..ca2dafc85 100644--- a/src/output/handlers.rs+++ b/src/output/handlers.rs@@ -648,12 +648,13 @@ fn handle_removed_worktree_output(/// Execute a command with streaming output///-/// Uses Stdio::inherit to preserve TTY behavior - this ensures commands like cargo detect they're-/// connected to a terminal and don't buffer their output.+/// Uses Stdio::inherit for stderr to preserve TTY behavior - this ensures commands like cargo+/// detect they're connected to a terminal and don't buffer their output.///-/// If `redirect_stdout_to_stderr` is true, wraps the command in `{ command; } 1>&2` to merge-/// stdout into stderr. This ensures deterministic output ordering (all output flows through stderr).-/// Per CLAUDE.md: child process output goes to stderr, worktrunk output goes to stdout.+/// If `redirect_stdout_to_stderr` is true, redirects child stdout to our stderr at the OS level+/// (via `Stdio::from(io::stderr())`). This ensures deterministic output ordering (all child output+/// flows through stderr). Per CLAUDE.md: child process output goes to stderr, worktrunk output+/// goes to stdout.////// If `stdin_content` is provided, it will be piped to the command's stdin (used for hook context JSON).///@@ -671,7 +672,7 @@ fn handle_removed_worktree_output(/// - If the child was killed by a signal, we return exit code 128 + signal number/// - This follows Unix conventions (e.g., exit code 130 for SIGINT)///-/// The child process receives SIGINT directly from the terminal (via Stdio::inherit).+/// The child process receives SIGINT directly from the terminal (via Stdio::inherit for stderr).pub(crate) fn execute_streaming(command: &str,working_dir: &std::path::Path,@@ -684,29 +685,15 @@ pub(crate) fn execute_streaming(let shell = ShellConfig::get();- // Determine stdout handling based on shell and redirect flag- let (command_to_run, stdout_mode) = if redirect_stdout_to_stderr {- if shell.is_posix() {- // POSIX: wrap command to redirect stdout to stderr at shell level- // Use newline instead of semicolon before closing brace to support- // multi-line commands with control structures (if/fi, for/done, etc.)- (- format!("{{ {}\n}} 1>&2", command),- std::process::Stdio::inherit(),- )- } else {- // Non-POSIX (PowerShell): redirect stdout to stderr at OS level- // PowerShell doesn't support shell-level stdout-to-stderr redirection (*>&2 fails).- // Use Stdio::from(io::stderr()) to redirect child stdout to our stderr.- // This keeps stdout clean for directive scripts while hook output goes to stderr.- // See: https://github.com/PowerShell/PowerShell/issues/7620- (- command.to_string(),- std::process::Stdio::from(std::io::stderr()),- )- }+ // Determine stdout handling based on redirect flag+ // When redirecting, use Stdio::from(stderr) to redirect child stdout to our stderr at OS level.+ // This keeps stdout clean for directive scripts while hook output goes to stderr.+ // Previously used shell-level `{ cmd } 1>&2` wrapping, but OS-level redirect is simpler+ // and may improve signal handling by removing an extra shell process layer.+ let stdout_mode = if redirect_stdout_to_stderr {+ std::process::Stdio::from(std::io::stderr())} else {- (command.to_string(), std::process::Stdio::inherit())+ std::process::Stdio::inherit()};let stdin_mode = if stdin_content.is_some() {@@ -715,7 +702,7 @@ pub(crate) fn execute_streaming(std::process::Stdio::null()};- let mut cmd = shell.command(&command_to_run);+ let mut cmd = shell.command(command);let mut child = cmd.current_dir(working_dir).stdin(stdin_mode)