ace-overseer 0.30.2 → 0.31.0

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

@@ -76,6 +76,10 @@ module Ace
             verdict = Atoms::ReportInterpretation.evaluate(event: event, managers: managers)
             next false unless verdict[:status] == :duplicate
             manager = managers.find { |task| task.id.to_s == verdict[:manager_ref] }
+            step = Array(manager&.subtasks).find { |candidate| candidate.id.to_s == verdict[:step_ref] } || manager
+            receipt = step&.metadata&.fetch("report_receipt", nil)
+            next false unless receipt.is_a?(Hash) && receipt["key"] == event["key"] &&
+              receipt["revision"] == event["revision"] && receipt["cleanup"] == "complete" && receipt["continuation"] == "complete"
             # A persisted report alone is not proof its continuation ran. Keep
             # active managers eligible after restart; their existing gates reconcile
             # the same attempt. Only completed trees suppress historical reports.

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+require "json"
+require "fileutils"
+require "tempfile"
+
+module Ace::Overseer::Molecules
+  # Start owns the standard session input; Pi owns observation checkpoints.
+  class EyesConfiguration
+    def self.prepare(root:, recipient:)
+      path = File.join(root, ".ace-local/overseer/eyes.json")
+      existing = File.file?(path) ? JSON.parse(File.read(path)) : {}
+      raise Ace::Overseer::Error, "eyes configuration must be an object" unless existing.is_a?(Hash)
+      config = existing.merge("scope" => "all", "recipient" => recipient)
+      FileUtils.mkdir_p(File.dirname(path))
+      Tempfile.create(["eyes-", ".json"], File.dirname(path)) do |file|
+        file.write(JSON.pretty_generate(config) + "\n")
+        file.flush
+        file.fsync
+        File.rename(file.path, path)
+      end
+      path
+    rescue JSON::ParserError, SystemCallError => error
+      raise Ace::Overseer::Error, "cannot prepare eyes configuration: #{error.message}"
+    end
+  end
+end

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

@@ -12,7 +12,7 @@ module Ace
         BINDING = "ace-wake-eyes-binding"
         BIRTH = /\A(?:linux:[0-9a-f-]{36}:[1-9][0-9]*|darwin:[1-9][0-9]*:[0-9]{1,6})\z/
 
-        def self.ready?(branch:, root:, process:, prompt:, required_sources:, now_ms:)
+        def self.ready?(branch:, root:, process:, prompt:, required_sources:, now_ms:, expected_config: nil)
           return false unless branch.is_a?(Array) && root.is_a?(String) && process.is_a?(Hash) &&
             prompt.is_a?(String) && !prompt.empty? && required_sources.is_a?(Array) &&
             !required_sources.empty? && required_sources.all? { |name| name.is_a?(String) && !name.empty? } &&
@@ -20,6 +20,10 @@ module Ace
             process["started_at"].match?(BIRTH) && now_ms.is_a?(Integer)
           eye_index = branch.rindex { |entry| entry.is_a?(Hash) && entry["type"] == "custom" && entry["customType"] == ENTRY }
           return false unless eye_index
+          if expected_config
+            actual = branch[eye_index].dig("data", "config")
+            return false unless actual.is_a?(Hash) && expected_config.all? { |key, value| actual[key] == value }
+          end
 
           identity = {"pid" => process["pid"], "startedAt" => process["started_at"]}
 
@@ -86,7 +90,7 @@ module Ace
           evidence = eye["observerEvidence"]
           return false unless evidence.is_a?(Hash) && evidence["process"] == identity
           observed, sources, config = evidence.values_at("observedAt", "sources") + [eye["config"]]
-          return false unless observed.is_a?(Integer) && observed >= prompt_at && observed <= now_ms && config.is_a?(Hash) &&
+          return false unless observed.is_a?(Integer) && observed <= now_ms && config.is_a?(Hash) &&
             config["intervalSeconds"].is_a?(Integer) && config["intervalSeconds"].between?(1, 3600) &&
             config["maxObservationsPerHour"].is_a?(Integer) && config["maxObservationsPerHour"].between?(1, 3600) &&
             config["timeoutMs"].is_a?(Integer) && config["timeoutMs"].between?(100, 120_000)

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

@@ -13,7 +13,12 @@ module Ace
         end
 
         def ready?(pane:, root:, prompt:, required_sources:)
-          @local.ready?(pane: pane, root: root, prompt: prompt, required_sources: required_sources)
+          path = File.join(root, ".ace-local/overseer/eyes.json")
+          expected = JSON.parse(File.read(path))
+          return false unless expected.is_a?(Hash) && expected["scope"] == "all" && !expected["recipient"].to_s.empty?
+          @local.ready?(expected_config: expected.slice("scope", "recipient"), pane: pane, root: root, prompt: prompt, required_sources: required_sources)
+        rescue SystemCallError, JSON::ParserError
+          false
         end
       end
     end

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

@@ -46,7 +46,7 @@ module Ace
           @executor, @identity, @clock, @file_opener = executor, identity, clock, file_opener
         end
 
-        def ready?(pane:, root:, prompt:, required_sources:, expected_terminal: nil)
+        def ready?(pane:, root:, prompt:, required_sources:, expected_terminal: nil, expected_config: nil)
           executor = @executor || Ace::Herdr::Molecules::BoundedObservation.new(
             deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5)
           before = pane_binding(executor, pane)
@@ -68,7 +68,7 @@ module Ace
           process = @identity.capture(pid)
           return false unless process && process["uid"] == stat.uid
           return false unless EyesEvidence.ready?(branch: branch, root: root, process: process,
-            prompt: prompt, required_sources: required_sources, now_ms: @clock.call)
+            prompt: prompt, required_sources: required_sources, expected_config: expected_config, now_ms: @clock.call)
           # The owner or its session may change while the file is read.
           return false unless @identity.capture(pid) == process && foreground?(executor, pane, pid) && pane_binding(executor, pane) == before
           final = file.stat

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

@@ -43,6 +43,7 @@ module Ace
             {
               "role" => mapping["role"],
               "start_config" => mapping["start_config"],
+              "execution" => mapping["execution"],
               "assignment" => record["id"],
               "name" => record["name"],
               "state" => states.fetch(record["id"], "")
@@ -91,7 +92,7 @@ module Ace
             role = data["role"].to_s
             next if assignment.empty? || role.strip.empty?
 
-            [assignment, {"role" => role,
+            [assignment, {"role" => role, "execution" => data["execution"],
                           "start_config" => File.join(PREPARE_DIR, File.basename(path))}]
           end.to_h
         end

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

@@ -49,7 +49,7 @@ module Ace
         private
 
         def normalize(event)
-          {
+          @observation.project(event).merge(
             "id" => event.id,
             "type" => event.type,
             "result" => event.result,
@@ -57,7 +57,7 @@ module Ace
             "assignment" => event.metadata["assignment"],
             "role" => event.metadata["role"],
             "title" => event.title
-          }
+          )
         end
       end
     end

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

@@ -125,8 +125,9 @@ module Ace
         # executor probe reads the worktree's commissioned config and the
         # ace-assign inventory (existing run identifiers — assignment
         # 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.
+        # stale. Progress remains readable; between-step paused/running
+        # transitions of an identified live native executor are not wake
+        # reasons. Native completion/disappearance and reports remain signals.
         def coworker_events(overseer_tasks)
           result = @worktrees.list_all
           raise Error, result[:error] || "failed to list worktrees" unless result[:success]
@@ -149,12 +150,24 @@ module Ace
             end
             payload = {"path" => worktree.path, "active" => verdict[:active],
               "evidence" => verdict[:evidence], "sessions" => visible, "missing_sessions" => missing}
-            executor = {"key" => "executor:#{identity}", "revision" => revision(payload),
+            live_assignments = report[:assignments].filter_map do |assignment|
+              id = assignment["id"]
+              id if visible.any? { |session| session["agent"] == "coworker-#{id}" } &&
+                missing.none? { |binding| binding["assignment"] == id }
+            end
+            actionable_assignments = report[:assignments].map do |assignment|
+              assignment.merge("state" => actionable_assignment_state(assignment, live_assignments))
+            end
+            actionable_verdict = Ace::Coworker::Atoms::ActiveExecutorRule.evaluate(
+              config: report[:config], assignments: actionable_assignments
+            )
+            fingerprint = payload.merge("active" => actionable_verdict[:active], "evidence" => actionable_verdict[:evidence])
+            executor = {"key" => "executor:#{identity}", "revision" => revision(fingerprint),
               "type" => "executor"}.merge(payload)
             assignments = report[:assignments].map do |assignment|
               {"key" => "assignment:#{assignment["id"]}",
-               "revision" => revision({"id" => assignment["id"], "state" => assignment["state"],
-                                       "progress" => assignment["progress"]}),
+               "revision" => revision({"id" => assignment["id"],
+                 "state" => actionable_assignment_state(assignment, live_assignments)}),
                "type" => "assignment", "id" => assignment["id"],
                "state" => assignment["state"], "progress" => assignment["progress"]}
             end
@@ -162,6 +175,13 @@ module Ace
           end
         end
 
+        def actionable_assignment_state(assignment, live_assignments)
+          state = assignment["state"]
+          return "running" if state == "paused" && live_assignments.include?(assignment["id"])
+
+          state
+        end
+
         # A coordinator's durable binding also detects a session that
         # started and exited between two native observations.
         def executor_bindings(tasks)

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "ace/task/molecules/git_ignored_path"
+
+module Ace
+  module Overseer
+    module Molecules
+      # References live in ace-task; execution truth stays in coworker/Herdr.
+      # Call under the manager and task delegation exclusions. Creation tags are
+      # written by ace-task with the child, so a crash before update is recoverable.
+      class ManagerBinding
+        def initialize(task_manager:)
+          @tasks = task_manager
+        end
+
+        def validate!(manager_ref:, task:, roles:)
+          manager = @tasks.show(manager_ref)
+          raise Error, "Manager not found: #{manager_ref}" unless manager
+          unless Ace::Task::Molecules::GitIgnoredPath.ignored_task?(manager)
+            raise Error, "manager #{manager.id} must be a private Git-ignored task"
+          end
+          raise Error, "manager must be a top-level task" if manager.metadata["parent"]
+          if Ace::Task::Atoms::TaskValidationRules.terminal_status?(manager.status.to_s)
+            raise Error, "manager #{manager.id} is terminal"
+          end
+          expected = manager.metadata["project_task"].to_s
+          raise Error, "manager #{manager.id} belongs to task #{expected}" if !expected.empty? && expected != task.id.to_s
+          existing_roles = manager.metadata["roles"]
+          if existing_roles && existing_roles != roles
+            raise Error, "manager #{manager.id} has a different role sequence"
+          end
+          managers = @tasks.list(in_folder: "_overseer")
+          unless managers.any? { |other| other.id == manager.id }
+            raise Error, "manager #{manager.id} must belong to the private _overseer tree"
+          end
+          conflicts = managers.reject { |other| other.id == manager.id }.select do |other|
+            other.metadata["project_task"].to_s == task.id.to_s
+          end
+          raise Error, "task #{task.id} already belongs to manager #{conflicts.first.id}" unless conflicts.empty?
+          manager
+        end
+
+        def prepare(manager_ref:, task:, sequence:, worktree_path:, project_root:)
+          roles = sequence.map { |leg| leg.fetch("role") }
+          manager = validate!(manager_ref: manager_ref, task: task, roles: roles)
+          # Refuse conflicts before creating any child. Otherwise a malformed
+          # later role could leave a newly created earlier role on every retry.
+          matched_roles = {}
+          sequence.each do |leg|
+            role = leg.fetch("role")
+            children = Array(manager.subtasks)
+            matches = children.select { |step| step.metadata["role"] == role || Array(step.tags).include?("overseer-role:#{role}") }
+            raise Error, "manager #{manager.id} has ambiguous children for #{role}" if matches.size > 1
+            matches.each do |step|
+              if matched_roles.key?(step.id) && matched_roles[step.id] != role
+                raise Error, "manager child #{step.id} matches conflicting roles"
+              end
+              matched_roles[step.id] = role
+            end
+            assigned = children.select { |step| step.metadata["assignment"].to_s == leg.fetch("assignment") }
+            if assigned.any? { |step| !matches.include?(step) }
+              raise Error, "assignment #{leg.fetch('assignment')} belongs to a different manager role"
+            end
+            assignment = matches.first&.metadata&.fetch("assignment", nil)
+            if assignment && assignment != leg.fetch("assignment")
+              raise Error, "role #{role} already belongs to assignment #{assignment}"
+            end
+          end
+          if roles.include?("bootstrap-verifier") && Array(manager.subtasks).count { |step|
+              step.metadata["role"] == "confirm-start" || Array(step.tags).include?("overseer-role:confirm-start")
+            } > 1
+            raise Error, "manager has ambiguous confirm-start children"
+          end
+          if Array(manager.subtasks).any? { |step| matched_roles.key?(step.id) &&
+              (step.metadata["role"] == "confirm-start" || Array(step.tags).include?("overseer-role:confirm-start")) }
+            raise Error, "confirm-start child also matches an execution role"
+          end
+          update!(manager.id, set: {"project_task" => task.id.to_s,
+            "project_root" => project_root, "roles" => roles, "worktree" => worktree_path})
+          previous = nil
+          bindings = sequence.map do |leg|
+            manager = @tasks.show(manager.id)
+            role = leg.fetch("role")
+            tag = "overseer-role:#{role}"
+            matches = Array(manager.subtasks).select do |step|
+              step.metadata["role"] == role || Array(step.tags).include?(tag)
+            end
+            raise Error, "manager #{manager.id} has ambiguous children for #{role}" if matches.size > 1
+            step = matches.first || @tasks.create_subtask(manager.id, role, tags: [tag], status: "pending")
+            assignment = step.metadata["assignment"].to_s
+            if !assignment.empty? && assignment != leg.fetch("assignment")
+              raise Error, "role #{role} already belongs to assignment #{assignment}"
+            end
+            update!(step.id, set: {"role" => role, "assignment" => leg.fetch("assignment"),
+              "project_task" => task.id.to_s, "worktree" => worktree_path,
+              "dependencies" => (Array(step.dependencies) + Array(previous)).uniq})
+            previous = step.id.to_s
+            {"role" => role, "assignment" => leg.fetch("assignment"), "step" => previous}
+          end
+          if roles.include?("bootstrap-verifier")
+            manager = @tasks.show(manager.id)
+            matches = Array(manager.subtasks).select do |step|
+              step.metadata["role"] == "confirm-start" || Array(step.tags).include?("overseer-role:confirm-start")
+            end
+            raise Error, "manager has ambiguous confirm-start children" if matches.size > 1
+            step = matches.first || @tasks.create_subtask(manager.id, "confirm-start",
+              tags: ["overseer-role:confirm-start"], status: "pending")
+            update!(step.id, set: {"role" => "confirm-start",
+              "dependencies" => (Array(step.dependencies) + Array(previous)).uniq})
+          end
+          bindings
+        end
+
+        def ready!(manager_ref:, assignment:, allow_unbound: false)
+          manager = @tasks.show(manager_ref)
+          step = Array(manager.subtasks).find { |child| child.metadata["assignment"] == assignment }
+          raise Error, "assignment #{assignment} has no manager step" unless step || allow_unbound
+          [manager, step].compact.each do |task|
+            result = Atoms::DependencyReadiness.check(task, lookup: ->(ref) { @tasks.show(ref) })
+            raise Error, "delegation blocked: #{result[:reasons].join('; ')}" if result[:status] == :blocked
+          end
+        end
+
+        private def update!(ref, **options)
+          @tasks.update(ref, **options) || raise(Error, "task #{ref} disappeared while recording delegation; retry to reconcile")
+        end
+
+        def record_execution(manager_ref:, assignment:, execution:)
+          manager = @tasks.show(manager_ref)
+          matches = Array(manager.subtasks).select { |step| step.metadata["assignment"] == assignment }
+          raise Error, "assignment #{assignment} has no unique manager step" unless matches.size == 1
+          update!(matches.first.id, set: {"terminal" => execution["terminal_id"],
+            "executor" => execution["agent"], "start_config" => execution["config_path"]}.compact)
+        end
+      end
+    end
+  end
+end

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

@@ -1,66 +1,42 @@
 # 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"
+require "ace/hitl/molecules/event_observation"
 
 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.
+  # The lab reads only its own incoming messages from configured project HITL
+  # owners. It does not run the project coordinator's complete observation or
+  # borrow that project's interpretation of the lab's recipient alias.
   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)
+      hitl_config: nil)
+      @root, @env, @loader = root, env, loader
+      @hitl_config = hitl_config
     end
 
     def call(owner:, scope:, limit:)
       empty = {"events" => [], "sources" => {}}
-      return empty unless @env["ACE_TOOLCHAIN"] == "installed" &&
-        File.exist?(Ace::Lab.install_manifest_path)
+      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)
+      config = @hitl_config || Dir.chdir(@root) { Ace::Hitl::Molecules::HitlConfigLoader.load }
+      address = Ace::Hitl::Molecules::HitlAddressResolver.new(config: config).resolve(owner)
       events, sources = [], {}
-      deadline = @clock.call + BUDGET_SECONDS
       document.fetch("projects").each do |project|
         id, root = project.values_at("id", "path")
-        source = "project:#{id}"
+        source = "project:#{id}:hitl"
         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"
+          projection = Dir.chdir(root) do
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            Ace::Hitl::Molecules::EventObservation.new(manager: manager).call(scope: scope, limit: limit)
           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')}"),
+          projection.fetch("events").each do |row|
+            recipient = row["recipient"]
+            next unless recipient.is_a?(Hash) && address.all? { |key, value| recipient[key] == value }
+            events << 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
@@ -74,7 +50,7 @@ module Ace::Overseer::Molecules
     private
 
     def project_health(root, id, status, revision = status)
-      key = Digest::SHA256.hexdigest("#{root}:project-observation")
+      key = Digest::SHA256.hexdigest("#{root}:project-hitl")
       {"key" => key, "id" => key, "revision" => Digest::SHA256.hexdigest(revision),
        "type" => "source-health", "status" => status, "project" => id, "project_root" => root}
     end

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

@@ -5,6 +5,7 @@ require "ace/herdr"
 require "digest"
 require "json"
 require_relative "project_root_resolver"
+require_relative "eyes_readiness"
 
 module Ace
   module Overseer
@@ -13,12 +14,14 @@ module Ace
       # 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_resolver: ProjectRootResolver.new, executor: Ace::Herdr::Molecules::HerdrExecutor.new,
+          eyes_evidence: EyesReadiness.new, env: ENV)
           @root = File.realpath(root)
           @control = control || Ace::Herdr::Organisms::ControlSurface.new
           @locations = locations
           @root_resolver = root_resolver
           @executor, @env = executor, env
+          @eyes_evidence = eyes_evidence
         end
 
         def configured?
@@ -54,7 +57,7 @@ module Ace
 
           tabs = @control.list_tabs
           panes = @control.list_panes
-          failures + resolved.map do |id, root, project|
+          failures + resolved.flat_map do |id, root, project|
             begin
               project_row(id, root, tabs, panes)
             rescue StandardError => e
@@ -74,16 +77,16 @@ module Ace
         end
 
 
-        def live_agent?(pane)
+        def live_agent(pane)
           json = @executor.agent_get(pane).parsed_json
           raise Error, "herdr returned malformed agent state" unless json.is_a?(Hash)
           agent = json["agent"]
           agent ||= json.dig("result", "agent") if json["result"].is_a?(Hash)
           agent ||= json["result"] if json["result"].is_a?(Hash)
           raise Error, "herdr returned no agent identity" unless agent.is_a?(Hash)
-          true
+          agent
         rescue Ace::Herdr::AgentNotFoundError
-          false
+          nil
         end
 
         def project_row(id, root, tabs, panes)
@@ -93,22 +96,55 @@ module Ace
             raise Error, "project overseer tab has no unique pane: #{label}" unless matches.length == 1
             matches
           end
-          if owners.length > 1
-            # Reconciliation preserves dead panels for diagnostics. Native
-            # agent presence, not the retained tab, identifies the live owner.
-            owners = owners.select { |owner| live_agent?(owner.fetch(:id)) }
-            raise Error, "project overseer has ambiguous sessions: #{label}" unless owners.length == 1
+          # Reconciliation preserves dead panels for diagnostics. Native agent
+          # presence, not retained tabs, identifies the live owner.
+          live = owners.filter_map do |owner|
+            agent = live_agent(owner.fetch(:id))
+            [owner, agent] if agent
           end
-          pane = owners.first
+          raise Error, "project overseer has ambiguous sessions: #{label}" if live.length > 1
+          pane, agent = live.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)),
+          row = {"key" => "project-session:#{Digest::SHA256.hexdigest(root)}",
+           "revision" => Digest::SHA256.hexdigest(JSON.generate(payload.merge(
+             "state" => (%w[working idle done].include?(state) ? "available" : state)))),
            "type" => "project-session"}.merge(payload)
+          [row, readiness_event(id, root, pane, agent)].compact
+        end
+
+        # A successful first-turn proof is a stable confirmation, not a sampled
+        # boolean lifecycle. A concurrent transcript append can make a proof
+        # inconclusive; omitting this marker then does not undo eyes' existing ack.
+        # The recipient still rechecks start readiness before recording success.
+        def readiness_event(id, root, pane, agent)
+          return unless pane
+          required = Atoms::ObservationSources::REQUIRED.dup
+          required << Atoms::ObservationSources::PROJECT_SESSIONS if File.file?(File.join(root, ".ace/lab/config.yml"))
+          return unless @eyes_evidence.ready?(pane: pane.fetch(:id), root: root,
+            prompt: Atoms::StartContract::FIRST_TURN_PROMPT, required_sources: required)
+          identity = readiness_identity(agent)
+          current = live_agent(pane.fetch(:id))
+          return unless current && readiness_identity(current) == identity
+
+          payload = {"project" => id, "root" => root, "pane" => pane.fetch(:id),
+            "terminal" => identity[0], "session" => identity[1], "ready" => true}
+          key = Digest::SHA256.hexdigest(JSON.generate([root, *identity]))
+          {"key" => "project-ready:#{key}", "revision" => Digest::SHA256.hexdigest("ready:#{key}"),
+           "type" => "project-ready"}.merge(payload)
+        end
+
+        def readiness_identity(agent)
+          terminal = agent["terminal_id"]
+          session = agent.dig("agent_session", "value")
+          unless terminal.is_a?(String) && !terminal.empty? && session.is_a?(String) && !session.empty?
+            raise Error, "ready project agent has no terminal/session identity"
+          end
+          [terminal, session]
         end
       end
     end

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

@@ -25,7 +25,9 @@ module Ace
           role = step.metadata["role"].to_s
           worktree = step.metadata["worktree"].to_s
           worktree = manager.metadata["worktree"].to_s if worktree.empty?
-          return "success requires recorded project task, role and worktree" if [task, role, worktree].any?(&:empty?)
+          return "private coordination task #{manager.id} is missing project_task" if task.empty?
+          return "private coordination step #{step.id} is missing role; record its commissioned role with ace-task update #{step.id} --set role=<role>" if role.empty?
+          return "private coordination step #{step.id} (or its parent) is missing worktree" if worktree.empty?
           return "report task disagrees with the allocation" unless event["task"].to_s == task
           return "confirm-start requires coordinator session evidence" if role == "confirm-start"
           return "report assignment disagrees with the allocation" unless step.metadata["assignment"].to_s == assignment

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

@@ -13,7 +13,7 @@ module Ace::Overseer::Molecules
   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
+    RESERVED = %w[ACE_TOOLCHAIN GEM_HOME GEM_PATH PATH PI_CODING_AGENT_DIR ACE_SESSION_CREDENTIALS_DIRECTORY BUNDLE_GEMFILE RUBYOPT RUBYLIB ACE_OVERSEER_EYES_CONFIG].freeze
     MAX_BYTES = 65_536
     ENVIRONMENT_ROLES = {"reviewer" => "verifier", "bootstrap-verifier" => "verifier", "bootstrap-worker" => "worker"}.freeze
 
@@ -22,7 +22,7 @@ module Ace::Overseer::Molecules
       @env, @loader, @manifest_path = env, manifest_loader, manifest_path
     end
 
-    def with_environment(root:, role:)
+    def with_environment(root:, role:, eyes_config: nil)
       environment = @env.to_h.slice(*BASE_KEYS)
       directory = nil
       handed_off = false
@@ -46,6 +46,7 @@ module Ace::Overseer::Molecules
       else
         environment.merge!(ProjectBundle.environment(root, env: @env)).compact!
       end
+      environment["ACE_OVERSEER_EYES_CONFIG"] = eyes_config if eyes_config
       Tempfile.create(["ace-environment-", ".json"]) do |file|
         file.chmod(0o600)
         file.write(JSON.generate(environment))
@@ -59,12 +60,6 @@ module Ace::Overseer::Molecules
       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.

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

@@ -17,7 +17,7 @@ module Ace
             return recover_from_stale_worktree(task_ref_str, source: :switch, previous_result: switch_result)
           end
 
-          create_result = @manager.create_task(task_ref_str)
+          create_result = @manager.create_task(task_ref_str, defer_setup: true)
           raise Error, create_result[:error] || "Failed to provision worktree for task #{task_ref}" unless create_result[:success]
 
           created = !create_result[:existing]
@@ -44,7 +44,7 @@ module Ace
         def recover_from_stale_worktree(task_ref, source:, previous_result:)
           @manager.prune
 
-          retry_result = @manager.create_task(task_ref)
+          retry_result = @manager.create_task(task_ref, defer_setup: true)
           raise Error, retry_result[:error] || "Failed to provision worktree for task #{task_ref}" unless retry_result[:success]
 
           created = !retry_result[:existing]