CNA-GAP-055: TerminalSession does not restore or re-establish the terminal on job-control stop and continue (SIGTSTP/SIGCONT)

CNA snapshot 009d40f5  ·  Known Issues › Functional gaps  ·  source links pinned to 009d40f5

The session's restoring signal set covers termination and crash signals but not SIGTSTP/SIGCONT, so a Ctrl-Z that suspends a terminal game leaves the terminal in raw mode, the alternate screen and mouse reporting until the process is resumed.

Identifier

CNA-GAP-055

Category

Functional gap

Subsystem

Platforms

Status

Open

Verified against

CNA 009d40f5 (009d40f5dd085c4e674d3479675fac84b12b3e0a)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

CNA::Platform::Terminal::TerminalSession terminal restoration on job-control signals

Expected behaviour

The session's whole purpose is that a terminal game never leaves the user with a broken terminal: it restores on normal exit, on SIGINT/SIGTERM/SIGHUP/SIGQUIT, on SIGABRT and the hard-crash signals, and on an uncaught exception. Job-control suspend (Ctrl-Z → SIGTSTP) leaves the process alive but stopped, with the terminal still owned; a robust interactive terminal program restores cooked mode and the main screen while suspended and re-enters its session on SIGCONT.

Actual behaviour at TARGET

kRestoringSignals is {SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGABRT, SIGSEGV, SIGBUS, SIGFPE, SIGILL}. SIGTSTP and SIGCONT are absent, and raw mode clears ISIG, so the terminal driver will not even generate SIGTSTP from Ctrl-Z while the game runs; a SIGTSTP sent to the process group by other means stops the process with the alternate screen up, the cursor hidden, mouse reporting on and the line discipline in raw mode. The shell that regains the foreground sees that state until the game is continued.

Source locations

• modules/platform/src/Terminal/TerminalSession.cpp — kRestoringSignals (no SIGTSTP/SIGCONT); raw mode clears ISIG

Evidence

Checked by reading TerminalSession.cpp's signal set and raw-mode setup at 009d40f5. Not executed. The Development terminal page states the limit explicitly (“SIGTSTP and SIGCONT are not in the restoring set”), and CNA's own terminal feasibility analysis lists the restoration signals without SIGTSTP, so this is a scoped, currently-unimplemented behaviour rather than a contradiction of a stated contract.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

TerminalRestorationTests.cpp drives the restoring signals and the forced-exit limit; no case covers suspend/continue.

Regression test

A pseudo-terminal harness that sends SIGTSTP to a session, checks the terminal is restored to cooked mode and the main screen while stopped, sends SIGCONT, and checks the session's prologue is re-emitted.

Blast radius

Interactive terminal games suspended by job control (mainly where something sends SIGTSTP, since raw mode disables the Ctrl-Z keystroke path). The termination and crash paths are handled.

Workaround

Resume the game (fg) to restore the terminal; avoid suspending a running terminal game.