From 25426f72ae04a306f1e08de09583b4e89503b9e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Hou=C5=A1ka?= Date: Sat, 31 Oct 2026 16:15:42 +0100 Subject: [PATCH] docs(coding-agent): document Windows terminal and conhost limitations (#11644) Adds a "Choose a terminal" section to `packages/coding-agent/docs/windows.md` (https://pi.dev/docs/latest/windows), with two tables (last updated October 2026): - Terminals and which conhost they use: Windows Terminal (recommended), VS Code, WezTerm nightly (bundled, up to date); WezTerm 20240203 (bundled, old); Alacritty (built-in unless `conpty.dll` + `OpenConsole.exe` are provided); classic console window, mintty, ConEmu/Cmder, Windows OpenSSH (built-in). - Known problems by conhost type: - Built-in: crash when switching fullscreen -> regular or using `Ctrl+G` from fullscreen (#9186, microsoft/terminal#17515). - Built-in behind another terminal (mintty, OpenSSH): query replies leak into the prompt, BEL opens the external editor (#10256, #10362, #10742). - Old bundled (WezTerm 20240203): reply fragments in the prompt (#10717, #10970). - Built-in, classic console: reported regular-mode redraw issue (#6300). - Notes that the fixes exist upstream and reach the built-in conhost with a future Windows update, timing unknown. Sources: VS Code defaults `terminal.integrated.windowsUseConptyDll` to `true` (bundled conpty v1.25). Alacritty loads `conpty.dll` only if present (`alacritty_terminal/src/tty/windows/conpty.rs`) and its installer ships only `alacritty.exe`. The crash was verified locally in the classic console window on conhost 10.0.26100.9807: fullscreen -> regular crashed 3/3 runs and `Ctrl+G` from fullscreen crashed 2/2 runs (`0xC0000005`). --- packages/coding-agent/docs/windows.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/packages/coding-agent/docs/windows.md b/packages/coding-agent/docs/windows.md index 26f2f961c..18826cd02 100644 --- a/packages/coding-agent/docs/windows.md +++ b/packages/coding-agent/docs/windows.md @@ -76,6 +76,31 @@ JSON uses backslashes for escape sequences. When you write a Windows path with b See [Configure shell commands](shell-aliases.md) for command prefixes, aliases, and the complete shell-resolution behavior. +## Choose a terminal + +Windows terminals run Pi through a console host (conhost). Some bundle an up-to-date copy; others use the older one built into Windows, which has bugs that affect Pi. + +We recommend [Windows Terminal](https://aka.ms/terminal). It always ships an up-to-date conhost, and Pi is best tested with it. + +Last updated: October 2026. + +| Terminal | Conhost | Status | +|---|---|---| +| [Windows Terminal](https://aka.ms/terminal) | Bundled, current | Recommended | +| [VS Code](https://code.visualstudio.com), [Tabby](https://tabby.sh), [WezTerm](https://wezterm.org) nightly | Bundled, current | Works | +| [Alacritty](https://alacritty.org) | Built-in, unless `conpty.dll` and `OpenConsole.exe` from Windows Terminal are next to `alacritty.exe` | Works only with those files | +| WezTerm 20240203 and older | Bundled, old | Known problems | +| Classic console (`cmd.exe` or PowerShell without Windows Terminal), mintty (Git Bash), ConEmu, Cmder, [Hyper](https://hyper.is), Windows OpenSSH | Built-in | Known problems | + +| Problem | Where | Why | +|---|---|---| +| Switching from fullscreen to regular mode, or `Ctrl+G` from fullscreen, crashes the session ([#9186](https://github.com/earendil-works/pi/issues/9186), [microsoft/terminal#17515](https://github.com/microsoft/terminal/issues/17515)). Start with `--tui-mode regular` to avoid it. | Built-in | Conhost crashes when leaving the alternate screen while input is in line mode. | +| Text such as `;0;rgb:0000/0000/0000` appears in the prompt and BEL opens the external editor ([#10256](https://github.com/earendil-works/pi/issues/10256), [#10362](https://github.com/earendil-works/pi/issues/10362), [#10742](https://github.com/earendil-works/pi/issues/10742)) | Built-in behind another terminal (mintty, OpenSSH) | Conhost drops the start of terminal replies that arrive in pieces. | +| Fragments such as `79` or `55` appear in the prompt ([#10717](https://github.com/earendil-works/pi/issues/10717), [#10970](https://github.com/earendil-works/pi/issues/10970)) | WezTerm 20240203 | The bundled conhost cuts terminal replies short. | +| In regular mode, each keystroke redraws the input line on a new row ([#6300](https://github.com/earendil-works/pi/issues/6300)) | Built-in, classic console | Suspected: cursor wraps after full-width lines. | + +Microsoft has fixed these bugs in its source, but has not said when the built-in conhost will get the fixes. + ## Configure Windows Terminal Windows Terminal reserves or rewrites some modified keys. See [Windows Terminal](terminal-setup.md#windows-terminal) to configure `Shift+Enter` and `Alt+Enter`, and [Keybindings](keybindings.md) for Pi's Windows and WSL shortcut defaults.