ace-hitl 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c36ea0129ebd4da1a3b54f5f6cb2f1701e38a1c4176403aead696aacc954dae
-  data.tar.gz: 4c46c595bd2dbe61968429240b6a1770895ea9f531fe84c4fe472c6146bb06df
+  metadata.gz: 765d5a3ec0942bb25b92c9e16bf325bc60f5f9c58e72da56e8b62f8c716817e2
+  data.tar.gz: b3c1015a2037ac173be8cae4ce7527fc0b099bbdf5acd419572c30992a874424
 SHA512:
-  metadata.gz: 54cf3972cd8ada223070d61b8d09ae1fbd6c7f033ad202831e07d2d7fd902f465e424947eb558c85f6aee4eb493d754b54f11c4f6a032a2787b4054b12ebea55
-  data.tar.gz: 98ffa471017dae7e4671958411e2a4d36b573dfaaa5ef363a39153353466919ff06c76fd6f69108289cb3d35a5781db02f3e7d6855031c38fdc340b2427d2a35
+  metadata.gz: a54fd6f1fc8ac167b6ccd87bb724cd469c733df2a37006e2066a5123f875365ee65ef7d91132cf284167ea359bb57df6147ecc6e75f3f9cab264a9377c31809d
+  data.tar.gz: 11bd3b6c7a553d5372b9cb2ee10ac87b1586e82ca90ab470e6216f041410db987842605ce7dca8595eed31e07c17c05b0453374e0cf14b2131bd65d9982aa516

data/CHANGELOG.md

@@ -7,6 +7,23 @@ 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

data/README.md

@@ -10,11 +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 to the Lab (`--work`, effect callback flags)
+- `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:
 
@@ -23,6 +28,32 @@ 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
@@ -30,6 +61,7 @@ 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,12 +102,14 @@ ace-hitl update abc123 --move-to next
 ace-hitl update abc123 --answer "close the assignment" --resume
 ```
 
-## Ask (Lab request with effect callback)
+## Ask (Provider adapter 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.
+`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?" \
@@ -118,6 +120,12 @@ ace-hitl ask "Proceed with deploy?" \
 
 - `--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
@@ -126,12 +134,72 @@ ace-hitl ask "Proceed with deploy?" \
 - 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.
+- 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)
 
@@ -154,11 +222,14 @@ callback-ok / callback-escalated). Terminal semantics are effect-aware:
 - 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 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 the agent's choice (`lab-hitl consume`).
+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
 

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

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require "ace/support/cli"
+require_relative "../../lifecycle"
 require_relative "../../atoms/hitl_effect_validator"
-require_relative "../../molecules/lab_request_submitter"
+require_relative "../../providers/providers"
 
 module Ace
   module Hitl
@@ -11,11 +12,12 @@ module Ace
         class Ask < Ace::Support::Cli::Command
           include Ace::Support::Cli::Base
 
-          desc "Ask a human via HITL and forward the request to the Lab"
+          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)"
@@ -32,69 +34,49 @@ module Ace
           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?)
+            effect = build_effect(options)
+            validate_effect!(effect)
 
             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
+            attempt = require_attempt!(options)
+            provider = resolve_provider(options[:provider])
+            ref = capture_ref
 
-            manager = Ace::Hitl::Organisms::HitlManager.new
-            event = manager.create(
-              options[:title] || question,
-              questions: [question]
-            )
-
-            argv = submitter.build_argv(
-              request_id: request_id,
+            result = provider.ask(
+              question: question,
+              title: options[:title],
+              ref: ref,
               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
+              project: options[:project] || Providers::Lab::DEFAULT_PROJECT,
+              harness: options[:harness] || Providers::Lab::DEFAULT_HARNESS,
+              plan: options[:plan] || Providers::Lab::DEFAULT_PLAN,
+              effect: 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
+            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
 
-            manager.update(event.id, set: {
-              "lab_request_id" => lab_request_id,
-              "lab_request_state" => "created",
-              "lab_request_effect" => effect_declared ? "declared" : "none"
-            })
+          private
 
-            puts "HITL event: #{event.id}"
-            puts "Lab request: #{lab_request_id}"
-            puts "Answer relay: lab-hitl consume #{lab_request_id}"
+          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
 
-          private
+          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]
@@ -102,6 +84,30 @@ module Ace
 
             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

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

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Host-broker drain view of the Overseer response outbox.
+        class OverseerPending < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "List queued Overseer responses (host-broker operation)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(overseer.pending)
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # The Root Overseer's bounded, type-tagged response through the
+        # reverse address (spec 8wm.t.y21 §6). The response is read from
+        # stdin.
+        class OverseerSend < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Queue a bounded, type-tagged Overseer response (stdin)"
+
+          option :"reply-to", type: :string, desc: "Source message id this response answers"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(overseer.send_response(
+              reply_to: options[:"reply-to"] || "",
+              reader: LifecycleCommand::STDIN_READER
+            ))
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end