ace-hitl 0.8.10 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9a48d15df570a949720e3ca4e9aa1795629a9822dad2411f4ae4ddd1a59d22e
-  data.tar.gz: 56bb54f1137d22cee38863f6df76d03ac9452c45f2382f62cee70feea23d4c88
+  metadata.gz: 765d5a3ec0942bb25b92c9e16bf325bc60f5f9c58e72da56e8b62f8c716817e2
+  data.tar.gz: b3c1015a2037ac173be8cae4ce7527fc0b099bbdf5acd419572c30992a874424
 SHA512:
-  metadata.gz: 0ff1a815c40e0469c6f41e08c2ac40222e3e395907e7c656cfd761ae1607e820d9d1ed124a392518ce013a264755ca07fec3dedd34bd5b1c61f6e473d7ec6196
-  data.tar.gz: 40e3928262e57b092da698c4193cb03c7c848534a8f8037fea426bc677d1437980f7be3d4b1741e1adbe87ecb0fbc2efbea83d7e6c80c2a0a4b3f42ae74338a5
+  metadata.gz: a54fd6f1fc8ac167b6ccd87bb724cd469c733df2a37006e2066a5123f875365ee65ef7d91132cf284167ea359bb57df6147ecc6e75f3f9cab264a9377c31809d
+  data.tar.gz: 11bd3b6c7a553d5372b9cb2ee10ac87b1586e82ca90ab470e6216f041410db987842605ce7dca8595eed31e07c17c05b0453374e0cf14b2131bd65d9982aa516

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-27
+
+### Added
+- **Generic HITL request lifecycle (spec 8wm.t.y21, M1 migration from lab-config lab-hitl)**: the generic core now lives natively in the gem under `Ace::Hitl::Lifecycle` — request store (`create`/`pending`/`states`/`deliver`/`consume`/`cancel`), kinds + OTP/secret-shape answer gates, 0400 requester-owned answer relay, 0440 merge-on-write public projection under a per-request `flock`, no time-based expiry (W651: only an answer, its consumption, or an explicit audited `cancel` ends a request), requester-declared effect callbacks executed AS THE REQUESTER (exec-argv with `{answer}`, fullmatch regex gate, bounded timeout, redacted root-only effects log, deduped escalation with `callback-ok`/`callback-escalated` projection states and the pending+escalated duty projection), and the Overseer reverse-address surface (`overseer-send`/`overseer-pending`/`overseer-ack`: bounded, type-tagged `[decyzja]`/`[pytanie]`/`[info]`, no SHA/Work/Attempt/task IDs). New CLI commands: `deliver`, `consume`, `cancel`, `pending`, `states`, `duty`, `overseer-send`, `overseer-pending`, `overseer-ack` (machine output: one JSON line). Store root: `ACE_HITL_STORE_ROOT` (default `/run/lab/hitl`); Overseer channel root: `ACE_HITL_OVERSEER_CHANNEL_ROOT` (default `/lab/state/overseer-channel`).
+- **Binding policy seam**: the generic store requires a fail-closed `Lifecycle::Binding` policy; provider=lab supplies `Providers::Lab::DaemonBinding`, the minimal client of the lab daemon's read-only `hitl_binding` socket op (Work/Attempt binding authority stays lab-side, per audit 8wl.t.gad.6). Escalation spooling stays behind the store's `escalation_sink` seam (the wake/`lab_control` glue stays lab-config).
+- **Provider adapter interface + provider=lab contract (spec 8wm.t.vrz)**: `ace-hitl ask` dispatches through the `Ace::Hitl::Providers` registry (selection: `--provider` flag → `ACE_HITL_PROVIDER` env → `lab`). The ask performs the local-event + transport send in ONE operation and captures the asker's reverse address fail-closed from the herdr environment (`HERDR_SESSION` / `HERDR_PANE`; versioned schema `ace.hitl.ref/v1`), persisting `provider`, `ref_schema`, `ref_session`, `ref_pane` alongside the existing `lab_request_*` fields. Pinned error model: `UnknownProviderError`, `InvalidRefError` (fail closed before any event or transport state), `ProviderUnavailableError` (transport failure; orphan event id message preserved), `UnsupportedOperationError` (`deliver(ref, answer)` lands with ace-herdr push delivery 8wm.t.vs0 + provider=lab integration 8wm.t.vs2; `wait` remains the pane-less CLI path outside the adapter).
+
+### Changed
+- **provider=lab `ask` creates the relay request through the native lifecycle store** (binding + effect declared in-process). The external-binary transport `Providers::Lab::Transport` is DELETED (pre-1.0; supersedes the 8wm.t.vrz §7 re-homing); the orphan-event `ProviderUnavailableError` contract is preserved. File and record formats stay byte-compatible with the deployed lab consumers.
+- **Zero-lab-hitl guard**: the legacy `Molecules::LabRequestSubmitter` was deleted and re-homed (same behavior, provider error model) as `Providers::Lab::Transport`, the sole owner of the lab transport binary reference. A fast guard test keeps every agent-facing ace-hitl path free of direct lab transport references, and agent-facing ask/wait output no longer names the relay binary.
+
+### Removed
+- `Providers::Lab::Transport` and the `ACE_HITL_LAB_BIN` selection: the relay request path no longer shells out to an external binary.
+
+### Fixed
+- **PR#336 review hardening (codex astra high)**: unique atomic-writer temporary files so competing writers can no longer delete each other's in-flight temp (store answer relay included); delivery and cancel re-validate the request incarnation and ownership under the per-request lock (a cancel+recreate of the same id can no longer redirect an answer into the new incarnation); the first projection is initialized inside the lifecycle lock behind a per-incarnation token so a broker delivery can never be regressed to `created`; effect callbacks spawn with forced exec/argv semantics (a single-element declaration can no longer reach a shell) as process group leaders whose whole group is terminated on timeout; `{answer}` substitution is literal (block-form `gsub`, no replacement-string backreferences); answer bounds are enforced on decoded UTF-8 characters with a separate byte bound, so valid multibyte answers through real IO are accepted.
+
+## [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
 

data/README.md

@@ -10,10 +10,16 @@ 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 through a provider adapter (`--provider`, default `lab`); ONE operation: local event + relay request through the native lifecycle store (`--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
 - `ace-hitl wait` polls a specific HITL event until answered (`--poll-every`, `--timeout`)
+- `ace-hitl deliver` answers a pending relay request from stdin (host-broker operation); executes the declared effect callback as the requester
+- `ace-hitl consume` consumes one own relay request's answer (indefinite by default; `--timeout` bounds only the local wait)
+- `ace-hitl cancel` cancels with an audited reason (the only way to abandon a request)
+- `ace-hitl pending` / `ace-hitl states` / `ace-hitl duty` host-broker projections (pending, public lifecycle records, pending + escalated)
+- `ace-hitl overseer-send` / `ace-hitl overseer-pending` / `ace-hitl overseer-ack` the Overseer reverse-address response channel
 
 `ace-hitl` is a blocker-resolution tool, not a global dashboard:
 
@@ -22,12 +28,40 @@ Canonical workflow and skill for agents:
 
 Use `ace-overseer status` for a global worktree dashboard.
 
+## Provider adapters
+
+`ace-hitl ask` dispatches through the `Ace::Hitl::Providers` registry
+(selection: `--provider` flag → `ACE_HITL_PROVIDER` env → `lab`).
+
+- `ask` is ONE operation: it creates the local HITL event and the relay
+  request through the NATIVE generic lifecycle store
+  (`Ace::Hitl::Lifecycle`; migration spec 8wm.t.y21), then persists
+  `provider`, `ref_schema`, `ref_session`, `ref_pane` plus the existing
+  `lab_request_*` fields.
+- The asker's reverse address (`ref`, versioned schema
+  `ace.hitl.ref/v1`: herdr session + pane) is captured fail-closed from
+  `HERDR_SESSION` / `HERDR_PANE`; absent or invalid values abort the ask
+  before any event is created or store state changes.
+- Error model: `UnknownProviderError`, `InvalidRefError`,
+  `ProviderUnavailableError` (store-create failure; surfaces the orphan
+  event id when one was already created), `UnsupportedOperationError`.
+- `deliver(ref, answer)` (push the answer back to the asker's pane) is
+  declared by the interface; provider `lab` raises
+  `UnsupportedOperationError` until the ace-herdr push-delivery
+  integration lands. `ace-hitl wait` stays the pane-less script path and
+  does not go through a provider.
+- The generic lifecycle is provider-agnostic; all lab coupling lives in
+  the provider=lab seams (the `Providers::Lab::DaemonBinding` labd
+  binding client and the store factory), enforced by guard tests.
+
 ## Examples
 
 ```bash
 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 ask "Proceed with deploy?" --provider lab --work W685
 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,105 @@ ace-hitl update abc123 --move-to next
 ace-hitl update abc123 --answer "close the assignment" --resume
 ```
 
+## Ask (Provider adapter with effect callback)
+
+`ace-hitl ask` dispatches through the provider adapter registry
+(`--provider`, default: `ACE_HITL_PROVIDER` env, then `lab`). ONE
+operation: it creates the local HITL event, forwards the question through
+the provider transport bound to the event via `--ace-hitl-id`, and prints
+both ids. Effect declarations are validated client-side (exact bounds)
+and passed through verbatim into the native relay request store.
+
+```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`.
+- Reverse address (fail closed): the asker's herdr session + pane are
+  read from `HERDR_SESSION` / `HERDR_PANE` and persisted on the event as
+  `ref_session` / `ref_pane` with `ref_schema: ace.hitl.ref/v1` and
+  `provider: lab`. Absent or invalid values abort the ask before any
+  event is created or transport is called — an ask must always know
+  where its answer can be delivered.
+- 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; consumption stays on the
+  operator side via `ace-hitl consume`.
+- If the transport send fails after the local event was created, the
+  error surfaces the event id as an orphan (created but never bound to a
+  relay request); inspect it with `ace-hitl show <id>` and delete or
+  re-ask as needed.
+- `deliver(ref, answer)` — pushing the answer back to the asker's pane —
+  is declared by the adapter interface; provider `lab` reports it as
+  unsupported until the ace-herdr push-delivery integration lands.
+
+## Relay Lifecycle (Generic HITL Request Store)
+
+The generic relay request lifecycle is native to the gem
+(`Ace::Hitl::Lifecycle`; migration spec 8wm.t.y21). Requests are
+file-backed, never expire on a timer, and every terminal transition
+shares one per-request lock. The store root is `ACE_HITL_STORE_ROOT`
+(default `/run/lab/hitl`); the Overseer channel root is
+`ACE_HITL_OVERSEER_CHANNEL_ROOT` (default `/lab/state/overseer-channel`).
+Machine output is one JSON line.
+
+Operator/broker side (host-broker operations are root-only):
+
+```bash
+ace-hitl pending                    # answerable requests
+ace-hitl states                     # all public lifecycle projections
+ace-hitl duty                       # pending + escalated projection
+ace-hitl deliver hitl-0a1b2c3d4e5f6708 <<< "approved"
+```
+
+`deliver` reads the answer from stdin, relays it unchanged (0400,
+owner = requester) into `secrets/` for OTP kinds or `answers/` for
+everything else, re-verifies attempt liveness under the request lock,
+and then executes the declared effect callback AS THE REQUESTER:
+exec-style argv (never a shell), `{answer}` substituted once per
+element, optional fullmatch regex gate, bounded timeout, attempts
+logged redacted in the root-only effects log, and one deduped
+escalation with `effect_state: callback-escalated` in the public
+projection on failure (`callback-ok` on success).
+
+Requester side:
+
+```bash
+ace-hitl consume hitl-0a1b2c3d4e5f6708
+ace-hitl consume hitl-0a1b2c3d4e5f6708 --timeout 600
+ace-hitl cancel hitl-0a1b2c3d4e5f6708 --reason "operator stopped the work"
+```
+
+A consume timeout bounds ONLY the local wait — the request stays
+pending and answerable. Cancel is the ONLY way to abandon a request;
+it records `cancelled_by` and the `reason` in the public projection,
+and a late answer fails closed.
+
+Overseer reverse address (bounded, type-tagged responses):
+
+```bash
+ace-hitl overseer-send --reply-to 321 <<< "[decyzja] Rekomendacja: A."
+ace-hitl overseer-pending
+ace-hitl overseer-ack msg-0123456789abcdef
+```
+
+Responses are 1..1200 characters and must open with a type tag
+(`[decyzja]`, `[pytanie]`, or `[info]`); full SHAs, Work/Attempt/task
+IDs, or the word "SHA" are rejected. `overseer-send` is the overseer
+user's operation; `overseer-pending`/`overseer-ack` are host-broker
+(root) operations used by the transport to drain and acknowledge
+relayed responses.
+
 ## Wait (Polling Default)
 
 Wait only for a specific HITL id. This is the default reliability path for the requester agent.
@@ -112,6 +211,26 @@ 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
+  the lab duty projection 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 on the operator side via `ace-hitl consume`.
+`wait` is the pane-less script path: agents with a herdr pane ask
+through the provider adapter and receive answers delivered back to
+their pane.
+
 ## 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,115 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "../../lifecycle"
+require_relative "../../atoms/hitl_effect_validator"
+require_relative "../../providers/providers"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Ask < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Ask a human via HITL and forward the request through a provider adapter"
+
+          argument :question, required: true, desc: "Question text for the human"
+
+          option :title, type: :string, desc: "Local HITL event title (defaults to the question)"
+          option :provider, type: :string, desc: "HITL provider adapter (default: ACE_HITL_PROVIDER or lab)"
+          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 = build_effect(options)
+            validate_effect!(effect)
+
+            work = require_work!(options)
+            attempt = require_attempt!(options)
+            provider = resolve_provider(options[:provider])
+            ref = capture_ref
+
+            result = provider.ask(
+              question: question,
+              title: options[:title],
+              ref: ref,
+              work: work,
+              attempt: attempt,
+              project: options[:project] || Providers::Lab::DEFAULT_PROJECT,
+              harness: options[:harness] || Providers::Lab::DEFAULT_HARNESS,
+              plan: options[:plan] || Providers::Lab::DEFAULT_PLAN,
+              effect: effect
+            )
+
+            puts "HITL event: #{result.event_id}"
+            puts "Provider: #{Providers::Lab::PROVIDER_NAME} (ref #{ref.session}/#{ref.pane}, #{Providers::Ref::SCHEMA})"
+            puts "Lab request: #{result.request_id}"
+          rescue Providers::ProviderUnavailableError => e
+            raise_cli_error(e.message)
+          end
+
+          private
+
+          def build_effect(options)
+            {
+              match: options[:"effect-match"],
+              effect_args: Array(options[:"effect-arg"]),
+              effect_cwd: options[:"effect-cwd"],
+              effect_timeout: options[:"effect-timeout-s"]
+            }
+          end
+
+          def validate_effect!(effect)
+            Atoms::HitlEffectValidator.validate!(**effect)
+          rescue Atoms::HitlEffectValidator::ValidationError => e
+            raise_cli_error(e.message)
+          end
+
+          def require_work!(options)
+            work = options[:work]
+            raise_cli_error("--work required (Lab Work id, e.g. W685)") if work.nil? || work.strip.empty?
+
+            work
+          end
+
+          def require_attempt!(options)
+            attempt = options[:attempt] || ENV["LAB_ATTEMPT_ID"]
+            unless attempt && !attempt.strip.empty?
+              raise_cli_error("--attempt required (or set LAB_ATTEMPT_ID)")
+            end
+
+            attempt
+          end
+
+          def resolve_provider(raw)
+            name = raw || ENV["ACE_HITL_PROVIDER"] || Providers::Lab::PROVIDER_NAME
+            Providers.resolve(name)
+          rescue Providers::UnknownProviderError => e
+            raise_cli_error(e.message)
+          end
+
+          # Fail closed BEFORE any state is created: the reverse address is
+          # required so the answer can be delivered back to this pane.
+          def capture_ref
+            Providers::Ref.from_env
+          rescue Providers::InvalidRefError => e
+            raise_cli_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # The ONLY way to abandon a relay request: explicit, audited
+        # cancellation recorded in the public lifecycle projection
+        # (spec 8wm.t.y21 §3).
+        class Cancel < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Cancel one HITL relay request with an audited reason"
+
+          argument :id, required: true, desc: "HITL relay request id"
+
+          option :reason, type: :string, desc: "Audited reason recorded in the public lifecycle record"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(id:, **options)
+            emit(lifecycle_store.cancel(id, reason: options[:reason] || ""))
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Requester-side answer consumption. A positive timeout bounds
+        # ONLY the local wait and never cancels the request (W651);
+        # without it the wait is indefinite (spec 8wm.t.y21 §3).
+        class Consume < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Wait for and consume the answer of one own HITL relay request"
+
+          argument :id, required: true, desc: "HITL relay request id"
+
+          option :timeout, type: :integer, desc: "Local wait bound in seconds; 0 (default) waits indefinitely"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(id:, **options)
+            emit(lifecycle_store.consume(id, timeout: options[:timeout] || 0))
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Operator/broker answering of one relay request (the "respond"
+        # surface). The answer is read from stdin; the effect callback,
+        # if declared, executes after the relay (spec 8wm.t.y21 §3, §5).
+        class Deliver < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Deliver an answer (stdin) to a pending HITL relay request"
+
+          argument :id, required: true, desc: "HITL relay request id"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(id:, **options)
+            emit(lifecycle_store.deliver(id, LifecycleCommand::STDIN_READER))
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # The standing-duty projection: pending + escalated (spec
+        # 8wm.t.y21 §7).
+        class Duty < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Project pending and escalated HITL requests (host-broker operation)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(Lifecycle::Duty.project(lifecycle_store))
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Shared plumbing for the operator/broker lifecycle commands
+        # (spec 8wm.t.y21 §8): the store is built through the provider=lab
+        # seam and machine outputs are one JSON line, byte-compatible
+        # with the migrated CLI contract.
+        module LifecycleCommand
+          STDIN_READER = ->(limit) { $stdin.read(limit) }.freeze
+
+          def lifecycle_store(store: nil)
+            Providers::Lab.lifecycle_store(store: store)
+          end
+
+          def overseer
+            channel_root = ENV.fetch("ACE_HITL_OVERSEER_CHANNEL_ROOT", "/lab/state/overseer-channel")
+            Lifecycle::Overseer.new(outbox_dir: File.join(channel_root, "outbox"))
+          end
+
+          def emit(result)
+            puts JSON.generate(result)
+          end
+
+          def raise_lifecycle_error(message)
+            raise Ace::Support::Cli::Error.new(message)
+          end
+        end
+      end
+    end
+  end
+end

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

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