Skip to content

Require coordinated optional tmux operation guards - #1093

Draft
tony wants to merge 8 commits into
bump-min-tmux-000from
bump-min-tmux-001
Draft

tony wants to merge 8 commits into
bump-min-tmux-000from
bump-min-tmux-001

Conversation

@tony

@tony tony commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

Require libtmux's command policy (libtmux._internal.support.require_commands) before custom builder/plugin imports or shell code. A libtmux without it is refused. The package requires libtmux~=0.63.0 (see #1092); until that release exists the lock pins libtmux's feature head (5df9cb3e), whose version and control-identity probes are hook-free. Install a checkout with uv sync --locked.

Merge and release order: libtmux 0.63.0 is released first, from #779 and #780. This PR, stacked on #1092, requires libtmux~=0.63.0, which no installer can satisfy until then, so it merges only after that release, in the same change that drops the development [tool.uv.sources] pin. Nothing in this PR tags or releases.

Optional operations retain their individual requirements: stable tmux 3.7+ with a compatible client for control, 3.4+ for exact named-buffer operations, and 3.5+ for captured foreground shell output. Exact tmux 3.7 pane breaks require a window name. Malformed literal layouts refuse before dispatch on 3.3a, preserving running sessions; valid layouts, ordinary workspace operations, and portable percentage splits remain available.

Validation:

  • Version check, optional-operation and workspace-layout cases pass locally after the move to libtmux._internal.support (29 passed, 12 skipped); earlier revisions of this branch passed 48 cases each on 3.3a, 3.4, 3.5, exact 3.7 and 3.7d. Installed-pair checks use the immutable dependency without PYTHONPATH.
  • Dropping require_commands from the backend gate fails the three refusal cases (builder import, plugin import, shell code). The 3.3a layout test expects LibTmuxException on every release, because libtmux now raises InvalidLayout instead of a bare ValueError, so the release-dependent expectation is gone.
  • Formatting, lint, mypy, the documented docs build and wheel/sdist builds pass. Docs retain the same 16 warnings. Replay verifies every final file against the independently reviewed source.

The earlier full suites (949 passed, 2 skipped on both 3.3a and 3.7d) belong to a prior candidate and remain separate corpus evidence. The core base (44da4788, run) has all eight hosted CI cells green; this restacked head (dc819005) is not claimed green.

Depends on the tmux 3.3a version check change.

Closes #1091.

@codecov

codecov Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.48%. Comparing base (44da478) to head (dc81900).

Additional details and impacted files
@@                  Coverage Diff                  @@
##           bump-min-tmux-000    #1093      +/-   ##
=====================================================
+ Coverage              82.44%   82.48%   +0.03%     
=====================================================
  Files                     31       31              
  Lines                   2826     2826              
  Branches                 525      525              
=====================================================
+ Hits                    2330     2331       +1     
+ Misses                   357      356       -1     
  Partials                 139      139              

☔ 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 force-pushed the bump-min-tmux-001 branch from f5c805a to c01963c Compare October 17, 2026 08:49
tony added 8 commits October 17, 2026 07:37
why: Use the coordinated parent revision with layout refusal and
     per-operation compatibility.

what:
- Pin the immutable policy-2 libtmux source in project and lock.
- Keep the matching 0.62 package metadata.
why: A package version can still lack required operation guards.

what:
- Require integer policy 2 before workspace imports or shell code.
- Exercise refusal, supported operations and native layout behavior.
why: Ordinary workspace support and optional operation requirements
     need separate installation and behavior guidance.

what:
- Describe operation floors and narrow layout refusal.
- Explain coordinated source installation and native client needs.
why: Existing custom code needs the individual tmux requirements.

what:
- Document optional operation guards and policy-2 installation.
- Keep ordinary tmux 3.3a operations available.
why: The next release changes optional-operation version checks.

what:
- Record operation requirements and layout refusal behavior.
The backend gate compared TMUX_OPTIONAL_FEATURE_POLICY_VERSION, which libtmux
no longer exposes. Require libtmux._internal.support.require_commands instead; a
libtmux without it is refused before builders, plugins or shell code run, and
the layout test now expects LibTmuxException on every release, because libtmux
raises InvalidLayout (a LibTmuxException) from the 3.3a guard instead of a bare
ValueError.

Tests: a libtmux without require_commands is refused for builders, plugins and
shell code with no effect. Dropping the name from the gate fails all three.
The feature-policy and version check modules (30 cases) pass on 3.7d and 3.3a.
Replace the policy-version sentence with the require_commands requirement.
Keep the migration note separate from runtime changes.
Replace the policy-version sentence with the require_commands requirement.
Keep the release note separate from runtime changes.
@tony
tony force-pushed the bump-min-tmux-001 branch from c01963c to f3f2518 Compare October 17, 2026 12:39
@tony
tony force-pushed the bump-min-tmux-000 branch from 6d89492 to bfab78b Compare October 17, 2026 12:40
@tony
tony force-pushed the bump-min-tmux-001 branch from f3f2518 to 357b145 Compare October 17, 2026 12:40
@tony
tony force-pushed the bump-min-tmux-000 branch from bfab78b to 44da478 Compare October 17, 2026 17:56
@tony
tony force-pushed the bump-min-tmux-001 branch from 357b145 to dc81900 Compare October 17, 2026 17:59

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

None yet

Development

Successfully merging this pull request may close these issues.

1 participant