hermes - 💡(How to fix) Fix TUI freezes when typing @ character — complete.path RPC timeout blocks stdio pipe [1 pull requests]

Bug Description

Typing a single @ character in the Hermes TUI input field causes the entire TUI to freeze for ~120 seconds, eventually showing error: timeout: prompt.submit or error: timeout: complete.path. During the freeze, all user input is unresponsive.

Reproduction Steps

1. Open Hermes TUI (hermes --tui)
2. Type a single @ character in the input field
3. A completion overlay appears showing: @diff, @file:, @folder:, @url:, @git:
4. Press Escape to dismiss the overlay (or wait)
5. TUI becomes completely frozen — no input is accepted
6. After ~120 seconds: error: timeout: prompt.submit or error: timeout: complete.path

Root Cause Analysis

Traced through the source code:

1. Trigger: ui-tui/src/hooks/useCompletion.ts L12 — TAB_PATH_RE regex includes @, so typing @ triggers complete.path RPC request to tui_gateway.

2. RPC handler: tui_gateway/server.py L4801 — complete.path method returns the list @diff/@file:/@folder:/@url:/@git:.

3. Timeout: ui-tui/src/gatewayClient.ts L15 — REQUEST_TIMEOUT_MS = 120000 (120 seconds). L233 onTimeout rejects with timeout: {method}.

4. Blocking: When the completion overlay is dismissed but the RPC response hasn't arrived, the pending RPC request blocks the stdio pipe. All subsequent RPCs (including prompt.submit) are queued behind the stalled request, making the entire TUI unresponsive.

5. No match: agent/context_references.py L17 — REFERENCE_PATTERN requires @ followed by a known keyword (diff, file:, folder:, etc.). A bare @ matches nothing, so the completion is useless but the RPC still fires.

6. Overlay not blocked: ui-tui/src/app/overlayStore.ts — completion overlay is not in the $isBlocked control set (only approval/clarify/confirm/modelPicker/pager/picker/skillsHub/sudo are blocked), so it cannot prevent the deadlock scenario.

Suggested Fixes

1. Quick fix: In useCompletion.ts, skip the complete.path RPC when input is just a bare @ (no following keyword character). Return an empty completion list immediately.

2. Shorter timeout: Give complete.path RPCs a much shorter timeout (e.g., 5 seconds) instead of the default 120s, since path completion should be fast.

3. Non-blocking RPC: Ensure completion RPCs don't block the main stdio pipe for other operations like prompt.submit.

Environment

• Hermes v0.12.0
• WSL2 Ubuntu 22.04
• TUI mode