ace-herdr 0.2.0 → 0.3.0

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module Ace
+  module Herdr
+    module Molecules
+      # The provider-native submission boundary. A failed process does not
+      # prove that a message was not accepted, so only validation failures
+      # raised before this boundary are retryable without reconciliation.
+      #
+      # Child processes run under BoundedProcess: the deadline is enforced at
+      # the child boundary (process-group kill), never via a cleanup-blocking
+      # Timeout.timeout around capture3, so a stalled child cannot hold the
+      # inbox event lock past the configured timeout.
+      class NativeQueueExecutor
+        DEFAULT_SUBMIT_TIMEOUT_S = 60
+        DEFAULT_IDENTITY_TIMEOUT_S = 20
+        # Codex payloads ride in argv; a single argument beyond the OS
+        # per-argument limit fails at exec with E2BIG — before any client
+        # code ran — so the payload is bounded pre-launch and any E2BIG
+        # escape is classified as a proven pre-submission rejection.
+        MAX_ARG_PAYLOAD_BYTES = 65_536
+        PI_PAYLOAD_LIMIT_BYTES = 65_536
+
+        # runner: test seam. Callable (argv, stdin_data:, timeout_s:) ->
+        # [stdout, stderr, status]. Defaults to the bounded runner.
+        def initialize(codex: "codex", pi_client: nil, runner: nil,
+          submit_timeout_s: DEFAULT_SUBMIT_TIMEOUT_S,
+          identity_timeout_s: DEFAULT_IDENTITY_TIMEOUT_S)
+          @codex = codex
+          @pi_client = pi_client || ENV["ACE_HERDR_PI_QUEUE_CLIENT"] || "pi-overseer-queue-client"
+          @runner = runner
+          @submit_timeout_s = submit_timeout_s
+          @identity_timeout_s = identity_timeout_s
+        end
+
+        def pi_identity
+          result = execute([@pi_client, "--identity"], stdin_data: "",
+            timeout_s: @identity_timeout_s)
+          raise ExecutorError, "Pi identity probe failed: #{result.stderr}" unless result.status.success?
+
+          identity = JSON.parse(result.stdout)
+          raise ExecutorError, "Pi identity probe returned invalid JSON" unless identity.is_a?(Hash)
+
+          identity.fetch("session_id")
+        rescue Errno::ENOENT, Errno::EACCES => e
+          raise ExecutorUnavailableError, e.message
+        rescue JSON::ParserError, KeyError, TypeError
+          raise ExecutorError, "Pi identity probe returned invalid JSON"
+        rescue Timeout::Error
+          raise ExecutorError, "Pi identity probe timed out"
+        end
+
+        def submit(agent:, thread:, event_id:, digest:, payload:)
+          if agent == "pi" && (payload.empty? || payload.bytesize > PI_PAYLOAD_LIMIT_BYTES)
+            return {"accepted" => false, "pre_submit" => true, "error" => "Pi payload must be 1..65536 bytes"}
+          end
+          if agent == "codex" && payload.bytesize > MAX_ARG_PAYLOAD_BYTES
+            return {"accepted" => false, "pre_submit" => true,
+                    "error" => "Codex payload must be at most #{MAX_ARG_PAYLOAD_BYTES} bytes for argv delivery"}
+          end
+          argv = if agent == "codex"
+            [@codex, "queue", "--thread", thread, "--message", payload]
+          elsif agent == "pi"
+            [@pi_client, "--delivery", event_id, "--session-id", thread,
+              "--payload-sha256", digest, "--payload-bytes", payload.bytesize.to_s]
+          else
+            raise ValidationError, "unsupported native queue agent: #{agent}"
+          end
+          result = execute(argv, stdin_data: agent == "pi" ? payload : "",
+            timeout_s: @submit_timeout_s)
+          raise ExecutorError, "native queue output exceeded the retained limit" if result.oversized
+          unless result.status.success?
+            return {"accepted" => false, "exit_code" => result.status.exitstatus,
+                    "error" => result.stderr.strip}
+          end
+
+          if agent == "pi"
+            receipt = JSON.parse(result.stdout)
+            unless receipt.is_a?(Hash) && receipt["ok"] == true && receipt["id"] == event_id &&
+                receipt["session_id"] == thread && receipt["payload_sha256"] == digest
+              return {"accepted" => false, "error" => "Pi queue receipt identity or digest mismatch"}
+            end
+          end
+          {"accepted" => true, "exit_code" => result.status.exitstatus, "stdout" => result.stdout.strip}
+        rescue Errno::ENOENT, Errno::EACCES, Errno::E2BIG, ExecutorUnavailableError => e
+          # The executable never launched (or exec rejected the argv). No
+          # submission could have occurred, so this stays retryable.
+          {"accepted" => false, "pre_submit" => true, "error" => e.message}
+        rescue JSON::ParserError
+          {"accepted" => false, "error" => "Pi queue returned invalid receipt JSON"}
+        rescue Timeout::Error
+          {"accepted" => false, "error" => "native queue timed out after submission may have begun"}
+        end
+
+        private
+
+        def execute(argv, stdin_data:, timeout_s:)
+          if @runner
+            stdout, stderr, status = @runner.call(argv, stdin_data: stdin_data, timeout_s: timeout_s)
+            return BoundedProcess::Result.new(stdout, stderr, status, false)
+          end
+
+          BoundedProcess.call(argv, stdin_data: stdin_data, timeout_s: timeout_s)
+        rescue SystemCallError => e
+          # popen3 raises spawn failures before the child exists, so no
+          # submission can have begun: proven pre-launch, retryable.
+          # (Post-launch I/O failures arrive as PostLaunchError instead.)
+          raise ExecutorUnavailableError, e.message
+        rescue BoundedProcess::PostLaunchError => e
+          # The child was live, so the message may already have been accepted:
+          # keep this uncertain, never pre-submit retryable.
+          raise ExecutorError, e.message
+        end
+      end
+    end
+  end
+end

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

@@ -81,6 +81,7 @@ module Ace
 
           Molecules::DeliveryRecordStore.with_lock(@deliveries_dir, event_id) do
             record = Molecules::DeliveryRecordStore.load(@deliveries_dir, event_id)
+            raise ValidationError, "event belongs to the agent inbox" if record&.inbox
             validate_existing_record(record, ref, digest) if record
             record ||= Models::DeliveryRecord.new(
               event_id: event_id, session: ref.session, pane: ref.pane,
@@ -98,6 +99,7 @@ module Ace
           validate_event_id!(event_id)
           Molecules::DeliveryRecordStore.with_lock(@deliveries_dir, event_id) do
             record = Molecules::DeliveryRecordStore.load(@deliveries_dir, event_id)
+            raise ValidationError, "event belongs to the agent inbox" if record&.inbox
             if record.nil? || record.answer.to_s.empty?
               raise ValidationError,
                 "no recoverable answer stored for event #{event_id.inspect}"

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

@@ -0,0 +1,484 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "time"
+require "securerandom"
+require "openssl"
+require "ace/hitl"
+
+module Ace
+  module Herdr
+    module Organisms
+      # Durable event inbox. All transitions for one event are serialized by
+      # DeliveryRecordStore; a saved submission intent is never replayed.
+      class Inbox
+        class IdentityDriftError < ValidationError; end
+
+        EVENT = /\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/
+        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/
+        # Agent statuses herdr reports (pane observations use busy; agent wait
+        # also names working/blocked). Anything else — including an explicit
+        # "unknown" — is undetermined and stays a retryable pre-submission
+        # rejection.
+        AGENT_STATUSES = %w[idle busy working blocked done].freeze
+        WAKE_STATUSES = %w[idle done].freeze
+
+        def initialize(executor:, native:, deliveries_dir:, receipt_public_key: nil)
+          @executor = executor
+          @native = native
+          @deliveries_dir = deliveries_dir
+          @receipt_public_key = receipt_public_key
+        end
+
+        def enqueue(event:, attempt:, ref:, payload:)
+          validate_id!(event, "event")
+          validate_id!(attempt, "attempt")
+          raise ValidationError, "trusted receipt public key is unavailable" unless @receipt_public_key
+          payload = payload.to_s
+          raise ValidationError, "payload is required" if payload.empty?
+          raise ValidationError, "payload contains NUL" if payload.include?("\0")
+          # Callers may hand over binary-tagged bytes; persistence is JSON, so
+          # the payload must decode as UTF-8 regardless of its source tag.
+          payload = payload.dup.force_encoding(Encoding::UTF_8)
+          unless payload.valid_encoding?
+            raise ValidationError, "payload is not valid UTF-8 text"
+          end
+
+          address = address_for(ref)
+          digest = Digest::SHA256.hexdigest(payload)
+          with_event(event) do |record|
+            if record
+              validate_match!(record, attempt, address, digest)
+              next public_record(record)
+            end
+
+            target = observe_target(address.session, address.pane)
+            if target["agent"] == "pi" && !PI_EVENT_ID.match?(event)
+              raise ValidationError,
+                "Pi queue requires an inbox (inb-) or wake (wnk-) event id with at " \
+                "least 8 id characters; the id is immutable once enqueued"
+            end
+            payload_limit = target["agent"] == "pi" ?
+              Molecules::NativeQueueExecutor::PI_PAYLOAD_LIMIT_BYTES :
+              Molecules::NativeQueueExecutor::MAX_ARG_PAYLOAD_BYTES
+            if payload.bytesize > payload_limit
+              raise ValidationError,
+                "payload exceeds the #{target['agent']} native queue limit " \
+                "of #{payload_limit} bytes and could never be delivered"
+            end
+            record = Models::DeliveryRecord.new(
+              event_id: event, session: address.session, pane: address.pane,
+              answer_digest: digest, answer: payload, state: "queued",
+              inbox: {"attempt_id" => attempt, "claim_generation" => 0,
+                "receipt_key_sha256" => key_fingerprint,
+                "target" => target, "binding" => target.merge("payload_sha256" => digest)}
+            )
+            save(record)
+            public_record(record)
+          end
+        end
+
+        def status(event:)
+          validate_id!(event, "event")
+          with_event(event) do |record|
+            raise ValidationError, "unknown inbox event: #{event}" unless record&.inbox
+
+            public_record(record)
+          end
+        end
+
+        def deliver(event:)
+          validate_id!(event, "event")
+          with_event(event) do |record|
+            raise ValidationError, "unknown inbox event: #{event}" unless record&.inbox
+            next retry_wake(record) if record.state == "delivered" && wake_pending?(record)
+            next public_record(record) if %w[delivered completed uncertain].include?(record.state)
+            unless record.state == "queued"
+              if record.inbox["submission_intent"]
+                # A previous owner crashed after saving submission intent:
+                # the submission boundary is unknown to a new process.
+                record = transition(record, "uncertain", record.inbox,
+                  "orphan-claim", "claim owner ended after submission intent")
+              else
+                # The claim was saved before any submission intent existed,
+                # so no submission could have started: provably pre-send.
+                record = transition(record, "queued", record.inbox.reject { |key, _| key == "claim_owner" },
+                  "claim-recovery", "claim owner ended before submission intent")
+              end
+              save(record)
+              next public_record(record)
+            end
+
+            claim = record.inbox.merge(
+              "claim_owner" => "#{Process.pid}:#{SecureRandom.hex(8)}",
+              "claim_generation" => record.inbox.fetch("claim_generation", 0) + 1
+            )
+            record = transition(record, "claimed", claim, "claim")
+            save(record)
+
+            begin
+              binding = observe(record)
+            rescue ValidationError, ExecutorError => e
+              state = e.is_a?(IdentityDriftError) ? "uncertain" : "queued"
+              record = transition(record, state, claim.merge("last_error" => e.message),
+                state == "uncertain" ? "identity-drift" : "pre-submit-rejection", e.message)
+              save(record)
+              next public_record(record)
+            end
+
+            target = binding.reject { |key, _| key == "payload_sha256" }
+            bound = claim.merge("binding" => binding, "target" => target)
+            record = transition(record, "claimed", bound, "bind")
+            save(record)
+            # No later process may infer from a claimed record that submission
+            # did not occur. Persist intent immediately before the native call.
+            intent = bound.merge("submission_intent" => true)
+            record = transition(record, "uncertain", intent, "submit-intent")
+            save(record)
+
+            result = submit(record, binding)
+            if result["pre_submit"]
+              # Missing executable is the only proven pre-submission error.
+              record = transition(record, "queued", bound.merge("last_error" => result["error"]),
+                "pre-submit-rejection", result["error"])
+            elsif result["accepted"]
+              receipt = {"event_id" => event, "attempt_id" => bound["attempt_id"],
+                "claim_generation" => bound["claim_generation"],
+                "payload_sha256" => record.answer_digest, "binding" => binding,
+                "native_output" => result["stdout"]}
+              # The wake is a separate effect from the accepted submission,
+              # but its DECISION rides the first delivered transition: a crash
+              # between saves must never leave the wake field missing (which
+              # later reads as pending) for a busy target.
+              wake = if WAKE_STATUSES.include?(binding["agent_status"])
+                {"status" => "pending"}
+              else
+                {"status" => "none", "reason" => "busy target uses the native queue form"}
+              end
+              record = transition(record, "delivered",
+                intent.merge("receipt" => receipt).merge("wake" => wake), "accepted")
+              save(record)
+              # A pending wake is attempted after the decision is durable, so
+              # a crash or transient failure can be recovered by a later
+              # deliver call without ever resubmitting the message.
+              record = attempt_wake(record, binding) if wake["status"] == "pending"
+            else
+              record = transition(record, "uncertain", intent.merge("last_error" => result["error"]),
+                "submission-uncertain", result["error"])
+            end
+            save(record)
+            public_record(record)
+          end
+        end
+
+        def reconcile(event:, receipt:, signed_bytes: nil, signature: nil)
+          validate_id!(event, "event")
+          with_event(event) do |record|
+            raise ValidationError, "unknown inbox event: #{event}" unless record&.inbox
+            # `delivered` only proves native queue acceptance: the message may
+            # still be consumed or evicted afterwards, so a signed observation
+            # can reconcile it exactly like an uncertain outcome.
+            unless %w[uncertain delivered].include?(record.state)
+              raise ValidationError, "event is not reconcilable from state #{record.state}"
+            end
+            binding = record.inbox["binding"]
+            matches = receipt.is_a?(Hash) && receipt["event_id"] == event &&
+              receipt["attempt_id"] == record.inbox["attempt_id"] &&
+              receipt["claim_generation"] == record.inbox["claim_generation"] &&
+              receipt["payload_sha256"] == record.answer_digest &&
+              receipt["binding"] == binding
+            refusal = if !binding
+              "event has no verified binding"
+            elsif !matches
+              "reconciliation receipt does not match bound event"
+            end
+            refusal ||= proof_refusal(receipt) if receipt.is_a?(Hash)
+            refusal ||= signature_refusal(record, receipt, signed_bytes, signature)
+            replacement = nil
+            if !refusal && receipt["outcome"] == "superseded" && receipt.key?("replacement_target")
+              replacement = receipt["replacement_target"]
+              observed = begin
+                raise ValidationError, "replacement target must be an object" unless replacement.is_a?(Hash)
+
+                address = address_for(replacement)
+                observe_target(address.session, address.pane)
+              rescue ValidationError, ExecutorError, Ace::Hitl::Providers::InvalidRefError => e
+                refusal = "replacement target cannot be verified: #{e.message}"
+                nil
+              end
+              stable = %w[session pane terminal_id agent thread thread_kind]
+              unless replacement.is_a?(Hash) && observed &&
+                  stable.all? { |key| replacement[key] == observed[key] }
+                refusal ||= "replacement target does not match the live native session"
+              end
+              # The replacement agent's own delivery rules must admit this
+              # event: its immutable-id requirement and payload bound.
+              if observed
+                if observed["agent"] == "pi" && !PI_EVENT_ID.match?(event)
+                  refusal ||= "replacement pi target requires an inbox (inb-) or wake (wnk-) event id"
+                end
+                payload_limit = observed["agent"] == "pi" ?
+                  Molecules::NativeQueueExecutor::PI_PAYLOAD_LIMIT_BYTES :
+                  Molecules::NativeQueueExecutor::MAX_ARG_PAYLOAD_BYTES
+                if record.answer.to_s.bytesize > payload_limit
+                  refusal ||= "payload exceeds the replacement agent's native queue limit"
+                end
+              end
+            end
+            next public_record(record).merge("reconciliation_refusal" => refusal) if refusal
+
+            outcome = receipt["outcome"]
+            state = outcome == "consumed" ? "completed" : "queued"
+            inbox = record.inbox.merge("reconciliation" => receipt)
+            if state == "queued"
+              inbox = inbox.reject do |key, _|
+                %w[submission_intent claim_owner receipt].include?(key)
+              end
+              inbox = inbox.merge("target" => replacement) if replacement
+            end
+            record = transition(record, state, inbox, "reconcile-#{outcome}")
+            save(record)
+            public_record(record)
+          end
+        end
+
+        private
+
+        def key_fingerprint
+          Digest::SHA256.hexdigest(@receipt_public_key.public_to_der)
+        end
+
+        def signature_refusal(record, receipt, signed_bytes, signature)
+          return "trusted receipt public key is unavailable" unless @receipt_public_key
+          unless record.inbox["receipt_key_sha256"] == key_fingerprint
+            return "trusted receipt public key differs from the enqueued event"
+          end
+          return "receipt signature is missing" unless signed_bytes.is_a?(String) && signature.is_a?(String)
+          return "signed receipt content differs from parsed receipt" unless JSON.parse(signed_bytes) == receipt
+          return "receipt signature is invalid" unless @receipt_public_key.verify(
+            OpenSSL::Digest::SHA256.new, signature, signed_bytes)
+
+          nil
+        rescue JSON::ParserError, OpenSSL::PKey::PKeyError
+          "receipt signature is invalid"
+        end
+
+        # The receipt is an explicit operator or supervisor attestation of a
+        # native outcome. Native queue submission alone cannot prove consumption
+        # or nonconsumption; an absent or incomplete attestation is never retried.
+        def proof_refusal(receipt)
+          return "invalid reconciliation outcome" unless %w[consumed superseded].include?(receipt["outcome"])
+          observer = receipt["observer"]
+          unless observer.is_a?(Hash) && %w[operator supervisor].include?(observer["role"]) &&
+              observer["id"].is_a?(String) && !observer["id"].strip.empty?
+            return "receipt requires an identified operator or supervisor"
+          end
+          evidence = receipt["evidence"]
+          kinds = receipt["outcome"] == "consumed" ? %w[consumed_acknowledged] :
+            %w[queue_evicted queue_expired thread_replaced]
+          unless evidence.is_a?(Hash) && kinds.include?(evidence["kind"]) &&
+              evidence["native_reference"].is_a?(String) && !evidence["native_reference"].strip.empty? &&
+              evidence["observation"].is_a?(String) && !evidence["observation"].strip.empty?
+            return "receipt requires a native outcome observation and reference"
+          end
+          nil
+        end
+
+        def with_event(event)
+          Molecules::DeliveryRecordStore.with_lock(@deliveries_dir, event) do
+            yield Molecules::DeliveryRecordStore.load(@deliveries_dir, event)
+          end
+        end
+
+        def save(record)
+          Molecules::DeliveryRecordStore.save(record, @deliveries_dir)
+        end
+
+        def transition(record, state, inbox, action, error = nil)
+          detail = {"action" => action}
+          detail["error"] = error if error && !error.empty?
+          record.advance_inbox(state: state, inbox: inbox, detail: detail, timestamp: Time.now.utc.iso8601)
+        end
+
+        def validate_id!(value, name)
+          raise ValidationError, "invalid #{name} id" unless value.is_a?(String) && EVENT.match?(value)
+        end
+
+        def address_for(ref)
+          hash = ref.is_a?(Hash) ? ref : JSON.parse(File.read(ref))
+          raise ValidationError, "invalid ref: expected a JSON object" unless hash.is_a?(Hash)
+          Ace::Hitl::Providers::Ref.new(
+            session: Ace::Hitl::Providers::Ref.validate!(hash.fetch("session"), "session"),
+            pane: Ace::Hitl::Providers::Ref.validate!(hash.fetch("pane"), "pane")
+          )
+        rescue Errno::ENOENT, JSON::ParserError, KeyError, TypeError => e
+          raise ValidationError, "invalid ref: #{e.message}"
+        end
+
+        def validate_match!(record, attempt, address, digest)
+          unless record.inbox && record.inbox["attempt_id"] == attempt &&
+              record.session == address.session && record.pane == address.pane &&
+              record.answer_digest == digest
+            raise ValidationError, "event identity, attempt, target, or payload digest conflicts"
+          end
+        end
+
+        def observe(record)
+          target = record.inbox["target"]
+          binding = observe_target(target ? target["session"] : record.session,
+            target ? target["pane"] : record.pane, target: target)
+          # Target drift is classified BEFORE agent-specific event id rules:
+          # a bound event whose pane changed agent (e.g. codex -> pi) must
+          # reconcile, not loop on a pre-send validation error.
+          stable = %w[session pane terminal_id agent thread thread_kind]
+          if target && !stable.all? { |key| target[key] == binding[key] }
+            raise IdentityDriftError, "target identity changed since enqueue; reconciliation is required"
+          end
+          if binding["agent"] == "pi" && !PI_EVENT_ID.match?(record.event_id)
+            raise ValidationError, "Pi queue requires an inbox or wake event ID"
+          end
+          binding.merge("payload_sha256" => record.answer_digest)
+        end
+
+        def observe_target(expected_session, expected_pane, target: nil)
+          payload = @executor.pane_get_bounded(expected_pane).parsed_json
+          # Shape-check each level: parseable but malformed probe JSON must
+          # fail as a validation error, never as a TypeError that would
+          # strand the event in claimed.
+          result = payload.is_a?(Hash) ? payload["result"] : nil
+          pane = result.is_a?(Hash) ? result["pane"] : nil
+          raise ValidationError, "pane observation is unavailable" unless pane.is_a?(Hash)
+          raise IdentityDriftError, "pane identity changed" unless pane["pane_id"] == expected_pane
+          observed_session = pane["workspace_id"] || pane["session_id"]
+          raise IdentityDriftError, "runtime session identity changed" unless observed_session == expected_session
+          agent = pane["agent"]
+          # An agent change is target drift: classify it as reconciliation-
+          # worthy before any agent-specific validation can mask it.
+          if target && target["agent"] != agent
+            raise IdentityDriftError, "target identity changed since enqueue; reconciliation is required"
+          end
+          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)
+            raise ValidationError,
+              "native queue binding requires an immutable session id " \
+              "(got #{kind.inspect})"
+          end
+          raise ValidationError, "Pi queue requires a session ID" if agent == "pi" && kind != "id"
+          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
+            raise ValidationError, "durable terminal identity is unavailable"
+          end
+          if agent == "pi" && @native.pi_identity != thread
+            raise IdentityDriftError, "live Pi session identity differs"
+          end
+          status = pane["agent_status"].to_s
+          unless AGENT_STATUSES.include?(status)
+            # An undetermined status cannot decide the wake form; fail the
+            # submission provably before the submission boundary (retryable).
+            raise ValidationError, "native agent status is unrecognized: #{status.inspect}"
+          end
+          {"session" => expected_session, "pane" => expected_pane, "terminal_id" => terminal,
+           "agent" => agent, "thread" => thread, "thread_kind" => kind,
+           "agent_status" => status}
+        end
+
+        def submit(record, binding)
+          @native.submit(agent: binding["agent"], thread: binding["thread"],
+            event_id: record.event_id, digest: record.answer_digest, payload: record.answer)
+        rescue ExecutorError => e
+          {"accepted" => false, "error" => e.message}
+        end
+
+        # A delivered record still owes its idle wake after a crash (no wake
+        # entry) or a transient failure (status pending). Re-verify the live
+        # target first — identity drift demotes the event to uncertain — then
+        # retry the payload-free wake. The native payload is never resubmitted.
+        def retry_wake(record)
+          begin
+            binding = observe(record)
+          rescue IdentityDriftError => e
+            record = transition(record, "uncertain", record.inbox.merge("last_error" => e.message),
+              "identity-drift", e.message)
+            save(record)
+            return public_record(record)
+          rescue ExecutorError, ValidationError => e
+            record = transition(record, "delivered",
+              record.inbox.merge("wake" => record.inbox.fetch("wake", {"status" => "pending"})
+                .merge("status" => "pending", "error" => e.message)),
+              "wake-retry-blocked", e.message)
+            save(record)
+            return public_record(record)
+          end
+          unless WAKE_STATUSES.include?(binding["agent_status"])
+            # The live target works on its native queue; no prompt is owed.
+            record = transition(record, "delivered",
+              record.inbox.merge("wake" => {"status" => "none",
+                "reason" => "busy target uses the native queue form"}), "wake-none")
+            save(record)
+            return public_record(record)
+          end
+          public_record(attempt_wake(record, binding))
+        end
+
+        def wake_pending?(record)
+          wake = record.inbox["wake"]
+          wake.nil? || wake["status"] == "pending"
+        end
+
+        def attempt_wake(record, binding)
+          wake_error = wake_idle(binding)
+          wake = if wake_error
+            {"status" => "pending", "error" => wake_error}
+          else
+            {"status" => "sent"}
+          end
+          detail = wake_error ? "wake-failed" : "wake-sent"
+          saved = transition(record, "delivered",
+            record.inbox.merge("wake" => wake).compact, detail, wake_error)
+          save(saved)
+          saved
+        end
+
+        def wake_idle(binding)
+          @executor.agent_prompt_bounded(pane: binding["pane"],
+            text: "Check your native queued messages.", timeout_ms: 10_000)
+          nil
+        rescue StandardError => e
+          e.message
+        end
+
+        def public_record(record)
+          {"event_id" => record.event_id, "attempt_id" => record.inbox["attempt_id"],
+           "session" => record.session, "pane" => record.pane,
+           "payload_sha256" => record.answer_digest, "state" => record.state,
+           "receipt_key_sha256" => record.inbox["receipt_key_sha256"],
+           "claim_generation" => record.inbox["claim_generation"],
+           "claim_owner" => record.inbox["claim_owner"],
+           "submission_intent" => !!record.inbox["submission_intent"],
+           "target" => record.inbox["target"],
+           "binding" => record.inbox["binding"], "receipt" => record.inbox["receipt"],
+           "reconciliation" => record.inbox["reconciliation"],
+           "wake" => record.inbox["wake"],
+           "last_error" => record.inbox["last_error"]}
+        end
+      end
+    end
+  end
+end

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

@@ -90,7 +90,7 @@ module Ace
             record = entry[:record]
             if record.nil?
               report[:deliveries][:preserved] << {event_id: event_id, reason: "unreadable"}
-            elsif record.state != "delivered"
+            elsif record.inbox || record.state != "delivered"
               report[:deliveries][:protected] << {event_id: event_id, state: record.state}
             elsif (updated_at = parse_updated_at(record))
               entry = {event_id: event_id, updated_at: record.updated_at}
@@ -138,7 +138,7 @@ module Ace
               fresh = @record_store.load_revalidated(@deliveries_dir, event_id)
               if fresh == :unreadable
                 outcome = {reason: "unreadable"}
-              elsif fresh&.delivered? && older_than_retention?(fresh)
+              elsif fresh&.delivered? && !fresh.inbox && older_than_retention?(fresh)
                 outcome = {archive_path: @record_store.archive(@deliveries_dir, event_id)}
               end
             end

data/lib/ace/herdr/version.rb

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

data/lib/ace/herdr.rb

@@ -38,12 +38,15 @@ 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/bounded_process"
 require_relative "herdr/molecules/herdr_executor"
+require_relative "herdr/molecules/native_queue_executor"
 require_relative "herdr/molecules/pane_tidy_probe"
 require_relative "herdr/molecules/delivery_record_store"
 require_relative "herdr/molecules/preset_loader"
 require_relative "herdr/molecules/preset_resolver"
 require_relative "herdr/organisms/deliverer"
+require_relative "herdr/organisms/inbox"
 require_relative "herdr/organisms/dispatcher"
 require_relative "herdr/organisms/control_surface"
 require_relative "herdr/organisms/runtime_adapter"