Skip to content

Investigate libtmux-side trim detection for scrollback consumers #671

Open

Description

@tony

Two equal captures do not prove that no output was lost between them. At the history cap, repeated rows can be trimmed and replaced while captured text, history_size, cursor position and geometry remain equal.

PR #808 adds an independently tested reproducer and documents that ambiguity. On an owned 20×5 pane with five history rows, two bursts of repeated output produce identical captures and cursor/history observations. The newer qualified build’s history_collected counter changes; the older supported floor does not supply that counter. Changing the second burst makes the equality assertion fail, so the regression detects the intended counterexample.

Native capabilities are version-specific. Current inspected tmux source exposes history_collected and history_generation, backed by history collection and unsigned counters. Do not generalize the historical absence of such fields to every current build. A qualified counter can positively expose collection/reset within its evidenced lifetime; it cannot reconstruct freed text or turn separate metadata and capture commands into an atomic checkpoint. Counter wrap, reset, unsupported formats and uncertain lifetimes require explicit uncertainty.

Acceptance remains:

  • Merge the reproducible repeated-row case and limitation documentation, with the supported-floor and newer-build controls. An open PR is not completion.
  • Classify positive evidence of trim/reset, conservative invalidation and unknown continuity without fabricating a continuous empty delta.
  • Qualify any counter/timestamp aid against the connected daemon and known grid/pane lifetime, including unavailable fields and counter/reset ambiguity.
  • Preserve feature: upstream capture_since #740’s immutable cursor semantics and Wait for visible text, future output, or cooperative completion with explicit evidence #673’s distinction between current text and future output. Neither helper depends on merging this issue first.

A changed first row can indicate changed history, clear-history or other changes. An unchanged row cannot prove continuity; repeated rows defeat that heuristic. A diagnostic may conservatively refuse or report unknown, but must not advertise lossless absolute indexing from history_size + cursor_y.

Historical context: the original investigation at tmux 134ba6c reported approximately 3,000 high-frequency samples without observing an intermediate history-size dip during collect-and-scroll. That measurement is retained as historical evidence, not rerun or treated as a current all-version statement. The original proposed upstream feature request is retired from this work. NEVER write to tmux/tmux: no issues, comments, edits or other tracker mutations; use pinned source links and local capability evidence only.

Canonical scope: #740 (cursor/reset/gap behavior), #673 (wait baselines), #456 (environment qualification), and #629 in the Python project. PR #808 covers only the reproducer/documentation slice; keep remaining diagnostic criteria open. Each implementation slice must build from current master with siblings absent and preserve existing facade and engine contracts. No macOS work or core-minimum change belongs to this train.

Activity

  1. moved this to Todo in libtmuxon Oct 31, 2026
  2. tony commented on Nov 1, 2026

    @tony
    MemberAuthor

    PR #808 supplies the reproducible ambiguity case and capture-continuity documentation. It is independent of the cursor and engine branches and does not change the tmux minimum.

    The owned fixture retains five history rows in a 20×5 pane. After 64 more identical producer rows, both captures still contain nine same rows, both history sizes remain five, and both cursors remain at column zero, row four. A producer signal establishes the phase boundary; the test uses no polling sleeps or reruns. Changing the second burst to different text deliberately makes the equality assertion fail. The final fixture passes on tmux 3.2a and local 3.8a.

    Current tmux source exposes history_collected, so the original statement that no collection counter exists needs version qualification. The format is absent at the supported 3.2a floor. In the fresh 3.8a probe it increased from 56 to 121 while the other observations remained equal; input echo contributes to that difference. It is evidence of collection, not an exact command-output offset or recovery of lost text. Missing evidence must not be treated as zero.

    The reproducer and documented limit preserve this negative result. Ruff, full-tree mypy, and the project docs build pass; the full local suite retains the same unrelated hooks/popup/floating failures observed on unchanged master. Hosted checks pass at the corrected PR head, including all eight tmux build lanes and CodeQL.

    Keep #671 open for justified diagnostic classification and the consumers in #740/#673. No upstream tracker write is proposed or authorized. No macOS qualification work is added.

  3. moved this from Todo to In Progress in libtmuxon Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    • Status
      In Progress

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions