ace-overseer 0.20.0 → 0.20.2

data/lib/ace/overseer/organisms/protected_prune.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "ace/lab/organisms/protected_service_client"
+require_relative "../molecules/protected_selection"
+
+module Ace
+  module Overseer
+    module Organisms
+      class ProtectedPrune
+        Preview = Ace::Lab::Atoms::ProtectedWorkspacePrunePreview
+
+        def initialize(selection: nil, document_loader: nil, client_factory: nil, authority_factory: nil)
+          @selection = selection || Molecules::ProtectedSelection.new
+          @document_loader = document_loader || -> { Ace::Lab::Molecules::GrantResolver.trusted_document(Ace::Lab.authorization_path) }
+          @client_factory = client_factory || ->(mapping, service, deployment) {
+            Ace::Lab::Organisms::ProtectedServiceClient.new(mapping_id: mapping, service_id: service, deployment: deployment)
+          }
+          @authority_factory = authority_factory || ->(mapping, deployment) {
+            Ace::Assign::Authority::Client.new(mapping_id: mapping, deployment: deployment)
+          }
+        end
+
+        def preview(project:, agent:, assignment:, attempt:, request:)
+          intent = Preview.intent!(read_file(request, limit: Preview::Input::MAX_BYTES))
+          deployment, service = selection!(intent, project, agent, assignment, attempt)
+          @client_factory.call(intent.dig("maintenance", "mapping_id"), service, deployment).preview_workspace_prune(intent: intent)
+        rescue ArgumentError, KeyError, TypeError, JSON::ParserError, SystemCallError, IOError, SecurityError,
+          Ace::Runtime::RuntimeUnavailableError, Ace::Lab::Error, Ace::Assign::Error => error
+          raise Error, "Protected prune preview unavailable (#{error.class.name.split('::').last})"
+        end
+
+        def apply(project:, agent:, assignment:, attempt:, request:, mutation:, expected_generation:, authorization:)
+          token!(mutation); token!(authorization)
+          raise Error, "Expected authority generation must be a positive integer" unless expected_generation.is_a?(Integer) && expected_generation.positive?
+          result, intent = result_file!(request)
+          deployment, service = selection!(intent, project, agent, assignment, attempt)
+          context = result.fetch("maintenance_context")
+          input = Preview::Input.parse(JSON.generate({"schema" => "ace.protected-workspace-prune/v1"}.merge(
+            result.slice("maintenance", "target", "publication", "preservation"))))
+          submission = context.fetch("maintenance").slice("assignment_id", "attempt_id").merge(
+            "expected_generation" => expected_generation, "candidate_generation" => context.fetch("candidate_generation"),
+            "head" => context.fetch("head"), "request_id" => mutation, "operation" => "prune-preserved-workspace",
+            "authorization" => authorization, "input_digest" => Ace::Lab::Atoms::ServiceInput.digest(input),
+            "target" => Ace::Lab::Atoms::ServiceInput.target(input))
+          @client_factory.call(context.dig("maintenance", "mapping_id"), service, deployment).submit(
+            submission: submission, input_bytes: JSON.generate(input), mutation_id: mutation)
+        rescue ArgumentError, KeyError, TypeError, JSON::ParserError, SystemCallError, IOError, SecurityError,
+          Ace::Runtime::RuntimeUnavailableError, Ace::Lab::Error, Ace::Assign::Error => error
+          raise Error, "Protected prune apply unavailable (#{error.class.name.split('::').last})"
+        end
+
+        def status(request:, mutation:)
+          token!(mutation)
+          result, intent = result_file!(request)
+          target = intent.fetch("target")
+          deployment, = selection!(intent, *target.values_at("project_id", "mapping_id", "assignment_id", "attempt_id"))
+          context = result.fetch("maintenance_context")
+          params = context.fetch("maintenance").slice("assignment_id", "attempt_id").merge(
+            "head" => context.fetch("head"), "candidate_generation" => context.fetch("candidate_generation"), "request_id" => mutation)
+          @authority_factory.call(context.dig("maintenance", "mapping_id"), deployment).call(
+            "service_status", params, mutation_id: nil, timeout: 5).data
+        rescue ArgumentError, KeyError, TypeError, JSON::ParserError, SystemCallError, IOError, SecurityError,
+          Ace::Runtime::RuntimeUnavailableError, Ace::Lab::Error, Ace::Assign::Error => error
+          raise Error, "Protected prune status unavailable (#{error.class.name.split('::').last})"
+        end
+
+        private
+
+        def result_file!(path)
+          result = read_file(path, limit: 16_384)
+          intent = Preview.intent!({"schema" => "ace.protected-workspace-prune-preview/v1",
+            "maintenance" => result.fetch("maintenance"), "target" => result.fetch("target").except("artifact_digest"),
+            "publication" => result.fetch("publication"), "destinations" => result.fetch("preservation").fetch("destinations")})
+          context = Preview.context!(result.fetch("maintenance_context"))
+          raise Error, "Preview maintenance context differs" unless context.fetch("maintenance") == intent.fetch("maintenance")
+          [Preview.result!(result, intent: intent, context: context), intent]
+        end
+
+        def token!(value)
+          raise Error, "Explicit protected service identity is required" unless value.is_a?(String) && value.match?(Preview::Input::ID)
+        end
+
+        def selection!(intent, project, agent, assignment, attempt)
+          unless intent.fetch("target").values_at("project_id", "mapping_id", "assignment_id", "attempt_id") ==
+              [project, agent, assignment, attempt]
+            raise Error, "Protected prune target differs from CLI selection"
+          end
+          maintenance = intent.fetch("maintenance")
+          # The successor can omit the retired target mapping. Visibility and
+          # current caller admission belong to the separate maintenance actor.
+          deployment, = @selection.call(project: maintenance.fetch("project_id"), agent: maintenance.fetch("mapping_id"))
+          map = deployment.mapping(maintenance.fetch("mapping_id"))
+          raise Error, "Protected maintenance project differs" unless map.fetch("project_id") == maintenance.fetch("project_id")
+          operation = @document_loader.call.fetch("operations").fetch("prune-preserved-workspace")
+          service = operation.fetch("service_id")
+          unless operation.fetch("project") == maintenance.fetch("project_id") &&
+              deployment.project(maintenance.fetch("project_id")).fetch("service_receivers").key?(service)
+            raise Error, "Installed protected prune receiver is unavailable"
+          end
+          [deployment, service]
+        end
+
+        def read_file(path, limit:)
+          raise ArgumentError, "request FILE is required" unless path.is_a?(String) && !path.empty?
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+            raise ArgumentError, "request FILE must be bounded and regular" unless file.stat.file? && file.stat.size.between?(1, limit)
+            bytes = file.read(limit + 1).force_encoding(Encoding::UTF_8)
+            raise ArgumentError, "request FILE must be bounded UTF-8" unless bytes.bytesize.between?(1, limit) && bytes.valid_encoding?
+            JSON.parse(bytes, create_additions: false, max_nesting: 16, allow_nan: false,
+              allow_comments: false, allow_duplicate_key: false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/organisms/protected_review.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "tmpdir"
+require "time"
+require "ace/assign/authority/client"
+require "ace/assign/authority/candidate_transfer"
+require "ace/assign/models/execution_receipt"
+
+module Ace
+  module Overseer
+    module Organisms
+      # The original requesting process owns the review through acceptance.
+      # Retained files are observation/retry evidence, never an authority cache.
+      class ProtectedReview
+        def initialize(deployment_loader: nil, kernel: nil, client_factory: nil, reviewer_factory: nil)
+          @deployment_loader = deployment_loader || -> { Ace::Assign::Authority::Deployment.load }
+          @kernel = kernel || Ace::Runtime::Molecules::ProtectedLinux.new
+          @client_factory = client_factory || ->(id, deployment) { Ace::Assign::Authority::Client.new(mapping_id: id, deployment: deployment, kernel: @kernel) }
+          @reviewer_factory = reviewer_factory || ->(root) do
+            require "ace/review"
+            Ace::Review::Organisms::ReviewManager.new(project_root: root)
+          end
+        end
+
+        def call(project:, agent:, assignment:, attempt:, mutation:, status: false, cancel: false,
+          head: nil, candidate_generation: nil, expected_generation: nil, accept_mutation: nil, review_event: nil)
+          [project, agent, assignment, attempt, mutation].each { |value| token!(value) }
+          raise Error, "Review modes are mutually exclusive" if status && cancel
+          if status
+            raise Error, "Status forbids mutation and candidate options" if [head, candidate_generation, expected_generation, accept_mutation, review_event].any?
+          else
+            sha!(head, 40)
+            positive!(candidate_generation)
+            positive!(expected_generation)
+            if cancel
+              sha!(review_event, 64)
+              raise Error, "Cancel forbids accept mutation" if accept_mutation
+            else
+              token!(accept_mutation)
+              raise Error, "Request and acceptance need distinct mutation IDs" if mutation == accept_mutation
+              raise Error, "Request forbids cancellation selector" if review_event
+            end
+          end
+          deployment = @deployment_loader.call
+          map = deployment.mapping(agent)
+          raise Error, "Mapping belongs to another project" unless map.fetch("project_id") == project
+          installed = deployment.project(project)
+          peer = @kernel.capture(Process.pid)
+          credentials = installed.fetch("peer_credentials").fetch(peer.fetch("uid").to_s)
+          unless installed.fetch("reviewer_uids").include?(peer.fetch("uid")) && peer.fetch("uid") != map.fetch("worker_uid") &&
+              peer.values_at("gid", "groups") == credentials.values_at("gid", "groups")
+            raise Error, "Review requires its installed independent reviewer principal"
+          end
+          client = @client_factory.call(agent, deployment)
+          selectors = {"assignment_id" => assignment, "attempt_id" => attempt}
+          return client.call("review_status", selectors.merge("mutation_id" => mutation), timeout: 30).data if status
+          candidate = selectors.merge("head" => head, "candidate_generation" => candidate_generation)
+          if cancel
+            return client.call("cancel_review", candidate.merge("review_event_id" => review_event,
+              "expected_generation" => expected_generation), mutation_id: mutation, timeout: 30).data
+          end
+          root = credentials.fetch("scratch_root")
+          Ace::Assign::Authority::PrivateDirectory.verify!(root)
+          directory = Dir.mktmpdir("review-request-", root)
+          File.chmod(0o700, directory)
+          request = candidate.merge("expected_generation" => expected_generation)
+          persist(directory, "request.json", JSON.generate("project" => project, "mapping" => agent,
+            "request" => request, "mutation" => mutation, "accept_mutation" => accept_mutation, "reviewer" => peer))
+          requested = true
+          reply = client.call("request_review", request, mutation_id: mutation, timeout: 30)
+          persist(directory, "assignment.json", JSON.generate(reply.data))
+          if reply.replayed || reply.data["state"] != "assigned"
+            return {"state" => reply.data.fetch("state"), "replayed" => reply.replayed,
+              "required_action" => "inspect_review_status", "session_dir" => directory}
+          end
+          review = reply.data.fetch("assignment")
+          positive!(reply.data.fetch("generation"))
+          unless review.is_a?(Hash) && review.values_at("head", "candidate_generation") == candidate.values_at("head", "candidate_generation") &&
+              review["reviewer_uid"] == peer.fetch("uid") && review["reviewer_actor"] == "uid-#{peer.fetch('uid')}" &&
+              @kernel.same?(review.fetch("reviewer_process_binding"), peer)
+            raise Error, "Assigned review differs from original requesting process or candidate"
+          end
+          token!(review.fetch("review_id"))
+          attempt_state = client.call("attempt_status", selectors.merge("result_candidate_generation" => candidate_generation), timeout: 30).data
+          unless attempt_state.values_at("assignment_id", "attempt_id") == [assignment, attempt] &&
+              attempt_state["scope"].is_a?(String) && attempt_state["scope"].match?(/\A[0-9]+(?:\.[0-9]+)*\z/)
+            raise Error, "Canonical review scope is unavailable"
+          end
+          purpose = candidate.merge("purpose_id" => review.fetch("review_id"))
+          exported = client.call("export_candidate", purpose, download: true, purpose: :candidate, timeout: 30)
+          unless exported.parts.is_a?(Array) && exported.parts.size == 1 &&
+              exported.data.values_at("head", "candidate_generation") == candidate.values_at("head", "candidate_generation")
+            raise Error, "Exported review candidate differs"
+          end
+          snapshot = Ace::Assign::Authority::CandidateTransfer.new(root: directory).review_snapshot(
+            bytes: exported.parts.first, size: exported.data.fetch("bytes"), sha256: exported.data.fetch("sha256"),
+            head: head, tree: exported.data.fetch("tree"), root: directory)
+          result = @reviewer_factory.call(snapshot.fetch("directory")).execute_prepared_candidate(
+            candidate: purpose.merge("tree" => snapshot.fetch("tree")), subject: snapshot.fetch("subject"),
+            session_dir: File.join(directory, "execution"))
+          unless result[:success] && result[:verdict] == "approved"
+            return {"state" => "not_approved", "verdict" => result[:verdict] || "unavailable", "session_dir" => directory}
+          end
+          artifacts = result.fetch(:artifacts)
+          unless artifacts.is_a?(Hash) && artifacts.size.between?(1, 16) && artifacts.all? { |name, bytes|
+              name.is_a?(String) && name.match?(/\A[a-zA-Z0-9_.-]{1,128}\z/) && bytes.is_a?(String) && bytes.bytesize.between?(1, 65_536) } &&
+              artifacts.values.sum(&:bytesize) <= 256 * 1024
+            raise Error, "Review artifacts exceed receipt bounds"
+          end
+          receipt = Ace::Assign::Models::ExecutionReceipt.new(assignment_id: assignment, attempt_id: attempt,
+            project_id: project, scope: attempt_state.fetch("scope"), operation: "review", head: head,
+            producer: {"actor" => map.fetch("worker_actor"), "role" => "worker", "runtime" => "herdr"},
+            verdict: "succeeded", checks: result.fetch(:checks), recorded_at: Time.now.utc,
+            artifacts: artifacts.map { |name, bytes| {"path" => name, "sha256" => Digest::SHA256.hexdigest(bytes)} },
+            review: {"head" => head, "verdict" => "approved", "reviewer" => {"actor" => review.fetch("reviewer_actor")}})
+          encoded = JSON.generate(receipt.to_h)
+          raise Error, "Review receipt exceeds bounds" if encoded.bytesize > 65_536
+          persist(directory, "receipt.json", encoded)
+          acceptance = purpose.merge("expected_generation" => reply.data.fetch("generation"),
+            "receipt_sha256" => Digest::SHA256.hexdigest(encoded))
+          persist(directory, "acceptance.json", JSON.generate("mutation" => accept_mutation, "params" => acceptance))
+          @kernel.live!(peer)
+          unless @kernel.same?(@kernel.capture(Process.pid), review.fetch("reviewer_process_binding"))
+            raise Error, "Original reviewer process changed before acceptance"
+          end
+          accepted = client.call("accept_review", acceptance, mutation_id: accept_mutation,
+            upload_parts: [encoded, *artifacts.values], purpose: :receipt_artifacts, timeout: 30)
+          unless accepted.data.values_at("head", "candidate_generation", "review_id", "reviewer_uid", "uploaded_receipt_sha256") ==
+              [head, candidate_generation, review.fetch("review_id"), peer.fetch("uid"), Digest::SHA256.hexdigest(encoded)]
+            raise Error, "Canonical acceptance differs from submitted review"
+          end
+          persist(directory, "accepted.json", JSON.generate(accepted.data))
+          {"state" => "accepted", "acceptance" => accepted.data, "session_dir" => directory}
+        rescue Ace::Assign::Error, Ace::Runtime::RuntimeUnavailableError, Error, ArgumentError, KeyError, TypeError, SystemCallError, IOError => error
+          raise Error, error.message unless requested
+          {"state" => "uncertain", "required_action" => "inspect_review_status", "session_dir" => directory,
+            "error" => error.message}
+        end
+
+        private
+
+        def persist(directory, name, bytes)
+          File.open(File.join(directory, name), File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0o600) do |file|
+            file.write(bytes)
+            file.flush
+            file.fsync
+          end
+          File.open(directory, File::RDONLY) { |file| file.fsync }
+        end
+
+        def token!(value)
+          raise Error, "Review selector is invalid" unless value.is_a?(String) && value.match?(Ace::Assign::Authority::Deployment::TOKEN)
+        end
+
+        def positive!(value)
+          raise Error, "Review generation must be a positive integer" unless value.is_a?(Integer) && value.positive?
+        end
+
+        def sha!(value, length)
+          raise Error, "Review digest is invalid" unless value.is_a?(String) && value.match?(/\A[0-9a-f]{#{length}}\z/)
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/organisms/protected_status.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "ace/lab"
+require "ace/assign/authority/client"
+require_relative "../molecules/protected_selection"
+
+module Ace
+  module Overseer
+    module Organisms
+      # Public topology supplies visibility; protected Deployment supplies the
+      # actual fixed capacity. Canonical authority pages supply attempt facts.
+      # None of these metadata observations is a mutation/cleanup grant.
+      class ProtectedStatus
+        ROW_KEYS = %w[assignment_id task_id definition_digest definition_generation prepared_bundle_ref prepared_bundle_bytes prepared_bundle_sha256 selection_sha256 attempt_id scope reservation_mutation_id base_head reservation_generation generation canonical_state original_binding_digest terminal_event_id reservation_release_event_id].sort.freeze
+
+        def initialize(topology: nil, deployment_loader: nil, client_factory: nil)
+          @selection = Molecules::ProtectedSelection.new(topology: topology, deployment_loader: deployment_loader)
+          @client_factory = client_factory || ->(id, deployment) { Ace::Assign::Authority::Client.new(mapping_id: id, deployment: deployment) }
+        end
+
+        def collect(project:, agent: nil)
+          deployment, pool, ids = selection!(project, agent)
+          selected = agent ? [agent] : ids
+          snapshots = selected.map do |id|
+            client = @client_factory.call(id, deployment)
+            {"agent_id" => id, "status" => "ok", "inventory" => inventory(client, project: project, mapping_id: id)}
+          rescue Ace::Assign::Error, Ace::Runtime::RuntimeUnavailableError, Error
+            {"agent_id" => id, "status" => "unavailable", "inventory" => nil}
+          end
+          {"project_id" => project, "provisioned_capacity" => pool.size, "visible_capacity" => ids.size,
+            "visibility" => ids == pool ? "complete" : "partial", "agents" => snapshots}
+        rescue KeyError, TypeError, NoMethodError
+          raise Error, "Protected status metadata is malformed"
+        end
+
+        # The parent cannot impersonate its foreground child's original birth.
+        # Join that child's bounded frame to its retained canonical snapshot.
+        def join_ready!(project:, agent:, ready:)
+          deployment, = selection!(project, agent)
+          unless ready.is_a?(Hash) && ready.keys.all? { |key| key.is_a?(String) } && ready.keys.sort == %w[assignment_id attempt_id generation journal_commit mapping_id original_binding_digest type version] &&
+              ready["version"].is_a?(Integer) && ready["version"] == 1 && ready["type"] == "launch_ready" && ready["mapping_id"] == agent
+            raise Error, "Original launch readiness is malformed"
+          end
+          %w[assignment_id attempt_id].each { |key| token!(ready.fetch(key)) }
+          positive!(ready.fetch("generation"))
+          digest!(ready.fetch("original_binding_digest"))
+          unless ready["journal_commit"].is_a?(String) && ready["journal_commit"].match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/)
+            raise Error, "Original launch readiness revision is malformed"
+          end
+          snapshot = inventory(@client_factory.call(agent, deployment), project: project, mapping_id: agent, commit: ready.fetch("journal_commit"))
+          row = snapshot.fetch("items").find { |entry| entry.values_at("assignment_id", "attempt_id") == ready.values_at("assignment_id", "attempt_id") }
+          unless row && row.values_at("generation", "original_binding_digest") == ready.values_at("generation", "original_binding_digest")
+            raise Error, "Original launch readiness differs from canonical attempt"
+          end
+          {"journal_commit" => snapshot.fetch("journal_commit"), "item" => row}
+        rescue KeyError, TypeError, NoMethodError
+          raise Error, "Original launch readiness is malformed"
+        rescue Ace::Assign::Error, Ace::Runtime::RuntimeUnavailableError
+          raise Error, "Original launch readiness canonical snapshot is unavailable"
+        end
+
+        private
+
+        def selection!(project, agent)
+          @selection.call(project: project, agent: agent)
+        end
+
+        def inventory(client, project:, mapping_id:, commit: nil)
+          after = nil
+          rows = []
+          selectors = {}
+          loop do
+            page = client.call("assignment_inventory", {"journal_commit" => commit, "after" => after, "limit" => 25}, timeout: 30).data
+            unless page.is_a?(Hash) && page.keys.all? { |key| key.is_a?(String) } && page.keys.sort == %w[items journal_commit mapping_id next_after project_id] &&
+                page["project_id"] == project && page["mapping_id"] == mapping_id &&
+                page["journal_commit"].is_a?(String) && page["journal_commit"].match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/) &&
+                (commit.nil? || page["journal_commit"] == commit) && page["items"].is_a?(Array) && page["items"].size <= 25
+              raise Error, "Protected inventory snapshot differs"
+            end
+            commit ||= page.fetch("journal_commit")
+            page.fetch("items").each do |row|
+              validate_row!(row)
+              selector = [row.fetch("assignment_id"), row.fetch("attempt_id")]
+              if selectors[selector] || (!rows.empty? && (selector_order(selector) <=> selector_order(rows.last.values_at("assignment_id", "attempt_id"))) <= 0)
+                raise Error, "Protected inventory ordering is ambiguous"
+              end
+              selectors[selector] = true
+              rows << row
+            end
+            following = page.fetch("next_after")
+            break if following.nil?
+            unless following.is_a?(Hash) && following.keys.all? { |key| key.is_a?(String) } && following.keys.sort == %w[assignment_id attempt_id] && !page.fetch("items").empty? &&
+                following == page.fetch("items").last.slice("assignment_id", "attempt_id") && following != after
+              raise Error, "Protected inventory continuation is malformed"
+            end
+            after = following
+          end
+          {"journal_commit" => commit, "items" => rows}
+        end
+
+        def validate_row!(row)
+          raise Error, "Protected inventory row is malformed" unless row.is_a?(Hash) && row.keys.all? { |key| key.is_a?(String) } && row.keys.sort == ROW_KEYS
+          token!(row.fetch("assignment_id"))
+          unless row["task_id"].is_a?(String) && !row["task_id"].empty? && row["task_id"].bytesize <= 32_768
+            raise Error, "Protected task identity is malformed"
+          end
+          digest!(row.fetch("definition_digest"))
+          positive!(row.fetch("definition_generation"))
+          digest!(row.fetch("prepared_bundle_sha256"))
+          digest!(row.fetch("selection_sha256"))
+          positive!(row.fetch("prepared_bundle_bytes"))
+          unless row.fetch("prepared_bundle_bytes") <= 64 * 1024 * 1024 &&
+              row.fetch("prepared_bundle_ref") == "execution/prepared/#{row.fetch('assignment_id')}-#{row.fetch('prepared_bundle_sha256')}.bundle"
+            raise Error, "Protected prepared bundle identity is malformed"
+          end
+          if row.fetch("attempt_id").nil?
+            unless row.values_at("scope", "reservation_mutation_id", "base_head", "reservation_generation", "generation", "canonical_state", "original_binding_digest", "terminal_event_id", "reservation_release_event_id").all?(&:nil?)
+              raise Error, "Registration-only inventory has attempt facts"
+            end
+          else
+            token!(row.fetch("attempt_id"))
+            raise Error, "Protected inventory scope is malformed" unless row["scope"].is_a?(String) && !row["scope"].empty? && row["scope"].bytesize <= 128
+            token!(row.fetch("reservation_mutation_id"))
+            unless row["base_head"].is_a?(String) && row["base_head"].match?(/\A[0-9a-f]{40}\z/)
+              raise Error, "Protected reservation base is malformed"
+            end
+            positive!(row.fetch("reservation_generation"))
+            positive!(row.fetch("generation"))
+            unless %w[reserved running succeeded failed stopped uncertain].include?(row.fetch("canonical_state"))
+              raise Error, "Protected canonical state is malformed"
+            end
+            %w[original_binding_digest terminal_event_id reservation_release_event_id].each { |key| digest!(row.fetch(key)) unless row.fetch(key).nil? }
+            if row["reservation_release_event_id"] && (!row["terminal_event_id"] || !%w[succeeded failed stopped].include?(row["canonical_state"]))
+              raise Error, "Protected release lacks terminal provenance"
+            end
+          end
+        end
+
+        def selector_order(value)
+          [value.first.b, value.last.to_s.b]
+        end
+
+        def token!(value)
+          raise Error, "Protected identity is invalid" unless value.is_a?(String) && value.match?(Ace::Assign::Authority::Deployment::TOKEN)
+        end
+
+        def digest!(value)
+          raise Error, "Protected digest is invalid" unless value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+        end
+
+        def positive!(value)
+          raise Error, "Protected generation is invalid" unless value.is_a?(Integer) && value.positive?
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/organisms/protected_steering.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+require "ace/assign/authority/client"
+require_relative "../molecules/protected_selection"
+require_relative "protected_status"
+
+module Ace
+  module Overseer
+    module Organisms
+      # Visibility and exact inventory select a target, never a replay grant.
+      # The authority authenticates the original principal and immutable input.
+      class ProtectedSteering
+        def initialize(selection: nil, status: nil, client_factory: nil)
+          @selection = selection || Molecules::ProtectedSelection.new
+          @status = status || ProtectedStatus.new
+          @client_factory = client_factory || ->(id, deployment) { Ace::Assign::Authority::Client.new(mapping_id: id, deployment: deployment) }
+        end
+
+        def prompt(project:, agent:, assignment:, attempt:, mutation:, expected_generation: nil, text: nil, status: false)
+          if status
+            raise Error, "Prompt status forbids text and expected generation" unless text.nil? && expected_generation.nil?
+          else
+            generation!(expected_generation)
+            unless text.is_a?(String) &&
+                text.dup.force_encoding(Encoding::UTF_8).valid_encoding? && text.bytesize.between?(1, 16_384) &&
+                !text.dup.force_encoding(Encoding::UTF_8).match?(/\A[[:space:]]*\z/)
+              raise Error, "Prompt must be bounded UTF-8 non-whitespace text"
+            end
+          end
+          client, selectors = target(project, agent, assignment, attempt, mutation)
+          if status
+            client.call("prompt_status", selectors.merge("mutation_id" => mutation), mutation_id: nil, timeout: 30).data
+          else
+            client.call("prompt_attempt", selectors.merge("expected_generation" => expected_generation),
+              mutation_id: mutation, upload_parts: [text], purpose: :prompt_text, timeout: 30).data
+          end
+        end
+
+        def stop(project:, agent:, assignment:, attempt:, mutation:, expected_generation:)
+          generation!(expected_generation)
+          client, selectors = target(project, agent, assignment, attempt, mutation)
+          client.call("stop_attempt", selectors.merge("expected_generation" => expected_generation), mutation_id: mutation).data
+        end
+
+        private
+
+        def target(project, agent, assignment, attempt, mutation)
+          [project, agent, assignment, attempt, mutation].each do |value|
+            unless value.is_a?(String) && value.match?(Ace::Assign::Authority::Deployment::TOKEN)
+              raise Error, "Exact protected steering identity is required"
+            end
+          end
+          deployment, = @selection.call(project: project, agent: agent)
+          snapshot = @status.collect(project: project, agent: agent)
+          selected = snapshot.fetch("agents").select { |entry| entry["agent_id"] == agent }
+          unless snapshot["project_id"] == project && selected.size == 1 && selected.first["status"] == "ok"
+            raise Error, "Exact protected steering inventory is unavailable"
+          end
+          rows = selected.first.fetch("inventory").fetch("items").select do |row|
+            row.values_at("assignment_id", "attempt_id") == [assignment, attempt]
+          end
+          unless rows.size == 1 && rows.first["original_binding_digest"].is_a?(String) &&
+              rows.first["original_binding_digest"].match?(/\A[0-9a-f]{64}\z/)
+            raise Error, "Exact original protected steering binding is unavailable"
+          end
+          # Do not compare the supplied generation with current inventory:
+          # an identical explicit replay retains its earlier immutable generation.
+          [@client_factory.call(agent, deployment), {"assignment_id" => assignment, "attempt_id" => attempt}]
+        rescue KeyError, TypeError, NoMethodError
+          raise Error, "Protected steering inventory is malformed"
+        end
+
+        def generation!(value)
+          raise Error, "Observed generation must be a positive integer" unless value.is_a?(Integer) && value.positive?
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/organisms/protected_work_on.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+require "ace/assign/organisms/prepared_work_builder"
+require "ace/assign/authority/launch_driver"
+require_relative "../molecules/protected_selection"
+require_relative "../molecules/launch_request"
+require_relative "../molecules/original_launch_child"
+require_relative "protected_status"
+
+module Ace
+  module Overseer
+    module Organisms
+      # Compose existing owners. Retained handles are process-local observation,
+      # never another authority/progress ledger or a replacement-launch grant.
+      class ProtectedWorkOn
+        attr_reader :children
+
+        def initialize(selection: nil, status: nil, builder_factory: nil, driver_factory: nil,
+          child_factory: nil, task_manager: nil, request_root: nil, head_reader: nil, pause: nil)
+          @selection = selection || Molecules::ProtectedSelection.new
+          @status = status || ProtectedStatus.new
+          @builder_factory = builder_factory || ->(root) { Ace::Assign::Organisms::PreparedWorkBuilder.new(export_root: root) }
+          @driver_factory = driver_factory || ->(id, deployment) { Ace::Assign::Authority::LaunchDriver.new(mapping_id: id, deployment: deployment) }
+          @child_factory = child_factory || -> { Molecules::OriginalLaunchChild.new }
+          @tasks = task_manager || Ace::Task::Organisms::TaskManager.new
+          @root = File.expand_path(request_root || File.join(Dir.pwd, ".ace-local", "overseer", "launch-requests"))
+          @head_reader = head_reader || -> do
+            result = Ace::Git::Atoms::CommandExecutor.execute("git", "rev-parse", "HEAD")
+            raise Error, "Exact launch base is unavailable" unless result.fetch(:success)
+            result.fetch(:output).strip
+          end
+          @pause = pause || -> { sleep 0.1 }
+          @children = {}
+        end
+
+        def start(task_ref:, project:, agent: nil, runtime: "auto", dependency_reports: [], mutation_id: nil, base_head: nil, report:)
+          raise Error, "Protected launch requires Herdr; tmux cannot allocate protected work" unless %w[auto herdr].include?(runtime)
+          deployment, pool, visible = @selection.call(project: project, agent: agent)
+          ids = agent ? [agent] : visible
+          raise Error, "Protected project has no visible mapping" if ids.empty?
+          mapping = nil
+          ids.each do |id|
+            begin
+              preflight = @driver_factory.call(id, deployment).preflight
+            rescue Ace::Assign::AttemptErrors::UnauthorizedIdentity
+              raise if agent
+              next # Attributable readonly refusal; no retained/canonical effect.
+            end
+            unless preflight.is_a?(Hash) && preflight.values_at("project_id", "runtime", "supported") == [project, "herdr", true]
+              raise Error, "Protected Herdr capability is unavailable"
+            end
+            mapping = id
+            break
+          end
+          raise Error, "No visible protected mapping admits this launcher" unless mapping
+          task = @tasks.show(task_ref)
+          raise Error, "Protected leaf task is unavailable" unless task
+          captured_head = @head_reader.call
+          unless captured_head.is_a?(String) && captured_head.match?(/\A[0-9a-f]{40}\z/) && (base_head.nil? || base_head == captured_head)
+            raise Error, "Explicit reviewed code base differs from current source head"
+          end
+          base_head = captured_head
+          mutation = mutation_id || SecureRandom.hex(16)
+          unless mutation.is_a?(String) && mutation.match?(Molecules::LaunchRequest::MUTATION)
+            raise Error, "Retained invocation ID is invalid"
+          end
+          raise Error, "Original invocation already has a child" if children.key?(mutation)
+          FileUtils.mkdir_p(@root, mode: 0700)
+          owner = Molecules::LaunchRequest.new(root: @root)
+          prepared = @builder_factory.call(@root).call(task_ref: task.id, project_id: project, dependency_reports: dependency_reports)
+          raise Error, "Code base changed during prepared input capture" unless @head_reader.call == base_head
+          request = owner.publish(project_id: project, mapping_id: mapping, task_id: task.id, base_head: base_head, mutation_id: mutation, prepared: prepared)
+          owner.verify_fresh!(request)
+          identity = owner.identity(request)
+          # The caller must write and flush this mandatory identity before any
+          # child or canonical mutation. Reporting failure remains zero-child.
+          report.call(identity.merge("provisioned_capacity" => pool.size, "visible_capacity" => visible.size,
+            "visibility" => pool == visible ? "complete" : "partial"))
+          owner.verify_fresh!(request)
+          raise Error, "Code base changed before original child" unless @head_reader.call == base_head
+          child = @child_factory.call
+          children[mutation] = child
+          child.start(request: request, definition_path: owner.definition_path(request), bundle_path: identity.fetch("prepared_bundle_path"))
+          child.await_ready(status: @status)
+          {"input" => identity, "child" => child}
+        end
+
+        # Keep one living owner through uncertainty. Reaping the original child
+        # is not terminal/release proof and does not authorize display cleanup.
+        def serve(child)
+          until child.state == "exited"
+            child.observe
+            @pause.call unless child.state == "exited"
+          end
+          child
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/organisms/work_on_orchestrator.rb

@@ -18,7 +18,7 @@ module Ace
           @lifecycle_exclusion = lifecycle_exclusion
         end
 
-        def call(task_ref:, task_refs: nil, cli_preset: nil, on_progress: nil)
+        def call(task_ref:, task_refs: nil, cli_preset: nil, on_progress: nil, runtime: nil)
           progress = on_progress || ->(_msg) {}
 
           requested_refs = normalize_requested_refs(task_ref, task_refs)
@@ -68,10 +68,9 @@ module Ace
             end
 
             progress.call("Opening terminal window...")
-            @window_opener.open(
-              worktree_path: worktree[:worktree_path],
-              preset: window_preset
-            )
+            window_options = {worktree_path: worktree[:worktree_path], preset: window_preset}
+            window_options[:runtime] = runtime if runtime
+            @window_opener.open(**window_options)
 
             progress.call("Checking assignment status...")
             existing = if @assignment_detector