Capture(fix[review]): Refuse to read a failed capture as silence

why: Pane.capture_pane returns tmux's stdout without inspecting stderr,
so a failed capture and a blank pane were indistinguishable — the one
case where this module could return an incomplete delta without setting
lines_missed. Separately, the exhausted-retry path took three
unsynchronized reads, pairing an anchor row number with a fingerprint
sampled at a different instant.

what:
- Issue capture-pane directly and raise on stderr; the module only ever
  needs -p, -S and -E, so it does not need the wrapper's flag matrix
- Return the last attempt's paired reads when stability retries are
  exhausted, anchoring cursor and fingerprint to one sample and saving
  three round-trips
- Hash each row once in the fingerprint search instead of once per
  overlapping window
- Make the module-level entry point private; Pane.capture_since and
  CaptureCursor are the public surface
- Add a module logger and a DEBUG line explaining a missed capture
- Correct an inverted bound in the delta comment: start is below
  pane_height, and may be negative to address retained history

Author: tony

src/libtmux/capture.py

@@ -28,13 +28,17 @@
 import dataclasses
 import hashlib
 import json
+import logging
 import typing as t
 
 from libtmux import exc
+from libtmux.common import raise_if_stderr
 
 if t.TYPE_CHECKING:
     from libtmux.pane import Pane
 
+logger = logging.getLogger(__name__)
+
 
 #: Serialized-cursor prefix. Versioned so the wire format can change without
 #: a decoder silently misreading an older payload as a newer one.
@@ -553,10 +557,15 @@ def _find_unique_cursor_match(rows: list[str], cursor: CaptureCursor) -> int | N
     if len(rows) < len(fingerprint):
         return None
 
+    # Hash each row once. Windows overlap, so hashing per-window would
+    # re-hash a row once for every window it appears in -- up to the
+    # fingerprint's length -- on the path that is already the expensive
+    # fallback.
+    hashes = [_line_hash(line) for line in rows]
+
     match_index: int | None = None
-    for index in range(len(rows) - len(fingerprint) + 1):
-        candidate = rows[index : index + len(fingerprint)]
-        if tuple(_line_hash(line) for line in candidate) != fingerprint:
+    for index in range(len(hashes) - len(fingerprint) + 1):
+        if tuple(hashes[index : index + len(fingerprint)]) != fingerprint:
             continue
         if match_index is not None:
             return None
@@ -775,15 +784,27 @@ def _capture_rows(
     start: t.Literal["-"] | int | None = None,
     end: t.Literal["-"] | int | None = None,
 ) -> list[str]:
-    """Capture pane rows as a concrete list.
+    """Capture pane rows, refusing to mistake a failed read for silence.
+
+    Issues ``capture-pane`` directly rather than through
+    :meth:`~libtmux.pane.Pane.capture_pane`, which returns tmux's stdout
+    without inspecting stderr. A blank pane and a failed capture both
+    yield no rows there, and this module cannot tell a caller "nothing
+    was written" unless it knows the read succeeded.
 
     Examples
     --------
     >>> isinstance(_capture_rows(pane), list)
     True
     """
-    rows = pane.capture_pane(start=start, end=end)
-    return [] if rows is None else list(rows)
+    args = ["capture-pane", "-p"]
+    if start is not None:
+        args.extend(["-S", str(start)])
+    if end is not None:
+        args.extend(["-E", str(end)])
+    proc = pane.cmd(*args)
+    raise_if_stderr(proc, "capture-pane")
+    return list(proc.stdout)
 
 
 def _capture_cursor_rows(pane: Pane, state: _PaneState) -> list[str]:
@@ -816,6 +837,14 @@ def _read_stable_visible(
     the read is retried. After :data:`_STABLE_READ_ATTEMPTS` the rows are
     returned with ``lines_missed`` set rather than presented as exact.
 
+    Exhausting the attempts returns the *last attempt's* reads rather than
+    taking fresh ones. On a pane writing continuously enough to defeat
+    three brackets, another round of unbracketed samples would pair an
+    anchor row number with a fingerprint taken at a different instant, and
+    the resulting cursor would claim to anchor content it never saw. The
+    last attempt's ``before`` snapshot and the rows captured against it at
+    least describe one moment.
+
     Parameters
     ----------
     pane : Pane
@@ -836,6 +865,9 @@ def _read_stable_visible(
     >>> isinstance(read.lines, list)
     True
     """
+    before = _read_pane_state(pane)
+    lines: list[str] = []
+    cursor_rows: list[str] = []
     for _attempt in range(_STABLE_READ_ATTEMPTS):
         before = _read_pane_state(pane)
         if baseline_pid is None:
@@ -857,15 +889,15 @@ def _read_stable_visible(
                 lines_missed=False,
             )
 
-    state = _read_pane_state(pane)
-    if baseline_pid is None:
-        _raise_if_dead_without_baseline(pane, state)
-    else:
-        _raise_if_lifecycle_changed(pane.pane_id, state, baseline_pid)
+    logger.debug(
+        "pane never settled across %s reads; reporting a missed capture",
+        _STABLE_READ_ATTEMPTS,
+        extra={"tmux_pane": pane.pane_id, "tmux_stdout_len": len(lines)},
+    )
     return _PaneRead(
-        state=state,
-        cursor_rows=_capture_cursor_rows(pane, state),
-        lines=_capture_rows(pane),
+        state=before,
+        cursor_rows=cursor_rows,
+        lines=lines,
         lines_missed=True,
     )
 
@@ -915,8 +947,9 @@ def _read_delta(pane: Pane, cursor: CaptureCursor) -> _PaneRead:
             rows = _capture_rows(pane, start="-", end=None)
         else:
             # ``_cursor_anchor_lost`` returning False above already proved
-            # ``anchor_abs`` sits at or above the grid bottom, so ``start``
-            # is always inside the visible region here.
+            # ``anchor_abs`` sits at or below the grid bottom, so ``start``
+            # is always below ``pane_height``. It may still be negative,
+            # which is how ``capture-pane -S`` addresses retained history.
             rows = _capture_rows(pane, start=start, end=None)
         cursor_rows = _capture_cursor_rows(pane, before)
 
@@ -952,7 +985,7 @@ def _missed_read(pane: Pane, cursor: CaptureCursor) -> _PaneRead:
     return missed._replace(lines_missed=True)
 
 
-def capture_since(pane: Pane, cursor: CaptureCursor | None = None) -> CaptureSince:
+def _capture_since(pane: Pane, cursor: CaptureCursor | None = None) -> CaptureSince:
     """Capture rows written to ``pane`` since ``cursor``.
 
     Implements :meth:`libtmux.pane.Pane.capture_since`; call that instead.
@@ -979,8 +1012,8 @@ def capture_since(pane: Pane, cursor: CaptureCursor | None = None) -> CaptureSin
 
     Examples
     --------
-    >>> first = capture_since(pane)
-    >>> capture_since(pane, first.cursor).lines
+    >>> first = _capture_since(pane)
+    >>> _capture_since(pane, first.cursor).lines
     []
     """
     if pane.pane_id is None:

src/libtmux/pane.py

@@ -15,7 +15,7 @@
 
 from libtmux import exc
 from libtmux._internal.env import pane_id_from_env
-from libtmux.capture import CaptureCursor, CaptureSince, capture_since
+from libtmux.capture import CaptureCursor, CaptureSince, _capture_since
 from libtmux.common import get_version_str, has_gte_version, raise_if_stderr, tmux_cmd
 from libtmux.constants import (
     PANE_DIRECTION_FLAG_MAP,
@@ -766,7 +766,7 @@ def capture_since(self, cursor: CaptureCursor | None = None) -> CaptureSince:
 
         .. versionadded:: 0.63
         """
-        return capture_since(self, cursor)
+        return _capture_since(self, cursor)
 
     def send_keys(
         self,

tests/test_capture_since.py

@@ -273,6 +273,33 @@ def is_dead() -> bool:
         pane.capture_since()
 
 
+def test_a_failed_capture_raises_instead_of_reading_as_empty(
+    session: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A tmux capture failure is never reported as "nothing was written".
+
+    ``Pane.capture_pane`` returns tmux's stdout without inspecting stderr,
+    so a failed capture and a blank pane are indistinguishable there. Uses
+    ``monkeypatch`` because provoking a real ``capture-pane`` failure
+    against a live, healthy pane is not otherwise reachable.
+    """
+    pane = session.new_window(window_name="capture_since_failed_read").active_pane
+    assert pane is not None
+    real_cmd = type(pane).cmd
+
+    def failing_capture(self: Pane, *args: str) -> t.Any:
+        proc = real_cmd(self, *args)
+        if args and args[0] == "capture-pane":
+            proc.stderr = ["no such pane"]
+            proc.stdout = []
+        return proc
+
+    monkeypatch.setattr(type(pane), "cmd", failing_capture)
+
+    with pytest.raises(exc.LibTmuxException, match="capture-pane"):
+        pane.capture_since()
+
+
 def test_cursor_round_trips_through_a_string(session: Session) -> None:
     """A serialized cursor decodes back to an equal cursor."""
     pane = session.new_window(window_name="capture_since_codec").active_pane