ace-lab 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb4f48b950b3a32e27a457e36af99148a65e8a95cdbbc55a1586e4f9f2d2abd9
-  data.tar.gz: 361f1a4f8b0167365fe8fee52c7e78047c0f31a9d8f1b1dd9644de79e13b540f
+  metadata.gz: a7d3d64373a6eaadb24dde7d501cd5c4b8e2ebfb370e054334297fc0796a8c9c
+  data.tar.gz: 98961e2da9d0b7383cb48a3ae3a801b7018a21c8822fa95fde779c94f2ddfb87
 SHA512:
-  metadata.gz: c556ae2dfb4f3137d2e3a45473287c385cc265b2da115aa9db6a2fe42b1e1e61b5a4e6839d98b4b76ce093ace09032c1e8795373f41b33987c0e0127ba1e084a
-  data.tar.gz: 7d470523a46606f392ea1ed22cffd708861c5e635c34ff9d1321ff64d542ef45f30e5cc763ac422ec28a9add7c7ef6a26e8fb705d01f25cdfba291746c19c520
+  metadata.gz: fae21d841c34b8ff24586a806778377589a476ea4e824e9716c6ff55700d207fc9a501656fe2d1712c5c8358a29e22a31a2c8fb2cde8713d464e700f6fdea795
+  data.tar.gz: feacdf38956ff9a1c3afe9296e4cc762deba5029ece4dbc6e9d6bd3a1d6e28e825d746e29cd0f52268c39ba5fe4bd5d97a48e93d7a8f901da38ad9225db41ffc

data/CHANGELOG.md

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

data/docs/usage.md

@@ -276,6 +276,143 @@ 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.
@@ -447,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

@@ -1,12 +1,59 @@
 # 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"
@@ -16,7 +63,7 @@ module Ace
             option :dependency_reports, desc: "JSON array of explicit dependency report selections"
 
             def call(project:, task:, pane:, output:, **options)
-              reports = options[:dependency_reports] ? JSON.parse(Organisms::OrdinaryAssignmentClient.read_file(
+              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))

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

data/lib/ace/lab/cli.rb

@@ -10,6 +10,8 @@ require_relative "cli/commands/resolve"
 require_relative "cli/commands/route"
 require_relative "cli/commands/service"
 require_relative "cli/commands/assignment"
+require_relative "cli/commands/command_execute"
+require_relative "cli/commands/run"
 
 module Ace
   module Lab
@@ -21,6 +23,8 @@ module Ace
 
       # Application commands with descriptions (for help output)
       REGISTERED_COMMANDS = [
+        ["run", "Run one explicitly authorized project command"],
+        ["run-status", "Inspect an original command execution without running it"],
         ["projects", "List lab projects visible to the verified caller"],
         ["agents", "List lab agents in a project by stable ID"],
         ["services", "List lab services in a project by stable ID"],
@@ -30,6 +34,7 @@ module Ace
         ["service status", "Read a service request outcome"],
         ["service listen", "Serve the ordinary fixed merge receiver on its configured socket"],
         ["assignment prepare", "Retain reviewed task input for ordinary Assign registration"],
+        ["assignment drive", "Drive one original execution through the installed ordinary owner"],
         ["assignment request", "Send one retained operation to the installed ordinary Assign owner"]
       ].freeze
 
@@ -45,6 +50,7 @@ module Ace
       # @param args [Array<String>] Command-line arguments
       # @return [Integer] Exit code (0 for success, non-zero for failure)
       def self.start(args)
+        return CLI::Commands::Run.invoke(args.drop(1)) if args.first == "run" && !(args.take(args.index("--") || args.size).include?("--help") || args.take(args.index("--") || args.size).include?("-h"))
         Ace::Support::Cli::Runner.new(self).call(args: args)
       end
 
@@ -57,7 +63,11 @@ module Ace
       register "service request", CLI::Commands::Service::Request.new
       register "service status", CLI::Commands::Service::Status.new
       register "service listen", CLI::Commands::Service::Listen.new
+      register "run", CLI::Commands::Run.new
+      register "run-status", CLI::Commands::RunStatus.new
+      register "command execute", CLI::Commands::CommandExecute.new
       register "assignment prepare", CLI::Commands::Assignment::Prepare.new
+      register "assignment drive", CLI::Commands::Assignment::Drive.new
       register "assignment request", CLI::Commands::Assignment::Request.new
 
       # Register version command

data/lib/ace/lab/molecules/command_owner_admission.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "find"
+require "ace/assign/authority/command_execution"
+require "ace/herdr/molecules/bounded_observation"
+require "ace/runtime/molecules/process_identity"
+require_relative "command_policy"
+
+module Ace
+  module Lab
+    module Molecules
+      # Adds the project-command principals to the same installed listener.
+      # Root launch facts do not impersonate a participant/native agent.
+      class CommandOwnerAdmission
+        def initialize(base:, project:, policy_loader: nil)
+          @base, @project = base, project
+          @policy_loader = policy_loader || -> { CommandPolicy.load(project: @project) }
+          @peer = Ace::Assign::Authority::OrdinaryPeer.new
+        end
+        def service = @base.service
+        def verify_listener! = @base.verify_listener!
+        def peer(socket, deadline:) = @base.peer(socket, deadline: deadline)
+        def authorize!(request:, peer:, deadline:)
+          return @base.authorize!(request: request, peer: peer, deadline: deadline) unless Ace::Assign::Authority::CommandExecution::OPERATIONS.include?(request["operation"])
+          raise Ace::Assign::AttemptErrors::UnauthorizedIdentity unless request["project_id"] == @project
+          if %w[command_claim command_bind command_complete].include?(request["operation"])
+            command_launcher!(peer: peer, deadline: deadline)
+          elsif request["operation"] == "command_status"
+            @peer.live!(peer, deadline: deadline) # Handler checks original requester before exposing data.
+          else
+            command_reader!(peer: peer, deadline: deadline)
+          end
+          :worker
+        end
+
+        def command_reader!(peer:, deadline:, definition: nil)
+          @peer.live!(peer, deadline: deadline)
+          return true if peer["uid"] == 0 && command_launcher!(peer: peer, deadline: deadline)
+          if definition
+            # Inspection never grants a second effect. Original requester UID
+            # retains reconciliation after policy revocation or process restart.
+            unless definition.dig("requester", "uid") == peer.fetch("uid")
+              raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "command reference belongs to another requester"
+            end
+            return true
+          end
+          # Authorize visibility through the same closed selection machinery;
+          # absence of any configured grant is a refusal, not native inference.
+          document = policy
+          document.reader!(peer.fetch("uid"))
+        end
+
+        def command_request!(selection:, peer:, deadline:)
+          @peer.live!(peer, deadline: deadline)
+          selected = policy.select(selection: selection, peer: peer)
+          if selected.fetch("requester_kind") == "agent"
+            selected["native_binding"] = @base.identity!(peer: peer, pane: selection.fetch("pane"), deadline: deadline).runtime_binding
+          end
+          verify_context!(selected, deadline)
+          selected
+        end
+
+        # Historical execution can outlive its requester. Current root policy
+        # and immutable source/executable must still grant this exact TEST
+        # command; requester liveness does not invent a new execution.
+        def command_test_evidence!(definition:, deadline:)
+          unless definition["purpose"] == "test" && definition.dig("source", "head") && definition.dig("source", "tree") &&
+              policy.select(selection: definition.fetch("selection"), peer: definition.fetch("requester")) == definition.except("native_binding")
+            raise Ace::Assign::AttemptErrors::ReceiptRejected, "executed test command policy was revoked or changed"
+          end
+          verify_context!(definition, deadline)
+        rescue SecurityError, Ace::Lab::InvalidConfigurationError
+          raise Ace::Assign::AttemptErrors::ReceiptRejected, "executed test command policy or source is unavailable"
+        end
+
+        def command_launcher!(peer:, deadline:)
+          @peer.live!(peer, deadline: deadline)
+          expected = JSON.parse(GrantResolver.read_verified(policy.launcher.fetch("identity_path")) || "null")
+          unless expected.is_a?(Hash) && expected.keys.sort == %w[identity schema] &&
+              expected["schema"] == "labd-command-launcher/v1" && expected["identity"].is_a?(Hash) &&
+              expected["identity"]["uid"] == 0 && peer["uid"] == 0
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "installed command launcher differs"
+          end
+          target = expected.fetch("identity")
+          @peer.live!(target, deadline: deadline)
+          cursor = peer
+          64.times do
+            return target if cursor.slice("pid", "uid", "host", "started_at") == target.slice("pid", "uid", "host", "started_at")
+            break unless RUBY_PLATFORM.include?("linux") && cursor["uid"] == 0
+            stat = File.read("/proc/#{cursor.fetch('pid')}/stat")
+            parent = Integer(stat[(stat.rindex(")") + 2)..].split.fetch(1), 10)
+            break if parent <= 1
+            @peer.live!(cursor, deadline: deadline)
+            identity = Ace::Runtime::Molecules::ProcessIdentity.new(executor:
+              Ace::Herdr::Molecules::BoundedObservation.new(deadline: deadline)).capture(parent)
+            break unless identity
+            cursor = identity
+          end
+          raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "command helper is outside installed launcher ancestry"
+        rescue JSON::ParserError, SystemCallError, IndexError, ArgumentError
+          raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "installed command launcher is unavailable"
+        end
+
+        def command_claim!(definition:, caller:, launcher:, deadline:)
+          command_launcher!(peer: launcher, deadline: deadline)
+          unless caller == definition.fetch("requester") && command_request!(selection: definition.fetch("selection"), peer: caller, deadline: deadline) == definition
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "command requester or policy changed"
+          end
+          true
+        end
+
+        def command_child!(definition:, child:, launcher:, deadline:)
+          command_launcher!(peer: launcher, deadline: deadline)
+          unless command_request!(selection: definition.fetch("selection"), peer: definition.fetch("requester"), deadline: deadline) == definition
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "command admission changed before exec"
+          end
+          # The authenticated root daemon witnesses cwd/identity after dropping
+          # the gated child. Owner independently captures its kernel generation.
+          keys = %w[pid uid gid groups started_at host cwd process_group no_new_privs capabilities]
+          actual = Ace::Runtime::Molecules::ProcessIdentity.new(executor:
+            Ace::Herdr::Molecules::BoundedObservation.new(deadline: deadline)).capture(child["pid"])
+          executor = definition.fetch("executor")
+          unless child.is_a?(Hash) && child.keys.sort == keys.sort && actual &&
+              actual == child.slice("pid", "uid", "started_at", "host") &&
+              child["no_new_privs"] == 1 && child["capabilities"].is_a?(Hash) &&
+              child["capabilities"].keys.sort == %w[CapAmb CapEff CapInh CapPrm] &&
+              child["capabilities"].values.all? { |value| value.is_a?(String) && value.match?(/\A0{16}\z/) } &&
+              child.values_at("uid", "gid", "groups", "cwd", "process_group") ==
+                [executor.fetch("uid"), executor.fetch("gid"), executor.fetch("groups"), executor.fetch("cwd"), child.fetch("pid")]
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "gated command child differs"
+          end
+          {"kernel_identity" => actual, "root_witness" => child, "witnessed_by" => launcher}
+        end
+
+        private
+
+        def policy = @policy_loader.call
+
+        def verify_context!(definition, deadline)
+          executor = definition.fetch("executor")
+          cwd = executor.fetch("cwd")
+          wire = Ace::Runtime::Molecules::ProtectedSocket
+          wire.root_path!(cwd, directory: true)
+          executor.fetch("path").each { |entry| GrantResolver.trusted_directory!(entry) }
+          home = executor.fetch("home")
+          GrantResolver.trusted_directory!(home) if File.exist?(home) || File.symlink?(home)
+          count = 0
+          Find.find(cwd) do |path|
+            raise InvalidConfigurationError, "command source exceeds verification bound" if (count += 1) > 20_000 || Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            stat = File.lstat(path)
+            unless stat.uid.zero? && (stat.mode & 0o022).zero? && !stat.symlink? && (stat.file? || stat.directory?)
+              raise InvalidConfigurationError, "command source must be an immutable installed view"
+            end
+          end
+          executable = File.expand_path(definition.fetch("argv").first, cwd)
+          raise InvalidConfigurationError, "command executable exceeds verification bound" if File.size(executable) > 64 * 1024 * 1024
+          bytes = GrantResolver.read_verified(executable)
+          unless bytes && File.executable?(executable) && Digest::SHA256.hexdigest(bytes) == definition.fetch("executable_sha256")
+            raise InvalidConfigurationError, "command executable differs"
+          end
+          source = definition.fetch("source")
+          if source.fetch("head")
+            result = Ace::Herdr::Molecules::BoundedProcess.call(["/usr/bin/git", "-c", "safe.directory=#{cwd}",
+              "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "rev-parse", "HEAD", "HEAD^{tree}"],
+              environment: Ace::Assign::Molecules::InstalledJournalRead::ENVIRONMENT, chdir: cwd,
+              stdin_data: "", timeout_s: deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), output_limit: 1024, cleanup_group: true)
+            unless result.status.success? && result.stdout.lines.map(&:strip) == source.values_at("head", "tree")
+              raise InvalidConfigurationError, "command accepted source differs"
+            end
+            clean = Ace::Herdr::Molecules::BoundedProcess.call(["/usr/bin/git", "-c", "safe.directory=#{cwd}",
+              "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+              environment: Ace::Assign::Molecules::InstalledJournalRead::ENVIRONMENT, chdir: cwd,
+              stdin_data: "", timeout_s: deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), output_limit: 65_536, cleanup_group: true)
+            unless clean.status.success? && clean.stdout.empty? && !clean.oversized
+              raise InvalidConfigurationError, "command accepted source is dirty"
+            end
+          end
+          true
+        end
+      end
+    end
+  end
+end