ace-herdr 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00422d9f6820e48b0ea45698e4663f7ecaeb9b5b01ddf1626ab86aed50adcbfd
-  data.tar.gz: 2632e4056271d3c022056a70fa5f3b95e2f69ae08544bf70f2577bc11fbac4f7
+  metadata.gz: cff3b8e4bd486d4b0e4e9a914fbdfe7010ffd1bc2a2be82babd93acf273e875d
+  data.tar.gz: 1b2e18f9c0faef285ff1e4003ff65b49565227a95ce4d80321cf43108486ff8c
 SHA512:
-  metadata.gz: c6626094540195dadf06116add8bd27708934b809347c12cb0bc355cb6c03d5ff32e30e3e63870e158316cf9c80de7e2bdd5cad5f731cea4fef11303c1c9bd8a
-  data.tar.gz: 7b4e02b683be089a602d10c7fafcb09abc134a9f5b60e5a58a8d0ef42b35bb0ec18555700e0c316ec5de12aae7e5c01a4f0ffede12e26597f1a881fcbb5d50af
+  metadata.gz: ccc1d8b7fc65614ff262c9a84cf431e0a964057426a49e3cd981a38909c85f22752d31bb3b0924f26ccee69eb74487fa41a46a4fef8ab50fcd607cda64f921bd
+  data.tar.gz: 0c0f22e240507331336df50b2ebc8966a4b390ae6728b6ccb86b1628eba228d6a82ffa81db19439d2974d124a015bf06a02770558dec1911b40b22a51d2131e6

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-10-16
+
+### Fixed
+
+- Share native immutable session normalization between Inbox and process admission so real Pi path selectors bind their session UUID without weakening ancestry, foreground owner or live-session checks.
+
+### Changed
+
+- Follow the ace-hitl-contract 0.3 request-envelope line (dependency floor).
+
+## [0.6.0] - 2026-10-16
+
+### Added
+
+- Expose bounded native observations and hold ordinary Inbox delivery settlement through canonical Assign acceptance. Preserve exact targets and unresolved outcomes without repeat sends or alternate execution records.
+
 ## [0.5.1] - 2026-10-10
 
 ### Fixed

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ace
+  module Herdr
+    module Atoms
+      # Herdr reports Pi sessions as paths and Codex sessions as IDs. Both
+      # consumers bind the same immutable UUID; names never identify a session.
+      module NativeAgentSession
+        UUID = /\A[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}\z/
+        PI_PATH = /_([0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12})\.jsonl\z/
+
+        def self.normalize(session, agent:)
+          return nil unless %w[codex pi].include?(agent) && session.is_a?(Hash) && session["agent"] == agent
+
+          value = session["value"]
+          return nil unless value.is_a?(String) && value.valid_encoding? && !value.include?("\0")
+
+          kind = session["kind"]
+          if agent == "pi" && kind == "path"
+            return nil unless value.start_with?("/") && value.bytesize <= 4096
+
+            value = PI_PATH.match(value)&.captures&.first
+            kind = "id"
+          end
+          return nil unless kind == "id" && value.is_a?(String) && UUID.match?(value)
+
+          {"agent" => agent, "kind" => "id", "value" => value}
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/models/delivery_record.rb

@@ -79,6 +79,15 @@ module Ace
           state == "delivered"
         end
 
+        # Exact native submission receipt, not a business completion verdict.
+        def inbox_delivered?
+          return false unless delivered? && inbox.is_a?(Hash)
+          receipt = inbox["receipt"]
+          inbox["claim_generation"].is_a?(Integer) && inbox["claim_generation"].positive? &&
+            receipt.is_a?(Hash) && receipt.values_at("event_id", "attempt_id", "claim_generation", "payload_sha256", "binding") ==
+              [event_id, inbox["attempt_id"], inbox["claim_generation"], answer_digest, inbox["binding"]]
+        end
+
         # A "submitting" history entry without a matching outcome means the
         # previous run crashed between prompt submission and persistence;
         # resending could duplicate the answer, so the outcome is ambiguous.

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "herdr_executor"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Read-only native attribution under one absolute deadline, including all
+      # ancestry probes. Never renew the budget for another process in the chain.
+      class BoundedObservation < HerdrExecutor
+        def initialize(deadline:, binary: DEFAULT_BINARY, process: BoundedProcess)
+          super(binary: binary, process: process)
+          @deadline = deadline
+        end
+
+        def pane_get(pane) = observe!([@binary, "pane", "get", pane])
+        def pane_process_info(pane) = observe!([@binary, "pane", "process-info", "--pane", pane])
+
+        # ProcessIdentity's existing executor seam. Do not let PATH select ps.
+        def capture2(command, *args, stdin_data: "")
+          raise ArgumentError, "observation only permits ps" unless command == "ps" && stdin_data.empty?
+          result = bounded(["/bin/ps", *args])
+          [result.stdout, result.status]
+        end
+
+        private
+
+        def observe!(argv)
+          result = bounded(argv)
+          execution = ExecutionResult.new(stdout: result.stdout.strip, stderr: result.stderr.strip,
+            success: result.status.success?, exit_code: result.status.exitstatus || -1)
+          raise classify(execution, argv) unless execution.success?
+          execution
+        end
+
+        def bounded(argv)
+          remaining = @deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise AgentNotReadyError, "native observation deadline elapsed" unless remaining.positive?
+          result = @process.call(argv, stdin_data: "", timeout_s: remaining,
+            output_limit: WAKE_OUTPUT_LIMIT, cleanup_group: true)
+          raise AgentNotReadyError, "native observation output exceeded limit" if result.oversized
+          result
+        rescue Timeout::Error, BoundedProcess::PostLaunchError
+          raise AgentNotReadyError, "native observation did not complete within its bound"
+        rescue SystemCallError
+          raise ExecutorUnavailableError, "native observation executable unavailable"
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../errors"
+require_relative "../atoms/native_agent_session"
 require "digest"
 require "json"
 require "time"
@@ -22,8 +23,6 @@ module Ace
 
         EVENT = /\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/
         TARGET_IDENTITY = %w[session pane terminal_id agent thread thread_kind].freeze
-        THREAD_ID = /\A[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}\z/
-        PI_PATH = /_([0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12})\.jsonl\z/
         # Single validator for Pi queue event ids, shared by enqueue and
         # delivery observation so the two sites can never disagree again.
         PI_EVENT_ID = /\A(?:inb|wnk)-[a-z0-9-]{8,64}\z/
@@ -172,6 +171,39 @@ module Ace
 
         def context_root = @deliveries_dir.dup.freeze
 
+        # The installed consumer supplies canonical references and native
+        # owner, while this owner holds every existing record lock through the
+        # consumer's acceptance CAS. No delivery/retry/wake is performed here.
+        def with_delivery_settlement(deadline: nil)
+          self.class.with_retained_records(deliveries_dir: @deliveries_dir, deadline: deadline) do |records|
+            verify = lambda do |references:, attempt_id:, owner:|
+              unless references.is_a?(Array) && references.all? { |reference|
+                reference.is_a?(Hash) && reference.keys.sort == %w[attempt_id event_id payload_sha256] &&
+                  reference["attempt_id"] == attempt_id }
+                raise ValidationError, "canonical Inbox references differ"
+              end
+              selected = records.select { |record| record.inbox.fetch("attempt_id") == attempt_id }
+              ids = references.map { |reference| reference.fetch("event_id") }
+              unless ids.uniq == ids && selected.map(&:event_id).sort == ids.sort
+                raise ValidationError, "canonical Inbox reference inventory differs"
+              end
+              next [] if selected.empty?
+              target = target_from_owner(owner)
+              selected.map do |record|
+                reference = references.find { |item| item.fetch("event_id") == record.event_id }
+                binding = record.inbox.fetch("binding", {})
+                unless !record.inbox["original_context"] && record.inbox_delivered? && record.answer_digest == reference.fetch("payload_sha256") &&
+                    record.inbox["origin_target"] == target && binding.slice(*target.keys) == target &&
+                    binding["payload_sha256"] == record.answer_digest && %w[none sent].include?(record.inbox.dig("wake", "status"))
+                  raise ValidationError, "original Inbox delivery or wake remains unsettled"
+                end
+                reference.merge("claim_generation" => record.inbox.fetch("claim_generation"))
+              end
+            end
+            yield verify
+          end
+        end
+
 
         def enqueue(event:, attempt:, ref:, payload:, managed_envelope: nil, expected_target: nil, original_context: nil, original_binding_digest: nil)
           validate_id!(event, "event")
@@ -544,7 +576,7 @@ module Ace
         def validate_expected_target!(target)
           unless target.is_a?(Hash) && TARGET_IDENTITY.all? { |key| target[key].is_a?(String) && !target[key].empty? } &&
               %w[codex pi].include?(target["agent"]) && target["thread_kind"] == "id" &&
-              THREAD_ID.match?(target["thread"]) && target["terminal_id"].bytesize <= 64
+              Atoms::NativeAgentSession::UUID.match?(target["thread"]) && target["terminal_id"].bytesize <= 64
             raise ValidationError, "accepted original native target is incomplete or invalid"
           end
         end
@@ -594,21 +626,12 @@ module Ace
           raise ValidationError, "unsupported native agent" unless %w[codex pi].include?(agent)
           session = pane["agent_session"]
           raise IdentityDriftError, "native session identity is unavailable" unless session.is_a?(Hash) && session["agent"] == agent
-          thread = session["value"].to_s
-          kind = session["kind"]
-          if agent == "pi" && kind == "path"
-            thread = PI_PATH.match(thread)&.captures&.first.to_s
-            kind = "id"
-          end
-          # Only an immutable session UUID may carry a binding: a name
-          # survives an agent restart in the same pane/terminal, so a reused
-          # session could inherit an old event.
-          unless kind == "id" && THREAD_ID.match?(thread)
+          normalized = Atoms::NativeAgentSession.normalize(session, agent: agent)
+          unless normalized
             raise ValidationError,
-              "native queue binding requires an immutable session id " \
-              "(got #{kind.inspect})"
+              "native queue binding requires an immutable session id (got #{session['kind'].inspect})"
           end
-          raise ValidationError, "Pi queue requires a session ID" if agent == "pi" && kind != "id"
+          thread, kind = normalized.values_at("value", "kind")
           raw_terminal = pane["terminal_id"]
           terminal = raw_terminal.to_s.strip if raw_terminal.is_a?(String) || raw_terminal.is_a?(Integer)
           if terminal.nil? || terminal.empty? || terminal.bytesize > 64

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

@@ -378,12 +378,7 @@ module Ace
         end
 
         def completed_record?(record)
-          return false unless record.state == "delivered" && record.inbox.is_a?(Hash)
-          inbox = record.inbox
-          receipt = inbox["receipt"]
-          inbox["claim_generation"].is_a?(Integer) && inbox["claim_generation"].positive? &&
-            receipt.is_a?(Hash) && receipt.values_at("event_id", "attempt_id", "claim_generation", "payload_sha256", "binding") ==
-              [record.event_id, inbox["attempt_id"], inbox["claim_generation"], record.answer_digest, inbox["binding"]]
+          record.inbox_delivered?
         end
 
         def expected!(state, expected)

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

@@ -4,6 +4,7 @@ require "ace/runtime"
 require "digest"
 require "fileutils"
 require "json"
+require_relative "../atoms/native_agent_session"
 
 module Ace
   module Herdr
@@ -124,12 +125,10 @@ module Ace
               process.is_a?(Hash) && process["pid"] == owner.dig("process_identity", "pid")
             end
 
-            session = native["agent_session"]
+            session = Atoms::NativeAgentSession.normalize(native["agent_session"], agent: native["agent"])
             workspace = native["workspace_id"] || native["session_id"]
             terminal = native["terminal_id"]
-            next nil unless session.is_a?(Hash) && session["kind"] == "id" &&
-              session["value"].is_a?(String) && session["value"].match?(Inbox::THREAD_ID) &&
-              session["agent"] == native["agent"] && native["agent"].is_a?(String) &&
+            next nil unless session &&
               workspace.is_a?(String) && !workspace.empty? &&
               (terminal.is_a?(String) || terminal.is_a?(Integer)) && !terminal.to_s.empty?
 

data/lib/ace/herdr/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Herdr
-    VERSION = "0.5.1"
+    VERSION = "0.6.1"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-herdr
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: websocket-driver
@@ -49,14 +49,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: ace-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -219,6 +219,7 @@ files:
 - lib/ace/herdr.rb
 - lib/ace/herdr/atoms/answer_digest.rb
 - lib/ace/herdr/atoms/json_find.rb
+- lib/ace/herdr/atoms/native_agent_session.rb
 - lib/ace/herdr/cli.rb
 - lib/ace/herdr/cli/commands/capture.rb
 - lib/ace/herdr/cli/commands/close.rb
@@ -237,6 +238,7 @@ files:
 - lib/ace/herdr/errors.rb
 - lib/ace/herdr/models/delivery_record.rb
 - lib/ace/herdr/models/dispatch_outcome.rb
+- lib/ace/herdr/molecules/bounded_observation.rb
 - lib/ace/herdr/molecules/bounded_process.rb
 - lib/ace/herdr/molecules/delivery_record_store.rb
 - lib/ace/herdr/molecules/guarded_native_origin.rb