ace-hitl 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0827bd8ade04c613021128ac335a1d0fea74d5954e718122bd243a780bebb675'
-  data.tar.gz: df48a9612ca6a87670142ee8f511a837e206af2294a1a609be8045bfc14c1830
+  metadata.gz: 8ab176a502d7a751a22e89f461245046caa44d71943897b7f27b6d5ffdd10c84
+  data.tar.gz: f789375f072b07f087462b78fd2d2fb7a9ae45e167eedbd413a11fe09e9ead0e
 SHA512:
-  metadata.gz: b0f0b827b307e8baf05a25c9503455fde43c8734e121f7d3f5f222a4d0a0aa201653bb346366fd6b8445c700031113068ff133cf24e4566b825e4bf59633f622
-  data.tar.gz: 462e2cef1a68a7a4a3975b96b324977223101a53ba384940875197e61c103054d3e52cbb83d4337f98aea0f5c92dfd306d0c372caa61e2bd8ab20517aca73cf3
+  metadata.gz: b6f1c00953d56deac3fe8e7099a1aac527681b1314aeda336c7691de04bf7ab40af33c8815ddcac76777e02151609c555cb0f4f0be2276e8a7b8ab0359b3a9ae
+  data.tar.gz: 19e978992b0041ae887a26d743555fe69b8292fd01c763c488bef96e6feecb00c3437f58909d015eeaefa21884b552b203af47f94e583b2feef4e8bc3f4e06fc

data/CHANGELOG.md

@@ -7,6 +7,30 @@ 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
+
+- Require explicit predelegation for sixteen-hour proposal decisions and bind ordinary project proposals to the selected canonical owner. Refresh project and owner grants at transitions and replay; compose existing Unix/TLS listeners under the authority lifetime.
+
+### Fixed
+
+- Read TLS authority configuration through bounded protected descriptors, rejecting symlinks, unsafe ancestors, special files and concurrent replacement before startup. Declare the direct Runtime dependency used by this reader.
+
 ## [0.15.0] - 2026-10-14
 
 ### 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/docs/usage.md

@@ -358,8 +358,11 @@ The JSON proposal requires operation, target (`resource` and optional `artifact_
 candidate_head, input_digest, context, options, recommendation and prerequisites; rationale
 is optional. Contents are bounded and non-secret. Input digest uses the canonical service
 input digest. Candidate head is separate from base head and the evidence journal commit.
-Every precisely presented operation is eligible for sixteen-hour silence, including
-publishing, deployment and access/privilege expansion. Fixed service scope, current head,
+Only operation classes explicitly delegated in trusted project policy are eligible
+for sixteen-hour silence. Delegation must exist when the revision is created and
+remain current at the deadline; a later grant cannot approve an older revision.
+Without delegation the proposal still accepts an explicit correlated decision.
+Fixed service scope, current head,
 independently executed review/tests, bound running attempt and operation-specific OTP gates
 still apply at execution. Proposal authorization never supplies credentials or runs a callback.
 
@@ -423,6 +426,8 @@ hitl:
   service_uid: 1200
   transport_uids: [1201]
   proposal_uids: [1202]
+  silence_operations:
+    ace: [merge]
 authorization:
   principals:
     "1201":
@@ -438,6 +443,11 @@ resolve silence. Missing role or project admission refuses the operation,
 including direct library calls. This is a source configuration contract;
 installed deployment adoption remains part of gad.8 acceptance.
 
+`silence_operations` is an exact project-to-operation list, with no wildcards or
+implicit publish/deploy/access grants. It never expands command or credential
+authority. TLS authorities read the same trusted grants document selected by
+`--grants-path`; certificate authentication alone grants no silence decision.
+
 ### Controlled installed proposal verification
 
 From an ACE checkout with Ruby, tmux and the complete dependency archives cached locally:

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,
@@ -69,6 +79,7 @@ module Ace
               binding: binding_policy,
               project: authority.project_id,
               credential: authority.credential,
+              decision_policy: Providers::Lab.grants_policy(grants_path: grants_path(options)),
               ssl_context: authority.ssl_context!,
               listen: authority.listen,
               port: authority.port,

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,9 +102,21 @@ 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
+
+        def proposal_silence?(caller_uid:, requester:, project:, operation:)
+          false
+        end
+
+        def silence_operation?(project:, operation:)
+          false
+        end
         # @return [Boolean] true when the peer may deliver answers and
         #   observe pending/states for the given project
         def transport?(_peer, project: nil)
@@ -129,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)
@@ -151,13 +174,36 @@ module Ace
         # an ordinary requester or transport grant.
         def proposal?(peer, project:)
           current = document
+          proposal_principal?(peer.uid, project, current)
+        end
+
+        # A proposer grant allows asking. Only this separate, exact project
+        # operation list delegates a decision after the acknowledged window.
+        def proposal_silence?(caller_uid:, requester:, project:, operation:)
+          current = document
+          proposal_principal?(caller_uid, project, current) &&
+            delegated_operation?(project, operation, current)
+        end
+
+        def silence_operation?(project:, operation:)
+          delegated_operation?(project, operation, document)
+        end
+
+        private
+
+        def proposal_principal?(uid, project, current)
           uids = hitl_facts(current)["proposal_uids"]
-          projects = authorized_projects(peer.uid, current)
-          uids.is_a?(Array) && uids.include?(peer.uid) && projects &&
+          projects = authorized_projects(uid, current)
+          uid.is_a?(Integer) && uids.is_a?(Array) && uids.include?(uid) && projects &&
             (projects.empty? || projects.include?(project.to_s))
         end
 
-        private
+        def delegated_operation?(project, operation, current)
+          delegations = hitl_facts(current)["silence_operations"]
+          operations = delegations.is_a?(Hash) && delegations[project]
+          operations.is_a?(Array) && operation.is_a?(String) &&
+            operation.match?(/\A[a-z][a-z0-9-]{0,63}\z/) && operations.include?(operation)
+        end
 
         def document
           @document || TrustedFile.read_yaml(@grants_path) || {}

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

@@ -54,6 +54,7 @@ module Ace
           claims = proposal_journal(project).proposal_claims(record["revision_id"])
           claim = claims.last
           outcome = case claim && claim["state"]
+          when "pending" then "queued"
           when "accepted" then "executing"
           when "succeeded" then "succeeded"
           when "failed", "failed-settled", "rejected" then "failed"
@@ -88,6 +89,7 @@ module Ace
           record = proposal_for_request!(request, project: project)
           require_transport!("proposal reconciliation", {"project" => record["project_id"]})
           proposal_transition(record) do |current|
+            next current unless silence_delegated?(current)
             Ace::Hitl::Proposals::Policy.resolve(current, checkpoint: checkpoint, now: proposal_now)
           end
         end
@@ -136,6 +138,11 @@ module Ace
 
         private
 
+        def silence_delegated?(record)
+          @policy.proposal_silence?(caller_uid: record["caller_uid"], requester: record["requester"],
+            project: record["project_id"], operation: record["operation"])
+        end
+
         def require_proposer!(project)
           unless @policy.respond_to?(:proposal?) && @policy.proposal?(@identity, project: project)
             raise PermissionError, "proposal requires the installed second-commander decision principal"
@@ -189,6 +196,8 @@ module Ace
         def proposal_transition(record, &policy)
           proposal_journal(record.fetch("project_id")).change_proposal(record["proposal_id"], assignment_id: record["assignment_id"],
             attempt_id: record["attempt_id"]) do |current|
+            # Selection may change while waiting for the canonical ref lock.
+            proposal_journal(record.fetch("project_id"))
             # A reply to an older revision cannot modify the new decision.
             next current unless current["request_id"] == record["request_id"]
             policy.call(current)
@@ -203,6 +212,7 @@ module Ace
           replay = nil
           record = @binding.with_active(assignment: assignment, attempt: attempt, project: project, requester: @identity.username) do
             proposal_journal(project).change_proposal(id, assignment_id: assignment, attempt_id: attempt) do |previous|
+              proposal_journal(project)
               if operation_id
                 replay = proposal_revision_replay(id, expected_revision, operation_id, content, project: project)
                 next previous if replay
@@ -228,6 +238,8 @@ module Ace
                 "attempt_id" => attempt, "project_id" => project, "requester" => @identity.username,
                 "caller_uid" => @identity.uid, "content_digest" => Digest::SHA256.hexdigest(JSON.generate(content)),
                 "state" => "awaiting-delivery", "created_at" => proposal_now,
+                "silence_delegated" => @policy.proposal_silence?(caller_uid: @identity.uid,
+                  requester: @identity.username, project: project, operation: content.fetch("operation")),
                 "authorization" => request, "lifecycle_request" => projection).tap do |value|
                   if operation_id
                     value["revision_operation_id"] = operation_id

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/service.rb

@@ -186,10 +186,12 @@ module Ace
         # the service identity or root — otherwise anyone who can replace
         # the socket can impersonate the service.
         def verify_control_group!
-          group = Etc.getgrnam(@group)
-          if group.gid.zero? || BROAD_CONTROL_GROUPS.include?(group.name)
+          # Named broad groups are forbidden even on a host where that
+          # deployment group has not been created yet.
+          group = Etc.getgrnam(@group) unless BROAD_CONTROL_GROUPS.include?(@group)
+          if group.nil? || group.gid.zero? || BROAD_CONTROL_GROUPS.include?(group.name)
             raise TransportError,
-              "HITL boundary control group is too broad: #{group.name} " \
+              "HITL boundary control group is too broad: #{@group} " \
               "(configure a dedicated lifecycle group; root and #{Store::DEFAULT_GROUP} are refused)"
           end
 

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

@@ -10,18 +10,33 @@ module Ace
       # even when issued by the same CA, and no operation against any
       # other project is reachable through this authority.
       class TlsAccessPolicy < AccessPolicy
-        def initialize(project:)
+        def initialize(project:, decision_policy: AccessPolicy.new)
           @project = project.to_s
+          @decision_policy = decision_policy
         end
 
         def transport?(peer, project: nil)
           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
 
+        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_authority.rb

@@ -2,6 +2,7 @@
 
 require "ipaddr"
 require "json"
+require "ace/runtime/molecules/protected_artifact_set"
 require_relative "tls_credentials"
 require_relative "credential_path_policy"
 require_relative "tls_material"
@@ -22,16 +23,24 @@ module Ace
         SCHEMA = "ace.hitl.tls.authority/v1"
         FIELDS = %w[schema project_id listen port service_user service_group
           tls_server_credential].freeze
+        MAX_BYTES = 65_536
 
         attr_reader :project_id, :listen, :port, :service_user, :service_group,
           :credential, :path
 
         def self.load(path)
-          config = JSON.parse(File.read(path))
-          authority = new(config, path: path)
-          CredentialPathPolicy.verify_runtime_file!(path, authority.service_group)
-          authority
-        rescue JSON::ParserError, SystemCallError, IOError
+          reader = Ace::Runtime::Molecules::ProtectedArtifactSet.new(file_limit: MAX_BYTES, total_limit: MAX_BYTES)
+          reader.with do |held|
+            bytes, = held.read_path!(path)
+            config = JSON.parse(bytes, create_additions: false, allow_duplicate_key: false, max_nesting: 16)
+            authority = new(config, path: path)
+            CredentialPathPolicy.verify_runtime_file!(path, service_group: authority.service_group)
+            # Exact mode/group validation and parsing must refer to the same
+            # bounded protected inode, including every retained ancestor.
+            held.verify_unchanged!
+            authority
+          end
+        rescue JSON::ParserError, SystemCallError, IOError, Ace::Runtime::Error
           raise TransportError, "the HITL TLS authority configuration is unavailable or malformed: #{path}"
         end
 

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 })
+          idle_seconds: DEFAULT_IDLE_SECONDS, proposal_clock: -> { Time.now.utc }, decision_policy: AccessPolicy.new)
           @root = root
           @binding = binding
           @project = TlsCredentials.project_id(project)
@@ -48,6 +48,7 @@ module Ace
           @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
           @handler_threads = []
@@ -223,7 +224,7 @@ module Ace
             Store.new(
               root: @root,
               binding: @binding,
-              policy: TlsAccessPolicy.new(project: @project),
+              policy: @policy,
               identity: peer,
               vault: @vault,
               proposal_clock: @proposal_clock, stopping: -> { @stopping }, group: @group
@@ -233,7 +234,7 @@ module Ace
         end
 
         def root_store
-          Store.new(root: @root, binding: @binding, policy: TlsAccessPolicy.new(project: @project), group: @group)
+          Store.new(root: @root, binding: @binding, policy: @policy, group: @group)
         end
       end
     end

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

@@ -108,8 +108,10 @@ module Ace
 
         def resolve(record, checkpoint:, now:)
           return record unless record["state"] == "awaiting-decision"
+          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/providers/lab/assignment_binding.rb

@@ -16,9 +16,14 @@ module Ace
         # authority. Every doubt maps to the classified BindingError —
         # unknown identity/authority is an error, never permission.
         class AssignmentBinding < Lifecycle::Binding
-          def initialize(coordinator: nil, repo_root: nil)
+          def initialize(coordinator: nil, repo_root: nil, project: nil, owner_guard: nil)
+            unless (project.nil? && owner_guard.nil?) ||
+                (project.is_a?(String) && !project.empty? && owner_guard.respond_to?(:call))
+              raise ArgumentError, "installed binding needs both a fixed project and its owner guard"
+            end
             @coordinator = coordinator
             @repo_root = repo_root
+            @project, @owner_guard = project, owner_guard
           end
 
           def validate_request(assignment:, attempt:, project:, requester:, caller_pid: nil)
@@ -30,6 +35,7 @@ module Ace
           # Read-only owner verification can run inside an already-held
           # assignment exclusion without reacquiring that exclusion.
           def reverse_address(assignment:, attempt:, project:, caller_pid:)
+            verify_selection!(project)
             unless caller_pid.is_a?(Integer) && caller_pid.positive?
               raise Lifecycle::BindingError, "kernel requester process identity is unavailable"
             end
@@ -49,15 +55,26 @@ module Ace
             unless project.is_a?(String) && !project.empty?
               raise Lifecycle::BindingError, "proposal requires an explicit project"
             end
+            verify_selection!(project)
             coordinator.send(:journal_for)
           end
 
           def proposal_projects
+            if @project
+              verify_selection!(@project)
+              return [@project]
+            end
             coordinator.send(:journal_for).proposals.map { |record| record.fetch("project_id") }.uniq.sort
           end
 
           private
 
+          def verify_selection!(project)
+            return unless @project
+            raise Lifecycle::BindingError, "project differs from installed HITL owner" unless project == @project
+            @owner_guard.call
+          end
+
           def with_verified(assignment_id, attempt_id, project_id, requester)
             # ONLY the authority verification is error-mapped: the
             # caller's transition (answer hand-off, commits, effects)
@@ -66,12 +83,14 @@ module Ace
             # failure (review 8x327bud). The exclusion still spans the
             # whole transition, so the phase flag separates the two.
             verifying = true
+            verify_selection!(project_id)
             coordinator.with_verified_attempt(
               assignment_id: assignment_id,
               attempt_id: attempt_id,
               project_id: project_id,
               requester: requester
             ) do |attempt|
+              verify_selection!(project_id)
               verifying = false
               yield attempt
             end

data/lib/ace/hitl/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-hitl-contract
@@ -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
@@ -113,28 +113,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.67'
+        version: '0.70'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.67'
+        version: '0.70'
 - !ruby/object:Gem::Dependency
   name: ace-herdr
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: ace-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 description: Provides the dedicated ace-hitl package surface for human in the loop
   (HITL) semantics and CLI workflows.
 email:
@@ -170,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
@@ -193,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