[Bug]: TUI leaves terminal in corrupted state after clean /quit — breaks legacy ncurses apps (e.g. nano); survives stty sane and manual escape-sequence resets, requires full reset

[calamityclay]

Bug Description

After exiting the Hermes TUI via a normal /quit command, the terminal session is left in a corrupted state. Any subsequent legacy ncurses program run in the same terminal pane — confirmed with nano — receives raw, unparsed escape sequence fragments (e.g. 0;133u, ;129u) as literal text input instead of having them interpreted as control keys (Ctrl+X, Ctrl+O, etc.).

What doesn't fix it (tried and confirmed insufficient):
stty sane
printf '\033[<u\033[>4;0m' (pop kitty keyboard protocol stack)
printf '\033[=0u\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l' (explicit zero of keyboard protocol flags + disable mouse tracking modes + disable bracketed paste)

What does fix it:
Running the full reset command. This suggests the corruption isn't limited to the keyboard protocol or mouse tracking flags specifically — something more fundamental about terminal mode state isn't being restored on exit.

Steps to Reproduce

1. SSH into a Hermes host using a terminal with kitty keyboard protocol support (Kitty terminal, via SSH kitten).
2. Confirm nano works normally beforehand — Ctrl+X exits cleanly.
3. Launch hermes --tui.
4. Exit the TUI using the /quit slash command (not Ctrl+C, not a crash — a clean exit).
5. Immediately run nano again in the same terminal session.
6. Attempt Ctrl+X / Ctrl+O / Esc — instead of triggering nano's commands, raw fragments like 0;133u are inserted into the document as text.

Expected Behavior

On exit (including via /quit), the TUI should pop any keyboard protocol mode it pushed on entry, returning the terminal to its prior state — the same way it presumably already tries to do for alt-screen/cursor state.

Actual Behavior

After exiting the Hermes TUI via a normal /quit command, the terminal session is left in a corrupted state. Any subsequent legacy ncurses program run in the same terminal pane — confirmed with nano — receives raw, unparsed escape sequence fragments (e.g. 0;133u, ;129u) as literal text input instead of having them interpreted as control keys (Ctrl+X, Ctrl+O, etc.).

Affected Component

Other

Messaging Platform (if gateway-related)

No response

Debug Report

Report       https://paste.rs/7wgsn
  agent.log    https://paste.rs/0UsKt
  gateway.log  https://paste.rs/KrWfZ
  gui.log      https://paste.rs/HmHAf

Operating System

Ubuntu 24.04.4 LTS (Proxmox-hosted VM)

Python Version

3.11.15

Hermes Version

0.18.0

Additional Logs / Traceback (optional)

Terminal: Kitty (via SSH kitten)
Client OS: Windows 11, WSL2 Ubuntu
nano version: 7.2

Root Cause Analysis (optional)

Given reset's bluntness works while targeted escape sequences don't, this may point to multiple stacked pushes of the same mode (unwound by reset but not a single pop), or a terminal mode outside the ones tested above. Worth checking whatever exit/cleanup path /quit runs versus what a bare terminal disable_raw_mode()-style teardown would do.

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR

[GottZ]

This was generated by AI during triage.

Summary

Three PRs address or reference this terminal-corruption complex, but none currently verifies the reported root cause: #19210 established the historical all-exit cleanup path, #56765 adds a keyboard-protocol reset already reported as insufficient, and #57161 changes shutdown ordering without yet proving that its reset is the final terminal output.

Related pull requests

• fix(tui): restore terminal modes on all exit paths #19210 [closed] unrelated — (+13/-0) — unrelated to the current regression, but relevant as the closed historical reference implementation salvaged into fix(tui): restore terminal modes on all exit paths #19589: it added an explicit process exit and an exit-handler reset for [Bug]: hermes leaves fish shell in a broken state after /quit #19194, establishing the cleanup path on which the newer proposals operate rather than resolving [Bug]: TUI leaves terminal in corrupted state after clean /quit — breaks legacy ncurses apps (e.g. nano); survives stty sane and manual escape-sequence resets, requires full reset #56759's remaining corruption.
• fix: kitty keyboard protocol corruption after TUI /quit #56765 unrelated — (+13/-0) — unrelated as a demonstrated fix: it appends CSI = 0 u after the Kitty stack pop, but [Bug]: TUI leaves terminal in corrupted state after clean /quit — breaks legacy ncurses apps (e.g. nano); survives stty sane and manual escape-sequence resets, requires full reset #56759 explicitly reports that this sequence was insufficient and the diff contains no reproduction proving the proposed stack-depth cause. Despite the keep_open review on fix: kitty keyboard protocol corruption after TUI /quit #56765, its own review identifies this mismatch and directs verification and re-scoping rather than supporting the current diff for merge.
• fix(tui): reset terminal modes before Ink unmount to prevent kitty keyboard leak (#56759) #57161 best fix — (+11/-0) — partial fix and best consolidation target: it synchronously resets terminal modes in both die() and dieWithCode() before Ink teardown, directly targeting the /quit shutdown path. The keep_open review on fix(tui): reset terminal modes before Ink unmount to prevent kitty keyboard leak (#56759) #57161 must be addressed before merge: because Ink can emit buffered POP+PUSH output during teardown, the current placement does not prove that the reset is final; the PR needs post-teardown ordering and a queued-output regression covering both exit paths.

Duplicates

No exact duplicates: #56765 changes Kitty flag-reset semantics, while #57161 changes shutdown ordering; #19210 is a closed historical cleanup implementation rather than the same current change.

Suggested consolidation

Merge #57161 only after addressing its keep_open review by ensuring the final synchronous reset occurs after teardown and any reasserting output, with a regression proving final byte ordering for both die() and dieWithCode(). Then close #56765 as an unsupported competing fix rather than as an exact duplicate; #19210 remains closed and relevant only as the implementation lineage salvaged through #19589.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I19194(["issue #19194 (closed)"])
    I56759(["issue #56759 (open)"])
    P19210["PR #19210 (closed)"]
    P57161["PR #57161 (open)"]
    P57161 -->|best fix| I56759
    P19210 -->|best fix| I19194
    class I19194 closed
    class I56759 open
    class I56759 target
    class P19210 closed
    class P57161 open
    class P19210 best
    class P57161 best
    click I19194 "https://github.com/NousResearch/hermes-agent/issues/19194"
    click I56759 "https://github.com/NousResearch/hermes-agent/issues/56759"
    click P19210 "https://github.com/NousResearch/hermes-agent/pull/19210"
    click P57161 "https://github.com/NousResearch/hermes-agent/pull/57161"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 3 pull requests and 2 issues in this complex. Each diff was read against this issue; Assessment working set: 5 kB of PR diffs, 10 kB of issue/PR text, 5 kB of discussion (7 comments), 8 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.