ace-hitl 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c36ea0129ebd4da1a3b54f5f6cb2f1701e38a1c4176403aead696aacc954dae
-  data.tar.gz: 4c46c595bd2dbe61968429240b6a1770895ea9f531fe84c4fe472c6146bb06df
+  metadata.gz: 579408795de68b05baeeb590eac46687706134301423cb6114874c377d8183ed
+  data.tar.gz: ba4f300554670fb40acd58c470183d70342626b170889bda9944468aa54df6e8
 SHA512:
-  metadata.gz: 54cf3972cd8ada223070d61b8d09ae1fbd6c7f033ad202831e07d2d7fd902f465e424947eb558c85f6aee4eb493d754b54f11c4f6a032a2787b4054b12ebea55
-  data.tar.gz: 98ffa471017dae7e4671958411e2a4d36b573dfaaa5ef363a39153353466919ff06c76fd6f69108289cb3d35a5781db02f3e7d6855031c38fdc340b2427d2a35
+  metadata.gz: f421f0a4df5ea2eb782766c259336f1298844b3e8ebcefad34885c446865538f02d4d7da3bedcbc84c254464e8a589ff4d3007de8fbe14d0158ad23edf6118d3
+  data.tar.gz: 5102b14720d671f3252eae1b37b942620128f33df90983877e25354958b147bda0545b86ff946aa35f973210abdea603a342547acf11621b4baf2829c0372a65

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-04
+
+### Added
+- **Scoped privilege boundary for multi-user HITL state (spec 8wq.t.34i)**: the lifecycle store is now the PRIVATE state of one authenticated boundary service. `ace-hitl serve` runs the boundary over a peer-credential-authenticated UNIX socket (`Ace::Hitl::Lifecycle::Service`): every connection is identified from kernel peer credentials (`getpeereid` — payload fields and environment variables are never authority), clients authenticate the endpoint back (socket must be owned by the trusted service uid from the grants document, not world-writable, connected peer must BE the service uid), and the store root is service-owned (`0711` traverse-only root, `0700` private directories, `0755` public projections with `0440` non-secret records — no chmod-to-world workaround anywhere). Bounded newline-JSON protocol (`Lifecycle::Protocol`) with classified errors: `PermissionError`, `BindingError`, `StateError`, `AnswerError`, and the new `TransportError` for boundary unavailability — transport failures are visible and recoverable, never silent.
+- **Managed assignment binding**: requests bind to the exact ACTIVE MANAGED attempt of the calling actor through the ace-assign coordinator (`Providers::Lab::AssignmentBinding`). `ace-assign` gained `AttemptCoordinator#with_verified_attempt`, which holds the assignment `LifecycleExclusion` (shared side) across the caller's whole locked transition while `finish`/`reconcile` hold the exclusive side — stale, ended, replaced, or unproven (uncertain) attempts cannot acquire authority, and terminal commits can never interleave with a liveness check. CLI: `ace-hitl ask --assignment ID --attempt ID --project ID`.
+- **Transport authorization from trusted grants** (`Lifecycle::GrantsPolicy` + `TrustedFile`): transport uids and the service identity come only from the deployment-owned grants document (same file and traversal trust rules as ace-lab's `GrantResolver`: root-owned, no group/world-writable components, symlink-verified). ace-lab ships the matching `Molecules::HitlAuthorizer` for the lab-side delivery path.
+- **Idempotent terminal receipts**: every consume/cancel commits a durable receipt under the stable per-request lock (lock files live in `locks/` and survive id reuse); retries report the committed outcome instead of failing, conflicting transitions stay classified errors.
+- **OTP exact-operation challenges**: an `otp` request exists only with its non-secret publisher evidence (`{operation, result_ref, input_digest, expires_at}`, bounded to 24h); consumption requires the challenge's authorized operation; duplicate consumes replay the receipt WITHOUT the secret bytes. OTP effects are forbidden (the authorized operation consumes the OTP transiently). The service holds OTP bytes in a bounded, TTL-bound memory vault (`OtpVault::MemoryVault`) — secret bytes persist nowhere, transfer exactly once, and a restart deliberately loses the challenge (prompt again).
+
+### Changed
+- **BREAKING (pre-1.0, ADR-024)**: `ace-hitl ask/deliver/consume/cancel/pending/states/duty` run through the boundary client — the CLI no longer touches shared store files directly, and broker operations no longer require root (the configured transport identity from the grants document does). The admin binding bypass is removed: EVERY request validates against its live attempt. The `LAB_ATTEMPT_ID` environment default is gone (environment is never attempt authority); `--attempt` is required, and binding requires `--assignment` (managed) or `--work` (legacy path, kept until vs2 switches consumers). Answers and store files are service-owned `0600` — requesters receive bytes over the authenticated boundary, not through file ownership. The multi-UID acceptance fixture (`test/edge/lifecycle/`) proves requester isolation, protected ownership, forged-identity rejection, and one-terminal-transition races under real distinct OS accounts (requires root; CI records the run as advisory evidence).
+
+
+## [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,23 @@ 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 authenticated boundary (`--assignment/--attempt/--project` managed binding, `--work` legacy, 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 (configured transport operation through the boundary); executes the declared effect callback (non-OTP kinds)
+- `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` transport projections (pending, public lifecycle records, pending + escalated)
+- `ace-hitl serve` runs the authenticated store boundary service (peer-credential UNIX socket; trusted grants authorize the transport)
+
+Multi-user HITL state (spec 8wq.t.34i) is the PRIVATE state of the
+`ace-hitl serve` boundary: identity comes from kernel peer
+credentials, transport authority from the trusted grants document,
+and OTP secrets are held in service memory only — never in files,
+logs, or projections.
+- `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 +35,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 +68,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,141 @@ 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.
+
+## Scoped Store Boundary (spec 8wq.t.34i)
+
+The relay request store is the PRIVATE state of one authenticated
+boundary service. `ace-hitl serve` owns the store and speaks a bounded
+JSON protocol over a UNIX socket; every client operation
+(`ask`/`deliver`/`consume`/`cancel`/`pending`/`states`/`duty`/`read`)
+runs through the authenticated boundary client — the CLI never touches
+shared store files directly.
+
+Identity is a kernel fact: the service resolves each connection's peer
+uid from the OS (`getpeereid`), and payload fields or environment
+variables can never name a requester. Clients authenticate the
+endpoint back: the socket must be owned by the trusted service uid,
+must not be world-writable, and the connected peer must BE the service
+uid. Authorization facts (service uid, transport uids, per-project
+Captain visibility) come only from the trusted deployment grants
+document — the same file and traversal trust rules as ace-lab
+(default `ACE_HITL_GRANTS_PATH`, `/etc/lab/ace-lab/authorization.yml`).
+
+```bash
+# Deployment (root runs the service under its own account):
+ace-hitl serve                      # ACE_HITL_SOCKET, ACE_HITL_STORE_ROOT,
+                                    # ACE_HITL_GRANTS_PATH override paths
+```
+
+Store layout (all service-owned): `0711` traverse-only root;
+`requests/ answers/ secrets/ effects/ locks/ terminals/` are `0700`;
+`public/` is `0755` with `0440` non-secret projections. There is no
+chmod-to-world-writable mode: requesters receive answer bytes over the
+authenticated connection, never through file ownership.
+
+Roles:
+
+- requester: create, consume and cancel its OWN requests (request
+  facts come back from `ask`/`consume`; the boundary `read` protocol
+  operation is available to library clients);
+- configured transport (grants `hitl.transport_uids` + principals):
+  `deliver`, `pending`, `states`, `duty`;
+- unknown identity is an error, never permission.
+
+Failures are classified end to end: `PermissionError`,
+`BindingError`, `StateError`, `AnswerError`, and `TransportError`
+(unavailable/untrusted boundary, deadline, malformed frame) — transport
+failures are visible and recoverable, and duplicate consume/cancel are
+idempotent (the committed receipt replays; a conflicting transition is
+an error).
+
+## Relay Lifecycle (Generic HITL Request Store)
+
+The generic relay request lifecycle is native to the gem
+(`Ace::Hitl::Lifecycle`; migration spec 8wm.t.y21, scoped by
+8wq.t.34i). Requests never expire on a timer, every terminal
+transition shares one stable per-request lock, and 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.
+
+Managed binding (the default authority):
+
+```bash
+ace-hitl ask "Choose the next scope" \
+  --assignment 8x3abc --attempt a1b2c3 --project ace
+```
+
+The request binds to the exact ACTIVE MANAGED attempt of the calling
+identity, verified through the ace-assign coordinator under the
+assignment exclusion: a stale, ended, replaced, or uncertain attempt
+cannot acquire authority, and the exclusion is HELD across every
+consume/deliver transition so an attempt cannot end between the
+liveness check and the commit. `--work W... --attempt A-...` remains
+the legacy binding until the provider=lab integration (vs2) switches
+consumers; the two authorities are mutually exclusive and
+`--attempt` is always required (environment variables are never
+attempt identity).
+
+Transport side:
+
+```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 and relays it unchanged. OTP
+bytes go to the service's memory vault; plain answers to the
+service-owned `0600` answers file. Liveness is re-verified under the
+lock, and the declared effect callback (non-OTP kinds only) executes:
+exec-style argv (never a shell), `{answer}` substituted once per
+element, optional fullmatch regex gate, bounded timeout, attempts
+logged redacted in the effects log, and one deduped escalation with
+`effect_state: callback-escalated` in the public projection on failure
+(`callback-ok` on success). Duplicate deliveries are idempotent: the
+committed answer is reported without re-running any effect.
+
+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. OTP consumption requires the challenge's
+authorized operation (`--operation <name>`); the secret transfers
+exactly once and a consumed retry replays the receipt WITHOUT the
+bytes. Cancel is the ONLY way to abandon a request, requester-only;
+it records `cancelled_by` and the `reason` in the public projection,
+and late answers/consumes fail closed against the committed receipt.
+
+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 +291,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,13 +12,22 @@ 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 :work, type: :string, desc: "Lab Work id (W...)"
-          option :attempt, type: :string, desc: "Lab Attempt id (A-...); defaults to LAB_ATTEMPT_ID"
+          option :provider, type: :string, desc: "HITL provider adapter (default: ACE_HITL_PROVIDER or lab)"
+          # Managed binding (spec 8wq.t.34i): the request binds to the
+          # exact active managed attempt of the calling identity.
+          option :assignment, type: :string, desc: "Managed assignment id (compact id)"
+          option :kind, type: :string, desc: "Request kind (default: text; otp requires the challenge evidence)"
+          option :"otp-operation", type: :string, desc: "OTP challenge: the ONE authorized operation name"
+          option :"otp-result-ref", type: :string, desc: "OTP challenge: OTP-required publisher result reference"
+          option :"otp-input-digest", type: :string, desc: "OTP challenge: sha256 input digest of the authorized input"
+          option :"otp-expires-at", type: :string, desc: "OTP challenge: expiry as unix seconds (<= 24h ahead)"
+          option :work, type: :string, desc: "Lab Work id (W...) - legacy binding until vs2 switches consumers"
+          option :attempt, type: :string, desc: "Attempt id of the exact active attempt"
           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)"
@@ -32,75 +42,114 @@ module Ace
           option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
 
           def call(question:, **options)
-            effect = {
+            effect = build_effect(options)
+            validate_effect!(effect)
+
+            work, assignment = require_binding!(options)
+            attempt = require_attempt!(options)
+            otp = build_otp_challenge!(options)
+            provider = resolve_provider(options[:provider])
+            ref = capture_ref
+
+            result = provider.ask(
+              question: question,
+              title: options[:title],
+              ref: ref,
+              work: work,
+              assignment: assignment,
+              attempt: attempt,
+              kind: options[:kind] || "text",
+              otp: otp,
+              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"]
             }
-            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?)
+          end
 
-            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
+          def validate_effect!(effect)
+            Atoms::HitlEffectValidator.validate!(**effect)
+          rescue Atoms::HitlEffectValidator::ValidationError => e
+            raise_cli_error(e.message)
+          end
 
-            submitter = Molecules::LabRequestSubmitter.new
-            request_id = submitter.generate_request_id
+          # The binding is authority: exactly one of the managed
+          # assignment binding or the legacy Work binding. An
+          # environment variable never supplies attempt identity
+          # (spec 8wq.t.34i).
+          def require_binding!(options)
+            work = options[:work]
+            assignment = options[:assignment]
+            if work && assignment
+              raise_cli_error("--assignment and --work are mutually exclusive binding authorities")
+            end
+            if work.nil? && assignment.nil?
+              raise_cli_error("--assignment required (managed binding), or --work for the legacy Work binding")
+            end
+            return [work, nil] unless work.nil?
 
-            manager = Ace::Hitl::Organisms::HitlManager.new
-            event = manager.create(
-              options[:title] || question,
-              questions: [question]
-            )
+            [nil, assignment]
+          end
 
-            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
-            )
+          # The OTP challenge evidence is non-secret, structurally
+          # validated store-side; the CLI only assembles it (spec
+          # 8wq.t.34i: no publisher result, no OTP request).
+          def build_otp_challenge!(options)
+            kind = options[:kind] || "text"
+            return nil unless kind == "otp"
+
+            operation = options[:"otp-operation"]
+            result_ref = options[:"otp-result-ref"]
+            input_digest = options[:"otp-input-digest"]
+            expires_at = options[:"otp-expires-at"]
+            missing = %w[--otp-operation --otp-result-ref --otp-input-digest --otp-expires-at]
+              .zip([operation, result_ref, input_digest, expires_at])
+              .select { |_flag, value| value.nil? || value.to_s.strip.empty? }
+              .map(&:first)
+            raise_cli_error("OTP requests require #{missing.join(", ")} (the OTP-required publisher evidence)") unless missing.empty?
+
+            {operation: operation, result_ref: result_ref, input_digest: input_digest, expires_at: expires_at}
+          end
 
-            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"
-              )
+          def require_attempt!(options)
+            attempt = options[:attempt]
+            unless attempt && !attempt.strip.empty?
+              raise_cli_error("--attempt required (the exact active attempt id)")
             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}"
+            attempt
           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?
+          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
 
-            work
+          # 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

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_client.cancel(id, reason: options[:reason] || ""))
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# 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). OTP
+        # answers require the challenge's authorized operation
+        # (spec 8wq.t.34i).
+        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 :operation, type: :string, desc: "Authorized operation (required for OTP challenges)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(id:, **options)
+            emit(lifecycle_client.consume(id, timeout: options[:timeout] || 0, operation: options[:operation]))
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# 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)
+            answer = $stdin.read(Lifecycle::Store::MAX_ANSWER_BYTES + 1).to_s
+            emit(lifecycle_client.deliver(id, answer))
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end