[GH-ISSUE #99] fix(tui): TUI hangs on startup due to signal handler deadlock (macOS) #42

New issue

Closed

opened 2026-02-27 10:21:54 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 10:21:54 +03:00

Owner

Originally created by @memyselfandm on GitHub (Jan 23, 2026).
Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/99

Summary

Ralph hangs silently on startup when TUI is enabled (default behavior), but works correctly with --no-tui flag. This regression was introduced in v2.2.1.

Environment

Version: v2.2.1 (worked in v2.2.0)
OS: macOS (Darwin 25.1.0)
Terminal: iTerm2
Backend: Claude

Reproduction

# Hangs silently - no output
ralph run -p "test"

# Works correctly
ralph run -p "test" --no-tui

Expected Behavior

TUI should initialize and display the Ralph header, iteration info, and begin orchestration.

Actual Behavior

Process hangs silently with no output
No TUI renders
No error messages
Ctrl+C shows prompt in verbose mode, indicating hang occurs before orchestration begins

Root Cause

Deadlock between tokio signal handlers and crossterm TUI initialization on macOS.

Problematic sequence in crates/ralph-cli/src/loop_runner.rs:

Lines 84-117: Spawn tokio tasks for ctrl_c(), SIGTERM, and SIGHUP signal handling
Line 243: Spawn TUI task which calls tui.run().await
Inside TUI (crates/ralph-tui/src/app.rs:114-131):
- Calls enable_raw_mode()
- Calls EventStream::new()

On macOS, when tokio signal handlers are already registered and crossterm tries to enable raw mode or create an EventStream, a deadlock occurs.

Introduced By

Refactor in commit f0af5d6 (PR #97) which modularized loop_runner.rs changed the signal setup order/TUI initialization sequence.

Proposed Fix

Move signal handler registration to AFTER TUI initialization completes (after the 100ms sleep at line 253).

This ensures:

TUI enters raw mode and creates EventStream first
Signal handlers are registered afterwards
No conflict between tokio signals and crossterm event handling

Workaround

Use --no-tui flag until fix is available:

ralph run -p "your prompt" --no-tui

Originally created by @memyselfandm on GitHub (Jan 23, 2026). Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/99 ## Summary Ralph hangs silently on startup when TUI is enabled (default behavior), but works correctly with `--no-tui` flag. This regression was introduced in v2.2.1. ## Environment - **Version**: v2.2.1 (worked in v2.2.0) - **OS**: macOS (Darwin 25.1.0) - **Terminal**: iTerm2 - **Backend**: Claude ## Reproduction ```bash # Hangs silently - no output ralph run -p "test" # Works correctly ralph run -p "test" --no-tui ``` ### Expected Behavior TUI should initialize and display the Ralph header, iteration info, and begin orchestration. ### Actual Behavior - Process hangs silently with no output - No TUI renders - No error messages - Ctrl+C shows prompt in verbose mode, indicating hang occurs before orchestration begins ## Root Cause Deadlock between tokio signal handlers and crossterm TUI initialization on macOS. **Problematic sequence** in `crates/ralph-cli/src/loop_runner.rs`: 1. **Lines 84-117**: Spawn tokio tasks for `ctrl_c()`, `SIGTERM`, and `SIGHUP` signal handling 2. **Line 243**: Spawn TUI task which calls `tui.run().await` 3. **Inside TUI** (`crates/ralph-tui/src/app.rs:114-131`): - Calls `enable_raw_mode()` - Calls `EventStream::new()` On macOS, when tokio signal handlers are already registered and crossterm tries to enable raw mode or create an EventStream, a deadlock occurs. ## Introduced By Refactor in commit `f0af5d6` (PR #97) which modularized `loop_runner.rs` changed the signal setup order/TUI initialization sequence. ## Proposed Fix Move signal handler registration to AFTER TUI initialization completes (after the 100ms sleep at line 253). This ensures: 1. TUI enters raw mode and creates EventStream first 2. Signal handlers are registered afterwards 3. No conflict between tokio signals and crossterm event handling ## Workaround Use `--no-tui` flag until fix is available: ```bash ralph run -p "your prompt" --no-tui ```