Adopt libtmux Pane.capture_since() for the capture_since tool

[tony]

Important

Not mergeable yet. This branch pins libtmux to an unreleased branch. See Before merging below.

Summary

• Replace the capture_since tool's local read driver with libtmux's Pane.capture_since() — the cursor codec, anchor-loss and trim-risk checks, fingerprint re-anchoring, and the stable double-read all move upstream.
• Keep max_lines / max_bytes truncation here. Bounding a response so one observation cannot blow an agent's context window is an MCP concern, not a tmux one.
• Map libtmux's CaptureCursorError family to an agent-facing error that advises taking a fresh cursor, ahead of the generic tmux-error catch-all.
• Drop the state.py readers only this tool used. wait.py keeps the formats and parser it issues through its own timeout-bounded subprocess.
• Pin libtmux to the branch that adds Pane.capture_since(), temporarily.

The motivation is duplication: this tool's cursor machinery is general-purpose tmux observation that libtmux now ships. Two copies of the same anchor arithmetic is two copies to keep correct.

The cursor wire format is unchanged, so this tool's tests pass without modification and cursors issued by earlier versions still decode.

Changes by area

Tool

• tools/pane_tools/capture_since.py: Calls Pane.capture_since() off the event loop and applies the response limits to what comes back. The module docstring now states which half of the problem lives where.
• tools/pane_tools/state.py: Retains _PaneState, the format constants, the parser, and the lifecycle guard that wait.py imports; the two libtmux-backed readers go with the tool that used them.
• _utils.py: A CaptureCursorError branch in the shared exception mapper.

Tests

Behavioral tests are untouched. Two docstrings that explained why a test is shaped the way it is now name the upstream mechanism rather than a private symbol that used to be local.

Design decisions

Truncation stays here. libtmux's capture_since returns unbounded lines, matching capture_pane. The limiter runs after the capture completes, and the cursor is built from pane state rather than from the truncated rows, so bounding a response cannot shift where the next observation resumes.

CaptureCursorError gets its own mapping rather than falling through. The generic branch would render a replayed-cursor mistake as tmux error: ..., pointing the agent at tmux when the thing to fix is the cursor it sent. The new branch carries a suggestion to start a fresh observation.

Cursor failures are registered as non-retryable. Raising a real libtmux exception instead of a locally-built ExpectedToolError has a non-obvious consequence here: handle_tool_errors_async re-raises as ExpectedToolError(...) from e, and ReadonlyRetryMiddleware decides by walking __cause__ against LibTmuxException. Left alone, a malformed, cross-pane, dead-pane, or respawned-pane cursor would newly cost a backoff window and a duplicate tmux round-trip before failing identically. CaptureCursorError joins NON_RETRYABLE_EXCEPTIONS alongside the conceptually identical PaneNotFound. Worth knowing for any future swap of a local error for a libtmux one.

wait.py keeps issuing its own state read. It reads through a timeout-bounded subprocess.run rather than libtmux, because Popen.communicate() has no timeout and can wedge a worker thread on the wait path. That constraint is unchanged, so the shared format constants and parser stay.

Before merging

1. Land the companion libtmux PR and cut a libtmux release containing Pane.capture_since().
2. Remove the [tool.uv.sources] block from pyproject.toml and re-lock.
3. Raise the libtmux floor to that release. The current libtmux>=0.62.0,<1.0 would otherwise admit a version without Pane.capture_since(), and the import fails at load rather than at call.

Companion PR

libtmux: tmux-python/libtmux#741

Verification

Confirm no cursor machinery remains in this repository:

$ rg -n '_CaptureCursor|_build_cursor|_decode_cursor|_read_delta|_read_stable_visible' src/

Confirm the cursor type is imported from libtmux:

$ rg -n 'from libtmux.capture import' src/libtmux_mcp/tools/pane_tools/capture_since.py

Confirm response limiting still lives here:

$ rg -n 'def _limit_lines' src/libtmux_mcp/tools/pane_tools/capture_since.py

Test plan

• uv run ruff check . — lint clean
• uv run ruff format --check . — formatting clean
• uv run mypy src tests — no type errors
• uv run pytest -k capture_since — every existing capture_since test passes with no test-side change, against the upstream implementation
• uv run pytest tests/test_middleware.py — cursor failures are not retried; both new cases fail if CaptureCursorError is dropped from NON_RETRYABLE_EXCEPTIONS
• uv run pytest — full suite
• just build-docs — builds with no warnings

The suite carries load-sensitive wait_for_text timing flakes that predate this branch. A full run here and a full run on pristine main each produced a failure, and the two failure sets were disjoint — a test that failed here passed on main, and vice versa. Every one of them passes when re-run in isolation.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.43%. Comparing base (b90c58b) to head (6e3fe54).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #122      +/-   ##
==========================================
+ Coverage   86.24%   87.43%   +1.19%     
==========================================
  Files          46       46              
  Lines        4042     3860     -182     
  Branches      599      567      -32     
==========================================
- Hits         3486     3375     -111     
+ Misses        404      351      -53     
+ Partials      152      134      -18     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.