feat(windows): fix terminal bricking when running via uvx on Windows 🐶

Author: mpfaffenberger

code_puppy/agents/base_agent.py

@@ -1938,7 +1938,12 @@ def keyboard_interrupt_handler(_sig, _frame):
         def graceful_sigint_handler(_sig, _frame):
             # When using keyboard-based cancel, SIGINT should be a no-op
             # (just show a hint to user about the configured cancel key)
+            # Also reset terminal to prevent bricking on Windows+uvx
             from code_puppy.keymap import get_cancel_agent_display_name
+            from code_puppy.terminal_utils import reset_windows_terminal_full
+
+            # Reset terminal state first to prevent bricking
+            reset_windows_terminal_full()
 
             cancel_key = get_cancel_agent_display_name()
             emit_info(f"Use {cancel_key} to cancel the agent task.")

code_puppy/cli_runner.py

@@ -171,6 +171,45 @@ async def main():
         emit_error(str(e))
         sys.exit(1)
 
+    # Show uvx detection notice if we're on Windows + uvx
+    # Also disable Ctrl+C at the console level to prevent terminal bricking
+    try:
+        from code_puppy.uvx_detection import should_use_alternate_cancel_key
+
+        if should_use_alternate_cancel_key():
+            from code_puppy.terminal_utils import (
+                disable_windows_ctrl_c,
+                set_keep_ctrl_c_disabled,
+            )
+
+            # Disable Ctrl+C at the console input level
+            # This prevents Ctrl+C from being processed as a signal at all
+            disable_windows_ctrl_c()
+
+            # Set flag to keep it disabled (prompt_toolkit may re-enable it)
+            set_keep_ctrl_c_disabled(True)
+
+            # Use print directly - emit_system_message can get cleared by ANSI codes
+            print(
+                "🔧 Detected uvx launch on Windows - using Ctrl+K for cancellation "
+                "(Ctrl+C is disabled to prevent terminal issues)"
+            )
+
+            # Also install a SIGINT handler as backup
+            import signal
+
+            from code_puppy.terminal_utils import reset_windows_terminal_full
+
+            def _uvx_protective_sigint_handler(_sig, _frame):
+                """Protective SIGINT handler for Windows+uvx."""
+                reset_windows_terminal_full()
+                # Re-disable Ctrl+C in case something re-enabled it
+                disable_windows_ctrl_c()
+
+            signal.signal(signal.SIGINT, _uvx_protective_sigint_handler)
+    except ImportError:
+        pass  # uvx_detection module not available, ignore
+
     # Load API keys from puppy.cfg into environment variables
     from code_puppy.config import load_api_keys_to_environment
 
@@ -440,6 +479,15 @@ async def interactive_mode(message_renderer, initial_command: str = None) -> Non
                 task = await get_input_with_combined_completion(
                     get_prompt_with_active_model(), history_file=COMMAND_HISTORY_FILE
                 )
+
+                # Windows+uvx: Re-disable Ctrl+C after prompt_toolkit
+                # (prompt_toolkit restores console mode which re-enables Ctrl+C)
+                try:
+                    from code_puppy.terminal_utils import ensure_ctrl_c_disabled
+
+                    ensure_ctrl_c_disabled()
+                except ImportError:
+                    pass
             except ImportError:
                 # Fall back to basic input if prompt_toolkit is not available
                 task = input(">>> ")
@@ -605,6 +653,13 @@ async def interactive_mode(message_renderer, initial_command: str = None) -> Non
                 if result is None:
                     # Windows-specific: Reset terminal state after cancellation
                     reset_windows_terminal_ansi()
+                    # Re-disable Ctrl+C if needed (uvx mode)
+                    try:
+                        from code_puppy.terminal_utils import ensure_ctrl_c_disabled
+
+                        ensure_ctrl_c_disabled()
+                    except ImportError:
+                        pass
                     continue
                 # Get the structured response
                 agent_response = result.output
@@ -645,6 +700,15 @@ async def interactive_mode(message_renderer, initial_command: str = None) -> Non
 
             auto_save_session_if_enabled()
 
+            # Re-disable Ctrl+C if needed (uvx mode) - must be done after
+            # each iteration as various operations may restore console mode
+            try:
+                from code_puppy.terminal_utils import ensure_ctrl_c_disabled
+
+                ensure_ctrl_c_disabled()
+            except ImportError:
+                pass
+
 
 def prettier_code_blocks():
     """Configure Rich to use prettier code block rendering."""

code_puppy/keymap.py

@@ -55,11 +55,19 @@ class KeymapError(Exception):
 def get_cancel_agent_key() -> str:
     """Get the configured cancel agent key from config.
 
+    On Windows when launched via uvx, this automatically returns "ctrl+k"
+    to work around uvx capturing Ctrl+C before it reaches Python.
+
     Returns:
         The key name (e.g., "ctrl+c", "ctrl+k") from config,
         or the default if not configured.
     """
     from code_puppy.config import get_value
+    from code_puppy.uvx_detection import should_use_alternate_cancel_key
+
+    # On Windows + uvx, force ctrl+k to bypass uvx's SIGINT capture
+    if should_use_alternate_cancel_key():
+        return "ctrl+k"
 
     key = get_value("cancel_agent_key")
     if key is None or key.strip() == "":

code_puppy/terminal_utils.py

@@ -6,6 +6,10 @@
 import platform
 import subprocess
 import sys
+from typing import Callable, Optional
+
+# Store the original console ctrl handler so we can restore it if needed
+_original_ctrl_handler: Optional[Callable] = None
 
 
 def reset_windows_terminal_ansi() -> None:
@@ -86,17 +90,36 @@ def reset_windows_console_mode() -> None:
         pass  # Silently ignore errors - best effort reset
 
 
+def flush_windows_keyboard_buffer() -> None:
+    """Flush the Windows keyboard buffer.
+
+    Clears any pending keyboard input that could interfere with
+    subsequent input operations after an interrupt.
+    """
+    if platform.system() != "Windows":
+        return
+
+    try:
+        import msvcrt
+
+        while msvcrt.kbhit():
+            msvcrt.getch()
+    except Exception:
+        pass  # Silently ignore errors - best effort flush
+
+
 def reset_windows_terminal_full() -> None:
-    """Perform a full Windows terminal reset (ANSI + console mode).
+    """Perform a full Windows terminal reset (ANSI + console mode + keyboard buffer).
 
-    Combines both ANSI reset and console mode reset for complete
-    terminal state restoration after interrupts.
+    Combines ANSI reset, console mode reset, and keyboard buffer flush
+    for complete terminal state restoration after interrupts.
     """
     if platform.system() != "Windows":
         return
 
     reset_windows_terminal_ansi()
     reset_windows_console_mode()
+    flush_windows_keyboard_buffer()
 
 
 def reset_unix_terminal() -> None:
@@ -124,3 +147,145 @@ def reset_terminal() -> None:
         reset_windows_terminal_full()
     else:
         reset_unix_terminal()
+
+
+def disable_windows_ctrl_c() -> bool:
+    """Disable Ctrl+C processing at the Windows console input level.
+
+    This removes ENABLE_PROCESSED_INPUT from stdin, which prevents
+    Ctrl+C from being interpreted as a signal at all. Instead, it
+    becomes just a regular character (^C) that gets ignored.
+
+    This is more reliable than SetConsoleCtrlHandler because it
+    prevents Ctrl+C from being processed before it reaches any handler.
+
+    Returns:
+        True if successfully disabled, False otherwise.
+    """
+    global _original_ctrl_handler
+
+    if platform.system() != "Windows":
+        return False
+
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+
+        # Get stdin handle
+        STD_INPUT_HANDLE = -10
+        stdin_handle = kernel32.GetStdHandle(STD_INPUT_HANDLE)
+
+        # Get current console mode
+        mode = ctypes.c_ulong()
+        if not kernel32.GetConsoleMode(stdin_handle, ctypes.byref(mode)):
+            return False
+
+        # Save original mode for potential restoration
+        _original_ctrl_handler = mode.value
+
+        # Console mode flags
+        ENABLE_PROCESSED_INPUT = 0x0001  # This makes Ctrl+C generate signals
+
+        # Remove ENABLE_PROCESSED_INPUT to disable Ctrl+C signal generation
+        new_mode = mode.value & ~ENABLE_PROCESSED_INPUT
+
+        if kernel32.SetConsoleMode(stdin_handle, new_mode):
+            return True
+        return False
+
+    except Exception:
+        return False
+
+
+def enable_windows_ctrl_c() -> bool:
+    """Re-enable Ctrl+C at the Windows console level.
+
+    Restores the original console mode saved by disable_windows_ctrl_c().
+
+    Returns:
+        True if successfully re-enabled, False otherwise.
+    """
+    global _original_ctrl_handler
+
+    if platform.system() != "Windows":
+        return False
+
+    if _original_ctrl_handler is None:
+        return True  # Nothing to restore
+
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+
+        # Get stdin handle
+        STD_INPUT_HANDLE = -10
+        stdin_handle = kernel32.GetStdHandle(STD_INPUT_HANDLE)
+
+        # Restore original mode
+        if kernel32.SetConsoleMode(stdin_handle, _original_ctrl_handler):
+            _original_ctrl_handler = None
+            return True
+        return False
+
+    except Exception:
+        return False
+
+
+# Flag to track if we should keep Ctrl+C disabled
+_keep_ctrl_c_disabled: bool = False
+
+
+def set_keep_ctrl_c_disabled(value: bool) -> None:
+    """Set whether Ctrl+C should be kept disabled.
+
+    When True, ensure_ctrl_c_disabled() will re-disable Ctrl+C
+    even if something else (like prompt_toolkit) re-enables it.
+    """
+    global _keep_ctrl_c_disabled
+    _keep_ctrl_c_disabled = value
+
+
+def ensure_ctrl_c_disabled() -> bool:
+    """Ensure Ctrl+C is disabled if it should be.
+
+    Call this after operations that might restore console mode
+    (like prompt_toolkit input).
+
+    Returns:
+        True if Ctrl+C is now disabled (or wasn't needed), False on error.
+    """
+    if not _keep_ctrl_c_disabled:
+        return True
+
+    if platform.system() != "Windows":
+        return True
+
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+
+        # Get stdin handle
+        STD_INPUT_HANDLE = -10
+        stdin_handle = kernel32.GetStdHandle(STD_INPUT_HANDLE)
+
+        # Get current console mode
+        mode = ctypes.c_ulong()
+        if not kernel32.GetConsoleMode(stdin_handle, ctypes.byref(mode)):
+            return False
+
+        # Console mode flags
+        ENABLE_PROCESSED_INPUT = 0x0001
+
+        # Check if Ctrl+C processing is enabled
+        if mode.value & ENABLE_PROCESSED_INPUT:
+            # Disable it
+            new_mode = mode.value & ~ENABLE_PROCESSED_INPUT
+            return bool(kernel32.SetConsoleMode(stdin_handle, new_mode))
+
+        return True  # Already disabled
+
+    except Exception:
+        return False