Skip to content

Retain immutable pane capture observations - #810

Open
tony wants to merge 5 commits into
masterfrom
rmux-py-pane-observation
Open

tony wants to merge 5 commits into
masterfrom
rmux-py-pane-observation

Conversation

@tony

@tony tony commented Nov 1, 2026 •

Copy link
Copy Markdown
Member

PaneObservation.capture(pane) retains sampled pane text after redraw or removal. It copies lines and the actual command argv into a frozen standalone value, retaining capture selection and the controller's monotonic interval without live pane/server references.

The call uses the supplied pane.cmd route and refuses failed or oversized captures instead of returning a successful empty value. The decoded-text admission limit counts Python Unicode code points and LF, after the existing transport returns. It is not a transport memory cap or an added deadline. Pane lifetime remains explicitly unknown with the legacy handle. Lines are frozen before their retained size is measured, so a backend mutation cannot bypass the decoded-text admission check.

For example, saved = PaneObservation.capture(pane, start=-20) retains saved.text and saved.command after redraw or removal. Its range and joined-line selection follow tmux 3.2a capture semantics.

This is the independent pane-value slice of #370 and #584 under #629, based on current master with sibling branches absent. PR #568 still retains mutable nested lists/dicts; #587/#590 cover inherited object graphs and #613 covers mutable ASCII rendering and pytest integration. Their wider work remains open. This slice adds no engine classes, object graph, serializer or persistent recording.

Validation:

  • Owned noninteractive producer and API example on connected tmux 3.2a, 3.7b and stable 3.8; all retained fields survive redraw, pane removal and server destruction.
  • Actual custom command routing to a live selected endpoint despite a different facade endpoint; immutable text/argv aliases, Unicode/LF admission, native oversized captures, missing resources, stderr/nonzero/unknown status and original backend errors.
  • The original size-admission defect fails before repair; deliberate mutations of immutability, output ownership, routing, capture errors and limit enforcement fail their corresponding regressions.
  • Historical proposed-engine composition routed to the selected borrowed engine; that earlier receipt has not been requalified on this candidate.
  • Historical disposable composition with PR command(feat[timeout]) Add opt-in per-call deadlines #807 remains recorded; current qualification builds each slice independently.
  • Ruff, full-tree mypy, a typed external consumer, doctests, just build-docs and rendered API/changelog links pass.
  • Full configured pytest on stable 3.8 is FAIL: the failing node set exactly matches unchanged master. PR tmux(fix[3.8]): Support hooks and terminal fixtures #825 separately addresses the hooks, popup and floating-pane failures; retries are disabled.
  • Hosted checks at 398322f0e7442b37968add264157f15a621bd363 remain FAIL: tmux 3.3a pass; 3.2a, 3.4, 3.5, 3.6, 3.7a, 3.7b fail. CodeQL passes; codecov/project fails. The development-tmux job allows failures and is not full-suite pass evidence. The 3.2a failure is the existing capture test accepting an echoed, unexecuted completion marker; the other stable failures include the cached-binary ABI problem tracked in tmux(fix[3.8]): Support hooks and terminal fixtures #825.

Retained values remain readable while referenced, including after server loss; process exit loses the in-memory value. Captures cannot establish omitted-output continuity, hidden terminal state, or arbitrary-shell completion. A cooperating producer's signal establishes only its application-defined milestone. No macOS work or minimum-version change is included; existing support remains unchanged.

Refs #370 and #584. Keep full object graphs, serialization and wiring retained observations into every failure open under those canonical issues. The failed mandatory full-suite gate keeps delivery partial; maintainer review remains pending.

@codecov

codecov Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 64.00000% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.52%. Comparing base (03c4c4b) to head (ce4abc5).

Files with missing lines Patch % Lines
src/libtmux/observation.py 64.00% 17 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #810      +/-   ##
==========================================
+ Coverage   52.37%   52.52%   +0.15%     
==========================================
  Files          26       27       +1     
  Lines        3729     3779      +50     
  Branches      747      757      +10     
==========================================
+ Hits         1953     1985      +32     
- Misses       1472     1489      +17     
- Partials      304      305       +1     

☔ 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.

@tony tony mentioned this pull request Nov 1, 2026
10 tasks
@tony tony added this to libtmux Nov 1, 2026
@tony tony moved this to In Progress in libtmux Nov 1, 2026
tony added a commit that referenced this pull request Nov 1, 2026
why: Readers need product notes before adopting this change.

what:
- Describe retained pane observations in the unreleased changelog
- Reference PR #810
@tony
tony force-pushed the rmux-py-pane-observation branch from 041e23d to d794cc8 Compare November 1, 2026 13:51
tony added 5 commits November 6, 2026 19:40
why: Consumers need capture evidence that remains readable after redraw or pane removal.
what:
- Copy decoded text and command provenance into a frozen standalone value
- Preserve backend routing and reject failed or oversized captures
- Document sampled identity limits and verify retained text with an owned producer
why: Readers need product notes before adopting this change.

what:
- Describe retained pane observations in the unreleased changelog
- Reference PR #810
why: A backend can change its mutable output after size validation, leaving
an observation with more retained text than its admission limit permits.
what:
- Copy decoded lines once before measuring and retaining them
- Cover native custom routing, redraw, pane removal and server removal
- Document observation fields and qualify producer signal semantics
why: Keep development and CI linting on the same Ruff release,
including corrected f-string conversions and safer lint fixes.

what:
- Raise Ruff floors in the development and lint dependency groups
- Lock Ruff 0.17.3 with its published source and wheel hashes

Ruff release notes:
https://github.com/astral-sh/ruff/releases/tag/0.17.2
https://github.com/astral-sh/ruff/releases/tag/0.17.3
why: Contributors need the lint-tool requirement alongside other
development environment changes.

what:
- Document the Ruff 0.17.3 minimum for development and lint checks
@tony
tony force-pushed the rmux-py-pane-observation branch from 398322f to ce4abc5 Compare November 7, 2026 02:17

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

1 participant