ace-tmux 0.17.5 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47d3f7e66d05f81a0a8a043b082db3e2cd918d9b277b458c34e905c05c143c1e
-  data.tar.gz: b37138140b2c607cf8e34071a0b5735b9be7f8476778f1120478409452288b54
+  metadata.gz: c0536170a8bdb58035764cfe894282b86535192375a8933b85f6900d7a089197
+  data.tar.gz: 898348819cbbd6d92189be96e0d3a29d80b2d8582d66e6f56e544bd604a35ae9
 SHA512:
-  metadata.gz: b06256b52d87757b7e8240b96ee3303250fae755f1f30ae839b97ad4a530c799fa27bd6a3a2e266d9274c992b4de11f9619feda58dd6159c1937474c149fa943
-  data.tar.gz: 4c1f2f7bb03d4bbb3a1527bdd041fda9cb95eb3f1890a29771ffb79a43a0cd421a818298cec3ea0406ebd0087b8a76674e57889e74eae17e9c187a5206fed0a0
+  metadata.gz: b8cb0173511b48a1d99cc18cea00bb0c61fe556228e9cb281f1123cfb798e5fb619c6b94b5c7264576ba53d3c0b4557833c425c523fb9dfda18207994d6d0348
+  data.tar.gz: 240d71c6487b3e81a327c62ac43d169b8530bd5eb4ab34b2dbc8bf0b5c5f733926869fcabc03f3ddc048556a0e392e1c47ba269d6b7e7d9fd09b0d15c88bedee

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-10-05
+
+### Added
+
+- Expose native session/pane/shell identity for managed assignment owner verification.
+
+### Changed
+
+- Declare the required direct dependencies and minimum producer versions for this coordinated release: `ace-runtime ~> 0.2`.
+
+## [0.18.0] - 2026-10-02
+
+### Added
+- Added the `ace-runtime` tmux adapter, exposing window, pane, send, capture, wait, and listing intents through the shared runtime contract while retaining the existing `ace-tmux` control surface.
+
+### Fixed
+- Send adapter message text literally, classify missing pane targets, and use bounded polling plus output settling for agent completion waits.
+- Agent completion waits poll shell panes and any mixed requested states instead of requiring an interactive CLI pane, and `working` now matches immediately in mixed requests.
+- Shell-pane waits accept only after the monotonic deadline, stability timing starts at the first matching observation, unset option reads are distinguished from transport errors, literal send messages terminate option parsing, and pane capture includes the visible screen.
+- Window option reads use the window scope (`-w`) with trimmed values so idempotent `ensure_window` works across calls, shell-pane completion aliases resolve to the observable idle state, and context reporting no longer drops an explicit session when the pane cannot be resolved.
+- Shell-pane agent waits require pane output to hold still before reporting completion, `pane-exited` distinguishes absent panes from failed queries, and the full send key sequence is validated before any transport with ctrl-chord keys supported.
+
 
 ## [0.17.5] - 2026-09-02
 

data/README.md

@@ -36,6 +36,8 @@
 
 **Control tmux through a shared ACE contract** - run `ace-tmux send`, `capture`, `wait`, `attach`, and `detach` when higher-level ACE tools or operators need live pane/session control without re-implementing tmux wrappers.
 
+The `ace-runtime` library can also resolve the tmux adapter with `Ace::Runtime.resolve("tmux")`. It keeps tmux targets and environment resolution inside this gem, and exposes the shared window, pane, send, capture, and wait methods to runtime-neutral callers. A named window is reused when its root and preset match; `prepare_pane` creates a retained shell pane when no prepared live pane exists.
+
 **Compose nested pane layouts in YAML** - use `direction` and nested pane containers to model custom split trees beyond tmux built-in layouts, keeping workspace structure version-controlled alongside your project.
 
 **Reuse presets through config cascade** - load project presets from `.ace/tmux/`, personal presets from `~/.ace/tmux/`, and gem defaults via `.ace-defaults/tmux/` with deep-merge behavior so teams share a baseline while individuals customize.

data/lib/ace/runtime/adapters/tmux.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "ace/tmux"
+
+Ace::Runtime.register(:tmux, -> { Ace::Tmux::RuntimeAdapter.new })

data/lib/ace/tmux/atoms/named_key_registry.rb

@@ -24,9 +24,12 @@ module Ace
           raise Ace::Tmux::ValidationError, "Named key is required" if value.empty?
 
           normalized = KEYS[value.downcase]
-          raise Ace::Tmux::ValidationError, "Unsupported named key: #{key}" unless normalized
+          return normalized if normalized
 
-          normalized
+          chord = value.downcase[/\Ac-([a-z])\z/, 1]
+          return "C-#{chord.upcase}" if chord
+
+          raise Ace::Tmux::ValidationError, "Unsupported named key: #{key}"
         end
       end
     end

data/lib/ace/tmux/atoms/tmux_command_builder.rb

@@ -211,7 +211,9 @@ module Ace
 
         def capture_pane(target, lines: 40, tmux: "tmux")
           start = -Integer(lines.to_i.abs)
-          [tmux, "capture-pane", "-p", "-t", target, "-S", start.to_s, "-E", "-1"]
+          # No -E: capture ends at the visible bottom. -E -1 would stop a
+          # line ABOVE the visible screen and exclude it entirely.
+          [tmux, "capture-pane", "-p", "-t", target, "-S", start.to_s]
         end
 
         def capture_pane_visible(target, start_line:, end_line:, include_alternate: false, tmux: "tmux")

data/lib/ace/tmux/molecules/runtime_target_resolver.rb

@@ -191,13 +191,13 @@ module Ace
         end
 
         def parse_window_identity(line)
-          id, index, name, active = line.to_s.split("\t", 4)
-          return nil if [id, index, name].any? { |value| value.to_s.empty? }
+          id, index, name, active = line.to_s.chomp.split("\t", 4)
+          return nil if [id, index, name].any? { |value| value.to_s.strip.empty? }
 
           {
             id: id,
             index: index,
-            name: name,
+            name: name.to_s.strip,
             active: active == "1"
           }
         end

data/lib/ace/tmux/molecules/tmux_executor.rb

@@ -18,8 +18,10 @@ module Ace
         # @return [ExecutionResult] Result with stdout, stderr, success?
         def capture(cmd)
           stdout, stderr, status = Open3.capture3(*with_socket_target(cmd))
+          # stdout stays raw: pane capture must preserve whitespace and the
+          # trailing newline; parsing callers trim at their own boundary.
           ExecutionResult.new(
-            stdout: stdout.strip,
+            stdout: stdout,
             stderr: stderr.strip,
             success: status.success?,
             exit_code: status.exitstatus

data/lib/ace/tmux/native_runtime_backend.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+module Ace
+  module Tmux
+    # Maps runtime intents onto the existing tmux executor and control surface.
+    class NativeRuntimeBackend
+      B = Atoms::TmuxCommandBuilder
+      # tmux target errors are phrased can't-find/unknown-target; bare "no
+      # such" also matches socket connection failures and must not classify
+      # as a missing target.
+      TARGET_ERROR_PATTERN = /can't find|unknown target|not found/i
+      WINDOW_FORMAT = Organisms::ControlSurface::WINDOW_LIST_FORMAT
+      PANE_FORMAT = Organisms::ControlSurface::PANE_LIST_FORMAT
+
+      def initialize(executor: Molecules::TmuxExecutor.new, env: ENV, tmux: "tmux", surface: nil)
+        @executor = executor
+        @env = env
+        @tmux = tmux
+        @resolver = Molecules::RuntimeTargetResolver.new(executor: executor, tmux: tmux, env: env)
+        @surface = surface || Organisms::ControlSurface.new(executor: executor, resolver: @resolver, tmux: tmux)
+      end
+
+      def context
+        present = !env["TMUX"].to_s.empty? || !env["ACE_TMUX_SESSION"].to_s.empty?
+        return {in_runtime: false, session: nil, window: nil, pane: nil} unless present
+
+        session = resolver.resolve_session.session
+        window = context_window(session)
+        pane = context_pane(session, window)
+        {in_runtime: true, session: session, window: window, pane: pane}
+      rescue Ace::Tmux::TargetResolutionError
+        {in_runtime: false, session: nil, window: nil, pane: nil}
+      end
+
+      def process_target(pane)
+        value = query(B.display_message_target(pane, "\#{session_id}\t\#{pane_id}\t\#{pane_pid}", tmux: tmux))
+        session, id, pid = value.split("\t", -1)
+        return nil unless session.to_s.match?(/\A\$[0-9]+\z/) && id.to_s.match?(/\A%[0-9]+\z/) &&
+          pid.to_s.match?(/\A[0-9]+\z/)
+
+        {"session" => session, "pane" => id, "shell_pid" => pid.to_i}
+      end
+
+      def available!
+        raise Ace::Tmux::NotInTmuxError unless executor.tmux_available?(tmux: tmux)
+
+        resolver.resolve_session
+        true
+      end
+
+      def window_info(name)
+        entry = windows.find { |window| window[:name] == name || window[:id] == name }
+        return nil unless entry
+
+        root = option(entry[:id], "@ace_runtime_root")
+        root ||= query(B.display_message_target(entry[:id], "\#{pane_current_path}", tmux: tmux))
+        preset = option(entry[:id], "@ace_runtime_preset")
+        {id: entry[:id], root: root, preset: preset}
+      end
+
+      def create_window(name:, root:, preset: nil)
+        session = resolver.resolve_session.session
+        if preset
+          loader = Molecules::PresetLoader.new(gem_root: Ace::Tmux.gem_root)
+          builder = Molecules::SessionBuilder.new(preset_loader: loader)
+          begin
+            Organisms::WindowManager.new(executor: executor, session_builder: builder, tmux: tmux)
+              .add_window(preset, session: session, root: root, name: name)
+          rescue Ace::Tmux::Error
+            raise
+          rescue StandardError => e
+            raise Ace::Tmux::Error, "preset window creation failed: #{e.message}"
+          end
+          id = window_info(name)[:id]
+        else
+          id = query(B.new_window(session, name: name, root: root, print_format: "\#{window_id}", tmux: tmux))
+        end
+        run!(B.set_window_option(id, "@ace_runtime_root", File.expand_path(root), tmux: tmux))
+        run!(B.set_window_option(id, "@ace_runtime_preset", preset, tmux: tmux)) if preset
+        id
+      end
+
+      def panes_for(window)
+        target = resolve_window!(window)
+        result = executor.capture(B.list_panes(target, format: PANE_FORMAT, tmux: tmux))
+        unless result.success?
+          detail = result.stderr.to_s
+          raise Ace::Tmux::TargetResolutionError, "tmux target is unavailable" if detail.match?(TARGET_ERROR_PATTERN)
+
+          raise Ace::Tmux::Error, detail
+        end
+        result.stdout.lines.filter_map do |line|
+          parts = line.chomp.split("\t", -1)
+          next unless parts.length == 9
+
+          pane = parts[1]
+          {pane: pane, keep_alive: option(pane, "@ace_runtime_prepared", pane: true) == "1",
+           alive: query(B.display_message_target(pane, "\#{pane_dead}", tmux: tmux)) != "1"}
+        end
+      end
+
+      def split_window(window)
+        target = resolve_window!(window)
+        query(B.split_window(target, root: window_info(window)[:root], print_format: "\#{pane_id}", tmux: tmux))
+      end
+
+      def set_keep_alive(pane, value)
+        run!(B.set_pane_option(pane, "remain-on-exit", value ? "on" : "off", tmux: tmux))
+        run!(B.set_pane_option(pane, "@ace_runtime_prepared", value ? "1" : "0", tmux: tmux))
+      end
+
+      def focus_window(window)
+        run!(B.select_window(resolve_window!(window), tmux: tmux))
+      end
+
+      def write_text(pane, text)
+        # -- terminates option parsing so messages starting with "-" are
+        # delivered literally.
+        run!([tmux, "send-keys", "-l", "-t", pane, "--", text])
+        @pending_text_pane = pane
+      end
+
+      def press_key(pane, key)
+        if @pending_text_pane == pane && Atoms::NamedKeyRegistry.normalize(key) == "Enter"
+          profile = surface.send(:fetch_pane_profile, pane)
+          sleep(Organisms::ControlSurface::INTERACTIVE_SUBMIT_DELAY) if profile[:interactive_cli]
+        end
+        normalized = Atoms::NamedKeyRegistry.normalize(key)
+        run!(B.send_raw_keys(pane, normalized, tmux: tmux))
+        @pending_text_pane = nil
+      end
+
+      def capture_output(pane, lines:)
+        surface.capture_recent_output(pane: pane, lines: lines)
+      rescue Ace::Tmux::Error
+        raise Ace::Tmux::TargetResolutionError, "tmux target is unavailable" unless pane_exists?(pane)
+
+        raise
+      end
+
+      def agent_state(pane)
+        agent_state_from_output(capture_output(pane, lines: 40))
+      end
+
+      def agent_state_from_output(output)
+        busy = Organisms::ControlSurface::INTERACTIVE_BUSY_PATTERNS.any? { |pattern| output.match?(pattern) }
+        busy ? "working" : "idle"
+      end
+
+      def wait_agent(pane:, states:, timeout:)
+        desired = Array(states).map(&:to_s)
+        completion_states = %w[idle done working-done ready]
+        supported_states = completion_states + ["working"]
+        if desired.empty? || (desired - supported_states).any?
+          raise ArgumentError, "agent states must be one or more of: #{supported_states.join(", ")}"
+        end
+
+        interval = (timeout.to_f / 5).clamp(0.02, 0.2)
+        # The stability+settle completion wait only supports interactive CLI
+        # panes and only observes completion. Shell panes and any requested
+        # "working" state must poll the observed state instead. Shell panes
+        # only ever observe idle/working, so completion aliases read as idle.
+        if (desired - completion_states).empty? && interactive_cli_pane?(pane)
+          return surface.wait_for_condition(
+            condition: "agent", pane: pane, timeout: timeout,
+            interval: interval,
+            settle: [timeout.to_f / 2, 1.0].min
+          )
+        end
+
+        # Shell panes only ever observe idle/working, so completion
+        # aliases read as idle.
+        observable = desired.flat_map { |state| %w[idle working].include?(state) ? [state] : %w[idle] }.uniq
+        poll_agent_states(pane, observable, interval: interval, timeout: timeout)
+      end
+
+      def validate_key!(key)
+        Atoms::NamedKeyRegistry.normalize(key)
+      rescue Ace::Tmux::ValidationError => e
+        raise Ace::Runtime::SendRejectedError, e.message
+      end
+
+      def lifecycle?(condition, target)
+        case condition
+        when "window-exists" then !window_info(target).nil?
+        when "window-active" then windows.any? { |entry| (entry[:name] == target || entry[:id] == target) && entry[:active] }
+        when "pane-exists" then pane_exists?(target)
+        when "pane-exited" then pane_exited?(target)
+        end
+      end
+
+      def kill_window(window)
+        run!([tmux, "kill-window", "-t", resolve_window!(window)])
+      end
+
+      def windows
+        session = resolver.resolve_session.session
+        output = query(B.list_windows(session, format: WINDOW_FORMAT, tmux: tmux))
+        output.lines.filter_map do |line|
+          active, id, _session, _index, name, _panes = line.chomp.split("\t", 6)
+          {name: name, id: id, active: active == "1"} if id && name
+        end
+      end
+
+      private
+
+      attr_reader :executor, :env, :tmux, :resolver, :surface
+
+      def interactive_cli_pane?(pane)
+        surface.send(:fetch_pane_profile, pane)[:interactive_cli]
+      rescue Ace::Tmux::Error
+        false
+      end
+
+      # Shell-pane wait: a working observation matches immediately; a
+      # completion observation only counts once pane output has held
+      # still for the settle window (the documented output-stability
+      # heuristic) so a running command never reads as done.
+      def poll_agent_states(pane, observable, interval:, timeout:)
+        settle = [timeout.to_f / 2, 1.0].min
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout.to_f
+        current_output = capture_output(pane, lines: 40)
+        stable_since = nil
+        loop do
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          state = agent_state_from_output(current_output)
+          if observable.include?(state)
+            return true if state == "working" && now < deadline
+
+            stable_since ||= now
+            return true if now < deadline && now - stable_since >= settle
+          else
+            stable_since = nil
+          end
+          raise Ace::Tmux::WaitTimeoutError if now >= deadline
+
+          sleep(interval)
+          fresh_output = capture_output(pane, lines: 40)
+          stable_since = nil if fresh_output != current_output
+          current_output = fresh_output
+        end
+      end
+
+      # Pane absence and a dead pane both satisfy the pane-exited
+      # observation; any other query failure is a runtime error, never
+      # silent evidence of exit.
+      def pane_exited?(target)
+        result = executor.capture(B.display_message_target(target, "\#{pane_dead}", tmux: tmux))
+        return true if !result.success? && result.stderr.to_s.match?(TARGET_ERROR_PATTERN)
+        raise Ace::Tmux::Error, result.stderr.to_s unless result.success?
+
+        result.stdout.to_s.strip == "1"
+      end
+
+      # A missing pane must not erase an explicitly available session or
+      # window from the reported context.
+      def context_window(session)
+        return nil if env["TMUX"].to_s.empty? && env["ACE_TMUX_WINDOW"].to_s.empty?
+
+        resolver.resolve_window(session: session).window
+      rescue Ace::Tmux::TargetResolutionError
+        nil
+      end
+
+      def context_pane(session, window)
+        return nil unless window
+
+        resolver.resolve_pane(session: session, window: window).pane_target
+      rescue Ace::Tmux::TargetResolutionError
+        nil
+      end
+
+      def pane_exists?(pane)
+        result = executor.capture(B.display_message_target(pane, "\#{pane_id}", tmux: tmux))
+        return false if !result.success? && result.stderr.to_s.match?(TARGET_ERROR_PATTERN)
+        raise Ace::Tmux::Error, result.stderr.to_s unless result.success?
+
+        !result.stdout.to_s.strip.empty?
+      end
+
+      def resolve_window!(window)
+        info = window_info(window)
+        raise Ace::Tmux::TargetResolutionError, "window target is unavailable" unless info
+
+        info[:id]
+      end
+
+      def option(target, name, pane: false)
+        command = [tmux, "show-options", "-v"]
+        command << "-p" if pane
+        # Runtime window marks live in the window scope; without -w tmux
+        # reports the option as unset and idempotency checks conflict.
+        command << "-w" unless pane
+        result = executor.capture(command + ["-t", target, name])
+        if result.success?
+          value = result.stdout.to_s.strip
+          value.empty? ? nil : value
+        else
+          detail = result.stderr.to_s
+          raise Ace::Tmux::TargetResolutionError, "tmux target is unavailable" if detail.match?(TARGET_ERROR_PATTERN)
+          # tmux exits non-zero for an unset option — with quiet output or
+          # "invalid option: NAME" for unset user options.
+          return nil if detail.strip.empty? || detail.match?(/invalid option/i)
+
+          raise Ace::Tmux::Error, detail
+        end
+      end
+
+      def query(command)
+        result = executor.capture(command)
+        unless result.success?
+          detail = result.stderr.to_s
+          raise Ace::Tmux::TargetResolutionError, "tmux target is unavailable" if detail.match?(TARGET_ERROR_PATTERN)
+
+          raise Ace::Tmux::Error, detail
+        end
+
+        result.stdout.to_s.strip
+      end
+
+      def run!(command)
+        result = executor.capture(command)
+        unless result.success?
+          detail = result.stderr.to_s
+          raise Ace::Tmux::TargetResolutionError, "tmux target is unavailable" if detail.match?(TARGET_ERROR_PATTERN)
+
+          raise Ace::Tmux::Error, detail
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/ace/tmux/organisms/control_surface.rb

@@ -235,7 +235,7 @@ module Ace
           result = executor.capture(
             Atoms::TmuxCommandBuilder.display_message_target(target.pane_target, '#{pane_dead}', tmux: tmux)
           )
-          !result.success? || result.stdout == "1"
+          !result.success? || result.stdout.to_s.strip == "1"
         rescue Ace::Tmux::TargetResolutionError
           true
         end

data/lib/ace/tmux/organisms/window_manager.rb

@@ -76,7 +76,7 @@ module Ace
 
           cmd = Atoms::TmuxCommandBuilder.display_message("#S", tmux: @tmux)
           result = @executor.capture(cmd)
-          result.success? ? result.stdout : nil
+          result.success? ? result.stdout.to_s.strip : nil
         end
 
         def setup_panes(window, window_target, base_root = nil)

data/lib/ace/tmux/runtime_adapter.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Ace
+  module Tmux
+    # Runtime-neutral intent surface backed by ace-tmux's existing control API.
+    class RuntimeAdapter
+      SEND = Ace::Runtime::Atoms::SendContract
+      LIFECYCLE = SEND::LIFECYCLE_CONDITIONS
+
+      def initialize(backend: NativeRuntimeBackend.new, process_identity: Ace::Runtime::Molecules::ProcessIdentity.new)
+        @backend = backend
+        @process_identity = process_identity
+      end
+
+      def send_profile = :plain_pane
+
+      def context
+        backend.context
+      end
+
+      def process_binding(pane:, caller_pid:)
+        return nil unless caller_pid.is_a?(Integer) && caller_pid.positive?
+
+        with_errors do
+          target = backend.process_target(pane)
+          next nil unless target
+
+          owner = @process_identity.owner(shell_pid: target["shell_pid"], caller_pid: caller_pid)
+          next nil unless owner
+
+          target.slice("session", "pane").merge("runtime" => "tmux").merge(owner)
+        end
+      end
+
+      def ensure_window(name:, root:, preset: nil)
+        with_errors do
+          backend.available!
+          normalized = Ace::Runtime.sanitize_name(name)
+          existing = backend.window_info(normalized)
+          if existing
+            if File.expand_path(existing[:root]) != File.expand_path(root) || existing[:preset] != preset
+              raise Ace::Runtime::WindowConflictError, "window '#{normalized}' has a different root or preset"
+            end
+            return existing[:id]
+          end
+
+          backend.create_window(name: normalized, root: root, preset: preset)
+        end
+      end
+
+      def prepare_pane(window:)
+        with_errors do
+          backend.available!
+          raise Ace::Runtime::TargetNotFoundError, "window is unavailable" unless backend.window_info(window)
+
+          reusable = backend.panes_for(window).find { |pane| pane[:keep_alive] && pane[:alive] }
+          return reusable[:pane] if reusable
+
+          pane = backend.split_window(window)
+          backend.set_keep_alive(pane, true)
+          pane
+        end
+      end
+
+      def focus(window:)
+        with_errors { backend.focus_window(window) }
+      end
+
+      def send(pane:, command: nil, items: [])
+        request = SEND.normalize!(command: command, items: items, profile: send_profile)
+        # Validate the whole key sequence before any transport call so a
+        # rejected key can never leave a partially delivered submission.
+        request.items.each { |item| backend.validate_key!(item[:key]) if item.key?(:key) }
+        with_errors do
+          backend.available!
+          if request.command
+            backend.write_text(pane, request.command)
+            backend.press_key(pane, "Enter")
+          end
+          request.items.each do |item|
+            if item.key?(:message)
+              backend.write_text(pane, item[:message])
+            else
+              backend.press_key(pane, item[:key])
+            end
+          end
+          SEND::Result.new(dropped_trailing_enter: false)
+        end
+      end
+
+      def send_command(pane:, command:) = send(pane: pane, command: command)
+      def send_text(pane:, text:) = send(pane: pane, items: [{message: text}])
+      def send_keys(pane:, keys:) = send(pane: pane, items: Array(keys).map { |key| {key: key} })
+
+      def capture(pane:, lines: 40)
+        with_errors { backend.capture_output(pane, lines: lines) }
+      end
+
+      def wait_output(pane:, pattern:, timeout:)
+        raise ArgumentError, "pattern must be present" if pattern.nil? || pattern.to_s.empty?
+
+        wait_until(condition: "output", target: pane, timeout: timeout) do
+          backend.capture_output(pane, lines: 40).include?(pattern.to_s)
+        end
+      end
+
+      def wait_agent(pane:, states:, timeout:)
+        desired = Array(states).map(&:to_s)
+        if backend.respond_to?(:wait_agent)
+          return with_errors do
+            backend.available!
+            backend.wait_agent(pane: pane, states: desired, timeout: timeout)
+          end
+        end
+
+        wait_until(condition: "agent", target: pane, timeout: timeout) do
+          desired.include?(backend.agent_state(pane).to_s)
+        end
+      rescue Ace::Tmux::WaitTimeoutError
+        raise Ace::Runtime::WaitTimeoutError.new(condition: "agent", target: pane, timeout: timeout)
+      end
+
+      def wait_lifecycle(condition:, target:, timeout:)
+        unless LIFECYCLE.include?(condition.to_s)
+          raise ArgumentError, "lifecycle condition must be one of: #{LIFECYCLE.join(", ")}"
+        end
+
+        wait_until(condition: condition, target: target, timeout: timeout) do
+          backend.lifecycle?(condition.to_s, target)
+        end
+      end
+
+      def close_window(window:)
+        with_errors { backend.kill_window(window) }
+      end
+
+      def list_windows
+        with_errors { backend.windows }
+      end
+
+      def list_panes(window:)
+        with_errors do
+          backend.available!
+          next [] unless backend.window_info(window)
+
+          backend.panes_for(window).map { |entry| {pane: entry[:pane]} }
+        end
+      end
+
+      private
+
+      attr_reader :backend
+
+      def wait_until(condition:, target:, timeout:)
+        duration = Float(timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + duration
+        loop do
+          observed = with_errors do
+            backend.available!
+            yield
+          end
+          # The clock is read after the observation so a slow observation
+          # cannot accept a match that completed past the deadline.
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return true if observed && now < deadline
+          break if now >= deadline
+
+          sleep([0.02, duration].min)
+        end
+        raise Ace::Runtime::WaitTimeoutError.new(condition: condition, target: target, timeout: timeout)
+      end
+
+      def with_errors
+        yield
+      rescue Ace::Runtime::Error
+        raise
+      rescue Errno::ENOENT, Ace::Tmux::NotInTmuxError
+        raise Ace::Runtime::RuntimeUnavailableError, "tmux runtime is unavailable"
+      rescue Ace::Tmux::TargetResolutionError
+        raise Ace::Runtime::TargetNotFoundError, "tmux target is unavailable"
+      rescue Ace::Tmux::WaitTimeoutError
+        raise
+      rescue Ace::Tmux::Error
+        raise Ace::Runtime::RuntimeUnavailableError, "tmux runtime is unavailable"
+      rescue => e
+        raise backend.translate_error(e) if backend.respond_to?(:translate_error)
+
+        raise
+      end
+    end
+  end
+end

data/lib/ace/tmux/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Tmux
-    VERSION = "0.17.5"
+    VERSION = "0.19.0"
   end
 end

data/lib/ace/tmux.rb

@@ -2,6 +2,7 @@
 
 require_relative "tmux/version"
 require "ace/support/config"
+require "ace/runtime"
 
 # Define error hierarchy before loading components (they reference these classes)
 module Ace
@@ -41,6 +42,8 @@ require_relative "tmux/molecules/wait_condition_validator"
 require_relative "tmux/organisms/control_surface"
 require_relative "tmux/organisms/session_manager"
 require_relative "tmux/organisms/window_manager"
+require_relative "tmux/native_runtime_backend"
+require_relative "tmux/runtime_adapter"
 require_relative "tmux/cli"
 
 module Ace

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-tmux
 version: !ruby/object:Gem::Version
-  version: 0.17.5
+  version: 0.19.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: ace-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: ace-support-test-helpers
   requirement: !ruby/object:Gem::Requirement
@@ -178,6 +192,7 @@ files:
 - docs/handbook.md
 - docs/usage.md
 - exe/ace-tmux
+- lib/ace/runtime/adapters/tmux.rb
 - lib/ace/tmux.rb
 - lib/ace/tmux/atoms/layout_string_builder.rb
 - lib/ace/tmux/atoms/named_key_registry.rb
@@ -206,9 +221,11 @@ files:
 - lib/ace/tmux/molecules/session_builder.rb
 - lib/ace/tmux/molecules/tmux_executor.rb
 - lib/ace/tmux/molecules/wait_condition_validator.rb
+- lib/ace/tmux/native_runtime_backend.rb
 - lib/ace/tmux/organisms/control_surface.rb
 - lib/ace/tmux/organisms/session_manager.rb
 - lib/ace/tmux/organisms/window_manager.rb
+- lib/ace/tmux/runtime_adapter.rb
 - lib/ace/tmux/version.rb
 homepage: https://github.com/cs3b/ace
 licenses: