Repository navigation
Open
Description
Summary
An independent review of this port's script-cleanup commits on master (2a09108 through 952b8d2, the work for #170, #142, #173 and #174) scored all 13 dimensions below 9.5/10 and two below the 8.5 gate: DX 8 and AI use 8. It also failed one policy check: a Python program embedded in a Java test that no ruff or ty step reaches, and sh tmux stand-ins in two script tests with no recorded exception. This issue tracks the diff-level findings only; whole-project scores are in #176. Close it when a fresh review of these changes scores every applicable dimension 9.5 or higher.
Motivation
Evidence at 952b8d2707b7b6d32576dc9892f9807cb954d349:
- Embedded Python (policy, idioms):
NativeClient.javaholds a Python program in a text block (import fcntl, pty, signal, sys, termios) that it runs aspython3 -u -c. Thescripts (ruff, ty, pytest)job checksscriptsandlibtmux-workspace-cli/src/test/resourcesonly, so this program is never formatted, linted or type checked.952b8d2moved the twelveProcessTestprograms out for that reason and left this one. shtmux stand-ins (policy, tmux fidelity):test_reap_stale_servers.pywrites a#!/bin/shfile namedtmux, andtest_build_tmux_matrix.pybuilds a source archive whosemake installwrites a#!/bin/shtmux. SCRIPTS.md records neither as an exception, and the READMEs give the reason ("start no real server") without a measurement.- No documented script check command (DX): the "Checks that must pass" section of
.github/CONTRIBUTING.mdnames only./gradlew :libtmux-mcp:test check, which does not run the script checks. Theruff format --check,ruff check,ty checkandpytestcommands appear only inci.yml, andscripts/has no index README. - AI path (AI use):
AGENTS.mdlinks SCRIPTS.md, which gives thescripts/<name>/layout and the four tools but no command and no link to the script READMEs. - Unbounded subprocesses (async correctness):
kill_serverrunstmux kill-serverwith notimeout=against servers the script exists to clean up when they may be wedged.build_tmux_matrix.pyruns./configure,makeandurlretrievewith none. The stand-in test loops ontime.monotonic()with no sleep for up to 5 seconds (line 163). - Unverified build (tmux fidelity):
build_tmux_matrix.pydownloads a release archive and builds it without a checksum. The sharedbuild-tmuxaction inlibtmux/.githubpins a SHA256 per release in itstmux-releases.json, and shipsbuild_tmux.pywith a--prefixoption. - Reader detail (readability, idioms):
reap_stale_servers.pyreads the socket with-S ([^ ]*), which mis-reads a path containing a space.PrivateDaemon.daemonCommandinserts-Dat index 2 of the endpoint command, which depends on its layout.ci.ymlruns the four script checks in one step, so a failure does not name the tool. - Writing: against WRITING.md, 26 of the 31 subjects exceed 50 characters, 20 omit the colon, and six commit bodies have no blank line before
what:. - Open and already tracked: the
tmuxp==1.74.0install andtmux-python/libtmuxfetch inci.ymlandtmux-matrix.ymlwait on Decide whether the workspace CLIs keep their tmuxp and Python libtmux bridge docs#324 under Clean up support scripts under SCRIPTS.md #170, as does the macOS tmux build inclojure-compatibility.yml.
Proposal
- Move the
NativeClientprogram next topty_helper.py(or into a test resource), load it asProcessTestloads its probes, and add it to the ruff and ty paths. - Replace the two
shstand-ins with a Python stand-in or a real server under the port's test root, or record the exception in SCRIPTS.md with its measurement. - Add the four
uv run --lockedcommands to "Checks that must pass" and ascripts/README.mdindex; link both from SCRIPTS.md "Layout and checks". - Add
timeout=tokill_server, the download and the build steps, and replace the busy loop with a short sleep. - Call the shared action's
build_tmux.py, or verify each archive against its pinned SHA256. - Split the script job into one step per tool.
References
- Clean up support scripts under SCRIPTS.md #170, Raise each review dimension to 9.5/10 #176
- libtmux/docs#323, the script policy decision
- libtmux/docs#324, the bridge decision behind the
tmuxpstep
Metadata
Metadata
Assignees
Labels
No labels
Activity
tests(refactor[native-client]) Run the ordinary client's Python from …
docs(scripts[checks]) Document the script check commands and index th…
fix(scripts[reap-stale-servers]) Bound kill-server and read the socke…
fix(scripts[build-tmux-matrix]) Verify each archive's SHA256 and boun…
docs(scripts[exceptions]) Record why the tmuxp installs stay and drop…
tony commentedon Nov 16, 2026
Fixes are on
masterthrough1de5891d. CI at that head is green: CI, tmux matrix, Clojure compatibility, docs, CodeQL. The tmux matrix needed one rerun oftmux 3.8, jdk 25:ControlObservationSuite > scope close ends a parked stream and server loss fails it with the client's causefailed once atControlObservationSuite.scala:322and passed on attempt 2. That Scala suite does not touchNativeClient; I will file an issue if it fails again.Blocking items:
3003487amoves theNativeClientprogram tointegration-tests/src/test/resources/io/github/libtmux/it/ordinary_client.py, adds that directory to the ruff and ty paths, and tests the driver on a real pty. Running the clients' integration tests (70 tests across six classes) against the change found that the imported helper leaves a__pycache__that broke cleanup in eight tests; the commit setsPYTHONDONTWRITEBYTECODE.shstand-ins:f9ce12dc(reaper) and207ee79d(matrix builder) write them in Python. The commit messages carry thehyperfine -N --warmup 3measurement (545 us for sh, 13.8 ms for Python 3), so no SCRIPTS.md exception is needed.d71be019adds "Checking the scripts" to CONTRIBUTING.md andscripts/README.md.d71be019links both from SCRIPTS.md "Layout and checks" and from AGENTS.md.Other items:
kill_server(f9ce12dc); the download,./configureandmake(207ee79d). The busy loop is gone;Popenreturns after exec, so the lookup needs no retry.build-tmuxaction pins, read at the committmux-matrix.ymlpins (207ee79d). It does not call the action, which readsRUNNER_TEMPand writesGITHUB_OUTPUT.SOCKETregex: the reaper reads the NUL-separatedcmdline, so a path with a space works (f9ce12dc).3003487a).tmuxp==1.74.0installs and drops the unsourced size claim (1de5891d).Remains:
tmuxp==1.74.0installs wait on Decide whether the workspace CLIs keep their tmuxp and Python libtmux bridge docs#324, tracked in Clean up support scripts under SCRIPTS.md #170.why:/what:format findings are in pushed commits, which cannot change.PrivateDaemon.daemonCommandstill inserts-Dat index 2; that is library code and outside this round.run:blocks inci.yml("Install the optional workspace Python test runtime", "No tmux server outlived the suite") stay; the review passed them.chore(scripts[ci-steps]) Add the scripts the multi-command workflow s…
ci(workflows[steps]) Make every run step call one command
fix(scripts[ci-steps]) Mark the new scripts executable
tony commentedon Nov 16, 2026
Follow-up for the multi-command
run:blocks, added to this round's scope. The commits are onmasterthrough681f10a0. A count of the lines that start a command in each block gave 16 of 39 before and 0 of 50 after; actionlint is clean andscripts/ci-checkpasses.32ab76b0adds the scripts the steps that held logic move into:no-tmux-survivors(four copies of the survivors check, on Linux and macOS),check-tmux-build(the lane runs the tmux it is named after, and its client),release-checks(release-version,staged-version,ci-passedthroughgh, andcarry-passphrase, which now writes the passphrase with a delimiter so one with a newline cannot add a variable), and--only RELEASEwith Homebrew's libraries on macOS forbuild-tmux-matrix, so the macOS lanes call it in place of an inline build. The sharedbuild-tmuxaction runs on Linux, which is why they do not use it.6a2b3b35splits every plain sequence into a step per command and moves the workspace Python runtime, repeated inci.ymlandtmux-matrix.yml, into one composite action,.github/actions/workspace-python.681f10a0sets the executable bit on the three new scripts: the scripts job failed ruff on EXE001 at6a2b3b35. Local ruff did not report it, and I did not find out why; the commit message's explanation of the cause is a guess.CI at
681f10a0: CI, tmux matrix, Clojure compatibility, docs and CodeQL are green. A push runs only the edge lanes, so I dispatched tmux matrix at scope full: the four lanes that must be refused, with the client check, and the master preview lane passed.tmux 3.7, jdk 25failed atControlObservationSuite.scala:322, the same test that failed once in the earlier run; filed as #179.The macOS lanes of
clojure-compatibility.ymlran at this head and passed, but their tmux caches hit, so the new build step was skipped and has not run on macOS. Its tests use a fakebrew. The first cache miss exercises it.tony commentedon Nov 16, 2026
Re-score of the script-cleanup changes at trunk
681f10a0by a fresh reviewer: every dimension is at 8.5 or higher, nine of thirteen are below 9.5, and two policy checks fail, so this issue stays open. The nine findings of the first review are resolved. CI at the head passed forCI,tmux matrix(push),Clojure compatibilityanddocs; aworkflow_dispatchrun of the matrix at the same head failed intmux 3.7, jdk 25atControlObservationSuite.scala:322, which #179 tracks.count-run.pyprints0/50multi-commandrun:blocks, down from16 of 39.Dimensions still below 9.5:
examples/apiprograms start their own server withServer.start. The seven programs ofexamples/src/main/{java,kotlin}/.../examples/(BuildAWorkspace,FindPanesRunning,RunACommand,ServeTmuxOverMcp,WatchPaneOutput,WatchWhatChanges,WatchWithFlow.kt) still take/tmp/libtmux-java-dev/demo/sand need a server something else started (#171, open).cf4b0b31("identical plans ... for 12 event and dispatch inputs"),636aed46,e9384111("byte-identical ... on seven broken ones") and1119b623carry no command or old-script SHA.build_tmux_matrix.py:49-50keeps "took 8.5 s to configure and 6.3 s to make here" in a comment.check_tmux_build.pysays the build-tmux action "can restore a cached build"; the action's README says a cached build "is validated before it is used".ci_check.pyreads workflows with regexes (_run_bodies,_jobs,_steps,_where) where a YAML loader would do; every script keepsfrom __future__ import annotationsat a 3.12 floor.tools/mcp-swaptests embed Python programs (see the policy check).PrivateDaemon.java:177waits for readiness withThread.sleep(10)in a loop.subprocesscalls inscripts/carry notimeout=:pgrepandpsinno_tmux_survivors.py,tmux -Vincheck_tmux_build.pyandbuild_tmux_matrix.py,brew,release_checks.py:84,verify_staged_release.py:81.ci_check.pyis 429 lines of regex scanning; the test probes'mainruns up to 98 lines (switch_clients.py).check_tmux_buildrationale above.Failed policy checks:
SCRIPTS.mdsays "A Python program a test runs is a checked file ... not a string in a test", and four programs still sit in Java text blocks:tools/mcp-swap/.../McpPreflightTest.java:47andSwapServiceTest.java:97(not tied to the bridge), andExecutionTest.java:291and:483(workspace bridge, waiting on docs#324).no_tmux_survivors.py:10,README.md:6), and a measurement in a comment atbuild_tmux_matrix.py:49-50.Remaining work:
Server.startand create the session each watches (Java and Kotlin examples on libtmux.org need an outside tmux server #171).cf4b0b31,636aed46,e9384111and1119b623in the Clean up support scripts under SCRIPTS.md #170 closing comment; delete the timing sentence frombuild_tmux_matrix.py.mcp-swaptest programs totools/mcp-swap/src/test/resources/and add the directory to the ruff and ty paths.versionoutput in the workflow, or say whatcheck_tmux_build.pyadds to the action's cache validation.timeout=on the seven unboundedsubprocesscalls.ci_check.pywith PyYAML through a PEP 723 dependency.PrivateDaemonwith aWatchService, or record why polling is the portable choice; cut the two flourishes.mcp-swap(test[python]) Run the two embedded Python programs from chec…
scripts(feat[lib]) Add bounded: a time limit that stops the command's…
scripts(fix[no-tmux-survivors]) Bound pgrep and ps and drop the flourish
scripts(fix[check-tmux-build]) Bound tmux -V and say what the check adds
scripts(fix[release-checks]) Bound gh run list and report a failure t…
scripts(fix[verify-staged-release]) Bound gpg --verify
scripts(fix[reap-stale-servers]) Send kill-server through bounded
scripts(fix[build-tmux-matrix]) Kill a build step's group and bound t…
scripts(test[lib]) Fail when a script starts a process without bounded
scripts(refactor[annotations]) Drop from __future__ import annotation…
workspace-cli(test[python]) Run the bridge test programs from checked…
mcp-swap(style[format]) Apply spotless to McpPreflightTest