ace-herdr 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11805892b3ae5bdf74d4bdd555f8e508e7fe3693476d07fa537a41b9f891857e
-  data.tar.gz: 2aa907e23b109838153215ac004f344045220d2c77cf0f295a99c6ff55a75cb2
+  metadata.gz: 7bf428cc5ca891abf1fc4214e10301ab30e50ca66b2cc122f14512152437b0e8
+  data.tar.gz: f43847a527924ee7f2b2ba7266f47c18f741a04e012aef255cebfb121c05ad1d
 SHA512:
-  metadata.gz: 53e2cbd3f3c97db17b5e14609e54deb210e0d7474886dc4f6fe7d78a33154df1cb7fe680a565aa500d534c0ce06235dd20445f9ae6bb867d5b989732c5a5fa70
-  data.tar.gz: 9397dfe3b7fb8ac0d9b42f2a43ad7ac56204c7b70197e5f1a6095a00f62f38ecb8d7a0967ca0ab5d68c91864656c86db25a9cc9bc0274fa65c63d74216771e09
+  metadata.gz: 83223ba775d983ce92b32031a0e13d99d33cf9c95f2e8067816933051f0dfca77388c65241115e67eaf2d101d2c648cc72af134355a582b8b4e523bf4e2799c9
+  data.tar.gz: 5f8dc827d8cad595d2821442386247c764ac7913c6d8371f19621a7f633db824a271a0791f8556bc9359da821f3fcd8cf6358eb12769befdd4ecbc33d4a25103

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to `ace-herdr` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.2.0] - 2026-10-02
+
+### Added
+- `Ace::Herdr::Organisms::RuntimeAdapter` and the lazy `ace/runtime/adapters/herdr` entrypoint implement the shared ace-runtime intent contract. It preserves native agent prompt and wait semantics, polls all four lifecycle observations, and maps Herdr failures to contract errors. Native tab and pane probes support context, focus, and retained pane preparation. The packaged shared adapter contract suite runs against a Herdr-shaped fake executor.
+
 ## [0.1.0] - 2026-09-27
 
 ### Added

data/README.md

@@ -32,6 +32,7 @@
 - Dispatch a subagent in one command with deterministic defaults and no LLM decisions.
 - Wait for agent readiness or completion without scraping pane noise.
 - Close out finished agent panes (rename/close) and return their result.
+- Use Herdr through the shared `ace-runtime` Ruby intent API, with workspace/session and tab/window mapping handled by the adapter.
 
 ## Installation
 

data/docs/usage.md

@@ -3,8 +3,8 @@ doc-type: user
 title: ace-herdr Usage
 purpose: Full CLI and configuration reference for ace-herdr: push delivery, agent bootstrap, the terminal-control surface (list, send, capture, wait, presets), and tidy cleanup.
 ace-docs:
-  last-updated: 2026-09-28
-  last-checked: 2026-09-28
+  last-updated: 2026-10-02
+  last-checked: 2026-10-02
 ---
 
 # Usage
@@ -31,6 +31,16 @@ Control commands print exactly one deterministic JSON line on stdout; `--quiet`
 
 herdr *sessions* (server persistence) are intentionally not exposed; the tmux session analogue is the herdr **workspace**.
 
+## ace-runtime adapter
+
+Install `ace-herdr` alongside `ace-runtime`, then resolve the adapter with `Ace::Runtime.resolve("herdr")`. The contract's `session` is a Herdr **workspace**, `window` is a **tab**, and `pane` is an opaque Herdr pane ID. The adapter does not construct pane IDs. It locates the caller through `HERDR_SESSION` and `HERDR_PANE` and reads the explicit pane with `pane get`; the pane's native workspace is authoritative and a conflicting `HERDR_WORKSPACE_ID` hint is rejected instead of honored. Outside Herdr, `context` reports `in_runtime: false`; operations requiring a caller workspace raise `Ace::Runtime::RuntimeUnavailableError`.
+
+The adapter implements `context`, `ensure_window`, `prepare_pane`, `focus`, ordered `send` and its convenience methods, `capture`, `wait_output`, `wait_agent`, `wait_lifecycle`, `close_window`, `list_windows`, and `list_panes`. `ensure_window` scopes the sanitized tab label to the caller workspace. It records the tab's root, preset, and prepared pane under `~/.ace/local/herdr/runtime-tabs/` — keyed by workspace and label, so adapter instances from any working directory or requested root share one record, create through the same lock, and serialize prepared-pane creation through it. Later instances verify an idempotent request and reject a conflicting one; a tab whose ownership cannot be proven is never closed or replaced (a failed create rolls back only tabs the same attempt created). `prepare_pane` splits a retained shell target and returns the native pane ID after verifying it exists and has a shell process.
+
+Sends probe for a live agent. Plain panes receive raw text and keys in order; agent panes receive one self-submitting `agent prompt`, with one trailing Enter dropped and reported. Agent waits use native `agent wait` states (`idle`, `working`, `blocked`, `done`). Contract timeout values are seconds and are converted to Herdr milliseconds. Lifecycle waits observe `tab get`, focused tab state, `pane get`, and `pane process-info`; a missing pane keeps `pane-exists` waiting but immediately satisfies `pane-exited`. A pane with only its retained shell also satisfies `pane-exited` because no submitted foreground command remains. This observation does not prove assignment success or authorize cleanup.
+
+Native `agent_blocked` becomes `SendRejectedError`; `agent_prompt_stalled` becomes `SendStalledError` and must not be automatically resent. Native wait timeouts become `WaitTimeoutError`, missing targets become `TargetNotFoundError`, and an unavailable binary or socket becomes `RuntimeUnavailableError`.
+
 ## tmux-intent ↔ herdr-command parity
 
 Every common terminal-control intent available through `ace-tmux` is available through `ace-herdr` (herdr 0.9.1). Parity is of INTENT and FLAG VOCABULARY, not byte-format: ace-herdr keeps one-line JSON where ace-tmux renders human tables.

data/lib/ace/herdr/atoms/json_find.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ace
+  module Herdr
+    module Atoms
+      # Shared recursive extraction from herdr's native JSON responses
+      # (ids nest under result.*; native shapes vary slightly between
+      # commands). Pure functions — no side effects.
+      module JsonFind
+        module_function
+
+        # Walk a path of hash keys; nil unless every hop is a Hash. A hop
+        # resolves only to a non-empty String.
+        def dig_value(json, path)
+          current = json
+          path.each do |key|
+            return nil unless current.is_a?(Hash)
+
+            current = current[key]
+          end
+          current.is_a?(String) && !current.empty? ? current : nil
+        end
+
+        # Depth-first search for the first non-empty String under any of
+        # the given keys (tolerant extraction of ids from native shapes).
+        def find_value(json, keys)
+          case json
+          when Hash
+            keys.each { |key| return json[key] if json[key].is_a?(String) && !json[key].empty? }
+            json.each_value do |value|
+              found = find_value(value, keys)
+              return found if found
+            end
+            nil
+          when Array
+            json.each do |value|
+              found = find_value(value, keys)
+              return found if found
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/errors.rb

@@ -22,6 +22,9 @@ module Ace
       end
     end
 
+    # Native timeout is distinct from a prompt accepted but not observed.
+    class ExecutorTimeoutError < AgentNotReadyError; end
+
     # Target pane does not exist (pane_not_found)
     class PaneNotFoundError < ExecutorError; end
 

data/lib/ace/herdr/molecules/herdr_executor.rb

@@ -60,6 +60,10 @@ module Ace
           run!([@binary, "pane", "current", "--current"])
         end
 
+        def pane_get(pane)
+          run!([@binary, "pane", "get", pane])
+        end
+
         # Inspect a pane's processes (positive proof of process exit for tidy)
         def pane_process_info(pane)
           run!([@binary, "pane", "process-info", "--pane", pane])
@@ -73,6 +77,18 @@ module Ace
           run!(cmd)
         end
 
+        def tab_get(tab)
+          run!([@binary, "tab", "get", tab])
+        end
+
+        def tab_focus(tab)
+          run!([@binary, "tab", "focus", tab])
+        end
+
+        def api_snapshot
+          run!([@binary, "api", "snapshot"])
+        end
+
         # --- terminal-control surface (spec 8wq.t.k84) -----------------------
 
         # List workspaces (tmux sessions analogue)
@@ -200,6 +216,25 @@ module Ace
         # code is kept in the message so CLI failures carry it.
         def classify(result, cmd)
           code, message = error_code(result)
+          if code
+            return classify_code(code, message, result: result, cmd: cmd)
+          end
+
+          # No structured code: first nonempty of stderr/stdout — herdr
+          # writes some failures (socket errors) to stdout with an empty
+          # stderr, and empty strings are truthy in Ruby, so `||` chaining
+          # would hide the detail.
+          detail = [result.stderr, result.stdout].reject { |value| value.to_s.empty? }.first
+          if detail.to_s.match?(/no herdr server is running|cannot connect|connection refused|socket.*unavailable/i)
+            return ExecutorUnavailableError.new(detail)
+          end
+
+          CommandError.new(
+            "herdr command failed (exit #{result.exit_code}): #{cmd.join(" ")} #{detail}".strip
+          )
+        end
+
+        def classify_code(code, message, result:, cmd:)
           case code
           when "agent_blocked" then AgentBlockedError.new(tag_code(code, message))
           when "agent_prompt_stalled" then AgentNotReadyError.new(tag_code(code, message))
@@ -207,11 +242,10 @@ module Ace
           when "agent_not_found" then AgentNotFoundError.new(tag_code(code, message))
           when "tab_not_found" then TabNotFoundError.new(tag_code(code, message))
           when "workspace_not_found" then WorkspaceNotFoundError.new(tag_code(code, message))
-          when "timeout" then AgentNotReadyError.new(tag_code(code, message))
+          when "timeout" then ExecutorTimeoutError.new(tag_code(code, message))
           else
             CommandError.new(
-              "herdr command failed (exit #{result.exit_code}): #{cmd.join(" ")} " \
-              "#{message || result.stderr}".strip
+              "herdr command failed (exit #{result.exit_code}): #{cmd.join(" ")}: #{tag_code(code, message)}"
             )
           end
         end

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

@@ -146,9 +146,10 @@ module Ace
         # Create a tab from a preset (tmux `window` analogue) in the given
         # or resolved workspace; --cwd overrides the resolved tab cwd. The
         # layout is validated before the tab is created.
-        def create_tab(preset_name, workspace_id: nil, cwd: nil)
+        def create_tab(preset_name, workspace_id: nil, cwd: nil, label: nil)
           workspace_id = resolve_workspace_id(workspace_id)
           resolved = resolve_tab_preset(preset_name)
+          resolved = resolved.merge("label" => label) if label
           preflight_tab!(resolved)
           instantiate_tab(
             resolved, workspace_id: workspace_id,
@@ -248,13 +249,20 @@ module Ace
           tab_id = dig_value(tab_json, %w[result tab tab_id]) ||
             raise(TargetResolutionError, "could not read the new tab id from herdr tab create output")
 
-          pane_specs = Array(tab_spec["panes"])
-          root_pane_id = dig_value(tab_json, %w[result root_pane pane_id]) ||
-            raise(TargetResolutionError, "could not read the root pane id from herdr tab create output")
-          placed = place_panes(tab_spec, pane_specs, tab_cwd, root_pane_id)
-
-          commands = run_pane_commands(placed)
-          agents = start_pane_agents(placed, workspace_id: workspace_id)
+          begin
+            pane_specs = Array(tab_spec["panes"])
+            root_pane_id = dig_value(tab_json, %w[result root_pane pane_id]) ||
+              raise(TargetResolutionError, "could not read the root pane id from herdr tab create output")
+            placed = place_panes(tab_spec, pane_specs, tab_cwd, root_pane_id)
+
+            commands = run_pane_commands(placed)
+            agents = start_pane_agents(placed, workspace_id: workspace_id)
+          rescue StandardError => e
+            # Surface the created tab id and the original error class so
+            # the owner can roll back exactly this tab and keep
+            # mapping-relevant semantics (e.g. AgentBlockedError).
+            raise TabMaterializationError.new(tab_id: tab_id, message: "#{e.class}: #{e.message}")
+          end
 
           {
             tab: tab_id,
@@ -386,33 +394,13 @@ module Ace
         end
 
         def dig_value(json, path)
-          current = json
-          path.each do |key|
-            return nil unless current.is_a?(Hash)
-
-            current = current[key]
-          end
-          current.is_a?(String) && !current.empty? ? current : nil
+          Atoms::JsonFind.dig_value(json, path)
         end
 
-        # Recursive search mirroring the Dispatcher's tolerant extraction of
-        # ids from native responses (native shapes nest under result.*)
+        # Tolerant extraction of ids from native responses (native shapes
+        # nest under result.*); shared atom, same semantics as Dispatcher.
         def find_value(json, keys)
-          case json
-          when Hash
-            keys.each { |key| return json[key] if json[key].is_a?(String) && !json[key].empty? }
-            json.each_value do |value|
-              found = find_value(value, keys)
-              return found if found
-            end
-            nil
-          when Array
-            json.each do |value|
-              found = find_value(value, keys)
-              return found if found
-            end
-            nil
-          end
+          Atoms::JsonFind.find_value(json, keys)
         end
 
         # --- send: validation -------------------------------------------------

data/lib/ace/herdr/organisms/runtime_adapter.rb

@@ -0,0 +1,555 @@
+# frozen_string_literal: true
+
+require "ace/runtime"
+require "digest"
+require "fileutils"
+require "json"
+
+module Ace
+  module Herdr
+    module Organisms
+      # Maps ace-runtime's terminal intents onto herdr's workspace/tab/pane API.
+      # Contract session means workspace; contract window means tab.
+      class RuntimeAdapter
+        POLL_INTERVAL = 0.02
+
+        def initialize(executor: Molecules::HerdrExecutor.new, env: ENV, clock: Process, sleeper: Kernel, surface: nil,
+          identity_dir: nil, poll_interval: POLL_INTERVAL)
+          @executor = executor
+          @env = env
+          @clock = clock
+          @sleeper = sleeper
+          @surface = surface || ControlSurface.new(executor: executor)
+          @prepared = {}
+          @identity_dir = identity_dir
+          @poll_interval = poll_interval
+        end
+
+        def context
+          return {in_runtime: false, session: nil, window: nil, pane: nil} unless inside?
+
+          with_errors do
+            current = @executor.pane_get(@env["HERDR_PANE"]).parsed_json
+            native_workspace = find_value(current, %w[workspace_id workspaceId])
+            hint = @env["HERDR_WORKSPACE_ID"]
+            if hint && native_workspace && hint != native_workspace
+              raise Runtime::RuntimeUnavailableError,
+                "HERDR_WORKSPACE_ID '#{hint}' does not match the caller pane's workspace " \
+                "'#{native_workspace}'; clear the hint or reconnect the pane"
+            end
+
+            {
+              in_runtime: true,
+              session: native_workspace || hint,
+              window: find_value(current, %w[tab_id tabId]),
+              pane: @env["HERDR_PANE"] || find_value(current, %w[pane_id paneId])
+            }
+          end
+        end
+
+        def ensure_window(name:, root:, preset: nil)
+          with_errors do
+            workspace = workspace_id!
+            label = Runtime.sanitize_name(name)
+            with_identity_lock(workspace, label) do
+              path = identity_path(workspace, label)
+              existing = tabs(workspace).find { |tab| tab[:name] == label }
+              if existing
+                # Ownership must be proven by the record (or, without one,
+                # by the pane's native root for a preset-free request); a
+                # tab we cannot verify is never closed or replaced.
+                unless verifiable_identity?(existing, root: root, preset: preset, path: path)
+                  raise Runtime::WindowConflictError,
+                    "window '#{existing[:name]}' conflicts with root or preset"
+                end
+
+                # Adopting a record-less tab: persist its provenance (and
+                # keep any prepared-pane pointer) so later instances share it.
+                if read_identity(path, existing).nil?
+                  write_identity(path, id: existing[:id], root: canonical_root(root), preset: preset,
+                    prepared_pane: pointer_prepared_pane(path, existing[:id]))
+                end
+                next existing[:id]
+              end
+
+              created_id =
+                if preset
+                  begin
+                    created = @surface.create_tab(preset, workspace_id: workspace, cwd: File.expand_path(root), label: label)
+                  rescue TabMaterializationError => e
+                    # Roll back the tab this call created — exact id from
+                    # the surface, never a listing guess. Best effort: a
+                    # rollback failure never replaces the primary error.
+                    begin
+                      @executor.tab_close(e.tab_id)
+                    rescue StandardError => close_error
+                      warn "ace-herdr: rollback close failed for tab #{e.tab_id}: #{close_error.class}: #{close_error.message}"
+                    end
+                    raise
+                  end
+                  created.fetch(:tab)
+                else
+                  parsed = @executor.tab_create(workspace_id: workspace, label: label, cwd: File.expand_path(root)).parsed_json
+                  find_value(parsed, %w[tab tab_id])
+                end
+              raise TargetResolutionError, "tab create returned no tab id" if created_id.nil?
+
+              begin
+                write_identity(path, id: created_id, root: canonical_root(root), preset: preset)
+              rescue StandardError
+                begin
+                  @executor.tab_close(created_id)
+                rescue StandardError => close_error
+                  warn "ace-herdr: rollback close failed for tab #{created_id}: #{close_error.class}: #{close_error.message}"
+                end
+                raise
+              end
+              created_id
+            end
+          end
+        end
+
+        def prepare_pane(window:)
+          with_errors do
+            tab = resolve_tab!(window)
+            # Hold the identity lock through discovery, split, verification,
+            # and recording so concurrent instances cannot split twice.
+            with_identity_lock(tab[:workspace], tab[:name]) do
+              cached = discover_prepared_pane(tab)
+              next cached if cached
+
+              # Split a shell pane: prefer the first pane without a live
+              # agent — pane list ordering does not contractually promise
+              # a shell root pane in foreign multi-pane tabs. Single-pane
+              # tabs skip the probe entirely.
+              tab_panes = panes(tab[:workspace]).select { |pane| pane[:tab] == tab[:id] }
+              root_pane = tab_panes.first
+              if tab_panes.length > 1
+                root_pane = tab_panes.find { |pane| !agent_pane?(pane[:pane]) } || tab_panes.first
+              end
+              raise Runtime::TargetNotFoundError, "tab '#{window}' has no pane" unless root_pane
+
+              parsed = @executor.pane_split(pane: root_pane[:pane], direction: "right").parsed_json
+              id = find_value(parsed, %w[pane pane_id])
+              raise TargetResolutionError, "pane split returned no pane id" if id.nil?
+
+              verify_retained_shell!(id)
+              record_prepared_pane(tab, id)
+              id
+            end
+          end
+        end
+
+        def focus(window:)
+          with_errors { @executor.tab_focus(resolve_tab!(window)[:id]); true }
+        end
+
+        def send_profile
+          :agent_aware
+        end
+
+        def send(pane:, command: nil, items: [])
+          # Reject malformed shared shapes before any delivery or mutation;
+          # the agent probe below is a native read, never a write.
+          Runtime::Atoms::SendContract.normalize!(command: command, items: items, profile: :plain_pane)
+          with_errors do
+            agent = agent_pane?(pane)
+            request = Runtime::Atoms::SendContract.normalize!(
+              command: command, items: items, profile: agent ? :agent_aware : :plain_pane
+            )
+            if agent
+              request.items.each do |item|
+                item.key?(:message) ? @executor.agent_prompt(pane: pane, text: item[:message]) :
+                  @executor.agent_send_keys(pane, [item[:key]])
+              end
+            else
+              @executor.pane_run(pane, request.command) if request.command
+              request.items.each do |item|
+                item.key?(:message) ? @executor.pane_send_text(pane, item[:message]) :
+                  @executor.pane_send_keys(pane, [item[:key]])
+              end
+            end
+            Runtime::Atoms::SendContract::Result.new(dropped_trailing_enter: request.dropped_trailing_enter)
+          end
+        end
+
+        def send_command(pane:, command:)
+          send(pane: pane, command: command)
+        end
+
+        def send_text(pane:, text:)
+          send(pane: pane, items: [{message: text}])
+        end
+
+        def send_keys(pane:, keys:)
+          send(pane: pane, items: Array(keys).map { |key| {key: key} })
+        end
+
+        def capture(pane:, lines: 40)
+          with_errors { @surface.capture(pane: pane, lines: lines) }
+        end
+
+        def wait_output(pane:, pattern:, timeout:)
+          with_errors(condition: "output", target: pane, timeout: timeout) do
+            @surface.wait_output(pane: pane, pattern: pattern, timeout_ms: milliseconds(timeout))
+          end
+        end
+
+        def wait_agent(pane:, states:, timeout:)
+          with_errors(condition: "agent", target: pane, timeout: timeout) do
+            @executor.agent_wait(pane: pane, until_states: states, timeout_ms: milliseconds(timeout))
+            true
+          end
+        end
+
+        def wait_lifecycle(condition:, target:, timeout:)
+          unless Runtime::Atoms::SendContract::LIFECYCLE_CONDITIONS.include?(condition)
+            raise ArgumentError, "unknown lifecycle condition '#{condition}'"
+          end
+
+          # Window conditions resolve the caller workspace once per wait so
+          # poll iterations do not re-run context and tab-list subprocesses;
+          # pane conditions never need it.
+          scope = nil
+          deadline = @clock.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          with_errors(condition: condition, target: target, timeout: timeout) do
+            loop do
+              if condition.start_with?("window-") && scope.nil?
+                scope = workspace_id!
+              end
+              return true if lifecycle_met?(condition, target, workspace: scope)
+              raise Runtime::WaitTimeoutError.new(condition: condition, target: target, timeout: timeout) if
+                @clock.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+              @sleeper.sleep(@poll_interval)
+            end
+          end
+        end
+
+        def close_window(window:)
+          with_errors { @executor.tab_close(resolve_tab!(window)[:id]); true }
+        end
+
+        def list_windows
+          with_errors { tabs(workspace_id!).map { |tab| {name: tab[:name], window: tab[:id], active: tab[:active]} } }
+        end
+
+        def list_panes(window:)
+          with_errors do
+            tab = resolve_tab!(window)
+            panes(tab[:workspace]).select { |pane| pane[:tab] == tab[:id] }
+          end
+        end
+
+        private
+
+        def inside?
+          !@env["HERDR_SESSION"].to_s.empty? && !@env["HERDR_PANE"].to_s.empty?
+        end
+
+        def workspace_id!
+          raise Runtime::RuntimeUnavailableError, "not inside a herdr workspace" unless inside?
+
+          context[:session] || raise(Runtime::RuntimeUnavailableError, "herdr workspace is unavailable")
+        end
+
+        def tabs(workspace)
+          @surface.list_tabs(workspace_id: workspace).map do |row|
+            {id: row[:id], name: row[:title], workspace: row[:workspace], active: row[:focused]}
+          end
+        end
+
+        def panes(workspace)
+          @surface.list_panes(workspace_id: workspace).map do |row|
+            {pane: row[:id], tab: row[:tab], workspace: row[:workspace]}
+          end
+        end
+
+        def resolve_tab!(window)
+          workspace = workspace_id!
+          tab = tabs(workspace).find { |row| row[:id] == window || row[:name] == window }
+          tab || raise(Runtime::TargetNotFoundError, "tab '#{window}' not found")
+        end
+
+        def canonical_root(root)
+          File.realpath(root)
+        rescue Errno::ENOENT
+          File.expand_path(root)
+        end
+
+        # Identity records and locks are keyed on the shared (workspace,
+        # label) identity in a stable user-level location — instances from
+        # any cwd and any requested root agree on the same record, so
+        # concurrent creators of the same label serialize and reuse is
+        # verifiable across processes.
+        def identity_path(workspace, label)
+          base = @identity_dir || File.join(Dir.home, ".ace", "local", "herdr", "runtime-tabs")
+          File.join(base, "#{Digest::SHA256.hexdigest("#{workspace}\0#{label}")}.json")
+        end
+
+        def with_identity_lock(workspace, label, &_block)
+          path = "#{identity_path(workspace, label)}.lock"
+          FileUtils.mkdir_p(File.dirname(path))
+          File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
+            file.flock(File::LOCK_EX)
+            yield
+          end
+        end
+
+        # Reuse needs the recorded identity to match the request; when no
+        # readable record exists, native pane cwd is the only remaining
+        # root evidence and a preset can never be verified.
+        def verifiable_identity?(tab, root:, preset:, path:)
+          recorded = read_identity(path, tab)
+          if recorded
+            return recorded["root"] == canonical_root(root) && recorded["preset"] == preset
+          end
+
+          native_root = native_pane_cwd(tab)
+          native_root && canonical_root(native_root) == canonical_root(root) && preset.nil?
+        end
+
+        # Rollback after a failed create is exact-id only (see ensure_window);
+        # listings are never consulted for ownership decisions.
+
+        def read_identity(path, tab)
+          recorded = JSON.parse(File.read(path)) if File.file?(path)
+          recorded = nil unless recorded.is_a?(Hash) && recorded["id"] == tab[:id]
+          # A pointer-only record (no root/preset provenance — written for
+          # a foreign tab's prepared pane) proves no ownership.
+          recorded = nil if recorded && !recorded.key?("root") && !recorded.key?("preset")
+          recorded
+        rescue JSON::ParserError
+          raise Runtime::WindowConflictError,
+            "window '#{tab[:name]}' has unreadable root or preset identity"
+        end
+
+        def native_pane_cwd(tab)
+          native_pane = @surface.list_panes(workspace_id: tab[:workspace]).find { |pane| pane[:tab] == tab[:id] }
+          native_pane && native_pane[:cwd]
+        end
+
+        # Cross-instance prepared-pane reuse: the identity record carries
+        # the prepared pane id, so another adapter instance (or process)
+        # reuses the retained target instead of splitting again. Works for
+        # provenance records and pointer-only (foreign tab) records alike.
+        def discover_prepared_pane(tab)
+          cached = @prepared[tab[:id]]
+          return cached if usable_prepared_pane?(cached)
+
+          pane_id = pointer_prepared_pane(identity_path(tab[:workspace], tab[:name]), tab[:id])
+          return nil unless pane_id && usable_prepared_pane?(pane_id)
+
+          @prepared[tab[:id]] = pane_id
+          pane_id
+        end
+
+        def pointer_prepared_pane(path, id)
+          raw = JSON.parse(File.read(path))
+          raw.is_a?(Hash) && raw["id"] == id ? raw["prepared_pane"] : nil
+        rescue JSON::ParserError, Errno::ENOENT
+          nil
+        end
+
+        def record_prepared_pane(tab, pane_id)
+          @prepared[tab[:id]] = pane_id
+          path = identity_path(tab[:workspace], tab[:name])
+          begin
+            recorded = File.file?(path) ? JSON.parse(File.read(path)) : nil
+          rescue JSON::ParserError
+            # A corrupt record is repaired under the identity lock rather
+            # than silently dropped, so the pointer survives.
+            recorded = :corrupt
+          end
+          if recorded.is_a?(Hash) && recorded["id"] == tab[:id]
+            write_identity(path, id: recorded["id"], root: recorded["root"], preset: recorded["preset"],
+              prepared_pane: pane_id)
+          else
+            # Foreign tab (not created through ensure_window) or corrupt
+            # record: persist a pointer-only record so later instances
+            # reuse this pane instead of splitting again.
+            write_pointer_only(path, id: tab[:id], prepared_pane: pane_id)
+          end
+        rescue StandardError => e
+          # The pointer is an optimization; losing it only costs a re-split.
+          # Warn and continue — provenance writes in ensure_window stay
+          # hard-fail, this one does not.
+          warn "ace-herdr: could not persist prepared-pane record for '#{tab[:name]}': #{e.class}: #{e.message}"
+          nil
+        end
+
+        def usable_prepared_pane?(pane_id)
+          return false unless pane_id
+
+          @executor.pane_get(pane_id)
+          info = find_hash(@executor.pane_process_info(pane_id).parsed_json, %w[result process_info])
+          info.is_a?(Hash) && !!find_value_of_type(info, "shell_pid", Integer)
+        rescue PaneNotFoundError
+          false
+        end
+
+        def verify_retained_shell!(pane_id)
+          info = find_hash(@executor.pane_process_info(pane_id).parsed_json, %w[result process_info])
+          return if info.is_a?(Hash) && find_value_of_type(info, "shell_pid", Integer)
+
+          raise Runtime::Error, "prepared pane '#{pane_id}' has no retained shell"
+        end
+
+        def write_identity(path, id:, root:, preset:, prepared_pane: nil)
+          payload = {id: id, root: root, preset: preset}
+          payload[:prepared_pane] = prepared_pane if prepared_pane
+          atomic_write_json(path, payload)
+        end
+
+        def write_pointer_only(path, id:, prepared_pane:)
+          atomic_write_json(path, {id: id, prepared_pane: prepared_pane})
+        end
+
+        def atomic_write_json(path, payload)
+          temp = "#{path}.#{Process.pid}.tmp"
+          File.open(temp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+            file.write(JSON.generate(payload))
+            file.flush
+            file.fsync
+          end
+          File.rename(temp, path)
+        ensure
+          File.delete(temp) if temp && File.exist?(temp)
+        end
+
+        def agent_pane?(pane)
+          @executor.agent_get(pane)
+          true
+        rescue AgentNotFoundError
+          false
+        end
+
+        def lifecycle_met?(condition, target, workspace:)
+          case condition
+          when "window-exists" then tab_exists?(target, workspace: workspace)
+          when "window-active" then tab_active?(target, workspace: workspace)
+          when "pane-exists" then pane_exists?(target)
+          when "pane-exited" then pane_exited?(target)
+          end
+        end
+
+        def tab_exists?(target, workspace:)
+          @executor.tab_get(find_tab(target, workspace)[:id])
+          true
+        rescue Runtime::TargetNotFoundError, TabNotFoundError
+          false
+        end
+
+        def tab_active?(target, workspace:)
+          tab = find_tab(target, workspace)
+          @executor.tab_get(tab[:id])
+          tab[:active] == true
+        rescue Runtime::TargetNotFoundError, TabNotFoundError
+          false
+        end
+
+        # Scoped to the workspace resolved once for the enclosing wait.
+        def find_tab(target, workspace)
+          tabs(workspace).find { |row| row[:id] == target || row[:name] == target } ||
+            raise(Runtime::TargetNotFoundError, "tab '#{target}' not found")
+        end
+
+        def pane_exists?(target)
+          @executor.pane_get(target)
+          true
+        rescue PaneNotFoundError
+          false
+        end
+
+        # Mirrors PaneTidyProbe.process_evidence semantics: herdr
+        # serializes `foreground_processes` with serde skip_serializing_if,
+        # so inside a well-formed result.process_info object an OMITTED key
+        # is the process-exit proof; an explicit null or non-array value is
+        # malformed evidence and stays inconclusive. Anything alive appears
+        # as a non-empty array; a list holding only the retained shell
+        # counts as exited (no submitted foreground command remains).
+        def pane_exited?(target)
+          return true unless pane_exists?(target)
+
+          info = find_hash(@executor.pane_process_info(target).parsed_json, %w[result process_info])
+          return false unless info.is_a?(Hash)
+
+          processes = info["foreground_processes"]
+          return false if info.key?("foreground_processes") && !processes.is_a?(Array)
+
+          # An omitted list is only trusted exit evidence inside a
+          # well-formed object that also carries the pane's shell pid;
+          # an empty or shell-only hash alone proves nothing.
+          shell_pid = find_value_of_type(info, "shell_pid", Integer)
+          return false unless shell_pid
+
+          processes = Array(processes)
+          return true if processes.empty?
+
+          processes.all? { |process| process.is_a?(Hash) && process["pid"] == shell_pid }
+        rescue PaneNotFoundError
+          true
+        end
+
+        def find_value(value, keys)
+          Atoms::JsonFind.find_value(value, keys)
+        end
+
+        # Pinned-path walk that fails closed: nil unless every hop resolves
+        def find_hash(value, keys)
+          keys.each do |key|
+            return nil unless value.is_a?(Hash)
+
+            value = value[key]
+          end
+          value
+        end
+
+        def find_value_of_type(value, key, type)
+          return unless value.is_a?(Hash)
+          return value[key] if value[key].is_a?(type)
+
+          value.each_value { |child| found = find_value_of_type(child, key, type); return found if found }
+          nil
+        end
+
+        def milliseconds(seconds)
+          (seconds * 1000).ceil
+        end
+
+        def with_errors(condition: nil, target: nil, timeout: nil)
+          yield
+        rescue AgentBlockedError => e
+          raise Runtime::SendRejectedError, e.message
+        rescue ExecutorTimeoutError, Herdr::WaitTimeoutError => e
+          raise Runtime::WaitTimeoutError.new(condition: condition || "send", target: target, timeout: timeout || 0)
+        rescue AgentNotReadyError => e
+          error = condition ? Runtime::WaitTimeoutError.new(condition: condition, target: target, timeout: timeout) :
+            Runtime::SendStalledError.new(e.message)
+          raise error
+        rescue PaneNotFoundError, TabNotFoundError, AgentNotFoundError => e
+          raise Runtime::TargetNotFoundError, e.message
+        rescue WorkspaceNotFoundError, TargetResolutionError => e
+          # Unresolvable caller context, or the runtime responded but the
+          # answer was unusable (missing ids)
+          raise Runtime::RuntimeUnavailableError, e.message
+        rescue TabMaterializationError, ValidationError, CommandError => e
+          # Bad request configuration, a failed materialization, or an
+          # unmapped native failure keeps the native cause while surfacing
+          # under the contract error type.
+          raise Runtime::Error, e.message
+        rescue ExecutorUnavailableError => e
+          raise Runtime::RuntimeUnavailableError, e.message
+        rescue Runtime::Error
+          # Already a contract error (raised inside the block): pass through
+          # untouched — never re-wrap.
+          raise
+        rescue StandardError => e
+          # Adapter boundary: every runtime failure surfaces under the
+          # contract error model, with the native cause preserved.
+          raise Runtime::Error, "#{e.class}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Herdr
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/ace/herdr.rb

@@ -15,6 +15,18 @@ module Ace
 
     # Raised when a bounded wait exceeds its timeout
     class WaitTimeoutError < Error; end
+
+    # Raised when a preset tab was created natively but a later
+    # materialization step (splits, commands, agents) failed; carries the
+    # created tab id so the owner can roll back exactly that tab.
+    class TabMaterializationError < Error
+      attr_reader :tab_id
+
+      def initialize(tab_id:, message:)
+        @tab_id = tab_id
+        super(message)
+      end
+    end
   end
 end
 
@@ -23,6 +35,7 @@ require_relative "herdr/errors"
 
 # Load all ace-herdr components
 require_relative "herdr/atoms/answer_digest"
+require_relative "herdr/atoms/json_find"
 require_relative "herdr/models/delivery_record"
 require_relative "herdr/models/dispatch_outcome"
 require_relative "herdr/molecules/herdr_executor"
@@ -33,6 +46,7 @@ require_relative "herdr/molecules/preset_resolver"
 require_relative "herdr/organisms/deliverer"
 require_relative "herdr/organisms/dispatcher"
 require_relative "herdr/organisms/control_surface"
+require_relative "herdr/organisms/runtime_adapter"
 require_relative "herdr/organisms/tidy"
 require_relative "herdr/cli"
 

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "ace/herdr"
+require "ace/runtime"
+
+Ace::Runtime.register(:herdr, -> { Ace::Herdr::Organisms::RuntimeAdapter.new })

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-herdr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-hitl
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: ace-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
   requirement: !ruby/object:Gem::Requirement
@@ -170,6 +184,7 @@ files:
 - exe/ace-herdr
 - lib/ace/herdr.rb
 - lib/ace/herdr/atoms/answer_digest.rb
+- lib/ace/herdr/atoms/json_find.rb
 - lib/ace/herdr/cli.rb
 - lib/ace/herdr/cli/commands/capture.rb
 - lib/ace/herdr/cli/commands/close.rb
@@ -194,8 +209,10 @@ files:
 - lib/ace/herdr/organisms/control_surface.rb
 - lib/ace/herdr/organisms/deliverer.rb
 - lib/ace/herdr/organisms/dispatcher.rb
+- lib/ace/herdr/organisms/runtime_adapter.rb
 - lib/ace/herdr/organisms/tidy.rb
 - lib/ace/herdr/version.rb
+- lib/ace/runtime/adapters/herdr.rb
 homepage: https://github.com/cs3b/ace
 licenses:
 - MIT