fix(cli): render mid-spin log lines flush-left, coordinating spinner and logging

Log records emitted while the TTY spinner was painting rendered with
phantom leading padding (e.g. 19 blank columns after a '[|] set_repo
remove' frame during update/prepare), or -- with colours disabled on a
TTY -- glued straight onto the leftover frame text. ColorFormatter
prepended ESC[2K (erase entire line) to the levelname, which blanks the
frame but leaves the cursor at the frame's end column, so the record
started mid-line; with colours off there was no erase at all.

Move screen management out of the formatter into a shared seam:

* mtui/support/spinner.py: serialize frame painting through a
  module-level RLock, register active spinners, and expose
  spinner_suspended() -- it erases the visible frame with CR + ESC[K
  (homing the cursor to column 0) and pauses repainting while held.
  stop() erases under the lock and _spin re-checks the stop flag under
  the lock so a frame is never repainted after stop erased it.
* mtui/cli/colors/formatter.py: emit every record from a
  SpinnerAwareStreamHandler that wraps super().emit() in
  spinner_suspended(), and drop the ESC[2K injections from
  ColorFormatter (also fixes the NO_COLOR-on-a-TTY variant and stops
  the escape leaking into non-terminal handlers such as the MCP
  capture handler).
* mtui/cli/prompter.py: hold spinner_suspended() for the whole stdin
  read so the SSH command-timeout prompt is not repainted over by a
  live 'run' spinner.

Off a TTY nothing changes: spinners never register, spinner_suspended()
writes nothing, and the handler behaves like a plain StreamHandler.
Worker parallelism is untouched -- only terminal writes serialize.

Regression tests drive the real spinner and the real create_logger
handler against a pty and assert on the raw captured bytes: a record
emitted mid-spin must be preceded by CR + ESC[K and render flush-left;
the non-TTY path is pinned byte-exact.

Author: plusky

CHANGELOG.md

@@ -434,6 +434,15 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
   (e.g. a plain file in the way) is now reported as one clear error naming the
   option instead of an `OSError` traceback, and openQA queries catch any
   remaining URL/transport error shape instead of crashing the command.
+- Log lines emitted while the TTY spinner is painting (e.g. the per-host
+  `Removing repo … on <host>` lines under the `set_repo remove` spinner during
+  `update`/`prepare`) no longer render with phantom leading padding — or, with
+  colours off, glued to the leftover frame text. The spinner and the logging
+  handler now coordinate through a shared paint lock: each record first erases
+  the live frame and homes the cursor to column 0, then prints, and the spinner
+  repaints on its next tick. Interactive prompts raised under a live spinner
+  (e.g. the SSH command-timeout question) also pause the spinner for the whole
+  read instead of repainting over the prompt. Off a TTY nothing changes.
 
 ## 18.2.0 - 2026-06-23
 

mtui/cli/colors/formatter.py

@@ -3,6 +3,7 @@
 import inspect
 import logging
 
+from ...support.spinner import spinner_suspended
 from .mode import colors_enabled
 
 # ANSI color offsets (added to 30 to form the foreground color escape code).
@@ -60,21 +61,15 @@ def formatColor(self, levelname: str) -> str:
             if not colors_enabled():
                 return levelname.lower() + suffix
             return (
-                "\033[2K"
-                + COLOR_SEQ.format(30 + COLORS[levelname])
+                COLOR_SEQ.format(30 + COLORS[levelname])
                 + levelname.lower()
                 + RESET_SEQ
                 + suffix
                 + RESET_SEQ
             )
         if not colors_enabled():
             return levelname.lower()
-        return (
-            "\033[2K"
-            + COLOR_SEQ.format(30 + COLORS[levelname])
-            + levelname.lower()
-            + RESET_SEQ
-        )
+        return COLOR_SEQ.format(30 + COLORS[levelname]) + levelname.lower() + RESET_SEQ
 
     @staticmethod
     def _find_caller_frame() -> tuple[object, str] | None:
@@ -113,8 +108,31 @@ def format(self, record: logging.LogRecord) -> str:
         return logging.Formatter.format(self, record)
 
 
+class SpinnerAwareStreamHandler(logging.StreamHandler):
+    """A stream handler that coordinates with a live TTY spinner.
+
+    Every record is emitted inside :func:`spinner_suspended`: while a
+    :class:`mtui.support.spinner.TtySpinner` is painting, the handler
+    erases the current frame (``\\r`` + erase-to-end, homing the cursor
+    to column 0), writes the record from a clean line, and lets the
+    spinner repaint on its next tick. Without this, a record emitted
+    mid-spin starts at the column where the frame write left the
+    cursor, rendering with phantom leading padding (or, with colours
+    off, appended straight after the frame text).
+
+    When no spinner is active — notably off a TTY, where spinners never
+    start — the wrapper adds nothing and the handler behaves exactly
+    like a plain :class:`logging.StreamHandler`.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emit the record with any live spinner frame erased first."""
+        with spinner_suspended():
+            super().emit(record)
+
+
 def create_logger(name: str, level: str = "INFO") -> logging.Logger:
-    """Creates a logger with a colorized output.
+    """Creates a logger with a colorized, spinner-aware output.
 
     Args:
         name: The name of the logger.
@@ -126,7 +144,7 @@ def create_logger(name: str, level: str = "INFO") -> logging.Logger:
     """
     out = logging.getLogger(name) if name else logging.getLogger()
     out.setLevel(level)
-    handler = logging.StreamHandler()
+    handler = SpinnerAwareStreamHandler()
     formatter = ColorFormatter("%(levelname)s: %(message)s")
     handler.setFormatter(formatter)
     out.addHandler(handler)

mtui/cli/prompter.py

@@ -19,6 +19,8 @@
 import threading
 from collections.abc import Callable
 
+from ..support.spinner import spinner_suspended
+
 
 class Prompter:
     """Serialise interactive prompts across worker threads.
@@ -53,7 +55,11 @@ def ask(self, text: str) -> str:
         """Prompt the user with ``text`` and return the typed response.
 
         Acquires the prompter's lock for the duration of the read so
-        sibling workers cannot race for ``stdin``.
+        sibling workers cannot race for ``stdin``, and holds
+        :func:`mtui.support.spinner.spinner_suspended` for the whole
+        read so a live TTY spinner (e.g. ``run_parallel``'s) erases its
+        frame and stops repainting over the prompt until the user has
+        answered. A no-op when no spinner is active.
 
         Args:
             text: The prompt text shown to the user.
@@ -63,5 +69,5 @@ def ask(self, text: str) -> str:
             identical to :func:`input`).
 
         """
-        with self._lock:
+        with self._lock, spinner_suspended():
             return self._reader(text)

mtui/support/spinner.py

@@ -4,6 +4,14 @@
 stderr is a TTY. Off a TTY (pytest, redirected output, log files, the
 ``mtui-mcp`` transport) it is a no-op, so test output and log files stay clean
 and the MCP layer can surface progress through its own channel instead.
+
+Frame painting is serialised through a module-level paint lock so other
+writers on the same terminal can coordinate with a live spinner: wrap the
+write in :func:`spinner_suspended` to erase the current frame, keep the
+spinner from repainting while the block runs, and write from column 0. The
+logging handler installed by :func:`mtui.cli.colors.create_logger` does this
+for every record, so worker-thread log lines emitted mid-spin render
+flush-left instead of starting at the cursor column the frame left behind.
 """
 
 from __future__ import annotations
@@ -13,6 +21,38 @@
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager, suppress
 
+#: Serialises every write that repaints or erases a spinner frame. An
+#: ``RLock`` so a thread already holding it (e.g. a prompt inside
+#: :func:`spinner_suspended`) can log without deadlocking itself.
+_paint_lock = threading.RLock()
+
+#: Spinners currently painting frames (TTY-enabled and started, not yet
+#: stopped). Guarded by :data:`_paint_lock`. Empty off a TTY, so
+#: :func:`spinner_suspended` is a strict no-op there.
+_active: set[TtySpinner] = set()
+
+
+@contextmanager
+def spinner_suspended() -> Iterator[None]:
+    """Pause spinner painting for the block and erase any visible frame.
+
+    Acquires the paint lock for the whole block, so a live spinner cannot
+    repaint while the caller writes to the terminal. If a spinner is
+    active, the current frame is erased first (``\\r`` + erase-to-end) and
+    the cursor is homed to column 0, so the caller's output starts on a
+    clean line. The spinner repaints on its next tick after the block
+    exits.
+
+    A no-op (beyond taking the lock) when no spinner is active — in
+    particular off a TTY, where spinners never register.
+    """
+    with _paint_lock:
+        if _active:
+            with suppress(Exception):
+                sys.stderr.write("\r\033[K")
+                sys.stderr.flush()
+        yield
+
 
 class TtySpinner:
     """A ``|/-\\`` spinner driven by one daemon thread; a no-op off a TTY.
@@ -33,6 +73,8 @@ def start(self) -> None:
         """Start the spinner thread (no-op when stderr is not a TTY)."""
         if not self._enabled:
             return
+        with _paint_lock:
+            _active.add(self)
         self._thread = threading.Thread(target=self._spin, daemon=True)
         self._thread.start()
 
@@ -47,9 +89,12 @@ def stop(self) -> None:
             self._thread.join(timeout=1.0)
             self._thread = None
         # Erase the spinner line so the next caller writes from column 0.
-        with suppress(Exception):
-            sys.stderr.write("\r\033[K")
-            sys.stderr.flush()
+        # Under the paint lock so the erase cannot race a frame repaint.
+        with _paint_lock:
+            _active.discard(self)
+            with suppress(Exception):
+                sys.stderr.write("\r\033[K")
+                sys.stderr.flush()
 
     def is_stopped(self) -> bool:
         """True once :meth:`stop` has been called (set even off a TTY).
@@ -62,9 +107,15 @@ def is_stopped(self) -> bool:
     def _spin(self) -> None:
         i = 0
         while not self._stop.is_set():
-            with suppress(Exception):
-                sys.stderr.write(f"\r[{self._FRAMES[i % 4]}] {self._desc}")
-                sys.stderr.flush()
+            with _paint_lock:
+                # Re-check under the lock: a long ``spinner_suspended`` hold
+                # (e.g. an interactive prompt) can outlive ``stop()``; never
+                # repaint a frame that ``stop`` has already erased.
+                if self._stop.is_set():
+                    return
+                with suppress(Exception):
+                    sys.stderr.write(f"\r[{self._FRAMES[i % 4]}] {self._desc}")
+                    sys.stderr.flush()
             i += 1
             self._stop.wait(self._INTERVAL)
 

tests/test_spinner.py

@@ -43,7 +43,10 @@ def test_spin_paints_a_frame(monkeypatch):
     fake = _fake_tty(monkeypatch)
     s = TtySpinner("regen")
 
-    calls = iter([False, True])  # one loop body, then exit
+    # ``_spin`` checks the stop event twice per iteration: once in the loop
+    # condition and once under the paint lock (so a frame is never repainted
+    # after ``stop`` erased it). One painted frame, then exit.
+    calls = iter([False, False, True])
     s._stop = MagicMock()  # noqa: SLF001
     s._stop.is_set.side_effect = lambda: next(calls)  # noqa: SLF001
     s._stop.wait.return_value = None  # noqa: SLF001
@@ -81,3 +84,21 @@ def test_is_stopped_set_even_off_a_tty(monkeypatch):
     assert s.is_stopped() is False
     s.stop()
     assert s.is_stopped() is True
+
+
+def test_spin_never_repaints_after_stop_wins_the_lock(monkeypatch):
+    """stop() landing between the while-check and the paint lock wins.
+
+    A long ``spinner_suspended`` hold can outlive ``stop()``; the frame
+    painter must re-check the stop flag under the lock and bail without
+    painting, or it would repaint a frame stop() already erased.
+    """
+    fake = _fake_tty(monkeypatch)
+    s = TtySpinner("desc")
+    # First is_set(): the outer while condition (not stopped yet). Second:
+    # the re-check under the paint lock (stop() got there first).
+    s._stop.is_set = MagicMock(side_effect=[False, True])
+
+    s._spin()
+
+    fake.write.assert_not_called()