ace-lab 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3799161a4575055b78e316deb18a4fa952fb1d84fa9fb10cd6e5c081a36acee
-  data.tar.gz: dd2d0fa5764e5bce423396e93e4fd1751fddd880649219d6a130306d0ec49667
+  metadata.gz: a7d3d64373a6eaadb24dde7d501cd5c4b8e2ebfb370e054334297fc0796a8c9c
+  data.tar.gz: 98961e2da9d0b7383cb48a3ae3a801b7018a21c8822fa95fde779c94f2ddfb87
 SHA512:
-  metadata.gz: 1556efc67f0fa45a412b40430570355578c7e61000bda7af07982345631f023c3f56c709d2d02a25c3faf84495b510d6fb171a904d8f910e7c336b4b8113cd44
-  data.tar.gz: a78076debb811ce94046ff8cb056648b6455f8dbe30514a5d575ac417bcf98adce21bb42c3f6f712f0d0e2d6d4bbb3c67ba3764dfb9e4138cb6eb17e6dd6a113
+  metadata.gz: fae21d841c34b8ff24586a806778377589a476ea4e824e9716c6ff55700d207fc9a501656fe2d1712c5c8358a29e22a31a2c8fb2cde8713d464e700f6fdea795
+  data.tar.gz: feacdf38956ff9a1c3afe9296e4cc762deba5029ece4dbc6e9d6bd3a1d6e28e825d746e29cd0f52268c39ba5fe4bd5d97a48e93d7a8f901da38ad9225db41ffc

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-16
+
+### Added
+
+- Wire ordinary artifact retention to fresh installed project visibility and the existing exact service or canonical proposal decision; retention does not select an executor or consume publication authorization.
+- Expose ordinary candidate upload, assigned review export/acceptance and canonical merge evidence through retained assignment requests. Compose their proof owner with the existing merge receiver and command executor journal.
+- Expose ordinary driver status, bootstrap, progress, result and exact recovery commands using the selected Assign owner; authenticate coordinator replacement with bounded process-generation observation.
+
+### Changed
+
+- Require an explicit `purpose: command` or `purpose: test` on every installed command-policy entry. Only test commands with exact candidate head/tree and canonical successful execution can authorize merge evidence; previous entries without purpose are refused.
+
+## [0.8.0] - 2026-10-16
+
+### Added
+
+- Compose ordinary Assign, HITL and Forgejo merge under one installed owner and journal, with readiness barriers and fresh native/project admission.
+- Optionally serve existing mTLS HITL beside the ordinary Unix listener under the same canonical owner, journal, proposal policy and one-use OTP vault. Validate the configured project and service identity before either listener starts.
+- Add retained assignment prepare/request clients and bounded canonical worktree observations. Separate stable configuration identity from changing decisions, preserve no-effect settlement after slow provider calls, and clean delivery handler process groups.
+- This source cut enables initial installation; it does not claim autonomous release or installed two-project acceptance.
+
 ## [0.7.0] - 2026-10-16
 
 ### Added

data/docs/usage.md

@@ -121,6 +121,298 @@ Only the original OS caller identity with project visibility can read the
 request. The authoritative state survives loss of the local assignment cache
 because it lives in the separate assignment evidence Git ref.
 
+### `ace-lab service listen --mode ordinary-merge`
+
+The installed ordinary service owns the Assign, HITL and merge endpoints in one
+process. Start it as the configured service account:
+
+```sh
+ace-lab service listen --mode ordinary-merge --project atlas \
+  --config /etc/lab/ace-lab/atlas-receiver.yml
+```
+
+The receiver configuration selects its existing forge, repository, principal and
+merge socket. `/etc/lab/ace-lab/assign-owners.yml` separately selects the canonical
+Assign journal and native execution owner. Both selections must agree with the
+ordinary project mapping in the trusted authorization document. `repo_path` is
+the merge candidate repository; it does not choose the execution journal.
+
+Each project entry in the root-installed assignment document contains:
+
+| Entry | Installed selection |
+|---|---|
+| `service` | Non-root owner UID/GID, assignment socket and private state root |
+| `journal` | Service-owned repository, execution ref and private evidence checkout |
+| `assignment_root`, `lifecycle_root` | Separate private prepared-input and exclusion directories |
+| `runtime_binary`, `native` | Installed executable and exact native server/socket generation from the installation receipt |
+| `worktrees` | Allowed worktree root and Git common directory |
+| `participants` | OS UID/GID/actor, native workspace and supervisor panes |
+| `hitl` | Private store root, distinct socket, dedicated group, trusted grants path and optional installed TLS authority reference |
+
+For example, the `hitl` entry inside an already selected project can be:
+
+```yaml
+hitl:
+  root: /var/lib/lab/assign/atlas/hitl
+  socket_path: /run/lab/assign/atlas/hitl.sock
+  group: atlas-lifecycle
+  grants_path: /etc/lab/ace-lab/authorization.yml
+```
+
+The store must be a separate child of that project's `service.state_root`; the
+installer creates `service.state_root` with mode `0700`, the HITL root with its
+maintained mode `0711`, and socket access before startup. The private parent keeps
+the HITL tree inaccessible to other accounts; Store maintains private request and
+secret subdirectories. Startup and restart validate the same layout.
+`hitl.service_uid` in the grants document must equal the Assign owner UID. Native
+identities come from the installed receipt and live observation, not the project
+configuration cascade. HITL requests, decisions and merge claims use the same
+canonical Assign journal and lifecycle exclusion.
+
+For the existing remote Hermes transport, install its project-scoped mTLS
+authority and add its absolute configuration path to this same `hitl` entry:
+
+```yaml
+  tls_authority: /etc/lab/ace-hitl/atlas-tls.json
+```
+
+The referenced file uses the maintained `ace.hitl.tls.authority/v1` schema and
+credential provisioning layout from `ace-hitl`. Its project must match this
+owner; `service_user` and `service_group` must resolve to the owner's actual UID
+and primary GID. The dedicated Unix control group remains `hitl.group`. Root
+installs the credential references and Incus TCP proxy; callers cannot choose
+them. Invalid ownership, identity, project or TLS material prevents startup.
+
+The TLS listener runs in this same service process and shares its exact HITL
+binding, store, decision policy and in-memory one-time OTP vault. Hermes uses its
+verified project certificate as a remote transport identity; it does not need a
+synthetic Unix transport UID. Keep `transport_uids` empty when no local transport
+is installed. Configure the actual local proposer separately with
+`proposal_uids` and its project grant. A proposer grant never authorizes replies
+or delegates silence-based decisions. Restart the composed service after changing
+its TLS authority or credential selection, retaining the canonical journal.
+
+All selected endpoints must become ready before assignment ingress opens. A
+failed endpoint shuts down the complete owner. A stale assignment endpoint needs
+installer inspection; startup does not remove it or recover merge effects first.
+
+## Ordinary assignment client
+
+`ace-lab assignment` selects the root-installed project owner and uses the
+existing Assign protocol. Assign remains the only accepted execution journal.
+Preparation captures reviewed task context and the existing managed assignment
+graph; it does not start a worker or register accepted work.
+
+```sh
+ace-lab assignment prepare --project atlas --task 8wr.t.abc --pane w1:pS \
+  --output .ace-local/prepared-task
+ace-lab assignment request --project atlas --input .ace-local/prepared-task/request.json
+```
+
+The output directory must not exist. Preparation retains the definition, bundle,
+and registration request with one stable mutation ID. `--dependency-reports FILE`
+selects an explicit JSON array of `{task_id, assignment_id, number}` entries for
+dependency reports. A failed preparation keeps partial files for inspection;
+it never rebuilds an existing directory. In this source checkout use
+`bundle exec ace-lab` because no `bin/ace-lab` binstub is committed.
+
+Every request file has exactly these fields:
+
+```json
+{
+  "version": 1,
+  "project_id": "atlas",
+  "operation": "start_attempt",
+  "mutation_id": "original-start-001",
+  "params": {
+    "assignment_id": "assignment-id",
+    "attempt_id": "attempt-id",
+    "expected_generation": 0,
+    "scope": "010",
+    "head": "0123456789012345678901234567890123456789",
+    "pane": "w1:p2"
+  },
+  "parts": []
+}
+```
+
+Use actual retained IDs, scope, head and native pane. The actual worker executes
+its start request: the owner verifies caller ancestry, live process and checkout.
+A supervisor cannot impersonate another pane by changing `pane`. A new terminal
+or prompt acknowledgement alone is not running proof.
+
+| Operation | `params` beyond `assignment_id` | Transfer / authority |
+|---|---|---|
+| `register_assignment` | Generated by prepare | Exact prepared bundle; supervisor |
+| `registration_status` | None | Read; `mutation_id: null` |
+| `start_attempt` | `attempt_id`, `expected_generation: 0`, `scope`, `head`, `pane` | Actual worker start |
+| `assignment_snapshot` | `attempt_id` (or null), `kind: queue` or `prepared_work` | Download; `mutation_id: null` |
+| `queue_start` | `attempt_id`, `expected_generation`, `pane`, `step` (or null for next) | Original worker |
+| `queue_finish` | Same as queue_start | One UTF-8 report part |
+| `queue_fail` | `attempt_id`, `expected_generation`, `pane`, `message` | Original worker; unfinished work stays failed |
+| `submit_result` | `attempt_id`, `expected_generation`, `pane`, `head`, `receipt_sha256` | Receipt first, then its ordered artifacts; original worker |
+| `result_status` | `attempt_id` | Read; `mutation_id: null` |
+| `result_snapshot` | `attempt_id`, `result_id` | Canonical receipt/artifacts download; `mutation_id: null` |
+| `finish` | `attempt_id`, `expected_generation`, `pane`, `head`, `result_id`, `receipt_digest` | Supervisor accepts exact submitted result after settlement |
+
+Upload `parts` are ordered `{file, bytes, sha256}` entries. Relative files resolve
+beside the retained request. Changed, oversized or symlinked inputs refuse before
+connection. Requesters never supply a wire `transfer` descriptor. Downloads require
+`--output NEW_DIRECTORY`; numbered byte files and `response.json` are private
+projections of the authenticated reply, not another execution store. For queue
+snapshots, the first byte file contains the current step instructions and reports
+as JSON; prepared-work snapshots contain the original Git bundle.
+
+Retain each request and its exact parts before invoking it. On response loss,
+inspect `registration_status` or `result_status` and reuse the same original
+mutation when replay is appropriate. Never refresh its generation, replace its
+bytes, or create a second worker because a reply was lost. Queue completion and
+`submit_result` keep the attempt running; only the canonical accepted `finish`
+reply proves terminal completion. Unknown effect or Inbox settlement refuses it.
+
+These commands do not silently route to a local `ace-assign` cache. Missing or
+changed installed owner selection is an explicit failure. Native wake consumers
+must read the same canonical status and adopt its original attempt/result IDs.
+Changed owner selection refuses new admission and dispatch until a controlled
+restart. Existing canonical receipts remain the source for reconciliation.
+
+## Ordinary candidate, review and merge evidence
+
+Keep the real delivery attempt running through review, test execution and merge.
+Finish it only after settlement. A completed coder attempt can seed a new real
+registered delivery attempt; never reopen its old authority.
+
+The existing `assignment request --input request.json` interface also supports:
+
+| Operation | Params in addition to assignment_id/attempt_id/head/candidate_generation | Authority / transfer |
+|---|---|---|
+| `submit_candidate` | `pane`, `expected_generation` | Original worker; one complete Git bundle; candidate_generation is the previous generation (0 initially) |
+| `assign_review` | `pane`, `expected_generation`, `reviewer_assignment_id`, `reviewer_attempt_id` | Current canonical supervisor selects an already started independent reviewer |
+| `export_candidate` | `pane`, `review_id` | Assigned reviewer; null mutation; `--output NEW_DIRECTORY` downloads canonical bundle |
+| `accept_review` | `pane`, `expected_generation`, `review_id`, `receipt_sha256` | Assigned reviewer uploads exact receipt followed by its ordered report artifacts |
+| `cancel_review` | `pane`, `expected_generation`, `review_id` | Current supervisor revokes that exact review |
+| `review_status` | None | Null mutation; revalidates accepted original receipt and artifacts |
+| `merge_evidence` | `test_execution_ids` (nonempty array) | Null mutation; projects exact accepted review and canonical executed-test references |
+
+First submit the candidate, retaining its returned head, tree and new generation.
+Prepare/register/start a separate review assignment through the ordinary native
+entry. Its agent must have a different actual process generation, session UUID
+and pane. The supervisor assigns that exact reviewer assignment/attempt at its
+honestly observed starting base. Export gives the assigned agent canonical candidate
+bytes; it then materializes/checks out the candidate. Receipt acceptance requires
+that exact candidate HEAD and the unchanged original native reviewer binding. A receipt uses the delivery attempt's identifiers,
+scope and actual producer; its `review.reviewer.actor` is the real reviewer's
+account. The owner derives independence from authenticated native origins, so
+shared-account agents do not need invented actor aliases.
+
+`accept_review` retains the original receipt and up to 15 report artifacts in
+CanonicalEvidence, verifies their exact digests, and returns the accepted review
+ID/digest. The receipt declares operation review, succeeded, approved at the exact
+candidate head, and executed review checks. These review checks are not test
+execution authority. Missing/corrupt reports, a different caller, terminal delivery
+attempt, changed head/generation or cancellation refuse. Retrying the exact
+accepted mutation cannot accept a second review; changed bytes under that mutation
+refuse. This first ingress accepts direct independent review of the exact candidate
+generation. Campaign receipts and accepted-head carry are deliberately unavailable
+until the existing ace-review campaign/assessment owner is connected; a head change
+currently refuses prior approval. This is a remaining delivery capability, not the
+final policy of requiring a full independent review after every SHA change.
+
+Execute the project's root-selected test command through the existing command
+transport. Only an explicit `purpose: test` definition with exact immutable
+candidate head/tree, root-witnessed child, and canonical exit0/no signal can supply
+test evidence. `merge_evidence` resolves those execution IDs and returns
+`review_evidence` and `test_evidence` for the fixed merge request. Copy those exact
+projections into the retained request before obtaining its digest-bound decision.
+Plain worker check strings or generic allowed commands are not substitutes.
+
+The sole owner revalidates evidence in the merge admission CAS and before each
+Forge effect. Assignment exclusion prevents candidate changes, review cancellation
+or finish racing an executing merge. Policy revocation or missing canonical bytes
+refuses without dispatch. Existing unknown outcomes retain their original merge
+reference and require reconciliation.
+
+The dynamic candidate-to-immutable-command-view binding and installed two-worker
+acceptance remain separate required gates. Static source fixtures do not authorize
+per-PR administrative head/path edits or claim installed autonomous merging.
+
+## Ordinary driver and supervisor recovery
+
+`ace-overseer ordinary --operation prepare` retains one context per fresh worker.
+From that worker's native tool process, drive only the installed owner:
+
+```sh
+ace-lab assignment drive --project atlas --context /private/work/context.json --operation status
+ace-lab assignment drive --project atlas --context /private/work/context.json --operation start
+ace-lab assignment drive --project atlas --context /private/work/context.json --operation bootstrap --output /private/work/accepted-context
+ace-lab assignment drive --project atlas --context /private/work/context.json --operation next
+ace-lab assignment drive --project atlas --context /private/work/context.json --operation step-start --generation 1 --step 010.01.01
+ace-lab assignment drive --project atlas --context /private/work/context.json --operation step-finish --generation 2 --step 010.01.01 --report /private/work/check.md
+```
+
+Use returned generations and actual step numbers, not the illustrative values.
+`HERDR_PANE` supplies the caller pane unless `--pane` is explicit; the selected
+owner authenticates actual native ancestry independently. `bootstrap` returns
+accepted context paths, byte counts, SHA256 values and manifest digest. `next`
+reads the canonical queue including reports and returns current/next instructions.
+`fail --generation N --message REASON` records a failed scope; it never fabricates
+successful completion. The workflow `wfi://assign/drive` selects this protocol
+before local assignment resolution when `--ordinary`/the ordinary environment
+is present.
+
+Submit one bounded execution receipt JSON with the following fields, using
+actual observed values (no placeholders in submitted evidence):
+
+```json
+{
+  "assignment_id": "original-assignment", "attempt_id": "original-attempt",
+  "project_id": "atlas", "scope": "010.01", "operation": "check",
+  "producer": {"actor": "actual-user", "role": "worker", "runtime": "herdr"},
+  "head": "0123456789012345678901234567890123456789",
+  "verdict": "succeeded", "checks": [{"name": "tests", "verdict": "passed"}],
+  "artifacts": [{"path": "check.md", "sha256": "actual-64-hex-artifact-digest"}]
+}
+```
+
+The producer comes from canonical start status; checks and artifacts must describe
+executed work. Run `--operation result --generation N --receipt receipt.json
+--artifact check.md` with files in receipt order. The existing receipt verifier
+and canonical import validate attribution, evidence and exact bytes. A result
+submission leaves the worker running until its canonical supervisor executes
+`--operation adopt` and receives terminal status. Keep the actual worker process
+and checkout alive until that acceptance; a terminal pane without the required
+native binding is insufficient.
+
+Mutations retain their exact request and transferred bytes under the original
+context directory before sending. A lost response is recovered with canonical
+`status`/`next`, then `--operation replay --request /original/requests/.../request.json`.
+Never update an existing request's generation, mutation ID or bytes to force a
+retry. The requester directory is not an accepted-state store. The result hint
+file is ignored by canonical reads/adoption, including when forged or stale.
+Inbound Inbox settlement is not provisioned by this driver; nonempty references
+still require the separately selected existing Inbox owner and fail closed otherwise.
+
+A replacement coordinator reads `--operation supervisor`, then from its actual
+installed native supervisor placement uses:
+
+```sh
+ace-lab assignment drive --project atlas --context /private/work/context.json \
+  --operation adopt-supervisor --generation 1 --previous-binding-sha256 EXACT_OLD_DIGEST
+```
+
+The definition chain records old→new bindings under its original generation CAS.
+Only a positively ended old generation (kernel process absence or a different
+exact process birth) permits adoption; live, inaccessible, remote-host and unknown
+identities refuse. A lost adoption response reuses its original retained request.
+No worker is re-registered or relaunched. Existing pending results, uncertain
+operations, attempts and request IDs remain unchanged. Finish, including replay,
+checks the current canonical supervisor binding and rejects the displaced one.
+
+Wire additions are `supervisor_status` (assignment only, null mutation), and
+`adopt_supervisor` (assignment, actual pane, expected definition generation,
+previous_binding_sha256; original mutation). They use the same installed owner,
+project policy, journal and lifecycle exclusion as ordinary execution.
+
 ## Error semantics
 
 Errors are one deterministic JSON document on stdout plus a non-zero exit.
@@ -292,3 +584,54 @@ Handlers retain the fixed closed environment and 30-second execution deadline, w
 The existing protected receiver exposes `recover_no_effect(binding:, input_bytes:, mutation_id:, expected_generation:)`. Supply the original assignment/attempt/candidate/head/request binding, original structured input, stable mutation ID and unchanged original positive authority generation. The receiver snapshots those inputs, authenticates canonical status and input before any settled return, and adopts an already accepted current challenge without claiming again. A needed claim uses the supplied generation unchanged. Lost acknowledgements remain uncertain; status retry never repeats the original effect.
 
 Trusted operation configuration must provide a distinct fixed `no_effect_argv` for the original project/service/executor. Inspection may proceed after the effect lease expires, but it never renews effect permission or selects normal effect argv. The selected inspector must produce operation-specific original target/handler/writer observations and existing strict challenge-bound artifacts; only the authority's canonical import can establish `failed-settled`. This source API and controlled composition do not deliver the outstanding gad.b inspector or installed acceptance.
+
+## Project commands
+
+`ace-lab run --project ace -- /usr/bin/id` invokes one exact installed command
+policy. `--as publisher` selects a permitted executor; repeated `--service NAME`
+replaces the configured default set. Every service and the entire combination
+must be granted. Arguments after `--` remain literal, including command options.
+No shell is added. Duplicate `--project`/`--as` or empty argv are usage errors.
+
+The root-owned `/etc/lab/ace-lab/project-commands.yml` is the only command-policy
+source. Project preferences and caller environment cannot create grants. Its
+version1 project entries contain `launcher`, `default_executor`, `default_services`,
+`executors`, `services`, `commands`, and `grants`. Executors declare UID/GID/groups,
+HOME/cwd/PATH and nonsecret environment; services declare nonsecret environment
+and secret references; commands bind exact argv, executable SHA256, source
+head/tree and required `purpose: command` or `purpose: test`. Test purpose requires
+nonnull source head/tree and is never inferred from executable name or exit0.
+With `purpose: command`, source head/tree may both be null for a non-Git probe;
+Git source uses two exact object IDs. Grants bind requester kind/UID, command, executor
+and the exact service combination. Accepted code/cwd must be root-owned and
+unwritable by the executor. Missing or changed context refuses execution.
+
+An operator grant authorizes an OS account. Agents sharing that account share
+its operator authority; an environment hint does not prove human presence.
+Agent-selected invocation additionally checks actual current native ancestry.
+Separate identities are required when operator authority must exclude agents.
+
+The CLI retains an invocation under `.ace-local/lab-commands/` and prints its
+execution reference before contacting the canonical Assign owner. Inspect it with
+`ace-lab run-status --project ace --reference REF`. Inspection starts no command
+and remains available to the original requester account after a grant is revoked.
+After response loss, inspect that original reference before requesting new work.
+An existing claim or a replayed acknowledgment cannot release another child.
+
+Interactive terminals preserve no-echo input, dimensions and signals. Pipe mode
+preserves EOF, separate stdout/stderr and actual exit/signal status. Socket closure
+without the authenticated result is uncertainty. Root launch/exit observations
+remain separate from accepted product delivery evidence; exit0 alone does not
+prove publication, installation or completed delivery.
+
+This implementation slice admits nonsecret commands. A nonempty selected secret
+reference set is explicitly refused before claim until the secret execution
+capability is supplied. Publication also requires the publisher's writable
+artifact/cache destination outside immutable accepted source, or retained exact
+artifacts. These remaining joins and installed acceptance are tracked by ei9 .5;
+source/kernel fixture success does not assert installed autonomous publication.
+
+In interactive mode, input EOF sends the terminal's conventional Ctrl-D byte; a
+program that changes its terminal to raw mode may interpret that byte itself.
+Noninteractive EOF closes the command input pipe. The dedicated Linux helper owns
+and reaps detached command descendants as well as the original process group.

data/lib/ace/lab/cli/commands/assignment.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "../../organisms/ordinary_assignment_client"
+require "ace/assign/organisms/ordinary_driver"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        module Assignment
+          class Drive < Ace::Support::Cli::Command
+            desc "Drive or inspect one original ordinary execution through its installed owner"
+            option :project, required: true, desc: "Installed project ID; never inferred from local Assign"
+            option :context, required: true, desc: "Original retained ordinary context.json"
+            option :operation, required: true, desc: "status, supervisor, adopt-supervisor, bootstrap, next, start, step-start, step-finish, fail, result, adopt, replay"
+            option :previous_binding_sha256, desc: "Exact canonical old supervisor binding digest for adoption"
+            option :output, desc: "New private directory for accepted bootstrap context"
+            option :pane, desc: "Actual native caller pane (defaults to HERDR_PANE)"
+            option :generation, type: :integer, desc: "Exact canonical generation observed before mutation"
+            option :step, desc: "Exact queue step within the retained scope"
+            option :report, desc: "Executed step's bounded UTF-8 report file"
+            option :message, desc: "Failure reason"
+            option :receipt, desc: "Attributable execution receipt JSON"
+            option :artifact, type: :array, desc: "Artifact files in receipt order"
+            option :request, desc: "Original mutation request to replay after reconciliation"
+
+            def call(project:, context:, operation:, **options)
+              transport = Organisms::OrdinaryAssignmentClient.new(project: project)
+              driver = Ace::Assign::Organisms::OrdinaryDriver.new(path: context, project: project, transport: transport)
+              pane = options[:pane] || ENV["HERDR_PANE"]
+              result = case operation
+              when "status" then driver.status
+              when "supervisor" then driver.supervisor
+              when "adopt-supervisor"
+                driver.adopt_supervisor(pane: pane, generation: options.fetch(:generation),
+                  previous_binding_sha256: options.fetch(:previous_binding_sha256))
+              when "bootstrap" then driver.bootstrap(output: options.fetch(:output))
+              when "next" then driver.queue
+              when "start" then driver.start(pane: pane)
+              when "step-start", "step-finish", "fail"
+                driver.progress(operation: {"step-start" => "queue_start", "step-finish" => "queue_finish", "fail" => "queue_fail"}.fetch(operation),
+                  pane: pane, generation: options.fetch(:generation), step: options[:step],
+                  report: operation == "step-finish" ? options.fetch(:report) : nil,
+                  message: operation == "fail" ? options.fetch(:message) : nil)
+              when "result"
+                driver.submit(pane: pane, generation: options.fetch(:generation), receipt: options.fetch(:receipt), artifacts: options[:artifact] || [])
+              when "adopt" then driver.adopt(pane: pane)
+              when "replay" then driver.replay(input: options.fetch(:request))
+              else raise ArgumentError, "unknown ordinary driver operation"
+              end
+              puts JSON.generate(result)
+            rescue ArgumentError, KeyError, SystemCallError, Ace::Assign::Error, Ace::Runtime::Error, Ace::Lab::Error => error
+              raise Ace::Support::Cli::Error, "ordinary execution unavailable: #{error.message}; inspect the original context with --operation status"
+            end
+          end
+
+          class Prepare < Ace::Support::Cli::Command
+            desc "Retain reviewed task input for ordinary Assign registration"
+            option :project, required: true, desc: "Installed project ID"
+            option :task, required: true, desc: "Reviewed leaf task ID"
+            option :pane, required: true, desc: "Actual supervisor pane for registration"
+            option :output, required: true, desc: "New private directory for retained input"
+            option :dependency_reports, desc: "JSON array of explicit dependency report selections"
+
+            def call(project:, task:, pane:, output:, **options)
+              reports = options[:dependency_reports] ? JSON.parse(Ace::Assign::Authority::RetainedInput.read_file(
+                options.fetch(:dependency_reports), 65_536), allow_duplicate_key: false, create_additions: false, max_nesting: 16) : []
+              puts JSON.generate(Organisms::OrdinaryAssignmentClient.prepare(project: project, task: task,
+                pane: pane, output: output, dependency_reports: reports))
+            rescue JSON::ParserError, ArgumentError, KeyError, SystemCallError, Ace::Assign::Error, Ace::Runtime::Error => error
+              raise Ace::Support::Cli::Error, "ordinary preparation incomplete: #{error.message}; retain existing files"
+            end
+          end
+
+          class Request < Ace::Support::Cli::Command
+            desc "Send one retained operation to the installed ordinary Assign owner"
+            option :project, required: true, desc: "Installed project ID"
+            option :input, required: true, desc: "Retained request JSON with original mutation and part digests"
+            option :output, desc: "New private directory for a canonical snapshot download"
+
+            def call(project:, input:, **options)
+              service = Organisms::OrdinaryAssignmentClient.new(project: project)
+              puts JSON.generate(service.request(input: input, output: options[:output]))
+            rescue ArgumentError, KeyError, SystemCallError, Ace::Assign::Error, Ace::Runtime::Error, Ace::Lab::Error => error
+              raise Ace::Support::Cli::Error, "ordinary assignment unavailable: #{error.message}; retain the original request; inspect status before new work"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/command_execute.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+require_relative "../../organisms/command_executor"
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class CommandExecute < Ace::Support::Cli::Command
+          desc "Execute one admitted command for the installed root launcher"
+          option :project, required: true
+          option :fd, type: :integer, required: true
+          def call(project:, fd:, **)
+            raise SecurityError unless Process.uid.zero? && Process.euid.zero? && fd >= 3
+            bytes = $stdin.read(16_385)
+            raise ArgumentError if bytes.bytesize > 16_384
+            request = JSON.parse(bytes, allow_duplicate_key: false, create_additions: false, max_nesting: 16)
+            socket = UNIXSocket.for_fd(fd)
+            Organisms::CommandExecutor.new(project: project).run(socket: socket, request: request)
+            0 # Child status belongs to the framed result, not helper transport.
+          rescue StandardError, SecurityError
+            raise Ace::Support::Cli::Error, "command uncertain; inspect original execution reference"
+          ensure
+            socket&.close unless socket&.closed?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/run.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+require "optparse"
+require_relative "../../organisms/command_run_client"
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Run < Ace::Support::Cli::Command
+          desc "Run one explicitly authorized project command"
+          option :project, required: true, desc: "Installed project ID"
+          option :as, desc: "Configured permitted executor"
+          option :service, repeat: true, desc: "Replace default services with this complete set"
+          argument :argv, type: :array, desc: "Literal command argv after --"
+
+          def self.parse(args)
+            separator = args.index("--")
+            raise ArgumentError, "run requires -- followed by literal command argv" unless separator && separator < args.size - 1
+            switches, argv = args.first(separator), args.drop(separator + 1)
+            options = {executor: nil, services: nil}
+            seen = {}
+            parser = OptionParser.new
+            %w[project as].each do |name|
+              parser.on("--#{name} VALUE") do |value|
+                raise ArgumentError, "duplicate --#{name}" if seen[name]
+                seen[name] = true
+                options[name == "as" ? :executor : :project] = value
+              end
+            end
+            parser.on("--service VALUE") { |value| (options[:services] ||= []) << value }
+            parser.parse!(switches)
+            raise ArgumentError, "run requires one --project and no extra options" unless seen["project"] && switches.empty?
+            options.merge(argv: argv)
+          rescue OptionParser::ParseError, ArgumentError
+            raise Ace::Support::Cli::Error, "usage_error: run requires unique project/executor options and literal argv after --"
+          end
+
+          def self.invoke(args)
+            options = parse(args)
+            project = options.delete(:project)
+            client = Organisms::CommandRunClient.new(project: project)
+            begin
+              client.run(**options, pane: ENV["HERDR_PANE_ID"])
+            rescue StandardError, SecurityError
+              # Once admission may have crossed the owner boundary, even a
+              # malformed stream is uncertainty, never a fresh usage refusal.
+              raise Ace::Support::Cli::Error, "command_uncertain: inspect the original execution reference before new work"
+            end
+          rescue Ace::Lab::InvalidConfigurationError
+            raise Ace::Support::Cli::Error, "invalid_command_context: installed project selection is unavailable"
+          end
+        end
+        class RunStatus < Ace::Support::Cli::Command
+          desc "Inspect an original command execution without running it"
+          option :project, required: true
+          option :reference, required: true
+          def call(project:, reference:, **)
+            puts JSON.generate(Organisms::CommandRunClient.new(project: project).status(reference))
+          rescue StandardError, SecurityError
+            raise Ace::Support::Cli::Error, "command_status_unavailable: preserve original execution reference"
+          end
+        end
+      end
+    end
+  end
+end