feat(pane_tools): Add capture_since incremental pane reader

[tony]

Summary

• Add capture_since — a non-blocking, cursor-based incremental pane reader that returns only new terminal output since the previous observation
• Add fingerprint-based cursor re-anchoring to detect and report history-limit trimming without silently dropping output
• Route server instructions, prompts, docs, and recipes toward capture_since for repeated-observation workflows (tailing, diagnosis, multi-pane monitoring)
• Extract shared _PaneState and lifecycle helpers into pane_tools/state.py so wait_for_text and capture_since share the same tmux state reading

Changes by area

Tool implementation

• tools/pane_tools/capture_since.py: Core tool — cursor encode/decode, stable double-read with retry, delta extraction, fingerprint-based re-anchoring under trim risk, tail-preserving line/byte truncation
• tools/pane_tools/state.py: Extracted _PaneState NamedTuple and _read_pane_state() helper (previously inline in wait.py)
• models.py: CaptureSinceResult Pydantic model with cursor, lines, and structured loss/truncation metadata

Server registration

• server.py: Register capture_since in response-limited tools list; update instruction strings to recommend it for repeated observation

Documentation

• docs/tools/pane/capture-since.md: Dedicated tool page explaining cursor lifecycle, delta semantics, and lines_missed recovery
• docs/topics/pagination.md: Distinguish protocol pagination, search paging, and observation cursors
• docs/topics/prompting.md, docs/recipes.md, docs/demo.md: Route tailing and diagnosis workflows to capture_since

Design decisions

• Non-blocking immediate return: Avoids agent lockout — the agent controls poll timing, not the tool
• Opaque versioned cursor: capture-since-v1: prefix + base64 JSON payload keeps the wire format stable if internals change; agents must treat the cursor as opaque
• SHA-256 row fingerprinting for trim recovery: When history-limit trimming makes the positional anchor ambiguous, re-locate via content hashes; report lines_missed=True if the fingerprint is non-unique or absent
• Agent judges, not ctx.sample(): No hidden LLM call — the agent has full project context and can interpret terminal output directly
• Tail-preserving truncation: Newest output is most actionable; oldest lines drop first

Verification

Verify capture_since is registered and response-limited:

rg "capture_since" src/libtmux_mcp/server.py

Verify shared state helpers are imported by both tools:

rg "from libtmux_mcp.tools.pane_tools.state import" src/

Test plan

• test_capture_since_first_call_returns_visible_screen_and_cursor — baseline capture returns content and opaque cursor
• test_capture_since_followup_returns_only_new_output — delta contains only rows written after the cursor
• test_capture_since_follows_anchor_into_retained_history — cursor tracks output that scrolls into retained scrollback
• test_capture_since_marks_lines_missed_after_history_limit_trim — lines_missed=True when trim exceeds fingerprint recovery
• test_capture_since_marks_lines_missed_after_history_clear — lines_missed=True after clear-history
• test_capture_since_reports_same_row_rewrite — carriage-return/printf overwrites are detected
• test_capture_since_truncates_with_structured_metadata — max_lines/max_bytes produce correct truncated_lines/truncated_bytes
• test_capture_since_rejects_malformed_cursor — garbage and wrong-version cursors raise ToolError
• test_capture_since_rejects_cursor_for_different_pane — cross-pane cursor reuse raises ToolError
• test_capture_since_rejects_respawned_pane_cursor — PID mismatch after respawn-pane raises ToolError
• test_capture_since_rejects_dead_pane_cursor — dead pane raises ToolError
• test_capture_since_does_not_block_event_loop — async wrapper offloads to thread
• Full verification chain: ruff check, ruff format --check, mypy --strict, pytest

Closes #60

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 69.76744% with 78 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.31%. Comparing base (3fe34da) to head (7b11f17).

Files with missing lines	Patch %	Lines
src/libtmux_mcp/tools/pane_tools/capture_since.py	65.48%	57 Missing and 21 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #63      +/-   ##
==========================================
- Coverage   85.98%   84.31%   -1.68%     
==========================================
  Files          40       42       +2     
  Lines        2448     2684     +236     
  Branches      319      359      +40     
==========================================
+ Hits         2105     2263     +158     
- Misses        260      317      +57     
- Partials       83      104      +21     

☔ View full report in Codecov by Sentry.
📢 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.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}