fix(tui): terminal corrupts to black screen after exiting shell session

[r3v5]

Problem Statement

When using openshell term → selecting a sandbox → pressing [s] Shell → running commands → typing exit, the TUI corrupts to an entirely black screen. The TUI becomes unresponsive and must be force-quit. This affects the core sandbox interaction workflow in the TUI.

Technical Context

The TUI suspends itself before launching an SSH shell subprocess (leaves alternate screen, disables raw mode), then resumes after the subprocess exits (re-enables raw mode, re-enters alternate screen, clears, redraws). The resume path is missing several terminal state restoration steps that are present in other code paths, causing terminal state pollution from the SSH PTY session to persist into the restored TUI.

Affected Components

Component	Key Files	Role
TUI runtime	crates/openshell-tui/src/lib.rs	Terminal lifecycle, shell subprocess suspend/resume
TUI rendering	crates/openshell-tui/src/ui.rs	Frame drawing after resume
SSH utilities	crates/openshell-core/src/forward.rs	SSH command construction, ProxyCommand building

Technical Investigation

Architecture Overview

The TUI uses ratatui with a crossterm backend. Terminal state management follows the standard ratatui pattern:

• Startup (lines 67-73): enable_raw_mode() → EnterAlternateScreen + EnableMouseCapture → Terminal::new() (fresh buffers) → terminal.clear()
• Shutdown (lines 436-443): disable_raw_mode() → LeaveAlternateScreen + DisableMouseCapture → terminal.show_cursor()
• Shell suspend (lines 964-971): LeaveAlternateScreen + DisableMouseCapture → disable_raw_mode()
• Shell resume (lines 991-1003): enable_raw_mode() → EnterAlternateScreen + EnableMouseCapture → terminal.clear() → terminal.draw() → events.discard_pending() → events.resume()

The SSH subprocess is spawned with -tt (force PTY) and RequestTTY=force, inheriting stdin/stdout/stderr. This means the remote shell runs in its own PTY and writes directly to the parent terminal, bypassing ratatui entirely.

Code References

Location	Description
crates/openshell-tui/src/lib.rs:67-73	TUI initialization — creates fresh Terminal with new buffers
crates/openshell-tui/src/lib.rs:436-443	TUI shutdown — includes show_cursor() not present in resume
crates/openshell-tui/src/lib.rs:854-1006	handle_shell_connect() — full shell suspend/resume handler
crates/openshell-tui/src/lib.rs:964-971	Suspend: leave alternate screen + disable raw mode
crates/openshell-tui/src/lib.rs:991-1003	Resume: re-enable raw mode + re-enter alternate screen + clear/draw
crates/openshell-tui/src/lib.rs:936-956	SSH command construction with -tt, RequestTTY=force, Stdio::inherit()
crates/openshell-tui/src/lib.rs:1013-1164	handle_exec_command() — same pattern, same bug
crates/openshell-tui/src/lib.rs:443	Shutdown calls terminal.show_cursor() — resume does not

Current Behavior

1. User presses [s] → app.pending_shell_connect = true (app.rs:1600)
2. Main loop detects flag (lib.rs:145-147), calls handle_shell_connect()
3. TUI suspends: leaves alternate screen, disables raw mode (lines 964-971)
4. SSH spawns via spawn_blocking(move || command.status()) (line 974) — blocks until exit
5. SSH exits, resume begins (line 991+)
6. Raw mode re-enabled, alternate screen re-entered
7. terminal.clear() resets ratatui's internal diff buffers
8. terminal.draw() renders frame — but terminal state is polluted from SSH PTY
9. Result: black screen

What Would Need to Change

The resume path (lines 991-1003) is missing three critical terminal state restoration operations compared to init/shutdown:

1. ResetColor: SSH PTY can leave terminal foreground/background colors in a state where they match (both dark), making all drawn content invisible. The resume path must reset color attributes before drawing.

2. cursor::Show: Present in shutdown (line 443) but absent from resume. If the SSH session or remote application hid the cursor, it stays hidden.

3. Terminal size re-sync: If the user resized their terminal window during the SSH session, the ratatui Terminal object retains stale dimensions. terminal.size() + terminal.resize() is needed to re-query actual dimensions before drawing.

Additionally, a defensive SGR reset (\x1b[0m) before re-entering alternate screen would clear any attribute state (bold, underline, reverse video, character set changes) left by the SSH session.

The same bug exists in handle_exec_command() (lines 1152-1158) which follows the identical resume pattern.

Alternative Approaches Considered

A. Patch the existing resume sequence (minimal fix)
Add ResetColor, cursor::Show, and size re-query to the existing resume code. Lowest risk, keeps the Terminal object alive across suspend/resume.

B. Recreate the Terminal object on resume
Drop the old Terminal and create a new one after SSH exits (like init does). More thorough but loses ratatui's viewport state. Would need to ensure the crossterm backend's stdout handle is still valid.

C. Use ratatui::restore() / ratatui::init() helpers
Modern ratatui (0.28+) provides restore() and init() convenience functions that handle the full terminal lifecycle. Would simplify the suspend/resume code but requires checking the ratatui version in use.

Approach A is recommended — it's the minimal targeted fix with lowest risk.

Patterns to Follow

The shutdown path at lines 436-443 is the reference pattern. The resume code should mirror it in reverse: reset all terminal state, then re-enter TUI mode with a full redraw.

Proposed Approach

Add terminal state reset operations to the resume path in handle_shell_connect(): issue SGR reset, add ResetColor and cursor::Show to the execute! block, re-query terminal size with terminal.size() + terminal.resize(), then proceed with existing clear+draw. Apply the same fix to handle_exec_command(). This is a targeted ~10-line fix in a single file.

Scope Assessment

• Complexity: Low
• Confidence: High — clear path, well-understood terminal state management
• Estimated files to change: 1 (crates/openshell-tui/src/lib.rs)
• Issue type: fix

Risks & Open Questions

• Terminal emulator differences: the exact behavior when re-entering alternate screen with polluted state varies by emulator (Terminal.app, iTerm2, Ghostty, Alacritty). Fix should be defensive enough to work across all.
• The handle_exec_command() function has the same bug and should be fixed in the same PR.
• Testing: this requires manual testing with an actual sandbox SSH session — no automated test can verify terminal visual output.

Test Considerations

• Manual test: openshell term → select sandbox → [s] Shell → run commands → exit → verify TUI renders correctly
• Edge cases: resize terminal during SSH session, then exit — verify TUI adapts to new size
• Edge case: Ctrl+C out of SSH session (abnormal exit) — verify TUI still recovers
• Both code paths: test [s] Shell interactive and exec command paths
• Multiple terminals: test on at least 2 terminal emulators (e.g., iTerm2 + Terminal.app, or Ghostty + Alacritty)

---

Created by spike investigation. Use build-from-issue to plan and implement.

[r3v5]

📋 triage-agent

Triage Assessment

Classification: bug-confirmed

Summary

Terminal state corruption after SSH shell exit is a real defect. The resume path in handle_shell_connect() and handle_exec_command() is missing terminal reset operations that are present in the shutdown path. All code references in the spike are accurate against current main.

Investigation

Verified three gaps in crates/openshell-tui/src/lib.rs:

1. Resume (lines 991-1003) — missing ResetColor, cursor::Show, and terminal size re-sync after SSH PTY exit. Shutdown (line 443) includes show_cursor() but resume does not.
2. handle_exec_command() resume (lines 1152-1161) — same missing operations AND additionally missing the terminal.draw() call entirely. After terminal.clear() it jumps straight to events.discard_pending() with no redraw. This is a second, worse instance of the same bug.
3. SSH spawned with -tt + RequestTTY=force + Stdio::inherit() — remote PTY writes directly to parent terminal, bypassing ratatui buffers. Any terminal mode pollution (colors, cursor visibility, character sets) persists into the resumed TUI.

Recommendation

Ready for implementation. Low complexity (~10-line fix), single file, high confidence. The spike correctly identifies Approach A (patch existing resume sequence) as the right fix. The additional handle_exec_command missing-draw finding should be included in the same fix.

[r3v5]

Hi! I'd like to work on the fix.

[r3v5]

Additional Investigation: Crossterm Version Mismatch (Critical Root Cause)

Further analysis uncovered the likely root cause beyond the missing terminal reset operations:

Two crossterm runtimes in one binary

• Workspace declares crossterm = "0.28" → resolves to crossterm 0.28.1
• ratatui 0.26.3 depends on crossterm 0.27.0
• Both versions are linked into the binary with independent static state (raw mode tracking, saved terminal attributes, internal event reader)

This means:

• enable_raw_mode() / disable_raw_mode() called by TUI code goes through crossterm 0.28.1
• CrosstermBackend methods (via terminal.clear(), terminal.draw()) go through crossterm 0.27.0
• Raw mode state bookkeeping diverges across the suspend/resume boundary

When disable_raw_mode() is called via 0.28.1 before SSH, crossterm 0.27.0 internal state never records that raw mode was disabled. When enable_raw_mode() is called via 0.28.1 after SSH, the terminal attributes saved/restored by each version diverge. The backend (0.27.0) operates on stale terminal state assumptions.

Verified in Cargo.lock

[[package]]
name = "crossterm"
version = "0.27.0"   ← used by ratatui backend

[[package]]
name = "crossterm"
version = "0.28.1"   ← used by TUI code directly

[[package]]
name = "ratatui"
version = "0.26.3"
dependencies = ["crossterm 0.27.0"]

Additional findings

1. Race condition in event handler pause (event.rs:80-88): Ordering::Relaxed on ARM64 (Apple Silicon) provides no store-load ordering guarantees. Pause flag may not be visible to reader thread before it enters event::poll().

2. Missing terminal.draw() in handle_exec_command (lib.rs:1152-1161): Already noted in triage — resume clears but never redraws, leaving blank screen for up to 2s until next tick.

3. No stdin drain after SSH exit: Stale bytes from remote PTY remain in stdin fd buffer. events.discard_pending() only clears the mpsc channel, not crossterm parser buffer or fd buffer.

Recommended fix priority

1. Align crossterm versions — either pin workspace to crossterm = "0.27" to match ratatui 0.26.3, or upgrade ratatui to a version that uses crossterm 0.28. This is the highest-impact fix.
2. Add missing terminal reset ops — ResetColor, cursor::Show, terminal size re-sync in both resume paths.
3. Add missing terminal.draw() in handle_exec_command resume.
4. Fix pause ordering — use Ordering::Release/Acquire for pause flag.

[r3v5]

Revised Root Cause Analysis

After deeper tracing through crossterm call sites and ratatui buffer internals, the root cause assessment has been refined.

Crossterm version mismatch: downgraded from Critical to Warning

Two crossterm versions exist (0.27.0 via ratatui, 0.28.1 via workspace), but all enable_raw_mode()/disable_raw_mode()/execute!()/event::poll() calls go through 0.28.1 consistently. Ratatui's 0.27.0 is only used for rendering (Write trait ops) — no state divergence occurs today. Still a maintenance hazard that will bite on ratatui upgrade with Drop-based cleanup.

Ratatui buffer management: verified correct

Traced through ratatui 0.26.3 source — Terminal::clear() resets the back buffer, then Terminal::draw() diffs against it producing a full repaint of all non-blank cells. The clear() + draw() sequence at lib.rs:998-1001 is correct. The TUI renders successfully after SSH exit.

Actual root cause: stale stdin + crossterm parser corruption

The TUI likely draws correctly but appears frozen/black because key input is dead:

1. SSH with -tt allocates remote PTY, forwards I/O to local terminal
2. During SSH shutdown, terminal restore sequences may produce response bytes (DSR responses, echo) into stdin
3. SSH exits → command.status() returns → main task wakes
4. events.discard_pending() clears the mpsc channel only — NOT:
   • Stdin file descriptor buffer (kernel-side)
   • Crossterm 0.28.1's internal InternalEventReader parser state
5. events.resume() starts polling again
6. Event handler reads stale bytes from stdin → feeds them to crossterm escape sequence parser
7. Partial escape sequence (e.g., \x1b[ without terminator) causes parser to buffer and wait
8. Subsequent real key presses are appended to the partial sequence buffer and consumed as escape sequence data instead of producing key events
9. Result: TUI renders but all input is swallowed → appears unresponsive/black

Compounding factor: pause race condition on ARM64

Ordering::Relaxed on the pause flag (event.rs:80) provides no store-load guarantees on Apple Silicon (weak memory model). Event handler can enter poll() after main task disables raw mode, causing spurious wakeups and malformed reads that further corrupt parser state.

Revised fix priority

Priority	Fix	Impact
P0	Drain stdin fd after SSH exits, before resuming event reader	Fixes root cause — eliminates stale bytes
P1	Add terminal.draw() to handle_exec_command resume (lib.rs:1159)	Fixes blank screen on exec path
P2	Upgrade Ordering::Relaxed → Release/Acquire on pause flag	Fixes ARM64 race condition
P3	Align crossterm versions in workspace	Prevents future breakage

Files to change

File	Change
crates/openshell-tui/src/lib.rs:974-991	Add stdin drain between SSH exit and resume
crates/openshell-tui/src/lib.rs:1135-1152	Same stdin drain in handle_exec_command
crates/openshell-tui/src/lib.rs:1159	Add missing terminal.draw()
crates/openshell-tui/src/event.rs:63,80,135,139,142	Ordering::Relaxed → Release/Acquire
Cargo.toml (workspace)	Align crossterm version with ratatui

[johntmyers]

What version does this happen in? #2230 Recently merged so am curious if this is a net new issue

[r3v5]

What version does this happen in? #2230 Recently merged so am curious if this is a net new issue

I have caught this bug on main branch today.