ace-hitl 0.11.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 579408795de68b05baeeb590eac46687706134301423cb6114874c377d8183ed
-  data.tar.gz: ba4f300554670fb40acd58c470183d70342626b170889bda9944468aa54df6e8
+  metadata.gz: 2529e6b24197617c3554da5d1ff7348b19681769562259b05f6d88f469527cf1
+  data.tar.gz: 76b205cac4da0c4d7a34f391ebf569b8c997af87d47edf8b607d602727f82582
 SHA512:
-  metadata.gz: f421f0a4df5ea2eb782766c259336f1298844b3e8ebcefad34885c446865538f02d4d7da3bedcbc84c254464e8a589ff4d3007de8fbe14d0158ad23edf6118d3
-  data.tar.gz: 5102b14720d671f3252eae1b37b942620128f33df90983877e25354958b147bda0545b86ff946aa35f973210abdea603a342547acf11621b4baf2829c0372a65
+  metadata.gz: 977f6398c3f1e6a10e198c267c9b65af6f6d3ff0a2e668c3e80e4a0ad79a0fc332b9f03081fd0f4bfcd7f995a8c6b3458d5afc1bb39063dafaa4516f2b51d04c
+  data.tar.gz: be81c083da2b5af0a5c97646b621ec2b71a6950025e0da4a608c25a2d28142ec67bba8dab032ccf06c004c3021d1e3d660a2c384a58f4925f4b4690895ea53cb

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-10-04
+
+### Fixed
+- Enforce the persisted OTP challenge deadline at locked consumption, including vault reads that cross expiry. Expired secrets are discarded without a success receipt; memory retention is bounded by both vault TTL and challenge expiry.
+
+- Preserve the authenticated service endpoint when another HITL startup is refused. Serialize listener ownership and remove only the socket acquired by the stopping invocation; stale recovery requires a protected service-owned socket.
+
+### Changed
+
+- Load shared provider references, results, and errors from `ace-hitl-contract`; retain provider registration and locked assignment authority in HITL.
+
 ## [0.11.0] - 2026-10-04
 
 ### Added
@@ -17,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **OTP exact-operation challenges**: an `otp` request exists only with its non-secret publisher evidence (`{operation, result_ref, input_digest, expires_at}`, bounded to 24h); consumption requires the challenge's authorized operation; duplicate consumes replay the receipt WITHOUT the secret bytes. OTP effects are forbidden (the authorized operation consumes the OTP transiently). The service holds OTP bytes in a bounded, TTL-bound memory vault (`OtpVault::MemoryVault`) — secret bytes persist nowhere, transfer exactly once, and a restart deliberately loses the challenge (prompt again).
 
 ### Changed
+- **Hardened privileged lifecycle boundary handling**: boundary-facing provider flows no longer trust ambient test fixtures and the lab-side authorizer validates the same privileged transition rules the service enforces.
 - **BREAKING (pre-1.0, ADR-024)**: `ace-hitl ask/deliver/consume/cancel/pending/states/duty` run through the boundary client — the CLI no longer touches shared store files directly, and broker operations no longer require root (the configured transport identity from the grants document does). The admin binding bypass is removed: EVERY request validates against its live attempt. The `LAB_ATTEMPT_ID` environment default is gone (environment is never attempt authority); `--attempt` is required, and binding requires `--assignment` (managed) or `--work` (legacy path, kept until vs2 switches consumers). Answers and store files are service-owned `0600` — requesters receive bytes over the authenticated boundary, not through file ownership. The multi-UID acceptance fixture (`test/edge/lifecycle/`) proves requester isolation, protected ownership, forged-identity rejection, and one-terminal-transition races under real distinct OS accounts (requires root; CI records the run as advisory evidence).
 
 

data/docs/usage.md

@@ -251,7 +251,12 @@ A consume timeout bounds ONLY the local wait — the request stays
 pending and answerable. OTP consumption requires the challenge's
 authorized operation (`--operation <name>`); the secret transfers
 exactly once and a consumed retry replays the receipt WITHOUT the
-bytes. Cancel is the ONLY way to abandon a request, requester-only;
+bytes. The persisted challenge deadline is checked at the locked handoff;
+consumption at or after that deadline refuses with an expired error and
+discards the pending secret. Memory retention ends at the earlier of the
+challenge deadline and the vault TTL. Delivery, duplicate delivery, waits,
+and service restarts cannot extend the authorized window. Request a fresh
+authorized challenge after expiry. Cancel is the ONLY way to abandon a request, requester-only;
 it records `cancelled_by` and the `reason` in the public projection,
 and late answers/consumes fail closed against the committed receipt.
 

data/lib/ace/hitl/lifecycle/otp_vault.rb

@@ -90,7 +90,10 @@ module Ace
           def write(_store, value, answer)
             key = key_for(value)
             @entries.shift while @entries.length >= @max_entries
-            @entries[key] = Entry.new(answer.dup.freeze, @clock.now.to_i + @ttl_seconds)
+            retention_deadline = @clock.now.to_i + @ttl_seconds
+            challenge_deadline = value.dig("otp", "expires_at")
+            deadline = challenge_deadline ? [retention_deadline, Integer(challenge_deadline)].min : retention_deadline
+            @entries[key] = Entry.new(answer.dup.freeze, deadline)
             nil
           end
 
@@ -101,7 +104,10 @@ module Ace
           def read(store, value)
             entry = @entries[key_for(value)]
             raise MissError, "no OTP is pending for this request" unless entry
-            raise ExpiredError, "the OTP challenge has expired; request a new one" if entry.expires_at <= @clock.now.to_i
+            if entry.expires_at <= @clock.now.to_i
+              @entries.delete(key_for(value))
+              raise ExpiredError, "the OTP challenge has expired; request a new one"
+            end
 
             @entries.delete(key_for(value))
             entry.answer.dup

data/lib/ace/hitl/lifecycle/service.rb

@@ -50,6 +50,8 @@ module Ace
           @connections_mutex = Mutex.new
           @stopping = false
           @server = nil
+          @endpoint_identity = nil
+          @endpoint_lock = nil
         end
 
         # Serve until #stop. Installs TERM/INT handlers for a clean
@@ -125,9 +127,10 @@ module Ace
         def prepare!
           begin
             verify_socket_directory!
-            refuse_live_service!
-            FileUtils.rm_f(@socket_path)
+            acquire_endpoint_lock!
+            recover_stale_endpoint!
             @server = UNIXServer.open(@socket_path)
+            @endpoint_identity = endpoint_identity
           rescue SystemCallError, IOError => e
             raise TransportError, "the HITL boundary endpoint is not usable (#{e.class}: #{e.message})"
           end
@@ -148,8 +151,20 @@ module Ace
         end
 
         def shutdown!
-          @server&.close rescue nil
-          FileUtils.rm_f(@socket_path)
+          begin
+            @server&.close
+          rescue SystemCallError, IOError
+            nil
+          end
+          begin
+            File.unlink(@socket_path) if @endpoint_identity && endpoint_identity == @endpoint_identity
+          rescue Errno::ENOENT
+            nil
+          ensure
+            @endpoint_identity = nil
+            @endpoint_lock&.close
+            @endpoint_lock = nil
+          end
           log("stopped")
         end
 
@@ -229,27 +244,53 @@ module Ace
           ->(limit) { answer[0, limit] }
         end
 
-        # A connectable socket has a live listener: a second service must
-        # refuse to start instead of stealing the endpoint (review
-        # 8x327buq). Only a dead socket (ECONNREFUSED) is removed.
-        def refuse_live_service!
-          return unless File.exist?(@socket_path)
+        # Keep one stable lock inode for the endpoint. Holding the lock
+        # through shutdown prevents simultaneous starters from recovering
+        # or replacing a socket another invocation is still acquiring.
+        # Never unlink the lock file: waiters must all use the same inode.
+        def acquire_endpoint_lock!
+          @endpoint_lock = File.open("#{@socket_path}.lock", File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+          stat = @endpoint_lock.stat
+          unless stat.file? && stat.uid == Process.uid && stat.nlink == 1 && (stat.mode & 0o077).zero?
+            raise TransportError, "HITL boundary endpoint lock is not protected"
+          end
+          return if @endpoint_lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+          raise TransportError,
+            "a HITL boundary service is already serving #{@socket_path}; stop it before starting another"
+        end
+
+        def endpoint_identity
+          stat = File.lstat(@socket_path)
+          [stat.dev, stat.ino] if stat.socket?
+        rescue Errno::ENOENT
+          nil
+        end
 
+        # Only an owned socket whose connection is explicitly refused is
+        # stale. Permission, type and other probe failures cannot grant
+        # authority to delete an endpoint.
+        def recover_stale_endpoint!
+          stat = File.lstat(@socket_path)
+          unless stat.socket? && stat.uid == Process.uid && (stat.mode & 0o002).zero?
+            raise TransportError, "HITL boundary endpoint is not a protected service-owned socket"
+          end
+          identity = [stat.dev, stat.ino]
           begin
             probe = UNIXSocket.open(@socket_path)
-          rescue SystemCallError, IOError
+          rescue Errno::ECONNREFUSED
+            unless endpoint_identity == identity
+              raise TransportError, "HITL boundary endpoint changed during stale socket recovery"
+            end
+            File.unlink(@socket_path)
             return
-          end
-          begin
-            probe.write(Protocol.encode_request("ping"))
-            probe.flush
-          rescue SystemCallError, IOError
-            nil
           ensure
-            probe.close rescue nil
+            probe&.close
           end
           raise TransportError,
             "a HITL boundary service is already serving #{@socket_path}; stop it before starting another"
+        rescue Errno::ENOENT
+          nil
         end
 
         def read_frame(socket)

data/lib/ace/hitl/lifecycle/store.rb

@@ -235,11 +235,18 @@ module Ace
               # fails closed instead of handing over an answer.
               with_live_authority!(value, requester: @identity.username) do
                 verify_operation!(value, operation)
+                verify_otp_deadline!(value)
                 answer = read_answer(value)
                 unless answer
                   next
                 end
 
+                begin
+                  verify_otp_deadline!(value)
+                rescue OtpVault::ExpiredError
+                  answer.clear if value["sensitive"] == true && !answer.frozen?
+                  raise
+                end
                 commit_terminal!(value, "consumed",
                   answer: value["sensitive"] == true ? nil : answer)
                 update_public(value, "consumed")
@@ -341,6 +348,7 @@ module Ace
             # under the lock; report it without a second write or effect.
             return delivered_result(value) if answer_present?(value)
             with_live_authority!(value, requester: value["requester"]) do
+              verify_otp_deadline!(value)
               write_answer(value, answer)
               update_public(value, "answer-delivered")
               unless value["sensitive"] == true
@@ -839,6 +847,15 @@ module Ace
           answer
         end
 
+        # The persisted authorization window applies to every vault and
+        # is checked under the request and live-authority locks at handoff.
+        def verify_otp_deadline!(value)
+          return unless value["otp"] && Integer(value["otp"]["expires_at"]) <= Time.now.to_i
+
+          @vault.discard(self, value)
+          raise OtpVault::ExpiredError, "the OTP challenge has expired; request a new one"
+        end
+
         # Persist the answer service-owned (0600): requesters never touch
         # store files — consumption transfers the bytes over the
         # authenticated boundary. The temporary is unique per invocation

data/lib/ace/hitl/providers/lab/daemon_binding.rb

@@ -2,7 +2,7 @@
 
 require "socket"
 require "json"
-require_relative "../errors"
+require "ace/hitl/contract"
 require_relative "../../lifecycle/errors"
 
 module Ace

data/lib/ace/hitl/providers/lab.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
-require_relative "errors"
+require "ace/hitl/contract"
 require_relative "lab/daemon_binding"
 require_relative "lab/assignment_binding"
 require_relative "lab/composite_binding"

data/lib/ace/hitl/providers/providers.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "errors"
-require_relative "ref"
+require "ace/hitl/contract"
 require_relative "lab"
 
 module Ace
@@ -10,13 +9,6 @@ module Ace
     # transports behind one interface. Agent-facing ace-hitl paths resolve
     # adapters through this registry only — never a concrete transport.
     module Providers
-      # ask(question:, ...) result: local event id + relay request id.
-      AskResult = Struct.new(:event_id, :request_id, keyword_init: true)
-
-      # deliver(ref, answer) result; state is :delivered, :retryable
-      # (safe to re-push identical content) or :failed.
-      DeliverResult = Struct.new(:ref, :state, keyword_init: true)
-
       REGISTRY = {
         Lab::PROVIDER_NAME => -> { Lab.new }
       }.freeze

data/lib/ace/hitl/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Hitl
-    VERSION = "0.11.0"
+    VERSION = "0.11.1"
   end
 end

data/lib/ace/hitl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ace/support/items"
+require "ace/hitl/contract"
 require_relative "hitl/version"
 require_relative "hitl/atoms/hitl_file_pattern"
 require_relative "hitl/atoms/hitl_id_formatter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Michal Czyz
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-hitl-contract
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: ace-support-core
   requirement: !ruby/object:Gem::Requirement
@@ -99,14 +113,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.62'
+        version: 0.63.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.62'
+        version: 0.63.1
 description: Provides the dedicated ace-hitl package surface for human in the loop
   (HITL) semantics and CLI workflows.
 email:
@@ -179,13 +193,11 @@ files:
 - lib/ace/hitl/molecules/resume_dispatcher.rb
 - lib/ace/hitl/molecules/worktree_scope_resolver.rb
 - lib/ace/hitl/organisms/hitl_manager.rb
-- lib/ace/hitl/providers/errors.rb
 - lib/ace/hitl/providers/lab.rb
 - lib/ace/hitl/providers/lab/assignment_binding.rb
 - lib/ace/hitl/providers/lab/composite_binding.rb
 - lib/ace/hitl/providers/lab/daemon_binding.rb
 - lib/ace/hitl/providers/providers.rb
-- lib/ace/hitl/providers/ref.rb
 - lib/ace/hitl/version.rb
 homepage: https://github.com/cs3b/ace
 licenses:

data/lib/ace/hitl/providers/errors.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Ace
-  module Hitl
-    module Providers
-      # Error model for HITL provider adapters (spec 8wm.t.vrz §2).
-      class Error < StandardError; end
-
-      # The provider name is not in the registry.
-      class UnknownProviderError < Error; end
-
-      # The reverse address (herdr session + pane) is absent or invalid.
-      # Ask fails closed before any event or transport state is created.
-      class InvalidRefError < Error; end
-
-      # The transport send failed (binary missing, non-zero exit,
-      # unparseable output) after the local event may already exist.
-      class ProviderUnavailableError < Error; end
-
-      # The provider does not implement the requested operation.
-      class UnsupportedOperationError < Error; end
-    end
-  end
-end

data/lib/ace/hitl/providers/ref.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "errors"
-
-module Ace
-  module Hitl
-    module Providers
-      # Typed reverse address of the asking agent: herdr session + pane
-      # (spec 8wm.t.vrz §3). Versioned schema ace.hitl.ref/v1; captured
-      # fail-closed from the herdr environment at ask time. ace-herdr
-      # exports both variables when it bootstraps an agent pane.
-      #
-      # The ref identifies WHERE the answer goes; it never carries answer
-      # content.
-      class Ref
-        SCHEMA = "ace.hitl.ref/v1"
-        SESSION_ENV = "HERDR_SESSION"
-        PANE_ENV = "HERDR_PANE"
-        MAX_LENGTH = 128
-        TOKEN_PATTERN = /\A[A-Za-z0-9._:-]+\z/.freeze
-
-        attr_reader :session, :pane
-
-        def initialize(session:, pane:)
-          @session = session
-          @pane = pane
-        end
-
-        # Fail closed: raises InvalidRefError naming the offending variable
-        # and rule when the reverse address is absent or invalid.
-        def self.from_env(env = ENV)
-          session = validate!(env[SESSION_ENV], SESSION_ENV)
-          pane = validate!(env[PANE_ENV], PANE_ENV)
-          new(session: session, pane: pane)
-        end
-
-        def self.validate!(value, source)
-          token = value.to_s.strip
-          if token.empty?
-            raise InvalidRefError,
-              "#{source} is required (herdr reverse address, #{SCHEMA})"
-          end
-          if token.length > MAX_LENGTH
-            raise InvalidRefError,
-              "#{source} exceeds #{MAX_LENGTH} characters"
-          end
-          unless token.match?(TOKEN_PATTERN)
-            raise InvalidRefError,
-              "#{source} contains invalid characters " \
-              "(allowed: letters, digits, '.', '_', ':', '-')"
-          end
-
-          token
-        end
-
-        def to_h
-          {schema: SCHEMA, session: session, pane: pane}
-        end
-      end
-    end
-  end
-end