ace-hitl 0.17.0 → 0.23.2

data/lib/ace/hitl/organisms/hitl_sender.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "time"
+require "ace/support/items"
+require_relative "../adapters"
+require_relative "../atoms/hitl_event_text"
+require_relative "../molecules/hitl_route_loader"
+require_relative "../molecules/hitl_delivery_state"
+require_relative "hitl_manager"
+
+module Ace
+  module Hitl
+    module Organisms
+      # Delivers one persisted HITL event through the configured adapter
+      # route set. The sender's interface is adapter-independent: routes
+      # come from configuration, every route is invoked independently, and
+      # per-route failures never prevent or substitute another route's
+      # delivery (no silent rerouting).
+      #
+      # Retention (8xg.t.sbz.1.3): each route's last outcome, failure
+      # reason, and attempt timestamp are persisted on the event file
+      # itself (`delivery.<route>` frontmatter) — the single state owner.
+      # Default redelivery retries only undelivered/unknown routes;
+      # `force:` redelivers every route with the SAME case ID and content
+      # (at-least-once: recipients dedup by case ID). Redelivery retries
+      # the delivery, never the assignment.
+      class HitlSender
+        SendReport = Struct.new(:event_id, :results, :skipped, keyword_init: true) do
+          def all_delivered?
+            results.all?(&:delivered?) && skipped.all?(&:delivered?)
+          end
+        end
+
+        SkippedRoute = Struct.new(:route, :adapter, :status, :detail, keyword_init: true) do
+          def delivered?
+            status == :delivered
+          end
+        end
+
+        def initialize(manager: nil, config: nil, adapters: Adapters, now_proc: nil)
+          @manager = manager || HitlManager.new(config: config)
+          @config = config || @manager.config
+          @adapters = adapters
+          @now_proc = now_proc || -> { Time.now.utc }
+        end
+
+        # @param ref [String] event reference (exact ID or unique shortcut)
+        # @param force [Boolean] redeliver every configured route
+        # @param dry_run [Boolean] report decisions only; no delivery, no write
+        # @return [SendReport]
+        # @raise [Molecules::HitlRouteLoader::NoRoutesError,
+        #   Molecules::HitlRouteLoader::InvalidRouteError] before any delivery attempt
+        def send(ref, scope: nil, force: false, dry_run: false)
+          routes = Molecules::HitlRouteLoader.load(@config)
+
+          current = @manager.show(ref, scope: scope)
+          raise Adapters::Error, "HITL event '#{ref}' not found" unless current
+
+          event = current[:event]
+          routes = Molecules::HitlRouteLoader.for_recipient(routes, recipient: event.recipient, config: @config)
+          text = Atoms::HitlEventText.call(event)
+          delivery = event.metadata["delivery"]
+
+          attempted, skipped = partition_routes(routes, delivery, force)
+
+          if dry_run
+            results = attempted.map do |route|
+              reason = if force
+                "force - will redeliver"
+              elsif Molecules::HitlDeliveryState.unknown?(delivery&.dig(route["route"]))
+                "unknown result - will retry"
+              else
+                "undelivered - will retry"
+              end
+              Adapters::RouteResult.new(route: route["route"], adapter: route["adapter"],
+                status: :dry_run, detail: reason)
+            end
+            return SendReport.new(event_id: event.id, results: results, skipped: skipped)
+          end
+
+          results = attempted.map do |route|
+            persist_delivery(event, route, "in_flight", nil)
+            deliver_route(route, event: event, text: text).tap do |result|
+              persist_delivery(event, route, result.status.to_s, result.detail)
+            end
+          end
+
+          SendReport.new(event_id: event.id, results: results, skipped: skipped)
+        end
+
+        private
+
+        def partition_routes(routes, delivery, force)
+          attempted = []
+          skipped = []
+          routes.each do |route|
+            record = delivery.is_a?(Hash) ? delivery[route["route"]] : nil
+            if !force && !Molecules::HitlDeliveryState.retry?(record)
+              skipped << SkippedRoute.new(route: route["route"], adapter: route["adapter"],
+                status: :delivered, detail: "already delivered (#{record["attempted_at"]})")
+            else
+              attempted << route
+            end
+          end
+          [attempted, skipped]
+        end
+
+        # Nested dot-keys through FieldUpdater: exclusive-flock atomic
+        # rewrite of the event's own file (single state owner).
+        def persist_delivery(event, route, status, detail)
+          Ace::Support::Items::Molecules::FieldUpdater.update(event.file_path,
+            set: {
+              "delivery.#{route["route"]}.status" => status,
+              "delivery.#{route["route"]}.adapter" => route["adapter"],
+              "delivery.#{route["route"]}.detail" => detail,
+              "delivery.#{route["route"]}.attempted_at" => @now_proc.call.iso8601
+            })
+        end
+
+        # One route's failure is contained to its own result; the remaining
+        # routes still run and nothing is ever sent to a different
+        # destination than the route's own configuration.
+        def deliver_route(route, event:, text:)
+          adapter_name = route["adapter"]
+          route = route.merge("machine" => @config.dig("hitl", "machine").to_s) do |_key, route_val, config_val|
+            route_val.to_s.strip.empty? ? config_val : route_val
+          end
+          adapter = @adapters.resolve(adapter_name, route: route)
+          adapter.deliver(event: event, text: text,
+            recipient: event.recipient, reply_to: event.reply_to)
+        rescue Adapters::UnknownAdapterError => e
+          # The route's adapter cannot be resolved: record it as
+          # unavailable with the reason (never a bare in_flight marker)
+          # and keep going so healthy routes still deliver.
+          Adapters::RouteResult.new(
+            route: route["route"], adapter: adapter_name,
+            status: :unavailable, detail: e.message
+          )
+        rescue StandardError => e
+          Adapters::RouteResult.new(
+            route: route["route"], adapter: adapter_name,
+            status: :failed, detail: "#{e.class}: #{e.message}"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require "securerandom"
 require "ace/hitl/contract"
-require_relative "lab/assignment_binding"
 require_relative "../lifecycle/store"
 require_relative "../lifecycle/policy"
 require_relative "../lifecycle/client"
@@ -10,47 +8,26 @@ require_relative "../lifecycle/client"
 module Ace
   module Hitl
     module Providers
-      # provider=lab adapter (spec 8wm.t.vrz §1; lifecycle migration
-      # spec 8wm.t.y21 §1; scoped boundary 8wq.t.34i): ONE ask operation
-      # = local HITL event + relay request created through the scoped
-      # store boundary with the lab-backed binding policy. Owns every
-      # lab-specific seam; agent-facing ace-hitl paths must never bypass
-      # it (guard-tested).
+      # Deployment facts for the host-installed HITL lifecycle transport:
+      # the trusted grants policy and the authenticated boundary client.
+      # The managed `ask`/native-delivery path and its attempt-bound
+      # assignment binding were removed with the old authority model; the
+      # local file-based commands and the lifecycle/relay transport remain.
       class Lab
-        DEFAULT_PROJECT = "ace"
-        DEFAULT_HARNESS = "lab-admin"
-        DEFAULT_PLAN = "ace-hitl ask"
         DEFAULT_STORE_ROOT = "/run/lab/hitl"
         STORE_ROOT_ENV = "ACE_HITL_STORE_ROOT"
         DEFAULT_SOCKET_PATH = "/run/lab/hitl.sock"
         SOCKET_PATH_ENV = "ACE_HITL_SOCKET"
-        # The trusted deployment grants document, shared with ace-lab's
-        # GrantResolver (same format, same trust rules). The PATH may be
-        # overridden for tests; the document's trust is verified
-        # absolutely (root-owned, protected traversal), so an override
-        # cannot inject authority.
+        # The trusted deployment grants document, shared with the operator
+        # question and transport authorization facts. The PATH may be
+        # overridden for tests; the document's trust is verified absolutely
+        # (root-owned, protected traversal), so an override cannot inject
+        # authority.
         DEFAULT_GRANTS_PATH = "/etc/lab/ace-lab/authorization.yml"
         GRANTS_PATH_ENV = "ACE_HITL_GRANTS_PATH"
 
-        PROVIDER_NAME = "lab"
-
-        def initialize(manager: nil, store: nil, binding: nil, live_client: nil)
-          @manager = manager
-          # The boundary dependency: an injected store (unit wiring) or
-          # the authenticated boundary client (review 8x333sqz).
-          @boundary = store
-          @binding = binding
-          @live_client = live_client
-        end
-
-        # The managed binding authority (spec 8wq.t.34i): assignment
-        # attempts verified through the ace-assign coordinator.
-        def self.assignment_binding(repo_root: nil)
-          AssignmentBinding.new(repo_root: repo_root)
-        end
-
         # The transport/service authorization policy from the trusted
-        # grants document (ace-lab supplies the deployment facts).
+        # grants document.
         def self.grants_policy(grants_path: nil, document: nil)
           Lifecycle::GrantsPolicy.new(
             grants_path: grants_path || ENV[GRANTS_PATH_ENV] || DEFAULT_GRANTS_PATH,
@@ -58,10 +35,10 @@ module Ace
           )
         end
 
-        # The authenticated boundary client for CLI operations. The
-        # service identity comes ONLY from the trusted grants document;
-        # without it the boundary is unconfigured and every lifecycle
-        # operation fails closed with a visible transport error.
+        # The authenticated boundary client for CLI operations. The service
+        # identity comes ONLY from the trusted grants document; without it
+        # the boundary is unconfigured and every lifecycle operation fails
+        # closed with a visible transport error.
         def self.boundary_client(socket_path: nil, policy: nil)
           policy ||= grants_policy
           service_uid = policy.service_uid
@@ -76,97 +53,6 @@ module Ace
             service_uid: service_uid
           )
         end
-
-        # Local event + scoped request in ONE operation. The authenticated
-        # managed binding supplies the verified reverse; callers cannot choose it.
-        def ask(question:, attempt:, assignment:, title: nil,
-          kind: "text", otp: nil, project: DEFAULT_PROJECT, harness: DEFAULT_HARNESS,
-          plan: DEFAULT_PLAN, effect: {})
-          effect = effect.to_h
-          request_id = "hitl-#{SecureRandom.hex(8)}"
-          manager = build_manager
-          event = manager.create(title || question, questions: [question])
-
-          # The ask reaches the store through the AUTHENTICATED BOUNDARY
-          # (spec 8wq.t.34i): requesters never write shared store files.
-          # An injected store stays available for unit-level wiring.
-          begin
-            created = boundary.create(
-              id: request_id,
-              assignment: assignment,
-              attempt: attempt,
-              kind: kind,
-              otp: otp,
-              project: project,
-              harness: harness,
-              plan: plan,
-              question: question,
-              ace_hitl_id: event.id,
-              effect: effect_declared?(effect) ? effect : nil
-            )
-            envelope = Contract::ManagedEnvelope.load(created.fetch("envelope"), expected: {
-              request_id: request_id, assignment_id: assignment, attempt_id: attempt, project: project,
-              correlation_id: request_id, kind: kind
-            })
-            address = envelope["reverse"]
-            raise Lifecycle::BindingError, "managed ask has no verified native reverse address" unless address
-            ref = Ref.new(session: address.fetch("session"), pane: address.fetch("pane"))
-          rescue Lifecycle::Error, Contract::InvalidEnvelope, KeyError => e
-            raise ProviderUnavailableError,
-              "#{e.message}; local HITL event #{event.id} was created but never bound to a " \
-              "Lab request (orphan) - inspect it with ace-hitl show #{event.id} and delete " \
-              "or re-ask as needed"
-          end
-
-          manager.update(event.id, set: {
-            "provider" => PROVIDER_NAME,
-            "ref_schema" => ref.to_h[:schema],
-            "ref_session" => ref.session,
-            "ref_pane" => ref.pane,
-            "lab_request_id" => request_id,
-            "lab_request_state" => "created",
-            "lab_request_effect" => effect_declared?(effect) ? "declared" : "none"
-          })
-
-          AskResult.new(event_id: event.id, request_id: request_id, ref: ref)
-        end
-
-        def deliver(request:, timeout: 0)
-          live_client.deliver(request: request, timeout: timeout)
-        end
-
-        def watch(request:, timeout: 0, &observer)
-          live_client.watch(request: request, timeout: timeout, &observer)
-        end
-
-        def wait(request:, timeout: 0, operation: nil)
-          live_client.wait(request: request, timeout: timeout, operation: operation)
-        end
-
-        private
-
-        def live_client
-          require_relative "../live_client"
-          @live_client ||= LiveClient.new(boundary: boundary)
-        end
-
-        def effect_declared?(effect)
-          !!(effect[:match] || effect[:effect_cwd] || effect[:effect_timeout] ||
-            Array(effect[:effect_args]).any?)
-        end
-
-        def boundary
-          @boundary || self.class.boundary_client
-        end
-
-        def build_manager
-          return @manager if @manager
-
-          # Boundary-only consumers use fixed grants and authenticated transport;
-          # local event configuration belongs to the ask operation alone.
-          require_relative "../organisms/hitl_manager"
-          Organisms::HitlManager.new
-        end
       end
     end
   end

data/lib/ace/hitl/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Hitl
-    VERSION = "0.17.0"
+    VERSION = "0.23.2"
   end
 end

data/lib/ace/hitl.rb

@@ -5,6 +5,7 @@ require "ace/hitl/contract"
 require_relative "hitl/version"
 require_relative "hitl/atoms/hitl_file_pattern"
 require_relative "hitl/atoms/hitl_id_formatter"
+require_relative "hitl/atoms/hitl_address"
 require_relative "hitl/models/hitl_event"
 require_relative "hitl/lifecycle"
 require_relative "hitl/molecules/hitl_config_loader"
@@ -16,8 +17,14 @@ require_relative "hitl/molecules/hitl_answer_editor"
 require_relative "hitl/molecules/hitl_creator"
 require_relative "hitl/molecules/resume_dispatcher"
 require_relative "hitl/molecules/worktree_scope_resolver"
+require_relative "hitl/molecules/hitl_address_resolver"
+require_relative "hitl/atoms/hitl_event_text"
+require_relative "hitl/molecules/hitl_route_loader"
+require_relative "hitl/adapters"
+require_relative "hitl/adapters/terminal"
 require_relative "hitl/organisms/hitl_manager"
-require_relative "hitl/providers/providers"
+require_relative "hitl/organisms/hitl_sender"
+require_relative "hitl/providers/lab"
 require_relative "hitl/live_client"
 require_relative "hitl/cli"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.23.2
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-hitl-contract
@@ -107,34 +107,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
-- !ruby/object:Gem::Dependency
-  name: ace-assign
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.70'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.70'
-- !ruby/object:Gem::Dependency
-  name: ace-herdr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.6'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: ace-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -172,11 +144,15 @@ files:
 - handbook/skills/as-hitl/SKILL.md
 - handbook/workflow-instructions/hitl.wf.md
 - lib/ace/hitl.rb
+- lib/ace/hitl/adapters.rb
+- lib/ace/hitl/adapters/registry.rb
+- lib/ace/hitl/adapters/terminal.rb
+- lib/ace/hitl/atoms/hitl_address.rb
 - lib/ace/hitl/atoms/hitl_effect_validator.rb
+- lib/ace/hitl/atoms/hitl_event_text.rb
 - lib/ace/hitl/atoms/hitl_file_pattern.rb
 - lib/ace/hitl/atoms/hitl_id_formatter.rb
 - lib/ace/hitl/cli.rb
-- lib/ace/hitl/cli/commands/ask.rb
 - lib/ace/hitl/cli/commands/cancel.rb
 - lib/ace/hitl/cli/commands/consume.rb
 - lib/ace/hitl/cli/commands/create.rb
@@ -185,12 +161,9 @@ files:
 - lib/ace/hitl/cli/commands/lifecycle_command.rb
 - lib/ace/hitl/cli/commands/list.rb
 - lib/ace/hitl/cli/commands/operator_question.rb
-- lib/ace/hitl/cli/commands/overseer_ack.rb
-- lib/ace/hitl/cli/commands/overseer_pending.rb
-- lib/ace/hitl/cli/commands/overseer_send.rb
 - lib/ace/hitl/cli/commands/pending.rb
-- lib/ace/hitl/cli/commands/proposal.rb
 - lib/ace/hitl/cli/commands/read.rb
+- lib/ace/hitl/cli/commands/send.rb
 - lib/ace/hitl/cli/commands/serve.rb
 - lib/ace/hitl/cli/commands/show.rb
 - lib/ace/hitl/cli/commands/states.rb
@@ -211,14 +184,11 @@ files:
 - lib/ace/hitl/lifecycle/lifecycle_requests.rb
 - lib/ace/hitl/lifecycle/operator_questions.rb
 - lib/ace/hitl/lifecycle/otp_vault.rb
-- lib/ace/hitl/lifecycle/overseer.rb
 - lib/ace/hitl/lifecycle/peer.rb
 - lib/ace/hitl/lifecycle/policy.rb
-- lib/ace/hitl/lifecycle/proposals.rb
 - lib/ace/hitl/lifecycle/protocol.rb
 - lib/ace/hitl/lifecycle/remote_peer.rb
 - lib/ace/hitl/lifecycle/service.rb
-- lib/ace/hitl/lifecycle/service_publication_binding.rb
 - lib/ace/hitl/lifecycle/store.rb
 - lib/ace/hitl/lifecycle/tls_access_policy.rb
 - lib/ace/hitl/lifecycle/tls_authority.rb
@@ -228,22 +198,21 @@ files:
 - lib/ace/hitl/lifecycle/tls_service.rb
 - lib/ace/hitl/live_client.rb
 - lib/ace/hitl/models/hitl_event.rb
+- lib/ace/hitl/molecules/hitl_address_resolver.rb
 - lib/ace/hitl/molecules/hitl_answer_editor.rb
 - lib/ace/hitl/molecules/hitl_config_loader.rb
 - lib/ace/hitl/molecules/hitl_creator.rb
+- lib/ace/hitl/molecules/hitl_delivery_state.rb
 - lib/ace/hitl/molecules/hitl_display_formatter.rb
 - lib/ace/hitl/molecules/hitl_loader.rb
 - lib/ace/hitl/molecules/hitl_resolver.rb
+- lib/ace/hitl/molecules/hitl_route_loader.rb
 - lib/ace/hitl/molecules/hitl_scanner.rb
 - 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/proposals/evaluator.rb
-- lib/ace/hitl/proposals/policy.rb
+- lib/ace/hitl/organisms/hitl_sender.rb
 - lib/ace/hitl/providers/lab.rb
-- lib/ace/hitl/providers/lab/assignment_binding.rb
-- lib/ace/hitl/providers/lab/protected_assignment_binding.rb
-- lib/ace/hitl/providers/providers.rb
 - lib/ace/hitl/version.rb
 homepage: https://github.com/cs3b/ace
 licenses:

data/lib/ace/hitl/cli/commands/ask.rb

@@ -1,136 +0,0 @@
-# frozen_string_literal: true
-
-require "ace/support/cli"
-require_relative "../../lifecycle"
-require_relative "../../atoms/hitl_effect_validator"
-require_relative "../../providers/providers"
-
-module Ace
-  module Hitl
-    module CLI
-      module Commands
-        class Ask < Ace::Support::Cli::Command
-          include Ace::Support::Cli::Base
-
-          desc "Ask a human via HITL and forward the request through a provider adapter"
-
-          option :question, type: :string, required: true, desc: "Question text for the human"
-
-          option :title, type: :string, desc: "Local HITL event title (defaults to the question)"
-          option :provider, type: :string, desc: "HITL provider adapter (default: ACE_HITL_PROVIDER or lab)"
-          # Managed binding (spec 8wq.t.34i): the request binds to the
-          # exact active managed attempt of the calling identity.
-          option :assignment, type: :string, desc: "Managed assignment id (compact id)"
-          option :kind, type: :string, desc: "Request kind (default: text; otp requires the challenge evidence)"
-          option :"otp-operation", type: :string, desc: "OTP challenge: the ONE authorized operation name"
-          option :"otp-result-ref", type: :string, desc: "OTP challenge: OTP-required publisher result reference"
-          option :"otp-input-digest", type: :string, desc: "OTP challenge: sha256 input digest of the authorized input"
-          option :"otp-expires-at", type: :string, desc: "OTP challenge: expiry as unix seconds (<= 24h ahead)"
-          option :attempt, type: :string, desc: "Attempt id of the exact active attempt"
-          option :project, type: :string, desc: "Lab project label (default: ace)"
-          option :harness, type: :string, desc: "Lab harness label (default: lab-admin)"
-          option :plan, type: :string, desc: "Lab plan label (default: ace-hitl ask)"
-
-          option :"effect-match", type: :string, desc: "Effect callback regex gate on the answer (<= 200 chars)"
-          option :"effect-arg", type: :string, repeat: true, desc: "Effect callback argv element, repeatable (1..16 x 1..512 chars)"
-          option :"effect-cwd", type: :string, desc: "Effect callback working directory (absolute, must exist)"
-          option :"effect-timeout-s", type: :string, desc: "Effect callback timeout in seconds (1..600)"
-
-          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
-          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
-          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
-
-          def call(question:, **options)
-            effect = build_effect(options)
-            validate_effect!(effect)
-
-            assignment = require_binding!(options)
-            attempt = require_attempt!(options)
-            otp = build_otp_challenge!(options)
-            provider = resolve_provider(options[:provider])
-
-            result = provider.ask(
-              question: question,
-              title: options[:title],
-              assignment: assignment,
-              attempt: attempt,
-              kind: options[:kind] || "text",
-              otp: otp,
-              project: options[:project] || Providers::Lab::DEFAULT_PROJECT,
-              harness: options[:harness] || Providers::Lab::DEFAULT_HARNESS,
-              plan: options[:plan] || Providers::Lab::DEFAULT_PLAN,
-              effect: effect
-            )
-
-            puts "HITL event: #{result.event_id}"
-            ref = result.ref
-            puts "Provider: #{Providers::Lab::PROVIDER_NAME} (ref #{ref.session}/#{ref.pane}, #{Providers::Ref::SCHEMA})"
-            puts "Lab request: #{result.request_id}"
-          rescue Providers::ProviderUnavailableError => e
-            raise_cli_error(e.message)
-          end
-
-          private
-
-          def build_effect(options)
-            {
-              match: options[:"effect-match"],
-              effect_args: Array(options[:"effect-arg"]),
-              effect_cwd: options[:"effect-cwd"],
-              effect_timeout: options[:"effect-timeout-s"]
-            }
-          end
-
-          def validate_effect!(effect)
-            Atoms::HitlEffectValidator.validate!(**effect)
-          rescue Atoms::HitlEffectValidator::ValidationError => e
-            raise_cli_error(e.message)
-          end
-
-          def require_binding!(options)
-            assignment = options[:assignment]
-            raise_cli_error("--assignment required (the managed assignment id)") if assignment.nil? || assignment.strip.empty?
-            assignment
-          end
-
-          # The OTP challenge evidence is non-secret, structurally
-          # validated store-side; the CLI only assembles it (spec
-          # 8wq.t.34i: no publisher result, no OTP request).
-          def build_otp_challenge!(options)
-            kind = options[:kind] || "text"
-            return nil unless kind == "otp"
-
-            operation = options[:"otp-operation"]
-            result_ref = options[:"otp-result-ref"]
-            input_digest = options[:"otp-input-digest"]
-            expires_at = options[:"otp-expires-at"]
-            missing = %w[--otp-operation --otp-result-ref --otp-input-digest --otp-expires-at]
-              .zip([operation, result_ref, input_digest, expires_at])
-              .select { |_flag, value| value.nil? || value.to_s.strip.empty? }
-              .map(&:first)
-            raise_cli_error("OTP requests require #{missing.join(", ")} (the OTP-required publisher evidence)") unless missing.empty?
-
-            {operation: operation, result_ref: result_ref, input_digest: input_digest, expires_at: expires_at}
-          end
-
-          def require_attempt!(options)
-            attempt = options[:attempt]
-            unless attempt && !attempt.strip.empty?
-              raise_cli_error("--attempt required (the exact active attempt id)")
-            end
-
-            attempt
-          end
-
-          def resolve_provider(raw)
-            name = raw || ENV["ACE_HITL_PROVIDER"] || Providers::Lab::PROVIDER_NAME
-            Providers.resolve(name)
-          rescue Providers::UnknownProviderError => e
-            raise_cli_error(e.message)
-          end
-
-        end
-      end
-    end
-  end
-end

data/lib/ace/hitl/cli/commands/overseer_ack.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-require "ace/support/cli"
-require_relative "lifecycle_command"
-
-module Ace
-  module Hitl
-    module CLI
-      module Commands
-        # Host-broker acknowledgement of one relayed Overseer response.
-        class OverseerAck < Ace::Support::Cli::Command
-          include Ace::Support::Cli::Base
-          include LifecycleCommand
-
-          desc "Acknowledge (remove) one relayed Overseer response"
-
-          argument :id, required: true, desc: "Overseer response message id"
-
-          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
-
-          def call(id:, **options)
-            emit(overseer.ack(id))
-          rescue Lifecycle::Error => e
-            raise_lifecycle_error(e.message)
-          end
-        end
-      end
-    end
-  end
-end