ace-overseer 0.28.1 → 0.30.0

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

@@ -2,14 +2,16 @@
 
 require "digest"
 require "json"
+require_relative "../atoms/observation_sources"
+require "ace/herdr/molecules/herdr_executor"
 
 module Ace
   module Overseer
     module Molecules
       # Standing local-state observation (task 8xs.t.pu0.3): projects the
-      # six local source classes the started overseer watches — project
+      # local source classes the started overseer watches — project
       # tasks, private _overseer tasks, worktrees, coworker availability,
-      # assignment progress and HITL events — each read from its STATE
+      # assignment progress, project sessions and HITL events — each read from its STATE
       # OWNER (ace-task, ace-git-worktree, ace-coworker probe, ace-assign
       # inventory, ace-hitl). This molecule owns no second state: every
       # row is a {key, revision, type} projection whose revision changes
@@ -21,12 +23,18 @@ module Ace
       # (an identical repeated failure never re-wakes; a new failure mode
       # wakes once), while the healthy sources keep projecting.
       class LocalSources
-        def initialize(task_manager: nil, worktree_manager: nil, probe_factory: nil)
+        EXECUTOR_ROLES = %w[worker verifier integrator].freeze
+
+        def initialize(task_manager: nil, worktree_manager: nil, probe_factory: nil, project_sessions: nil,
+          herdr: Ace::Herdr::Molecules::HerdrExecutor.new, env: ENV)
           @tasks = task_manager || Ace::Task::Organisms::TaskManager.new
           @worktrees = worktree_manager || Ace::Git::Worktree::Organisms::WorktreeManager.new
           @probe_factory = probe_factory || ->(path) {
             Ace::Coworker::Molecules::WorktreeExecutorProbe.new(project_root: path)
           }
+          @project_sessions = project_sessions || ProjectSessions.new
+          @herdr = herdr
+          @env = env
         end
 
         # @return [Hash] {"events" => Array<{key, revision, type, ...}>,
@@ -35,10 +43,25 @@ module Ace
           sources = {}
           events = []
 
-          collect(sources, events, "project_tasks") { project_task_events }
-          collect(sources, events, "overseer_tasks") { overseer_task_events }
-          collect(sources, events, "worktrees") { worktree_events }
-          collect(sources, events, "coworkers") { coworker_events }
+          collect(sources, events, Atoms::ObservationSources::PROJECT_TASKS) { project_task_events }
+          overseer_tasks = []
+          collect(sources, events, Atoms::ObservationSources::OVERSEER_TASKS) do
+            overseer_tasks = @tasks.list(in_folder: "_overseer")
+            task_events(overseer_tasks, "overseer-task")
+          end
+          collect(sources, events, Atoms::ObservationSources::WORKTREES) { worktree_events }
+          collect(sources, events, Atoms::ObservationSources::COWORKERS) { coworker_events(overseer_tasks) }
+          if @project_sessions.configured?
+            collect(sources, events, Atoms::ObservationSources::PROJECT_SESSIONS) { @project_sessions.call }
+            failed_sessions = events.select { |event| event["type"] == "project-session" && event["state"] == "unavailable" }
+            unless failed_sessions.empty?
+              sources[Atoms::ObservationSources::PROJECT_SESSIONS] = {"status" => "degraded", "error" => "one or more configured project sessions are unavailable"}
+              failures = failed_sessions.map { |event| [event.fetch("key"), event.fetch("revision")] }.sort
+              events << {"key" => "source:project_sessions", "revision" => revision(failures),
+                         "type" => "source-health", "status" => "degraded",
+                         "error" => "one or more configured project sessions are unavailable"}
+            end
+          end
 
           {"events" => events, "sources" => sources}
         end
@@ -73,10 +96,6 @@ module Ace
           task_events(@tasks.list(in_folder: "next"), "task")
         end
 
-        def overseer_task_events
-          task_events(@tasks.list(in_folder: "_overseer"), "overseer-task")
-        end
-
         # Task rows revision on real lifecycle facts (status, dependency
         # set, subtask statuses) — not on cosmetic frontmatter churn.
         def task_events(tasks, type)
@@ -108,23 +127,30 @@ module Ace
         # ids, never pane names), the ActiveExecutorRule decides live vs
         # stale, and each in-flight assignment projects its own progress
         # row so a step report revises that assignment only.
-        def coworker_events
+        def coworker_events(overseer_tasks)
           result = @worktrees.list_all
           raise Error, result[:error] || "failed to list worktrees" unless result[:success]
 
-          Array(result[:worktrees]).reject(&:bare).flat_map do |worktree|
+          worktrees = Array(result[:worktrees]).reject(&:bare)
+          native = !worktrees.empty? && (@env["ACE_RUNTIME"] == "herdr" || !@env["HERDR_PANE_ID"].to_s.empty? || !@env["HERDR_PANE"].to_s.empty?)
+          sessions = native ? executor_sessions : {}
+          bindings = native ? executor_bindings(overseer_tasks) : {}
+          worktrees.flat_map do |worktree|
             probe = @probe_factory.call(worktree.path)
             report = probe.probe(worktree.path)
             verdict = Ace::Coworker::Atoms::ActiveExecutorRule.evaluate(
               config: report[:config], assignments: report[:assignments]
             )
             identity = Digest::SHA256.hexdigest(worktree.path)
-            executor = {"key" => "executor:#{identity}",
-                        "revision" => revision({"path" => worktree.path,
-                                                "active" => verdict[:active],
-                                                "evidence" => verdict[:evidence]}),
-                        "type" => "executor", "path" => worktree.path,
-                        "active" => verdict[:active], "evidence" => verdict[:evidence]}
+            visible = sessions.fetch(worktree.path, [])
+            completed = report[:assignments].filter_map { |row| row["id"] if row["state"] == "completed" }
+            missing = bindings.fetch(worktree.path, []).reject do |binding|
+              completed.include?(binding["assignment"]) || visible.any? { |session| session["terminal"] == binding["terminal"] }
+            end
+            payload = {"path" => worktree.path, "active" => verdict[:active],
+              "evidence" => verdict[:evidence], "sessions" => visible, "missing_sessions" => missing}
+            executor = {"key" => "executor:#{identity}", "revision" => revision(payload),
+              "type" => "executor"}.merge(payload)
             assignments = report[:assignments].map do |assignment|
               {"key" => "assignment:#{assignment["id"]}",
                "revision" => revision({"id" => assignment["id"], "state" => assignment["state"],
@@ -135,6 +161,44 @@ module Ace
             [executor] + assignments
           end
         end
+
+        # A coordinator's durable binding also detects a session that
+        # started and exited between two native observations.
+        def executor_bindings(tasks)
+          tasks.flat_map { |task| [task, *Array(task.subtasks)] }.filter_map do |step|
+            next if %w[done canceled cancelled].include?(step.status)
+
+            metadata = step.metadata || {}
+            worktree, assignment, terminal = metadata.values_at("worktree", "assignment", "terminal")
+            next unless worktree.is_a?(String) && worktree.start_with?("/") &&
+              assignment.is_a?(String) && assignment.match?(/\A[a-zA-Z0-9_-]+\z/) &&
+              terminal.is_a?(String) && terminal.match?(/\Aterm_[0-9a-f]+\z/)
+
+            [worktree, {"task" => step.id, "assignment" => assignment, "terminal" => terminal}]
+          end.group_by(&:first).transform_values { |rows| rows.map(&:last).sort_by { |row| row.fetch("task") } }
+        end
+
+        # Native sessions can disappear without writing an assignment report.
+        # Project their presence on the existing stable worktree row so that
+        # even an interruption before the first assignment step is visible.
+        def executor_sessions
+          response = @herdr.agent_list.parsed_json
+          agents = response.is_a?(Hash) && !response.key?("error") && response.dig("result", "agents")
+          raise Error, "native executor inventory is unavailable" unless agents.is_a?(Array)
+
+          sessions = Hash.new { |index, cwd| index[cwd] = [] }
+          agents.each do |agent|
+            next unless agent.is_a?(Hash) && agent["name"].to_s.start_with?("coworker-")
+
+            terminal, cwd = agent.values_at("terminal_id", "cwd")
+            unless terminal.is_a?(String) && terminal.match?(/\Aterm_[0-9a-f]+\z/) &&
+                cwd.is_a?(String) && cwd.start_with?("/")
+              raise Error, "executor session identity is invalid"
+            end
+            sessions[cwd] << {"terminal" => terminal, "agent" => agent["name"]}
+          end
+          sessions.transform_values { |rows| rows.sort_by { |row| row.fetch("terminal") } }
+        end
       end
     end
   end

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

@@ -144,7 +144,7 @@ module Ace
           unless report.is_a?(Hash) && report["scope"] == "project" && report["status"].is_a?(String)
             raise Ace::Overseer::Error, "project start returned no project-scope report"
           end
-          if !status.success? && %w[started reused ready].include?(report["status"])
+          if !status.success? && %w[started reused ready].include?(report["status"]) && report["prompt_failed"] != true
             raise Ace::Overseer::Error, "project start exited #{status.exitstatus} despite a ready report"
           end
           report

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+require "digest"
+require "json"
+require_relative "../atoms/observation_sources"
+require "ace/lab/molecules/install_manifest_loader"
+require "ace/herdr/molecules/bounded_process"
+require "ace/support/cli/toolchain"
+require_relative "session_environment"
+
+module Ace::Overseer::Molecules
+  # The lab reads the same public projection as each configured project.
+  # Tasks, reports and assignments remain in that project's existing owners.
+  class ProjectObservations
+    BUDGET_SECONDS = 20
+    def initialize(root: Dir.pwd, env: ENV, loader: -> { Ace::Lab::Molecules::InstallManifestLoader.load },
+      runner: Ace::Herdr::Molecules::BoundedProcess.method(:call),
+      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, environment: nil)
+      @root, @env, @loader, @runner, @clock = root, env, loader, runner, clock
+      @environment = environment || SessionEnvironment.new(env: env, manifest_loader: loader)
+    end
+
+    def call(owner:, scope:, limit:)
+      empty = {"events" => [], "sources" => {}}
+      return empty unless @env["ACE_TOOLCHAIN"] == "installed" &&
+        File.exist?(Ace::Lab.install_manifest_path)
+      document = @loader.call
+      return empty unless document.dig("coordinator", "path") == File.realpath(@root)
+      events, sources = [], {}
+      deadline = @clock.call + BUDGET_SECONDS
+      document.fetch("projects").each do |project|
+        id, root = project.values_at("id", "path")
+        source = "project:#{id}"
+        begin
+          raise Ace::Overseer::Error, "project root is not canonical" unless root != @root && File.realpath(root) == root
+          remaining = deadline - @clock.call
+          raise Timeout::Error, "project observation budget exhausted" unless remaining.positive?
+          result = @runner.call([Ace::Support::Cli::Toolchain.executable("ace-overseer"), "observe",
+            "--owner", owner, "--scope", scope, "--limit", limit.to_s],
+            environment: @environment.observation_environment(root: root),
+            chdir: root, timeout_s: remaining, output_limit: 2_097_152, cleanup_group: true)
+          raise Ace::Overseer::Error, "project observation failed" unless result.status.success? && !result.oversized
+          value = JSON.parse(result.stdout)
+          unless value["schema"] == "ace.hitl.observation/v1" && value["events"].is_a?(Array) &&
+              value["settled"].is_a?(Array) && value["sources"].is_a?(Hash) &&
+              (Ace::Overseer::Atoms::ObservationSources::REQUIRED - value["sources"].keys).empty?
+            raise Ace::Overseer::Error, "project observation is incomplete"
+          end
+          rows = (value.fetch("events") + value.fetch("settled")).map do |row|
+            unless row.is_a?(Hash) && %w[key revision id type].all? { |key| row[key].is_a?(String) }
+              raise Ace::Overseer::Error, "project event is incomplete"
+            end
+            row.merge("key" => Digest::SHA256.hexdigest("#{root}:#{row.fetch('key')}"),
+              "project" => id, "project_root" => root, "owner_key" => row.fetch("key"))
+          end
+          health = value.fetch("sources").to_h do |name, state|
+            unless name.is_a?(String) && name.match?(/\A[a-zA-Z0-9_.:-]{1,64}\z/) &&
+                state.is_a?(Hash) && %w[ok degraded].include?(state["status"])
+              raise Ace::Overseer::Error, "project source health is incomplete"
+            end
+            ["#{source}:#{name}", state]
+          end
+          events.concat(rows)
+          sources.merge!(health)
+          sources[source] = {"status" => "ok"}
+          events << project_health(root, id, "ok")
+        rescue StandardError => error
+          sources[source] = {"status" => "degraded", "error" => error.class.name}
+          events << project_health(root, id, "degraded", error.class.name)
+        end
+      end
+      {"events" => events, "sources" => sources}
+    end
+
+    private
+
+    def project_health(root, id, status, revision = status)
+      key = Digest::SHA256.hexdigest("#{root}:project-observation")
+      {"key" => key, "id" => key, "revision" => Digest::SHA256.hexdigest(revision),
+       "type" => "source-health", "status" => status, "project" => id, "project_root" => root}
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "ace/lab"
+require "ace/herdr"
+require "digest"
+require "json"
+require_relative "project_root_resolver"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Project locations and terminal sessions remain owned by ace-lab and
+      # herdr. This projection has no persisted copy of either.
+      class ProjectSessions
+        def initialize(root: Dir.pwd, control: nil, locations: Ace::Lab::Molecules::ProjectLocations,
+          root_resolver: ProjectRootResolver.new, executor: Ace::Herdr::Molecules::HerdrExecutor.new, env: ENV)
+          @root = File.realpath(root)
+          @control = control || Ace::Herdr::Organisms::ControlSurface.new
+          @locations = locations
+          @root_resolver = root_resolver
+          @executor, @env = executor, env
+        end
+
+        def configured?
+          File.file?(File.join(@root, ".ace/lab/config.yml"))
+        end
+
+        def call
+          return [] unless configured?
+
+          projects = @locations.read(@root)
+          return [] if projects.empty?
+
+          seen = {}
+          failures = []
+          resolved = projects.filter_map do |project|
+            begin
+              path = project.fetch("path")
+              raise Error, "project has no configured path" if path.to_s.empty?
+              canonical = File.realpath(path, @root)
+              next if canonical == @root
+              canonical = @root_resolver.resolve(cwd: canonical)
+              next if canonical == @root
+              raise Error, "multiple projects use the same root" if seen[canonical]
+
+              seen[canonical] = true
+              [project.fetch("id"), canonical, project]
+            rescue StandardError => e
+              failures << unavailable_row(project, e)
+              nil
+            end
+          end
+          return failures if resolved.empty?
+
+          tabs = @control.list_tabs
+          panes = @control.list_panes
+          failures + resolved.map do |id, root, project|
+            begin
+              project_row(id, root, tabs, panes)
+            rescue StandardError => e
+              unavailable_row(project, e)
+            end
+          end
+        end
+
+        private
+
+        def unavailable_row(project, error)
+          identity = Digest::SHA256.hexdigest(JSON.generate([project["id"], project["path"]]))
+          payload = {"project" => project["id"], "state" => "unavailable", "error" => "#{error.class}: #{error.message}"}
+          {"key" => "project-session-error:#{identity}",
+           "revision" => Digest::SHA256.hexdigest(JSON.generate(payload)),
+           "type" => "project-session"}.merge(payload)
+        end
+
+
+        def project_row(id, root, tabs, panes)
+          label = Atoms::StartContract.session_label(root)
+          owners = tabs.select { |tab| tab[:title] == label }.flat_map do |tab|
+            matches = panes.select { |pane| pane[:tab] == tab[:id] }
+            raise Error, "project overseer tab has no unique pane: #{label}" unless matches.length == 1
+            matches
+          end
+          raise Error, "project overseer has ambiguous sessions: #{label}" if owners.length > 1
+          pane = owners.first
+          raise Error, "project overseer session did not report a working directory: #{label}" if pane && pane[:cwd].to_s.empty?
+          if pane && @root_resolver.resolve(cwd: pane[:cwd]) != root
+            raise Error, "project overseer session has a different root: #{label}"
+          end
+          state = pane ? (pane[:agent_status] || "unknown").to_s : "absent"
+          payload = {"project" => id, "root" => root, "pane" => pane && pane[:id], "state" => state}
+          {"key" => "project-session:#{Digest::SHA256.hexdigest(root)}",
+           "revision" => Digest::SHA256.hexdigest(JSON.generate(payload)),
+           "type" => "project-session"}.merge(payload)
+        end
+      end
+    end
+  end
+end

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

@@ -6,12 +6,10 @@ require "json"
 module Ace
   module Overseer
     module Molecules
-      # Remote PR/repo observation (task 8xs.t.pu0.4): projects configured
-      # pull requests through the EXISTING forge provider adapters
+      # Remote issue and PR observation through the existing forge adapters
       # (Ace::Git::Providers.for — Forgejo and GitHub; no separate HTTP
-      # client here). Observed PRs come from the project's own
-      # configuration (`observe.remote.pull_requests` in the overseer
-      # cascade) — never a scan of every accessible account.
+      # client here). Observed repositories and PRs come from the project's
+      # own configuration — never a scan of every accessible account.
       #
       # Rows follow the standing-observation contract of LocalSources:
       # stable key + SEMANTIC revision (state, head SHA, review/comment
@@ -26,6 +24,8 @@ module Ace
       # class wakes once per failure mode, never as an empty healthy
       # list — and recovery re-observes the real state.
       class RemoteSources
+        ISSUE_LIMIT = 500
+
         def initialize(provider_factory: nil, timeout: nil)
           @provider_factory = provider_factory || ->(server_name) {
             server = Ace::Git::ServerRegistry.resolve(server_name)
@@ -35,8 +35,9 @@ module Ace
 
         # @param pull_requests [Array<Hash>] {"server" =>, "number" =>}
         #   entries from the project's observe.remote configuration
+        # @param issues [Array<Hash>] {"server" =>} repository entries
         # @return [Hash] {"events" => Array, "sources" => {name => health}}
-        def call(pull_requests:)
+        def call(pull_requests:, issues: [])
           sources = {}
           events = []
 
@@ -46,16 +47,9 @@ module Ace
           valid, invalid = Array(pull_requests).partition do |entry|
             entry.is_a?(Hash) && !entry["server"].to_s.empty? && !entry["number"].to_s.empty?
           end
-          invalid.group_by { |entry| entry.is_a?(Hash) ? entry["server"].to_s : "" }.each do |server, entries|
-            if server.empty?
-              # Non-Hash or server-less entries still surface as health
-              # markers, never silently disappear.
-              sources["observe.remote"] ||= {"state" => "degraded",
-                "reason" => "invalid observe.remote.pull_requests entry: #{entries.first.inspect}"}
-            else
-              sources["pr:#{server}"] ||= {"state" => "degraded",
-                "reason" => "invalid observe.remote.pull_requests entry: #{entries.first.inspect}"}
-            end
+          unless invalid.empty?
+            index = Array(pull_requests).index(invalid.first)
+            collect(sources, events, "pr:configuration") { raise ArgumentError, "invalid observe.remote.pull_requests entry at index #{index}" }
           end
 
           valid.group_by { |entry| entry["server"] }.each do |server, entries|
@@ -64,11 +58,47 @@ module Ace
             end
           end
 
+          Array(issues).each_with_index do |entry, index|
+            unless entry.is_a?(Hash) && entry["server"].is_a?(String) && !entry["server"].strip.empty?
+              unless sources.key?("issues:configuration")
+                collect(sources, events, "issues:configuration") { raise ArgumentError, "invalid observe.remote.issues entry at index #{index}" }
+              end
+              next
+            end
+
+            server = entry["server"]
+            next if sources.key?("issues:#{server}")
+
+            collect(sources, events, "issues:#{server}") { [issue_snapshot(server)] }
+          end
+
           {"events" => events, "sources" => sources}
         end
 
         private
 
+        # A single collection revision also detects a closed/deleted issue,
+        # which would simply disappear if each open issue had its own row.
+        # Refuse a truncated collection instead of silently missing work. The
+        # provider must paginate completely and return min(limit, total).
+        def issue_snapshot(server)
+          provider = @provider_factory.call(server)
+          unless provider.respond_to?(:recent_issues)
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "the selected provider has no issue-listing API; issues are unavailable, not empty"
+          end
+          issues = provider.recent_issues(limit: ISSUE_LIMIT + 1)
+          raise ArgumentError, "too many open issues to observe completely" if issues.length > ISSUE_LIMIT
+
+          items = issues.map do |issue|
+            {"number" => issue.number, "title" => issue.title, "body" => issue.body, "state" => issue.state.to_s,
+             "author" => issue.author, "url" => issue.url, "labels" => Array(issue.labels).map(&:to_s).sort}
+          end.sort_by { |item| item.fetch("number") }
+          {"key" => "issues:#{server}", "revision" => digest(items), "type" => "issues",
+           "forge" => server, "count" => items.length,
+           "issue_numbers" => items.first(20).map { |item| item.fetch("number") }}
+        end
+
         def collect(sources, events, name)
           rows = yield
           sources[name] = {"status" => "ok"}

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "tmpdir"
+require "tempfile"
+require "ace/lab/auth/session_configuration"
+require "ace/support/cli/toolchain"
+
+module Ace::Overseer::Molecules
+  # Passive deployment data becomes an explicit environment for one ordinary
+  # child. Files here are transient credentials, not a session state store.
+  class SessionEnvironment
+    BASE_KEYS = %w[HOME USER LOGNAME SHELL TERM LANG LC_ALL TZ TMPDIR PATH GEM_HOME GEM_PATH ACE_TOOLCHAIN
+      HERDR_SOCKET_PATH HERDR_WORKSPACE_ID].freeze
+    RESERVED = %w[ACE_TOOLCHAIN GEM_HOME GEM_PATH PATH PI_CODING_AGENT_DIR ACE_SESSION_CREDENTIALS_DIRECTORY BUNDLE_GEMFILE RUBYOPT RUBYLIB].freeze
+    MAX_BYTES = 65_536
+    ENVIRONMENT_ROLES = {"reviewer" => "verifier", "bootstrap-verifier" => "verifier", "bootstrap-worker" => "worker"}.freeze
+
+    def initialize(env: ENV, manifest_loader: -> { Ace::Lab::Molecules::InstallManifestLoader.load },
+      manifest_path: Ace::Lab.install_manifest_path)
+      @env, @loader, @manifest_path = env, manifest_loader, manifest_path
+    end
+
+    def with_environment(root:, role:)
+      environment = @env.to_h.slice(*BASE_KEYS)
+      directory = nil
+      handed_off = false
+      args = []
+      if @env["ACE_TOOLCHAIN"] == "installed"
+        selection = selection_for(root, role)
+        runtime = selection.runtime
+        args = ["--model", "#{runtime.fetch('provider')}/#{runtime.fetch('model')}"]
+        [runtime.fetch("node"), runtime.fetch("pi")].each do |path|
+          raise Ace::Overseer::Error, "installed runtime executable is unavailable: #{path}" unless File.executable?(path)
+        end
+        directory = Dir.mktmpdir("ace-session-")
+        File.chmod(0o700, directory)
+        provider = runtime.fetch("provider")
+        auth = read_private_json(runtime.fetch("credentials"))
+        raise Ace::Overseer::Error, "model provider credentials are unavailable" unless auth[provider].is_a?(Hash) && !auth[provider].empty?
+        write_private(File.join(directory, "auth.json"), provider => auth.fetch(provider))
+        write_private(File.join(directory, "settings.json"), "defaultProjectTrust" => "never")
+        environment = configured_environment(selection)
+        environment.merge!("PI_CODING_AGENT_DIR" => directory, "ACE_SESSION_CREDENTIALS_DIRECTORY" => directory)
+      else
+        environment.merge!(ProjectBundle.environment(root, env: @env)).compact!
+      end
+      Tempfile.create(["ace-environment-", ".json"]) do |file|
+        file.chmod(0o600)
+        file.write(JSON.generate(environment))
+        file.flush
+        file.fsync
+        handed_off = true
+        yield file.path, directory, args
+      end
+    rescue StandardError
+      FileUtils.remove_entry(directory) if !handed_off && directory && File.directory?(directory)
+      raise
+    end
+
+    # A projection needs this project's read credentials and installed CLI,
+    # not the coordinator's token or a new model-auth directory per poll.
+    def observation_environment(root:)
+      configured_environment(selection_for(root, "project-overseer"))
+    end
+
+    def self.cleanup(directory)
+      return unless directory
+      # Only our exact scratch directory; never a caller's home/config root.
+      unless File.absolute_path(directory) == directory && File.dirname(directory) == Dir.tmpdir.chomp(File::SEPARATOR) &&
+          File.basename(directory).start_with?("ace-session-") && !File.symlink?(directory)
+        raise Ace::Overseer::Error, "invalid session credential directory"
+      end
+      # Pi's transcript may live beside auth.json. Keep execution evidence.
+      File.unlink(File.join(directory, "auth.json")) if File.file?(File.join(directory, "auth.json"))
+    end
+
+    private
+
+    def selection_for(root, role)
+      raise Ace::Overseer::Error, "installed deployment manifest is unavailable" unless File.file?(@manifest_path)
+      document = @loader.call
+      project = ([document["coordinator"]] + document.fetch("projects")).compact.find do |entry|
+        root == entry["path"] || root.start_with?("#{entry['path']}/.ace-wt/")
+      end
+      raise Ace::Overseer::Error, "execution directory is not a configured project" unless project
+      Ace::Lab::Auth::SessionConfiguration.new(loader: -> { document }).resolve(
+        project: project.fetch("id"), role: ENVIRONMENT_ROLES.fetch(role, role))
+    end
+
+    def configured_environment(selection)
+      environment = @env.to_h.slice(*BASE_KEYS)
+      if selection.environment_file
+        values = read_private_json(selection.environment_file)
+        unless values.all? { |key, value| key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/) && value.is_a?(String) && !value.include?("\0") } &&
+            (values.keys & RESERVED).empty? && values.keys.none? { |key| key.start_with?("BUNDLE", "BUNDLER_") }
+          raise Ace::Overseer::Error, "role environment contains invalid or reserved variables"
+        end
+        environment.merge!(values)
+      end
+      runtime = selection.runtime
+      environment.merge("HERDR_SOCKET_PATH" => runtime.fetch("herdr").fetch("socket"),
+        "ACE_TOOLCHAIN" => "installed", "GEM_HOME" => selection.gem_home,
+        "GEM_PATH" => selection.gem_home,
+        "PATH" => ([File.join(selection.gem_home, "bin"), File.dirname(runtime.fetch("node")), File.dirname(runtime.fetch("pi"))] + runtime.fetch("path")).uniq.join(File::PATH_SEPARATOR))
+    end
+
+    def read_private_json(path)
+      File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+        stat = file.stat
+        unless stat.file? && [0, Process.uid].include?(stat.uid) && (stat.mode & 0o777) == 0o600 && stat.size <= MAX_BYTES
+          raise Ace::Overseer::Error, "credential source must be a private regular file"
+        end
+        value = JSON.parse(file.read(MAX_BYTES + 1), create_additions: false, max_nesting: 8)
+        raise Ace::Overseer::Error, "credential source must be a JSON object" unless value.is_a?(Hash)
+        value
+      end
+    rescue JSON::ParserError, SystemCallError
+      raise Ace::Overseer::Error, "configured credential source is unavailable or invalid"
+    end
+
+    def write_private(path, value)
+      File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write(JSON.generate(value)) }
+    end
+  end
+end