hermes - 💡(How to fix) Fix [Bug]: TUI freezes — stdin handler unresponsive while agent continues in background

Bug Description

The TUI session can enter an unresponsive state where stdin handling stops servicing keystrokes (no echo, Enter / Ctrl-C have no effect) while the agent itself is still actively progressing in the background — sqlite is being updated, LLM calls succeed, tool calls run. The only way out is to refresh the dashboard tab (or kill the CLI process) and /resume the session, which loses any in-flight context not yet flushed to the database.

This makes long autonomous tasks unreliable: a freeze can land in the middle of a multi-step plan and force a recovery cycle. There is a companion skill the user has built specifically to recover lost context from sqlite after such freezes — that mitigation works, but the underlying freeze is a real obstacle to long-task stability.

Steps to Reproduce

No reliable repro. The freeze appears intermittently across both CLI (hermes chat) and dashboard PTY (hermes dashboard --tui

• browser xterm.js), with no clear pattern that distinguishes freeze-frames from healthy ones. It tends to surface during long- running sessions with frequent message arrival (autonomous goal loops, streaming tool output) but is not exclusive to those.

Two distinct bug shapes have been observed; they may be the same root cause manifesting differently:

1. Viewport-wipe (covered by #27282 and partially by PR #31430): on dashboard /chat?resume=<long_session>, the inline-mode TranscriptPane initially mounts a multi-thousand-row empty <Box> (the topSpacer from useVirtualHistory), which log-update.ts:renderFrameSlice flushes one CR+LF per row. The xterm.js scrollback ring rolls over and the cursor lands far below the visible viewport.

2. Stdin freeze (this report): during a live session, after some indeterminate trigger, keystrokes stop reaching the agent loop. The agent loop itself keeps running — visible in agent.log — but the frontend (CLI's ink renderer or the dashboard PTY) no longer accepts input. Restart is required.

PR #31430 caps the rendered tree at the most recent 200 items in inline mode; that demonstrably fixes the resume-time mount flood, but does not address the stdin freeze. The freeze is also reproducible in plain CLI where INLINE_MODE is off.

Expected Behavior

The TUI should never wedge stdin while the agent loop continues to run. Either:

• Stdin handling should remain responsive regardless of how busy / contended the renderer or stdout path becomes
• Or the freeze should be detected and surface a visible status indicator + an automatic recovery path that reattaches input without requiring a full process restart

Actual Behavior

• Keystrokes have no visible effect (no echo, no command activation, Ctrl-C / Enter ignored)
• agent.log shows the agent loop is alive: API calls keep landing with sequential API call #N, tool calls complete, Turn ended events are emitted
• sqlite session DB keeps gaining rows
• Refreshing the browser tab (dashboard) or killing the CLI process is the only way out
• After restart, hermes resume loads the session from sqlite and the latest in-flight work that was already persisted is back
• Any not-yet-persisted state (e.g. the in-progress reply that was streaming when the freeze hit) is lost — recoverable from agent.log if the user has a recovery routine, but not out-of-the-box

Affected Component

• CLI (interactive chat)
• Other (dashboard PTY at hermes dashboard --tui + browser xterm.js)

Messaging Platform (if gateway-related)

N/A (CLI only)

Debug Report

Report       https://paste.rs/uAHAp
agent.log    https://paste.rs/Z7TS3
gateway.log  https://paste.rs/WOx8i

Operating System

Ubuntu 24.04 (WSL2 on Windows 11)

Python Version

3.11.15

Hermes Version

0.14.0 (2026.5.16) [d3ec78e2]

Additional Logs / Traceback (optional)

The most recent CLI freeze coincided with a long autonomous goal-loop session. agent.log segments around the freeze show API call #N streaming completing normally and Turn ended events firing afterward; nothing in the log suggests the renderer noticed an issue. The user's frontend reported "cannot type, Ctrl-C does nothing" while those log lines were being written.

Root Cause Analysis (optional)

Suspected root-cause direction (not confirmed — would benefit from a maintainer with renderer-internal context):

The freeze is consistent with the stdin readable handler being permanently blocked — not a render correctness bug, a flow-control bug. Three shapes seem plausible:

• Stdin handler statically removed by a swallowed exception. App.tsx:handleReadable has a try/catch that re-attaches the readable listener after exceptions, but only when `rawModeEnabledCount

  0`. If raw-mode is reset to 0 inside an error path the listener goes away permanently and stdin data piles up in the buffer with nobody to drain it.

• Stdout backpressure stuck waiting on drain. If a frame's writeDiffToTerminal chunk stays unacknowledged by Node (e.g. host terminal parser is overwhelmed by a CR+LF burst — exactly the kind of burst PR #31430 reduces but does not eliminate), the ink loop can be stuck in a state where it won't accept further work.
• React render saturating the event loop. A microtask-only render path (scheduleRender → queueMicrotask(this.onRender)) combined with self-rescheduling (immediateRerenderRequested, scrollDrainPending) could in theory monopolize the event loop and starve the stdin readable callback. The drain-tick fast path (setTimeout(() => this.onRender(), FRAME_INTERVAL_MS >> 2)) helps but is gated on frame.scrollDrainPending.

py-spy / kill -USR1 <pid> traces from a live freeze would disambiguate. Reporting without those because the freeze is too intermittent to have one captured yet.

PR #31430 (the inline-mode CR+LF reduction) was specifically scoped to viewport-wipe-on-resume. It does not claim to address this freeze. Whether the two share a root cause is the most important open question for triage.

Proposed Fix (optional)

Not proposing a fix — this needs a maintainer with renderer-internal context to triage whether the freeze and the viewport-wipe are the same root cause, and what the right invariant to enforce is. Happy to provide more data (py-spy dump, node --inspect heap snapshot, strace) if a freeze is captured live.

Are you willing to submit a PR for this?

Not committing to a PR for this report. Already submitted #31430 for the related viewport-wipe issue; this freeze is separate, root cause not yet confirmed, and the change surface is likely renderer-internal (hermes-ink) rather than application-layer.

AI-assisted: drafted with Claude based on user reports and code inspection.