diff --git a/libs/code/deepagents_code/tui/widgets/messages.py b/libs/code/deepagents_code/tui/widgets/messages.py
index 0249c1fe265..5df1f3df3eb 100644
--- a/libs/code/deepagents_code/tui/widgets/messages.py
+++ b/libs/code/deepagents_code/tui/widgets/messages.py
@@ -1982,18 +1982,19 @@ def _format_ls_output(  # noqa: PLR6301  # Grouped as method for widget cohesion
 
     @staticmethod
     def _compact_line_gutter(output: str) -> str:
-        r"""Tighten `read_file`'s cat -n line-number gutter for display.
-
-        The tool emits `f"{line_num:6d}\t{line}"` — a 6-wide right-justified
-        number plus a tab — so even single-digit line numbers carry five
-        leading spaces and the tab pushes content to a distant tab stop. The
-        model needs that raw format for edits, but the TUI renders a compact
-        gutter instead: numbers right-justified to the widest number actually
-        present, then two spaces, mirroring how grep/glob results sit flush
-        left. Source indentation after the gutter is preserved untouched.
-
-        Lines that don't match the cat -n shape (e.g. test fixtures or
-        non-numbered output) are passed through unchanged.
+        r"""Tighten legacy `read_file` cat-n line-number gutters for display.
+
+        Older tool output used `f"{line_num:6d}\t{line}"` — a 6-wide
+        right-justified number plus a tab — so even single-digit line numbers
+        carried five leading spaces and the tab pushed content to a distant tab
+        stop. The TUI renders that legacy gutter in the newer compact shape:
+        numbers right-justified to the widest number actually present, then two
+        spaces, mirroring how grep/glob results sit flush left. Source
+        indentation after the gutter is preserved untouched.
+
+        Lines that don't match the legacy cat-n shape (e.g. current compact
+        read output, test fixtures, or non-numbered output) are passed through
+        unchanged.
 
         Returns:
             The output with compacted gutters, or the original string if no
diff --git a/libs/code/tests/unit_tests/tui/widgets/test_messages.py b/libs/code/tests/unit_tests/tui/widgets/test_messages.py
index 38a322c8fab..53022b97be5 100644
--- a/libs/code/tests/unit_tests/tui/widgets/test_messages.py
+++ b/libs/code/tests/unit_tests/tui/widgets/test_messages.py
@@ -2760,14 +2760,14 @@ def test_format_file_output_preview_budget_hit_on_separator(self) -> None:
     def test_format_output_compacts_line_number_gutter(self) -> None:
         r"""Line-number gutters are tightened, all rows aligned to one column.
 
-        `read_file` emits `f"{line_num:6d}\t{line}"` — a 6-wide right-justified
-        number plus a tab — which renders far from the line numbers and (when
-        the first row's padding was stripped) misaligned. The TUI recomputes a
-        compact gutter: numbers right-justified to the widest number present,
-        two spaces, then the original source indentation.
+        Legacy `read_file` output used `f"{line_num:6d}\t{line}"` — a 6-wide
+        right-justified number plus a tab — which renders far from the line
+        numbers and (when the first row's padding was stripped) misaligned. The
+        TUI recomputes a compact gutter: numbers right-justified to the widest
+        number present, two spaces, then the original source indentation.
         """
         msg = ToolCallMessage("read_file", {"path": "/tmp/a.py"})
-        # cat -n style: 6-wide right-justified number + tab + source line.
+        # Legacy cat-n style: 6-wide right-justified number + tab + source line.
         output = '     1\t"""doc"""\n     2\t\n     3\t    indented'
         result = msg._format_output(output, is_preview=False)