ace-hitl 0.17.0 → 0.23.2

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

@@ -15,7 +15,6 @@ require_relative "operator_questions"
 require_relative "effects"
 require_relative "otp_vault"
 require_relative "protocol"
-require_relative "proposals"
 
 module Ace
   module Hitl
@@ -39,7 +38,6 @@ module Ace
       #   or replaced attempts cannot acquire new authority.
       class Store
         include OperatorQuestions
-        include Proposals
         MAX_ANSWER = 4096
         # IO#read(limit) is byte-oriented, so the character limit is
         # enforced on a decoded string with this separate byte bound
@@ -82,7 +80,7 @@ module Ace
 
         def initialize(root:, binding:, policy: AccessPolicy.new,
           identity: Identity, ownership: AtomicJson::DEFAULT_OWNERSHIP,
-          poll_seconds: CONSUME_POLL_SECONDS, vault: :file, proposal_clock: -> { Time.now.utc },
+          poll_seconds: CONSUME_POLL_SECONDS, vault: :file,
           stopping: -> { false }, group: DEFAULT_GROUP)
           raise ArgumentError, "a binding policy is required (fail closed without one)" unless binding
           raise ArgumentError, "an access policy is required (fail closed without one)" unless policy
@@ -94,7 +92,6 @@ module Ace
           @ownership = ownership
           @poll_seconds = poll_seconds
           @vault = vault == :file ? OtpVault::FileVault : vault
-          @proposal_clock = proposal_clock
           @stopping = stopping
           @group = group
         end
@@ -113,39 +110,15 @@ module Ace
         # validates its binding — unknown identity/authority is an
         # error, never permission.
         def create(id:, attempt:, plan:, question:, ace_hitl_id:, project: "ace", harness: "lab-admin",
-          assignment:, kind: "text", options: [], effect: nil, otp: nil, publication_binding: nil)
-          raise StateError, "proposal kind must use proposal_create" if kind == "proposal"
+          assignment:, kind: "text", options: [], effect: nil, otp: nil)
           value = prepare_request(id: id, attempt: attempt, plan: plan, question: question,
             ace_hitl_id: ace_hitl_id, project: project, harness: harness, assignment: assignment,
-            kind: kind, options: options, effect: effect, otp: otp, publication_binding: publication_binding)
-          return persist_request(value) unless value["publication_binding"]
-          with_request_lock(value.fetch("id")) do
-            with_live_authority!(value, requester: @identity.username) do
-              if value["publication_binding"]
-                if load_terminal(value.fetch("id"))
-                  raise StateError, "publication HITL id is already terminal"
-                end
-                duplicate = request_path(value.fetch("id")).exist? && load_request(value.fetch("id"))
-                if duplicate
-                  unless duplicate.slice("publication_binding", "publication_requester_peer", "otp") == value.slice("publication_binding", "publication_requester_peer", "otp")
-                    raise StateError, "publication HITL id has different binding"
-                  end
-                  return {"id" => duplicate.fetch("id"), "requested" => true, "replay" => true, "envelope" => duplicate.fetch("envelope")}
-                end
-                requests_dir.glob("*.json").each do |path|
-                  existing = AtomicJson.read(path)
-                  if existing["publication_binding"] == value["publication_binding"]
-                    raise StateError, "publication challenge already has an active HITL request"
-                  end
-                end
-              end
-              persist_request_locked!(value)
-            end
-          end
+            kind: kind, options: options, effect: effect, otp: otp)
+          persist_request(value)
         end
 
         def prepare_request(id:, attempt:, plan:, question:, ace_hitl_id:, project: "ace", harness: "lab-admin",
-          assignment:, kind: "text", options: [], effect: nil, otp: nil, publication_binding: nil)
+          assignment:, kind: "text", options: [], effect: nil, otp: nil)
           requester = @identity.username
           request_id = safe_id(id)
           validate_binding_ids!(assignment, attempt)
@@ -154,8 +127,7 @@ module Ace
           end
           plan = plan.to_s.strip
           question = question.to_s.strip
-          question_too_long = kind == "proposal" ? question.bytesize > 4096 : question.length > MAX_PLAN_QUESTION
-          if plan.empty? || plan.length > MAX_PLAN_QUESTION || question.empty? || question_too_long
+          if plan.empty? || plan.length > MAX_PLAN_QUESTION || question.empty? || question.length > MAX_PLAN_QUESTION
             raise StateError, "plan and question must contain 1-#{MAX_PLAN_QUESTION} characters"
           end
           options = Array(options).map(&:strip)
@@ -168,8 +140,6 @@ module Ace
           unless Kinds.valid?(kind)
             raise StateError, "unknown HITL kind: #{kind}"
           end
-          raise StateError, "proposal effects belong to ace-assign" if kind == "proposal" && effect
-          require_proposer!(project) if kind == "proposal"
           if Kinds.secret?(kind)
             unless options.empty?
               raise StateError, "OTP requests must not offer choices"
@@ -178,13 +148,7 @@ module Ace
             challenge = normalize_otp_challenge!(otp)
           end
 
-          if publication_binding
-            raise StateError, "publication HITL must be OTP" unless kind == "otp"
-            publication_binding = JSON.parse(JSON.generate(publication_binding))
-            reverse = nil
-          else
-            reverse = validate_request_binding(assignment, attempt, project, requester)
-          end
+          reverse = validate_request_binding(assignment, attempt, project, requester)
 
           value = {
             "id" => request_id,
@@ -202,7 +166,6 @@ module Ace
             "created_at" => Time.now.to_i
           }
           value["otp"] = challenge if challenge
-          value["publication_binding"] = publication_binding if publication_binding
           Effects.validate_declaration!(effect) if effect
           value["effect"] = Effects.normalized_declaration(effect) if effect
           value["incarnation"] = SecureRandom.hex(8)
@@ -272,7 +235,7 @@ module Ace
             terminal = load_terminal(request_id)
             if terminal
               gate_read_access!(terminal)
-              return terminal.slice("id", "assignment", "attempt", "project", "requester", "requester_uid", "sensitive", "envelope", "state", "native_delivery", "effect_receipt_ref", "publication_binding", "publication_requester_peer", "otp")
+              return terminal.slice("id", "assignment", "attempt", "project", "requester", "requester_uid", "sensitive", "envelope", "state", "native_delivery", "effect_receipt_ref", "otp")
                 .merge("kind" => terminal.dig("envelope", "kind"))
             end
           end
@@ -290,8 +253,6 @@ module Ace
             "options" => value["options"],
             "plan" => value["plan"],
             "otp" => value["otp"],
-            "publication_binding" => value["publication_binding"],
-            "publication_requester_peer" => value["publication_requester_peer"],
             "requester" => value["requester"],
             "requester_uid" => value["requester_uid"],
             "envelope" => value["envelope"],
@@ -299,7 +260,6 @@ module Ace
             "effect_receipt_ref" => effect_receipt_ref(value),
             "effect" => value["effect_state"]
           }
-          facts["proposal"] = proposal_for_request!(request_id, project: value.fetch("project")) if value["kind"] == "proposal"
           facts
         end
 
@@ -328,7 +288,6 @@ module Ace
 
           value = load_request(request_id)
           requester_gate!(value)
-          raise StateError, "proposal authorization is consumed by the scoped Assign service claim" if value["kind"] == "proposal"
           verify_native_consumer!(value) if native_delivery
           verify_operation!(value, operation)
           deadline = timeout.positive? ? Time.now.to_i + timeout : nil
@@ -409,7 +368,6 @@ module Ace
           locked_value = nil
           with_request_lock(request_id) do
             value = load_request(request_id)
-            raise StateError, "proposal decisions use revise or authenticated Captain veto" if value["kind"] == "proposal"
             # Ownership is re-checked against the LOCKED record: an
             # unlocked check would race a concurrent recreate of the id
             # (review 8wq2zttu on PR#336).
@@ -424,11 +382,7 @@ module Ace
               remove_request(value, keep_public: true)
               locked_value = value
             end
-            if value["publication_binding"]
-              with_live_authority!(value, requester: @identity.username, &cancel)
-            else
-              cancel.call
-            end
+            cancel.call
           end
           {
             "id" => request_id,
@@ -459,7 +413,6 @@ module Ace
           end
           value = load_request(request_id)
           require_transport!("deliver", value)
-          raise StateError, "proposal reply requires authenticated ingress evidence" if value["kind"] == "proposal"
           if value["sensitive"] == true && !Kinds.secret?(value["kind"].to_s)
             raise StateError, "secret HITL answers are forbidden"
           end
@@ -525,7 +478,6 @@ module Ace
         def each_pending(project: nil, after: nil)
           return enum_for(__method__, project: project, after: after) unless block_given?
           require_transport!("pending")
-          recover_proposal_projections(project: project)
           ids = (requests_dir.glob("*.json") + public_dir.glob("*.json")).map { |path| path.basename(".json").to_s }.uniq.sort
           ids.each do |id|
             next if after && id <= after
@@ -879,9 +831,6 @@ module Ace
           unless @identity.username == value["requester"].to_s
             raise PermissionError, "only the requesting role can consume this answer"
           end
-          if value["publication_binding"]
-            @binding.verify_publication_requester!(identity: @identity, original_peer: value.fetch("publication_requester_peer"))
-          end
         end
 
         def gate_read_access!(value)
@@ -935,7 +884,7 @@ module Ace
             raise PermissionError, "only the requesting role can #{operation == "cancelled" ? "cancel" : "consume"} this request"
           end
 
-          requester_gate!(terminal) if terminal["publication_binding"] || operator_request?(terminal)
+          requester_gate!(terminal) if operator_request?(terminal)
           case terminal["state"]
           when "cancelled"
             return replayed_cancel(request_id, terminal) if operation == "cancelled"
@@ -1000,9 +949,7 @@ module Ace
             record["requester_uid"] = value.fetch("requester_uid")
             record["kind"] = "question"
           end
-          %w[publication_binding publication_requester_peer otp].each do |key|
-            record[key] = value[key] if value.key?(key)
-          end
+          record["otp"] = value["otp"] if value.key?("otp")
           record["answer"] = extra[:answer] if extra[:answer]
           record["native_delivery"] = true if extra[:native_delivery]
           record["audit"] = extra["audit"] if extra["audit"]
@@ -1027,17 +974,6 @@ module Ace
               require_transport!("operator transition", value)
             end
             yield
-          elsif value["publication_binding"]
-            unless @binding.respond_to?(:with_publication!)
-              raise BindingError, "publication HITL source binding is unavailable"
-            end
-            @binding.with_publication!(binding: value.fetch("publication_binding"), identity: @identity,
-              assignment: value.fetch("assignment"), attempt: value.fetch("attempt"), project: value.fetch("project"),
-              otp: value.fetch("otp"), original_peer: value["publication_requester_peer"],
-              requester_required: @identity.username == value.fetch("requester")) do |selection|
-              value["publication_requester_peer"] ||= JSON.parse(JSON.generate(selection.fetch("executor_process_binding")))
-              yield
-            end
           else
             @binding.with_active(
               assignment: value["assignment"], attempt: value["attempt"],

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

@@ -23,20 +23,6 @@ module Ace
           project == @project && @decision_policy.operator_question?(uid: uid, project: project)
         end
 
-        def proposal?(peer, project:)
-          transport?(peer, project: project)
-        end
-
-        def proposal_silence?(caller_uid:, requester:, project:, operation:)
-          return false unless project == @project
-          # The transport peer is authenticated separately. A local proposal
-          # retains its original kernel principal when Hermes reconciles it.
-          return @decision_policy.proposal_silence?(caller_uid: caller_uid, requester: requester,
-            project: project, operation: operation) unless caller_uid.nil?
-          requester == "urn:ace:hitl:#{@project}:hermes-client" &&
-            @decision_policy.silence_operation?(project: project, operation: operation)
-        end
-
         # A TLS authority has no Unix service uid; client endpoint
         # verification is certificate-based.
         def service_uid

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

@@ -39,21 +39,6 @@ module Ace
           super
         end
 
-        def proposal_wake(project:, after: nil)
-          require_bound_project!(project)
-          super(project: @project, after: after)
-        end
-
-        def proposal_due(project:, after: nil)
-          require_bound_project!(project)
-          super(project: @project, after: after)
-        end
-
-        def proposal_history(project:, query: "", after: nil)
-          require_bound_project!(project)
-          super(project: @project, query: query, after: after)
-        end
-
         private
 
         def require_bound_project!(project)

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

@@ -35,7 +35,7 @@ module Ace
 
         def initialize(root:, binding:, project:, credential:, ssl_context:,
           listen: "127.0.0.1", port:, group: Store::DEFAULT_GROUP, vault: nil, logger: nil,
-          idle_seconds: DEFAULT_IDLE_SECONDS, proposal_clock: -> { Time.now.utc }, decision_policy: AccessPolicy.new)
+          idle_seconds: DEFAULT_IDLE_SECONDS, decision_policy: AccessPolicy.new)
           @root = root
           @binding = binding
           @project = TlsCredentials.project_id(project)
@@ -47,7 +47,6 @@ module Ace
           @vault = vault || OtpVault::MemoryVault.new
           @logger = logger
           @idle_seconds = idle_seconds
-          @proposal_clock = proposal_clock
           @policy = TlsAccessPolicy.new(project: @project, decision_policy: decision_policy)
           @max_connections = MAX_CONNECTIONS
           @connections = 0
@@ -227,7 +226,7 @@ module Ace
               policy: @policy,
               identity: peer,
               vault: @vault,
-              proposal_clock: @proposal_clock, stopping: -> { @stopping }, group: @group
+              stopping: -> { @stopping }, group: @group
             ),
             project: @project
           )

data/lib/ace/hitl/lifecycle.rb

@@ -4,9 +4,8 @@
 # 8wq.t.34i): provider-agnostic request store behind an authenticated
 # scoped boundary (peer-credential service, bounded protocol, transport
 # policy), kinds/secrets gates with transient OTP, public projection,
-# effect layer, duty projection, and the Overseer reverse-address
-# surface. Lab coupling lives only in the provider=lab seams (binding
-# policy, store factory, grants deployment).
+# effect layer, and duty projection. Lab coupling lives only in the
+# provider=lab seams (binding policy, store factory, grants deployment).
 require_relative "lifecycle/errors"
 require_relative "lifecycle/identity"
 require_relative "lifecycle/peer"
@@ -32,4 +31,3 @@ require_relative "lifecycle/service"
 require_relative "lifecycle/tls_service"
 require_relative "lifecycle/tls_authority"
 require_relative "lifecycle/duty"
-require_relative "lifecycle/overseer"

data/lib/ace/hitl/live_client.rb

@@ -1,103 +1,39 @@
 # frozen_string_literal: true
 
-require "digest"
-require "ace/assign"
-require "ace/herdr"
+require "ace/hitl/contract"
 require_relative "providers/lab"
 
 module Ace
   module Hitl
-    # Explicit in-process client. The scoped service owns answer availability
-    # and business callbacks; Herdr owns delivery to the selected live terminal.
-    # A watcher lives only as long as its requesting agent. Delivery status is
-    # read from that original Inbox owner, never a duplicate recovery projection.
+    # Client of the authenticated lifecycle boundary. The installed
+    # attempt-bound native delivery path (Herdr inbox reconciliation and its
+    # ace-assign attempt authority) was removed with the old authority model;
+    # requester-side boundary operations remain.
     class LiveClient
-      def initialize(boundary: nil, coordinator: nil, inbox: nil, root: Dir.pwd)
+      def initialize(boundary: nil)
         @boundary = boundary
-        @coordinator = coordinator
-        @inbox = inbox
-        @root = root
       end
 
       # Pane-less waiting consumes the existing authorized request through
-      # protected IPC. It neither queues an answer nor attests native/effect
-      # completion. OTP bytes remain solely in this authenticated return value.
+      # the authenticated boundary. It neither queues an answer nor attests
+      # native/effect completion. OTP bytes remain solely in this
+      # authenticated return value.
       def wait(request:, timeout: 0, operation: nil)
         boundary.consume(request, timeout: timeout, operation: operation)
       end
 
-      def watch(request:, timeout: 0, &observer)
-        Thread.new do
-          result = deliver(request: request, timeout: timeout)
-          observer.call(result) if observer
-          result
-        end
-      end
-
-      def deliver(request:, timeout: 0)
-        facts = boundary.read(request)
-        envelope = envelope_for(facts, request)
-        raise Lifecycle::StateError, "OTP answers require protected consume; native/folder delivery is prohibited" if envelope["kind"] == "otp"
-        reverse = envelope["reverse"]
-        raise Lifecycle::BindingError, "request has no verified native reverse address" unless reverse
-        owner = coordinator.runtime_binding(attempt_id: envelope["attempt_id"], caller_pid: Process.pid)
-        unless owner.values_at("session", "pane") == reverse.values_at("session", "pane")
-          raise Lifecycle::BindingError, "request reverse differs from its exact active native owner"
-        end
-        target = inbox.target_from_owner(owner)
-        result = boundary.consume(request, timeout: timeout, native_delivery: true)
-        raise Lifecycle::StateError, "native delivery claim was not committed" unless result["native_delivery"] == true
-        consumed = envelope_for(result, request)
-        unless consumed == envelope
-          raise Lifecycle::BindingError, "request binding changed during answer consumption"
-        end
-        answer = result["answer"]
-        unless answer.is_a?(String) && !answer.empty?
-          raise Lifecycle::StateError, "ordinary answer is unavailable for native delivery"
-        end
-        delivery = envelope.merge("payload_sha256" => Digest::SHA256.hexdigest(answer))
-        if result["effect_receipt_ref"] && delivery["effect"]
-          delivery["effect"] = delivery["effect"].merge("receipt_ref" => result["effect_receipt_ref"])
-        end
-        delivery = Contract::ManagedEnvelope.load(delivery)
-        raise Lifecycle::AnswerError, "secret-bearing native answers are prohibited" if Contract::SecretGate::PATTERN.match?(answer)
-        event = event_id(envelope)
-        queued = inbox.enqueue(event: event, attempt: envelope["attempt_id"], ref: reverse, payload: answer,
-          managed_envelope: delivery, expected_target: target)
-        coordinator.bind_inbox(attempt_id: envelope["attempt_id"], event_id: event, inbox: inbox)
-        inbox.deliver(event: event)
-      ensure
-        answer&.clear unless answer&.frozen?
-      end
-
       def status(request:)
         facts = boundary.read(request)
         envelope = envelope_for(facts, request)
-        {"request_id" => request, "request_state" => facts["state"], "envelope" => envelope,
-         "delivery" => envelope["kind"] == "otp" ? {"state" => "not-applicable"} : delivery_status(envelope)}
+        {"request_id" => request, "request_state" => facts["state"], "envelope" => envelope}
       end
 
       def pending(project: nil)
-        boundary.pending(project: project).filter_map do |facts|
-          next facts unless facts["native_delivery"] == true
-          envelope = envelope_for(facts, facts["id"])
-          delivery = delivery_status(envelope)
-          next if delivery["state"] == "delivered"
-          facts.merge("delivery" => delivery)
-        end
+        boundary.pending(project: project)
       end
 
       private
 
-      def delivery_status(envelope)
-        event = event_id(envelope)
-        # This is transport history from its original owner, not proof that
-        # an agent read an answer or a cached view of the current terminal.
-        inbox.status(event: event)
-      rescue Ace::Herdr::Organisms::Inbox::MissingEventError
-        {"event_id" => event, "state" => "not-submitted"}
-      end
-
       def envelope_for(result, request)
         Contract::ManagedEnvelope.load(result.fetch("envelope"), expected: {
           request_id: request, correlation_id: request, assignment_id: result["assignment"], attempt_id: result["attempt"]
@@ -106,21 +42,9 @@ module Ace
         raise Lifecycle::BindingError, "managed request binding is invalid (#{e.message})"
       end
 
-      def event_id(envelope)
-        Contract::ManagedEnvelope.inbox_event_id(envelope)
-      end
-
       def boundary
         @boundary ||= Providers::Lab.boundary_client
       end
-
-      def coordinator
-        @coordinator ||= Ace::Assign::Organisms::AttemptCoordinator.new(repo_root: @root)
-      end
-
-      def inbox
-        @inbox ||= Ace::Herdr::Organisms::Inbox.from_config(root: @root)
-      end
     end
   end
 end

data/lib/ace/hitl/models/hitl_event.rb

@@ -7,6 +7,8 @@ module Ace
         :id,
         :status,
         :kind,
+        :type,
+        :result,
         :title,
         :tags,
         :questions,
@@ -26,6 +28,39 @@ module Ace
         def answered?
           status.to_s == "answered" || metadata["answered"] == true
         end
+
+        def report?
+          type.to_s == "report"
+        end
+
+        def question?
+          !report?
+        end
+
+        # Recipient address hash (machine + folder [+ id] or machine + panel)
+        # for consumers/adapters; nil for legacy events without keys.
+        def recipient
+          address_from_metadata("recipient")
+        end
+
+        # Reply address (original sender + exact case); questions only.
+        def reply_to
+          address_from_metadata("reply_to")
+        end
+
+        private
+
+        def address_from_metadata(prefix)
+          base = {
+            "machine" => metadata["#{prefix}_machine"],
+            "folder" => metadata["#{prefix}_folder"],
+            "panel" => metadata["#{prefix}_panel"],
+            "id" => metadata["#{prefix}_id"]
+          }
+          return nil if base["machine"].to_s.empty?
+
+          base.compact
+        end
       end
     end
   end

data/lib/ace/hitl/molecules/hitl_address_resolver.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/hitl_address"
+
+module Ace
+  module Hitl
+    module Molecules
+      # Config-backed recipient resolution and sender/reply address
+      # construction. The single place that reads address configuration;
+      # consumers pass a configured recipient name without own routing.
+      class HitlAddressResolver
+        class UnknownRecipientError < StandardError; end
+        class InvalidAddressError < StandardError; end
+
+        # @param config [Hash] merged hitl namespace config
+        def initialize(config: {})
+          @config = config || {}
+        end
+
+        # @return [Array<String>] configured recipient names
+        def recipient_names
+          recipients.keys.sort
+        end
+
+        # @return [String, nil] name applied when --to is absent
+        def default_recipient
+          value = @config.dig("hitl", "default_recipient").to_s.strip
+          value.empty? ? nil : value
+        end
+
+        # @param name [String] configured recipient name
+        # @return [Hash] validated base address (folder or panel form)
+        # @raise [UnknownRecipientError] listing configured names
+        # @raise [InvalidAddressError] when the configured address is malformed
+        def resolve(name)
+          entry = recipients[name.to_s]
+          unless entry
+            listed = recipient_names.empty? ? "(none configured)" : recipient_names.join(", ")
+            raise UnknownRecipientError, "Unknown HITL recipient '#{name}'. Configured recipients: #{listed}"
+          end
+
+          begin
+            Atoms::HitlAddress.validate!(entry)
+          rescue Atoms::HitlAddress::InvalidAddress => e
+            raise InvalidAddressError, "recipient '#{name}' has an invalid address: #{e.message}"
+          end
+        end
+
+        # Sender (reply) address: this machine + this events folder + case id.
+        #
+        # @param folder [String] configured events root (sender's folder)
+        # @param id [String] the event's own case ID
+        # @return [Hash] validated folder-form address
+        # @raise [InvalidAddressError] when hitl.machine is unset or malformed
+        def sender_address(folder:, id:)
+          machine = @config.dig("hitl", "machine").to_s.strip
+          if machine.empty?
+            raise InvalidAddressError,
+              "cannot build reply address: hitl.machine is not configured"
+          end
+
+          begin
+            Atoms::HitlAddress.validate!(machine: machine, folder: folder, id: id)
+          rescue Atoms::HitlAddress::InvalidAddress => e
+            raise InvalidAddressError, "invalid sender address: #{e.message}"
+          end
+        end
+
+        private
+
+        def recipients
+          @recipients ||= begin
+            raw = @config.dig("hitl", "recipients")
+            raw.is_a?(Hash) ? raw : {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/hitl_config_loader.rb

@@ -18,12 +18,33 @@ module Ace
             defaults_dir: ".ace-defaults",
             gem_path: gem_root
           )
-          {"hitl" => resolver.resolve_namespace("hitl").data}
+          data = resolver.resolve_namespace("hitl").data
+          {"hitl" => normalize(data)}
         rescue StandardError => e
           warn "ace-hitl: Could not load config: #{e.class} - #{e.message}" if Ace::Hitl.respond_to?(:debug?) && Ace::Hitl.debug?
           load_defaults_fallback(gem_root: gem_root)
         end
 
+        # A hitl config document is either shaped (settings under the
+        # `hitl:` key, like the shipped defaults) or flat (settings at the
+        # top level of `.ace/hitl/config.yml`). The cascade merge combines
+        # them into one document, so normalization folds the top-level
+        # keys over the shaped subtree — flat project overrides apply and
+        # are never silently dropped by the defaults supplying `hitl:`.
+        #
+        # Caveat: the folding happens after the tier merge, so mixing
+        # shapes across tiers can invert cascade precedence (a flat user
+        # document would override a shaped project document). Use the
+        # same shape at every tier.
+        def self.normalize(data)
+          return {} unless data.is_a?(Hash)
+
+          shaped = data["hitl"]
+          base = shaped.is_a?(Hash) ? shaped : {}
+          flat = data.reject { |key, _| key == "hitl" }
+          flat.empty? ? base : Ace::Support::Config::Atoms::DeepMerger.merge(base, flat)
+        end
+
         def self.root_dir(config = nil)
           config ||= load
           dir = config.dig("hitl", "root_dir") || DEFAULT_ROOT_DIR