ace-hitl 0.8.9 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3661968abbe2abf17fc1cf79fbe2a4d710805c134825dfa525661b64d27bd6d
-  data.tar.gz: 0c1b3ba003b4ce8020458d8f23909bbed8d2331a81cda9f83f33c23bcb6aaa28
+  metadata.gz: 6c36ea0129ebd4da1a3b54f5f6cb2f1701e38a1c4176403aead696aacc954dae
+  data.tar.gz: 4c46c595bd2dbe61968429240b6a1770895ea9f531fe84c4fe472c6146bb06df
 SHA512:
-  metadata.gz: 4ad8b699ab12f9ba22283fb1259cd5a9c5cb5b1de13e579097c8b8d3f1926f9200affb2e30aa6569c37720127da2c5ecb2202d4ad01b9b2a6594eb4fd5032880
-  data.tar.gz: 84f7b019ef890ab2b5e0d77b2ce8f75ef9618ffe1f03dbf63bfc3fbf9b762809f7bf4a42dc9e1fc43ef2b8139d3aca3c5d54725c3aad844177ec9b32194de1c0
+  metadata.gz: 54cf3972cd8ada223070d61b8d09ae1fbd6c7f033ad202831e07d2d7fd902f465e424947eb558c85f6aee4eb493d754b54f11c4f6a032a2787b4054b12ebea55
+  data.tar.gz: 98ffa471017dae7e4671958411e2a4d36b573dfaaa5ef363a39153353466919ff06c76fd6f69108289cb3d35a5781db02f3e7d6855031c38fdc340b2427d2a35

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-23
+
+### Added
+- **`ace-hitl ask`**: requester-side effect-callback API. Creates the local HITL event, binds it to a Lab HITL request via `--ace-hitl-id`, and passes effect declarations (`--effect-match`, `--effect-arg`, `--effect-cwd`, `--effect-timeout-s`) through verbatim after client-side bounds mirroring (match <= 200 chars and compilable; argv 1..16 x 1..512 chars using the lab's strip-then-bounds check so whitespace-only elements fail fast, valid values pass through verbatim; at least one element when any effect flag is present; cwd absolute and existing; timeout 1..600). Prints both the event id and the Lab request id, records `lab_request_effect: declared|none` on the event, and — when the Lab submit fails after the event was created — surfaces the orphan event id in the error.
+- **`ace-hitl wait` Lab awareness**: while waiting on the event answer, the waiter also observes the Lab request public projection (`/run/lab/hitl/public/<id>.json`, overridable via `ACE_HITL_LAB_PUBLIC_DIR`) across BOTH schema fields — the lifecycle `state` (created / answer-delivered / consumed / cancelled) and the separate `effect_state` (callback-pending-with-answer / callback-ok / callback-escalated). Terminal semantics are effect-aware: requests without a declared effect terminate on lifecycle states; effect-declaring requests keep waiting until the callback verdict appears instead of ending at answer delivery, and `callback-escalated` output points at `lab-hitl duty`. The event's `lab_request_state` records the effective state and never claims plain `answer-delivered` while an effect outcome exists. Relay consumption stays the agent's choice (`lab-hitl consume`).
+
+
+## [0.8.10] - 2026-09-02
+
+### Technical
+- Included in the coordinated all-package patch release preparation for ACE monorepo review.
 ## [0.8.9] - 2026-08-12
 
 ### Technical

data/README.md

@@ -10,6 +10,7 @@ Canonical workflow and skill for agents:
 ## Commands
 
 - `ace-hitl create` creates a HITL event
+- `ace-hitl ask` asks a human via HITL and forwards the request to the Lab (`--work`, effect callback flags)
 - `ace-hitl list` lists HITL events with filters (`--scope current|all`, all statuses by default)
 - `ace-hitl show` renders event details, path, or raw content (`--scope current|all`)
 - `ace-hitl update` updates frontmatter, answer content, and folder location
@@ -28,6 +29,7 @@ Use `ace-overseer status` for a global worktree dashboard.
 ace-hitl list
 ace-hitl list --scope all
 ace-hitl create "Which auth strategy?" --kind decision --question "JWT or sessions?"
+ace-hitl ask "Proceed with deploy?" --work W685 --effect-arg /bin/false --effect-cwd /tmp
 ace-hitl show abc123 --content
 ace-hitl show abc123 --scope current
 ace-hitl update abc123 --answer "Use JWT with server-side refresh tokens."

data/docs/usage.md

@@ -102,6 +102,37 @@ ace-hitl update abc123 --move-to next
 ace-hitl update abc123 --answer "close the assignment" --resume
 ```
 
+## Ask (Lab request with effect callback)
+
+`ace-hitl ask` creates the local HITL event, forwards the question to the Lab
+as a HITL request bound to the event via `--ace-hitl-id`, and prints both ids.
+Effect declarations are validated client-side (exact bounds) and passed through
+verbatim; the Lab tool remains the authority.
+
+```bash
+ace-hitl ask "Proceed with deploy?" \
+  --work W685 \
+  --effect-arg /usr/bin/notify-send "{answer}" \
+  --effect-cwd /tmp
+```
+
+- `--attempt` defaults to `LAB_ATTEMPT_ID`; `--project` to `ace`;
+  `--harness` to `lab-admin`; `--plan` to `ace-hitl ask`.
+- Effect flags: `--effect-match` (regex, <= 200 chars, must compile),
+  `--effect-arg` (repeatable, 1..16 x 1..512 chars after the lab's
+  strip-then-bounds check; whitespace-only elements fail fast, valid
+  values pass through verbatim; `{answer}` substituted lab-side),
+  `--effect-cwd` (absolute, must exist), `--effect-timeout-s` (1..600).
+- Whether an effect was declared is recorded on the event as
+  `lab_request_effect: declared|none` so `wait` can apply the right
+  terminal semantics.
+- The answer is always relayed unchanged; consume it with
+  `lab-hitl consume <request-id>` when ready.
+- If the Lab request fails after the local event was created, the error
+  surfaces the event id as an orphan (created but never bound to a Lab
+  request); inspect it with `ace-hitl show <id>` and delete or re-ask
+  as needed.
+
 ## Wait (Polling Default)
 
 Wait only for a specific HITL id. This is the default reliability path for the requester agent.
@@ -112,6 +143,23 @@ ace-hitl wait abc123 --poll-every 600 --timeout 14400
 ace-hitl wait abc123 --scope current
 ```
 
+When the event carries a Lab request (`lab_request_id`), wait also observes
+the Lab public projection instead of hanging blind. Both projection fields
+are observed: the lifecycle `state` (created / answer-delivered / consumed /
+cancelled) and the separate `effect_state` (callback-pending-with-answer /
+callback-ok / callback-escalated). Terminal semantics are effect-aware:
+
+- Requests without a declared effect terminate on lifecycle states
+  (`answer-delivered`, `consumed`, `cancelled`).
+- Effect-declaring requests keep waiting until the callback verdict
+  (`callback-ok` or `callback-escalated`) appears — they never end
+  silently at answer delivery; `callback-escalated` output points at
+  `lab-hitl duty` for the escalation.
+- The event's `lab_request_state` records the effective state, so it
+  never claims plain `answer-delivered` while an effect outcome exists.
+
+Relay consumption stays the agent's choice (`lab-hitl consume`).
+
 ## Lifecycle Event Names
 
 Canonical namespace for HITL lifecycle signaling:

data/lib/ace/hitl/atoms/hitl_effect_validator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Atoms
+      # Client-side mirror of the Lab effect-declaration bounds so invalid
+      # requests fail fast, before any external call. Declarations are never
+      # rewritten or "fixed": values pass through verbatim or fail.
+      class HitlEffectValidator
+        MAX_MATCH_LENGTH = 200
+        MIN_ARGV_ELEMENTS = 1
+        MAX_ARGV_ELEMENTS = 16
+        MAX_ARG_LENGTH = 512
+        MIN_TIMEOUT = 1
+        MAX_TIMEOUT = 600
+
+        class ValidationError < StandardError; end
+
+        def self.validate!(match: nil, effect_args: [], effect_cwd: nil, effect_timeout: nil)
+          new(
+            match: match,
+            effect_args: effect_args,
+            effect_cwd: effect_cwd,
+            effect_timeout: effect_timeout
+          ).validate!
+        end
+
+        def initialize(match:, effect_args:, effect_cwd:, effect_timeout:)
+          @match = present?(match) ? match.to_s : nil
+          @effect_args = Array(effect_args)
+          @effect_cwd = present?(effect_cwd) ? effect_cwd.to_s : nil
+          @effect_timeout = present?(effect_timeout) ? effect_timeout.to_s : nil
+        end
+
+        def validate!
+          validate_match
+          validate_effect_args
+          validate_effect_cwd
+          validate_effect_timeout
+          nil
+        end
+
+        private
+
+        def present?(value)
+          !(value.nil? || (value.respond_to?(:strip) ? value.strip.empty? : value.empty?))
+        end
+
+        def any_effect_flag?
+          @match || @effect_cwd || @effect_timeout || !@effect_args.empty?
+        end
+
+        def validate_match
+          return if @match.nil?
+
+          if @match.length > MAX_MATCH_LENGTH
+            raise ValidationError, "--effect-match exceeds #{MAX_MATCH_LENGTH} characters (got #{@match.length})"
+          end
+
+          begin
+            Regexp.new(@match)
+          rescue RegexpError => e
+            raise ValidationError, "--effect-match does not compile: #{e.message}"
+          end
+        end
+
+        def validate_effect_args
+          if any_effect_flag? && @effect_args.empty?
+            raise ValidationError, "at least one --effect-arg is required when any effect flag is present"
+          end
+
+          if @effect_args.length > MAX_ARGV_ELEMENTS
+            raise ValidationError, "too many --effect-arg values (#{@effect_args.length}); max #{MAX_ARGV_ELEMENTS}"
+          end
+
+          @effect_args.each_with_index do |arg, index|
+            # Mirror the lab's strip-then-bounds check; the value itself
+            # still passes through verbatim.
+            stripped = arg.to_s.strip
+            if stripped.empty?
+              raise ValidationError, "--effect-arg ##{index + 1} is empty"
+            end
+            if stripped.length > MAX_ARG_LENGTH
+              raise ValidationError, "--effect-arg ##{index + 1} exceeds #{MAX_ARG_LENGTH} characters (got #{stripped.length})"
+            end
+          end
+        end
+
+        def validate_effect_cwd
+          return if @effect_cwd.nil?
+
+          unless Pathname.new(@effect_cwd).absolute?
+            raise ValidationError, "--effect-cwd must be an absolute path (got '#{@effect_cwd}')"
+          end
+
+          return if File.directory?(@effect_cwd)
+
+          raise ValidationError, "--effect-cwd does not exist: #{@effect_cwd}"
+        end
+
+        def validate_effect_timeout
+          return if @effect_timeout.nil?
+
+          seconds = begin
+            Integer(@effect_timeout, 10)
+          rescue ArgumentError
+            raise ValidationError, "--effect-timeout-s must be an integer (got '#{@effect_timeout}')"
+          end
+
+          return if seconds.between?(MIN_TIMEOUT, MAX_TIMEOUT)
+
+          raise ValidationError, "--effect-timeout-s must be between #{MIN_TIMEOUT} and #{MAX_TIMEOUT} (got #{@effect_timeout})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "../../atoms/hitl_effect_validator"
+require_relative "../../molecules/lab_request_submitter"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Ask < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Ask a human via HITL and forward the request to the Lab"
+
+          argument :question, required: true, desc: "Question text for the human"
+
+          option :title, type: :string, desc: "Local HITL event title (defaults to the question)"
+          option :work, type: :string, desc: "Lab Work id (W...)"
+          option :attempt, type: :string, desc: "Lab Attempt id (A-...); defaults to LAB_ATTEMPT_ID"
+          option :project, type: :string, desc: "Lab project label (default: ace)"
+          option :harness, type: :string, desc: "Lab harness label (default: lab-admin)"
+          option :plan, type: :string, desc: "Lab plan label (default: ace-hitl ask)"
+
+          option :"effect-match", type: :string, desc: "Effect callback regex gate on the answer (<= 200 chars)"
+          option :"effect-arg", type: :string, repeat: true, desc: "Effect callback argv element, repeatable (1..16 x 1..512 chars)"
+          option :"effect-cwd", type: :string, desc: "Effect callback working directory (absolute, must exist)"
+          option :"effect-timeout-s", type: :string, desc: "Effect callback timeout in seconds (1..600)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(question:, **options)
+            effect = {
+              match: options[:"effect-match"],
+              effect_args: Array(options[:"effect-arg"]),
+              effect_cwd: options[:"effect-cwd"],
+              effect_timeout: options[:"effect-timeout-s"]
+            }
+            begin
+              Atoms::HitlEffectValidator.validate!(**effect)
+            rescue Atoms::HitlEffectValidator::ValidationError => e
+              raise_cli_error(e.message)
+            end
+            effect_declared = !!(effect[:match] || effect[:effect_cwd] || effect[:effect_timeout] ||
+              Array(effect[:effect_args]).any?)
+
+            work = require_work!(options)
+            attempt = options[:attempt] || ENV["LAB_ATTEMPT_ID"]
+            unless attempt && !attempt.strip.empty?
+              raise_cli_error("--attempt required (or set LAB_ATTEMPT_ID)")
+            end
+
+            submitter = Molecules::LabRequestSubmitter.new
+            request_id = submitter.generate_request_id
+
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            event = manager.create(
+              options[:title] || question,
+              questions: [question]
+            )
+
+            argv = submitter.build_argv(
+              request_id: request_id,
+              work: work,
+              attempt: attempt,
+              project: options[:project] || "ace",
+              harness: options[:harness] || "lab-admin",
+              plan: options[:plan] || "ace-hitl ask",
+              question: question,
+              ace_hitl_id: event.id,
+              **effect
+            )
+
+            begin
+              lab_request_id = submitter.submit(argv)
+            rescue Molecules::LabRequestSubmitter::SubmissionError => e
+              raise_cli_error(
+                "#{e.message}; local HITL event #{event.id} was created but never bound to a " \
+                  "Lab request (orphan) - inspect it with ace-hitl show #{event.id} and delete " \
+                  "or re-ask as needed"
+              )
+            end
+
+            manager.update(event.id, set: {
+              "lab_request_id" => lab_request_id,
+              "lab_request_state" => "created",
+              "lab_request_effect" => effect_declared ? "declared" : "none"
+            })
+
+            puts "HITL event: #{event.id}"
+            puts "Lab request: #{lab_request_id}"
+            puts "Answer relay: lab-hitl consume #{lab_request_id}"
+          end
+
+          private
+
+          def require_work!(options)
+            work = options[:work]
+            raise_cli_error("--work required (Lab Work id, e.g. W685)") if work.nil? || work.strip.empty?
+
+            work
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -47,8 +47,20 @@ module Ace
               event = result[:event]
               puts "HITL event answered: #{event.id} #{event.title}"
               puts "Answer: #{event.answer}"
+              puts "Lab request: #{event.metadata["lab_request_id"]} (#{result[:lab_state]})" if result[:lab_state]
               resume = event.metadata["resume_instructions"]
               puts "Resume: #{resume}" if resume
+            when :lab_delivered
+              event = result[:event]
+              lab_request_id = event.metadata["lab_request_id"]
+              puts "Lab request delivered: #{event.id} (#{result[:lab_state]})"
+              puts "Lab request: #{lab_request_id}"
+              puts "Consume the answer when ready: lab-hitl consume #{lab_request_id}"
+              if result[:lab_state] == "callback-ok"
+                puts "Effect callback: ok"
+              elsif result[:lab_state] == "callback-escalated"
+                puts "Effect callback: escalated; inspect with: lab-hitl duty"
+              end
             when :timeout
               raise Ace::Support::Cli::Error.new("Timed out waiting for HITL event '#{ref}'")
             else

data/lib/ace/hitl/cli.rb

@@ -3,6 +3,7 @@
 require "ace/support/cli"
 require_relative "../hitl/version"
 require_relative "cli/commands/create"
+require_relative "cli/commands/ask"
 require_relative "cli/commands/show"
 require_relative "cli/commands/list"
 require_relative "cli/commands/update"
@@ -17,6 +18,7 @@ module Ace
 
       REGISTERED_COMMANDS = [
         ["create", "Create HITL event"],
+        ["ask", "Ask a human via HITL and forward the request to the Lab"],
         ["show", "Show HITL event details"],
         ["list", "List HITL events"],
         ["update", "Update HITL event metadata or answer"],
@@ -27,11 +29,13 @@ module Ace
         "ace-hitl list --status pending",
         "ace-hitl show abc123 --content",
         "ace-hitl create \"Which auth strategy?\" --kind decision",
+        "ace-hitl ask \"Proceed with deploy?\" --work W685 --effect-arg /bin/false --effect-cwd /tmp",
         "ace-hitl update abc123 --answer \"Use JWT with refresh tokens\"",
         "ace-hitl wait abc123 --poll-every 600 --timeout 14400"
       ].freeze
 
       register "create", CLI::Commands::Create
+      register "ask", CLI::Commands::Ask
       register "show", CLI::Commands::Show
       register "list", CLI::Commands::List
       register "update", CLI::Commands::Update

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module Molecules
+      # Observes the Lab request public projection
+      # (`<public-dir>/<request-id>.json`) so waiters can surface lab-side
+      # states instead of hanging blind. Read-only; consumption of the
+      # answer relay remains the caller's choice.
+      #
+      # Projection schema (deployed lab-hitl, lab-config 8wl.t.ga9): the
+      # lifecycle field `state` carries created / answer-delivered /
+      # consumed / cancelled, while effect-callback outcomes live in the
+      # SEPARATE `effect_state` field (callback-pending-with-answer /
+      # callback-ok / callback-escalated). Both fields are observed here.
+      class LabProjectionObserver
+        DEFAULT_PUBLIC_DIR = "/run/lab/hitl/public"
+        PUBLIC_DIR_ENV = "ACE_HITL_LAB_PUBLIC_DIR"
+
+        # Lifecycle (`state`) terminal values: the answer was delivered to
+        # the relay, consumed, or the request was cancelled.
+        LIFECYCLE_TERMINAL_STATES = %w[answer-delivered consumed cancelled].freeze
+        # Effect (`effect_state`) terminal values: the callback reached a
+        # verdict. `callback-pending-with-answer` keeps a waiter holding.
+        EFFECT_TERMINAL_STATES = %w[callback-ok callback-escalated].freeze
+
+        # Both observed projection fields; either may be nil while the lab
+        # has not written it yet.
+        Snapshot = Struct.new(:state, :effect_state)
+
+        def initialize(public_dir: nil)
+          @public_dir = public_dir
+        end
+
+        # Reads the projection and returns a Snapshot with the lifecycle
+        # `state` and the separate `effect_state`, or nil when the
+        # projection is missing or unreadable.
+        def snapshot_for(request_id)
+          path = projection_path(request_id)
+          return nil unless File.file?(path)
+
+          projection = JSON.parse(File.read(path))
+          Snapshot.new(
+            state: projection["state"],
+            effect_state: projection["effect_state"]
+          )
+        rescue
+          nil
+        end
+
+        # The state a waiter should report: the effect outcome when one
+        # exists (so `lab_request_state` never claims plain
+        # `answer-delivered` while an effect outcome is present), the
+        # lifecycle state otherwise.
+        def effective_state(snapshot)
+          return nil unless snapshot
+
+          snapshot.effect_state || snapshot.state
+        end
+
+        # Terminality depends on whether the request declared an effect
+        # callback: effect-declaring requests terminate only on an effect
+        # verdict (callback-ok / callback-escalated), never at answer
+        # delivery; other requests terminate on lifecycle terminal states.
+        def terminal?(snapshot, effect_declared: false)
+          return false unless snapshot
+
+          if effect_declared
+            EFFECT_TERMINAL_STATES.include?(snapshot.effect_state)
+          else
+            LIFECYCLE_TERMINAL_STATES.include?(snapshot.state)
+          end
+        end
+
+        def projection_path(request_id)
+          File.join(public_dir, "#{request_id}.json")
+        end
+
+        private
+
+        def public_dir
+          @public_dir || ENV.fetch(PUBLIC_DIR_ENV, DEFAULT_PUBLIC_DIR)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "open3"
+require "securerandom"
+require "json"
+
+module Ace
+  module Hitl
+    module Molecules
+      # Builds and runs the `lab-hitl request` invocation on behalf of a
+      # requester. The argv contract is stable: existing required flags
+      # first, effect flags in a fixed order (match, args, cwd, timeout).
+      # Values pass through verbatim; no answer content or effect argv is
+      # ever logged here.
+      class LabRequestSubmitter
+        DEFAULT_LAB_BIN = "/usr/local/bin/lab-hitl"
+        LAB_BIN_ENV = "ACE_HITL_LAB_BIN"
+
+        class SubmissionError < StandardError; end
+
+        def initialize(bin: nil, runner: nil, id_generator: nil)
+          @bin = bin || ENV.fetch(LAB_BIN_ENV, DEFAULT_LAB_BIN)
+          @runner = runner || ->(argv) { Open3.capture3(*argv) }
+          @id_generator = id_generator || -> { "hitl-#{SecureRandom.hex(8)}" }
+        end
+
+        def generate_request_id
+          @id_generator.call
+        end
+
+        def build_argv(request_id:, work:, attempt:, project:, harness:, plan:, question:, ace_hitl_id:,
+          match: nil, effect_args: [], effect_cwd: nil, effect_timeout: nil)
+          argv = [
+            @bin, "request",
+            "--id", request_id,
+            "--work", work,
+            "--attempt", attempt,
+            "--project", project,
+            "--harness", harness,
+            "--plan", plan,
+            "--question", question,
+            "--ace-hitl-id", ace_hitl_id
+          ]
+          argv += ["--effect-match", match] if match
+          Array(effect_args).each { |arg| argv += ["--effect-arg", arg] }
+          argv += ["--effect-cwd", effect_cwd] if effect_cwd
+          argv += ["--effect-timeout-s", effect_timeout] if effect_timeout
+          argv
+        end
+
+        def submit(argv)
+          stdout, stderr, status = run(argv)
+          unless status.success?
+            raise SubmissionError, "lab-hitl request failed (exit #{status.exitstatus}): #{stderr.to_s.strip}"
+          end
+
+          parse_request_id(stdout)
+        end
+
+        private
+
+        # Distinguishes could-not-execute (missing/unreadable binary,
+        # Errno::*) from could-not-parse so failures are actionable.
+        def run(argv)
+          @runner.call(argv)
+        rescue => e
+          raise SubmissionError, "could not execute #{@bin}: #{e.class}: #{e.message}"
+        end
+
+        def parse_request_id(stdout)
+          value = JSON.parse(stdout)
+          id = value["id"]
+          raise SubmissionError, "lab-hitl request returned no id" if id.nil? || id.to_s.strip.empty?
+
+          id
+        rescue JSON::ParserError => e
+          raise SubmissionError, "could not parse lab-hitl request output as JSON: #{e.message}"
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,7 @@ require_relative "../molecules/hitl_config_loader"
 require_relative "../molecules/hitl_scanner"
 require_relative "../molecules/hitl_loader"
 require_relative "../molecules/hitl_creator"
+require_relative "../molecules/lab_projection_observer"
 require_relative "../molecules/hitl_answer_editor"
 require_relative "../molecules/resume_dispatcher"
 require_relative "../molecules/worktree_scope_resolver"
@@ -121,7 +122,7 @@ module Ace
           loader.load(current_path, id: event.id, special_folder: current_special)
         end
 
-        def wait_for_answer(ref, scope: nil, poll_every: 600, timeout: 14_400, waiter: {}, now_proc: nil, sleeper: nil)
+        def wait_for_answer(ref, scope: nil, poll_every: 600, timeout: 14_400, waiter: {}, now_proc: nil, sleeper: nil, lab_observer: nil)
           poll_every = normalize_poll_seconds(poll_every)
           timeout = normalize_timeout_seconds(timeout)
           now_proc ||= -> { Time.now.utc }
@@ -148,7 +149,20 @@ module Ace
               scope: scope
             )
 
-            if event.answered?
+            observer = lab_observer_for(lab_observer)
+            lab_snapshot = observe_lab_state(event, observer: observer, scope: scope)
+            lab_state = observer.effective_state(lab_snapshot)
+
+            # An effect-declaring request keeps waiting until the callback
+            # verdict (callback-ok / callback-escalated) is visible; answer
+            # delivery alone never ends the wait. When the projection is
+            # unreadable there is nothing to hold on, so the wait falls
+            # back to the event/lifecycle behavior (timeout stays the
+            # backstop).
+            hold_for_effect = effect_declared?(event) && lab_snapshot &&
+              !observer.terminal?(lab_snapshot, effect_declared: true)
+
+            if event.answered? && !hold_for_effect
               update(event.id,
                 set: {
                   "waiter_state" => "answered",
@@ -157,12 +171,25 @@ module Ace
                 scope: scope
               )
               refreshed = show(event.id, scope: scope)&.dig(:event) || event
-              return {status: :answered, event: refreshed}
+              return {status: :answered, event: refreshed, lab_state: lab_state}
+            end
+
+            if observer.terminal?(lab_snapshot, effect_declared: effect_declared?(event))
+              update(
+                event.id,
+                set: {
+                  "waiter_state" => "lab_delivered",
+                  "waiter_last_seen_at" => now.iso8601,
+                  "lab_request_state" => lab_state
+                },
+                scope: scope
+              )
+              return {status: :lab_delivered, event: event, lab_state: lab_state}
             end
 
             if now >= deadline
               update(event.id, set: {"waiter_state" => "timed_out"}, scope: scope)
-              return {status: :timeout, event: event}
+              return {status: :timeout, event: event, lab_state: lab_state}
             end
 
             sleep_seconds = [poll_every, (deadline - now).ceil].min
@@ -216,6 +243,26 @@ module Ace
 
         private
 
+        def lab_observer_for(lab_observer)
+          lab_observer || Molecules::LabProjectionObserver.new
+        end
+
+        def effect_declared?(event)
+          event.metadata["lab_request_effect"] == "declared"
+        end
+
+        def observe_lab_state(event, observer:, scope:)
+          request_id = event.metadata["lab_request_id"]
+          return nil if request_id.nil? || request_id.to_s.strip.empty?
+
+          snapshot = observer.snapshot_for(request_id)
+          state = observer.effective_state(snapshot)
+          if state && state != event.metadata["lab_request_state"]
+            update(event.id, set: {"lab_request_state" => state}, scope: scope)
+          end
+          snapshot
+        end
+
         def load_config
           Molecules::HitlConfigLoader.load
         end

data/lib/ace/hitl/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Hitl
-    VERSION = "0.8.9"
+    VERSION = "0.9.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.8.9
+  version: 0.9.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-core
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: ace-support-fs
   requirement: !ruby/object:Gem::Requirement
@@ -116,9 +116,11 @@ files:
 - handbook/skills/as-hitl/SKILL.md
 - handbook/workflow-instructions/hitl.wf.md
 - lib/ace/hitl.rb
+- lib/ace/hitl/atoms/hitl_effect_validator.rb
 - lib/ace/hitl/atoms/hitl_file_pattern.rb
 - lib/ace/hitl/atoms/hitl_id_formatter.rb
 - lib/ace/hitl/cli.rb
+- lib/ace/hitl/cli/commands/ask.rb
 - lib/ace/hitl/cli/commands/create.rb
 - lib/ace/hitl/cli/commands/list.rb
 - lib/ace/hitl/cli/commands/show.rb
@@ -132,6 +134,8 @@ files:
 - lib/ace/hitl/molecules/hitl_loader.rb
 - lib/ace/hitl/molecules/hitl_resolver.rb
 - lib/ace/hitl/molecules/hitl_scanner.rb
+- lib/ace/hitl/molecules/lab_projection_observer.rb
+- lib/ace/hitl/molecules/lab_request_submitter.rb
 - lib/ace/hitl/molecules/resume_dispatcher.rb
 - lib/ace/hitl/molecules/worktree_scope_resolver.rb
 - lib/ace/hitl/organisms/hitl_manager.rb