bug: TUI shows a black screen after exiting a sandbox shell

[johntmyers]

Agent Diagnostic

• Skills loaded: tui-development, create-github-issue
• OpenShell version tested: 0.0.82-dev.10+g40194f93 from current main (40194f93)
• Latest release checked: v0.0.80 (published 2026-07-09)
• Known fixes reviewed: reviewed recent TUI history, including fix(tui): route warning logs to status bar instead of stderr (#2210); the shell restoration sequence has been unchanged since the shell feature landed
• Possible duplicates reviewed: searched all issues for TUI black screens, shell exit, alternate-screen restoration, and post-shell refresh behavior. Closed fix(tui): shell connect broken — wrong ssh-proxy CLI arguments after #175 rename #188 concerns incorrect SSH proxy arguments and is not a duplicate
• Findings: reproduced on this Ubuntu host. After the remote exit, OpenShell re-enters and clears the alternate screen, then synchronously runs refresh_data() before the event loop can draw another frame. The refresh consists of several sequential gRPC calls with individual five-second timeouts, leaving an entirely black screen for approximately 20–30 seconds. Once the refresh finishes, the TUI redraws and responds normally
• Remaining reason for filing: the blank screen looks like a terminal deadlock, accepts no visible interaction while refresh is running, and can cause users to kill the TTY even though the process eventually recovers

Description

Actual behavior: After opening a sandbox from openshell term, pressing s for a shell, and running exit, OpenShell switches back to an empty alternate screen. The screen remains black for roughly 20–30 seconds before the TUI eventually reappears. Users can reasonably interpret this as a hung terminal and kill the TTY.

Expected behavior: Exiting the sandbox shell should restore and draw the TUI immediately. Any gateway refresh should happen after a visible frame is rendered, preferably asynchronously without blocking input or rendering.

The current flow handles pending_shell_connect in crates/openshell-tui/src/lib.rs by awaiting handle_shell_connect(), then awaiting refresh_data(). handle_shell_connect() re-enters and clears the alternate screen before it returns. The event loop cannot draw until the synchronous refresh chain completes.

The terminal restoration operations (enable_raw_mode, EnterAlternateScreen, mouse capture, and terminal.clear) also discard errors with let _ = ..., which makes a genuine restoration failure indistinguishable from the refresh delay.

Reproduction Steps

1. Run openshell term.
2. Select a ready sandbox.
3. Press s to open its interactive shell.
4. Run exit.
5. Observe that OpenShell enters a black alternate screen with no visible TUI or feedback.
6. Wait approximately 20–30 seconds; the TUI eventually redraws and is responsive again.

Environment

• OS: Ubuntu 24.04, Linux 6.17.0-1026-nvidia
• Architecture: arm64/aarch64
• Terminal: TERM=xterm-256color
• Docker: 29.2.1
• OpenShell: 0.0.82-dev.10+g40194f93, current main at 40194f93
• Latest release checked: yes, v0.0.80
• Possible duplicates checked: yes; fix(tui): shell connect broken — wrong ssh-proxy CLI arguments after #175 rename #188 is related to shell connect but addresses a different failure

Logs

The PTY output after exit stops immediately after alternate-screen entry and clear, with no frame content until the refresh completes:

exit
<leave bracketed paste mode>
exit
<enter alternate screen>
<enable mouse capture>
<clear screen>
... approximately 20–30 seconds with no output ...
<TUI frame is finally drawn>

[johntmyers]

🏗️ build-plan

Implementation Plan

Issue type: fix
Complexity: Low
Confidence: High — reproduced cause and control flow are explicit

Summary

Restore and paint the TUI synchronously when the SSH child exits, before any gateway RPC refresh can run. Make terminal suspend/resume failures observable instead of silently continuing with a potentially unusable terminal, while retaining the existing post-shell refresh for fresh data after a visible frame exists.

Scope

• crates/openshell-tui/src/lib.rs: make the interactive shell handoff fallible, propagate terminal lifecycle failures, and draw the current UI immediately after terminal restoration and before returning to the caller's synchronous refresh.
• crates/openshell-tui/src/lib.rs: apply equivalent terminal suspend/resume error handling to the create-sandbox exec-command path so both SSH handoffs use consistent lifecycle behavior.
• crates/openshell-tui/src/app.rs: no changes expected.
• crates/openshell-tui/src/event.rs: no changes expected.

Implementation Steps

1. In a new worktree and fix/2229-restore-tui-after-shell/johntmyers branch, refactor the two SSH suspend/resume paths to return miette::Result<()> and propagate raw-mode, alternate-screen, mouse-capture, clear, and draw failures instead of discarding them.
2. After an interactive shell exits, restore the terminal and immediately render ui::draw before resuming event polling and returning to the caller; keep refresh_data() after the handoff so the first visible frame is not delayed by RPC timeouts.
3. Verify the control-flow ordering and exercise repeated shell enter/exit cycles on Ubuntu, including a slow or unavailable gateway, to confirm the TUI appears immediately and remains navigable.

Test Plan

• Unit tests: No new unit test is expected because crossterm raw mode and alternate-screen restoration require a real PTY. Run the existing openshell-tui tests to cover App/UI regressions.
• Integration tests: Manually exercise openshell term in a PTY on Ubuntu: enter a ready sandbox with s, run exit, verify an immediate nonblank frame, then verify keyboard navigation. Repeat several times and with gateway RPC latency/timeouts. Smoke the create-sandbox exec-command restoration path because it shares the lifecycle handling.
• E2E tests: No repository E2E change; current lanes do not drive an interactive terminal and SSH child. Run mise run pre-commit as required.

Risks & Open Questions

• The post-resume refresh remains synchronous and may briefly block input, but painting first fixes the reported black-screen failure. A fully asynchronous refresh would require broader event/data-state changes and is outside this bug's minimal scope.
• Propagating terminal restoration errors may terminate the TUI instead of silently continuing. That is preferable to leaving an apparently hung terminal; outer cleanup behavior must remain correct.
• Event polling should resume only after terminal state restoration and the first successful draw to avoid stdin contention.

Documentation Impact

• None expected. This restores intended behavior without changing commands or the documented UI contract.
• Gateway configuration documentation: no impact; no TOML fields, defaults, Helm rendering, or driver settings change.
• LSM compatibility: no impact; no process identity, /proc, execution semantics, or inter-process visibility changes.

---

Revision 1 — initial plan

[johntmyers]

🏗️ build-from-issue-agent

Implementation Complete

PR: #2230

What was built

The TUI now paints a complete frame immediately after a sandbox shell exits, before post-shell gateway refresh calls can block the event loop. Terminal lifecycle failures are propagated consistently from both SSH handoff paths.

Tests

• Unit: existing openshell-tui suite, 24 passed
• Integration: manual Ubuntu PTY regression passed for shell exit and immediate redraw
• E2E: N/A; no E2E files changed and current lanes do not drive interactive TTY sessions
• Full verification: mise run pre-commit

Docs updated

• None needed; intended behavior was restored without a command or configuration change.

The issue will auto-close when the PR is merged.

[johntmyers]

🏗️ build-from-issue-agent

Follow-up testing found and fixed a second Linux-specific symptom: after the screen returned, stale refresh ticks could starve keyboard events. PR #2230 now clears suspended-state events before resuming input and omits the redundant immediate refresh. Two consecutive Ubuntu shell/exit cycles remained navigable. The reporter confirmed this behavior does not reproduce on macOS.