ace-hitl 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d2bae48cdaf02e617f52c254eb78f5a8dae316be06a8787d4282041c01eacc3
-  data.tar.gz: 81410404b3ad0e07900497a9f62594aba56aaf987ed2d816d208bcab112b096c
+  metadata.gz: 8ab176a502d7a751a22e89f461245046caa44d71943897b7f27b6d5ffdd10c84
+  data.tar.gz: f789375f072b07f087462b78fd2d2fb7a9ae45e167eedbd413a11fe09e9ead0e
 SHA512:
-  metadata.gz: e5ad8fad6083826ca4f1fb6220d7bf87bd302482bbbe946cc93778bf83279d3cf728898e9f2c9bb286ebac9e98a278b5129ab3914d1ee7b354c2befd07400129
-  data.tar.gz: 1b0bae700322c0fae15a9f6ab81a7efd5faad863db9f729115909c95e66087be26b2217ad037e5e21ea3a7e7dc7bd418afa3dd1b01654f8f5fcda36007fd5b3d
+  metadata.gz: b6f1c00953d56deac3fe8e7099a1aac527681b1314aeda336c7691de04bf7ab40af33c8815ddcac76777e02151609c555cb0f4f0be2276e8a7b8ab0359b3a9ae
+  data.tar.gz: 19e978992b0041ae887a26d743555fe69b8292fd01c763c488bef96e6feecb00c3437f58909d015eeaefa21884b552b203af47f94e583b2feef4e8bc3f4e06fc

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-16
+
+### Added
+
+- Add explicit unassigned operator questions with kernel requester UID, exact installed project grants, stable retries and existing request/terminal recovery. Expose public client/CLI creation/read and an operator-only service binding that refuses managed execution, secrets and effects.
+
+### Changed
+
+- Require the ace-hitl-contract 0.3 operator-question envelope for the tagged request union.
+
+### Fixed
+
+- Require a reconciliation checkpoint to name the canonical proposal project before silence can authorize its effect.
+
 ## [0.16.0] - 2026-10-16
 
 ### Added

data/README.md

@@ -87,3 +87,51 @@ Verification commands:
 `ace-hitl` owns HITL-specific event semantics and markdown contract.
 
 `ace-support-items` remains generic support infrastructure and should not absorb HITL-specific domain behavior.
+
+## Unassigned operator questions
+
+`ace-hitl operator-question ID --project lab-config --question "Which option?"`
+creates a nonsecret question under an explicit installed operator grant. An
+optional `--plan` adds question context; `--options A,B` supplies bounded choices.
+The owner binds the exact Captain-visible body including this context and choices. It does not create an Assign execution,
+request a command, grant a decision, or permit OTP/effects. Stable IDs support
+exact retries after lost responses, restart and consumption; changed content,
+principal, project or context is refused. `ace-hitl read ID` returns authenticated
+nonsecret facts; existing `consume ID` retrieves the requester's answer and
+replays its terminal receipt.
+
+The public Ruby client exposes `operator_question(id:, project:, question:,
+plan: "", options: [])`, `read`, and the existing pending/deliver/consume/cancel
+methods. The request records the actual kernel peer UID/name. No caller can supply
+requester attribution, assignment, attempt, OTP, effect or publication fields.
+Secret-shaped questions, context, choices and answers are refused.
+
+An operator-only service uses the existing owner and Unix protocol:
+
+```sh
+ace-hitl serve --operator-only --group ace-hitl-project \
+  --socket /run/ace-hitl-project/lifecycle.sock --store-root /var/lib/ace-hitl-project \
+  --grants-path /etc/ace-hitl-project/authorization.yml
+```
+
+The root-controlled grants document must explicitly name `hitl.service_uid`,
+`hitl.operator_uids`, `hitl.transport_uids` and each UID's exact project list in
+`authorization.principals`. Operator grants never interpret an empty project list
+as all projects. Existing trusted-file ownership/traversal checks apply. The
+operator-only binding refuses managed requests and requires no Assign journal.
+Admission and requester grants are checked again on reads, answer transitions,
+retries and terminal replay; transport delivery retains its independent project
+grant. Revocation preserves request and terminal history. Operator questions
+cannot be consumed as native execution or authorized-operation claims.
+
+`ping` advertises the supported `request_contexts` (`managed` and/or
+`operator-question`), not a grant to create or execute work. Hermes project
+routes may require `request_contexts: ["operator-question"]` at startup. The
+shared contract uses a closed tagged union of managed execution requests and
+operator questions; neither missing IDs nor an unknown schema select a fallback.
+
+One Unix UID with both roles is one OS trust domain. Use a distinct transport
+principal where Captain reply isolation is required. Source tests using one UID
+for both roles do not prove that isolation. Domain adapters must separately
+preserve legacy unresolved host questions and prove the installed group handoff;
+this API never migrates or deletes that legacy history.

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require "ace/support/cli"
+require_relative "lifecycle_command"
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class OperatorQuestion < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+          desc "Create a nonsecret operator question without an execution or effect grant"
+          argument :id, required: true, desc: "Stable question ID; reuse for an exact retry"
+          option :project, type: :string, required: true, desc: "Exact installed operator project scope"
+          option :question, type: :string, required: true, desc: "Nonsecret question"
+          option :plan, type: :string, desc: "Nonsecret question context"
+          option :options, type: :array, desc: "Nonsecret choices (comma-separated)"
+          def call(id:, **options)
+            emit(lifecycle_client.operator_question(id: id, project: options.fetch(:project),
+              question: options.fetch(:question), plan: options.fetch(:plan, ""), options: options.fetch(:options, [])))
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require "ace/support/cli"
+require_relative "lifecycle_command"
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Read < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+          desc "Read authenticated nonsecret lifecycle facts for one request"
+          argument :id, required: true, desc: "Request ID"
+          def call(id:, **)
+            emit(lifecycle_client.read(id))
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -23,6 +23,8 @@ module Ace
             desc: "Dedicated lifecycle group allowed to connect (required; root and lab-control are refused)"
           option :store_root, type: :string, desc: "Private store root (default: ACE_HITL_STORE_ROOT or /run/lab/hitl)"
           option :grants_path, type: :string, desc: "Trusted grants document (default: ACE_HITL_GRANTS_PATH or /etc/lab/ace-lab/authorization.yml)"
+          option :operator_only, type: :boolean,
+            desc: "Serve explicitly granted nonsecret operator questions without a managed execution authority"
           option :repo_root, type: :string, desc: "Candidate repository for the managed attempt authority"
           option :tls_authority, type: :string, desc: "Serve the host/Incus mTLS crossing from this authority config (root:<service-group> 0640; loopback TCP + verified project client identity)"
 
@@ -30,6 +32,9 @@ module Ace
           option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
 
           def call(**options)
+            if options[:tls_authority] && options[:operator_only]
+              raise_cli_error("operator questions require a local kernel requester; operator-only TLS is not supported")
+            end
             return serve_tls_authority(options) if options[:tls_authority]
 
             group = dedicated_group(options)
@@ -41,7 +46,12 @@ module Ace
                 "fail every client endpoint verification"
               )
             end
-            binding_policy = Providers::Lab.assignment_binding(repo_root: options[:repo_root])
+            binding_policy = if options[:operator_only]
+              raise_cli_error("operator-only serve cannot select a managed repository") if options[:repo_root]
+              Lifecycle::OperatorOnlyBinding.new
+            else
+              Providers::Lab.assignment_binding(repo_root: options[:repo_root])
+            end
             service = Lifecycle::Service.new(
               root: store_root(options),
               binding: binding_policy,

data/lib/ace/hitl/cli.rb

@@ -4,6 +4,8 @@ require "ace/support/cli"
 require_relative "../hitl/version"
 require_relative "cli/commands/create"
 require_relative "cli/commands/ask"
+require_relative "cli/commands/operator_question"
+require_relative "cli/commands/read"
 require_relative "cli/commands/show"
 require_relative "cli/commands/list"
 require_relative "cli/commands/update"
@@ -30,6 +32,8 @@ module Ace
       REGISTERED_COMMANDS = [
         ["proposal", "Create, inspect, revise or resolve an immutable second-commander proposal"],
         ["create", "Create HITL event"],
+        ["operator-question", "Create a nonsecret question under an installed operator project grant"],
+        ["read", "Read authenticated lifecycle request facts"],
         ["ask", "Ask a human via HITL and forward the request to the Lab"],
         ["show", "Show HITL event details"],
         ["list", "List HITL events"],
@@ -58,6 +62,8 @@ module Ace
       register "create", CLI::Commands::Create
       register "proposal", CLI::Commands::Proposal
       register "ask", CLI::Commands::Ask
+      register "operator-question", CLI::Commands::OperatorQuestion
+      register "read", CLI::Commands::Read
       register "show", CLI::Commands::Show
       register "list", CLI::Commands::List
       register "update", CLI::Commands::Update

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

@@ -31,6 +31,19 @@ module Ace
           raise NotImplementedError
         end
       end
+      # Explicit operator-only authority. Managed requests remain fail closed
+      # without creating or consulting a pretend Assign execution.
+      class OperatorOnlyBinding < Binding
+        def validate_request(**)
+          raise BindingError, "operator-only authority does not admit managed requests"
+        end
+        def reverse_address(**)
+          raise BindingError, "operator questions have no native execution address"
+        end
+        def with_active(**)
+          raise BindingError, "operator-only authority does not admit managed requests"
+        end
+      end
     end
   end
 end

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

@@ -42,7 +42,7 @@ module Ace
 
         def execute(store, op, params)
           case op
-          when "ping" then {"pong" => true}
+          when "ping" then store.capabilities
           when "proposal-create" then store.proposal_create(**symbolize(params))
           when "proposal-show" then store.proposal_show(required(params, "id"), project: required(params, "project"), history_after: params.fetch("history_after", 0))
           when "proposal-revise" then store.proposal_revise(required(params, "id"), project: required(params, "project"), expected_revision: required(params, "expected_revision"),
@@ -58,6 +58,7 @@ module Ace
           when "proposal-due" then store.proposal_due(project: required(params, "project"), after: params["after"])
           when "proposal-history" then store.proposal_history(project: required(params, "project"),
             query: params.fetch("query", ""), after: params["after"])
+          when "operator-question" then store.operator_question(**symbolize(params))
           when "create" then store.create(**symbolize(params))
           when "read" then store.read(required(params, "id"))
           when "deliver" then store.deliver(required(params, "id"), answer_reader(params))

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

@@ -9,6 +9,10 @@ module Ace
       # lifecycle frames are exchanged unchanged on both transports.
       # The includer implements `#request(op, params, deadline:)`.
       module LifecycleRequests
+        def operator_question(**params)
+          request("operator-question", params.transform_keys(&:to_s))
+        end
+
         def proposal_create(**params)
           request("proposal-create", params)
         end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+require "ace/hitl/contract/request_envelope"
+
+module Ace
+  module Hitl
+    module Lifecycle
+      module OperatorQuestions
+        def operator_question(id:, project:, question:, plan: "", options: [])
+          unless @identity.uid.is_a?(Integer) && @policy.operator_question?(uid: @identity.uid, project: project)
+            raise PermissionError, "operator question requires an installed UID and exact project grant"
+          end
+          unless project.is_a?(String) && Contract::ManagedEnvelope::TOKEN.match?(project) &&
+              question.is_a?(String) && question.valid_encoding? && !question.strip.empty? &&
+              question.length <= Store::MAX_PLAN_QUESTION && !question.include?("\0") &&
+              plan.is_a?(String) && plan.valid_encoding? && plan.length <= Store::MAX_PLAN_QUESTION &&
+              !plan.include?("\0") && options.is_a?(Array) && options.length <= Store::MAX_OPTIONS &&
+              options.all? { |item| item.is_a?(String) && item.valid_encoding? && !item.strip.empty? &&
+                item.length <= Store::MAX_OPTION && !item.include?("\0") }
+            raise StateError, "invalid nonsecret operator question content"
+          end
+          [question, plan, *options].each { |text| Kinds.check_answer!("question", text) }
+          question, plan = question.strip, plan.strip
+          options = options.map(&:strip)
+          input_digest = Digest::SHA256.hexdigest(JSON.generate([plan, question, options]))
+          # The authority binds the actual Captain-visible question, including
+          # its optional context/choices. Hermes publishes these exact bytes.
+          question += "\n\nContext: #{plan}" unless plan.empty?
+          unless options.empty?
+            question += "\n\nOptions:\n" + options.each_with_index.map { |item, index| "#{index + 1}. #{item}" }.join("\n")
+          end
+          request_id = safe_id(id)
+          incarnation = SecureRandom.hex(8)
+          envelope = Contract::OperatorEnvelope.load({
+            "schema" => Contract::OperatorEnvelope::SCHEMA, "context" => "operator-question",
+            "request_id" => request_id, "request_incarnation" => incarnation, "project" => project,
+            "requester" => @identity.username, "requester_uid" => @identity.uid,
+            "correlation_id" => request_id, "kind" => "question",
+            "payload_sha256" => Digest::SHA256.hexdigest(question),
+            "input_sha256" => input_digest})
+          value = {"id" => request_id, "project" => project, "requester" => @identity.username,
+            "requester_uid" => @identity.uid, "harness" => "operator", "kind" => "question", "sensitive" => false,
+            "plan" => plan, "question" => question, "options" => options, "created_at" => Time.now.to_i,
+            "incarnation" => incarnation, "envelope" => envelope}
+          with_request_lock(request_id) do
+            operator_authority!(value)
+            terminal = load_terminal(request_id)
+            previous = terminal
+            previous ||= load_request(request_id) if request_path(request_id).exist?
+            if previous
+              requester_gate!(previous)
+              old = Contract::RequestEnvelope.from_facts(previous)
+              unless old["schema"] == Contract::OperatorEnvelope::SCHEMA &&
+                  old.except("request_incarnation") == envelope.except("request_incarnation")
+                raise StateError, "operator question retry changed immutable content or context"
+              end
+              initialize_projection_locked!(previous) unless terminal
+              return {"id" => request_id, "requested" => true, "replay" => true, "envelope" => old}
+            end
+            persist_request_locked!(value)
+          end
+        rescue Contract::InvalidEnvelope => e
+          raise StateError, e.message
+        end
+
+        private
+
+        def operator_request?(value)
+          value.dig("envelope", "schema") == Contract::OperatorEnvelope::SCHEMA
+        end
+
+        def operator_authority!(value)
+          envelope = Contract::RequestEnvelope.from_facts(value)
+          unless envelope["schema"] == Contract::OperatorEnvelope::SCHEMA &&
+              @policy.operator_question?(uid: envelope.fetch("requester_uid"), project: envelope.fetch("project"))
+            raise PermissionError, "operator requester project grant is unavailable or revoked"
+          end
+          envelope
+        rescue Contract::InvalidEnvelope => e
+          raise StateError, e.message
+        end
+      end
+    end
+  end
+end

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

@@ -102,6 +102,10 @@ module Ace
       # the contract. The default denies everything — direct-library use
       # gets requester-only semantics and no transport authority.
       class AccessPolicy
+        def operator_question?(uid:, project:)
+          false
+        end
+
         def proposal?(_peer, project:)
           false
         end
@@ -137,6 +141,17 @@ module Ace
           @document = document
         end
 
+        # Operator questions have exact installed project scope, never the
+        # historical empty-list transport wildcard. UID is taken from the kernel
+        # peer on creation and retained in the protected request on transitions.
+        def operator_question?(uid:, project:)
+          current = document
+          uids = hitl_facts(current)["operator_uids"]
+          projects = authorized_projects(uid, current)
+          uid.is_a?(Integer) && uids.is_a?(Array) && uids.include?(uid) &&
+            projects.is_a?(Array) && projects.include?(project)
+        end
+
         def transport?(peer, project: nil)
           current = document
           facts = hitl_facts(current)

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

@@ -14,7 +14,7 @@ module Ace
         VERSION = 1
         MAX_FRAME_BYTES = 64 * 1024
         DEFAULT_DEADLINE_SECONDS = 10.0
-        OPERATIONS = %w[create read deliver consume cancel pending states ping
+        OPERATIONS = %w[operator-question create read deliver consume cancel pending states ping
           proposal-create proposal-show proposal-revise proposal-ack proposal-reply proposal-reconcile proposal-due proposal-history proposal-wake].freeze
 
         # Wire failures map to the transport error; classified lifecycle

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

@@ -11,6 +11,7 @@ require_relative "policy"
 require_relative "atomic_json"
 require_relative "kinds"
 require_relative "binding"
+require_relative "operator_questions"
 require_relative "effects"
 require_relative "otp_vault"
 require_relative "protocol"
@@ -37,6 +38,7 @@ module Ace
       #   with_active scope (the assignment exclusion), so stale, ended
       #   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
@@ -97,6 +99,12 @@ module Ace
           @group = group
         end
 
+        def capabilities
+          contexts = ["operator-question"]
+          contexts.unshift("managed") unless @binding.is_a?(OperatorOnlyBinding)
+          {"pong" => true, "request_contexts" => contexts}
+        end
+
         # ---- requester side ------------------------------------------------
 
         # Create one request bound to the exact live attempt of the
@@ -221,7 +229,11 @@ module Ace
 
         def persist_request_locked!(value)
           request_id = value.fetch("id")
-          attempt = value.fetch("attempt")
+          attempt = value["attempt"]
+          terminal = load_terminal(request_id)
+          if terminal && operator_request?(terminal)
+            raise StateError, "operator question identity is terminal and cannot acquire another context"
+          end
           request_path = requests_dir.join("#{request_id}.json")
           raise StateError, "HITL request already exists" if request_path.exist?
 
@@ -251,11 +263,16 @@ module Ace
         # transport). Never carries answer content.
         def read(id)
           request_id = safe_id(id)
+          terminal = load_terminal(request_id)
+          if terminal && operator_request?(terminal)
+            gate_read_access!(terminal)
+            return terminal.slice("id", "project", "requester", "requester_uid", "sensitive", "envelope", "state", "kind")
+          end
           unless request_path(request_id).exist?
             terminal = load_terminal(request_id)
             if terminal
               gate_read_access!(terminal)
-              return terminal.slice("id", "assignment", "attempt", "project", "requester", "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", "publication_binding", "publication_requester_peer", "otp")
                 .merge("kind" => terminal.dig("envelope", "kind"))
             end
           end
@@ -276,6 +293,7 @@ module Ace
             "publication_binding" => value["publication_binding"],
             "publication_requester_peer" => value["publication_requester_peer"],
             "requester" => value["requester"],
+            "requester_uid" => value["requester_uid"],
             "envelope" => value["envelope"],
             "state" => public_state(request_id, value),
             "effect_receipt_ref" => effect_receipt_ref(value),
@@ -298,6 +316,8 @@ module Ace
           request_id = safe_id(id)
           replay = replay_terminal!(request_id, "consumed")
           if replay
+            terminal = load_terminal(request_id)
+            verify_operation!(terminal, operation) if operator_request?(terminal)
             if native_delivery
               terminal = load_terminal(request_id)
               raise StateError, "request was consumed locally; it has no native delivery claim" unless terminal["native_delivery"]
@@ -463,7 +483,7 @@ module Ace
               verify_otp_deadline!(value)
               write_answer(value, answer)
               update_public(value, "answer-delivered")
-              unless value["sensitive"] == true
+              unless value["sensitive"] == true || operator_request?(value)
                 requester_uid, requester_gid = @identity.user_ids(value["requester"])
                 Effects.run(self, value, answer,
                   requester_uid: requester_uid, requester_gid: requester_gid, identity: @identity)
@@ -509,6 +529,8 @@ module Ace
           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
+            terminal = load_terminal(id)
+            next if terminal && operator_request?(terminal)
             value = AtomicJson.read(requests_dir.join("#{id}.json"))
             active = value.is_a?(Hash)
             value = AtomicJson.read(public_dir.join("#{id}.json")) unless active
@@ -521,7 +543,7 @@ module Ace
             end
             if active
               value = value.slice("id", "assignment", "attempt", "project", "harness", "kind", "sensitive", "plan", "question",
-                "options", "ace_hitl_id", "requester", "created_at", "otp", "envelope")
+                "options", "ace_hitl_id", "requester", "requester_uid", "created_at", "otp", "envelope")
                 .merge("state" => public_state(value["id"], value), "has_effect" => !value["effect"].nil?)
             end
             yield value
@@ -533,7 +555,16 @@ module Ace
         def states
           require_transport!("states")
           public_dir.glob("*.json").sort.filter_map do |path|
-            AtomicJson.read(path)
+            value = AtomicJson.read(path)
+            next unless value.is_a?(Hash)
+            if operator_request?(value)
+              begin
+                require_transport!("states", value)
+              rescue PermissionError
+                next
+              end
+            end
+            value
           end
         end
 
@@ -619,6 +650,13 @@ module Ace
             "envelope" => value["envelope"],
             "updated_at" => Time.now.to_i
           }
+          if operator_request?(value)
+            public.delete("assignment")
+            public.delete("attempt")
+            public["requester"] = value.fetch("requester")
+            public["requester_uid"] = value.fetch("requester_uid")
+            public["sensitive"] = false
+          end
           public["incarnation"] = value["incarnation"] if value["incarnation"]
           public["native_delivery"] = true if value["native_delivery"]
           public["otp"] = public_otp_projection(value["otp"]) if value["otp"]
@@ -771,6 +809,7 @@ module Ace
         end
 
         def verify_native_consumer!(value)
+          raise StateError, "operator question has no native execution claim" if operator_request?(value)
           raise StateError, "OTP requires protected local consume" if value["sensitive"] == true
           reverse = @binding.reverse_address(assignment: value["assignment"], project: value["project"], attempt: value["attempt"],
             caller_pid: @identity.respond_to?(:pid) ? @identity.pid : nil)
@@ -831,6 +870,12 @@ module Ace
         # ---- role gates ------------------------------------------------------
 
         def requester_gate!(value)
+          if operator_request?(value)
+            operator_authority!(value)
+            unless @identity.uid == value.fetch("requester_uid")
+              raise PermissionError, "only the kernel requester UID can consume this question"
+            end
+          end
           unless @identity.username == value["requester"].to_s
             raise PermissionError, "only the requesting role can consume this answer"
           end
@@ -849,6 +894,7 @@ module Ace
         end
 
         def require_transport!(operation, value = nil)
+          operator_authority!(value) if value && operator_request?(value)
           return true if @policy.transport?(@identity, project: value && value["project"])
 
           raise PermissionError, "#{operation} requires the configured transport identity"
@@ -858,6 +904,9 @@ module Ace
         # challenge's authorized operation; anything else fails closed
         # without touching the secret.
         def verify_operation!(value, operation)
+          if operator_request?(value) && operation
+            raise StateError, "operator question has no authorized execution operation"
+          end
           return unless value["otp"]
 
           presented = operation.to_s
@@ -886,7 +935,7 @@ module Ace
             raise PermissionError, "only the requesting role can #{operation == "cancelled" ? "cancel" : "consume"} this request"
           end
 
-          requester_gate!(terminal) if terminal["publication_binding"]
+          requester_gate!(terminal) if terminal["publication_binding"] || operator_request?(terminal)
           case terminal["state"]
           when "cancelled"
             return replayed_cancel(request_id, terminal) if operation == "cancelled"
@@ -947,6 +996,10 @@ module Ace
             "effect_receipt_ref" => effect_receipt_ref(value),
             "at" => Time.now.to_i
           }
+          if operator_request?(value)
+            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
@@ -968,7 +1021,13 @@ module Ace
         # the request stays pending and the classified error propagates
         # for retry (review 8x32r9b0).
         def with_live_authority!(value, requester:)
-          if value["publication_binding"]
+          if operator_request?(value)
+            operator_authority!(value)
+            if @identity.uid != value.fetch("requester_uid")
+              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

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

@@ -19,6 +19,10 @@ module Ace
           bound?(peer) && (project.nil? || project.to_s == @project)
         end
 
+        def operator_question?(uid:, project:)
+          project == @project && @decision_policy.operator_question?(uid: uid, project: project)
+        end
+
         def proposal?(peer, project:)
           transport?(peer, project: project)
         end

data/lib/ace/hitl/proposals/policy.rb

@@ -111,6 +111,7 @@ module Ace
           return record unless record["silence_delegated"] == true
           return record if timestamp(now) < timestamp(record.fetch("deadline"))
           valid = checkpoint["schema"] == "ace.hitl.hermes.ingress-checkpoint/v1" &&
+            checkpoint["project"].is_a?(String) && checkpoint["project"] == record["project_id"] &&
             checkpoint["request"] == record["request_id"] && checkpoint["revision"] == record["revision_id"] &&
             checkpoint["healthy"] == true && checkpoint["drained"] == true &&
             checkpoint.dig("checkpoint", "through") == record["deadline"] &&

data/lib/ace/hitl/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Michal Czyz
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: ace-support-core
   requirement: !ruby/object:Gem::Requirement
@@ -184,11 +184,13 @@ files:
 - lib/ace/hitl/cli/commands/duty.rb
 - 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/serve.rb
 - lib/ace/hitl/cli/commands/show.rb
 - lib/ace/hitl/cli/commands/states.rb
@@ -207,6 +209,7 @@ files:
 - lib/ace/hitl/lifecycle/identity.rb
 - lib/ace/hitl/lifecycle/kinds.rb
 - 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