Skip to content

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

Clarify SIGTTOU issue in nextest config and docs

Maximilian Roosee507ee519a8
diff --git a/.config/nextest.toml b/.config/nextest.toml
index 030db8e5e..b3de16a52 100644
--- a/.config/nextest.toml
+++ b/.config/nextest.toml
@@ -1,6 +1,6 @@
-# IMPORTANT: When running in background process groups (AI coding environments
-# like Codex/Claude Code, or nested tmux/screen sessions), nextest's InputHandler
-# can receive SIGTTOU when restoring terminal settings, causing process suspension.
+# IMPORTANT: Tests that spawn interactive shells (zsh -ic, bash -ic) cause
+# nextest's InputHandler to receive SIGTTOU when restoring terminal settings,
+# suspending the test process. See https://github.com/nextest-rs/nextest/issues/2878
#
# Solution: Run with NEXTEST_NO_INPUT_HANDLER=1 or use the pre-merge hook which
# sets this automatically:
@@ -10,8 +10,6 @@
# Or use `cargo test` which doesn't have this issue:
#
# cargo test --test integration --features shell-integration-tests
-#
-# See tests/common/mod.rs for details on the SIGTTOU issue.
[profile.default]
slow-timeout = { period = "60s", terminate-after = 1 }
diff --git a/CLAUDE.md b/CLAUDE.md
index e12dcb456..e06deac98 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -101,7 +101,7 @@ This installs required shells (zsh, fish) for shell integration tests and builds
PTY-based tests (approval prompts, TUI select, progressive rendering, shell wrappers) are behind the `shell-integration-tests` feature.
-**IMPORTANT for AI coding environments (Codex, Claude Code):** When running in background process groups, nextest's InputHandler receives SIGTTOU when restoring terminal settings. This causes the test process to be suspended mid-run. The symptom is `zsh: suspended (tty output)` or similar.
+**IMPORTANT:** Tests that spawn interactive shells (`zsh -ic`, `bash -ic`) cause nextest's InputHandler to receive SIGTTOU when restoring terminal settings. This suspends the test process mid-run with `zsh: suspended (tty output)` or similar. See [nextest#2878](https://github.com/nextest-rs/nextest/issues/2878) for details.
**Solutions:**
@@ -115,7 +115,7 @@ PTY-based tests (approval prompts, TUI select, progressive rendering, shell wrap
NEXTEST_NO_INPUT_HANDLER=1 cargo nextest run --features shell-integration-tests
```
-The pre-merge hook (`wt hook pre-merge --yes`) already sets `NEXTEST_NO_INPUT_HANDLER=1` automatically. See `tests/common/mod.rs` for technical details on the SIGTTOU issue.
+The pre-merge hook (`wt hook pre-merge --yes`) already sets `NEXTEST_NO_INPUT_HANDLER=1` automatically.
## Command Execution Principles
diff --git a/tests/common/mod.rs b/tests/common/mod.rs
index dbe729dac..e343cf768 100644
--- a/tests/common/mod.rs
+++ b/tests/common/mod.rs
@@ -355,11 +355,10 @@ pub fn merge_scenario_multi_commit(mut repo: TestRepo) -> (TestRepo, PathBuf) {
/// 2. SIGTTIN/SIGTTOU are blocked to prevent test processes from being stopped
///
/// NOTE: PTY tests are behind the `shell-integration-tests` feature because they can
-/// trigger a nextest bug where its InputHandler cleanup receives SIGTTOU. This is NOT
-/// caused by our code - investigation confirmed our tests don't change the terminal's
-/// foreground process group. The issue is in nextest's teardown path (InputHandlerImpl::restore
-/// calls tcsetattr while nextest isn't in the foreground pgrp). Workaround: run with
-/// NEXTEST_NO_INPUT_HANDLER=1. See CLAUDE.md for details.
+/// trigger a nextest bug where its InputHandler cleanup receives SIGTTOU. This happens
+/// when tests spawn interactive shells (zsh -ic, bash -ic) which take control of the
+/// foreground process group. See https://github.com/nextest-rs/nextest/issues/2878
+/// Workaround: run with NEXTEST_NO_INPUT_HANDLER=1. See CLAUDE.md for details.
#[cfg(unix)]
pub fn native_pty_system() -> Box<dyn portable_pty::PtySystem> {
ignore_tty_signals();