fix(tui): recover Windows shell UI from mid-session console blanking (#192)

* fix(tui): recover Windows shell UI from mid-session console blanking

The Windows shell UI could go blank mid-session (transcript and input box
gone until terminal restart). Two mechanisms, both fixed:

- Child processes attached to the interactive console: Shell-tool,
  background-task, and shell-escape spawns now pass CREATE_NO_WINDOW so a
  child touching the console via the Win32 console API (cls, Clear-Host,
  SetConsoleMode) cannot corrupt the TUI. Kill semantics are unchanged
  (TerminateProcess; no CTRL_BREAK usage anywhere).

- prompt_toolkit's differential renderer diffing against a stale frame
  after the real screen diverged (ConPTY resize rewrap, terminal replay,
  half-completed teardown erase): the prompt renderer state is now reset
  after terminal geometry changes and failed scrollback handoffs so the
  next redraw is absolute.

Also corrects the sync_output docstring: Windows10_Output delegates
_buffer to its vt100 output, so DEC-2026 marks ARE installed on
VT-capable Windows consoles (safe: WT expires after 100ms, xterm.js 5s).

* fix(tui): address review — Ctrl+L hard repaint, spawn-flag test coverage

- Add an explicit Ctrl+L binding (pins prompt_toolkit's default clear-screen)
  with a contained-failure handler, list it in /help shortcuts and
  docs/en/reference/keyboard.md.
- Add spawn-flag tests for the background worker child and the `!` foreground
  shell command (CREATE_NO_WINDOW on Windows), plus hard-repaint tests.
- Reviewed e2e cancellation failure: test_shell_cancel_running_command_kills_
  process_and_recovers passes outside the sandboxed test runner and on CI;
  the local failure was sandbox interference with PTY signal delivery.

* refactor(host): centralize Windows console-detach creationflags

The CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW computation was
duplicated across four subprocess spawn sites, and had already drifted:
local.py used a 0x00000200 fallback for CREATE_NEW_PROCESS_GROUP while
manager.py/worker.py used 0. Extract a shared
windows_console_detach_flags() helper so the fallback constants and
console-detachment logic can't diverge again.

Author: elkaix

CHANGELOG.md

@@ -15,6 +15,12 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- Fix the Windows shell UI going blank mid-session (transcript and input box
+  disappearing until terminal restart): child processes no longer attach to the
+  interactive console (`CREATE_NO_WINDOW` on Shell-tool, background-task, and
+  `!` command spawns), and the prompt renderer now forces an absolute repaint
+  after terminal resizes and failed scrollback handoffs instead of diffing
+  against a stale frame.
 - Fix Workflow progress rendering duplicating agents truncated by the per-phase
   display cap, close leaked `agent()` coroutines when `parallel()` rejects its
   arguments, and add a 1000-agent lifetime backstop against runaway workflow loops.

docs/en/reference/keyboard.md

@@ -17,6 +17,7 @@ Pythinker Code shell mode supports the following keyboard shortcuts.
 | `Ctrl-V` | Paste (supports images and video files) |
 | `Ctrl-E` | Expand full approval request content |
 | `Ctrl-T` | Show/hide the pinned todo list (during a running turn) |
+| `Ctrl-L` | Clear and repaint the screen (recovers a blank/corrupted display) |
 | `1`–`4` | Quick select approval option (`4` for decline with feedback) |
 | `1`–`5` | Select question option by number |
 | `Ctrl-D` | Exit Pythinker Code |

packages/pythinker-host/src/pythinker_host/local.py

@@ -3,7 +3,6 @@
 import asyncio
 import os
 import signal
-import subprocess
 from asyncio.subprocess import Process as AsyncioProcess
 from collections.abc import AsyncGenerator
 from pathlib import Path, PurePath
@@ -30,6 +29,7 @@
     StrOrHostPath,
 )
 from pythinker_host.path import HostPath
+from pythinker_host.windows import windows_console_detach_flags
 
 if TYPE_CHECKING:
 
@@ -198,9 +198,12 @@ async def exec(
 
         process_options: dict[str, Any] = {}
         if os.name == "nt":
-            process_options["creationflags"] = getattr(
-                subprocess, "CREATE_NEW_PROCESS_GROUP", 0x00000200
-            )
+            # CREATE_NO_WINDOW detaches the child from the interactive console
+            # (it gets its own hidden one): console-API writes, `cls`, or
+            # SetConsoleMode calls from the child would otherwise bypass the
+            # stdio pipes and corrupt the parent TUI until terminal restart.
+            # CREATE_NEW_PROCESS_GROUP keeps kill() semantics unchanged.
+            process_options["creationflags"] = windows_console_detach_flags()
         else:
             process_options["start_new_session"] = True
 

packages/pythinker-host/src/pythinker_host/windows.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import subprocess
+
+_CREATE_NO_WINDOW = 0x08000000
+_CREATE_NEW_PROCESS_GROUP = 0x00000200
+
+
+def windows_console_detach_flags(*, new_process_group: bool = True) -> int:
+    """Build Windows ``creationflags`` that keep a spawned child off the console.
+
+    ``CREATE_NO_WINDOW`` gives the child its own hidden console: without it, a
+    child that touches the Win32 console API (``cls``, ``SetConsoleMode``, ...)
+    bypasses redirected stdio and can blank the parent TUI until the terminal is
+    restarted. ``CREATE_NEW_PROCESS_GROUP`` is included by default so existing
+    ``kill()``/``taskkill`` semantics against the child are unaffected; pass
+    ``new_process_group=False`` for callers that only need console detachment.
+
+    Centralized here so the fallback constants (used when the real Win32
+    constants aren't defined, e.g. off-Windows) cannot drift between the
+    several process-spawn sites that need them.
+    """
+    flags = getattr(subprocess, "CREATE_NO_WINDOW", _CREATE_NO_WINDOW)
+    if new_process_group:
+        flags |= getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", _CREATE_NEW_PROCESS_GROUP)
+    return flags

packages/pythinker-host/tests/test_local_host.py

@@ -257,3 +257,46 @@ def _record_killpg(pgid: int, sig: int) -> None:
     await process.wait()
 
     assert sent and sent[0] == signal_any.SIGKILL
+
+
+async def test_exec_windows_child_gets_hidden_console(
+    local_host: LocalHost, monkeypatch: pytest.MonkeyPatch
+):
+    """On Windows the child must not attach to the interactive console.
+
+    A child sharing the TUI's console can clear it or reset its modes through
+    the Win32 console API (bypassing the stdio pipes), blanking the shell UI
+    until the terminal is restarted. CREATE_NO_WINDOW gives the child its own
+    hidden console; CREATE_NEW_PROCESS_GROUP keeps kill() semantics unchanged.
+    """
+    from types import SimpleNamespace
+
+    from pythinker_host import local as local_module
+
+    captured: dict[str, Any] = {}
+
+    class _FakePipe:
+        pass
+
+    class _FakeProcess:
+        stdin: Any = _FakePipe()
+        stdout: Any = _FakePipe()
+        stderr: Any = _FakePipe()
+
+    async def _fake_create_subprocess_exec(*args: Any, **kwargs: Any) -> Any:
+        captured.update(kwargs)
+        return _FakeProcess()
+
+    # Swap the module's `os` reference rather than mutating the global
+    # `os.name`, which corrupts pathlib/pytest path handling mid-run.
+    monkeypatch.setattr(local_module, "os", SimpleNamespace(name="nt"))
+    monkeypatch.setattr(
+        local_module.asyncio, "create_subprocess_exec", _fake_create_subprocess_exec
+    )
+
+    await local_host.exec("cmd", "/c", "echo hi")
+
+    flags = captured["creationflags"]
+    assert flags & 0x00000200  # CREATE_NEW_PROCESS_GROUP
+    assert flags & 0x08000000  # CREATE_NO_WINDOW
+    assert "start_new_session" not in captured

src/pythinker_code/background/manager.py

@@ -12,6 +12,7 @@
 from typing import TYPE_CHECKING, Any, Literal
 
 from pythinker_host.local import local_host
+from pythinker_host.windows import windows_console_detach_flags
 
 from pythinker_code.config import BackgroundConfig
 from pythinker_code.notifications import NotificationEvent, NotificationManager
@@ -243,7 +244,10 @@ def _launch_worker(self, task_dir: Path) -> int:
             "cwd": str(task_dir),
         }
         if os.name == "nt":
-            kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+            # CREATE_NO_WINDOW: don't share the interactive console — a child
+            # touching it via the Win32 console API bypasses DEVNULL stdio and
+            # can blank the parent TUI until terminal restart.
+            kwargs["creationflags"] = windows_console_detach_flags()
         else:
             kwargs["start_new_session"] = True
 

src/pythinker_code/background/worker.py

@@ -9,6 +9,8 @@
 from pathlib import Path
 from typing import Any
 
+from pythinker_host.windows import windows_console_detach_flags
+
 from pythinker_code.utils.logging import logger
 from pythinker_code.utils.subprocess_env import get_clean_env, scrub_secret_env
 
@@ -185,7 +187,10 @@ async def _input_loop() -> None:
                 "env": scrub_secret_env(get_clean_env()) if spec.scrub_secrets else get_clean_env(),
             }
             if os.name == "nt":
-                spawn_kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+                # CREATE_NO_WINDOW: don't share the interactive console — a child
+                # touching it via the Win32 console API bypasses the redirected
+                # stdio and can blank the parent TUI until terminal restart.
+                spawn_kwargs["creationflags"] = windows_console_detach_flags()
             else:
                 spawn_kwargs["start_new_session"] = True
 

src/pythinker_code/ui/shell/__init__.py

@@ -4,6 +4,7 @@
 import asyncio
 import contextlib
 import json
+import os
 import re
 import shlex
 import textwrap
@@ -24,6 +25,7 @@
     APITimeoutError,
     ChatProviderError,
 )
+from pythinker_host.windows import windows_console_detach_flags
 from rich import box
 from rich.align import Align
 from rich.cells import cell_len
@@ -1271,11 +1273,20 @@ def _handler():
         try:
             # TODO: For the sake of simplicity, we now use `create_subprocess_shell`.
             # Later we should consider making this behave like a real shell.
+            spawn_kwargs: dict[str, Any] = {}
+            if os.name == "nt":
+                # CREATE_NO_WINDOW: don't share the interactive console — a child
+                # touching it via the Win32 console API bypasses the pipes and
+                # can blank the TUI until terminal restart.
+                spawn_kwargs["creationflags"] = windows_console_detach_flags(
+                    new_process_group=False
+                )
             proc = await asyncio.create_subprocess_shell(
                 command,
                 env=get_clean_env(),
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.PIPE,
+                **spawn_kwargs,
             )
             stdout_task = asyncio.create_task(_read_stream_limited(proc.stdout, max_output_bytes))
             stderr_task = asyncio.create_task(_read_stream_limited(proc.stderr, max_output_bytes))

src/pythinker_code/ui/shell/prompt.py

@@ -2554,6 +2554,11 @@ def _(event: KeyPressEvent) -> None:
             track("shortcut_editor")
             self._open_in_external_editor(event)
 
+        @_kb.add("c-l", eager=True)
+        def _(event: KeyPressEvent) -> None:
+            """Erase and fully repaint the screen (recovery from console damage)."""
+            self._hard_repaint(event)
+
         def _has_staged_suggestion_prefill() -> bool:
             return bool(getattr(self, "_staged_suggestion_prefill", None))
 
@@ -3092,6 +3097,21 @@ def _render_shell_prompt_message(self) -> FormattedText:
         fragments.append(("bold", f"{PROMPT_SYMBOL_SHELL} "))
         return fragments
 
+    def _hard_repaint(self, event: KeyPressEvent) -> None:
+        """Erase the screen and absolutely repaint the prompt (Ctrl+L escape hatch).
+
+        Pins prompt_toolkit's default clear-screen behavior explicitly: when the
+        real screen has diverged from the renderer's frame model (Windows ConPTY
+        replay, a child process writing to the shared console), the differential
+        renderer keeps emitting empty diffs and the UI looks blank; this forces
+        an absolute frame. Explicit so future custom bindings cannot silently
+        shadow the recovery path.
+        """
+        try:
+            event.app.renderer.clear()
+        except Exception as exc:  # noqa: BLE001 — recovery must never crash the prompt
+            logger.debug("Hard repaint (ctrl-l) failed: {}", exc)
+
     def _open_in_external_editor(self, event: KeyPressEvent) -> None:
         """Open the current buffer content in an external editor."""
         from prompt_toolkit.application.run_in_terminal import run_in_terminal

src/pythinker_code/ui/shell/slash.py

@@ -81,6 +81,7 @@ def slash_command_arg_suggestions() -> dict[str, tuple[str, ...]]:
     ("Ctrl-O", "Edit in external editor ($VISUAL/$EDITOR)"),
     ("Ctrl-J / Alt-Enter", "Insert newline"),
     ("Ctrl-V", "Paste (supports images)"),
+    ("Ctrl-L", "Repaint the screen (recover a blank/corrupted display)"),
     ("Ctrl-D", "Exit"),
     ("Ctrl-C", "Interrupt"),
 ]