TUI-freeze-Windows-crossterm-poll

[aboimpinto]

Summary

DeepSeek TUI v0.8.39 freezes intermittently on Windows 11. The UI becomes completely unresponsive — no keyboard input, no screen updates — but the process stays alive (not crashed). Two confirmed events captured with logs, session files, and thread-state analysis.

Freeze Event #1 — 2026-05-19 ~02:12 CEST

Trigger: Model ran pnpm build in a Next.js project. The 5KB build output (Prisma errors + Next.js route table with Unicode box-drawing characters) was fed back as a tool result. The model streamed a response for ~8 minutes (00:10–00:17 UTC). The TUI froze during or after this long streaming period. The model's response was never saved to the session file.

Session file: Captures pre-freeze state — 182 messages, last message is the pnpm build output. The model's reply (message 183) is missing.

Freeze Event #2 — 2026-05-19 ~08:50 CEST (diagnosed in detail)

Trigger: Five rapid exec_shell calls in 51 seconds:

1. npm config get npm-globalconfig ... — failed
2. set | findstr /i "npm_ jsr..." — failed
3. Third npm investigation command — failed
4. Fourth command — succeeded
5. dir /s /b "%APPDATA%\npm\*npmrc*" ... — succeeded (97 bytes output)

The TUI froze after all five commands completed but before the model's streaming response (MessageStarted) was processed. The model never rendered any output.

Log evidence: Exact exec_shell calls matched by input_bytes size and timestamps to visible screen content. No MessageStarted was processed by the TUI event loop.

Thread-State Analysis (PID 141448, captured 5h post-freeze)

Metric	Value
Threads	35 (28 at startup, 6 new threads created 5h later)
State	Wait - UserRequest (main thread)
Windows Responding	true (not flagged as hung)
Working set	81.5 MB

Key finding: The main thread is stuck in Wait - UserRequest, consistent with crossterm::event::poll() → WaitForSingleObject(console_input_handle, INFINITE). The Windows console input handle has stopped delivering events. Meanwhile, the tokio runtime is still alive — it spawned 6 new worker threads 5 hours after the freeze, proving async code (engine, HTTP) continues to function.

Root Cause Hypothesis

Windows console input handle starvation after child process exit.

Each exec_shell call creates a child process via CreateProcess. On Windows, child processes can briefly attach to the parent's console. If a child exits while the console input buffer is in an inconsistent state, the parent's WaitForSingleObject on the console input handle may hang indefinitely — crossterm::event::poll() calls this internally and never returns.

This is consistent with:

• Freeze happening right after rapid exec_shell calls
• Main thread blocked at OS boundary, not in Rust code
• Process otherwise healthy (tokio still running)
• Windows-specific (Unix doesn't have this console input handle model)

Suggested Fix Directions

1. Bounded event poll timeout: Instead of event::poll(INFINITE), use a short timeout (e.g., 100ms). If the poll consistently times out with no events for >5 seconds while the engine has pending work, force a terminal mode recovery: re-enable raw mode, re-arm event listening.

2. Post-exec_shell console flush: After each exec_shell completes, call FlushConsoleInputBuffer(GetStdHandle(STD_INPUT_HANDLE)) via windows-sys to clear any stale state left by the child process.

3. Watchdog thread: Spawn a separate thread that monitors the event loop heartbeat. If no events are processed for >10 seconds, trigger terminal recovery or graceful shutdown.

Environment

• OS: Windows 11
• Terminal: Windows Terminal (WT_SESSION present)
• DeepSeek TUI version: 0.8.39
• Mode: YOLO (auto-approve)
• Model: deepseek-v4-pro
• Branch: feat/combined-local-build (local diagnostic logging added, not pushed)

Files Available

• Log file with exact exec_shell timestamps and byte sizes
• Session file (Event Fix cargo fmt formatting issues #1) with pre-freeze state
• Frozen process still running (PID 141448) — can capture minidump with procdump -ma on request
• Full investigation document with both event timelines

[GoldenSupremeSaltedFish]

I'd like to help fix this Windows TUI freeze issue.

I can reproduce the problem on Windows 11, and I fully understand the root cause: crossterm's infinite event::poll() gets stuck because the console input buffer state is corrupted after child shell processes exit.

I'm ready to implement the proposed fixes:

1. Add a bounded timeout to crossterm poll
2. Flush the console input buffer after exec_shell
3. Implement a watchdog thread for the event loop

Please let me know how I can contribute or take this task.

[aboimpinto]

I've implemented the three proposed fixes as proof-of-concept branches. Each is based on clean v0.8.39 so you can test them independently.

---

Branches (all on aboimpinto/DeepSeek-TUI)

Fix	Branch	What it does
1. Bounded poll timeout + stall detection	fix/1812-bounded-poll-timeout	Counts consecutive empty event polls. At 5s with engine busy, forces terminal recovery
2. Console input buffer flush	fix/1812-console-flush-after-exec	Calls FlushConsoleInputBuffer(STD_INPUT_HANDLE) after every exec_shell child exits
3. Watchdog thread	fix/1812-watchdog-thread	Spawns a separate thread that checks a heartbeat timestamp every 1s. At 10s stall, signals recovery

All three also include the fix from PR #1776 (stop RUST_LOG from leaking into TUI alt-screen on Windows) so the TUI display stays clean during testing.

---

How to build and run

# Clone my fork
git clone https://github.com/aboimpinto/DeepSeek-TUI.git
cd DeepSeek-TUI

# Pick one branch:
git checkout fix/1812-bounded-poll-timeout       # Fix 1
git checkout fix/1812-console-flush-after-exec   # Fix 2
git checkout fix/1812-watchdog-thread            # Fix 3

# Build (release recommended for realistic timing)
cargo build --release

# Run with verbose logging to see the fix in action:
$env:RUST_LOG = "tui_freeze=debug,info"
.\target\release\deepseek.exe --yolo

Log file: ~/.deepseek/logs/tui-YYYY-MM-DD.log

---

What to look for in the logs

Get-Content "$env:USERPROFILE\.deepseek\logs\tui-2026-05-19.log" -Tail 100 | Select-String "tui_freeze"

Log message	Which fix	Meaning
Flushed Windows console input buffer after exec_shell	Fix 2 (flush)	Prevention is active — buffer cleared after every shell call
TUI event poll stall detected … forcing terminal recovery	Fix 1 (stall detect)	A stall was caught within 5 seconds and recovered
TUI watchdog detected event-loop stall, signaling recovery	Fix 3 (watchdog)	Stall detection missed it, watchdog caught it at 10 seconds

Good outcome: you see flush messages after every exec_shell, but no stall/watchdog messages — meaning prevention is working.

Partial success: you see stall/watchdog messages, but the session recovers instead of freezing permanently.

---

Files changed (per branch)

Fix 1 — fix/1812-bounded-poll-timeout

• crates/tui/src/tui/ui.rs — stall detection counter + recovery trigger in event loop
• crates/tui/src/tui/app.rs — tui_freeze_consecutive_empty_polls_ms field

Fix 2 — fix/1812-console-flush-after-exec

• crates/tui/src/tools/shell.rs — flush_console_input_buffer() helper + call sites after child.wait() / child.wait_timeout()

Fix 3 — fix/1812-watchdog-thread

• crates/tui/src/tui/tui_watchdog.rs — new module: heartbeat statics, watchdog thread
• crates/tui/src/tui/mod.rs — module registration
• crates/tui/src/tui/ui.rs — heartbeat call + recovery check in event loop, start() at TUI init

---

Notes

• These are defense-in-depth measures. The underlying root cause (Windows console input handle going silent after rapid child process exits) likely lives in crossterm internals and needs investigation there.
• All three fixes can coexist — they're complementary layers, not alternatives.
• The RUST_LOG=tui_freeze=debug,info filter shows the new instrumentation without drowning you in HTTP/tokio noise.

[GoldenSupremeSaltedFish]

got it