ace-herdr 0.3.2 → 0.5.0

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

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
-require "open3"
+require "fiddle"
 require "timeout"
+require "fcntl"
 
 module Ace
   module Herdr
     module Molecules
       # Runs a child process in its own process group with a real deadline.
       # Pipes drain with bounded memory and a stalled child is killed at the
-      # deadline, so the caller never blocks in cleanup past the timeout the
-      # way an Open3.capture3 + Timeout.timeout combination can.
+      # execution deadline. Cleanup adds at most one second of owned reaping;
+      # unconfirmed cleanup transfers eventual reaping and reports uncertainty.
       module BoundedProcess
         # Immutable outcome of one bounded child run.
         Result = Struct.new(:stdout, :stderr, :status, :oversized)
@@ -23,33 +24,160 @@ module Ace
           end
         end
 
+        CLEANUP_TIMEOUT = 1.0
+        DARWIN_GROUP_PID_LIMIT = 4096
+
+        # No detached waiter may reap this leader before its owned group is
+        # signalled: the unreaped child pins its PID even after normal exit.
+        class OwnedChild
+          attr_reader :pid
+
+          def initialize(pid = nil)
+            @pid, @status, @owned = pid, nil, !pid.nil?
+            @group_signalled = false
+          end
+
+          def start!(command, options)
+            raise PostLaunchError, "original child handle cannot be replaced" if started?
+            @pid = Process.spawn(*command, **options)
+            @owned = true
+          end
+
+          def group_signalled? = @group_signalled
+
+          def group_signalled!
+            raise PostLaunchError, "original child ownership is unavailable" unless alive?
+            @group_signalled = true
+          end
+
+          def started?
+            !@pid.nil?
+          end
+
+          def alive?
+            @owned && @status.nil?
+          end
+
+          def join(timeout)
+            deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+            loop do
+              unless @status
+                result = Process.waitpid2(@pid, Process::WNOHANG)
+                @status = result.last if result
+              end
+              return self if @status
+              remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              return nil unless remaining.positive?
+              sleep [remaining, 0.002].min
+            end
+          rescue Errno::ECHILD
+            @owned = false
+            raise PostLaunchError, "original child ownership is unavailable"
+          end
+
+          def exited?
+            BoundedProcess.nonreaping_exit?(@pid)
+          rescue Errno::ECHILD
+            @owned = false
+            raise PostLaunchError, "original child ownership is unavailable"
+          end
+
+          def release_to_reaper!
+            raise PostLaunchError, "original child ownership is unavailable" unless alive?
+            Process.detach(@pid)
+            @owned = false
+          rescue Errno::ECHILD
+            @owned = false
+            raise PostLaunchError, "original child ownership is unavailable"
+          end
+
+          def value
+            raise PostLaunchError, "owned child has not been reaped" unless @status
+            @status
+          end
+        end
+
         module_function
 
         # @param argv [Array<String>] child argv (no shell)
         # @param stdin_data [String] payload written to the child's stdin
         # @param timeout_s [Numeric] wall-clock deadline for the whole run
-        # @param output_limit [Integer] per-stream retained byte cap
+        # @param output_limit [Integer] stdout retained byte cap
+        # @param stderr_limit [Integer] stderr retained byte cap (defaults to stdout cap)
+        # @param cleanup_group [Boolean] signal owned group after observed leader exit, before reaping
         # @return [Result] stdout/stderr are capped; oversized reports truncation
         # @raise [Timeout::Error] when the child outlives the deadline (killed)
         # @raise [SystemCallError] spawn failures only (child never launched)
         # @raise [PostLaunchError] SystemCallError while the child was live
-        def call(argv, stdin_data: "", timeout_s:, output_limit: 65_536)
-          Open3.popen3(*argv, pgroup: true) do |stdin, stdout, stderr, waiter|
+        def call(argv, stdin_data: "", timeout_s:, output_limit: 65_536, environment: nil, chdir: nil, descriptor_mapping: {}, stderr_limit: output_limit, cleanup_group: false)
+          if environment && (!environment.is_a?(Hash) || !environment.all? { |key, value| key.is_a?(String) && value.is_a?(String) })
+            raise ArgumentError, "bounded process environment must be explicit strings"
+          end
+          if chdir && (!chdir.is_a?(String) || !chdir.start_with?("/"))
+            raise ArgumentError, "bounded process working directory must be absolute"
+          end
+          unless descriptor_mapping.is_a?(Hash) && descriptor_mapping.size <= 16 &&
+              descriptor_mapping.all? { |descriptor, handle|
+                descriptor.is_a?(Integer) && descriptor.between?(3, 63) &&
+                  handle.is_a?(File) && !handle.closed? && handle.stat.file? &&
+                  (handle.fcntl(Fcntl::F_GETFL) & Fcntl::O_ACCMODE) == Fcntl::O_RDONLY
+              }
+            raise ArgumentError, "bounded process descriptors must be explicit read-only regular files"
+          end
+          unless [output_limit, stderr_limit].all? { |limit| limit.is_a?(Integer) && limit.positive? } &&
+              [true, false].include?(cleanup_group)
+            raise ArgumentError, "bounded process limits and cleanup mode are invalid"
+          end
+          selected_descriptors = descriptor_mapping.dup.freeze
+          command = environment ? [environment, *argv] : argv
+          options = {pgroup: true, close_others: true}.merge(selected_descriptors)
+          options[:chdir] = chdir if chdir
+          options[:unsetenv_others] = true if environment
+          handles = []
+          waiter = nil
+          begin
+            child_stdin, stdin = IO.pipe
+            handles.concat([child_stdin, stdin])
+            stdout, child_stdout = IO.pipe
+            handles.concat([stdout, child_stdout])
+            stderr, child_stderr = IO.pipe
+            handles.concat([stderr, child_stderr])
+            handles.each(&:binmode)
+            waiter = OwnedChild.new
             begin
-              run_loop(stdin, stdout, stderr, waiter,
-                stdin_data: stdin_data, timeout_s: timeout_s, output_limit: output_limit)
-            rescue SystemCallError => e
-              # The child was already spawned: an I/O failure now cannot be
-              # rewound into a pre-launch classification, and the child must
-              # not outlive the failure inside popen3's cleanup wait.
-              kill_group(waiter)
-              waiter.join
-              raise PostLaunchError, e.message
+              waiter.start!(command, options.merge(in: child_stdin, out: child_stdout, err: child_stderr))
+              close_error = close_handles([child_stdin, child_stdout, child_stderr])
+              raise close_error if close_error
+              run_loop(stdin, stdout, stderr, waiter, stdin_data: stdin_data,
+                timeout_s: timeout_s, output_limit: output_limit, stderr_limit: stderr_limit,
+                cleanup_group: cleanup_group)
+            rescue SystemCallError, IOError => error
+              raise unless waiter.started?
+              raise PostLaunchError, error.message
+            ensure
+              close_error = close_handles(handles)
+              # Closing one pipe cannot prevent original-child cleanup.
+              cleanup_child!(waiter) if waiter.started?
+              raise PostLaunchError.new(close_error.message), cause: close_error if close_error && waiter.started?
             end
+          ensure
+            close_handles(handles)
           end
         end
 
-        def run_loop(stdin, stdout, stderr, waiter, stdin_data:, timeout_s:, output_limit:)
+        def close_handles(handles)
+          first_error = nil
+          handles.each do |io|
+            begin
+              io.close unless io.closed?
+            rescue SystemCallError, IOError => error
+              first_error ||= error
+            end
+          end
+          first_error
+        end
+
+        def run_loop(stdin, stdout, stderr, waiter, stdin_data:, timeout_s:, output_limit:, stderr_limit:, cleanup_group:)
           payload = stdin_data.to_s
           sent = 0
           stdin_closed = payload.empty?
@@ -58,59 +186,146 @@ module Ace
           streams = [stdout, stderr]
           oversized = false
           deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_s
-            buffers = {stdout => +"", stderr => +""}
-            streams = [stdout, stderr]
-            oversized = false
-            deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_s
+          group_cleaned = false
 
-            until streams.empty? && stdin_closed && waiter.join(0)
-              remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-              if remaining <= 0
+          loop do
+            if streams.empty? && stdin_closed
+              if cleanup_group && !group_cleaned && waiter.exited?
                 kill_group(waiter)
-                raise Timeout::Error, "process did not finish within #{timeout_s}s"
+                group_cleaned = true
               end
+              break if (!cleanup_group || group_cleaned) && waiter.join(0)
+            end
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if remaining <= 0
+              kill_group(waiter)
+              raise Timeout::Error, "process did not finish within #{timeout_s}s"
+            end
 
-              ready = IO.select(streams, stdin_closed ? [] : [stdin], nil, [remaining, 0.02].min)
-              next unless ready
+            ready = IO.select(streams, stdin_closed ? [] : [stdin], nil, [remaining, 0.02].min)
+            next unless ready
 
-              ready.first.each do |io|
+            ready.first.each do |io|
+              begin
                 chunk = io.read_nonblock(4096, exception: false)
-                if chunk.nil?
-                  io.close
-                  streams.delete(io)
-                elsif chunk != :wait_readable
-                  buffer = buffers.fetch(io)
-                  available = output_limit - buffer.bytesize
-                  oversized = true if chunk.bytesize > available
-                  buffer << chunk.byteslice(0, available) if available.positive?
-                end
+              rescue Errno::EINTR
+                # No bytes were returned. Keep the original child/pipe and
+                # return to the same absolute-deadline loop before reading again.
+                next
               end
+              if chunk.nil?
+                io.close
+                streams.delete(io)
+              elsif chunk != :wait_readable
+                buffer = buffers.fetch(io)
+                limit = io.equal?(stderr) ? stderr_limit : output_limit
+                available = limit - buffer.bytesize
+                oversized = true if chunk.bytesize > available
+                buffer << chunk.byteslice(0, available) if available.positive?
+              end
+            end
 
-              next if stdin_closed || !ready[1].to_a.include?(stdin)
+            next if stdin_closed || !ready[1].to_a.include?(stdin)
 
-              begin
-                # Nonblocking with partial writes: a child that stops reading
-                # must never trap us inside one large stdin.write; the loop
-                # re-checks the deadline between write attempts.
-                written = stdin.write_nonblock(payload.byteslice(sent, payload.bytesize - sent),
-                  exception: false)
-                sent += written if written != :wait_writable
-              rescue Errno::EPIPE, IOError
-                sent = payload.bytesize
-              end
-              if sent >= payload.bytesize
-                stdin.close
-                stdin_closed = true
-              end
+            begin
+              # Nonblocking with partial writes: a child that stops reading
+              # must never trap us inside one large stdin.write; the loop
+              # re-checks the deadline between write attempts.
+              written = stdin.write_nonblock(payload.byteslice(sent, payload.bytesize - sent),
+                exception: false)
+              sent += written if written != :wait_writable
+            rescue Errno::EPIPE, IOError
+              sent = payload.bytesize
+            end
+            if sent >= payload.bytesize
+              stdin.close
+              stdin_closed = true
             end
+          end
 
           Result.new(buffers.fetch(stdout), buffers.fetch(stderr), waiter.value, oversized)
         end
 
+        def cleanup_child!(waiter)
+          return unless waiter.alive?
+          signal_error = nil
+          begin
+            kill_group(waiter)
+          rescue SystemCallError => error
+            signal_error = error
+          end
+          unless waiter.join(CLEANUP_TIMEOUT)
+            # Transfer only this still-exclusively-owned child to an eventual
+            # reaper. No signal or positive result can use it after transfer.
+            waiter.release_to_reaper!
+            raise PostLaunchError, "owned child cleanup could not be confirmed within deadline"
+          end
+          raise PostLaunchError.new(signal_error.message), cause: signal_error if signal_error
+        end
+
+        # POSIX waitid observes only this original child's termination and
+        # leaves it waitable. No stream/timeout/PID liveness inference is used.
+        # Constants: Linux v6.12 include/uapi/linux/wait.h; XNU bsd/sys/wait.h.
+        def nonreaping_exit?(pid)
+          nowait = if RUBY_PLATFORM.include?("linux")
+            0x01000000
+          elsif RUBY_PLATFORM.include?("darwin")
+            0x00000020
+          else
+            raise PostLaunchError, "nonreaping child observation is unsupported"
+          end
+          buffer = Fiddle::Pointer.malloc(512, Fiddle::RUBY_FREE)
+          buffer[0, 512] = "\0" * 512
+          function = Fiddle::Function.new(Fiddle.dlopen(nil)["waitid"],
+            [Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT], Fiddle::TYPE_INT)
+          result = function.call(1, pid, buffer, 4 | 1 | nowait)
+          raise SystemCallError.new("waitid", Fiddle.last_error) unless result.zero?
+          buffer[0, Fiddle::SIZEOF_INT].unpack1("i!") == Signal.list.fetch("CHLD")
+        rescue Fiddle::DLError => error
+          raise PostLaunchError, error.message
+        end
+
         def kill_group(waiter)
+          return unless waiter.alive?
+          return if waiter.is_a?(OwnedChild) && waiter.group_signalled?
           Process.kill("KILL", -waiter.pid)
+          waiter.group_signalled! if waiter.is_a?(OwnedChild)
         rescue Errno::ESRCH
           nil
+        rescue Errno::EPERM
+          # XNU killpg1 excludes SZOMB members and can return EPERM for
+          # the owned zombie alone. Genuine permission failures still fail:
+          # prove the complete group contains only our unreaped child.
+          raise unless darwin_singleton_exited_group?(waiter)
+        end
+
+        def darwin_singleton_exited_group?(waiter)
+          return false unless darwin_platform? && waiter.is_a?(OwnedChild) &&
+            waiter.alive? && waiter.exited?
+          return false unless darwin_group_pids(waiter.pid) == [waiter.pid]
+          waiter.alive? && waiter.exited? && waiter.alive?
+        rescue SystemCallError, IOError, Fiddle::DLError, PostLaunchError
+          false
+        end
+
+        def darwin_platform? = RUBY_PLATFORM.include?("darwin")
+
+        # libproc enumerates allproc AND zombproc under the kernel process
+        # list lock. A full buffer is potentially truncated, never proof.
+        # This observes only the owned group, not children escaping it.
+        def darwin_group_pids(pid)
+          library = Fiddle.dlopen("/usr/lib/libproc.dylib")
+          function = Fiddle::Function.new(library["proc_listpids"],
+            [Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT], Fiddle::TYPE_INT)
+          capacity = DARWIN_GROUP_PID_LIMIT * Fiddle::SIZEOF_INT
+          buffer = Fiddle::Pointer.malloc(capacity, Fiddle::RUBY_FREE)
+          buffer[0, capacity] = "\0" * capacity
+          # PROC_PGRP_ONLY=2, from XNU bsd/sys/proc_info.h.
+          size = function.call(2, pid, buffer, capacity)
+          return nil unless size.positive? && size < capacity && (size % Fiddle::SIZEOF_INT).zero?
+          pids = buffer[0, size].unpack("i!*")
+          return nil unless pids.all?(&:positive?) && pids.uniq == pids
+          pids
         end
       end
     end

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

@@ -11,6 +11,8 @@ module Ace
       # yields a torn record and the answer stays re-deliverable. A per-event
       # flock serializes concurrent deliveries of the same event.
       module DeliveryRecordStore
+        class LockUnavailable < StandardError; end
+
         module_function
 
         # @return [Models::DeliveryRecord, nil] the record, falling back to
@@ -41,6 +43,12 @@ module Ace
 
         # @return [String] path the record was written to
         def save(record, deliveries_dir)
+          with_inventory_lock(deliveries_dir, exclusive: false, create: true) do
+            save_held(record, deliveries_dir)
+          end
+        end
+
+        def save_held(record, deliveries_dir)
           FileUtils.mkdir_p(deliveries_dir)
           path = path_for(deliveries_dir, record.event_id)
           tmp = "#{path}.tmp.#{Process.pid}"
@@ -56,18 +64,79 @@ module Ace
 
         # Hold the exclusive per-event lock while delivering; concurrent
         # callers block until the winner finishes, then observe its record.
-        def with_lock(deliveries_dir, event_id)
-          FileUtils.mkdir_p(deliveries_dir)
-          File.open(lock_path(deliveries_dir, event_id), "a") do |lock|
-            lock.flock(File::LOCK_EX)
+        def with_lock(deliveries_dir, event_id, create: true, deadline: nil)
+          with_locks(deliveries_dir, [event_id], create: create, deadline: deadline) { yield }
+        end
+
+        def with_locks(deliveries_dir, event_ids, create: false, deadline: nil)
+          with_inventory_lock(deliveries_dir, exclusive: false, create: create, deadline: deadline) do
+            with_event_locks_held(deliveries_dir, event_ids, create: create, deadline: deadline) { yield }
+          end
+        end
+
+        # Global inventory always precedes event locks. Normal creators/writers
+        # share it; maintenance exclusively holds it through its entire mutation
+        # boundary. Reentrancy never upgrades a writer's shared lock.
+        def with_inventory_lock(deliveries_dir, exclusive:, create: false, prepare_directory: true, deadline: nil)
+          admission_deadline!(deadline) unless deadline.nil?
+          held = Thread.current[:ace_herdr_delivery_inventory_locks] ||= {}
+          if (existing = held[deliveries_dir])
+            raise ArgumentError, "delivery inventory lock cannot be upgraded" if exclusive && existing != :exclusive
+            return yield
+          end
+          FileUtils.mkdir_p(deliveries_dir) if create && prepare_directory
+          flags = File::RDWR | File::NOFOLLOW | (create ? File::CREAT : 0)
+          flags |= File::NONBLOCK unless deadline.nil?
+          File.open(File.join(deliveries_dir, ".inventory.lock"), flags, 0o600) do |lock|
+            raise ArgumentError, "delivery inventory lock is not a regular file" unless lock.stat.file?
+            acquire_lock!(lock, exclusive ? File::LOCK_EX : File::LOCK_SH, deadline)
+            held[deliveries_dir] = exclusive ? :exclusive : :shared
             begin
-              return yield
+              yield
             ensure
+              held.delete(deliveries_dir)
               lock.flock(File::LOCK_UN)
             end
           end
         end
 
+        def with_event_locks_held(deliveries_dir, event_ids, create: false, deadline: nil)
+          FileUtils.mkdir_p(deliveries_dir) if create
+          flags = create ? "a" : File::RDWR | File::NOFOLLOW
+          flags = File::WRONLY | File::APPEND | File::CREAT | File::NOFOLLOW if deadline && create
+          flags |= File::NONBLOCK unless deadline.nil?
+          handles = []
+          event_ids.sort.each do |event_id|
+            lock = File.open(lock_path(deliveries_dir, event_id), flags)
+            handles << lock
+            raise ArgumentError, "delivery event lock is not a regular file" unless lock.stat.file?
+            acquire_lock!(lock, File::LOCK_EX, deadline)
+          end
+          yield
+        ensure
+          handles&.reverse_each do |lock|
+            lock.flock(File::LOCK_UN)
+            lock.close
+          end
+        end
+
+        def acquire_lock!(lock, mode, deadline)
+          admission_deadline!(deadline) unless deadline.nil?
+          unless lock.flock(mode | (deadline ? File::LOCK_NB : 0))
+            raise LockUnavailable, "delivery exclusion is busy"
+          end
+          admission_deadline!(deadline) unless deadline.nil?
+        end
+
+        def admission_deadline!(deadline)
+          unless (deadline.is_a?(Integer) || deadline.is_a?(Float)) && deadline.finite?
+            raise ArgumentError, "delivery deadline must be finite"
+          end
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise LockUnavailable, "delivery admission deadline expired"
+          end
+        end
+
         def path_for(deliveries_dir, event_id)
           File.join(deliveries_dir, "#{event_id}.json")
         end
@@ -115,6 +184,12 @@ module Ace
         # archived event just reports its archive path.
         # @return [String] the archive path the record lives at
         def archive(deliveries_dir, event_id)
+          with_inventory_lock(deliveries_dir, exclusive: false, create: true) do
+            archive_held(deliveries_dir, event_id)
+          end
+        end
+
+        def archive_held(deliveries_dir, event_id)
           dest = File.join(archive_dir(deliveries_dir), "#{event_id}.json")
           return dest if !File.exist?(path_for(deliveries_dir, event_id)) && File.exist?(dest)
 
@@ -147,6 +222,7 @@ module Ace
         rescue JSON::ParserError, ArgumentError
           nil
         end
+        private_class_method :save_held, :archive_held, :with_event_locks_held
       end
     end
   end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+require "ace/runtime/errors"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Closed N1 producer value. Native endpoint selection and kernel capture
+      # belong to ProtectedNativeControl; this value never discovers a target.
+      module GuardedNativeOrigin
+        UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
+        TERMINAL = /\Aterm_[0-9a-f]{2,48}\z/
+        CHILD_FIELDS = %w[gid groups host parent_pid pid started_at uid].freeze
+        module_function
+
+        def verify!(value, terminal_id:, child:)
+          unless value.is_a?(Hash) && value.keys.all? { |key| key.is_a?(String) } && value.keys.sort == %w[child runtime_incarnation terminal_id] &&
+              value["terminal_id"] == terminal_id && terminal_id.is_a?(String) && terminal_id.ascii_only? && TERMINAL.match?(terminal_id) &&
+              value["runtime_incarnation"].is_a?(String) && value["runtime_incarnation"].ascii_only? && UUID.match?(value["runtime_incarnation"])
+            unavailable!
+          end
+          identity = value.fetch("child")
+          unless identity.is_a?(Hash) && identity.keys.all? { |key| key.is_a?(String) } && identity.keys.sort == CHILD_FIELDS && identity == child &&
+              %w[pid parent_pid].all? { |key| uint32?(identity[key]) && identity[key].positive? } &&
+              %w[uid gid].all? { |key| uint32?(identity[key]) } && identity["groups"].is_a?(Array) &&
+              identity["groups"].size <= 256 && identity["groups"].all? { |group| uint32?(group) } &&
+              identity["groups"] == identity["groups"].sort.uniq && valid_birth?(identity["started_at"]) &&
+              identity["host"].is_a?(String) && identity["host"].valid_encoding? && (identity["host"].encoding == Encoding::UTF_8 || identity["host"].ascii_only?) &&
+              identity["host"].bytesize.between?(1, 255) && !identity["host"].match?(/\p{Cc}/)
+            unavailable!
+          end
+          immutable(value)
+        end
+
+        def uint32?(value) = value.is_a?(Integer) && value.between?(0, 0xffff_ffff)
+
+        def valid_birth?(value)
+          return false unless value.is_a?(String) && value.ascii_only?
+          parts = value.split(":", -1)
+          parts.size == 3 && parts[0] == "linux" && UUID.match?(parts[1]) &&
+            parts[2].match?(/\A[0-9]+\z/) && parts[2].to_i.between?(1, 0xffff_ffff_ffff_ffff)
+        end
+
+        def immutable(value)
+          case value
+          when Hash then value.to_h { |key, item| [key.dup.freeze, immutable(item)] }.freeze
+          when Array then value.map { |item| immutable(item) }.freeze
+          when String then value.dup.freeze
+          else value.freeze
+          end
+        end
+
+        def unavailable!
+          raise Ace::Runtime::RuntimeUnavailableError, "original native guarded origin is unavailable"
+        end
+        private_class_method :uint32?, :valid_birth?, :immutable, :unavailable!
+      end
+    end
+  end
+end

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

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
 require "open3"
 require "json"
 require "timeout"
+require_relative "bounded_process"
 
 module Ace
   module Herdr
@@ -16,8 +18,9 @@ module Ace
         WAKE_OUTPUT_LIMIT = 65_536
         DEFAULT_PROBE_TIMEOUT_S = 60
 
-        def initialize(binary: DEFAULT_BINARY)
+        def initialize(binary: DEFAULT_BINARY, process: BoundedProcess)
           @binary = binary
+          @process = process
         end
 
         # Probe the agent living in a pane (raises AgentNotFoundError when none)
@@ -30,7 +33,7 @@ module Ace
         # killed at the deadline and the timeout classifies as a retryable
         # pre-submission failure.
         def pane_get_bounded(pane, timeout_s: DEFAULT_PROBE_TIMEOUT_S)
-          result = BoundedProcess.call([@binary, "pane", "get", pane], stdin_data: "",
+          result = @process.call([@binary, "pane", "get", pane], stdin_data: "",
             timeout_s: timeout_s, output_limit: WAKE_OUTPUT_LIMIT)
           execution = ExecutionResult.new(
             stdout: result.stdout.strip, stderr: result.stderr.strip,
@@ -65,7 +68,7 @@ module Ace
         # keep the inbox event lock through Open3.capture3 cleanup.
         def agent_prompt_bounded(pane:, text:, timeout_ms:)
           cmd = [@binary, "agent", "prompt", pane, text]
-          result = BoundedProcess.call(cmd, stdin_data: "",
+          result = @process.call(cmd, stdin_data: "",
             timeout_s: timeout_ms / 1000.0, output_limit: WAKE_OUTPUT_LIMIT)
           execution = ExecutionResult.new(
             stdout: result.stdout.strip, stderr: result.stderr.strip,

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+require_relative "inbox_context_store"
+
+module Ace
+  module Herdr
+    module Molecules
+      module InboxCliInput
+        module_function
+        def read(path, limit:)
+          unless path.is_a?(String) && !path.empty? && !path.include?("\0")
+            raise ValidationError, "inbox input path differs"
+          end
+          before = File.lstat(path)
+          raise ValidationError, "inbox input is not a bounded regular file" unless before.file? && !before.symlink? && before.size.between?(1, limit)
+          snapshot = ->(stat) { [stat.dev, stat.ino, stat.size, stat.mtime, stat.ctime] }
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |handle|
+            raise ValidationError, "inbox input handle changed" unless snapshot.call(before) == snapshot.call(handle.stat)
+            bytes = handle.read(before.size + 1)
+            unless bytes && bytes.bytesize == before.size && snapshot.call(before) == snapshot.call(handle.stat) &&
+                snapshot.call(before) == snapshot.call(File.lstat(path))
+              raise ValidationError, "inbox input changed"
+            end
+            bytes.freeze
+          end
+        rescue SystemCallError, IOError
+          raise ValidationError, "inbox input is unavailable"
+        end
+
+        def reverse(path)
+          value = InboxContextStore.decode(read(path, limit: 16_384), limit: 16_384)
+          InboxDirectEffectBinding.reverse!(value)
+        end
+      end
+    end
+  end
+end