ace-overseer 0.20.0 → 0.20.2

data/lib/ace/overseer/cli.rb

@@ -7,7 +7,6 @@ require_relative "cli/commands/status"
 require_relative "cli/commands/prune"
 require_relative "cli/commands/projects"
 require_relative "cli/commands/agents"
-require_relative "cli/commands/prepare"
 require_relative "cli/commands/prompt"
 require_relative "cli/commands/review"
 require_relative "cli/commands/stop"
@@ -20,15 +19,14 @@ module Ace
       PROGRAM_NAME = "ace-overseer"
 
       REGISTERED_COMMANDS = [
-        ["work-on", "Work on a task in isolated worktree"],
+        ["work-on", "Start local task work or one retained protected launch"],
         ["status", "Show status of task worktrees"],
         ["prune", "Remove stale task worktrees"],
-        ["projects", "List configured Lab projects"],
-        ["agents", "List configured Lab agents"],
-        ["prepare", "Prepare a Lab Work"],
-        ["prompt", "Prompt a Lab Work from stdin"],
-        ["review", "Start a Lab Work review"],
-        ["stop", "Stop a Lab Work"]
+        ["projects", "List visible public projects"],
+        ["agents", "List visible public project agents"],
+        ["prompt", "Prompt an exact protected attempt or inspect original prompt status"],
+        ["review", "Review an exact protected candidate under its original capability"],
+        ["stop", "Request proof-authenticated stop of an exact protected attempt"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -42,7 +40,6 @@ module Ace
       register "prune", Commands::Prune
       register "projects", Commands::Projects
       register "agents", Commands::Agents
-      register "prepare", Commands::Prepare
       register "prompt", Commands::Prompt
       register "review", Commands::Review
       register "stop", Commands::Stop

data/lib/ace/overseer/molecules/launch_request.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "ace/assign/authority/prepared_work"
+require "ace/assign/authority/private_directory"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Retained inputs, never an authority grant or an attempt/progress ledger.
+      class LaunchRequest
+        KEYS = %w[version project_id mapping_id assignment_id task_id scope base_head mutation_id definition_bytes definition_sha256 prepared_bundle].sort.freeze
+        BUNDLE_KEYS = %w[filename bytes sha256].sort.freeze
+        MAX_REQUEST = 131_072
+        MAX_DEFINITION = 32_768
+        MAX_BUNDLE = 64 * 1024 * 1024
+        SHA = /\A[0-9a-f]{64}\z/
+        GIT = /\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/
+        MUTATION = /\A[a-zA-Z0-9][a-zA-Z0-9._-]{0,115}\z/
+
+        def initialize(root:)
+          @root = Ace::Assign::Authority::PrivateDirectory.verify!(root)
+        rescue Ace::Assign::AttemptErrors::ReceiptRejected => error
+          raise Error, error.message
+        end
+
+        def publish(project_id:, mapping_id:, task_id:, base_head:, mutation_id:, prepared:)
+          bundle = prepared.fetch("bundle")
+          document = {"version" => 1, "project_id" => project_id, "mapping_id" => mapping_id,
+            "assignment_id" => prepared.fetch("assignment_id"), "task_id" => task_id,
+            "scope" => prepared.fetch("scope"), "base_head" => base_head, "mutation_id" => mutation_id,
+            "definition_bytes" => prepared.fetch("definition_bytes"),
+            "definition_sha256" => Digest::SHA256.hexdigest(prepared.fetch("definition_bytes")),
+            "prepared_bundle" => {"filename" => "#{mutation_id}.prepared.bundle", "bytes" => prepared.fetch("bytes"), "sha256" => prepared.fetch("sha256")}}
+          validate!(document)
+          verify_bundle!(document, bundle)
+          bytes = JSON.generate(document)
+          raise Error, "Retained launch request exceeds bound" if bytes.bytesize > MAX_REQUEST
+          request_path = File.join(@root, "#{mutation_id}.json")
+          bundle_path = File.join(@root, document.fetch("prepared_bundle").fetch("filename"))
+          sidecar_path = definition_path(document)
+          [request_path, bundle_path, sidecar_path].each do |path|
+            begin
+              File.lstat(path)
+              raise Error, "Retained launch invocation already exists"
+            rescue Errno::ENOENT
+              # Both names must be absent; exclusive creation closes the race.
+            end
+          end
+          # Never overwrite either input. Failure can leave an unselected orphan;
+          # it cannot create a different accepted invocation under the same ID.
+          write_exclusive(bundle_path, bundle)
+          write_exclusive(sidecar_path, document.fetch("definition_bytes"))
+          write_exclusive(request_path, bytes)
+          File.open(@root, File::RDONLY) { |directory| directory.fsync }
+          load(request_path)
+        rescue KeyError, JSON::GeneratorError, SystemCallError => error
+          raise Error, "Retained launch publication failed: #{error.message}"
+        end
+
+        def load(path)
+          path = File.expand_path(path)
+          raise Error, "Retained launch request is outside its private owner" unless File.dirname(path) == @root
+          bytes = held_read(path, MAX_REQUEST)
+          value = JSON.parse(bytes, create_additions: false, max_nesting: 32, allow_duplicate_key: false, allow_comments: false)
+          validate!(value)
+          raise Error, "Retained launch filename differs" unless File.basename(path) == "#{value.fetch('mutation_id')}.json"
+          freeze_value(value)
+        rescue JSON::ParserError, KeyError, TypeError, SystemCallError => error
+          raise Error, "Retained launch request is invalid: #{error.message}"
+        end
+
+        # Fresh launch requires the original complete bundle. Recovery only
+        # loads the document and observes availability; it never reconstructs.
+        def verify_fresh!(document)
+          validate!(document)
+          definition = held_read(definition_path(document), MAX_DEFINITION)
+          raise Error, "Retained definition sidecar differs" unless definition == document.fetch("definition_bytes")
+          bytes = held_read(File.join(@root, document.fetch("prepared_bundle").fetch("filename")), MAX_BUNDLE)
+          verify_bundle!(document, bytes)
+          bytes.freeze
+        end
+
+        def identity(document)
+          validate!(document)
+          path = File.join(@root, document.fetch("mutation_id") + ".json")
+          bytes = held_read(path, MAX_REQUEST)
+          raise Error, "Retained request changed before identity output" unless bytes == JSON.generate(document)
+          reference = JSON.parse(document.fetch("definition_bytes")).fetch("prepared_work")
+          document.slice("project_id", "mapping_id", "assignment_id", "task_id", "scope", "base_head", "mutation_id", "definition_sha256").merge(
+            "type" => "launch_inputs_retained", "request_path" => path, "request_sha256" => Digest::SHA256.hexdigest(bytes),
+            "definition_path" => definition_path(document), "prepared_bundle" => document.fetch("prepared_bundle"),
+            "prepared_bundle_path" => File.join(@root, document.fetch("prepared_bundle").fetch("filename")),
+            "selection_sha256" => reference.fetch("selection_sha256"))
+        end
+
+        def definition_path(document)
+          validate!(document)
+          File.join(@root, document.fetch("mutation_id") + ".definition.json")
+        end
+
+        def definition_availability(document)
+          bytes = held_read(definition_path(document), MAX_DEFINITION)
+          bytes == document.fetch("definition_bytes") ? "available" : "mismatch"
+        rescue Errno::ENOENT
+          "unavailable"
+        rescue Error, SystemCallError
+          "mismatch"
+        end
+
+        def bundle_availability(document)
+          validate!(document)
+          bytes = held_read(File.join(@root, document.fetch("prepared_bundle").fetch("filename")), MAX_BUNDLE)
+          ref = document.fetch("prepared_bundle")
+          bytes.bytesize == ref.fetch("bytes") && Digest::SHA256.hexdigest(bytes) == ref.fetch("sha256") ? "available" : "mismatch"
+        rescue Errno::ENOENT
+          "unavailable"
+        rescue Error, SystemCallError
+          "mismatch"
+        end
+
+        private
+
+        def validate!(value)
+          closed!(value, KEYS)
+          raise Error, "Retained launch version differs" unless value["version"].is_a?(Integer) && value["version"] == 1
+          %w[project_id mapping_id assignment_id task_id].each do |key|
+            raise Error, "Retained launch identity is invalid" unless value[key].is_a?(String) && value[key].match?(Ace::Assign::Authority::PreparedWork::TOKEN)
+          end
+          raise Error, "Retained launch mutation is invalid" unless value["mutation_id"].is_a?(String) && value["mutation_id"].match?(MUTATION)
+          raise Error, "Retained launch scope is invalid" unless value["scope"].is_a?(String) && value["scope"].match?(Ace::Assign::Authority::PreparedWork::SCOPE)
+          raise Error, "Retained launch base is invalid" unless value["base_head"].is_a?(String) && value["base_head"].match?(GIT)
+          definition = value["definition_bytes"]
+          raise Error, "Retained launch definition exceeds bound" unless definition.is_a?(String) && definition.bytesize.between?(1, MAX_DEFINITION) && definition.valid_encoding?
+          raise Error, "Retained launch definition digest differs" unless value["definition_sha256"].is_a?(String) && value["definition_sha256"].match?(SHA) && Digest::SHA256.hexdigest(definition) == value["definition_sha256"]
+          parsed = JSON.parse(definition, create_additions: false, max_nesting: 32, allow_duplicate_key: false, allow_comments: false)
+          unless parsed.is_a?(Hash) && parsed.values_at("session_id", "project_id", "task_id") == value.values_at("assignment_id", "project_id", "task_id")
+            raise Error, "Retained definition association differs"
+          end
+          reference = parsed.fetch("prepared_work")
+          closed!(reference, %w[version task_id scope prepared_head prepared_tree manifest_bytes manifest_sha256 selection_sha256].sort)
+          unless reference["version"].is_a?(Integer) && reference["version"] == 1 && reference.values_at("task_id", "scope") == value.values_at("task_id", "scope") &&
+              %w[prepared_head prepared_tree].all? { |key| reference[key].is_a?(String) && reference[key].match?(/\A[0-9a-f]{40}\z/) } &&
+              reference["manifest_bytes"].is_a?(Integer) && reference["manifest_bytes"].between?(1, MAX_DEFINITION) &&
+              %w[manifest_sha256 selection_sha256].all? { |key| reference[key].is_a?(String) && reference[key].match?(SHA) }
+            raise Error, "Retained prepared selection differs"
+          end
+          bundle = value["prepared_bundle"]
+          closed!(bundle, BUNDLE_KEYS)
+          unless bundle["filename"] == "#{value['mutation_id']}.prepared.bundle" && bundle["bytes"].is_a?(Integer) && bundle["bytes"].between?(1, MAX_BUNDLE) && bundle["sha256"].is_a?(String) && bundle["sha256"].match?(SHA)
+            raise Error, "Retained bundle reference differs"
+          end
+          value
+        rescue JSON::ParserError, KeyError, TypeError
+          raise Error, "Retained launch definition is invalid"
+        end
+
+        def verify_bundle!(document, bytes)
+          ref = document.fetch("prepared_bundle")
+          raise Error, "Retained bundle bytes differ" unless bytes.is_a?(String) && bytes.bytesize == ref.fetch("bytes") && Digest::SHA256.hexdigest(bytes) == ref.fetch("sha256")
+          # One instance-owned proof for the last exact admitted input. Every
+          # caller still validates the closed document and freshly held bytes;
+          # a new owner or any tuple/content change requires actual admission.
+          key = JSON.generate(document)
+          raise Error, "Retained launch request exceeds bound" if key.bytesize > MAX_REQUEST
+          return if @admitted_key == key
+          reference = JSON.parse(document.fetch("definition_bytes")).fetch("prepared_work")
+          work = Ace::Assign::Authority::PreparedWork.admit(bytes: bytes, head: reference.fetch("prepared_head"), tree: reference.fetch("prepared_tree"), sha256: ref.fetch("sha256"), size: ref.fetch("bytes"), root: @root)
+          unless work.definition_bytes(head: reference.fetch("prepared_head"), tree: reference.fetch("prepared_tree")) == document.fetch("definition_bytes")
+            raise Error, "Retained prepared definition differs"
+          end
+          @admitted_key = key.freeze
+        rescue ArgumentError, Ace::Assign::AttemptErrors::ReceiptRejected => error
+          raise Error, "Retained prepared work is invalid: #{error.message}"
+        end
+
+        def held_read(path, limit)
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+            before = file.stat
+            unless before.file? && before.uid == Process.uid && (before.mode & 0077).zero? && before.size.between?(1, limit)
+              raise Error, "Retained input is not a bounded private regular file"
+            end
+            bytes = file.read(limit + 1)
+            after = file.stat
+            fields = %i[dev ino mode uid gid size mtime ctime]
+            unless fields.all? { |field| before.public_send(field) == after.public_send(field) } && bytes.bytesize == before.size
+              raise Error, "Retained input changed during held read"
+            end
+            bytes
+          end
+        end
+
+        def write_exclusive(path, bytes)
+          File.open(path, File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0600) do |file|
+            file.write(bytes)
+            file.flush
+            file.fsync
+          end
+        end
+
+        def closed!(value, keys)
+          raise Error, "Retained launch fields differ" unless value.is_a?(Hash) && value.keys.all? { |key| key.is_a?(String) } && value.keys.sort == keys
+        end
+
+        def freeze_value(value)
+          case value
+          when Hash then value.each { |key, item| freeze_value(key); freeze_value(item) }
+          when Array then value.each { |item| freeze_value(item) }
+          end
+          value.freeze
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/molecules/original_launch_child.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/assign/cli"
+require "ace/runtime/molecules/process_identity"
+require_relative "proposal_tick"
+require_relative "../organisms/launch_recovery"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Own one foreground child of the already loaded fixed Assign CLI. The
+      # process boundary is injected in controlled tests, never selected by input.
+      class OriginalLaunchChild
+        LIMIT = 16_384
+        DEADLINE = 30
+        DRAIN_LIMIT = 65_536
+        READY_FIELDS = %w[assignment_id attempt_id generation journal_commit mapping_id original_binding_digest type version].sort.freeze
+        class ProcessBoundary
+          def supported? = Process.respond_to?(:fork)
+          def pipe = IO.pipe
+          def fork_loaded(argv:, reader:, writer:)
+            Process.fork do
+              reader.close
+              STDOUT.reopen(writer)
+              writer.close
+              $stdout = STDOUT
+              begin
+                code = Ace::Assign::CLI.start(argv)
+                Process.exit!(code.is_a?(Integer) ? code : 0)
+              rescue SystemExit => error
+                Process.exit!(error.status)
+              rescue Exception => error
+                warn "Original Assign child failed (#{error.class}): #{error.message}"
+                Process.exit!(1)
+              end
+            end
+          end
+          def wait(pid) = Process.waitpid2(pid, Process::WNOHANG)
+          def readable?(reader, timeout) = !!IO.select([reader], nil, nil, timeout)
+        end
+
+        attr_reader :pid, :identity, :state, :error, :ready, :exit_status
+
+        def initialize(process: ProcessBoundary.new, kernel: Ace::Runtime::Molecules::ProcessIdentity.new,
+          threads: -> { Thread.list }, quiescent: -> { ProposalTick.quiescent? },
+          clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          @process, @kernel, @threads, @quiescent, @clock = process, kernel, threads, quiescent, clock
+          @state = "not_started"
+        end
+
+        def start(request:, definition_path:, bundle_path:)
+          raise Error, "Original child already selected" unless state == "not_started"
+          raise Error, "Loaded CLI fork is unsupported" unless @process.supported?
+          safe_boundary!
+          argv = ["authority", "launch", "--mapping", request.fetch("mapping_id"), "--assignment", request.fetch("assignment_id"),
+            "--definition", definition_path, "--prepared-bundle", bundle_path, "--step", request.fetch("scope"),
+            "--base-head", request.fetch("base_head"), "--mutation", request.fetch("mutation_id")].freeze
+          @request = request
+          @reader, writer = @process.pipe
+          opened_here = true
+          safe_boundary!
+          @readiness_deadline = @clock.call + DEADLINE
+          @pid = @process.fork_loaded(argv: argv, reader: @reader, writer: writer)
+          started_here = true
+          @state = "awaiting_ready"
+          writer.close
+          @identity = @kernel.capture(pid)
+          if identity
+            identity.each_value(&:freeze)
+            identity.freeze
+          end
+          uncertain!("Original child birth is unavailable") unless identity
+          self
+        rescue StandardError, NotImplementedError
+          if started_here
+            uncertain!("Original child startup observation failed")
+            self
+          else
+            @reader&.close if opened_here
+            raise
+          end
+        ensure
+          writer&.close unless writer&.closed?
+        end
+
+        def await_ready(status:)
+          return self unless state == "awaiting_ready"
+          bytes = +"".b
+          loop do
+            remaining = @readiness_deadline - @clock.call
+            return uncertain!("Original child readiness timed out") unless remaining.positive? && @process.readable?(@reader, remaining)
+            chunk = @reader.read_nonblock(LIMIT + 1 - bytes.bytesize, exception: false)
+            next if chunk == :wait_readable
+            return uncertain!("Original child ended before readiness") if chunk.nil?
+            return uncertain!("Original child readiness timed out after receipt") unless @clock.call < @readiness_deadline
+            bytes << chunk
+            return uncertain!("Original child readiness exceeds bound") if bytes.bytesize > LIMIT
+            next unless bytes.include?("\n")
+            return uncertain!("Original child readiness has extra output") unless bytes.end_with?("\n") && bytes.count("\n") == 1
+            text = bytes.dup.force_encoding(Encoding::UTF_8)
+            raise Error, "Original child readiness is not UTF-8" unless text.valid_encoding?
+            ready = JSON.parse(text, create_additions: false, max_nesting: 32, allow_duplicate_key: false, allow_comments: false)
+            unless ready.is_a?(Hash) && ready.keys.sort == READY_FIELDS && ready["version"].is_a?(Integer) && ready["version"] == 1 &&
+                ready["type"] == "launch_ready" && ready.values_at("mapping_id", "assignment_id") == @request.values_at("mapping_id", "assignment_id") &&
+                @kernel.capture(pid) == identity
+              raise Error, "Original child readiness differs from original selection"
+            end
+            return uncertain!("Original child readiness timed out before canonical join") unless @clock.call < @readiness_deadline
+            canonical = status.join_ready!(project: @request.fetch("project_id"), agent: @request.fetch("mapping_id"), ready: ready)
+            Organisms::LaunchRecovery.verify_original!(request: @request, row: canonical.fetch("item"))
+            return uncertain!("Original child readiness timed out during canonical join") unless @clock.call < @readiness_deadline
+            raise Error, "Original child birth changed during readiness join" unless @kernel.capture(pid) == identity
+            ready.each_value(&:freeze)
+            @ready = ready.freeze
+            @state = "ready"
+            return self
+          end
+        rescue StandardError => error
+          uncertain!("Original child readiness unavailable: #{error.message}")
+        end
+
+        # No lifetime deadline, replacement, signal or detached waiter. Reaping
+        # this exact owned child is observation, never canonical release proof.
+        def observe
+          return self unless pid && state != "exited"
+          if %w[ready uncertain].include?(state) && @process.readable?(@reader, 0)
+            # Discard at most one bounded chunk per observation, including
+            # uncertain children. Never retain arbitrary output or let an
+            # ignored stdout pipe deadlock the same original foreground owner.
+            extra = @reader.read_nonblock(DRAIN_LIMIT, exception: false)
+            uncertain!("Original child emitted output outside readiness") if extra.is_a?(String) && !extra.empty?
+          end
+          result = @process.wait(pid)
+          if result
+            raise Error, "Wait selected a different child" unless result.first == pid
+            @exit_status = result.last
+            @reader.close unless @reader.closed?
+            @state = "exited"
+          elsif identity && @kernel.capture(pid) != identity
+            uncertain!("Original child birth is no longer observable")
+          end
+          self
+        rescue StandardError => error
+          uncertain!("Original child observation unavailable: #{error.message}")
+        end
+
+        private
+
+        def safe_boundary!
+          live = @threads.call.select(&:alive?)
+          unless live == [Thread.current] && @quiescent.call
+            raise Error, "Loaded CLI fork requires one quiescent coordinator thread with no held coordination lock"
+          end
+        end
+
+        def uncertain!(message)
+          @error = message
+          @state = "uncertain"
+          self
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/molecules/proposal_tick.rb

@@ -1,26 +1,54 @@
 # frozen_string_literal: true
 
-require "open3"
 require "json"
+require "ace/herdr/molecules/bounded_process"
 
 module Ace
   module Overseer
     module Molecules
-      # The living overseer invokes the deterministic policy evaluator.
-      # No timers, effect retries or executor live in this process.
+      # One bounded policy wake. These process-local active markers coalesce
+      # callers; they never retain proposal outcomes or grant permission.
       class ProposalTick
-        def initialize(runner: Open3, binary: "/usr/local/bin/ace-hitl", socket: ENV["ACE_HITL_SOCKET"], project: ENV["ACE_HITL_PROJECT"])
+        DEADLINE = 5
+        LIMIT = 65_536
+        @mutex = Mutex.new
+        @active = {}
+
+        def self.quiescent?
+          return false if @mutex.owned?
+          @mutex.synchronize { @active.empty? }
+        end
+
+        def self.acquire(key)
+          @mutex.synchronize do
+            return false if @active.key?(key)
+            @active[key] = true
+          end
+        end
+
+        def self.release(key)
+          @mutex.synchronize { @active.delete(key) }
+        end
+
+        def initialize(runner: Ace::Herdr::Molecules::BoundedProcess, binary: "/usr/local/bin/ace-hitl", socket: ENV["ACE_HITL_SOCKET"], project: ENV["ACE_HITL_PROJECT"])
           @runner, @binary, @socket, @project = runner, binary, socket, project
         end
 
         def call
           return [] if @socket.to_s.empty? || @project.to_s.empty?
-          out, _err, status = @runner.capture3({"ACE_HITL_SOCKET" => @socket},
-            @binary, "proposal", "resolve-due", "--project", @project)
-          raise Error, "Proposal resolution unavailable; deadlines deferred" unless status.success?
-          JSON.parse(out)
-        rescue JSON::ParserError, SystemCallError
+          key = [@binary, @socket, @project].map { |value| value.to_s.dup.freeze }.freeze
+          return [] unless self.class.acquire(key)
+          acquired = true
+          result = @runner.call([{"ACE_HITL_SOCKET" => @socket}, @binary, "proposal", "resolve-due", "--project", @project],
+            timeout_s: DEADLINE, output_limit: LIMIT, stderr_limit: LIMIT, cleanup_group: true)
+          raise Error, "Proposal resolution unavailable; deadlines deferred" unless result.status&.success? && !result.oversized
+          value = JSON.parse(result.stdout)
+          raise Error, "Proposal resolution malformed; deadlines deferred" unless value.is_a?(Array) && value.all? { |item| item.is_a?(Hash) }
+          value
+        rescue JSON::ParserError, SystemCallError, Timeout::Error, Ace::Herdr::Molecules::BoundedProcess::PostLaunchError
           raise Error, "Proposal resolution unavailable; deadlines deferred"
+        ensure
+          self.class.release(key) if acquired
         end
       end
     end

data/lib/ace/overseer/molecules/protected_selection.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "ace/lab"
+require "ace/assign/authority/deployment"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Visibility narrows the installed project pool; it never grants authority.
+      class ProtectedSelection
+        def initialize(topology: nil, deployment_loader: nil)
+          @topology = topology || Ace::Lab::Organisms::TopologyService.from_config
+          @deployment_loader = deployment_loader || -> { Ace::Assign::Authority::Deployment.load }
+        end
+
+        def call(project:, agent: nil)
+          token!(project)
+          token!(agent) if agent
+          topology = @topology.agents(project: project)
+          raise Error, "Protected topology unavailable (#{topology.error_code})" unless topology.ok?
+          deployment = @deployment_loader.call
+          pool = deployment.data.fetch("launch_mappings").select { |_id, map| map.fetch("project_id") == project }.keys.sort
+          raise Error, "Protected project has no provisioned mappings" if pool.empty?
+          visible = topology.data.fetch("agents")
+          unless visible.is_a?(Array) && visible.all? { |entry| entry.is_a?(Hash) && entry["project"] == project && pool.include?(entry["id"]) } &&
+              visible.map { |entry| entry.fetch("id") }.uniq.size == visible.size
+            raise Error, "Public agent visibility differs from protected project mappings"
+          end
+          ids = visible.map { |entry| entry.fetch("id") }.sort
+          if agent && !ids.include?(agent)
+            raise Error, "Requested protected agent is not visible in this project"
+          end
+          [deployment, pool.freeze, ids.freeze].freeze
+        rescue KeyError, TypeError, NoMethodError
+          raise Error, "Protected selection metadata is malformed"
+        end
+
+        private
+
+        def token!(value)
+          raise Error, "Protected identity is invalid" unless value.is_a?(String) && value.match?(Ace::Assign::Authority::Deployment::TOKEN)
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/molecules/window_opener.rb

@@ -15,9 +15,9 @@ module Ace
           @env = env
         end
 
-        def open(worktree_path:, preset: nil)
+        def open(worktree_path:, preset: nil, runtime: nil)
           name = Ace::Runtime.sanitize_name(File.basename(worktree_path.to_s))
-          adapter.ensure_window(
+          selected_adapter(runtime).ensure_window(
             name: name,
             root: File.expand_path(worktree_path.to_s),
             preset: preset
@@ -31,6 +31,13 @@ module Ace
 
         attr_reader :config, :env
 
+        def selected_adapter(runtime)
+          return adapter if runtime.nil? || @runtime
+          Ace::Runtime::Molecules::RuntimeSelector.new(
+            config: {runtime: Atoms::RuntimeSetting.normalize(runtime)}, env: env
+          ).resolve
+        end
+
         def adapter
           @adapter ||= @runtime || Ace::Runtime::Molecules::RuntimeSelector.new(
             config: {runtime: Atoms::RuntimeSetting.normalize(config["runtime"])},

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/launch_request"
+require_relative "protected_status"
+
+module Ace
+  module Overseer
+    module Organisms
+      # Canonical discovery only. Missing input or missing attribution never
+      # authorizes replacement, registration, upload, cleanup or a new launch.
+      class LaunchRecovery
+        def initialize(status: nil, request_factory: nil)
+          @status = status || ProtectedStatus.new
+          @request_factory = request_factory || ->(root) { Molecules::LaunchRequest.new(root: root) }
+        end
+
+        # Shared readiness/recovery association. A valid canonical row is not
+        # enough: it must belong to this retained invocation and exact inputs.
+        def self.verify_original!(request:, row:)
+          reference = JSON.parse(request.fetch("definition_bytes")).fetch("prepared_work")
+          bundle = request.fetch("prepared_bundle")
+          expected = {"assignment_id" => request.fetch("assignment_id"), "task_id" => request.fetch("task_id"),
+            "scope" => request.fetch("scope"), "base_head" => request.fetch("base_head"),
+            "reservation_mutation_id" => request.fetch("mutation_id") + "-reserve",
+            "definition_digest" => request.fetch("definition_sha256"), "selection_sha256" => reference.fetch("selection_sha256"),
+            "prepared_bundle_bytes" => bundle.fetch("bytes"), "prepared_bundle_sha256" => bundle.fetch("sha256"),
+            "prepared_bundle_ref" => "execution/prepared/#{request.fetch('assignment_id')}-#{bundle.fetch('sha256')}.bundle"}
+          unless expected.all? { |key, value| row.fetch(key) == value && row.fetch(key).class == value.class }
+            raise Error, "Retained invocation differs from original reservation"
+          end
+          row
+        rescue KeyError, TypeError, JSON::ParserError
+          raise Error, "Retained invocation association is malformed"
+        end
+
+        def call(path:)
+          path = File.expand_path(path)
+          owner = @request_factory.call(File.dirname(path))
+          request = owner.load(path)
+          availability = owner.bundle_availability(request)
+          definition_availability = owner.definition_availability(request)
+          snapshot = @status.collect(project: request.fetch("project_id"), agent: request.fetch("mapping_id"))
+          mapping = snapshot.fetch("agents").find { |entry| entry.fetch("agent_id") == request.fetch("mapping_id") }
+          raise Error, "Retained invocation canonical inventory is unavailable" unless mapping && mapping.fetch("status") == "ok"
+          inventory = mapping.fetch("inventory")
+          reference = JSON.parse(request.fetch("definition_bytes")).fetch("prepared_work")
+          bundle = request.fetch("prepared_bundle")
+          matches = inventory.fetch("items").select do |row|
+            row.fetch("reservation_mutation_id") == request.fetch("mutation_id") + "-reserve"
+          end
+          raise Error, "Retained invocation reservation is ambiguous" if matches.size > 1
+          row = matches.first
+          self.class.verify_original!(request: request, row: row) if row
+          {"request_path" => path, "project_id" => request.fetch("project_id"), "mapping_id" => request.fetch("mapping_id"),
+            "assignment_id" => request.fetch("assignment_id"), "mutation_id" => request.fetch("mutation_id"),
+            "definition_sha256" => request.fetch("definition_sha256"), "selection_sha256" => reference.fetch("selection_sha256"),
+            "prepared_bundle" => bundle, "local_bundle" => availability, "local_definition" => definition_availability,
+            "attribution" => row ? "original_reservation" : "unattributed", "journal_commit" => inventory.fetch("journal_commit"), "item" => row}
+        rescue KeyError, TypeError, JSON::ParserError
+          raise Error, "Retained invocation recovery metadata is malformed"
+        end
+      end
+    end
+  end
+end