fix(tui): pin the platform default driver — TG 2.4.17 auto-detect picks the keypress-dropping ansi driver (#51)

Terminal.Gui 2.4.17 added an 'ansi' driver and its auto-detect now selects
it on a bare terminal (IDriver.GetName() confirms), superseding 2.4.16's
'windows' default. The ansi driver's input path drops every other keypress:
vim j/k moves once per two presses (input eaten — the second press moves one
row — in both lists, persistently). Reproduces on main under
COBALT_DRIVER=ansi; windows and dotnet are clean.

ResolveDriver now pins the pre-2.4.17 platform default explicitly (windows
on Windows, dotnet elsewhere) instead of falling through to TG auto-detect;
the multiplexer/RDP path degrades to the same pin if 'dotnet' is ever
unregistered. null (TG picks) remains only when even the pinned driver is
missing. COBALT_DRIVER still overrides everything, including =ansi.

Also records in ADR 0016 that INPUT-1's owed both-driver UAT passed
2026-07-22 (the double-press seen at that UAT was this ansi driver,
initially misattributed to INPUT-1).

Author: jinyeow

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Fixed
+- **Vim `j`/`k` no longer needs two presses per move on a bare terminal.** Terminal.Gui
+  2.4.17's auto-detect selects its new `ansi` driver, whose input path drops every other
+  keypress. Cobalt now pins the platform default explicitly (`windows` on Windows, `dotnet`
+  elsewhere) instead of falling through to auto-detect; `COBALT_DRIVER` still overrides
+  everything, including `=ansi`. See
+  [ADR 0016](docs/adr/0016-terminal-driver-selection.md).
+
 ### Changed
 - **The work-item list is capped at the first 200 assigned items**, matching the existing
   pull-request-list cap: a heavy assignee no longer pulls an unbounded id set (and that many
@@ -20,8 +28,8 @@
   precomputed once per thread refresh instead of scanning every file's threads on each render,
   and the intra-line word diff skips its expensive comparison on line pairs whose lengths are
   too mismatched for the result to be useful. Vim movement now redraws only the moved list
-  instead of repainting the whole app on every keystroke (needs both-driver UAT before it's
-  fully trusted — see [ADR 0016](docs/adr/0016-terminal-driver-selection.md)). Per-keystroke
+  instead of repainting the whole app on every keystroke (both-driver UAT passed 2026-07-22 —
+  see [ADR 0016](docs/adr/0016-terminal-driver-selection.md)). Per-keystroke
   input handling (the key router and tokenizer) no longer allocates on the hot path. These are
   structural fixes verified by allocation/call-count tests, not measured against a live org.
 - **Fewer round-trips on work items.** Opening the work-item detail now fetches its comments and

README.md

@@ -196,11 +196,14 @@ A full-screen editor gets a clean terminal (the TUI suspends while it runs).
 
 ## Terminal multiplexers (zellij / tmux) and remote sessions
 
+On a bare terminal cobalt pins the platform default driver itself — `windows` on Windows,
+`dotnet` elsewhere — rather than deferring to Terminal.Gui's auto-detect, which (since
+TG 2.4.17) selects an `ansi` driver that drops every other keypress.
+
 Inside a multiplexer, cobalt runs against a pseudo-terminal rather than a real Win32
-console, and Terminal.Gui's default `windows` driver (Win32 console APIs) drops
-keystrokes and breaks the `$EDITOR` handoff there. cobalt **auto-detects zellij and
-tmux** (`ZELLIJ`/`TMUX`) and switches to the stdio/ANSI `dotnet` driver, so it works
-there with no configuration.
+console, and the Win32 `windows` driver (console APIs) drops keystrokes and breaks the
+`$EDITOR` handoff there. cobalt **auto-detects zellij and tmux** (`ZELLIJ`/`TMUX`) and
+switches to the stdio/ANSI `dotnet` driver, so it works there with no configuration.
 
 **Remote / RDP sessions** (including a Windows 365 Cloud PC) get the same treatment:
 cobalt detects them via `SESSIONNAME=RDP-*` and switches to `dotnet`. On the `windows`

docs/adr/0016-terminal-driver-selection.md

@@ -65,7 +65,22 @@ was dropped before any handler ran. The record is corrected here and in the code
   misses, set `COBALT_DRIVER=dotnet`. And `COBALT_DRIVER` always wins — including
   `COBALT_DRIVER=windows` to force the Win32 driver back inside a multiplexer.
 
-### Targeted redraw on vim movement (round 2, INPUT-1) — needs both-driver UAT
+- **Pin the platform default explicitly; never fall through to TG auto-detect (amended
+  2026-07-22).** Terminal.Gui 2.4.17 added an `ansi` driver, and its auto-detect now selects
+  it (verified empirically: `IDriver.GetName()` reports `ansi` after `Init(null)` on a bare
+  Windows Terminal — the "`null` → TG picks `windows`" claims above describe 2.4.16 and are
+  superseded). The ansi driver's input path drops every other keypress: vim `j`/`k` moves
+  once per two presses (the second press moves 1 row, both lists, persistent — input eaten,
+  not a repaint lag). Reproduces identically on `main` and on feature branches under
+  `COBALT_DRIVER=ansi`, while `windows` and `dotnet` are clean, so it is the driver, not
+  cobalt logic. `ResolveDriver` therefore pins the pre-2.4.17 platform default explicitly
+  (`windows` on Windows, `dotnet` elsewhere) when no override and no multiplexer/RDP
+  detection applies — and the multiplexer/RDP path degrades to that same pin (never to TG
+  auto) if the `dotnet` driver is ever unregistered. `null` (TG picks) remains only as the
+  last resort when even the pinned driver is missing. `COBALT_DRIVER=ansi` still passes
+  through for retesting the upstream bug.
+
+### Targeted redraw on vim movement (round 2, INPUT-1) — both-driver UAT passed
 
 The earlier `LayoutAndDraw(false)→(true)` change (`fb5b777`, see Context above) forced a full
 `Application.LayoutAndDraw(true)` on every vim move to dodge a driver dirty-flag quirk, even
@@ -74,12 +89,11 @@ moved list view calls `SetNeedsDraw()` on itself, and the app then runs
 `Application.LayoutAndDraw(false)` — no forced full-app repaint — relying on the explicit dirty
 flag to cover what `force:true` was compensating for on a programmatic `InvokeCommand` move.
 
-This is **not yet confirmed safe on both drivers** and must be UAT'd on the `windows` driver and
-the `dotnet` driver before it can be trusted — a headless test can assert `SetNeedsDraw()` was
-called, but not that the real driver actually repaints the moved row without the old `force:true`
-backstop, which is exactly the class of defect this ADR exists to catch (dropped input/redraw
-behaviour that only reproduces against a real console or pty). Until that UAT runs, treat the
-change as at-risk of resurrecting the redraw side of the original driver quirk.
+**UAT passed 2026-07-22** on both the `windows` and `dotnet` drivers: vim `j`/`k` movement
+paints correctly on the first press with INPUT-1's targeted redraw in place. (The double-press
+observed at that UAT was the 2.4.17 `ansi` auto-detect driver — see the 2026-07-22 pin above —
+initially misattributed to INPUT-1 precisely because the symptom matched the original
+`fb5b777`-era report. INPUT-1 is exonerated.)
 
 ## Consequences
 

src/Cobalt.Tui/App/CobaltTuiApp.cs

@@ -1,3 +1,4 @@
+using System.Runtime.InteropServices;
 using Cobalt.Core.Ado;
 using Cobalt.Core.Auth;
 using Cobalt.Core.Config;
@@ -57,7 +58,10 @@ private static int RunCore(CobaltConfig config, string? contextOverride, ITokenP
             context.PrScope,
             new PolicyApi(connection.Http));
 
-        var driverName = ResolveDriver(Environment.GetEnvironmentVariable, DriverRegistry.GetDriverNames().ToArray());
+        var driverName = ResolveDriver(
+            Environment.GetEnvironmentVariable,
+            DriverRegistry.GetDriverNames().ToArray(),
+            RuntimeInformation.IsOSPlatform(OSPlatform.Windows));
         // Enable Terminal.Gui's theming (scoped to its embedded config) before Init so the driver
         // starts on the resolved theme; the initial preset is applied just below.
         ThemeService.Enable();
@@ -84,7 +88,11 @@ private static int RunCore(CobaltConfig config, string? contextOverride, ITokenP
     /// unknown value throws an actionable <see cref="ConfigException"/>). Otherwise the
     /// <c>dotnet</c> driver is selected when a terminal multiplexer (<c>ZELLIJ</c>/<c>TMUX</c>)
     /// or a remote/RDP session (<c>SESSIONNAME=RDP-*</c>) is detected. Failing all of these,
-    /// <see langword="null"/> lets TG auto-detect (<c>windows</c> on Windows).
+    /// the platform default is pinned explicitly — <c>windows</c> on Windows, <c>dotnet</c>
+    /// elsewhere — never Terminal.Gui's auto-detect: since 2.4.17 auto-detect selects the new
+    /// <c>ansi</c> driver, whose input path drops every other keypress (vim <c>j</c>/<c>k</c>
+    /// needs two presses per move; diagnosed 2026-07-22). <see langword="null"/> (TG picks) is
+    /// only the last resort when even the pinned driver is unregistered.
     ///
     /// <para>The Win32-console <c>windows</c> driver is unreliable through a multiplexer's
     /// pseudo-terminal — it drops keystrokes and mishandles the editor suspend/resume — and
@@ -94,7 +102,8 @@ private static int RunCore(CobaltConfig config, string? contextOverride, ITokenP
     /// Set <c>COBALT_DRIVER</c> explicitly to override (e.g. <c>=windows</c> to force it back,
     /// or for an environment this detection misses). See ADR 0016.</para>
     /// </summary>
-    internal static string? ResolveDriver(Func<string, string?> env, IReadOnlyCollection<string> knownDrivers)
+    internal static string? ResolveDriver(
+        Func<string, string?> env, IReadOnlyCollection<string> knownDrivers, bool isWindows)
     {
         var requested = env("COBALT_DRIVER")?.Trim();
         if (!string.IsNullOrEmpty(requested))
@@ -111,11 +120,23 @@ private static int RunCore(CobaltConfig config, string? contextOverride, ITokenP
         // expensive over a latency link on a GPU-less host, where the terminal renders in
         // software. The stdio/ANSI 'dotnet' driver writes VT straight to stdout and skips it.
         var inRemoteSession = env("SESSIONNAME")?.StartsWith("RDP-", StringComparison.OrdinalIgnoreCase) == true;
-        return inMultiplexer || inRemoteSession
-            // FirstOrDefault, not First: if 'dotnet' is somehow unregistered, fall back to
-            // TG's default (null) rather than throwing into the crash boundary.
-            ? knownDrivers.FirstOrDefault(d => d.Equals("dotnet", StringComparison.OrdinalIgnoreCase))
-            : null;
+        if (inMultiplexer || inRemoteSession)
+        {
+            var dotnet = knownDrivers.FirstOrDefault(d => d.Equals("dotnet", StringComparison.OrdinalIgnoreCase));
+            if (dotnet is not null)
+            {
+                return dotnet;
+            }
+            // 'dotnet' unregistered: fall through to the platform pin — deterministic beats
+            // TG auto-detect (the broken 'ansi' driver).
+        }
+
+        // Pin the pre-2.4.17 platform default rather than returning null: null hands the
+        // choice to TG auto-detect, which since 2.4.17 lands on the keypress-dropping 'ansi'
+        // driver. FirstOrDefault, not First: with even this driver unregistered, null (TG
+        // picks) is still better than throwing into the crash boundary.
+        var preferred = isWindows ? "windows" : "dotnet";
+        return knownDrivers.FirstOrDefault(d => d.Equals(preferred, StringComparison.OrdinalIgnoreCase));
     }
 
     /// <summary>

tests/Cobalt.Tui.Tests/App/DriverResolutionTests.cs

@@ -5,9 +5,10 @@
 namespace Cobalt.Tui.Tests.App;
 
 /// <summary>
-/// The COBALT_DRIVER escape hatch: forces a specific Terminal.Gui driver (needed under
-/// terminal multiplexers like zellij/tmux, where TG's default Win32-console 'windows'
-/// driver drops keystrokes and mishandles the editor suspend/resume). Unset = TG default.
+/// Driver selection (ADR 0016): an explicit COBALT_DRIVER wins; a multiplexer/RDP session
+/// selects 'dotnet'; otherwise the platform default is pinned explicitly ('windows' on
+/// Windows, 'dotnet' elsewhere) — never Terminal.Gui's auto-detect, whose 2.4.17 pick (the
+/// new 'ansi' driver) drops every other keypress.
 /// </summary>
 public class DriverResolutionTests
 {
@@ -29,33 +30,49 @@ public class DriverResolutionTests
         };
 
     [Fact]
-    public void Unset_Resolves_To_Null_Default()
+    public void Unset_Pins_The_Windows_Driver_On_Windows()
     {
-        Assert.Null(CobaltTuiApp.ResolveDriver(Env(null), Known));
+        // Never null: null would hand selection to TG auto-detect, which picks 'ansi' in
+        // 2.4.17 — and the ansi driver eats every other keypress (the j/k double-press bug).
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(Env(null), Known, isWindows: true));
     }
 
     [Fact]
-    public void Blank_Resolves_To_Null_Default()
+    public void Unset_Pins_The_Dotnet_Driver_Off_Windows()
     {
-        Assert.Null(CobaltTuiApp.ResolveDriver(Env("   "), Known));
+        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(Env(null), Known, isWindows: false));
+    }
+
+    [Fact]
+    public void Blank_Pins_The_Platform_Default()
+    {
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(Env("   "), Known, isWindows: true));
     }
 
     [Fact]
     public void Valid_Value_Resolves_And_Trims()
     {
-        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(Env("  dotnet  "), Known));
+        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(Env("  dotnet  "), Known, isWindows: true));
     }
 
     [Fact]
     public void Value_Is_Case_Insensitive_And_Canonicalized()
     {
-        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(Env("DotNet"), Known));
+        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(Env("DotNet"), Known, isWindows: true));
+    }
+
+    [Fact]
+    public void Explicit_Ansi_Is_Still_Honoured()
+    {
+        // The pin only governs the default; an explicit COBALT_DRIVER=ansi is a deliberate
+        // user choice (e.g. to retest the upstream bug) and passes through.
+        Assert.Equal("ansi", CobaltTuiApp.ResolveDriver(Env("ansi"), Known, isWindows: true));
     }
 
     [Fact]
     public void Unknown_Value_Throws_With_Actionable_Message()
     {
-        var ex = Assert.Throws<ConfigException>(() => CobaltTuiApp.ResolveDriver(Env("dotnett"), Known));
+        var ex = Assert.Throws<ConfigException>(() => CobaltTuiApp.ResolveDriver(Env("dotnett"), Known, isWindows: true));
         Assert.Contains("dotnett", ex.Message);
         Assert.Contains("windows", ex.Message);
         Assert.Contains("dotnet", ex.Message);
@@ -64,34 +81,42 @@ public void Unknown_Value_Throws_With_Actionable_Message()
     [Fact]
     public void Zellij_Selects_The_Dotnet_Driver()
     {
-        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(EnvVars(zellij: "0"), Known));
+        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(EnvVars(zellij: "0"), Known, isWindows: true));
     }
 
     [Fact]
     public void Tmux_Selects_The_Dotnet_Driver()
     {
-        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(EnvVars(tmux: "/tmp/tmux-1000/default,1234,0"), Known));
+        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(EnvVars(tmux: "/tmp/tmux-1000/default,1234,0"), Known, isWindows: true));
+    }
+
+    [Fact]
+    public void Multiplexer_Without_A_Dotnet_Driver_Falls_Back_To_The_Platform_Pin()
+    {
+        // Defensive: if a future Terminal.Gui drops/renames the 'dotnet' driver, degrade to
+        // the deterministic platform pin — never to TG auto-detect.
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(zellij: "0"), ["windows", "ansi"], isWindows: true));
     }
 
     [Fact]
-    public void Multiplexer_Without_A_Dotnet_Driver_Falls_Back_To_Null()
+    public void Platform_Pin_Missing_From_The_Registry_Falls_Back_To_Null()
     {
-        // Defensive: if a future Terminal.Gui drops/renames the 'dotnet' driver, auto-detect
-        // degrades to TG's default rather than throwing (which would hit the crash boundary).
-        Assert.Null(CobaltTuiApp.ResolveDriver(EnvVars(zellij: "0"), ["windows", "ansi"]));
+        // Last resort only: with even the pinned driver unregistered, null lets TG pick
+        // rather than throwing into the crash boundary.
+        Assert.Null(CobaltTuiApp.ResolveDriver(EnvVars(), ["ansi"], isWindows: true));
     }
 
     [Fact]
     public void Explicit_Value_Overrides_Multiplexer_Detection()
     {
         // COBALT_DRIVER=windows forces the Win32 driver even inside a multiplexer.
-        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(cobaltDriver: "windows", zellij: "0"), Known));
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(cobaltDriver: "windows", zellij: "0"), Known, isWindows: true));
     }
 
     [Fact]
-    public void No_Override_And_No_Multiplexer_Is_Null()
+    public void No_Override_And_No_Multiplexer_Pins_The_Platform_Default()
     {
-        Assert.Null(CobaltTuiApp.ResolveDriver(EnvVars(), Known));
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(), Known, isWindows: true));
     }
 
     [Theory]
@@ -103,27 +128,28 @@ public void Rdp_Session_Selects_The_Dotnet_Driver(string sessionName)
         // A remote/RDP session (e.g. a Windows 365 Cloud PC) paints through ConPTY's
         // console-buffer translation on the Win32 'windows' driver — expensive over a
         // latency link on a GPU-less host. The stdio/ANSI 'dotnet' driver skips it.
-        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(EnvVars(sessionName: sessionName), Known));
+        Assert.Equal("dotnet", CobaltTuiApp.ResolveDriver(EnvVars(sessionName: sessionName), Known, isWindows: true));
     }
 
     [Fact]
-    public void Console_Session_Stays_On_The_Default_Driver()
+    public void Console_Session_Pins_The_Windows_Driver()
     {
-        // A physical console (SESSIONNAME=Console) is unchanged: null → TG picks 'windows'.
-        Assert.Null(CobaltTuiApp.ResolveDriver(EnvVars(sessionName: "Console"), Known));
+        // A physical console (SESSIONNAME=Console) gets the same explicit pin as any
+        // non-multiplexed Windows terminal.
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(sessionName: "Console"), Known, isWindows: true));
     }
 
     [Fact]
     public void Explicit_Value_Overrides_Rdp_Detection()
     {
         // COBALT_DRIVER=windows forces the Win32 driver even in a remote session.
-        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(cobaltDriver: "windows", sessionName: "RDP-Tcp#0"), Known));
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(cobaltDriver: "windows", sessionName: "RDP-Tcp#0"), Known, isWindows: true));
     }
 
     [Fact]
-    public void Rdp_Session_Without_A_Dotnet_Driver_Falls_Back_To_Null()
+    public void Rdp_Session_Without_A_Dotnet_Driver_Falls_Back_To_The_Platform_Pin()
     {
-        Assert.Null(CobaltTuiApp.ResolveDriver(EnvVars(sessionName: "RDP-Tcp#0"), ["windows", "ansi"]));
+        Assert.Equal("windows", CobaltTuiApp.ResolveDriver(EnvVars(sessionName: "RDP-Tcp#0"), ["windows", "ansi"], isWindows: true));
     }
 
     [Fact]