Skip to content

Raise the script-cleanup changes to 9.5/10 #178

Open

Description

@tony

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.java holds a Python program in a text block (import fcntl, pty, signal, sys, termios) that it runs as python3 -u -c. The scripts (ruff, ty, pytest) job checks scripts and libtmux-workspace-cli/src/test/resources only, so this program is never formatted, linted or type checked. 952b8d2 moved the twelve ProcessTest programs out for that reason and left this one.
  • sh tmux stand-ins (policy, tmux fidelity): test_reap_stale_servers.py writes a #!/bin/sh file named tmux, and test_build_tmux_matrix.py builds a source archive whose make install writes a #!/bin/sh tmux. 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.md names only ./gradlew :libtmux-mcp:test check, which does not run the script checks. The ruff format --check, ruff check, ty check and pytest commands appear only in ci.yml, and scripts/ has no index README.
  • AI path (AI use): AGENTS.md links SCRIPTS.md, which gives the scripts/<name>/ layout and the four tools but no command and no link to the script READMEs.
  • Unbounded subprocesses (async correctness): kill_server runs tmux kill-server with no timeout= against servers the script exists to clean up when they may be wedged. build_tmux_matrix.py runs ./configure, make and urlretrieve with none. The stand-in test loops on time.monotonic() with no sleep for up to 5 seconds (line 163).
  • Unverified build (tmux fidelity): build_tmux_matrix.py downloads a release archive and builds it without a checksum. The shared build-tmux action in libtmux/.github pins a SHA256 per release in its tmux-releases.json, and ships build_tmux.py with a --prefix option.
  • Reader detail (readability, idioms): reap_stale_servers.py reads the socket with -S ([^ ]*), which mis-reads a path containing a space. PrivateDaemon.daemonCommand inserts -D at index 2 of the endpoint command, which depends on its layout. ci.yml runs 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.0 install and tmux-python/libtmux fetch in ci.yml and tmux-matrix.yml wait 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 in clojure-compatibility.yml.

Proposal

  • Move the NativeClient program next to pty_helper.py (or into a test resource), load it as ProcessTest loads its probes, and add it to the ruff and ty paths.
  • Replace the two sh stand-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 --locked commands to "Checks that must pass" and a scripts/README.md index; link both from SCRIPTS.md "Layout and checks".
  • Add timeout= to kill_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

Activity

  1. tony commented on Nov 16, 2026

    @tony
    ContributorAuthor

    Fixes are on master through 1de5891d. CI at that head is green: CI, tmux matrix, Clojure compatibility, docs, CodeQL. The tmux matrix needed one rerun of tmux 3.8, jdk 25: ControlObservationSuite > scope close ends a parked stream and server loss fails it with the client's cause failed once at ControlObservationSuite.scala:322 and passed on attempt 2. That Scala suite does not touch NativeClient; I will file an issue if it fails again.

    Blocking items:

    • Embedded Python: 3003487a moves the NativeClient program to integration-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 sets PYTHONDONTWRITEBYTECODE.
    • sh stand-ins: f9ce12dc (reaper) and 207ee79d (matrix builder) write them in Python. The commit messages carry the hyperfine -N --warmup 3 measurement (545 us for sh, 13.8 ms for Python 3), so no SCRIPTS.md exception is needed.
    • Script check commands: d71be019 adds "Checking the scripts" to CONTRIBUTING.md and scripts/README.md.
    • AI path: d71be019 links both from SCRIPTS.md "Layout and checks" and from AGENTS.md.

    Other items:

    • Timeouts: kill_server (f9ce12dc); the download, ./configure and make (207ee79d). The busy loop is gone; Popen returns after exec, so the lookup needs no retry.
    • The matrix builder verifies each archive against the SHA256 the shared build-tmux action pins, read at the commit tmux-matrix.yml pins (207ee79d). It does not call the action, which reads RUNNER_TEMP and writes GITHUB_OUTPUT.
    • SOCKET regex: the reaper reads the NUL-separated cmdline, so a path with a space works (f9ce12dc).
    • The scripts job is one step per tool (3003487a).
    • SCRIPTS.md records the tmuxp==1.74.0 installs and drops the unsourced size claim (1de5891d).

    Remains:

  2. tony commented on Nov 16, 2026

    @tony
    ContributorAuthor

    Follow-up for the multi-command run: blocks, added to this round's scope. The commits are on master through 681f10a0. 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 and scripts/ci-check passes.

    • 32ab76b0 adds 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-passed through gh, and carry-passphrase, which now writes the passphrase with a delimiter so one with a newline cannot add a variable), and --only RELEASE with Homebrew's libraries on macOS for build-tmux-matrix, so the macOS lanes call it in place of an inline build. The shared build-tmux action runs on Linux, which is why they do not use it.
    • 6a2b3b35 splits every plain sequence into a step per command and moves the workspace Python runtime, repeated in ci.yml and tmux-matrix.yml, into one composite action, .github/actions/workspace-python.
    • 681f10a0 sets the executable bit on the three new scripts: the scripts job failed ruff on EXE001 at 6a2b3b35. 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 25 failed at ControlObservationSuite.scala:322, the same test that failed once in the earlier run; filed as #179.

    The macOS lanes of clojure-compatibility.yml ran 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 fake brew. The first cache miss exercises it.

  3. tony commented on Nov 16, 2026

    @tony
    ContributorAuthor

    Re-score of the script-cleanup changes at trunk 681f10a0 by 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 for CI, tmux matrix (push), Clojure compatibility and docs; a workflow_dispatch run of the matrix at the same head failed in tmux 3.7, jdk 25 at ControlObservationSuite.scala:322, which #179 tracks. count-run.py prints 0/50 multi-command run: blocks, down from 16 of 39.

    Dimensions still below 9.5:

    Dimension Score Why
    Examples 8.5 The examples/api programs start their own server with Server.start. The seven programs of examples/src/main/{java,kotlin}/.../examples/ (BuildAWorkspace, FindPanesRunning, RunACommand, ServeTmuxOverMcp, WatchPaneOutput, WatchWhatChanges, WatchWithFlow.kt) still take /tmp/libtmux-java-dev/demo/s and need a server something else started (#171, open).
    Data sourcing 8.5 The equivalence claims in cf4b0b31 ("identical plans ... for 12 event and dispatch inputs"), 636aed46, e9384111 ("byte-identical ... on seven broken ones") and 1119b623 carry no command or old-script SHA. build_tmux_matrix.py:49-50 keeps "took 8.5 s to configure and 6.3 s to make here" in a comment.
    tmux fidelity 9.0 check_tmux_build.py says the build-tmux action "can restore a cached build"; the action's README says a cached build "is validated before it is used".
    Language idioms 9.0 ci_check.py reads workflows with regexes (_run_bodies, _jobs, _steps, _where) where a YAML loader would do; every script keeps from __future__ import annotations at a 3.12 floor.
    MCP 9.0 Two tools/mcp-swap tests embed Python programs (see the policy check).
    Async, control, streaming 9.0 PrivateDaemon.java:177 waits for readiness with Thread.sleep(10) in a loop.
    Async correctness 9.0 Seven of nine subprocess calls in scripts/ carry no timeout=: pgrep and ps in no_tmux_survivors.py, tmux -V in check_tmux_build.py and build_tmux_matrix.py, brew, release_checks.py:84, verify_staged_release.py:81.
    Readability 9.0 ci_check.py is 429 lines of regex scanning; the test probes' main runs up to 98 lines (switch_clients.py).
    Freshness 9.0 The check_tmux_build rationale above.

    Failed policy checks:

    • Right language: SCRIPTS.md says "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:47 and SwapServiceTest.java:97 (not tied to the bridge), and ExecutionTest.java:291 and :483 (workspace bridge, waiting on docs#324).
    • No slop: "this is the one place the question gets asked for free" (no_tmux_survivors.py:10, README.md:6), and a measurement in a comment at build_tmux_matrix.py:49-50.

    Remaining work:

    • Start the seven top-level example programs with Server.start and create the session each watches (Java and Kotlin examples on libtmux.org need an outside tmux server #171).
    • Post the old-script SHA and the comparison loop for cf4b0b31, 636aed46, e9384111 and 1119b623 in the Clean up support scripts under SCRIPTS.md #170 closing comment; delete the timing sentence from build_tmux_matrix.py.
    • Move the two mcp-swap test programs to tools/mcp-swap/src/test/resources/ and add the directory to the ruff and ty paths.
    • Compare the action's version output in the workflow, or say what check_tmux_build.py adds to the action's cache validation.
    • Pass timeout= on the seven unbounded subprocess calls.
    • Load the workflows in ci_check.py with PyYAML through a PEP 723 dependency.
    • Wait on the socket's creation in PrivateDaemon with a WatchService, or record why polling is the portable choice; cut the two flourishes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions