Skip to content

tmux(fix[3.8]): Support hooks and terminal fixtures - #825

Merged
tony merged 4 commits into
masterfrom
fix/775-tmux38-compat
Nov 8, 2026
Merged

tony merged 4 commits into
masterfrom
fix/775-tmux38-compat

Conversation

@tony

@tony tony commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Fix typed reads of hooks added in tmux 3.8.
  • Run popup tests through an owned terminal client.
  • Correct floating-pane geometry examples and assertions.
  • Test stable tmux 3.8 and isolate build caches by runner image.

Issue #775 still reproduces on current master. For example, session.set_hook("pane-created[7]", "display-message created") succeeds natively, but session.show_hook("pane-created[7]") raises TypeError because the typed hook table lacks that field. The read now preserves the indexed string value. The core tmux minimum remains 3.2a.

Compatibility findings

Failing behavior Cause and correction
test_hooks_dataclass and new hook round trips Add fields from the tmux 3.8 hook table.
test_hook_set_show_unset_cycle[after_queue] Assert native rejection of the removed hook on 3.8; retain the older-version round trip.
Popup command markers never appear tmux 3.8 returns early for control clients. Attach a private PTY client, wait for its attachment hook, and retain the command-result assertions.
Floating-pane dimensions and position tmux 3.8 sizes the outer border, while pane formats report content cells. Update the assertions and public examples; keep wrapper arguments intact.

The Debian report's failure causes reproduce with a stable 3.8 client and daemon. Local qualification uses Python 3.15 on Linux/WSL, rather than Debian's exact Python and package builds. Changing TERM does not repair the baseline failures.

New hosted runs also exposed an environmental failure before pytest: the tmux 3.4 and 3.7a caches were built on Ubuntu 24.04 and restored on Ubuntu 26.04, where tmux -V fails to load NCURSES6_TINFO_6.4.current. The cache key now includes the actual runner image, image version and architecture. Missing image metadata fails before cache restoration. Existing caches are left intact.

This is a focused extraction of the relevant compatibility repairs from #758. Its engine changes and the minimum-version changes in #779/#780 remain separate.

Test plan

  • New hook reads fail before the correction and preserve sparse values afterward.
  • Deliberately omitting a hook field, discarding a popup command, or changing floating width fails the corresponding regression.
  • Focused native coverage passes on tmux 3.2a, 3.3a, 3.4, 3.5, 3.6, 3.7a, 3.7b and stable 3.8; the installed development 3.8a build is recorded separately.
  • Full configured pytest, including source, documentation and README doctests, passes on stable 3.8 with reruns disabled and all baseline cases retained.
  • Ruff format/lint, mypy and just build-docs pass; changed rendered documentation is checked.
  • Executed cache-key controls distinguish both observed images, architecture and tmux version, and reject missing image metadata.
  • Hosted checks pass at 025f41b40c8fec05f93bb55cbf66bbb86b7241ac: all eight stable tmux lanes (3.2a through 3.8), both CodeQL analyses and the aggregate, and the codecov/project status. Maintainer review remains pending.

The nonblocking development-tmux run reports a successful job but its pytest log has three failures: test_stable_baseline_options_and_hooks, test_display_popup_flags[no_keys_v36], and test_capture_pane_flags[join_wrapped_numbers]. The cached next-3.9 binary rejects popup -N; the capture fixture can accept an echoed, unexecuted completion marker. These failures remain separate from stable-3.8 qualification and are not passes. Unfiltered actionlint also retains the two existing shell-quoting warnings; workflow syntax validation passes. Neither result is reported as a passing test.

Addresses #775. No release, issue closure or merge is part of this handoff.

@codecov

codecov Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.17%. Comparing base (bfad66b) to head (8867f3f).

Files with missing lines Patch % Lines
src/libtmux/_internal/constants.py 0.00% 22 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #825      +/-   ##
==========================================
- Coverage   52.50%   52.17%   -0.34%     
==========================================
  Files          26       26              
  Lines        3729     3751      +22     
  Branches      747      747              
==========================================
- Hits         1958     1957       -1     
- Misses       1468     1490      +22     
- Partials      303      304       +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 added a commit that referenced this pull request Nov 7, 2026
why: Cached tmux executables must remain usable when GitHub changes
the runner image or its native libraries. Version-only cache keys can
restore a binary linked against an incompatible ncurses build and fail
at tmux -V before the Python tests begin. This occurred when the tmux
3.4 job restored an installation requiring NCURSES6_TINFO_6.4.current.

what:
- Identify native installations by the runner image and image version,
  architecture, compiler and dependency versions, selected source, and
  build recipe. Changes to any of these invalidate the cache key.
- Validate every restored installation against its recorded identity,
  executable checksum, reported tmux version, and ability to start a
  private daemon. Check the connected daemon's version as well as the
  client version. A private-daemon cleanup failure fails the step.
- Rebuild rejected installations in fresh source and build directories.
  Cache only the installed prefix, keeping source trees and intermediate
  objects out of restored entries. Preserve unrelated servers and files
  during validation, recovery, and cleanup.
- Keep official stable-release archive checksums in
  .github/tmux-releases.toml, including tmux 3.8. Verify each download
  before extraction and include the selected checksum in cache identity.
  Maintainers can update release pins without editing the build script.
- Resolve development tmux once to a commit, fetch that exact commit,
  and verify the checkout before building. Follow tmux's separate
  release-archive and source-checkout build procedures.
- Install build and runtime dependencies before cache validation on both
  hits and misses. Compile with up to four available processors and save
  validated installations before library tests run, allowing subsequent
  jobs to reuse a successful build even when a library test fails.
- Use separate cache restore and save steps, read-only repository
  permissions for build jobs, and a bounded job runtime. Keep the
  existing compatibility matrix and library checks in place.
- Exercise cache rejection, fresh rebuilds, valid-hit reuse, symlink
  safety, failed-build metadata, and environment-sensitive keys through
  regressions that use real tmux startup and isolated server cleanup.
- Document the native build and cache lifecycle for contributors, and
  summarize CI recovery and TOML release pins in the changelog.

GitHub cache entries are immutable. Rebuilding an invalid exact hit
repairs the current job but cannot replace that stored entry. The
workflow reports this condition; changing the build recipe invalidates
the key for subsequent jobs. Broad restore-key fallbacks are excluded
because they can reintroduce incompatible native installations.

The CI helper scripts require Python 3.11 for the standard-library TOML
reader. Library type checks retain the Python 3.10 floor, and the core
tmux minimum remains 3.2a. The release catalogue includes tmux 3.8 while
the separate library compatibility correction remains in PR #825.

Regression qualification covers cold builds, validated warm reuse,
recovery from a real shared-library loader failure, and rejection of an
incorrect archive checksum. Deliberate breaks verify that executable
validation, daemon startup checks, and environment-sensitive cache keys
are necessary for the tests to pass.

The development-tmux library job retains its existing continue-on-error
policy. Its successful job conclusion can therefore include failing
library tests. Library test-readiness defects and documentation-workflow
lint warnings remain separate from this native-cache repair.

Native build reference:
https://github.com/tmux/tmux/blob/3.8/README
@tony
tony force-pushed the fix/775-tmux38-compat branch from 025f41b to 4b37134 Compare November 7, 2026 02:42
tony added a commit to tmux-python/libtmux-mcp that referenced this pull request Nov 7, 2026
why: libtmux pins tmux 3.8, the latest stable release, in
`.github/tmux-releases.toml` (tmux-python/libtmux#835), and this repo's
port of the cache recovery left it out. With the pin in place a 3.8
build fetches a checksum-verified archive as soon as the matrix lists
it. The matrix is unchanged, as in libtmux, where tmux 3.8
compatibility is still open (tmux-python/libtmux#825).

what:
- .github/tmux-releases.toml: tmux 3.8 at sha256 e79c699c...d82e, the
  digest GitHub records for tmux-3.8.tar.gz
- .github/CONTRIBUTING.md: name tmux 3.8 among the pins, as libtmux's
  guide does
tony added a commit to tmux-python/tmuxp that referenced this pull request Nov 7, 2026
why: libtmux pins tmux 3.8, the latest stable release, in
`.github/tmux-releases.toml` (tmux-python/libtmux#835), and this repo's
port of the cache recovery left it out. With the pin in place a 3.8
build fetches a checksum-verified archive as soon as the matrix lists
it. The matrix is unchanged, as in libtmux, where tmux 3.8
compatibility is still open (tmux-python/libtmux#825).

what:
- .github/tmux-releases.toml: tmux 3.8 at sha256 e79c699c...d82e, the
  digest GitHub records for tmux-3.8.tar.gz
- .github/CONTRIBUTING.md: name tmux 3.8 among the pins and link the
  3.8 build instructions, as libtmux's guide does
tony added a commit to tmux-python/libtmux-mcp that referenced this pull request Nov 7, 2026
why: tmux 3.8 is the latest stable release and nothing tested libtmux-mcp against it (#146). Its release archive was already pinned in `.github/tmux-releases.toml`, and the 3.8 job passes on the current libtmux release, so the matrix entry does not wait on tmux-python/libtmux#825.

what:
- Add `'3.8'` to `matrix.tmux-version` in the tests workflow.
tony added a commit to tmux-python/tmuxp that referenced this pull request Nov 7, 2026
tmux 3.8 is the latest stable release, and nothing tested tmuxp against it (#1100). Its release archive was already pinned in `.github/tmux-releases.toml`, and the new job passes on the current libtmux release, so the matrix entry does not wait on tmux-python/libtmux#825.

- **Matrix**: `'3.8'` joins `matrix.tmux-version` in the tests workflow, built from the checksum-pinned archive.

See also: tmux-python/libtmux#775, tmux-python/libtmux#825
@tony
tony force-pushed the fix/775-tmux38-compat branch from 4b37134 to 1cc35fd Compare November 8, 2026 00:21
tony added 4 commits November 7, 2026 18:48
why: tmux 3.8 adds hook names and changes popup and floating-pane
semantics that existing decoding, fixtures, and examples assume.

what:
- Decode all 22 added hooks and retain indexed values
- Assert removal of after-queue while preserving older behavior
- Attach an owned terminal client for popup execution tests
- Document and check bordered floating-pane geometry

Adapted from the focused hook, geometry, and popup corrections in
PR #758, without its separate minimum-version or engine changes.
why: Version-only tmux cache keys restore Ubuntu 24.04 binaries on
Ubuntu 26.04, where their ncurses symbols are unavailable.

what:
- Include the hosted runner image and architecture in native cache keys
- Add stable tmux 3.8 to the existing compatibility matrix
- Retain all existing stable lanes and the tmux 3.2a minimum
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 fix/775-tmux38-compat branch from 1cc35fd to 8867f3f Compare November 8, 2026 00:48
@tony
tony merged commit 58f00aa into master Nov 8, 2026
16 checks passed
@tony
tony deleted the fix/775-tmux38-compat branch November 8, 2026 00:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant