ace-overseer 0.28.0 → 0.29.0

data/lib/ace/overseer/cli/commands/handoff.rb

@@ -50,6 +50,10 @@ module Ace
             end
 
             next_leg = result[:next]
+            if result[:execution]
+              puts "Executor #{result[:execution]['agent']} started for #{next_leg['assignment']}. End the turn; eyes observes its report."
+              return
+            end
             unless next_leg && next_leg["start_config"]
               raise Ace::Support::Cli::Error,
                 "handoff result is missing the next leg start config - refusing to print a guessed command"

data/lib/ace/overseer/cli/commands/process_reports.rb

@@ -9,6 +9,8 @@ module Ace
 
           desc "Process incoming ace-hitl reports and continue the overseer queue"
 
+          option :scope, type: :string, desc: "HITL scope: current or all (default: owner checkout scope)"
+          option :owner, type: :string, default: "overseer", desc: "Configured HITL recipient, matching the eyes observer"
           option :dry_run, type: :boolean, default: false, desc: "Interpret reports without writes or continuation"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
@@ -18,10 +20,10 @@ module Ace
             @processor = processor
           end
 
-          def call(dry_run: false, **options)
+          def call(dry_run: false, owner: "overseer", scope: nil, **options)
             Atoms::RepoGuard.ensure_repo!
 
-            processor = @processor || Organisms::ReportProcessor.new
+            processor = @processor || Organisms::ReportProcessor.new(owner: owner, scope: scope)
             result = processor.call(
               dry_run: dry_run,
               on_progress: options[:quiet] ? nil : ->(msg) { puts msg }

data/lib/ace/overseer/cli/commands/start.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "shellwords"
 
 module Ace
   module Overseer
@@ -9,8 +10,8 @@ module Ace
         # `ace-overseer start [--dry-run] [--format table|json]`
         # (task 8xs.t.pu0.1): starts or reuses the project overseer
         # session from the directory's explicit start configuration.
-        # Exit 0 only for started/reused (dry-run reports the plan with
-        # exit 0 but creates nothing); a blocked start is a CLI error.
+        # Ready starts and dry runs exit 0; blocked or partial starts
+        # are CLI errors. A dry run creates no session.
         class Start < Ace::Support::Cli::Command
           include Ace::Support::Cli::Base
 
@@ -27,7 +28,7 @@ module Ace
             super()
             @orchestrator = orchestrator
             @config = config
-            @launcher = launcher || ->(argv) { Kernel.exec(*argv) }
+            @launcher = launcher
           end
 
           def call(dry_run: false, format: "table", scope: nil, reconcile: false, **options)
@@ -45,7 +46,7 @@ module Ace
             else
               operation.bootstrap(dry_run: dry_run)
             end
-            return @launcher.call(report.fetch("command")) if report["status"] == "foreground"
+            return launch_foreground(report) if report["status"] == "foreground"
 
             if options[:quiet]
               # quiet still fails loudly on a blocked start
@@ -55,11 +56,16 @@ module Ace
               render_table(report)
             end
 
+            if report["prompt_failed"] == true
+              raise Ace::Support::Cli::Error, report["message"] || "first turn or readiness is unconfirmed"
+            end
             case report["status"]
             when "started", "reused", "ready", "dry_run" then nil
             else
               raise Ace::Support::Cli::Error, report["message"] || "start blocked"
             end
+          rescue Interrupt
+            raise Ace::Support::Cli::Error.new("start interrupted; inspect existing sessions before retrying", exit_code: 130)
           rescue Ace::Support::Cli::Error
             raise
           rescue => e
@@ -68,6 +74,25 @@ module Ace
 
           private
 
+          def launch_foreground(report)
+            return @launcher.call(report.fetch("command")) if @launcher
+
+            role = report["scope"] == "lab" ? "lab-overseer" : "project-overseer"
+            directory = nil
+            Molecules::SessionEnvironment.new.with_environment(root: report.fetch("root"), role: role) do |path, credentials, _args|
+              directory = credentials
+              environment = JSON.parse(File.read(path))
+              system(environment, *report.fetch("command"), unsetenv_others: true)
+              status = $?
+              unless status&.success?
+                raise Ace::Support::Cli::Error.new("coordinator process exited unsuccessfully",
+                  exit_code: status&.exitstatus || 1)
+              end
+            end
+          ensure
+            Molecules::SessionEnvironment.cleanup(directory) if directory
+          end
+
           def orchestrator(scope: nil)
             @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config, scope: scope)
           end
@@ -83,9 +108,16 @@ module Ace
             end
             puts "  workspace:     #{report["workspace"] || "-"}"
             puts "  pane:          #{report["pane"] || "-"}"
-            puts "  agent:         #{report["agent"]}"
+            puts "  agent:         #{report["agent"] || "-"}"
+            puts "  command:       #{Shellwords.join(report["command"])}" if report["command"]
             puts "  replaced pane: #{report["replaced_pane"] || "-"}" if report["replaced_pane"]
             puts "  #{report["message"]}" if report["message"]
+            Array(report["projects"]).each do |project|
+              status = project["status"] || "unknown"
+              status += " (first turn unconfirmed)" if project["prompt_failed"]
+              puts "  project #{project["id"]}: #{status} (#{project["path"] || "-"}, pane: #{project["pane"] || "-"})"
+              puts "    #{project["message"]}" if project["message"]
+            end
           end
         end
       end

data/lib/ace/overseer/cli/commands/work_on.rb

@@ -37,7 +37,7 @@ module Ace
             end
 
             progress = options[:quiet] ? nil : ->(msg) { puts msg }
-            @orchestrator.call(
+            result = @orchestrator.call(
               task_ref: task_refs.first,
               task_refs: task_refs,
               cli_preset: preset,
@@ -46,7 +46,11 @@ module Ace
 
             return if options[:quiet]
 
-            puts "Done. Switch to tmux window and run /ace-assign-drive"
+            if result[:execution]
+              puts "Executor #{result[:execution]['agent']} started for #{result[:assignment_id]}. End the turn; eyes observes its report."
+            else
+              puts "Done. Switch to the task window and run /ace-assign-drive"
+            end
           rescue Ace::Support::Cli::Error
             raise
           rescue => e

data/lib/ace/overseer/cli.rb

@@ -20,6 +20,7 @@ module Ace
       PROGRAM_NAME = "ace-overseer"
 
       REGISTERED_COMMANDS = [
+        ["start", "Start the lab or project overseer"],
         ["work-on", "Start local task work"],
         ["handoff", "Hand the task worktree to the next role"],
         ["process-reports", "Process ace-hitl reports and continue the queue"],
@@ -31,6 +32,7 @@ module Ace
       ].freeze
 
       HELP_EXAMPLES = [
+        "ace-overseer start                    # Start in the current directory",
         "ace-overseer work-on 148              # Launch task in worktree",
         "ace-overseer handoff --task 148       # Hand the worktree to the next role",
         "ace-overseer process-reports          # Interpret reports, continue the queue",

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "ace/coworker/molecules/execution_binding"
+require "ace/herdr"
+require "ace/herdr/atoms/native_agent_session"
+require_relative "session_environment"
+require_relative "eyes_readiness"
+
+module Ace::Overseer::Molecules
+  # Start and retire a real executor using the existing commission document.
+  # A recorded uncertain start is a blocker, never permission to duplicate it.
+  class CoworkerLauncher
+    def initialize(executor: Ace::Herdr::Molecules::HerdrExecutor.new, env: ENV,
+      environment: nil, bindings: Ace::Coworker::Molecules::ExecutionBinding.new,
+      brief_factory: nil, readiness: nil, eyes: nil, root_resolver: nil)
+      @executor, @env, @bindings = executor, env, bindings
+      @environment = environment || SessionEnvironment.new(env: env)
+      @brief_factory = brief_factory || ->(root, path) { Ace::Coworker::Organisms::StartOrchestrator.new(project_root: root).call(config_path: path) }
+      @readiness = readiness || method(:check_eyes!)
+      @eyes = eyes || EyesReadiness.new
+      @root_resolver = root_resolver || ProjectRootResolver.new
+    end
+
+    def ready!
+      @readiness.call
+    end
+
+    def recipient
+      context = coordinator_context
+      path = File.join(context.fetch(:root), ".ace-local/overseer/eyes.json")
+      data = JSON.parse(File.read(path))
+      value = data.is_a?(Hash) && data["recipient"]
+      unless value.is_a?(String) && !value.strip.empty? && !value.match?(/[[:space:][:cntrl:]]/)
+        raise Ace::Overseer::Error, "coordinator eyes recipient is unavailable"
+      end
+      value
+    rescue JSON::ParserError, SystemCallError
+      raise Ace::Overseer::Error, "coordinator eyes recipient is unavailable"
+    end
+
+    def call(worktree_path:, config_path:)
+      ready!
+      path = File.expand_path(config_path, worktree_path)
+      brief = @brief_factory.call(worktree_path, path)
+      @bindings.with_lock(path) do |document, save|
+        unless document["assignment"] == brief.config.assignment && document["role"] == brief.config.role &&
+            document["task"] == brief.config.task
+          raise Ace::Overseer::Error, "executor commission changed during validation"
+        end
+        if document["execution"]
+          next reuse(document.fetch("execution"))
+        end
+        unless %w[paused empty].include?(brief.assignment_snapshot&.state.to_s)
+          raise Ace::Overseer::Error, "unbound assignment is not ready for a new executor"
+        end
+        Dir.glob(File.join(File.dirname(path), "*.yml")).each do |other_path|
+          next if other_path == path
+          other = YAML.safe_load_file(other_path, permitted_classes: [Date, Time], aliases: false)
+          if other.is_a?(Hash) && other.key?("execution") &&
+              (!other["execution"].is_a?(Hash) || other.dig("execution", "state") != "retired")
+            raise Ace::Overseer::Error, "another executor has not been retired from this worktree"
+          end
+        end
+        name = "coworker-#{brief.config.assignment}"
+        execution = {"agent" => name, "assignment" => brief.config.assignment,
+          "role" => brief.config.role, "state" => "launching"}
+        @environment.with_environment(root: worktree_path, role: brief.config.role) do |file, directory, profile_args|
+          document["execution"] = execution
+          execution["credentials_directory"] = directory if directory
+          save.call
+          dispatcher = Ace::Herdr::Organisms::Dispatcher.from_config(executor: @executor)
+          result = dispatcher.dispatch(label: name, prompt: "", kind: "pi", cwd: worktree_path,
+            env_file: file, args: Array(profile_args) + ["--append-system-prompt", brief.instructions_source])
+          execution.merge!(result.to_h).merge!("state" => "started")
+          pane = pane_identity(execution.fetch("pane"))
+          execution["terminal_id"] = pane.fetch("terminal_id")
+          execution["agent_session"] = session_identity(pane)
+          save.call
+        end
+        # Record uncertainty BEFORE submission. A crash after input reaches Pi
+        # cannot cause the same task to be submitted again automatically.
+        execution["state"] = "prompting"
+        save.call
+        prompt = "#{brief.config.start_prompt}\n\n#{Ace::Coworker::Atoms::BriefFormatter.format_table(brief)}"
+        @executor.agent_prompt(pane: execution.fetch("pane"), text: prompt)
+        execution["state"] = "running"
+        save.call
+        execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => false)
+      end
+    rescue Ace::Coworker::Error, Ace::Herdr::ExecutorError => e
+      raise Ace::Overseer::Error, "executor launch blocked: #{e.message}"
+    end
+
+    def retire(worktree_path:, assignment:)
+      paths = Dir.glob(File.join(worktree_path, Ace::Coworker::Organisms::StartConfigWriter::PREPARE_DIR, "*.yml"))
+      paths.each do |path|
+        @bindings.with_lock(path) do |document, save|
+          next unless document["assignment"] == assignment
+          execution = document["execution"]
+          next unless execution
+          next if execution["state"] == "retired"
+          begin
+            pane = pane_identity(execution.fetch("pane"))
+            unless same_executor?(pane, execution)
+              raise Ace::Overseer::Error, "executor terminal changed; retirement refused"
+            end
+            execution["state"] = "retiring"
+            save.call
+            @executor.pane_close(execution.fetch("pane"))
+          rescue Ace::Herdr::PaneNotFoundError
+            # The native owner positively confirms that this panel is gone.
+          end
+          SessionEnvironment.cleanup(execution["credentials_directory"])
+          execution.delete("credentials_directory")
+          execution["state"] = "retired"
+          save.call
+        end
+      end
+    end
+
+    private
+
+    def reuse(execution)
+      if execution["state"] == "retired"
+        raise Ace::Overseer::Error, "recorded executor is retired; reconcile the assignment before starting another"
+      end
+      unless execution["state"] == "running"
+        raise Ace::Overseer::Error, "executor start is unconfirmed; inspect the recorded assignment before retrying"
+      end
+      pane = pane_identity(execution.fetch("pane"))
+      unless same_executor?(pane, execution)
+        raise Ace::Overseer::Error, "recorded executor terminal no longer matches"
+      end
+      agent = @executor.agent_get(execution.fetch("pane")).parsed_json&.dig("result", "agent")
+      unless agent.is_a?(Hash) && agent["interactive_ready"] == true && same_executor?(agent, execution)
+        raise Ace::Overseer::Error, "recorded executor is not a live interactive agent"
+      end
+      execution.reject { |key, _| key == "credentials_directory" }.merge("reused" => true)
+    end
+
+    def pane_identity(pane)
+      reply = @executor.pane_get(pane).parsed_json
+      row = reply&.dig("result", "pane")
+      unless row.is_a?(Hash) && row["pane_id"] == pane && row["terminal_id"]
+        raise Ace::Overseer::Error, "native executor identity is unavailable"
+      end
+      row
+    end
+
+    def session_identity(pane)
+      identity = Ace::Herdr::Atoms::NativeAgentSession.normalize(pane["agent_session"], agent: "pi")
+      raise Ace::Overseer::Error, "native executor session identity is unavailable" unless identity
+      identity
+    end
+
+    def same_executor?(pane, execution)
+      pane["terminal_id"] == execution["terminal_id"] && session_identity(pane) == execution["agent_session"]
+    end
+
+    def check_eyes!
+      context = coordinator_context
+      sources = Ace::Overseer::Atoms::ObservationSources::REQUIRED.dup
+      sources << Ace::Overseer::Atoms::ObservationSources::PROJECT_SESSIONS if context[:scope] == "lab"
+      unless @eyes.ready?(pane: context[:pane], root: context[:root],
+          prompt: Ace::Overseer::Atoms::StartContract::FIRST_TURN_PROMPT, required_sources: sources)
+        raise Ace::Overseer::Error, "delegation requires the coordinator's active eyes"
+      end
+      true
+    end
+
+    def coordinator_context
+      pane = @env["HERDR_PANE_ID"] || @env["HERDR_PANE"]
+      raise Ace::Overseer::Error, "coordinator native pane is unavailable" if pane.to_s.empty?
+      row = pane_identity(pane)
+      cwd = row["cwd"]
+      unless cwd.is_a?(String) && cwd.start_with?("/")
+        raise Ace::Overseer::Error, "coordinator working directory is unavailable"
+      end
+      root = @root_resolver.resolve(cwd: cwd)
+      config_path = File.join(root, ".ace/overseer/config.yml")
+      config = File.file?(config_path) ? YAML.safe_load_file(config_path, permitted_classes: [Date], aliases: true) : {}
+      scope = config.is_a?(Hash) ? config.dig("start", "scope") || "lab" : nil
+      raise Ace::Overseer::Error, "coordinator scope is invalid" unless %w[lab project].include?(scope)
+      {root: root, pane: pane, scope: scope}
+    rescue Psych::Exception, SystemCallError, TypeError
+      raise Ace::Overseer::Error, "coordinator configuration is unavailable"
+    end
+  end
+end

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 require "ace/hitl/molecules/event_observation"
 require "digest"
+require_relative "project_observations"
+require_relative "../atoms/observation_sources"
 
 module Ace
   module Overseer
@@ -8,20 +10,22 @@ module Ace
       # Read-only standing observation (task 8xs.t.pu0.3). HITL owns
       # semantic revisions; the existing private task tree owns report
       # adoption and continuation, never this view. The projection arms
-      # the started overseer with the six local source classes — HITL
+      # the started overseer with local source classes — HITL
       # events plus LocalSources (project tasks, _overseer tasks,
-      # worktrees, coworker availability, assignment progress) — every
+      # worktrees, coworker availability, assignment progress and project
+      # sessions) — every
       # row read from its state owner, with per-source health so a
       # failing source degrades only itself and healthy silence projects
       # identical revisions (no model turns).
       class EventObservation
         def initialize(hitl: nil, task_manager: nil, local_sources: nil, remote_sources: nil,
-          config: nil)
+          config: nil, project_observations: ProjectObservations.new)
           @hitl = hitl || Ace::Hitl::Molecules::EventObservation.new
           @tasks = task_manager || Ace::Task::Organisms::TaskManager.new
           @local_sources = local_sources || LocalSources.new(task_manager: @tasks)
           @remote_sources = remote_sources || RemoteSources.new
           @config = config || Ace::Overseer.config
+          @project_observations = project_observations
         end
 
         def call(owner:, scope: "current", limit: 500)
@@ -35,22 +39,39 @@ module Ace
 
           local = @local_sources.call
           remote = remote_projection
-          managers = @tasks.list(in_folder: "all").select { |task| !task.metadata["project_task"].to_s.empty? }
+          projects = @project_observations.call(owner: owner, scope: scope, limit: limit)
+          managers = begin
+            @tasks.list(in_folder: "all").select { |task| !task.metadata["project_task"].to_s.empty? }
+          rescue StandardError => error
+            # Report adoption depends on the private owner's state. An unreadable
+            # tree must leave reports pending and degrade that source, not abort
+            # healthy observations or claim that a report was already accepted.
+            name = Atoms::ObservationSources::OVERSEER_TASKS
+            local = local.merge(
+              "events" => local.fetch("events").reject { |row| row["key"] == "source:#{name}" } +
+                [health_marker(name, error)],
+              "sources" => local.fetch("sources").merge(name => {
+                "status" => "degraded", "error" => "#{error.class}: #{error.message}"
+              })
+            )
+            []
+          end
 
           if projection.nil?
             # A degraded HITL source degrades only itself: the local
             # sources keep projecting and the failure is visible data.
-            events = local.fetch("events") + remote.fetch("events") + [health_marker("hitl", hitl_error)]
             sources = local.fetch("sources").merge(remote.fetch("sources")).merge(
-              "hitl" => {"status" => "degraded", "error" => "#{hitl_error.class}: #{hitl_error.message}"}
+              Atoms::ObservationSources::HITL => {"status" => "degraded", "error" => "#{hitl_error.class}: #{hitl_error.message}"}
             )
-            ensure_budget!(events.length, limit)
+            events = local.fetch("events") + remote.fetch("events") + healthy_markers(sources) +
+              [health_marker(Atoms::ObservationSources::HITL, hitl_error)]
+            ensure_budget!(events.length + projects.fetch("events").length, limit)
             return {"schema" => "ace.hitl.observation/v1",
-                    "events" => wire_events(events).sort_by { |row| row["key"] },
-                    "settled" => [], "sources" => sources}
+                    "events" => (wire_events(events) + projects.fetch("events")).sort_by { |row| row["key"] },
+                    "settled" => [], "sources" => sources.merge(projects.fetch("sources"))}
           end
 
-          settled, pending = projection.fetch("events").partition do |event|
+          settled, pending = (projection.fetch("events") + projects.fetch("events")).partition do |event|
             next false unless event["type"] == "report"
             verdict = Atoms::ReportInterpretation.evaluate(event: event, managers: managers)
             next false unless verdict[:status] == :duplicate
@@ -61,12 +82,14 @@ module Ace
             manager && ([manager] + Array(manager.subtasks)).all? { |task| Ace::Task::Atoms::TaskValidationRules.terminal_status?(task.status.to_s) }
           end
 
-          ensure_budget!(pending.length + settled.length + local.fetch("events").length + remote.fetch("events").length, limit)
-          projection.merge("events" => (pending + wire_events(local.fetch("events") + remote.fetch("events")))
+          sources = local.fetch("sources").merge(remote.fetch("sources")).merge(
+            Atoms::ObservationSources::HITL => {"status" => "ok"})
+          events = local.fetch("events") + remote.fetch("events") + healthy_markers(sources)
+          ensure_budget!(pending.length + settled.length + events.length, limit)
+          projection.merge("events" => (pending + wire_events(events))
               .sort_by { |row| row["key"] },
             "settled" => settled,
-            "sources" => local.fetch("sources").merge(remote.fetch("sources"))
-              .merge("hitl" => {"status" => "ok"}))
+            "sources" => sources.merge(projects.fetch("sources")))
         end
 
         private
@@ -89,14 +112,15 @@ module Ace
         end
 
         # Configured remote observation (8xs.t.pu0.4): the project's own
-        # observe.remote.pull_requests list — never a scan of accessible
-        # accounts. No configuration means no remote rows and no remote
-        # source to degrade.
+        # observe.remote pull request and issue lists — never a scan of
+        # accessible accounts. No configuration means no remote rows and
+        # no remote source to degrade.
         def remote_projection
           entries = Array(@config.dig("observe", "remote", "pull_requests"))
-          return {"events" => [], "sources" => {}} if entries.empty?
+          issues = Array(@config.dig("observe", "remote", "issues"))
+          return {"events" => [], "sources" => {}} if entries.empty? && issues.empty?
 
-          @remote_sources.call(pull_requests: entries)
+          @remote_sources.call(pull_requests: entries, issues: issues)
         end
 
         def health_marker(name, error)
@@ -105,6 +129,17 @@ module Ace
            "type" => "source-health", "status" => "degraded",
            "error" => "#{error.class}: #{error.message}"}
         end
+
+        # The healthy row shares the degraded row's key. An acknowledged
+        # failure can then wake the owner when only source health recovers.
+        def healthy_markers(sources)
+          sources.filter_map do |name, source|
+            next unless source["status"] == "ok"
+
+            {"key" => "source:#{name}", "revision" => Digest::SHA256.hexdigest("ok"),
+             "type" => "source-health", "status" => "ok"}
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Evaluate the current Pi session branch; this owns no additional
+      # persisted state and must be paired with a live Herdr/process binding.
+      class EyesEvidence
+        ENTRY = "ace-wake-eyes"
+        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:)
+          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? } &&
+            process["pid"].is_a?(Integer) && process["pid"].positive? && process["started_at"].is_a?(String) &&
+            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
+
+          identity = {"pid" => process["pid"], "startedAt" => process["started_at"]}
+
+          # A user prompt in the current branch followed by an assistant
+          # completed assistant turn before the eyes entry proves more than
+          # an unrelated Herdr activity transition. Reject an intervening
+          # user turn or an assistant error during initialization.
+          prefix = branch[0...eye_index]
+          prompt_index = prefix.rindex do |entry|
+            message = entry.is_a?(Hash) && entry["type"] == "message" ? entry["message"] : nil
+            next false unless message.is_a?(Hash) && message["role"] == "user"
+            content = message["content"]
+            content == prompt || content.is_a?(Array) && content.any? { |part| part.is_a?(Hash) && part["type"] == "text" && part["text"] == prompt }
+          end
+          return false unless prompt_index
+          binding_index = prefix.rindex do |entry|
+            entry.is_a?(Hash) && entry["type"] == "custom" && entry["customType"] == BINDING &&
+              entry["data"].is_a?(Hash) && entry["data"]["ownerCwd"] == root && entry["data"]["process"] == identity
+          end
+          return false unless binding_index
+          prompt_at = (Time.iso8601(prefix[prompt_index].fetch("timestamp")).to_r * 1000).to_i
+          return false unless snapshot_healthy?(branch[eye_index], root: root, identity: identity,
+            required_sources: required_sources, now_ms: now_ms, prompt_at: prompt_at, fresh: true)
+
+          complete = false
+          known_bindings = {}
+          branch[0..prompt_index].each do |entry|
+            data = entry.is_a?(Hash) && entry["type"] == "custom" && entry["customType"] == BINDING && entry["data"]
+            known_bindings[data["process"]] = true if data.is_a?(Hash) && data["ownerCwd"] == root && data["process"].is_a?(Hash)
+          end
+          branch[(prompt_index + 1)..eye_index].each do |entry|
+            data = entry.is_a?(Hash) && entry["type"] == "custom" && entry["customType"] == BINDING && entry["data"]
+            known_bindings[data["process"]] = true if data.is_a?(Hash) && data["ownerCwd"] == root && data["process"].is_a?(Hash)
+            prior_identity = entry.is_a?(Hash) && entry.dig("data", "observerEvidence", "process")
+            prior_binding = prior_identity.is_a?(Hash) && prior_identity["pid"].is_a?(Integer) &&
+              prior_identity["pid"].positive? && prior_identity["startedAt"].is_a?(String) &&
+              prior_identity["startedAt"].match?(BIRTH) && known_bindings[prior_identity]
+            if complete && prior_binding && snapshot_healthy?(entry, root: root, identity: prior_identity,
+                required_sources: required_sources, now_ms: now_ms, prompt_at: prompt_at, fresh: false)
+              # The current binding was found in the prefix before the last
+              # snapshot; initial proof may precede a process restart.
+              return true
+            end
+            message = entry.is_a?(Hash) && entry["type"] == "message" ? entry["message"] : nil
+            next unless message.is_a?(Hash)
+            return false if message["role"] == "user"
+            next unless message["role"] == "assistant"
+            if message["stopReason"] == "stop"
+              complete = true
+              next
+            end
+            return false unless message["stopReason"] == "toolUse"
+          end
+          false
+        rescue ArgumentError, KeyError, TypeError
+          false
+        end
+
+        def self.snapshot_healthy?(entry, root:, identity:, required_sources:, now_ms:, prompt_at:, fresh:)
+          return false unless entry.is_a?(Hash) && entry["type"] == "custom" && entry["customType"] == ENTRY
+          eye = entry["data"]
+          return false unless eye.is_a?(Hash) && eye["ownerCwd"] == root && eye["enabled"] == true &&
+            eye["retired"] == false && eye["breaker"].nil? && eye["errors"] == 0
+          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) &&
+            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)
+          interval = config["intervalSeconds"] * 1000
+          cadence = (3_600_000.0 / (config["maxObservationsPerHour"] * interval)).ceil * interval
+          return false if fresh && now_ms - observed > cadence + config["timeoutMs"]
+          sources.is_a?(Hash) && sources.size.between?(1, 64) &&
+            sources.keys.all? { |name| name.is_a?(String) && name.match?(/\A[a-zA-Z0-9_.:-]{1,128}\z/) } &&
+            required_sources.all? { |name| sources[name] == "ok" } && sources.values.all? { |status| status == "ok" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+require_relative "eyes_session_evidence"
+require_relative "../atoms/start_contract"
+require_relative "../atoms/observation_sources"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Read readiness from the actual native pane and its Pi session.
+      class EyesReadiness
+        def initialize(env: ENV, local: EyesSessionEvidence.new)
+          @local = local
+        end
+
+        def ready?(pane:, root:, prompt:, required_sources:)
+          @local.ready?(pane: pane, root: root, prompt: prompt, required_sources: required_sources)
+        end
+      end
+    end
+  end
+end