ace-lab 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3799161a4575055b78e316deb18a4fa952fb1d84fa9fb10cd6e5c081a36acee
-  data.tar.gz: dd2d0fa5764e5bce423396e93e4fd1751fddd880649219d6a130306d0ec49667
+  metadata.gz: bb4f48b950b3a32e27a457e36af99148a65e8a95cdbbc55a1586e4f9f2d2abd9
+  data.tar.gz: 361f1a4f8b0167365fe8fee52c7e78047c0f31a9d8f1b1dd9644de79e13b540f
 SHA512:
-  metadata.gz: 1556efc67f0fa45a412b40430570355578c7e61000bda7af07982345631f023c3f56c709d2d02a25c3faf84495b510d6fb171a904d8f910e7c336b4b8113cd44
-  data.tar.gz: a78076debb811ce94046ff8cb056648b6455f8dbe30514a5d575ac417bcf98adce21bb42c3f6f712f0d0e2d6d4bbb3c67ba3764dfb9e4138cb6eb17e6dd6a113
+  metadata.gz: c556ae2dfb4f3137d2e3a45473287c385cc265b2da115aa9db6a2fe42b1e1e61b5a4e6839d98b4b76ce093ace09032c1e8795373f41b33987c0e0127ba1e084a
+  data.tar.gz: 7d470523a46606f392ea1ed22cffd708861c5e635c34ff9d1321ff64d542ef45f30e5cc763ac422ec28a9add7c7ef6a26e8fb705d01f25cdfba291746c19c520

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-16
+
+### Added
+
+- Compose ordinary Assign, HITL and Forgejo merge under one installed owner and journal, with readiness barriers and fresh native/project admission.
+- Optionally serve existing mTLS HITL beside the ordinary Unix listener under the same canonical owner, journal, proposal policy and one-use OTP vault. Validate the configured project and service identity before either listener starts.
+- Add retained assignment prepare/request clients and bounded canonical worktree observations. Separate stable configuration identity from changing decisions, preserve no-effect settlement after slow provider calls, and clean delivery handler process groups.
+- This source cut enables initial installation; it does not claim autonomous release or installed two-project acceptance.
+
 ## [0.7.0] - 2026-10-16
 
 ### Added

data/docs/usage.md

@@ -121,6 +121,161 @@ Only the original OS caller identity with project visibility can read the
 request. The authoritative state survives loss of the local assignment cache
 because it lives in the separate assignment evidence Git ref.
 
+### `ace-lab service listen --mode ordinary-merge`
+
+The installed ordinary service owns the Assign, HITL and merge endpoints in one
+process. Start it as the configured service account:
+
+```sh
+ace-lab service listen --mode ordinary-merge --project atlas \
+  --config /etc/lab/ace-lab/atlas-receiver.yml
+```
+
+The receiver configuration selects its existing forge, repository, principal and
+merge socket. `/etc/lab/ace-lab/assign-owners.yml` separately selects the canonical
+Assign journal and native execution owner. Both selections must agree with the
+ordinary project mapping in the trusted authorization document. `repo_path` is
+the merge candidate repository; it does not choose the execution journal.
+
+Each project entry in the root-installed assignment document contains:
+
+| Entry | Installed selection |
+|---|---|
+| `service` | Non-root owner UID/GID, assignment socket and private state root |
+| `journal` | Service-owned repository, execution ref and private evidence checkout |
+| `assignment_root`, `lifecycle_root` | Separate private prepared-input and exclusion directories |
+| `runtime_binary`, `native` | Installed executable and exact native server/socket generation from the installation receipt |
+| `worktrees` | Allowed worktree root and Git common directory |
+| `participants` | OS UID/GID/actor, native workspace and supervisor panes |
+| `hitl` | Private store root, distinct socket, dedicated group, trusted grants path and optional installed TLS authority reference |
+
+For example, the `hitl` entry inside an already selected project can be:
+
+```yaml
+hitl:
+  root: /var/lib/lab/assign/atlas/hitl
+  socket_path: /run/lab/assign/atlas/hitl.sock
+  group: atlas-lifecycle
+  grants_path: /etc/lab/ace-lab/authorization.yml
+```
+
+The store must be a separate child of that project's `service.state_root`; the
+installer creates `service.state_root` with mode `0700`, the HITL root with its
+maintained mode `0711`, and socket access before startup. The private parent keeps
+the HITL tree inaccessible to other accounts; Store maintains private request and
+secret subdirectories. Startup and restart validate the same layout.
+`hitl.service_uid` in the grants document must equal the Assign owner UID. Native
+identities come from the installed receipt and live observation, not the project
+configuration cascade. HITL requests, decisions and merge claims use the same
+canonical Assign journal and lifecycle exclusion.
+
+For the existing remote Hermes transport, install its project-scoped mTLS
+authority and add its absolute configuration path to this same `hitl` entry:
+
+```yaml
+  tls_authority: /etc/lab/ace-hitl/atlas-tls.json
+```
+
+The referenced file uses the maintained `ace.hitl.tls.authority/v1` schema and
+credential provisioning layout from `ace-hitl`. Its project must match this
+owner; `service_user` and `service_group` must resolve to the owner's actual UID
+and primary GID. The dedicated Unix control group remains `hitl.group`. Root
+installs the credential references and Incus TCP proxy; callers cannot choose
+them. Invalid ownership, identity, project or TLS material prevents startup.
+
+The TLS listener runs in this same service process and shares its exact HITL
+binding, store, decision policy and in-memory one-time OTP vault. Hermes uses its
+verified project certificate as a remote transport identity; it does not need a
+synthetic Unix transport UID. Keep `transport_uids` empty when no local transport
+is installed. Configure the actual local proposer separately with
+`proposal_uids` and its project grant. A proposer grant never authorizes replies
+or delegates silence-based decisions. Restart the composed service after changing
+its TLS authority or credential selection, retaining the canonical journal.
+
+All selected endpoints must become ready before assignment ingress opens. A
+failed endpoint shuts down the complete owner. A stale assignment endpoint needs
+installer inspection; startup does not remove it or recover merge effects first.
+
+## Ordinary assignment client
+
+`ace-lab assignment` selects the root-installed project owner and uses the
+existing Assign protocol. Assign remains the only accepted execution journal.
+Preparation captures reviewed task context and the existing managed assignment
+graph; it does not start a worker or register accepted work.
+
+```sh
+ace-lab assignment prepare --project atlas --task 8wr.t.abc --pane w1:pS \
+  --output .ace-local/prepared-task
+ace-lab assignment request --project atlas --input .ace-local/prepared-task/request.json
+```
+
+The output directory must not exist. Preparation retains the definition, bundle,
+and registration request with one stable mutation ID. `--dependency-reports FILE`
+selects an explicit JSON array of `{task_id, assignment_id, number}` entries for
+dependency reports. A failed preparation keeps partial files for inspection;
+it never rebuilds an existing directory. In this source checkout use
+`bundle exec ace-lab` because no `bin/ace-lab` binstub is committed.
+
+Every request file has exactly these fields:
+
+```json
+{
+  "version": 1,
+  "project_id": "atlas",
+  "operation": "start_attempt",
+  "mutation_id": "original-start-001",
+  "params": {
+    "assignment_id": "assignment-id",
+    "attempt_id": "attempt-id",
+    "expected_generation": 0,
+    "scope": "010",
+    "head": "0123456789012345678901234567890123456789",
+    "pane": "w1:p2"
+  },
+  "parts": []
+}
+```
+
+Use actual retained IDs, scope, head and native pane. The actual worker executes
+its start request: the owner verifies caller ancestry, live process and checkout.
+A supervisor cannot impersonate another pane by changing `pane`. A new terminal
+or prompt acknowledgement alone is not running proof.
+
+| Operation | `params` beyond `assignment_id` | Transfer / authority |
+|---|---|---|
+| `register_assignment` | Generated by prepare | Exact prepared bundle; supervisor |
+| `registration_status` | None | Read; `mutation_id: null` |
+| `start_attempt` | `attempt_id`, `expected_generation: 0`, `scope`, `head`, `pane` | Actual worker start |
+| `assignment_snapshot` | `attempt_id` (or null), `kind: queue` or `prepared_work` | Download; `mutation_id: null` |
+| `queue_start` | `attempt_id`, `expected_generation`, `pane`, `step` (or null for next) | Original worker |
+| `queue_finish` | Same as queue_start | One UTF-8 report part |
+| `queue_fail` | `attempt_id`, `expected_generation`, `pane`, `message` | Original worker; unfinished work stays failed |
+| `submit_result` | `attempt_id`, `expected_generation`, `pane`, `head`, `receipt_sha256` | Receipt first, then its ordered artifacts; original worker |
+| `result_status` | `attempt_id` | Read; `mutation_id: null` |
+| `result_snapshot` | `attempt_id`, `result_id` | Canonical receipt/artifacts download; `mutation_id: null` |
+| `finish` | `attempt_id`, `expected_generation`, `pane`, `head`, `result_id`, `receipt_digest` | Supervisor accepts exact submitted result after settlement |
+
+Upload `parts` are ordered `{file, bytes, sha256}` entries. Relative files resolve
+beside the retained request. Changed, oversized or symlinked inputs refuse before
+connection. Requesters never supply a wire `transfer` descriptor. Downloads require
+`--output NEW_DIRECTORY`; numbered byte files and `response.json` are private
+projections of the authenticated reply, not another execution store. For queue
+snapshots, the first byte file contains the current step instructions and reports
+as JSON; prepared-work snapshots contain the original Git bundle.
+
+Retain each request and its exact parts before invoking it. On response loss,
+inspect `registration_status` or `result_status` and reuse the same original
+mutation when replay is appropriate. Never refresh its generation, replace its
+bytes, or create a second worker because a reply was lost. Queue completion and
+`submit_result` keep the attempt running; only the canonical accepted `finish`
+reply proves terminal completion. Unknown effect or Inbox settlement refuses it.
+
+These commands do not silently route to a local `ace-assign` cache. Missing or
+changed installed owner selection is an explicit failure. Native wake consumers
+must read the same canonical status and adopt its original attempt/result IDs.
+Changed owner selection refuses new admission and dispatch until a controlled
+restart. Existing canonical receipts remain the source for reconciliation.
+
 ## Error semantics
 
 Errors are one deterministic JSON document on stdout plus a non-zero exit.

data/lib/ace/lab/cli/commands/assignment.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../../organisms/ordinary_assignment_client"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        module Assignment
+          class Prepare < Ace::Support::Cli::Command
+            desc "Retain reviewed task input for ordinary Assign registration"
+            option :project, required: true, desc: "Installed project ID"
+            option :task, required: true, desc: "Reviewed leaf task ID"
+            option :pane, required: true, desc: "Actual supervisor pane for registration"
+            option :output, required: true, desc: "New private directory for retained input"
+            option :dependency_reports, desc: "JSON array of explicit dependency report selections"
+
+            def call(project:, task:, pane:, output:, **options)
+              reports = options[:dependency_reports] ? JSON.parse(Organisms::OrdinaryAssignmentClient.read_file(
+                options.fetch(:dependency_reports), 65_536), allow_duplicate_key: false, create_additions: false, max_nesting: 16) : []
+              puts JSON.generate(Organisms::OrdinaryAssignmentClient.prepare(project: project, task: task,
+                pane: pane, output: output, dependency_reports: reports))
+            rescue JSON::ParserError, ArgumentError, KeyError, SystemCallError, Ace::Assign::Error, Ace::Runtime::Error => error
+              raise Ace::Support::Cli::Error, "ordinary preparation incomplete: #{error.message}; retain existing files"
+            end
+          end
+
+          class Request < Ace::Support::Cli::Command
+            desc "Send one retained operation to the installed ordinary Assign owner"
+            option :project, required: true, desc: "Installed project ID"
+            option :input, required: true, desc: "Retained request JSON with original mutation and part digests"
+            option :output, desc: "New private directory for a canonical snapshot download"
+
+            def call(project:, input:, **options)
+              service = Organisms::OrdinaryAssignmentClient.new(project: project)
+              puts JSON.generate(service.request(input: input, output: options[:output]))
+            rescue ArgumentError, KeyError, SystemCallError, Ace::Assign::Error, Ace::Runtime::Error, Ace::Lab::Error => error
+              raise Ace::Support::Cli::Error, "ordinary assignment unavailable: #{error.message}; retain the original request; inspect status before new work"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/service.rb

@@ -7,6 +7,7 @@ require_relative "support"
 require_relative "../../organisms/protected_service_request"
 require_relative "../../organisms/ordinary_merge_request"
 require_relative "../../organisms/ordinary_merge_receiver"
+require_relative "../../organisms/ordinary_authority_composition"
 require_relative "../../molecules/ordinary_listener"
 require_relative "../../molecules/ordinary_receiver_config"
 
@@ -176,7 +177,7 @@ module Ace
           # The ordinary receiver serve entrypoint (spec 8x3.t.xz9.4
           # execution clauses; 8x3.t.xz9.5 integration handoff): binds the
           # configured unix socket, mutually authenticates every connection
-          # through SO_PEERCRED, admits through the canonical Assign
+          # through OS peer credentials, admits through the canonical Assign
           # coordinator, executes the authorized fixed operation — one REAL
           # Forgejo merge under the scoped host-installed service identity —
           # and settles the exact terminal receipt proven by real forge
@@ -188,7 +189,7 @@ module Ace
             include Ace::Support::Cli::Base
             include Output
 
-            desc "Serve the ordinary fixed merge receiver on its configured socket"
+            desc "Serve ordinary Assign, HITL and fixed merge under the installed journal owner"
             option :mode, type: :string, required: true,
               desc: "ordinary-merge selects the ordinary fixed merge receiver"
             option :project, type: :string, required: true, desc: "Project stable ID"
@@ -217,36 +218,19 @@ module Ace
                   request_id: "unknown", input_digest: nil
                 ))
               end
-              policy_document = Molecules::GrantResolver.trusted_document(
-                receiver_config.policy_path
-              )
-              # The ONE canonical Assign journal: the coordinator binds the
-              # evidence ref of the canonical repository the receiver is
-              # installed for (config repo_path — the producer project's
-              # canonical checkout, the same authoritative journal the
-              # producer coordinator uses). Never an integration-checkout
-              # duplicate; the service identity's reviewed permissions are
-              # journal ref read/append, evidence checkout and no-effect
-              # attestation writes inside that repository.
-              coordinator = Ace::Assign::Organisms::AttemptCoordinator.new(
-                repo_root: receiver_config.repo_path
-              )
-              receiver = Organisms::OrdinaryMergeReceiver.new(
-                config: receiver_config, coordinator: coordinator,
-                policy_document: policy_document
-              )
-              listener = Molecules::OrdinaryListener.new(
-                socket_path: receiver_config.socket_path,
-                peer_uid: receiver_config.principal_uid,
-                handler: receiver
-              )
-              receiver.recover_pending!
-              listener.serve
-            rescue Ace::Lab::InvalidConfigurationError, Ace::Assign::AttemptErrors::EvidenceUnavailable => e
+              unless receiver_config.receiver_uid == Process.uid
+                raise Ace::Lab::InvalidConfigurationError, "receiver must run as its configured UID"
+              end
+              server = Organisms::OrdinaryAuthorityComposition.new(receiver_config: receiver_config).build
+              signals = %w[INT TERM].to_h { |signal| [signal, Signal.trap(signal) { server.request_stop }] }
+              server.serve
+            rescue Ace::Lab::InvalidConfigurationError, Ace::Assign::Error, Ace::Runtime::Error, Ace::Hitl::Lifecycle::Error => e
               emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
                 "ordinary_merge_unavailable", e.message,
                 request_id: "unknown", input_digest: nil
               ))
+            ensure
+              signals&.each { |signal, handler| Signal.trap(signal, handler) }
             end
           end
         end

data/lib/ace/lab/cli.rb

@@ -9,6 +9,7 @@ require_relative "cli/commands/services"
 require_relative "cli/commands/resolve"
 require_relative "cli/commands/route"
 require_relative "cli/commands/service"
+require_relative "cli/commands/assignment"
 
 module Ace
   module Lab
@@ -27,7 +28,9 @@ module Ace
         ["route", "Select a configured capable service in a project"],
         ["service request", "Request one authorized service operation"],
         ["service status", "Read a service request outcome"],
-        ["service listen", "Serve the ordinary fixed merge receiver on its configured socket"]
+        ["service listen", "Serve the ordinary fixed merge receiver on its configured socket"],
+        ["assignment prepare", "Retain reviewed task input for ordinary Assign registration"],
+        ["assignment request", "Send one retained operation to the installed ordinary Assign owner"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -54,6 +57,8 @@ module Ace
       register "service request", CLI::Commands::Service::Request.new
       register "service status", CLI::Commands::Service::Status.new
       register "service listen", CLI::Commands::Service::Listen.new
+      register "assignment prepare", CLI::Commands::Assignment::Prepare.new
+      register "assignment request", CLI::Commands::Assignment::Request.new
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

data/lib/ace/lab/molecules/ordinary_admission_resolver.rb

@@ -43,13 +43,16 @@ module Ace
         # @param path [String, nil] trusted policy path to re-read per decision
         # @param loader [Proc, nil] trusted reader (default: GrantResolver);
         #   the only override point, for non-privileged test documents
-        def initialize(policy_document, path: nil, loader: nil)
+        def initialize(policy_document, path: nil, loader: nil, proposal_resolver: nil, caller_uid: nil)
           unless policy_document.is_a?(Hash) && policy_document["authorizations"].is_a?(Hash)
             raise Ace::Lab::InvalidConfigurationError,
               "trusted policy document must contain an authorizations mapping"
           end
           @authorizations = policy_document.fetch("authorizations")
+          @configuration_digest = ServicePolicy.configuration_digest(policy_document)
           @path = path
+          @proposal_resolver = proposal_resolver
+          @caller_uid = caller_uid
           @loader = loader || ->(trusted_path) { GrantResolver.trusted_document(trusted_path) }
           freeze
         end
@@ -65,6 +68,18 @@ module Ace
           unless binding.is_a?(Hash) && binding.fetch("operation", nil) == OPERATION
             return refuse("only the ordinary merge operation is resolvable")
           end
+          if reference.start_with?("proposal-")
+            return refuse("canonical proposal authority is unavailable") unless @proposal_resolver && @caller_uid.is_a?(Integer)
+            begin
+              decision = @proposal_resolver.call(reference, binding.slice(
+                "operation", "project_id", "assignment_id", "attempt_id", "input_digest", "candidate_head").merge(
+                  "target" => {"resource" => binding.fetch("pr_url"), "artifact_digest" => nil},
+                  "caller_uid" => @caller_uid))
+              return Decision.new(authorized?: true, decision: decision, code: nil, message: nil)
+            rescue Ace::Assign::Error
+              return refuse("canonical proposal does not authorize this exact ordinary merge")
+            end
+          end
           decision = authorizations[reference]
           return refuse("authorization reference is unresolved") unless decision.is_a?(Hash)
           unless DECISION_KEYS.all? { |key| decision.key?(key) }
@@ -99,6 +114,10 @@ module Ace
               "invalid lab configuration: trusted authorization refresh at #{@path} " \
               "did not yield an authorizations mapping"
           end
+          unless ServicePolicy.configuration_digest(document) == @configuration_digest
+            raise Ace::Lab::InvalidConfigurationError,
+              "ordinary receiver configuration changed; restart with the installed configuration"
+          end
           document.fetch("authorizations")
         end
 

data/lib/ace/lab/molecules/ordinary_listener.rb

@@ -12,7 +12,7 @@ module Ace
       # entrypoint). Binds the configured unix socket and answers the exact
       # framed protocol the OrdinarySocket client speaks: one bounded JSON
       # document each way behind the shared handshake line. Authentication is
-      # MUTUAL through SO_PEERCRED: every connection's peer UID must equal
+      # MUTUAL through OS peer credentials: every connection's peer UID must equal
       # the configured producer principal UID, and the listener itself runs
       # as the configured receiver UID — the identity the client verifies on
       # its side. Every identity, framing, deadline or parse failure is
@@ -24,11 +24,15 @@ module Ace
         LIMIT = OrdinarySocket::LIMIT
         DEADLINE_SECONDS = 30
 
-        def initialize(socket_path:, peer_uid:, handler:, lock_path: nil, logger: nil)
+        def initialize(socket_path:, peer_uid:, handler:, socket_gid: nil, lock_path: nil, logger: nil)
           unless socket_path.is_a?(String) && socket_path.start_with?("/") &&
               peer_uid.is_a?(Integer) && peer_uid >= 0 && handler.respond_to?(:call)
             raise ArgumentError, "ordinary listener needs an absolute socket path, a peer uid and a handler"
           end
+          unless socket_gid.nil? || (socket_gid.is_a?(Integer) && socket_gid >= 0)
+            raise ArgumentError, "ordinary listener socket_gid must be a non-negative integer"
+          end
+          @socket_gid = socket_gid
           @socket_path = socket_path
           @peer_uid = peer_uid
           @handler = handler
@@ -40,12 +44,15 @@ module Ace
         # Serve until #stop. Excludes a second listener through one owned
         # lock file, removes only its own stale endpoint, and always removes
         # the endpoint it created.
-        def serve
+        def serve(on_ready: nil)
           acquire_lock!
           remove_stale_endpoint!
           @listener = UNIXServer.new(@socket_path)
-          File.chmod(0o600, @socket_path)
           @endpoint_identity = File.stat(@socket_path)
+          File.chown(nil, @socket_gid, @socket_path) if @socket_gid
+          File.chmod(@socket_gid ? 0o660 : 0o600, @socket_path)
+          on_ready.call if on_ready
+          @handler.recover_pending! if @handler.respond_to?(:recover_pending!)
           until @stopping
             socket = @listener.accept
             serve_connection(socket)
@@ -59,6 +66,11 @@ module Ace
           @lock&.close
         end
 
+        # The existing listener participates in the Assign owner's lifetime.
+        def run(on_ready:)
+          serve(on_ready: on_ready)
+        end
+
         def stop
           @stopping = true
           @listener&.close
@@ -75,26 +87,27 @@ module Ace
             verify_peer!(socket)
             submission = read_request!(socket, deadline)
             response = @handler.call(submission)
-            write_response!(socket, response, deadline)
+            write_response_safely(socket, response, deadline)
             if response.is_a?(Hash) && response["status"] == "ok" && @handler.respond_to?(:execute)
               begin
-                # The durable acknowledgment is already on the wire; the
+                # Admission is durable even if the acknowledgment was lost; the
                 # execution lifetime belongs to the canonical record, not
                 # the short connection. A lost lifecycle stays pending or
                 # uncertain and reconciles by the original reference.
                 @handler.execute(response.dig("data", "request_id"))
-              rescue StandardError
-                nil
+              rescue StandardError => error
+                log_failure("effect", error)
               end
             end
           rescue OrdinaryRefused => e
-            write_response!(socket, e.envelope, deadline)
-          rescue OrdinaryListenerError
+            write_response_safely(socket, e.envelope, deadline)
+          rescue OrdinaryListenerError, IOError, SystemCallError => error
             # Fail closed without a fabricated envelope; the client classifies
             # a lost/unreadable response as ordinary_merge_unavailable.
-            nil
-          rescue StandardError
-            write_response!(socket, refusal_envelope("ordinary_merge_unavailable",
+            log_failure("connection", error)
+          rescue StandardError => error
+            log_failure("request", error)
+            write_response_safely(socket, refusal_envelope("ordinary_merge_unavailable",
               "receiver failed to handle the request"), deadline)
           ensure
             begin
@@ -119,16 +132,27 @@ module Ace
 
         private
 
-        # Mutual half of SO_PEERCRED: the connecting process must run as the
+        def write_response_safely(socket, response, deadline)
+          write_response!(socket, response, deadline)
+        rescue OrdinaryListenerError, IOError, SystemCallError => error
+          log_failure("response", error)
+        end
+
+        def log_failure(phase, error)
+          # Arbitrary exception messages may contain provider credentials or
+          # request bodies. Journal references remain the source of effect state.
+          @logger&.call("ordinary receiver #{phase} failed (#{error.class.name})")
+        end
+
+        # Mutual half of OS peer authentication: the connecting process must run as the
         # configured producer principal UID. Anything else is refused before
         # one byte of request is read.
         def verify_peer!(socket)
-          credentials = socket.getsockopt(:SOCKET, :PEERCRED)
-          _peer_pid, peer_uid, = credentials.unpack("L3")
+          peer_uid, = socket.getpeereid
           return if peer_uid == @peer_uid
           raise OrdinaryRefused, refusal_envelope("ordinary_merge_unauthenticated",
             "connecting principal is not the configured ordinary overseer")
-        rescue SystemCallError, IOError
+        rescue SystemCallError, IOError, SocketError, NotImplementedError
           raise OrdinaryListenerError, "peer credentials are unavailable"
         end
 

data/lib/ace/lab/molecules/ordinary_merge_read.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "ordinary_worktree_read"
+
+module Ace
+  module Lab
+    module Molecules
+      # Local checks are bounded read-only observations. Only the forge provider
+      # executes merge; moving a local ref can never prove a delivered merge.
+      class OrdinaryMergeRead
+        STRATEGY = "ff"
+
+        def initialize(repo_path:, base_ref:, root: repo_path, common_dir: File.join(repo_path, ".git"),
+          deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30)
+          unless repo_path.is_a?(String) && repo_path.start_with?("/") &&
+              base_ref.is_a?(String) && base_ref.start_with?("refs/")
+            raise ArgumentError, "ordinary merge read needs an absolute repository and full base ref"
+          end
+          @repo_path, @base_ref = repo_path, base_ref
+          @reader = OrdinaryWorktreeRead.new(root: root, common_dir: common_dir, deadline: deadline)
+        end
+
+        def base_head
+          @reader.ref_head(@repo_path, @base_ref)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        def candidate_commit?(head)
+          @reader.commit?(@repo_path, head)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        def fast_forwardable?(head)
+          @reader.ancestor?(@repo_path, base_head, head)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        class GitUnavailable < StandardError; end
+      end
+    end
+  end
+end