libtmux 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1c19838a471ee26a9953d27f31bbaece230b6b8d2422d58dd5c57d0512a186f8
+  data.tar.gz: ce84cd707102bcd05b9a32d7dfdd7d59791fa8a802aa4eb81068bc36f81caae6
+SHA512:
+  metadata.gz: 99d71b78ddff682bbafbcb3cd24a60989cb8e5ea052bd34e83902276ccdf044b13ade3d8916fd7342e5627ebc752d8f4a7a30e85d22e703455ca423b5a5dcfbb
+  data.tar.gz: 835a4ff8a6185b3db991705836e229a5cf574b90ed8805d0110a21028878cbb9141368d4c52a88da2c9441342c7e1791bf300012f262b88dd73bc0c53103fcc0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026- libtmux contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# libtmux
+
+Ruby tmux orchestration core. `Server.open` borrows an
+existing explicit endpoint. Closing it retires owned clients and preserves
+the daemon; `kill` explicitly terminates the daemon. `Server.start` creates a
+private owned foreground daemon whose lifetime ends with its server handle.
+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.
+
+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
+guide for local build and verification commands.
+
+Handles carry immutable refs bound to one open server binding. IDs and refs
+are local readers; `list_*`, `snapshot` and command methods perform explicit
+I/O. Global windows represent unique entities. `WindowLink` retains a session,
+index and window ID so repeated links stay distinct.
+
+Link selection, unlinking, movement, swapping and display check the complete
+link identity in the same tmux queue turn as their operation. Configured
+command aliases are avoided using unshadowed builtin spellings. Hook waits
+before dispatch cannot turn a stale link into its replacement. Concurrent
+rewriting of command aliases is outside this guarantee; applications must
+coordinate configuration changes.
+
+Typed arguments preserve literal semicolons and distinguish pane text from
+key names. Pane commands take executable argument arrays. Hook commands,
+display formats, pipe shell commands and `source_file` configuration are
+explicit executable inputs. `Server.run` remains the raw tmux escape hatch,
+including daemon aliases, separators and format semantics.
+
+Creation accepts `cwd:` and a String-to-String `environment:` map. Directories
+resolve from the Ruby caller and are checked before dispatch; concurrent
+filesystem changes can still trigger tmux's directory fallback. Creation
+returns tmux-assigned IDs after dispatch, without claiming program readiness
+or a successful program exit. `new_session(window_name:)` names the initial
+window; its index can be moved explicitly after creation. `new_window(index:)`
+refuses an occupied slot. `Pane#split` targets that exact pane, with `size:` as
+cells or a percentage string. Windows and splits retain focus unless
+`focus: true` is requested.
+
+Typed operations accept `timeout:` and `cancel:`. Composed link and copy operations
+share one deadline across their preflights and final dispatch. Copy-mode
+exit uses `cancel_mode: true`; `cancel:` accepts `LibTmux::Cancellation.new`.
+Call the token's `cancel` from another thread to wake a blocked request, join
+its caller, then `close` the token. See the [plain-Ruby cancellation recipe](../../examples/cancel.rb)
+and [ownership contract](../../docs/ownership-errors.md).
+
+`Options` retains raw bytes, inheritance and sparse array indexes;
+`OptionValue#as` requests a strict conversion. Hook values remain tmux command
+strings. The stable tmux option listing uses its escaped representation,
+including octal bytes; it does not split raw values on line breaks. Option
+names containing whitespace are currently rejected. Inherited hook listing
+is not implemented and raises explicitly.
+
+Indexed `get` acquires the array and selects locally, so a missing index raises
+`NoMatchError` while a present empty value remains present. Reading an array
+without an index raises `MultipleMatchesError` when it has several entries.
+Append follows tmux's lowest-free-index rule; indexed hooks execute in index
+order. Empty arrays remain distinct from empty String values.
+
+Binary buffers and command results preserve trailing newlines. Capture can
+join wrapped lines, include attribute escapes, escape nonprintable bytes,
+preserve trailing spaces and trim unused trailing cells. `mode_screen: true`
+reads the mode's backing screen (the copy-mode snapshot, without its UI),
+`alternate: true` reads tmux's saved screen and raises when absent (while an
+application occupies the alternate screen, this is the saved main screen),
+and `pending: true` reads an incomplete escape sequence. These three selectors
+are mutually exclusive. Mode-screen and trailing-cell flags are checked
+against advertised command usage; unsupported requests raise explicitly.
+Copy-mode flags are checked against the connected daemon's advertised command
+usage. Client discovery returns observations. `Server#attach` uses an explicit
+caller-owned TTY and terminal type, waits for its owned client to exit, and
+restores the terminal mode. `Server#switch_client(client:, session:)` switches
+an explicit current native client selector to an exact bound session, keeping
+the session environment. A missing selector fails without fallback. This
+operation does not turn a client observation into an incarnation-safe
+reference; a reconnect matching the selector is eligible at dispatch.
+
+Control connections expose bounded event subscriptions and raw guarded replies.
+`pause_output(pane_id:)` and `resume_output(pane_id:)` return `GuardedReply`;
+they do not establish that an action took effect. Their gap events identify
+`:pause_requested` or `:resume_requested` when no outside-block native notice
+was observed, including cancellation after possible dispatch. Native notices
+use `:pause` and `:resume`. Loss counts are unknown (`dropped_bytes: nil`);
+resume does not replay skipped output. Guarded notification-looking text stays
+in its reply body.
+
+Close the old control connection, then explicitly call
+`server.open_control(session: ref, reconnect: old_connection)` to reconnect
+within the same binding and session. The replacement has a new `generation`
+and retains `previous_generation`. Every new subscription begins with a
+`:reconnect` gap containing both generations and an unknown loss count. Old
+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,
+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;
+installed signature consumers check selected real arguments, blocks and
+return values. [Executable recipes](../../docs/recipes.md) run
+against installed artifacts; the documentation gate renders YARD and guides
+and checks local destinations and fragments. The [public method inventory](../../docs/reference/api.md)
+links exported methods to source and behavioral contracts. These consumer
+checks do not establish whole-program static typing.

data/lib/libtmux/capture.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "snapshot"
+require_relative "metadata"
+
+module LibTmux
+  module Internal
+    class Capture
+      def initialize(server, binding_key:)
+        @server = server
+        @binding_key = binding_key.dup.freeze
+      end
+
+      def call(timeout: 5.0, cancel: nil, clients: false, max_bytes: 1 << 20,
+        max_rows: 10_000, max_field_bytes: 1 << 16)
+        unless timeout.is_a?(Numeric) && timeout.finite?
+          raise ArgumentError, "capture timeout must be finite"
+        end
+        unless [max_bytes, max_rows, max_field_bytes].all? { |value| value.is_a?(Integer) && value.positive? }
+          raise ArgumentError, "capture limits must be positive integers"
+        end
+        unless clients == true || clients == false
+          raise ArgumentError, "clients must be a Boolean"
+        end
+        if cancel && !(cancel.respond_to?(:cancelled?) && cancel.respond_to?(:reader))
+          raise ArgumentError, "cancel must be a cancellation token"
+        end
+        started_at = monotonic
+        budget = {deadline: started_at + timeout, cancel: cancel, max_bytes: max_bytes,
+                  max_rows: max_rows, max_field_bytes: max_field_bytes, bytes: 0, rows: 0, reads: []}
+        server_info = acquire_server_info(budget)
+        2.times do |attempt|
+          rows = acquire_rows(budget, attempt + 1, clients)
+          check_budget(budget)
+          begin
+            snapshot = Snapshot.__send__(:new, rows: rows, binding_key: @binding_key,
+              started_at: started_at, finished_at: monotonic, reads: budget.fetch(:reads), server_info: server_info)
+            check_budget(budget)
+            return snapshot
+          rescue InconsistentSnapshotError
+            raise if attempt == 1
+            check_budget(budget)
+          end
+        end
+      end
+
+      private
+
+      def acquire_server_info(budget)
+        rows = read(budget, :server, 1, ["display-message", "-p", framing(%w[version pid start_time])], 3)
+        unless rows.length == 1
+          raise ProtocolError.new("invalid capture server metadata", delivery: :observed, phase: :capture)
+        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)
+        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"}}
+      end
+
+      def acquire_rows(budget, attempt, clients)
+        sessions = catalog_read(budget, :session, attempt, ["list-sessions"])
+        if sessions.empty?
+          # tmux has no windows or panes without a session. Their list commands
+          # nevertheless require a default target, so the complete empty root
+          # supplies this evidence without treating command failures as emptiness.
+          rows = {session: sessions, window: [], window_link: [], pane: []}
+          rows[:client] = [] if clients
+          return rows
+        end
+        window_fields = Catalog.entity(:window).fields.values
+        link_fields = Catalog.entity(:window_link).fields.values
+        combined = read(budget, :window_link, attempt,
+          ["list-windows", "-a", "-F", framing((window_fields + link_fields).map(&:format))],
+          window_fields.length + link_fields.length)
+        windows = []
+        links = []
+        combined.each do |row|
+          windows << window_fields.map(&:name).zip(row.take(window_fields.length)).to_h
+          links << link_fields.map(&:name).zip(row.drop(window_fields.length)).to_h
+        end
+        rows = {session: sessions, window: windows, window_link: links,
+                pane: catalog_read(budget, :pane, attempt, ["list-panes", "-a"])}
+        rows[:client] = catalog_read(budget, :client, attempt, ["list-clients"]) if clients
+        rows
+      end
+
+      def catalog_read(budget, kind, attempt, command)
+        fields = Catalog.entity(kind).fields.values
+        read(budget, kind, attempt, command + ["-F", framing(fields.map(&:format))], fields.length)
+          .map { |row| fields.map(&:name).zip(row).to_h }
+      end
+
+      def framing(formats)
+        Metadata.format(formats)
+      end
+
+      def read(budget, source, attempt, argv, field_count)
+        started_at = monotonic
+        remaining = check_budget(budget)
+        result = @server.__send__(:execute_typed, argv, timeout: remaining, cancel: budget.fetch(:cancel))
+        finished_at = monotonic
+        budget[:bytes] += result.stdout.bytesize
+        capacity("capture exceeds its total byte limit") if budget.fetch(:bytes) > budget.fetch(:max_bytes)
+        remaining_rows = budget.fetch(:max_rows) - budget.fetch(:rows)
+        capacity("capture exceeds its total row limit") if remaining_rows <= 0 && !result.stdout.empty?
+        rows = Metadata.decode(result.stdout, fields: field_count, quoted: true, max_bytes: budget.fetch(:max_bytes),
+          max_rows: [remaining_rows, 1].max, max_field_bytes: budget.fetch(:max_field_bytes))
+        budget[:rows] += rows.length
+        budget.fetch(:reads) << {source: source, attempt: attempt, started_at: started_at,
+                                finished_at: finished_at, bytes: result.stdout.bytesize, rows: rows.length}
+        rows
+      end
+
+      def check_budget(budget)
+        delivery = budget.fetch(:reads).empty? ? :not_sent : :observed
+        if budget.fetch(:cancel)&.cancelled?
+          raise Cancelled.new("capture cancelled", delivery: delivery, phase: :capture)
+        end
+        remaining = budget.fetch(:deadline) - monotonic
+        unless remaining.positive?
+          raise DeadlineExceeded.new("capture exceeded its deadline", delivery: delivery, phase: :capture)
+        end
+        remaining
+      end
+
+      def capacity(message)
+        raise CapacityError.new(message, delivery: :observed, phase: :capture)
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/libtmux/catalog.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module LibTmux
+  module Internal
+    # Names and bounds are explicit: wire spelling is not Ruby case conversion.
+    module Catalog
+      Field = Data.define(:id, :name, :wire_name, :type, :nullable, :empty_is_null, :min, :max,
+        :operators, :format, :min_version, :scope, :capture_requirements)
+      Relation = Data.define(:name, :wire_name, :target, :cardinality, :nullable,
+        :capture_requirements)
+      Schema = Data.define(:kind, :wire_entity, :fields, :relations)
+
+      EQUALITY = %i[equals not in].freeze
+      INTEGER = (EQUALITY + %i[lt lte gt gte]).freeze
+      TEXT = (EQUALITY + %i[contains starts_with ends_with]).freeze
+      UINT_MAX = (1 << 32) - 1
+      INT_MAX = (1 << 31) - 1
+      TIME_MIN = -(1 << 63)
+      TIME_MAX = (1 << 63) - 1
+      private_constant :EQUALITY, :INTEGER, :TEXT, :UINT_MAX, :INT_MAX, :TIME_MIN, :TIME_MAX
+
+      def self.field(scope, id, name, wire_name, format, type, nullable: false, empty_is_null: false, min: nil, max: nil, operators: nil)
+        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)
+      end
+      private_class_method :field
+
+      def self.relation(name, wire_name, target, cardinality, *requirements, nullable: false)
+        Relation.new(name: name, wire_name: wire_name, target: target, cardinality: cardinality,
+          nullable: nullable, capture_requirements: requirements.freeze)
+      end
+      private_class_method :relation
+
+      def self.schema(kind, wire_entity, fields, relations)
+        Schema.new(kind: kind, wire_entity: wire_entity,
+          fields: fields.to_h { |field| [field.name, field] }.freeze,
+          relations: relations.to_h { |relation| [relation.name, relation] }.freeze)
+      end
+      private_class_method :schema
+
+      # 3.2a is the supported capture baseline, not a claim about first introduction.
+      SCHEMAS = {
+        session: schema(:session, "session", [
+          field(:session, "session.id", :id, "id", "session_id", :text, operators: EQUALITY),
+          field(:session, "session.name", :name, "name", "session_name", :text),
+          field(:session, "session.created", :created, "created", "session_created", :integer, min: TIME_MIN, max: TIME_MAX),
+          field(:session, "session.attached", :attached, "attached", "session_attached", :integer, min: 0, max: UINT_MAX),
+          field(:session, "session.window_count", :window_count, "windowCount", "session_windows", :integer, min: 0, max: UINT_MAX)
+        ], [
+          relation(:windows, "windows", :window, :many, :window_link, :window),
+          relation(:window_links, "windowLinks", :window_link, :many, :window_link),
+          relation(:panes, "panes", :pane, :many, :window_link, :window, :pane),
+          relation(:current_window, "currentWindow", :window, :one, :window_link, :window, nullable: true)
+        ]),
+        window: schema(:window, "window", [
+          field(:window, "window.id", :id, "id", "window_id", :text, operators: EQUALITY),
+          field(:window, "window.name", :name, "name", "window_name", :text),
+          field(:window, "window.width", :width, "width", "window_width", :integer, min: 0, max: UINT_MAX),
+          field(:window, "window.height", :height, "height", "window_height", :integer, min: 0, max: UINT_MAX),
+          field(:window, "window.pane_count", :pane_count, "paneCount", "window_panes", :integer, min: 0, max: UINT_MAX),
+          field(:window, "window.layout", :layout, "layout", "window_layout", :text)
+        ], [
+          relation(:panes, "panes", :pane, :many, :pane),
+          relation(:window_links, "windowLinks", :window_link, :many, :window_link),
+          relation(:active_pane, "activePane", :pane, :one, :pane, nullable: true)
+        ]),
+        pane: schema(:pane, "pane", [
+          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.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),
+          field(:pane, "pane.active", :active, "active", "pane_active", :boolean),
+          field(:pane, "pane.dead", :dead, "dead", "pane_dead", :boolean),
+          field(:pane, "pane.dead_status", :dead_status, "deadStatus", "pane_dead_status", :integer, nullable: true, empty_is_null: true, min: 0, max: 255),
+          field(:pane, "pane.width", :width, "width", "pane_width", :integer, min: 0, max: UINT_MAX),
+          field(:pane, "pane.height", :height, "height", "pane_height", :integer, min: 0, max: UINT_MAX)
+        ], [relation(:window, "window", :window, :one, :window)]),
+        window_link: schema(:window_link, "window_link", [
+          field(:window_link, "window_link.session_id", :session_id, "sessionId", "session_id", :text, operators: EQUALITY),
+          field(:window_link, "window_link.window_id", :window_id, "windowId", "window_id", :text, operators: EQUALITY),
+          field(:window_link, "window_link.index", :index, "index", "window_index", :integer, min: 0, max: INT_MAX),
+          field(:window_link, "window_link.active", :active, "active", "window_active", :boolean)
+        ], [
+          relation(:session, "session", :session, :one, :session),
+          relation(:window, "window", :window, :one, :window)
+        ]),
+        client: schema(:client, "client", [
+          field(:client, "client.name", :name, "name", "client_name", :text),
+          field(:client, "client.pid", :pid, "pid", "client_pid", :integer, min: 0, max: INT_MAX),
+          field(:client, "client.created", :created, "created", "client_created", :integer, min: TIME_MIN, max: TIME_MAX),
+          field(:client, "client.tty", :tty, "tty", "client_tty", :text, nullable: true, empty_is_null: true),
+          field(:client, "client.session_id", :session_id, "sessionId", "session_id", :text, nullable: true, empty_is_null: true, operators: EQUALITY),
+          field(:client, "client.width", :width, "width", "client_width", :integer, min: 0, max: UINT_MAX),
+          field(:client, "client.height", :height, "height", "client_height", :integer, nullable: true, empty_is_null: true, min: 0, max: UINT_MAX),
+          field(:client, "client.read_only", :read_only, "readOnly", "client_readonly", :boolean),
+          field(:client, "client.utf8", :utf8, "utf8", "client_utf8", :boolean),
+          field(:client, "client.control_mode", :control_mode, "controlMode", "client_control_mode", :boolean)
+        ], [relation(:session, "session", :session, :one, :session, nullable: true)])
+      }.freeze
+      private_constant :SCHEMAS
+
+      def self.entity(kind)
+        SCHEMAS.fetch(kind)
+      end
+
+      def self.kinds
+        SCHEMAS.keys.freeze
+      end
+    end
+  end
+end

data/lib/libtmux/child.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "libtmux/process_wait"
+
+module LibTmux
+  module Internal
+    # The native observer never reaps until the I/O owner retires signalling.
+    # Its pipe reports latched state; transport readers and writers stay outside.
+    class OwnedChild
+      attr_reader :pid, :reader
+
+      def initialize(process_wait = ProcessWait.new)
+        @mutex, @changed = Mutex.new, ConditionVariable.new
+        @launched, @retirement = Queue.new, Queue.new
+        @reader, @writer = IO.pipe
+        @reader.binmode
+        @writer.binmode
+        @creator_pid = Process.pid
+        @observer = Thread.new { observe(process_wait) }
+      rescue Exception
+        [@reader, @writer].compact.each { |io| io.close unless io.closed? }
+        raise
+      end
+
+      def spawned(pid)
+        Thread.handle_interrupt(Exception => :never) do
+          @mutex.synchronize do
+            raise ArgumentError, "child ownership was already published" if @published
+
+            @published = true
+            @pid = pid
+          end
+          @launched << pid
+        end
+      end
+
+      def observed?
+        @mutex.synchronize { !!@observed }
+      end
+
+      def observation_error
+        @mutex.synchronize { @observation_error }
+      end
+
+      def retirement_error
+        @mutex.synchronize { @retirement_error }
+      end
+
+      def status
+        @mutex.synchronize { @status }
+      end
+
+      def complete?
+        @mutex.synchronize { !!@complete }
+      end
+
+      def wait_observed(timeout)
+        deadline = clock + timeout
+        @mutex.synchronize do
+          until @observation_complete
+            remaining = deadline - clock
+            return nil unless remaining.positive?
+
+            @changed.wait(@mutex, remaining)
+          end
+          self
+        end
+      end
+
+      def join(timeout)
+        @observer.join(timeout) && self
+      end
+
+      def signal(name)
+        @mutex.synchronize do
+          return nil unless @pid && !@signalling_finished && !@observation_error.is_a?(Errno::ECHILD)
+
+          Process.kill(name, @pid)
+        end
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def finish_signalling
+        Thread.handle_interrupt(Exception => :never) do
+          @mutex.synchronize do
+            return if @signalling_finished
+
+            @signalling_finished = true
+            # Always queue the handoff: observation may fail after the last signal.
+            @retirement << true
+          end
+        end
+      end
+
+      def close
+        @reader.close unless @reader.closed?
+      end
+
+      def detach
+        raise ArgumentError, "only a forked child may detach its observer" if Process.pid == @creator_pid
+
+        [@reader, @writer].each { |io| io.close unless io.closed? }
+      end
+
+      private
+
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def observe(process_wait)
+        Thread.current.report_on_exception = false
+        child = @launched.pop
+        return unless child
+
+        begin
+          process_wait.observe(child)
+          @mutex.synchronize { @observed = true }
+        rescue Exception => failure
+          @mutex.synchronize { @observation_error = failure }
+        ensure
+          @mutex.synchronize do
+            @observation_complete = true
+            @changed.broadcast
+          end
+          notify
+        end
+        @retirement.pop
+        unless observation_error.is_a?(Errno::ECHILD)
+          begin
+            Thread.handle_interrupt(Exception => :never) do
+              status = Process.wait2(child).last
+              @mutex.synchronize { @status = status }
+            end
+          rescue Exception => failure
+            @mutex.synchronize { @retirement_error = failure }
+          end
+        end
+      ensure
+        @mutex.synchronize do
+          @complete = @observation_complete = true
+          @changed.broadcast
+        end
+        notify
+        @writer.close unless @writer.closed?
+      end
+
+      def notify
+        @writer.write_nonblock("x", exception: false)
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+  end
+end