Skip to content

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

Add nextest SIGTTOU guidance to config and docs

Maximilian Roos7184be83f12e
diff --git a/.config/nextest.toml b/.config/nextest.toml
index 1bc1b8d54..9d7e17dad 100644
--- a/.config/nextest.toml
+++ b/.config/nextest.toml
@@ -1,3 +1,18 @@
+# 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.
+#
+# Solution: Run with NEXTEST_NO_INPUT_HANDLER=1 or use the pre-merge hook which
+# sets this automatically:
+#
+# NEXTEST_NO_INPUT_HANDLER=1 cargo nextest run --features shell-integration-tests
+#
+# 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 b3ea6b709..5e3e3dbc9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,17 +82,23 @@ This installs required shells (zsh, fish) for shell integration tests and builds
### Shell/PTY Integration Tests
-PTY-based tests (approval prompts, TUI select, progressive rendering, shell wrappers) are behind the `shell-integration-tests` feature. These tests can trigger a nextest bug where its terminal cleanup receives SIGTTOU. See `native_pty_system()` in `tests/common/mod.rs` for details.
+PTY-based tests (approval prompts, TUI select, progressive rendering, shell wrappers) are behind the `shell-integration-tests` feature.
-```bash
-# Default: runs without PTY tests
-cargo nextest run
+**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.
-# Full suite: requires env var to prevent nextest suspension
-NEXTEST_NO_INPUT_HANDLER=1 cargo nextest run --features shell-integration-tests
-```
+**Solutions:**
+
+1. Use `cargo test` instead of `cargo nextest run` (no input handler issues):
+ ```bash
+ cargo test --test integration --features shell-integration-tests
+ ```
+
+2. Or set `NEXTEST_NO_INPUT_HANDLER=1`:
+ ```bash
+ NEXTEST_NO_INPUT_HANDLER=1 cargo nextest run --features shell-integration-tests
+ ```
-The pre-merge hook already sets `NEXTEST_NO_INPUT_HANDLER=1`.
+The pre-merge hook (`wt hook pre-merge --force`) already sets `NEXTEST_NO_INPUT_HANDLER=1` automatically. See `tests/common/mod.rs` for technical details on the SIGTTOU issue.
## Command Execution Principles