ace-herdr 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6c7f32e364c4df76447fd6d4356f2117007cf920dc3f2f420bd4dd1e21f8242
-  data.tar.gz: 783dd62904dd12e952528d80d9956511c052fcf23a53551b390f5817bbe93c8c
+  metadata.gz: 4e0747847d9a56e36a452fd156063284154be0c5eb6464b9acca559fba504750
+  data.tar.gz: 2dd3be6a92a0217c2ec0d194a83714c0b6cbc22856c4df0ba7bb99f4f0a02810
 SHA512:
-  metadata.gz: bd865086e653b9f8bed7434073707fb733f0f9f0f08c6d979046476ee955a65a2938e7efbad966942fe2a55b68b80c7bbc6a53076601bdaac4cb0ff94029e099
-  data.tar.gz: '08c29e0f0cfb5fa1857959c1fd0ef05376ce3dcc895e6ee6a056e2b3be58c00311e5d0b397e07f063bc94151bb3567441c9e1213bf11e6ea16ea570e8e3fa010'
+  metadata.gz: dc0422a8f818acfb8ad055543ef95938bd41bc988622e527dcffccbf0e757456f4b9aef47ab141eda71eb97fd1d55311d836b2f0f6fc2f04d6ac2f50f56a5c80
+  data.tar.gz: 98c840541c5d15bc6241f1a7bf0535567b34386fe441fdb14c97be8d1a98413a9777151807d4f142504d725871905b77144d89a2622b64f32e85e384b74daaa1

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-05
+
+### Fixed
+- Use the shared typed reverse-reference pair at CLI, Inbox and delivery boundaries, refusing malformed persisted targets and noncanonical serialized files before claim or native observation.
+- Pin managed delivery to the accepted original native target under the event lock and reject secret-bearing payloads even without a nested message.
+
+### Changed
+
+- Declare the required direct dependencies and minimum producer versions for this coordinated release: `ace-hitl-contract ~> 0.2`, `ace-runtime ~> 0.2`.
+- Bind protected control to the canonical per-attempt server/socket identity while retaining the fixed native executable view selected by installation verification.
+- Validate and preserve the shared managed delivery envelope at Inbox enqueue, rejecting mismatched scope/digest/correlation and changed replay metadata.
+
+### Added
+
+- Add protected Herdr control pinned to the installed server/socket and fixed workspace, creating one fresh bootstrap pane with exact child observation and no default shell.
+
+- Expose verified native process/session ownership and allow identical signed inbox proof re-verification after settlement without duplicate transitions.
+
 ## [0.3.2] - 2026-10-04
 
 ### Changed

data/docs/usage.md

@@ -48,13 +48,20 @@ Native `agent_blocked` becomes `SendRejectedError`; `agent_prompt_stalled` becom
 
 Use a stable event ID for one message and the assignment attempt that owns it. The reverse-address JSON contains `session` and `pane`, as with `deliver`.
 
+Reverse references use the shared `ace.hitl.ref/v1` pair contract. Herdr token names
+remain valid; the codec also preserves paired native tmux IDs (`$0`/`%0`) when
+carried by managed metadata. Mixed native/token or cross-field IDs refuse.
+Wire and persisted references must be canonical. Syntax acceptance does not add
+tmux execution to this Herdr controller or replace its exact native ownership,
+target and signed receipt checks.
+
 ```bash
 ace-herdr inbox enqueue --event inb-12345678 --attempt ATTEMPT --ref ref.json --file prompt.txt
 ace-herdr inbox status --event inb-12345678 --format json
 ace-herdr inbox deliver --event inb-12345678
 ```
 
-`enqueue` checks the live pane, durable terminal, agent kind, and native thread identity. Repeating the same event, attempt, target, and payload returns its existing record; a changed value is an error. `deliver` claims the record once. Idle and busy Codex or Pi agents receive an exact-session native queue submission. After an accepted idle submission, Herdr sends a generic wake prompt without the inbox payload. A pane replacement can receive at most that generic wake, never the payload. The JSON result includes `state`, `claim_generation`, `binding`, `last_error`, and any submission receipt.
+`enqueue` checks the live pane, durable terminal, agent kind, and native thread identity. Managed API callers must supply `expected_target`, projected from the accepted runtime owner with `Inbox#target_from_owner`; the live observation must equal that original session/pane/terminal/agent/thread identity under the event lock. The immutable `origin_target` survives retries and signed replacement of the current target. Managed payloads are checked for secret shapes before persistence, including envelopes without a nested message. Repeating the same event, attempt, target, and payload returns its existing record; a changed value is an error. `deliver` claims the record once. Idle and busy Codex or Pi agents receive an exact-session native queue submission. After an accepted idle submission, Herdr sends a generic wake prompt without the inbox payload. A pane replacement can receive at most that generic wake, never the payload. The JSON result includes `state`, `claim_generation`, `binding`, `last_error`, and any submission receipt.
 
 `queued` can be retried after a proven pre-submission rejection. `delivered` means native submission was accepted; it does not mean the agent consumed the message. A crash after claim, changed target identity, or a native result without a verified acceptance receipt is `uncertain`; another `deliver` call does not resend it. A `completed` record has a positively verified consumption receipt. A superseded uncertain record can return to `queued` only after positive nonconsumption proof.
 
@@ -364,3 +371,7 @@ Commands raise a CLI error (non-zero exit) carrying herdr's machine code where o
 - Invalid send shapes: usage error **before any transport call** (nothing is sent)
 
 Exit `0` means success (including an explicit empty `list` result or a satisfied wait).
+
+An identical signed reconciliation receipt may be verified again after a consumed/superseded settlement, without another transition. This lets an assignment consumer recover a crash before journaling its verified observation reference. Re-verification preserves the original pinned key, complete binding and generation checks; a later claim's generation rejects the old proof. It never resubmits the payload. Runtime recovery additionally exposes the read-only `process_binding(pane:, caller_pid:)` adapter operation, which requires OS ancestry under the native shell, a matching foreground owner and immutable agent-session identity.
+
+Recovery consumers with a separately accepted journal registration pass `expected_registration:` to `Inbox#reconcile`. The exact `event_id`, `attempt_id`, `payload_sha256` and `receipt_key_sha256` map is checked inside the event lock before signature verification or settlement. A prior `status` call alone does not establish this precondition. A mismatch raises `ValidationError` without settling the event.

data/lib/ace/herdr/cli/commands/inbox.rb

@@ -32,10 +32,9 @@ module Ace
             translate_errors do
               cli_error("--event is required") if options[:event].to_s.empty?
               cli_error("only --format json is supported") if options[:format] && options[:format] != "json"
-              inbox = Organisms::Inbox.new(executor: executor,
+              inbox = Organisms::Inbox.from_config(config: config, executor: executor,
                 native: @native || Molecules::NativeQueueExecutor.new,
-                deliveries_dir: deliveries_dir,
-                receipt_public_key: %w[enqueue reconcile].include?(operation) ? receipt_public_key : nil)
+                root: Dir.pwd)
               result = case operation
               when "enqueue"
                 %i[attempt ref file].each { |key| cli_error("--#{key} is required") if options[key].to_s.empty? }
@@ -70,17 +69,6 @@ module Ace
             raise Ace::Support::Cli::Error, e.message
           end
 
-          private
-
-          def receipt_public_key
-            path = config["inbox_receipt_public_key"]
-            return nil unless path.is_a?(String) && path.start_with?("/")
-
-            key = OpenSSL::PKey.read(File.read(path))
-            key if key.is_a?(OpenSSL::PKey::RSA) && !key.private?
-          rescue SystemCallError, OpenSSL::PKey::PKeyError
-            nil
-          end
         end
       end
     end

data/lib/ace/herdr/cli/commands/support.rb

@@ -30,12 +30,8 @@ module Ace
           # fail closed (spec 8wm.t.vrz §3)
           def resolve_ref(session, pane)
             Ace::Hitl::Providers::Ref.new(
-              session: Ace::Hitl::Providers::Ref.validate!(
-                session || ENV["HERDR_SESSION"], "HERDR_SESSION"
-              ),
-              pane: Ace::Hitl::Providers::Ref.validate!(
-                pane || ENV["HERDR_PANE"], "HERDR_PANE"
-              )
+              session: session || ENV["HERDR_SESSION"], pane: pane || ENV["HERDR_PANE"],
+              session_source: "HERDR_SESSION", pane_source: "HERDR_PANE"
             )
           end
 

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

@@ -33,8 +33,14 @@ module Ace
         # @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)
+          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
+          command = environment ? [environment, *argv] : argv
+          options = {pgroup: true}
+          options[:unsetenv_others] = true if environment
+          Open3.popen3(*command, **options) do |stdin, stdout, stderr, waiter|
             begin
               run_loop(stdin, stdout, stderr, waiter,
                 stdin_data: stdin_data, timeout_s: timeout_s, output_limit: output_limit)

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

@@ -56,9 +56,10 @@ 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|
+        def with_lock(deliveries_dir, event_id, create: true)
+          FileUtils.mkdir_p(deliveries_dir) if create
+          flags = create ? "a" : File::RDWR | File::NOFOLLOW
+          File.open(lock_path(deliveries_dir, event_id), flags) do |lock|
             lock.flock(File::LOCK_EX)
             begin
               return yield

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+require "ace/runtime/molecules/protected_linux"
+require "ace/runtime/molecules/protected_socket"
+require "securerandom"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Uses only the canonical attempt's pinned server and original fresh reply.
+      class ProtectedNativeControl
+        def initialize(mapping:, kernel: Ace::Runtime::Molecules::ProtectedLinux.new)
+          @mapping, @kernel = mapping, kernel
+          @origin = nil
+        end
+
+        def verify!
+          @kernel.supported!
+          native = @mapping.fetch("native")
+          wire.root_path!(File.dirname(native.fetch("socket_path")), directory: true, owner: @mapping.fetch("worker_uid"))
+          identity = wire.socket_identity(native.fetch("socket_path"))
+          unless identity == native.fetch("socket_identity") && native.fetch("version") == "0.9.3"
+            raise Ace::Runtime::RuntimeUnavailableError, "native endpoint generation or version changed"
+          end
+          @kernel.live!(native.fetch("server_identity"))
+          true
+        end
+
+        def request(method, params = {})
+          verify!
+          native = @mapping.fetch("native")
+          wire.connect(native.fetch("socket_path")) do |socket|
+            unless @kernel.same?(@kernel.peer(socket), native.fetch("server_identity")) &&
+                wire.socket_identity(native.fetch("socket_path")) == native.fetch("socket_identity")
+              raise Ace::Runtime::RuntimeUnavailableError, "native peer differs from installed server"
+            end
+            id = SecureRandom.hex(12)
+            deadline = wire.deadline
+            wire.write(socket, {"id" => id, "method" => method, "params" => params}, deadline: deadline)
+            result = wire.read(socket, deadline: deadline)
+            unless result.is_a?(Hash) && result["id"] == id && result["result"].is_a?(Hash) && !result.key?("error")
+              raise Ace::Runtime::RuntimeUnavailableError, "native control response is invalid"
+            end
+            verify!
+            result.fetch("result")
+          end
+        rescue SystemCallError, IOError
+          raise Ace::Runtime::RuntimeUnavailableError, "native control outcome is unavailable"
+        end
+
+        def preflight!
+          ping = request("ping")
+          unless ping["version"] == "0.9.3" && ping["protocol"] == 22 &&
+              ping.dig("capabilities", "endpoint_protocol_generation") == 1
+            raise Ace::Runtime::RuntimeUnavailableError, "installed native protocol is unsupported"
+          end
+          workspace = request("workspace.get", {"workspace_id" => @mapping.fetch("native").fetch("workspace_id")}).fetch("workspace")
+          unless workspace["workspace_id"] == @mapping.fetch("native").fetch("workspace_id")
+            raise Ace::Runtime::RuntimeUnavailableError, "installed native workspace differs"
+          end
+          true
+        rescue KeyError, TypeError
+          raise Ace::Runtime::RuntimeUnavailableError, "installed native workspace is unavailable"
+        end
+
+        def create(mapping_id:, ticket:)
+          preflight!
+          raise Ace::Runtime::RuntimeUnavailableError, "native creation is never repeated" if @origin
+          # Mark attempted BEFORE any remote write: a lost reply cannot respawn.
+          @origin = {"state" => "uncertain"}
+          workspace = @mapping.fetch("native").fetch("workspace_id")
+          command = [@mapping.fetch("bootstrap"), mapping_id, ticket]
+          layout = request("layout.apply", {"workspace_id" => workspace, "focus" => false,
+            "root" => {"type" => "pane", "cwd" => @mapping.fetch("worker_cwd"),
+              "command" => command}})
+          layout = layout.fetch("layout")
+          root = layout.fetch("root")
+          unless layout["workspace_id"] == workspace && root.is_a?(Hash) && root["type"] == "pane" &&
+              !root.key?("children") && !root.key?("first") && !root.key?("second") &&
+              root["command"] == command && root["cwd"] == @mapping.fetch("worker_cwd")
+            raise Ace::Runtime::RuntimeUnavailableError, "native creation is not a fresh single-pane layout"
+          end
+          pane = root.fetch("pane_id")
+          original = {"workspace" => workspace, "tab" => layout.fetch("tab_id"), "pane" => pane,
+            "server_identity" => @mapping.fetch("native").fetch("server_identity"),
+            "socket_identity" => @mapping.fetch("native").fetch("socket_identity"), "command" => command, "cwd" => @mapping.fetch("worker_cwd")}
+          @origin = original
+          observe(original)
+        rescue KeyError, TypeError
+          raise Ace::Runtime::RuntimeUnavailableError, "native creation provenance is unavailable"
+        end
+
+        def observe(origin)
+          unless origin["workspace"] == @mapping.fetch("native").fetch("workspace_id") &&
+              origin["server_identity"] == @mapping.fetch("native").fetch("server_identity") &&
+              origin["socket_identity"] == @mapping.fetch("native").fetch("socket_identity")
+            raise Ace::Runtime::RuntimeUnavailableError, "native creation server changed"
+          end
+          pane = request("pane.get", {"pane_id" => origin.fetch("pane")}).fetch("pane")
+          info = request("pane.process_info", {"pane_id" => origin.fetch("pane")}).fetch("process_info")
+          unless pane["pane_id"] == origin["pane"] && pane["workspace_id"] == origin["workspace"] &&
+              pane["tab_id"] == origin["tab"] && info["pane_id"] == origin["pane"] && [String, Integer].any? { |type| pane["terminal_id"].is_a?(type) }
+            raise Ace::Runtime::RuntimeUnavailableError, "original native pane or terminal changed"
+          end
+          child = @kernel.capture(info.fetch("shell_pid"))
+          unless child["uid"] == @mapping.fetch("worker_uid") && child["gid"] == @mapping.fetch("worker_gid") &&
+              child["groups"] == @mapping.fetch("worker_groups") &&
+              child["parent_pid"] == origin.fetch("server_identity").fetch("pid")
+            raise Ace::Runtime::RuntimeUnavailableError, "original native child lineage or credentials changed"
+          end
+          binding = {"runtime" => "herdr", "session" => origin.fetch("workspace"), "pane" => origin.fetch("pane"),
+            "terminal_id" => pane.fetch("terminal_id").to_s, "process_identity" => child,
+            "shell_identity" => child, "native_origin" => origin.reject { |key, _| key == "process_binding" }}
+          if origin.key?("process_binding") && origin["process_binding"] != binding
+            raise Ace::Runtime::RuntimeUnavailableError, "original native child changed"
+          end
+          binding
+        rescue KeyError, TypeError
+          raise Ace::Runtime::RuntimeUnavailableError, "original native child cannot be observed"
+        end
+
+        def terminate(binding, handle:)
+          observe(binding.fetch("native_origin").merge("process_binding" => binding))
+          request("pane.close", {"pane_id" => binding.fetch("pane")})
+          @kernel.exited?(handle, timeout: 5)
+        end
+
+        private
+        def wire
+          Ace::Runtime::Molecules::ProtectedSocket
+        end
+      end
+    end
+  end
+end

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

@@ -105,7 +105,7 @@ module Ace
                 "no recoverable answer stored for event #{event_id.inspect}"
             end
 
-            ref = Ace::Hitl::Providers::Ref.new(session: record.session, pane: record.pane)
+            ref = Ace::Hitl::Providers::Ref.new(session: record.session, pane: record.pane, canonical: true)
             deliver_locked(ref, record.answer, record, kind, label)
           end
         end
@@ -302,8 +302,7 @@ module Ace
             end
 
           Ace::Hitl::Providers::Ref.new(
-            session: Ace::Hitl::Providers::Ref.validate!(session, "ref session"),
-            pane: Ace::Hitl::Providers::Ref.validate!(pane, "ref pane")
+            session: session, pane: pane, session_source: "ref session", pane_source: "ref pane"
           )
         end
 

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

@@ -16,6 +16,7 @@ module Ace
         class IdentityDriftError < ValidationError; end
 
         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
@@ -28,6 +29,55 @@ module Ace
         AGENT_STATUSES = %w[idle busy working blocked done].freeze
         WAKE_STATUSES = %w[idle done].freeze
 
+        # One configured verifier construction for the Herdr CLI and signed
+        # receipt consumers. Configuration remains supervisor-owned.
+        def self.from_config(config: Ace::Herdr.config, root: Dir.pwd,
+          executor: Molecules::HerdrExecutor.new, native: Molecules::NativeQueueExecutor.new)
+          path = config["inbox_receipt_public_key"]
+          key = begin
+            candidate = OpenSSL::PKey.read(File.read(path)) if path.is_a?(String) && path.start_with?("/")
+            candidate if candidate.is_a?(OpenSSL::PKey::RSA) && !candidate.private?
+          rescue SystemCallError, OpenSSL::PKey::PKeyError
+            nil
+          end
+          new(executor: executor, native: native,
+            deliveries_dir: File.expand_path(config["deliveries_dir"] || ".ace-local/herdr/deliveries", root),
+            receipt_public_key: key)
+        end
+
+        # Enumerate retained event identities through the same store/lock owner.
+        # Unreadable unattributable records cannot be treated as another attempt.
+        def self.retained_events(deliveries_dir:, attempt:)
+          raise ValidationError, "invalid attempt id" unless attempt.is_a?(String) && EVENT.match?(attempt)
+          ids = [deliveries_dir, Molecules::DeliveryRecordStore.archive_dir(deliveries_dir)].flat_map do |dir|
+            next [] unless Dir.exist?(dir)
+            Dir.children(dir).filter_map { |name| name.delete_suffix(".json") if name.end_with?(".json") }
+          end.uniq
+          ids.select do |event|
+            raise ValidationError, "retained inbox event id is invalid" unless EVENT.match?(event)
+            Molecules::DeliveryRecordStore.with_lock(deliveries_dir, event, create: false) do
+              paths = [Molecules::DeliveryRecordStore.path_for(deliveries_dir, event),
+                Molecules::DeliveryRecordStore.path_for(Molecules::DeliveryRecordStore.archive_dir(deliveries_dir), event)]
+              copies = paths.filter_map do |path|
+                next unless File.exist?(path)
+                record = Models::DeliveryRecord.from_json(File.read(path))
+                unless record.event_id == event && record.inbox && record.inbox.fetch("attempt_id").is_a?(String)
+                  raise ValidationError, "retained inbox event is unavailable"
+                end
+                record.to_h
+              end
+              # Identical retained copies describe one event. Never let live
+              # precedence hide a corrupt or conflicting archived copy.
+              if copies.empty? || copies.uniq.length != 1
+                raise ValidationError, "retained inbox copies conflict"
+              end
+              copies.first.fetch("inbox").fetch("attempt_id") == attempt
+            end
+          end
+        rescue SystemCallError, JSON::ParserError, ArgumentError, KeyError
+          raise ValidationError, "retained inbox inventory is unavailable"
+        end
+
         def initialize(executor:, native:, deliveries_dir:, receipt_public_key: nil)
           @executor = executor
           @native = native
@@ -35,7 +85,20 @@ module Ace
           @receipt_public_key = receipt_public_key
         end
 
-        def enqueue(event:, attempt:, ref:, payload:)
+        # Project the accepted runtime owner before consuming an answer. Native
+        # observation may verify this identity, but cannot choose its replacement.
+        def target_from_owner(owner)
+          unless owner.is_a?(Hash) && owner["runtime"] == "herdr" &&
+              owner["agent_session"].is_a?(Hash) && owner.dig("agent_session", "agent") == owner["agent"]
+            raise ValidationError, "accepted native owner is unavailable"
+          end
+          target = owner.slice("session", "pane", "terminal_id", "agent").merge(
+            "thread" => owner.dig("agent_session", "value"), "thread_kind" => owner.dig("agent_session", "kind"))
+          validate_expected_target!(target)
+          target.transform_values { |value| value.dup.freeze }.freeze
+        end
+
+        def enqueue(event:, attempt:, ref:, payload:, managed_envelope: nil, expected_target: nil)
           validate_id!(event, "event")
           validate_id!(attempt, "attempt")
           raise ValidationError, "trusted receipt public key is unavailable" unless @receipt_public_key
@@ -51,13 +114,41 @@ module Ace
 
           address = address_for(ref)
           digest = Digest::SHA256.hexdigest(payload)
+          envelope = if managed_envelope
+            Ace::Hitl::Contract::ManagedEnvelope.load(managed_envelope, expected: {
+              attempt_id: attempt, payload_sha256: digest,
+              reverse: {"schema" => Ace::Hitl::Providers::Ref::SCHEMA, "session" => address.session, "pane" => address.pane}
+            })
+          end
+          if envelope && Ace::Hitl::Contract::SecretGate::PATTERN.match?(payload)
+            raise ValidationError, "secret-bearing managed native answers are prohibited"
+          end
+          if envelope && expected_target.nil?
+            raise ValidationError, "managed native delivery requires the accepted original target"
+          end
+          unless expected_target.nil?
+            validate_expected_target!(expected_target)
+            expected_target = expected_target.slice(*TARGET_IDENTITY)
+            unless expected_target.values_at("session", "pane") == [address.session, address.pane]
+              raise ValidationError, "accepted original target differs from reverse address"
+            end
+          end
           with_event(event) do |record|
             if record
               validate_match!(record, attempt, address, digest)
+              unless record.inbox["managed_envelope"] == envelope
+                raise ValidationError, "managed envelope conflicts with immutable inbox event"
+              end
+              if expected_target && record.inbox["origin_target"] != expected_target
+                raise IdentityDriftError, "original native target conflicts with immutable inbox event"
+              end
               next public_record(record)
             end
 
-            target = observe_target(address.session, address.pane)
+            target = observe_target(address.session, address.pane, target: expected_target)
+            if expected_target && !TARGET_IDENTITY.all? { |key| target[key] == expected_target[key] }
+              raise IdentityDriftError, "native target differs from accepted original owner"
+            end
             if target["agent"] == "pi" && !PI_EVENT_ID.match?(event)
               raise ValidationError,
                 "Pi queue requires an inbox (inb-) or wake (wnk-) event id with at " \
@@ -76,11 +167,15 @@ module Ace
               answer_digest: digest, answer: payload, state: "queued",
               inbox: {"attempt_id" => attempt, "claim_generation" => 0,
                 "receipt_key_sha256" => key_fingerprint,
+                "managed_envelope" => envelope,
+                "origin_target" => target.slice(*TARGET_IDENTITY),
                 "target" => target, "binding" => target.merge("payload_sha256" => digest)}
             )
             save(record)
             public_record(record)
           end
+        rescue Ace::Hitl::Contract::InvalidEnvelope => e
+          raise ValidationError, e.message
         end
 
         def status(event:)
@@ -92,6 +187,18 @@ module Ace
           end
         end
 
+        # Protected canonical reads only use an already registered event's lock.
+        # Missing retention is unavailable evidence, never query-time repair.
+        def retained_status(event:)
+          validate_id!(event, "event")
+          with_event(event, create_lock: false) do |record|
+            raise ValidationError, "unknown inbox event: #{event}" unless record&.inbox
+            public_record(record)
+          end
+        rescue SystemCallError
+          raise ValidationError, "retained inbox lock is unavailable"
+        end
+
         def deliver(event:)
           validate_id!(event, "event")
           with_event(event) do |record|
@@ -176,14 +283,46 @@ module Ace
           end
         end
 
-        def reconcile(event:, receipt:, signed_bytes: nil, signature: nil)
+        def reconcile(event:, receipt:, signed_bytes: nil, signature: nil, expected_registration: nil)
+          reconcile_record(event: event, receipt: receipt, signed_bytes: signed_bytes,
+            signature: signature, expected_registration: expected_registration, settle: true)
+        end
+
+        # Canonical consumers reverify retained signed settlement without creating
+        # a new local transition. The same event lock and proof owner are used.
+        def verify_reconciliation(event:, receipt:, signed_bytes:, signature:, expected_registration:)
+          unless expected_registration.is_a?(Hash) && expected_registration.keys.sort ==
+              %w[event_id attempt_id payload_sha256 receipt_key_sha256].sort &&
+              %w[event_id attempt_id].all? { |key| expected_registration[key].is_a?(String) && EVENT.match?(expected_registration[key]) } &&
+              %w[payload_sha256 receipt_key_sha256].all? { |key| expected_registration[key].is_a?(String) && expected_registration[key].match?(/\A[0-9a-f]{64}\z/) }
+            raise ValidationError, "canonical reconciliation requires exact registration"
+          end
+          reconcile_record(event: event, receipt: receipt, signed_bytes: signed_bytes,
+            signature: signature, expected_registration: expected_registration, settle: false)
+        rescue SystemCallError
+          raise ValidationError, "retained inbox lock is unavailable"
+        end
+
+        private
+
+        def reconcile_record(event:, receipt:, signed_bytes:, signature:, expected_registration:, settle:)
           validate_id!(event, "event")
-          with_event(event) do |record|
+          with_event(event, create_lock: settle) do |record|
             raise ValidationError, "unknown inbox event: #{event}" unless record&.inbox
+            # The consumer's accepted registration must match under the same
+            # event lock that verifies and settles the signed observation.
+            unless expected_registration.nil?
+              registration = public_record(record).slice("event_id", "attempt_id", "payload_sha256", "receipt_key_sha256")
+              unless expected_registration == registration
+                raise ValidationError, "inbox event differs from expected registration"
+              end
+            end
             # `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)
+            replay = %w[completed queued].include?(record.state) && receipt.is_a?(Hash) &&
+              receipt == record.inbox["reconciliation"]
+            unless replay || (settle && %w[uncertain delivered].include?(record.state))
               raise ValidationError, "event is not reconcilable from state #{record.state}"
             end
             binding = record.inbox["binding"]
@@ -211,7 +350,7 @@ module Ace
                 refusal = "replacement target cannot be verified: #{e.message}"
                 nil
               end
-              stable = %w[session pane terminal_id agent thread thread_kind]
+              stable = TARGET_IDENTITY
               unless replacement.is_a?(Hash) && observed &&
                   stable.all? { |key| replacement[key] == observed[key] }
                 refusal ||= "replacement target does not match the live native session"
@@ -231,6 +370,11 @@ module Ace
               end
             end
             next public_record(record).merge("reconciliation_refusal" => refusal) if refusal
+            # The consumer may crash after Herdr settles but before recording
+            # its observation reference. Re-verify the identical signed proof
+            # without another transition. A later claim has a new generation
+            # and fails the binding checks above.
+            next public_record(record) if replay
 
             outcome = receipt["outcome"]
             state = outcome == "consumed" ? "completed" : "queued"
@@ -289,9 +433,13 @@ module Ace
           nil
         end
 
-        def with_event(event)
-          Molecules::DeliveryRecordStore.with_lock(@deliveries_dir, event) do
-            yield Molecules::DeliveryRecordStore.load(@deliveries_dir, event)
+        def with_event(event, create_lock: true)
+          Molecules::DeliveryRecordStore.with_lock(@deliveries_dir, event, create: create_lock) do
+            record = Molecules::DeliveryRecordStore.load(@deliveries_dir, event)
+            if record
+              Ace::Hitl::Providers::Ref.new(session: record.session, pane: record.pane, canonical: true)
+            end
+            yield record
           end
         end
 
@@ -313,13 +461,20 @@ module Ace
           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")
+            session: hash.fetch("session"), pane: hash.fetch("pane"), canonical: !ref.is_a?(Hash)
           )
         rescue Errno::ENOENT, JSON::ParserError, KeyError, TypeError => e
           raise ValidationError, "invalid ref: #{e.message}"
         end
 
+        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
+            raise ValidationError, "accepted original native target is incomplete or invalid"
+          end
+        end
+
         def validate_match!(record, attempt, address, digest)
           unless record.inbox && record.inbox["attempt_id"] == attempt &&
               record.session == address.session && record.pane == address.pane &&
@@ -335,7 +490,7 @@ module Ace
           # 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]
+          stable = TARGET_IDENTITY
           if target && !stable.all? { |key| target[key] == binding[key] }
             raise IdentityDriftError, "target identity changed since enqueue; reconciliation is required"
           end
@@ -468,10 +623,12 @@ module Ace
           {"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,
+           "managed_envelope" => record.inbox["managed_envelope"],
            "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"],
+           "origin_target" => record.inbox["origin_target"],
            "target" => record.inbox["target"],
            "binding" => record.inbox["binding"], "receipt" => record.inbox["receipt"],
            "reconciliation" => record.inbox["reconciliation"],

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "inbox"
+require_relative "../molecules/protected_native_control"
+require_relative "../molecules/herdr_executor"
+require_relative "../molecules/native_queue_executor"
+require_relative "../molecules/bounded_process"
+
+module Ace
+  module Herdr
+    module Organisms
+      # Fixed construction for the canonical authority consumer. Callers of the
+      # public protocol cannot inject this factory or its collaborators.
+      module ProtectedInbox
+        class PaneReader
+          def initialize(control)
+            @control = control
+          end
+
+          def pane_get_bounded(pane)
+            result = @control.request("pane.get", {"pane_id" => pane})
+            Molecules::ExecutionResult.new(stdout: JSON.generate({"result" => result}), stderr: "",
+              success: true, exit_code: 0)
+          rescue Ace::Runtime::RuntimeUnavailableError
+            raise ExecutorUnavailableError, "original protected native endpoint is unavailable"
+          end
+        end
+
+        class PiIdentity
+          def initialize(client)
+            runner = lambda do |argv, stdin_data:, timeout_s:|
+              unless argv == [client, "--identity"] && stdin_data.empty?
+                raise ExecutorUnavailableError, "protected inbox permits identity inspection only"
+              end
+              result = Molecules::BoundedProcess.call(argv, stdin_data: stdin_data,
+                timeout_s: timeout_s, environment: {})
+              raise ExecutorError, "Pi identity output is oversized" if result.oversized
+              [result.stdout, result.stderr, result.status]
+            end
+            @native = Molecules::NativeQueueExecutor.new(pi_client: client, runner: runner)
+          end
+
+          def pi_identity
+            @native.pi_identity
+          end
+        end
+
+        module_function
+
+        # The Assign resolver has verified context paths/key/client. native is
+        # the immutable canonical stage, not current process discovery. Endpoint
+        # liveness is checked lazily only if Inbox actually observes replacement.
+        def build(context:, mapping:, native:, kernel: Ace::Runtime::Molecules::ProtectedLinux.new)
+          native_fields = %w[server_identity socket_identity workspace_id]
+          unless native.is_a?(Hash) && native_fields.all? { |key| native.key?(key) }
+            raise ValidationError, "canonical native stage is unavailable"
+          end
+          fixed = JSON.parse(JSON.generate(mapping))
+          fixed["native"].merge!(native.slice(*native_fields))
+          control = Molecules::ProtectedNativeControl.new(mapping: fixed, kernel: kernel)
+          key = OpenSSL::PKey.read(File.binread(context.fetch("receipt_public_key")))
+          unless key.is_a?(OpenSSL::PKey::RSA) && !key.private?
+            raise ValidationError, "protected inbox requires a public RSA key"
+          end
+          Inbox.new(executor: PaneReader.new(control), native: PiIdentity.new(context.fetch("pi_queue_client")),
+            deliveries_dir: context.fetch("deliveries_dir"), receipt_public_key: key)
+        rescue KeyError, SystemCallError, OpenSSL::PKey::PKeyError
+          raise ValidationError, "protected inbox fixed context is unavailable"
+        end
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Ace
         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)
+          identity_dir: nil, poll_interval: POLL_INTERVAL, process_identity: Runtime::Molecules::ProcessIdentity.new)
           @executor = executor
           @env = env
           @clock = clock
@@ -23,6 +23,7 @@ module Ace
           @prepared = {}
           @identity_dir = identity_dir
           @poll_interval = poll_interval
+          @process_identity = process_identity
         end
 
         def context
@@ -109,6 +110,34 @@ module Ace
           end
         end
 
+        def process_binding(pane:, caller_pid:)
+          return nil unless caller_pid.is_a?(Integer) && caller_pid.positive?
+
+          with_errors do
+            native = find_hash(@executor.pane_get(pane).parsed_json, %w[result pane])
+            info = find_hash(@executor.pane_process_info(pane).parsed_json, %w[result process_info])
+            next nil unless native && info && native["pane_id"] == pane
+
+            owner = @process_identity.owner(shell_pid: info["shell_pid"], caller_pid: caller_pid)
+            foreground = info["foreground_processes"]
+            next nil unless owner && foreground.is_a?(Array) && foreground.any? do |process|
+              process.is_a?(Hash) && process["pid"] == owner.dig("process_identity", "pid")
+            end
+
+            session = native["agent_session"]
+            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) &&
+              workspace.is_a?(String) && !workspace.empty? &&
+              (terminal.is_a?(String) || terminal.is_a?(Integer)) && !terminal.to_s.empty?
+
+            {"runtime" => "herdr", "session" => workspace, "pane" => pane,
+              "terminal_id" => terminal.to_s, "agent" => native["agent"], "agent_session" => session}.merge(owner)
+          end
+        end
+
         def prepare_pane(window:)
           with_errors do
             tab = resolve_tab!(window)

data/lib/ace/herdr/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Herdr
-    VERSION = "0.3.2"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-herdr
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-04 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-hitl-contract
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: ace-runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
   requirement: !ruby/object:Gem::Requirement
@@ -209,10 +209,12 @@ files:
 - lib/ace/herdr/molecules/pane_tidy_probe.rb
 - lib/ace/herdr/molecules/preset_loader.rb
 - lib/ace/herdr/molecules/preset_resolver.rb
+- lib/ace/herdr/molecules/protected_native_control.rb
 - lib/ace/herdr/organisms/control_surface.rb
 - lib/ace/herdr/organisms/deliverer.rb
 - lib/ace/herdr/organisms/dispatcher.rb
 - lib/ace/herdr/organisms/inbox.rb
+- lib/ace/herdr/organisms/protected_inbox.rb
 - lib/ace/herdr/organisms/runtime_adapter.rb
 - lib/ace/herdr/organisms/tidy.rb
 - lib/ace/herdr/version.rb