Add native Clojure facade

.github/CONTRIBUTING.md

@@ -30,11 +30,11 @@ answerable for how the whole library is tested.
 
 ## Building
 
-You need JDK 25 or newer and tmux on `PATH`. Nothing else — Gradle provisions
-the toolchain, and the library has no runtime dependencies. The workspace CLI
-adds its own runtime dependencies; its terminal regression tests also require
-Python 3 for the standard-library PTY driver and Bash on `PATH` for interactive
-completion tests. On macOS, install Bash with Homebrew; the system Bash lacks
+You need JDK 25 or newer and tmux on `PATH`. Gradle provisions the toolchain,
+and the library has no runtime dependencies. Native terminal test fixtures need
+Python 3 for its standard-library PTY driver. The workspace CLI adds its own
+runtime dependencies; its interactive completion tests also need Bash on
+`PATH`. On macOS, install Bash with Homebrew; the system Bash lacks
 the completion test's Readline hooks.
 
 `./gradlew` is the only supported entry point. A locally installed `gradle` is
@@ -232,7 +232,7 @@ toolchain and `options.release` in
 version matrix in the CI workflow, which builds on 25 and 27, and the claim
 `README.md` makes under `Requirements`.
 
-**tmux 3.2a through 3.7c is the supported range**, and it is not a claim: the
+**tmux 3.3a through 3.7c is the supported range**, and it is not a claim: the
 whole real-tmux suite runs against every one of those releases, and each lane
 checks it really ran the tmux it is named after. Moving the range means moving
 `workflows/tmux-matrix.yml` and the README together.

.github/WRITING.md

@@ -28,7 +28,7 @@ Four things near the top are compatibility claims, and they move together:
   exported identifiers without a deprecation period, pin an exact version, not
   recommended for production. `CHANGELOG.md` and the `Status` section say the
   same thing in the same words.
-- **The requirements are JDK 25 or newer, and tmux 3.2a through 3.7c.** The tmux
+- **The requirements are JDK 25 or newer, and tmux 3.3a through 3.7c.** The tmux
   range is not a claim — the matrix runs every lane of it — so it may not drift
   from `workflows/tmux-matrix.yml`.
 - **Coordinates are group `io.github.libtmux`, imported through
@@ -120,7 +120,7 @@ Order it capability, then consequence, then compatibility:
 
 > 0.0.1-alpha.7 adds streaming capture, and rejects `windowId` at pane scope
 > rather than ignoring it. Pass `scope: window` to read at window scope. JDK 25
-> and tmux 3.2a through 3.7c are unchanged.
+> and tmux 3.3a through 3.7c are unchanged.
 
 The title is plain — the version, optionally preceded by `libtmux for Java`.
 Never "we are excited to announce"; state what shipped.
@@ -321,7 +321,7 @@ Bad (Delete):
 Good (Keep):
 
 ```java
-// tmux < 3.2 reports the pane ID only after the command completes,
+// Some releases report the pane ID only after the command completes,
 // so this query must stay separate.
 ```
 

.github/workflows/ci.yml

@@ -79,6 +79,17 @@ jobs:
         run: |
           python3 -m venv "$RUNNER_TEMP/workspace-python"
           "$RUNNER_TEMP/workspace-python/bin/python" -m pip install 'tmuxp==1.74.0'
+          # Source-overlay qualification: released tmuxp still pins libtmux~=0.61.
+          # Reviewed PR780 supplies optional policy; these are not a released pair.
+          git init --quiet "$RUNNER_TEMP/python-libtmux-core"
+          git -C "$RUNNER_TEMP/python-libtmux-core" fetch --quiet --depth=1 \
+            https://github.com/tmux-python/libtmux.git 54b277bb673e208820fc9c795abe4444e2ded272
+          git -C "$RUNNER_TEMP/python-libtmux-core" checkout --quiet --detach \
+            54b277bb673e208820fc9c795abe4444e2ded272
+          PYTHONPATH="$RUNNER_TEMP/python-libtmux-core/src" "$RUNNER_TEMP/workspace-python/bin/python" -c \
+            'import sys, libtmux; from pathlib import Path; from libtmux.common import TMUX_MIN_VERSION, TMUX_OPTIONAL_FEATURE_POLICY_VERSION as policy; assert type(policy) is int and policy >= 2, policy; assert TMUX_MIN_VERSION == "3.3a", TMUX_MIN_VERSION; assert Path(libtmux.__file__).resolve() == Path(sys.argv[1]).resolve() / "libtmux" / "__init__.py", libtmux.__file__; print(TMUX_MIN_VERSION, policy, libtmux.__file__)' \
+            "$RUNNER_TEMP/python-libtmux-core/src"
+          echo "PYTHONPATH=$RUNNER_TEMP/python-libtmux-core/src" >> "$GITHUB_ENV"
           echo "TMUX_WORKSPACE_TEST_PYTHON=$RUNNER_TEMP/workspace-python/bin/python" >> "$GITHUB_ENV"
 
       # Runs every check task instead of stopping at the first failure, so one run names them all.

.github/workflows/clojure-compatibility.yml

@@ -0,0 +1,246 @@
+name: Clojure compatibility
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Clojure checks (JDK ${{ matrix.java }}, Clojure ${{ matrix.clojure }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        java: ['25', '27']
+        clojure: ['1.12.4', '1.12.6']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Install tmux
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends -y tmux
+          tmux -V
+
+      - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6
+        with:
+          distribution: temurin
+          # Gradle runs on 25 in every lane (last entry is JAVA_HOME); the lane's JDK runs the Clojure.
+          java-version: |
+            ${{ matrix.java }}
+            25
+
+      - uses: gradle/actions/setup-gradle@3f5f9adaf7d9fecd50b5935e54106014257a94e6 # v6.4.0
+        with:
+          validate-wrappers: true
+
+      - name: Run Clojure checks and publish local artifacts
+        run: >-
+          ./gradlew check clojureDependencyMetadata platformCoversEveryPublishedModule
+          publishToMavenLocal --rerun-tasks --stacktrace
+          -PlibtmuxJavaVersion=${{ matrix.java }}
+          -PlibtmuxClojureVersion=${{ matrix.clojure }}
+
+      - name: No tmux server outlived the suite
+        if: always()
+        run: |
+          left="$(pgrep -c tmux || true)"
+          if [ "${left:-0}" -ne 0 ]; then
+            echo "::error::$left tmux server(s) survived the suite"
+            for p in $(pgrep tmux); do tr '\0' ' ' < "/proc/$p/cmdline"; echo; done
+            exit 1
+          fi
+          echo "no tmux server survived the suite"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: failure()
+        with:
+          name: reports-clojure-jdk${{ matrix.java }}-${{ matrix.clojure }}
+          path: '**/build/reports/**'
+          retention-days: 7
+
+  tmux:
+    name: Clojure tmux ${{ matrix.tmux }} (JDK ${{ matrix.java }}, Clojure ${{ matrix.clojure }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        java: ['25', '27']
+        clojure: ['1.12.4', '1.12.6']
+        tmux: ['3.3a', '3.4', '3.5', '3.6', '3.7', '3.7a', '3.7b', '3.7c']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Build tmux dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends -y \
+            build-essential libevent-dev libncurses-dev bison pkg-config
+
+      - name: Restore tmux ${{ matrix.tmux }}
+        id: tmux-cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ~/tmux-builds/${{ matrix.tmux }}
+          key: tmux-${{ matrix.tmux }}-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Build tmux ${{ matrix.tmux }}
+        if: steps.tmux-cache.outputs.cache-hit != 'true'
+        env:
+          LANE: ${{ matrix.tmux }}
+        run: |
+          set -eux
+          work="$(mktemp -d)"
+          curl -fsSL -o "$work/tmux.tar.gz" \
+            "https://github.com/tmux/tmux/releases/download/$LANE/tmux-$LANE.tar.gz"
+          tar -xzf "$work/tmux.tar.gz" -C "$work"
+          cd "$work/tmux-$LANE"
+          ./configure --prefix="$HOME/tmux-builds/$LANE"
+          make -j"$(nproc)"
+          make install
+
+      - name: The lane runs the tmux it is named after
+        env:
+          LANE: ${{ matrix.tmux }}
+        run: |
+          "$HOME/tmux-builds/$LANE/bin/tmux" -V
+
+      - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6
+        with:
+          distribution: temurin
+          # Gradle runs on 25 in every lane (last entry is JAVA_HOME); the lane's JDK runs the Clojure.
+          java-version: |
+            ${{ matrix.java }}
+            25
+
+      - uses: gradle/actions/setup-gradle@3f5f9adaf7d9fecd50b5935e54106014257a94e6 # v6.4.0
+        with:
+          validate-wrappers: true
+
+      - name: Run the native Clojure real-tmux suite
+        env:
+          LANE: ${{ matrix.tmux }}
+        run: |
+          ./gradlew :integration-tests:clojureIntegrationTest --rerun-tasks --stacktrace \
+            -PlibtmuxJavaVersion=${{ matrix.java }} \
+            -PlibtmuxClojureVersion=${{ matrix.clojure }} \
+            "-PlibtmuxTmuxBinary=$HOME/tmux-builds/$LANE/bin/tmux" \
+            "-PlibtmuxTmuxExpected=$LANE"
+
+      - name: No tmux server outlived the suite
+        if: always()
+        run: |
+          left="$(pgrep -c tmux || true)"
+          if [ "${left:-0}" -ne 0 ]; then
+            echo "::error::$left tmux server(s) survived the suite"
+            for p in $(pgrep tmux); do tr '\0' ' ' < "/proc/$p/cmdline"; echo; done
+            exit 1
+          fi
+          echo "no tmux server survived the suite"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: failure()
+        with:
+          name: reports-clojure-tmux-${{ matrix.tmux }}-jdk${{ matrix.java }}-${{ matrix.clojure }}
+          path: '**/build/reports/**'
+          retention-days: 7
+
+  macos:
+    name: Clojure macOS tmux ${{ matrix.tmux }} (JDK ${{ matrix.java }}, Clojure ${{ matrix.clojure }})
+    runs-on: macos-latest
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        java: ['25', '27']
+        clojure: ['1.12.4', '1.12.6']
+        tmux: ['3.3a', '3.7c']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Build tmux dependencies
+        run: brew install libevent ncurses bison pkg-config
+
+      - name: Restore tmux ${{ matrix.tmux }}
+        id: tmux-cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ~/tmux-builds/${{ matrix.tmux }}
+          key: tmux-${{ matrix.tmux }}-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Build tmux ${{ matrix.tmux }}
+        if: steps.tmux-cache.outputs.cache-hit != 'true'
+        env:
+          LANE: ${{ matrix.tmux }}
+        run: |
+          set -eux
+          work="$(mktemp -d)"
+          curl -fsSL -o "$work/tmux.tar.gz" \
+            "https://github.com/tmux/tmux/releases/download/$LANE/tmux-$LANE.tar.gz"
+          tar -xzf "$work/tmux.tar.gz" -C "$work"
+          cd "$work/tmux-$LANE"
+          libevent_prefix="$(brew --prefix libevent)"
+          ncurses_prefix="$(brew --prefix ncurses)"
+          export PKG_CONFIG_PATH="$libevent_prefix/lib/pkgconfig:$ncurses_prefix/lib/pkgconfig"
+          export CPPFLAGS="-I$ncurses_prefix/include"
+          export LDFLAGS="-L$ncurses_prefix/lib"
+          ./configure --prefix="$HOME/tmux-builds/$LANE" --disable-utf8proc
+          make -j"$(sysctl -n hw.logicalcpu)"
+          make install
+
+      - name: The lane runs the tmux it is named after
+        env:
+          LANE: ${{ matrix.tmux }}
+        run: |
+          "$HOME/tmux-builds/$LANE/bin/tmux" -V
+
+      - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6
+        with:
+          distribution: temurin
+          # Gradle runs on 25 in every lane (last entry is JAVA_HOME); the lane's JDK runs the Clojure.
+          java-version: |
+            ${{ matrix.java }}
+            25
+
+      - uses: gradle/actions/setup-gradle@3f5f9adaf7d9fecd50b5935e54106014257a94e6 # v6.4.0
+        with:
+          validate-wrappers: true
+
+      - name: Run the native Clojure smoke and lifecycle suite
+        env:
+          LANE: ${{ matrix.tmux }}
+        run: |
+          ./gradlew :integration-tests:clojureIntegrationTest --rerun-tasks --stacktrace \
+            -PlibtmuxJavaVersion=${{ matrix.java }} \
+            -PlibtmuxClojureVersion=${{ matrix.clojure }} \
+            "-PlibtmuxTmuxBinary=$HOME/tmux-builds/$LANE/bin/tmux" \
+            "-PlibtmuxTmuxExpected=$LANE"
+
+      - name: No tmux server outlived the suite
+        if: always()
+        run: |
+          left="$(pgrep -c tmux || true)"
+          if [ "${left:-0}" -ne 0 ]; then
+            echo "::error::$left tmux server(s) survived the suite"
+            for p in $(pgrep tmux); do ps -o command= -p "$p"; done
+            exit 1
+          fi
+          echo "no tmux server survived the suite"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: failure()
+        with:
+          name: reports-clojure-macos-${{ matrix.tmux }}-jdk${{ matrix.java }}-${{ matrix.clojure }}
+          path: '**/build/reports/**'
+          retention-days: 7

.github/workflows/release.yml

@@ -137,6 +137,8 @@ jobs:
             libtmux-jackson/build/libs/*.jar
             libtmux-junit5/build/libs/*.jar
             libtmux-kotlin/build/libs/*.jar
+            libtmux-clojure/build/libs/*.jar
+            libtmux-clojure-core-async/build/libs/*.jar
             libtmux-mcp/build/libs/*.jar
             libtmux-workspace/build/libs/*.jar
             libtmux-workspace-cli/build/libs/*.jar

.github/workflows/tmux-matrix.yml

@@ -1,6 +1,6 @@
 name: tmux matrix
 
-# The README claims tmux 3.2a through 3.7c, and says that range is not a claim because the suite runs
+# The README claims tmux 3.3a through 3.7c, and says that range is not a claim because the suite runs
 # against every one of them. This is where that stops depending on someone running it locally.
 
 on:
@@ -27,7 +27,7 @@ jobs:
   lanes:
     # Preview lanes carry their own label: this is the only place a reader sees which entries the
     # supported range does not include, since the README and the matrix property list only the rest.
-    name: tmux ${{ matrix.tmux }}${{ matrix.experimental && ' (preview, not supported)' || '' }}
+    name: tmux ${{ matrix.tmux }}${{ matrix.experimental && ' (preview, not supported)' || '' }}${{ matrix.rejection && ' (must be refused)' || '' }}
     runs-on: ubuntu-latest
     timeout-minutes: ${{ matrix.tmux == 'master' && 25 || 15 }}
     continue-on-error: ${{ matrix.experimental == true }}
@@ -38,11 +38,19 @@ jobs:
         # (its `lanes` list), which is the source of truth. The agree step below fails if they drift
         # apart. This is also what DocumentationFactsTest reads the README's claimed range from, so a
         # preview lane belongs in `include` below and never here.
-        tmux: ['3.2a', '3.3', '3.3a', '3.4', '3.5', '3.6', '3.7', '3.7a', '3.7b', '3.7c']
+        tmux: ['3.3a', '3.4', '3.5', '3.6', '3.7', '3.7a', '3.7b', '3.7c']
         # Ahead of the supported range, matching the plugin's `previewLanes` list: 3.8-rc2 is a
         # candidate for a release not yet cut, and master is upstream's development branch, not a
         # version. Both may fail and neither moves the README's claimed range.
         include:
+          # Below the floor, matching the plugin's `rejectionLanes`: the real binary must refuse
+          # every call and leave a sentinel session, option and buffer untouched.
+          - tmux: '3.2a'
+            rejection: true
+          - tmux: '3.3'
+            rejection: true
+          - tmux: '3.8'
+            experimental: true
           - tmux: '3.8-rc2'
             experimental: true
           - tmux: master
@@ -132,6 +140,17 @@ jobs:
         run: |
           python3 -m venv "$RUNNER_TEMP/workspace-python"
           "$RUNNER_TEMP/workspace-python/bin/python" -m pip install 'tmuxp==1.74.0'
+          # Source-overlay qualification: released tmuxp still pins libtmux~=0.61.
+          # Reviewed PR780 supplies optional policy; these are not a released pair.
+          git init --quiet "$RUNNER_TEMP/python-libtmux-core"
+          git -C "$RUNNER_TEMP/python-libtmux-core" fetch --quiet --depth=1 \
+            https://github.com/tmux-python/libtmux.git 54b277bb673e208820fc9c795abe4444e2ded272
+          git -C "$RUNNER_TEMP/python-libtmux-core" checkout --quiet --detach \
+            54b277bb673e208820fc9c795abe4444e2ded272
+          PYTHONPATH="$RUNNER_TEMP/python-libtmux-core/src" "$RUNNER_TEMP/workspace-python/bin/python" -c \
+            'import sys, libtmux; from pathlib import Path; from libtmux.common import TMUX_MIN_VERSION, TMUX_OPTIONAL_FEATURE_POLICY_VERSION as policy; assert type(policy) is int and policy >= 2, policy; assert TMUX_MIN_VERSION == "3.3a", TMUX_MIN_VERSION; assert Path(libtmux.__file__).resolve() == Path(sys.argv[1]).resolve() / "libtmux" / "__init__.py", libtmux.__file__; print(TMUX_MIN_VERSION, policy, libtmux.__file__)' \
+            "$RUNNER_TEMP/python-libtmux-core/src"
+          echo "PYTHONPATH=$RUNNER_TEMP/python-libtmux-core/src" >> "$GITHUB_ENV"
           echo "TMUX_WORKSPACE_TEST_PYTHON=$RUNNER_TEMP/workspace-python/bin/python" >> "$GITHUB_ENV"
 
       # One lane rather than testTmuxMatrix: each version builds and runs on its own runner, so the