libtmux 0.1.0.alpha.1 → 0.1.0.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c19838a471ee26a9953d27f31bbaece230b6b8d2422d58dd5c57d0512a186f8
-  data.tar.gz: ce84cd707102bcd05b9a32d7dfdd7d59791fa8a802aa4eb81068bc36f81caae6
+  metadata.gz: 8c42fbd138b8dcb5637f8a47ee771a288f318c9a34dfb83a8836ca9be6cec7a9
+  data.tar.gz: a3801bfd5c494129d0bee1872f756c03c2ec148262d245075336e9f54869ab95
 SHA512:
-  metadata.gz: 99d71b78ddff682bbafbcb3cd24a60989cb8e5ea052bd34e83902276ccdf044b13ade3d8916fd7342e5627ebc752d8f4a7a30e85d22e703455ca423b5a5dcfbb
-  data.tar.gz: 835a4ff8a6185b3db991705836e229a5cf574b90ed8805d0110a21028878cbb9141368d4c52a88da2c9441342c7e1791bf300012f262b88dd73bc0c53103fcc0
+  metadata.gz: c8b889852d311651fdc65cff4a76776b7d3ab6dda81947d722ea4f268754361380e58095e99cc545c93c7a7d69b7ffc7ca4b76c09ab12ab4f620c32123f69b26
+  data.tar.gz: 98f5b864675439967d3377a465423b5719e8be045eb96e8ab53c06047e5d6c2bf3f7a6db54c6a87ab8382cfe8b272ddac1e16df444ee209144bd24579cad9406

data/README.md

@@ -1,3 +1,14 @@
+<!-- libtmux-logo -->
+<div align="center">
+  <picture>
+    <source srcset="assets/logo.svg" type="image/svg+xml">
+    <img src="assets/logo.png" width="128" height="128" alt="libtmux for Ruby">
+  </picture>
+</div>
+<!-- /libtmux-logo -->
+
+<div align="center">
+
 # libtmux
 
 Ruby tmux orchestration core. `Server.open` borrows an
@@ -8,6 +19,12 @@ Owned startup uses Linux and Darwin readiness backends. The
 [compatibility workflow](https://github.com/libtmux/libtmux-ruby/actions/workflows/compatibility.yml)
 retains exact per-revision platform and version results.
 
+</div>
+
+Requires tmux 3.3a or newer; unpatched 3.3 is below the minimum. A server
+handle checks the connected daemon's release before any command is
+dispatched, and refuses an older daemon even when its client is newer.
+
 Install the alpha with `gem install libtmux --pre`, then require `libtmux`.
 Imports do not
 start tmux, a scheduler or an MCP server. See the repository's contribution
@@ -96,8 +113,8 @@ and retains `previous_generation`. Every new subscription begins with a
 subscriptions stay closed, and requests are never replayed. Event sequences
 describe one connection's observations, not durable pane history.
 
-Typed command coverage includes hierarchy creation/listing,
-rename/split/resize/swap/join/break/respawn/layout operations, link operations,
+Typed command coverage includes hierarchy creation/listing; rename, split,
+resize, swap, join, break, respawn, and layout operations; link operations;
 options/hooks/environment, capture/send/paste/pipe/buffers, copy commands,
 display/source-file/wait-for. It does not establish complete flag parity or
 every compatibility cell; consult the workflow results. RBS validation checks declarations;

data/assets/logo.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 135.46667 135.46666" role="img" aria-label="libtmux for Ruby" class="libtmux-logo" data-language="ruby" data-variant="library" focusable="false"><title>libtmux for Ruby</title><g transform="translate(-210.28959,-409.98108)" data-part="artwork"><g transform="matrix(1.024,0,0,1.0240011,-5.0469507,-9.8399997)" data-part="primary-tile"><path d="M 227.78906,0 213.98242,3.6992188 V 460.62109 H 241.4082 V 15.564453 Z" transform="matrix(0.26458333,0,0,0.26458333,210.28959,409.98108)" fill="#2D0002" data-part="primary-edge"></path><path d="m 210.28981,417.13553 v 113.86425 l 60.26885,2.60089 V 409.98109 h -53.11441 c -3.95129,0 -7.15444,3.20315 -7.15444,7.15444 z" fill="#701516" data-part="primary"></path></g><g transform="matrix(1.024,0,0,1.0240011,-5.0469507,-9.8399997)" data-part="lower-tile"><path d="m 486.38086,246.03906 -5.24805,4.99805 v 207.2207 l 5.24805,-0.93164 L 500,465.18945 V 261.60352 Z" transform="matrix(0.26458333,0,0,0.26458333,210.28959,409.98108)" fill="#67221F" data-part="lower-edge"></path><path d="m 278.70874,475.07917 v 64.8875 l 60.26883,-8.98455 v -55.90295 z" fill="#984640" data-part="lower"></path></g><path d="m 210.28959,533.88585 v 4.23589 c 9e-5,4.04619 3.2803,7.32617 7.32649,7.32598 h 28.63105 l 81.26967,-1.0223 14.5495,-10.53906 v 0 z" fill="#231F20" data-part="base"></path><g transform="matrix(1.024,0,0,1.0240011,-5.0469507,-9.8399997)" data-part="upper-tile"><path d="m 459.33984,0 -25.33593,2.1074219 h 21.38281 c 14.93397,0 27.04101,12.1070061 27.04101,27.0410161 V 129.83008 l 6.17579,13.24609 L 500,112.43359 V 42.603516 C 499.99913,8.8176763 474.27408,-6.8031496e-4 459.33984,0 Z" transform="matrix(0.26458333,0,0,0.26458333,210.28959,409.98108)" fill="#854A46" data-part="upper-side"></path><path d="m 331.82331,409.98109 h -53.11442 v 56.93261 h 60.26885 v -49.77817 c 0,-3.95129 -3.20315,-7.15444 -7.15443,-7.15444 z" fill="#B6706A" data-part="upper"></path><path d="m 278.7089,466.9137 h 60.26885 l 3.6035,4.11782 h -60.26932 z" fill="#733A36" data-part="upper-bottom"></path></g><g transform="matrix(1.024,0,0,1.0240011,-5.0469507,-9.8399997)" data-part="gear-group"><path d="m 298.35661,419.37889 c -3.307,0 -6.01087,2.63649 -6.0946,5.94228 l -0.33026,13.04677 c -0.0503,1.98883 -1.3048,3.74588 -3.16843,4.44175 -1.63527,0.6105 -3.23561,1.29298 -4.79768,2.04293 -1.82786,0.87796 -4.00547,0.54134 -5.47527,-0.85609 l -9.17457,-8.72115 c -2.39692,-2.27863 -6.17361,-2.23122 -8.512,0.10759 l -14.3945,14.39447 c -1.27625,1.27604 -1.86544,2.98029 -1.77147,4.65491 -0.0118,0.22021 -0.0123,0.44029 0,0.66053 -0.0118,0.22023 -0.0123,0.44029 0,0.66053 -0.0118,0.22021 -0.0123,0.44029 0,0.66053 -0.0118,0.22024 -0.0123,0.44029 0,0.66053 -0.0118,0.22024 -0.0123,0.44029 0,0.66053 -0.0118,0.22024 -0.0123,0.44029 0,0.66053 -0.0118,0.22024 -0.0123,0.44029 0,0.66053 -0.0838,1.61437 0.46467,3.25669 1.6634,4.51768 l 8.99461,9.46208 c 0.23074,0.24278 0.42181,0.51038 0.59418,0.78721 -0.60023,1.35769 -1.15279,2.74067 -1.64984,4.15071 -0.6727,1.90958 -2.45019,3.20822 -4.47443,3.25942 l -12.65165,0.31971 c -3.30618,0.0837 -5.94279,2.7886 -5.94279,6.0956 v 0.66053 0.66053 0.66053 0.66056 2.64112 15.07361 0.66053 0.66053 0.66053 0.66053 0.66053 0.66053 0.66053 0.66053 c 0,3.30703 2.63661,6.01136 5.94279,6.09511 l 13.04677,0.32975 c 1.98885,0.0503 3.74539,1.30529 4.44124,3.16895 0.53531,1.43379 1.12957,2.83886 1.7725,4.21655 -0.17026,0.27145 -0.35881,0.53398 -0.58564,0.77264 l -8.72163,9.17405 c -1.19922,1.26148 -1.74723,2.90475 -1.66291,4.51969 -0.0124,0.22024 -0.0118,0.44029 0,0.66053 v 0.0457 h 0.0875 l 10.03868,-9.51839 29.63949,8.95286 h 43.47603 l 13.935,-16.69426 v -0.0216 c -8.04912,9.72841 -20.24315,15.90068 -33.88319,15.7844 -22.83086,-0.19494 -41.62302,-18.24181 -43.0251,-40.7806 1.34121,-22.94291 20.4588,-41.11551 43.78415,-40.91631 13.2902,0.11325 25.20451,6.28323 33.12414,15.86034 v -3.90741 -20.27843 -11.02398 l -3.97024,3.7742 c -1.44419,1.37264 -3.57681,1.72648 -5.38882,0.89729 -1.57465,-0.72024 -3.18724,-1.3729 -4.83384,-1.95295 -1.90955,-0.67268 -3.2077,-2.45012 -3.25892,-4.47392 l -0.32023,-12.65265 c -0.0836,-3.30579 -2.78757,-5.94228 -6.09457,-5.94228 z" fill="#999999" data-part="gear-edge"></path><path d="m 298.35715,419.3789 c -3.30703,0 -6.01139,2.63697 -6.09511,5.94277 l -0.33075,13.04677 c -0.0504,1.98885 -1.30431,3.74539 -3.16795,4.44126 -1.63521,0.6105 -3.23553,1.29298 -4.79716,2.04293 -1.8283,0.87755 -4.0065,0.54134 -5.47627,-0.85609 l -9.17408,-8.72115 c -2.39692,-2.27863 -6.17372,-2.23122 -8.51252,0.10759 l -14.39447,14.39498 c -2.33842,2.33839 -2.38624,6.1146 -0.10759,8.51152 l 8.9951,9.46211 c 1.37305,1.44416 1.72558,3.57678 0.89681,5.38881 -0.72068,1.57466 -1.37293,3.18676 -1.95295,4.83335 -0.67271,1.90958 -2.45022,3.20823 -4.47444,3.25942 l -12.65164,0.32023 c -3.30621,0.0837 -5.9428,2.78759 -5.9428,6.09459 v 20.35786 c 0,3.30703 2.63659,6.01087 5.9428,6.09459 l 13.04677,0.33027 c 1.98843,0.0504 3.74578,1.30479 4.44123,3.16846 0.61094,1.63521 1.29301,3.2356 2.04295,4.79765 0.87797,1.82789 0.54145,4.00591 -0.85559,5.47527 l -8.72164,9.17457 c -1.37514,1.44653 -1.88755,3.39384 -1.57592,5.22595 h 0.7465 24.32055 61.26465 3.60327 c 3.95126,0 7.15424,-3.20297 7.15424,-7.15427 v -2.056 -8.04952 c -8.05257,9.71866 -20.25002,15.87899 -33.88271,15.76278 -23.61284,-0.2016 -42.90943,-19.4986 -43.11104,-43.11106 -0.20729,-24.31847 19.55063,-44.07731 43.86912,-43.8696 13.28515,0.11319 25.2041,6.27146 33.12463,15.84172 v -18.88347 -11.02398 l -3.97073,3.77469 c -1.44417,1.37264 -3.57578,1.72599 -5.38782,0.8968 -1.57506,-0.72024 -3.18776,-1.37292 -4.83435,-1.95295 -1.90958,-0.67309 -3.20729,-2.45063 -3.25892,-4.47441 l -0.32023,-12.65167 c -0.0833,-3.3058 -2.78767,-5.94277 -6.09509,-5.94277 z" fill="#E6E6E6" data-part="gear"></path></g></g></svg>

data/lib/libtmux/capture.rb

@@ -2,6 +2,7 @@
 
 require_relative "snapshot"
 require_relative "metadata"
+require_relative "tmux_version"
 
 module LibTmux
   module Internal
@@ -53,19 +54,16 @@ module LibTmux
         end
         version, pid, start_time = rows.first
         version = version.dup.force_encoding(Encoding::UTF_8)
-        match = /\A(?:next-)?([0-9]+)\.([0-9]+)([a-z]?)(?:-[A-Za-z0-9.-]+)?\z/.match(version) if version.valid_encoding?
-        unless match
-          raise UnsupportedFeatureError.new("unrecognized tmux version for capture", delivery: :observed, phase: :capture)
-        end
-        supported = ([match[1].to_i, match[2].to_i, match[3]] <=> [3, 2, "a"]) >= 0
-        unless supported
-          raise UnsupportedFeatureError.new("captured metadata requires tmux 3.2a or newer", delivery: :observed, phase: :capture)
+        begin
+          TmuxVersion.require_supported(version)
+        rescue UnsupportedFeatureError => error
+          raise UnsupportedFeatureError.new(error.message, delivery: :observed, phase: :capture)
         end
         unless pid.match?(/\A[1-9][0-9]{0,9}\z/n) && start_time.match?(/\A-?[0-9]{1,19}\z/n)
           raise ProtocolError.new("invalid capture server identity metadata", delivery: :observed, phase: :capture)
         end
         {version: version, pid: Integer(pid, 10), start_time: Integer(start_time, 10),
-         capabilities: {metadata: :byte_counted, field_baseline: "3.2a"}}
+         capabilities: {metadata: :byte_counted, field_baseline: TmuxVersion::MINIMUM}}
       end
 
       def acquire_rows(budget, attempt, clients)

data/lib/libtmux/catalog.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "tmux_version"
+
 module LibTmux
   module Internal
     # Names and bounds are explicit: wire spelling is not Ruby case conversion.
@@ -23,7 +25,7 @@ module LibTmux
         Field.new(id: id, name: name, wire_name: wire_name, format: format, type: type,
           nullable: nullable, empty_is_null: empty_is_null, min: min, max: max,
           operators: operators || {text: TEXT, integer: INTEGER, boolean: EQUALITY}.fetch(type),
-          min_version: "3.2a", scope: scope, capture_requirements: [scope].freeze)
+          min_version: Internal::TmuxVersion::MINIMUM, scope: scope, capture_requirements: [scope].freeze)
       end
       private_class_method :field
 
@@ -40,7 +42,7 @@ module LibTmux
       end
       private_class_method :schema
 
-      # 3.2a is the supported capture baseline, not a claim about first introduction.
+      # The minimum supported tmux is the capture baseline, not a claim about first introduction.
       SCHEMAS = {
         session: schema(:session, "session", [
           field(:session, "session.id", :id, "id", "session_id", :text, operators: EQUALITY),
@@ -70,7 +72,7 @@ module LibTmux
           field(:pane, "pane.id", :id, "id", "pane_id", :text, operators: EQUALITY),
           field(:pane, "pane.window_id", :window_id, "windowId", "window_id", :text, operators: EQUALITY),
           field(:pane, "pane.index", :index, "index", "pane_index", :integer, min: 0, max: UINT_MAX),
-          field(:pane, "pane.pid", :pid, "pid", "pane_pid", :integer, min: 0, max: INT_MAX),
+          field(:pane, "pane.pid", :pid, "pid", "pane_pid", :integer, nullable: true, empty_is_null: true, min: 0, max: INT_MAX),
           field(:pane, "pane.current_command", :current_command, "currentCommand", "pane_current_command", :text),
           field(:pane, "pane.current_path", :current_path, "currentPath", "pane_current_path", :text, nullable: true, empty_is_null: true),
           field(:pane, "pane.title", :title, "title", "pane_title", :text),

data/lib/libtmux/entity.rb

@@ -135,16 +135,16 @@ module LibTmux
       value = layout.is_a?(Symbol) ? layout.to_s.tr("_", "-") : layout
       budget = server.__send__(:operation_budget, timeout, cancel)
       # Older tmux can access an invalid pointer for a malformed layout header.
-      unless LAYOUTS.include?(value) || /\A[0-9a-fA-F]{4},/.match?(value)
+      # tmux 3.8-rc2 and later report and accept saved layouts as JSON.
+      saved = /\A[0-9a-fA-F]{4},/.match?(value) ||
+        (value.start_with?("{") && server.__send__(:tmux_release) >= Internal::TmuxVersion.parse("3.8-rc2"))
+      unless LAYOUTS.include?(value) || saved
         choices = (LAYOUTS + MIRRORED_LAYOUTS).select { |name| name.start_with?(value) }
         raise ArgumentError, "layout must be a native name or a saved layout" if value.empty? || choices.empty?
 
         if choices.any? { |name| MIRRORED_LAYOUTS.include?(name) }
-          version = server.display('#{version}', **budget.options).text
-          release = /\A(\d+)\.(\d+)/.match(version)
-          raise ProtocolError.new("tmux version is invalid", phase: :decode, delivery: :observed) unless release
-
-          if ([release[1].to_i, release[2].to_i] <=> [3, 5]).negative?
+          release = server.__send__(:tmux_release)
+          if release < Internal::TmuxVersion.parse("3.5")
             choices &= LAYOUTS
             if choices.empty?
               raise UnsupportedFeatureError.new("mirrored layouts require tmux 3.5+", phase: :admission)

data/lib/libtmux/metadata.rb

@@ -16,7 +16,7 @@ module LibTmux
       def unquote(value)
         escapes = {"a" => "\a", "b" => "\b", "t" => "\t", "n" => "\n", "v" => "\v",
           "f" => "\f", "r" => "\r", "s" => " ", "E" => "\e"}
-        value.b.gsub(/\\([0-7]{3}|.)/n) do
+        value.b.gsub(/\\([0-7]{3}|.)/nm) do
           escaped = Regexp.last_match(1)
           if escaped.match?(/\A[0-7]{3}\z/)
             byte = escaped.to_i(8)

data/lib/libtmux/owned.rb

@@ -49,6 +49,9 @@ module LibTmux
               if @endpoint.socket_path.bytesize > 103
                 raise UnsupportedFeatureError.new("owned Unix socket path exceeds the platform limit", phase: :startup)
               end
+              Internal::TmuxVersion.executable(@endpoint.executable) do |argv|
+                ProcessExecutor.new.run(argv, timeout: deadline - clock, cancel: cancel)
+              end
               @readiness = SocketReadiness.new(@directory)
               @child = OwnedChild.new
               pid = nil

data/lib/libtmux/process.rb

@@ -104,14 +104,17 @@ module LibTmux
         @drain_timeout = drain_timeout
       end
 
-      def run(argv, input: "".b, env: {}, timeout: 5.0, cancel: nil)
-        Execution.new(argv, input, env, timeout, cancel, @limits, @cleanup_timeout, @drain_timeout).call
+      # +discard_stdout+ gives the child the null device for stdout, so the
+      # result reports no stdout and the call does not wait for a descriptor
+      # that a daemon older than tmux 3.2 keeps open after its client exits.
+      def run(argv, input: "".b, env: {}, timeout: 5.0, cancel: nil, discard_stdout: false)
+        Execution.new(argv, input, env, timeout, cancel, @limits, @cleanup_timeout, @drain_timeout, discard_stdout).call
       end
 
       class Execution
         CHUNK_BYTES = 16_384
 
-        def initialize(argv, input, env, timeout, cancel, limits, cleanup_timeout, drain_timeout)
+        def initialize(argv, input, env, timeout, cancel, limits, cleanup_timeout, drain_timeout, discard_stdout)
           @started = monotonic
           unless argv.is_a?(Array) && !argv.empty? && argv.all? { |argument| argument.is_a?(String) && !argument.include?("\0") }
             raise ArgumentError, "argv must contain strings without NUL"
@@ -130,6 +133,7 @@ module LibTmux
           @limits = limits
           @cleanup_timeout = cleanup_timeout
           @drain_timeout = drain_timeout
+          @discard_stdout = discard_stdout
           @process_wait = ProcessWait.new
           @owned = []
           @buffers = {stdout: +"".b, stderr: +"".b}
@@ -180,7 +184,12 @@ module LibTmux
 
         def spawn
           child_input, @input_writer = pipe
-          @output_reader, child_output = pipe
+          if @discard_stdout
+            child_output = File.open(File::NULL, "wb")
+            @owned << child_output
+          else
+            @output_reader, child_output = pipe
+          end
           @error_reader, child_error = pipe
           @child = OwnedChild.new(@process_wait)
           @exit_reader = @child.reader
@@ -198,7 +207,8 @@ module LibTmux
         end
 
         def communicate
-          reading = {@output_reader => :stdout, @error_reader => :stderr}
+          reading = {@error_reader => :stderr}
+          reading[@output_reader] = :stdout if @output_reader
           loop do
             return result if @status && reading.empty?
 

data/lib/libtmux/server.rb

@@ -4,9 +4,101 @@ require_relative "endpoint"
 require_relative "process"
 require_relative "metadata"
 require_relative "entity"
+require_relative "tmux_version"
 
 module LibTmux
   # Connects to an existing endpoint. Closing retires clients, never the daemon.
+  #
+  # A server is bound to one tmux executable and one Unix socket. It keeps a
+  # private link to the socket it bound, so commands never reach a different
+  # daemon that later takes over the same path. An {EntityRef} is valid only on
+  # the server that issued it; another server raises {TargetNotFoundError}.
+  #
+  # Methods that run a tmux command take `timeout:` and `cancel:`. The typed
+  # methods raise {CommandError} when tmux rejects a command, and a listing
+  # that fails raises, so an empty array means tmux answered with nothing to
+  # list. {#run} and {#run_group} answer their result whatever tmux's exit
+  # status. `max_requests:` bounds concurrent commands and `max_controls:`
+  # bounds control connections; a call past either limit raises
+  # {CapacityError} instead of waiting. After {#close} the server refuses new
+  # requests with {ClosedError}, and {#diagnostics} still answers. A forked
+  # child can close an inherited server but cannot use it.
+  #
+  # # What is on here
+  #
+  # The methods fall into the groups below. A {Session}, {Window}, or {Pane}
+  # carries the operations on that one thing.
+  #
+  # **Connecting.** {#initialize Server.new} and {Server.open} bind an endpoint
+  # that already exists; {Server.open} with a block closes the server when the
+  # block ends. {Server.start} starts a private daemon instead, creates no
+  # session, and owns the daemon's exit. {#endpoint} answers the {Endpoint}
+  # and {#owned?} says whether this server started its daemon. {#diagnostics}
+  # reports the request and control slots in use, and the limits. {#close}
+  # retires the server's clients; on an owned server it also stops the daemon.
+  # {#open_control} opens a {ControlConnection} to a session.
+  #
+  # **Finding one thing.** {#session}, {#window}, {#pane}, and {#window_link}
+  # wrap an {EntityRef} in a handle without running a command. Take the ref
+  # from a handle or a snapshot record. A ref of the wrong kind raises
+  # {TargetNotFoundError}; one whose entity has gone fails at its first
+  # command.
+  #
+  # **Listing everything.** {#list_sessions}, {#list_windows}, and
+  # {#list_panes} answer frozen arrays of handles in numeric ID order, and
+  # {#list_window_links} answers every {WindowLink}. {#list_clients} answers
+  # one hash per client. {#snapshot} captures the session, window, and pane
+  # tree, and clients with `clients: true`, as one validated {Snapshot}.
+  #
+  # **Querying things and getting around.** {#search_panes} filters the panes
+  # of a snapshot with `where:`, a hash of criteria or a {FilterExpr}, and
+  # answers a {Selection}; {#explain_panes} answers the plan for a query
+  # without running tmux. A {Selection} narrows with {Selection#where},
+  # {Selection#select}, {Selection#filter}, and {Selection#reject}, tests with
+  # {Selection#exists?}, and takes a single match with {Selection#one}, which
+  # raises {NoMatchError} or {MultipleMatchesError} otherwise, or
+  # {Selection#one_or_nil}. Build and compose criteria with
+  # {FilterExpr.build}, {FilterExpr#and}, {FilterExpr#or}, {FilterExpr#not},
+  # and {FilterExpr.from_json}.
+  #
+  # A {Snapshot} answers relational questions without another command:
+  # {Snapshot#sessions}, {Snapshot#windows}, {Snapshot#panes}, and
+  # {Snapshot#clients}. Its records follow relations by name: a
+  # {SessionSnapshot} reaches `windows`, `panes`, and `current_window`, a
+  # {WindowSnapshot} reaches `panes` and `active_pane`, and a {PaneSnapshot}
+  # reaches its `window`. {Entity#snapshot} reads one handle back as a record,
+  # and {CapturedRecord#ref} with {#session}, {#window}, or {#pane} turns a
+  # record into a handle. Live handles go down one command at a time with
+  # {Session#list_windows}, {Session#list_panes}, and {Window#list_panes}, and
+  # back up with {Entity#server}.
+  #
+  # **Changing things.** {#new_session} starts a detached session running
+  # `command:`, an argv array rather than a shell string, and answers the
+  # {Session} or, with `receipt: true`, a {CreationReceipt}. {#kill} stops the
+  # tmux server, which {#close} does only for an owned server.
+  # {#switch_client} points the client named by `client:` at a session.
+  #
+  # **Options and hooks.** {#options} answers {Options} at server scope, or at
+  # the global session or window scope. {#hooks} answers {Hooks} at the global
+  # session or window scope. {#environment}, {#set_environment}, and
+  # {#unset_environment} read, set, and unset one variable in the server's
+  # global environment.
+  #
+  # **Everything else tmux keeps.** Paste buffers: {#list_buffers},
+  # {#read_buffer}, {#write_buffer}, and {#delete_buffer}. {#source_file}
+  # loads a configuration file. {#display} expands a tmux format; the argument
+  # is a format, not literal text. {#wait_for} waits on, signals, locks, or
+  # unlocks a channel, as `action:` says.
+  #
+  # **Things that need a terminal.** {#attach} runs an interactive client on a
+  # TTY the caller supplies and keeps, blocks until that client exits, and
+  # answers a {TerminalResult}. Cancelling detaches the client and does not
+  # stop pane commands.
+  #
+  # Anything else tmux can do is reachable through {#run}, which runs one
+  # command from an argv array and keeps tmux's separators and format
+  # semantics, or {#run_group}, which runs several in one tmux invocation. A
+  # {GroupResult} cannot attribute the client's final status to a single step.
   class Server
     attr_reader :endpoint
 
@@ -42,7 +134,8 @@ module LibTmux
       result
     end
 
-    def initialize(endpoint: nil, socket_path: nil, socket_name: nil, executable: "tmux", max_requests: 32, max_controls: 4, close_timeout: 0.5)
+    def initialize(endpoint: nil, socket_path: nil, socket_name: nil, executable: "tmux", max_requests: 32, max_controls: 4, close_timeout: 0.5,
+      version_timeout: 5.0)
       if endpoint && (socket_path || socket_name || executable != "tmux")
         raise ArgumentError, "endpoint cannot be combined with socket or executable options"
       end
@@ -57,6 +150,10 @@ module LibTmux
         raise ArgumentError, "close_timeout must be positive and finite"
       end
 
+      unless version_timeout.is_a?(Numeric) && version_timeout.finite? && version_timeout.positive?
+        raise ArgumentError, "version_timeout must be positive and finite"
+      end
+
       @endpoint = endpoint || Endpoint.new(socket_path: socket_path, socket_name: socket_name, executable: executable)
       @owner_pid = Process.pid
       @max_requests = max_requests
@@ -69,6 +166,19 @@ module LibTmux
       @closed = false
       @executor = Internal::ProcessExecutor.new
       @pin = Internal::SocketIdentity.new(@endpoint)
+      begin
+        @release = Internal::TmuxVersion.connected(@pin.command_prefix) { |argv| @executor.run(argv, timeout: version_timeout, discard_stdout: true) }
+        argv, marker = Internal::TmuxVersion.fence_check_argv
+        Internal::TmuxVersion.verify_fence(@executor.run(@pin.command_prefix + argv, timeout: version_timeout), marker)
+      rescue Exception
+        @pin.close
+        raise
+      end
+    end
+
+    # The daemon's release text, such as "3.7d" or "next-3.9".
+    def tmux_version
+      @release.text
     end
 
     # Raw tmux arguments retain tmux's separators and format semantics.
@@ -79,8 +189,10 @@ module LibTmux
       raise ArgumentError, "raw commands cannot override endpoint flags" if argv.first.start_with?("-")
       raise ArgumentError, "timeout must be finite" unless timeout.is_a?(Numeric) && timeout.finite?
       perform_request(cancel: cancel) do |view|
-        @executor.run(@pin.command_prefix + argv, input: input,
+        fence, marker = Internal::TmuxVersion.fence(@release)
+        result = @executor.run(@pin.command_prefix + fence + argv, input: input,
           timeout: timeout - (monotonic - started), cancel: view)
+        Internal::TmuxVersion.check_fence(result, marker, @release)
       end
     end
 
@@ -283,6 +395,10 @@ module LibTmux
     end
     private_constant :CancellationView
 
+    def tmux_release
+      with_bound_endpoint { |_endpoint, _pin, release| release }
+    end
+
     def monotonic
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
@@ -298,7 +414,7 @@ module LibTmux
       ensure_owner
       @mutex.synchronize do
         ensure_open
-        yield @endpoint, @pin
+        yield @endpoint, @pin, @release
       end
     end
 

data/lib/libtmux/socket_readiness.rb

@@ -147,6 +147,10 @@ module LibTmux
     end
 
     class LogSocketReadiness
+      # tmux 3.8 parses more default key bindings under -v than 3.7, so the
+      # log reaches "server loop enter" past 1 MiB.
+      LIMIT = 1 << 22
+
       attr_reader :bytes_read
 
       def initialize(directory)
@@ -184,7 +188,7 @@ module LibTmux
         end
         while (bytes = @log.read(16_384))
           @bytes_read += bytes.bytesize
-          if @bytes_read > 1 << 20
+          if @bytes_read > LIMIT
             raise CapacityError.new("owned startup log exceeded byte limit", phase: :startup, pid: child.pid, delivery: :possibly_sent)
           end
           text = @tail + bytes

data/lib/libtmux/support.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "libtmux/errors"
+require "libtmux/tmux_version"
+
+module LibTmux
+  # Here "support" means which tmux releases libtmux supports, not helper
+  # code. Every server handle checks its daemon's release before any command
+  # runs; this module exposes that check.
+  module Support
+    # The version check: is this tmux daemon supported at all?
+    module Versions
+      MINIMUM = Internal::TmuxVersion::MINIMUM
+
+      module_function
+
+      # Returns the release text when +value+ is a supported release and
+      # raises UnsupportedFeatureError otherwise.
+      def require_supported(value)
+        Internal::TmuxVersion.require_supported(value).text
+      end
+
+      # The release text of the daemon behind +server+, such as "3.7d".
+      def server_version(server)
+        server.tmux_version
+      end
+    end
+
+    MINIMUM = Versions::MINIMUM
+
+    module_function
+
+    def require_supported(value) = Versions.require_supported(value)
+
+    def server_version(server) = Versions.server_version(server)
+  end
+end

data/lib/libtmux/tmux_version.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "libtmux/errors"
+require "securerandom"
+
+module LibTmux
+  module Internal
+    # Version check for the tmux daemon a server handle is bound to.
+    #
+    # The connected daemon decides support, not the configured client. A
+    # release is read once through the retained route and every dispatch is
+    # then fenced against that exact text.
+    module TmuxVersion
+      MINIMUM = "3.3a"
+      # The forms tmux has reported: X.Y, X.Y plus a patch letter, X.Y-rc and
+      # X.Y-rcN candidates, and next-X.Y development builds. Anything else,
+      # including master and openbsd-*, is not a release number. The candidate
+      # number is bounded so that it can never outrank the release it precedes.
+      PATTERN = /\A(?:next-(?<next_major>\d+)\.(?<next_minor>\d+)|(?<major>\d+)\.(?<minor>\d+)(?:(?<patch>[a-z])|(?<candidate>-rc(?<number>\d{1,3})?))?)\z/
+      # tmux resolves a command-alias entry by exact name before it resolves a
+      # command, so the full names run-shell and if-shell can be hijacked by
+      # one alias, as the existing link guards avoid with builtin_spellings.
+      # These unique prefixes are out of reach of such an entry, and
+      # verify_fence proves at the version check that the fence still rejects
+      # its marker, so an alias named for a prefix, or a future command
+      # sharing it, refuses the server instead of silently disabling the fence.
+      FENCE_COMMAND = "if-shel"
+      PROBE_COMMAND = "run-shel"
+      ABSENT = /no server running|error connecting to .*\((?:No such file or directory|Connection refused)\)/
+      # What a daemon older than 3.2 answers to the probe. run-shell gained -C
+      # in 3.2, so 3.1 reports its usage line; a 3.0 daemon speaks a protocol
+      # the client refuses before any command runs.
+      PRE_3_2_ANSWER = /\A(?:usage: run-shell \[-b\] \[-t target-pane\] shell-command|server version is too old for client)\n\z/
+      REMEDY = "upgrade tmux and restart the server, or pin the previous libtmux release"
+      # Marks the refusals that mean "this daemon is not the supported one",
+      # so a caller that cannot show the full message can still name the floor.
+      EXPECTED = "tmux #{MINIMUM} or newer"
+
+      # `key` orders releases: major, minor, patch letter, then the build kind.
+      # A development build or release candidate ranks below the release it
+      # names: next-X.Y < X.Y-rc < X.Y-rcN < X.Y < X.Ya.
+      STABLE = 1 << 20
+
+      Release = Data.define(:text, :key) do
+        include Comparable
+
+        def <=>(other)
+          key <=> other.key if other.is_a?(Release)
+        end
+      end
+
+      module_function
+
+      def parse(value, source: "the daemon")
+        match = value.is_a?(String) && PATTERN.match(value)
+        raise unrecognized(value, source) unless match
+
+        key = if match[:next_major]
+          [match[:next_major].to_i, match[:next_minor].to_i, 0, 0]
+        else
+          patch = match[:patch] ? match[:patch].ord - 96 : 0
+          kind = match[:candidate] ? 1 + match[:number].to_i : STABLE
+          [match[:major].to_i, match[:minor].to_i, patch, kind]
+        end
+        Release.new(text: value.dup.freeze, key: key.freeze)
+      end
+
+      def require_supported(value, minimum: MINIMUM, source: "the daemon")
+        release = parse(value, source: source)
+        if (release <=> parse(minimum)).negative?
+          reported = (source == "the daemon") ? "connected version" : "#{source} reports"
+          raise UnsupportedFeatureError.new("tmux #{minimum} or newer is required (#{reported} #{release.text}); #{REMEDY}",
+            phase: :admission, expected: EXPECTED)
+        end
+        release
+      end
+
+      # Names what the daemon or executable reported, shortened so that a
+      # long report cannot flood the message.
+      def unrecognized(value, source)
+        shown = value.is_a?(String) ? value.byteslice(0, 64).scrub("?") : value
+        UnsupportedFeatureError.new("tmux version is unrecognized (#{source} reports #{shown.inspect}); " \
+          "tmux #{MINIMUM} or newer is required; #{REMEDY}", phase: :admission, expected: EXPECTED)
+      end
+
+      # Reads the daemon behind +prefix+. The block runs the argv and returns a
+      # CommandResult. Unlike display-message, run-shell -C fires no after-*
+      # hook and no command-error hook: tmux parses the expanded string after
+      # the command returned, so the private unknown command it reports has no
+      # effect and the version travels in the error text.
+      def connected(prefix)
+        marker = "libtmux-version-#{SecureRandom.hex(16)}-"
+        result = yield(prefix + [PROBE_COMMAND, "-C", marker + '#{version}'])
+        stderr = result.stderr.dup.force_encoding(Encoding::UTF_8)
+        if !result.success? && result.stdout.empty? && (match = /\Aunknown command: #{Regexp.escape(marker)}([^\n]+)\n\z/.match(stderr))
+          return require_supported(match[1])
+        end
+        if !result.success? && result.stdout.empty? && PRE_3_2_ANSWER.match?(stderr)
+          raise UnsupportedFeatureError.new("tmux #{MINIMUM} or newer is required (the connected daemon is older than 3.2); #{REMEDY}",
+            phase: :admission, expected: EXPECTED)
+        end
+        if ABSENT.match?(stderr)
+          raise TargetNotFoundError.new("no tmux server is running at the selected endpoint", phase: :admission)
+        end
+
+        raise CommandError.new("tmux did not report a daemon version", result: result, phase: :admission, delivery: :not_sent)
+      rescue Error => error
+        raise not_sent(error), cause: nil
+      end
+
+      # Reads the executable that would start a new daemon. tmux 3.3a prints
+      # its own file name where later releases print "tmux".
+      def executable(path)
+        result = yield([path, "-V"])
+        unless result.success?
+          raise CommandError.new("tmux did not report its version", result: result, phase: :admission, delivery: :not_sent)
+        end
+
+        names = ["tmux", File.basename(path)].uniq.map { |name| Regexp.escape(name.b) }.join("|")
+        match = /\A(?:#{names}) ([^\n]+)\n?\z/n.match(result.stdout)
+        raise unrecognized(result.stdout.strip, "the executable") unless match
+
+        require_supported(match[1], source: "the executable")
+      rescue Error => error
+        raise not_sent(error), cause: nil
+      end
+
+      # Leading commands for one dispatch. A daemon that no longer reports
+      # +release+ fails the if-shell condition and reaches the private marker,
+      # which tmux rejects before the commands that follow.
+      def fence(release)
+        marker = "libtmux-version-#{SecureRandom.hex(16)}"
+        [[FENCE_COMMAND, "-F", "\#{==:\#{version},#{release.text}}", "", marker, ";"], marker]
+      end
+
+      # A server runs this once when it is checked. A true if-shell condition
+      # runs a probe whose parse error names the marker, which shows that the
+      # fence command and the probe command are the real ones, with no failing
+      # command and so no hook.
+      def fence_check_argv
+        marker = "libtmux-fence-#{SecureRandom.hex(16)}"
+        [[FENCE_COMMAND, "-F", "1", "#{PROBE_COMMAND} -C #{marker}"], marker]
+      end
+
+      def verify_fence(result, marker)
+        return result if !result.success? && result.stdout.empty? && result.stderr.b == "unknown command: #{marker}\n".b
+
+        raise UnsupportedFeatureError.new("a tmux command-alias or command shadows #{FENCE_COMMAND} or " \
+          "#{PROBE_COMMAND}; remove it before opening a server", phase: :admission, delivery: :not_sent)
+      end
+
+      def check_fence(result, marker, release)
+        return result unless result.stderr.b.each_line.any? { |line| line.chomp == "unknown command: #{marker}".b }
+
+        raise UnsupportedFeatureError.new("the tmux daemon no longer reports #{release.text}; reopen the server",
+          phase: :admission, delivery: :not_sent, expected: EXPECTED)
+      end
+
+      # True for the refusals that name the supported floor: an unsupported,
+      # unreadable or changed daemon. Other unsupported features are not.
+      def refusal?(error)
+        error.is_a?(UnsupportedFeatureError) && error.expected == EXPECTED
+      end
+
+      # A fixed line for results that cannot carry the full message.
+      def hint
+        "tmux #{MINIMUM} or newer is required, and the daemon must stay the " \
+          "one the server opened with; upgrade tmux and restart the server"
+      end
+
+      # A failed probe sent nothing, whatever stage it failed in, so only the
+      # delivery is forced; the error keeps its own phase.
+      def not_sent(error)
+        details = {delivery: :not_sent, phase: error.phase, pid: error.pid, cleanup_errors: error.cleanup_errors,
+          expected: error.expected}
+        return error.class.new(error.message, result: error.result, **details) if error.is_a?(CommandError)
+
+        error.class.new(error.message, **details)
+      end
+    end
+  end
+end

data/lib/libtmux/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LibTmux
-  VERSION = "0.1.0.alpha.1"
+  VERSION = "0.1.0.alpha.2"
 end

data/lib/libtmux.rb

@@ -8,6 +8,7 @@ require "libtmux/metadata"
 require "libtmux/selection"
 require "libtmux/entity"
 require "libtmux/server"
+require "libtmux/support"
 require "libtmux/operations"
 require "libtmux/criteria"
 require "libtmux/capture"

data/schema/where-v1.json

@@ -994,9 +994,16 @@
     "pane.pid": {
       "anyOf": [
         {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 2147483647
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 2147483647
+            },
+            {
+              "type": "null"
+            }
+          ]
         },
         {
           "type": "object",
@@ -1004,9 +1011,16 @@
           "additionalProperties": false,
           "properties": {
             "equals": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 2147483647
+              "anyOf": [
+                {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 2147483647
+                },
+                {
+                  "type": "null"
+                }
+              ]
             },
             "not": {
               "$ref": "#/$defs/pane.pid"
@@ -1015,9 +1029,16 @@
               "type": "array",
               "maxItems": 1024,
               "items": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 2147483647
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 2147483647
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
               }
             },
             "lt": {

data/sig/fields.rbs

@@ -28,7 +28,7 @@ module LibTmux
     def id: () -> String
     def window_id: () -> String
     def index: () -> Integer
-    def pid: () -> Integer
+    def pid: () -> Integer?
     def current_command: () -> String
     def current_path: () -> String?
     def title: () -> String

data/sig/libtmux.rbs

@@ -139,11 +139,24 @@ module LibTmux
     def send_keys: (*String, ?timeout: Numeric, ?cancel: untyped) -> CommandResult
   end
 
+  module Support
+    MINIMUM: String
+    def self.require_supported: (String value) -> String
+    def self.server_version: (Server server) -> String
+
+    module Versions
+      MINIMUM: String
+      def self.require_supported: (String value) -> String
+      def self.server_version: (Server server) -> String
+    end
+  end
+
   class Server
     attr_reader endpoint: Endpoint
-    def self.open: [T] (?endpoint: Endpoint?, ?socket_path: String?, ?socket_name: String?, ?executable: String, ?max_requests: Integer, ?max_controls: Integer, ?close_timeout: Numeric) { (Server) -> T } -> T
-                 | (?endpoint: Endpoint?, ?socket_path: String?, ?socket_name: String?, ?executable: String, ?max_requests: Integer, ?max_controls: Integer, ?close_timeout: Numeric) -> Server
-    def initialize: (?endpoint: Endpoint?, ?socket_path: String?, ?socket_name: String?, ?executable: String, ?max_requests: Integer, ?max_controls: Integer, ?close_timeout: Numeric) -> void
+    def self.open: [T] (?endpoint: Endpoint?, ?socket_path: String?, ?socket_name: String?, ?executable: String, ?max_requests: Integer, ?max_controls: Integer, ?close_timeout: Numeric, ?version_timeout: Numeric) { (Server) -> T } -> T
+                 | (?endpoint: Endpoint?, ?socket_path: String?, ?socket_name: String?, ?executable: String, ?max_requests: Integer, ?max_controls: Integer, ?close_timeout: Numeric, ?version_timeout: Numeric) -> Server
+    def initialize: (?endpoint: Endpoint?, ?socket_path: String?, ?socket_name: String?, ?executable: String, ?max_requests: Integer, ?max_controls: Integer, ?close_timeout: Numeric, ?version_timeout: Numeric) -> void
+    def tmux_version: () -> String
     def run: (Array[String], ?input: String, ?timeout: Numeric, ?cancel: untyped) -> CommandResult
     def close: () -> nil
     def diagnostics: () -> {admitted_requests: Integer, reserved_process_slots: Integer, control_connections: Integer, closed: bool, limits: {max_requests: Integer, max_controls: Integer, close_timeout: Numeric}}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.1
+  version: 0.1.0.alpha.2
 platform: ruby
 authors:
 - libtmux contributors
@@ -87,6 +87,8 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- assets/logo.png
+- assets/logo.svg
 - lib/libtmux.rb
 - lib/libtmux/capture.rb
 - lib/libtmux/catalog.rb
@@ -108,7 +110,9 @@ files:
 - lib/libtmux/snapshot.rb
 - lib/libtmux/socket_readiness.rb
 - lib/libtmux/source_query.rb
+- lib/libtmux/support.rb
 - lib/libtmux/terminal.rb
+- lib/libtmux/tmux_version.rb
 - lib/libtmux/version.rb
 - schema/where-v1.json
 - sig/control.rbs
@@ -125,6 +129,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/libtmux/libtmux-ruby
+  documentation_uri: https://libtmux.org/en/ruby/v0.1.0.alpha.2/
 rdoc_options: []
 require_paths:
 - lib