From 66149ca6681102ff758b516984a1ccfe2ce0d974 Mon Sep 17 00:00:00 2001
From: Kyle <50718101+kylesower@users.noreply.github.com>
Date: Fri, 24 Apr 2026 13:45:20 -0500
Subject: [PATCH] feat(tui): restore 'ttyfast' to control tty requests #38699

Problem:
When running nvim on a remote machine over SSH, if there is high ping,
then bg detection may not complete in time. This results in a warning
every time nvim is started. #38648

Solution:
Restore 'ttyfast' option and allow it to control whether or not bg
detection is performed. Because this is during startup and before any
user config or commands, we use the environment variable
`NVIM_NOTTYFAST` to allow disabling `ttyfast` during initialization.
---
 runtime/doc/news.txt                   |  2 ++
 runtime/doc/options.txt                | 10 ++++++++++
 runtime/doc/vim_diff.txt               |  5 +++--
 runtime/lua/vim/_core/defaults.lua     |  9 ++++++---
 runtime/lua/vim/_meta/options.gen.lua  | 13 +++++++++++++
 runtime/scripts/optwin.lua             |  1 +
 src/nvim/option.c                      |  6 ++++++
 src/nvim/option_vars.h                 |  1 +
 src/nvim/options.lua                   | 12 ++++++++++--
 test/functional/plugin/optwin_spec.lua |  1 -
 test/functional/terminal/tui_spec.lua  |  2 +-
 11 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index d47a39fdc9..ea340105d3 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -164,6 +164,8 @@ the same range instances now compare equal.
 
 OPTIONS
 
+• 'ttyfast' can be disabled during startup by setting the environment variable
+  `NVIM_NOTTYFAST` to disable automatic background detection.
 • 'scrolloffpad' allows vertically centering cursor at the end of file.
 • 'winpinned' prevents window from closing unless specifically targeted.
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index af3d8d57b3..a106b6065e 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -7010,6 +7010,16 @@ A jump table for the options with a short description can be found at |Q_op|.
 	used for CTRL-\ CTRL-N and CTRL-\ CTRL-G when part of a command has
 	been typed.
 
+				*'ttyfast'* *'tf'* *'nottyfast'* *'notf'*
+'ttyfast' 'tf'		boolean	(default on)
+			global
+	Assume that the underlying terminal can respond quickly to queries
+	required by features such as 'background' detection.
+
+	Nvim issues terminal queries before reading the user's |config| file,
+	so disabling this option there will not work. Set $NVIM_NOTTYFAST
+	before starting Nvim to disable terminal queries.
+
 					*'undodir'* *'udir'* *E5003*
 'undodir' 'udir'	string	(default "$XDG_STATE_HOME/nvim/undo//")
 			global
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 67a87a3c4e..1d3e61b54a 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -88,7 +88,9 @@ Defaults                                            *defaults* *nvim-defaults*
   host terminal
 - 'ttimeout' is enabled
 - 'ttimeoutlen' defaults to 50
-- 'ttyfast' is always set
+- 'ttyfast' is set by default, but it can be unset during startup by setting
+  the environment variable `NVIM_NOTTYFAST` to adjust the startup sequence for
+  slow environments.
 - 'undodir' defaults to ~/.local/state/nvim/undo// (|xdg|), auto-created
 - 'viewoptions' includes "unix,slash", excludes "options"
 - 'viminfo' includes "!"
@@ -877,7 +879,6 @@ Options:
 - *'toolbar'* *'tb'*
 - *'toolbariconsize'* *'tbis'*
 - *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'*
-- *'ttyfast'* *'tf'* *'nottyfast'* *'notf'*
 - *'ttymouse'* *'ttym'*
 - *'ttyscroll'* *'tsl'*
 - *'ttytype'* *'tty'*
diff --git a/runtime/lua/vim/_core/defaults.lua b/runtime/lua/vim/_core/defaults.lua
index 80327e0fc7..40c2304a1a 100644
--- a/runtime/lua/vim/_core/defaults.lua
+++ b/runtime/lua/vim/_core/defaults.lua
@@ -847,7 +847,10 @@ do
     --- ignored in the calculations.
     ---
     --- [1] https://en.wikipedia.org/wiki/Luma_%28video%29
-    do
+    ---
+    --- In slow environments (e.g. SSH with high latency), this will increase
+    --- startup time and produce a warning, so users may want to disable it.
+    if vim.o.ttyfast then
       --- Parse a string of hex characters as a color.
       ---
       --- The string can contain 1 to 4 hex characters. The returned value is
@@ -999,7 +1002,7 @@ do
         and os.getenv('NVIM_TEST') == nil
       then
         vim.notify(
-          'defaults.lua: Did not detect DSR response from terminal. This results in a slower startup time.',
+          "defaults.lua: Did not detect DSR response from terminal for 'background' detection. This results in a slower startup time. To disable this and other 'ttyfast' features during startup, set the environment variable NVIM_NOTTYFAST",
           vim.log.levels.WARN,
           { _truncate = true }
         )
@@ -1017,7 +1020,7 @@ do
         -- The TUI was able to determine truecolor support or $COLORTERM explicitly indicates
         -- truecolor support
         setoption('termguicolors', true)
-      elseif colorterm == nil or colorterm == '' then
+      elseif (colorterm == nil or colorterm == '') and vim.o.ttyfast then
         -- Neither the TUI nor $COLORTERM indicate that truecolor is supported, so query the
         -- terminal
         local caps = {} ---@type table<string, boolean>
diff --git a/runtime/lua/vim/_meta/options.gen.lua b/runtime/lua/vim/_meta/options.gen.lua
index 29bab51233..724432cddb 100644
--- a/runtime/lua/vim/_meta/options.gen.lua
+++ b/runtime/lua/vim/_meta/options.gen.lua
@@ -7555,6 +7555,19 @@ vim.o.ttm = vim.o.ttimeoutlen
 vim.go.ttimeoutlen = vim.o.ttimeoutlen
 vim.go.ttm = vim.go.ttimeoutlen
 
+--- Assume that the underlying terminal can respond quickly to queries
+--- required by features such as 'background' detection.
+---
+--- Nvim issues terminal queries before reading the user's `config` file,
+--- so disabling this option there will not work. Set $NVIM_NOTTYFAST
+--- before starting Nvim to disable terminal queries.
+---
+--- @type boolean
+vim.o.ttyfast = true
+vim.o.tf = vim.o.ttyfast
+vim.go.ttyfast = vim.o.ttyfast
+vim.go.tf = vim.go.ttyfast
+
 --- List of directory names for undo files, separated with commas.
 --- See 'backupdir' for details of the format.
 --- "." means using the directory of the file.  The undo file name for
diff --git a/runtime/scripts/optwin.lua b/runtime/scripts/optwin.lua
index ff5bd8d7f6..940a41164c 100644
--- a/runtime/scripts/optwin.lua
+++ b/runtime/scripts/optwin.lua
@@ -455,6 +455,7 @@ local options_list = {
     { 'busy', N_ 'buffer is busy' },
     { 'termpastefilter', N_ 'characters removed when pasting into terminal window' },
     { 'scrollback', N_ 'number of lines kept beyond the visible screen in terminal buffer' },
+    { 'ttyfast', N_ 'assume terminal responds quickly, enabling more features' },
   },
 }
 
diff --git a/src/nvim/option.c b/src/nvim/option.c
index a392412d53..c23a6855aa 100644
--- a/src/nvim/option.c
+++ b/src/nvim/option.c
@@ -407,6 +407,12 @@ void set_init_1(bool clean_arg)
   // Expand environment variables and things like "~" for the defaults.
   set_init_expand_env();
 
+  // Allow disabling ttyfast during startup to disable features such as
+  // automatic background detection over slow connections.
+  if (os_env_exists("NVIM_NOTTYFAST", false)) {
+    set_option_value_give_err(kOptTtyfast, BOOLEAN_OPTVAL(false), 0);
+  }
+
   save_file_ff(curbuf);         // Buffer is unchanged
 
   // Detect use of mlterm.
diff --git a/src/nvim/option_vars.h b/src/nvim/option_vars.h
index c57020b553..226f4ad242 100644
--- a/src/nvim/option_vars.h
+++ b/src/nvim/option_vars.h
@@ -553,6 +553,7 @@ EXTERN char *p_tsr;             ///< 'thesaurus'
 EXTERN int p_tgc;               ///< 'termguicolors'
 EXTERN int p_ttimeout;          ///< 'ttimeout'
 EXTERN OptInt p_ttm;            ///< 'ttimeoutlen'
+EXTERN int p_tf;                ///< 'ttyfast'
 EXTERN char *p_udir;            ///< 'undodir'
 EXTERN int p_udf;               ///< 'undofile'
 EXTERN OptInt p_ul;             ///< 'undolevels'
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index 3ab60f0af9..9192a1ee51 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -9777,12 +9777,20 @@ local options = {
     {
       abbreviation = 'tf',
       defaults = true,
+      desc = [=[
+        Assume that the underlying terminal can respond quickly to queries
+        required by features such as 'background' detection.
+        
+        Nvim issues terminal queries before reading the user's |config| file,
+        so disabling this option there will not work. Set $NVIM_NOTTYFAST
+        before starting Nvim to disable terminal queries.
+      ]=],
       full_name = 'ttyfast',
       no_mkrc = true,
       scope = { 'global' },
-      short_desc = N_('Deprecated'),
+      short_desc = N_('assume terminal responds quickly, enabling more features'),
       type = 'boolean',
-      immutable = true,
+      varname = 'p_tf',
     },
     {
       abbreviation = 'udir',
diff --git a/test/functional/plugin/optwin_spec.lua b/test/functional/plugin/optwin_spec.lua
index 2cfed64588..2e9a990fee 100644
--- a/test/functional/plugin/optwin_spec.lua
+++ b/test/functional/plugin/optwin_spec.lua
@@ -80,7 +80,6 @@ describe('optwin.lua', function()
       'pastetoggle',
       'langnoremap',
       'opendevice',
-      'ttyfast',
       'remap',
       'hkmap',
       'hkmapp',
diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua
index e97597f521..77660d8b23 100644
--- a/test/functional/terminal/tui_spec.lua
+++ b/test/functional/terminal/tui_spec.lua
@@ -3326,7 +3326,7 @@ describe('TUI', function()
     end)
     local child_session = n.connect(child_server)
     local expected_msg =
-      'defaults.lua: Did not detect DSR response from terminal. This results in a slower startup time.'
+      "defaults.lua: Did not detect DSR response from terminal for 'background' detection. This results in a slower startup time. To disable this and other 'ttyfast' features during startup, set the environment variable NVIM_NOTTYFAST"
     retry(nil, 4000, function()
       eq({ true, { mode = 'n', blocking = false } }, { child_session:request('nvim_get_mode') })
       if not is_os('win') then -- ConPTY provides DSR response on Windows?