ace-overseer 0.28.1 → 0.30.0

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

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/herdr"
+require "ace/herdr/molecules/bounded_observation"
+require "ace/runtime/molecules/process_identity"
+require_relative "eyes_evidence"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Reconstruct Pi's current persisted branch and bind its eyes evidence
+      # to the live Herdr pane and process, without persisting another copy.
+      class EyesSessionEvidence
+        MAX_BYTES = 64 * 1024 * 1024
+        MAX_ENTRIES = 200_000
+        SESSION_PATH = %r{\A/[^\0]*_([0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12})\.jsonl\z}
+
+        # Preserve exact kernel birth identity on Linux and Darwin. A stale
+        # PID or zombie never proves observation readiness.
+        class NativeIdentity
+          def initialize(birth: Ace::Runtime::Molecules::ProcessIdentity.new)
+            @birth = birth
+          end
+
+          def capture(pid)
+            return nil unless pid.is_a?(Integer) && pid.positive?
+            return @birth.capture(pid) if RUBY_PLATFORM.include?("darwin")
+            return nil unless RUBY_PLATFORM.include?("linux")
+            before = @birth.native_birth(pid)
+            return nil unless before
+            stat = File.read("/proc/#{pid}/stat")
+            match = stat.match(/\A#{pid} \(.*\) ([A-Za-z]) /m)
+            return nil unless match && !%w[Z X].include?(match[1])
+            uid = File.stat("/proc/#{pid}").uid
+            return nil unless @birth.native_birth(pid) == before
+            {"pid" => pid, "uid" => uid, "started_at" => before}
+          rescue SystemCallError, IOError
+            nil
+          end
+        end
+
+        def initialize(executor: nil, identity: NativeIdentity.new,
+          clock: -> { (Time.now.to_f * 1000).to_i },
+          file_opener: ->(path) { File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) })
+          @executor, @identity, @clock, @file_opener = executor, identity, clock, file_opener
+        end
+
+        def ready?(pane:, root:, prompt:, required_sources:, expected_terminal: nil)
+          executor = @executor || Ace::Herdr::Molecules::BoundedObservation.new(
+            deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5)
+          before = pane_binding(executor, pane)
+          return false unless before && (expected_terminal.nil? || before["terminal_id"] == expected_terminal)
+          path = before.fetch("path")
+          file = @file_opener.call(path)
+          stat = file.stat
+          return false unless stat.file? && stat.size.between?(1, MAX_BYTES)
+          content = file.read(MAX_BYTES + 1)
+          return false unless content && content.bytesize == stat.size && content.end_with?("\n")
+          again = file.stat
+          return false unless [stat.dev, stat.ino, stat.size, stat.mtime] == [again.dev, again.ino, again.size, again.mtime]
+          header, branch = branch_for(content)
+          return false unless header["cwd"] == root && header["id"].to_s.downcase == before.fetch("session_id").downcase
+
+          eye = branch.reverse.find { |entry| entry["type"] == "custom" && entry["customType"] == EyesEvidence::ENTRY }
+          pid = eye&.dig("data", "observerEvidence", "process", "pid")
+          return false unless pid.is_a?(Integer) && pid.positive? && foreground?(executor, pane, pid)
+          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)
+          # 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
+          named = File.lstat(path)
+          named.file? && !named.symlink? &&
+            [stat.dev, stat.ino, stat.size, stat.mtime] == [final.dev, final.ino, final.size, final.mtime] &&
+            [stat.dev, stat.ino] == [named.dev, named.ino]
+        rescue Ace::Herdr::ExecutorError, SystemCallError, IOError, JSON::ParserError, ArgumentError, TypeError, KeyError
+          false
+        ensure
+          file&.close
+        end
+
+        private
+
+        def pane_binding(executor, pane)
+          json = executor.pane_get(pane).parsed_json
+          row = json.is_a?(Hash) && json["result"].is_a?(Hash) ? json["result"]["pane"] : nil
+          return nil unless row.is_a?(Hash) && row["pane_id"] == pane && row["agent"] == "pi" &&
+            (row["terminal_id"].is_a?(String) || row["terminal_id"].is_a?(Integer)) && !row["terminal_id"].to_s.empty?
+          session = row["agent_session"]
+          return nil unless session.is_a?(Hash) && session["agent"] == "pi" && session["kind"] == "path"
+          path = session["value"]
+          match = path.is_a?(String) && SESSION_PATH.match(path)
+          return nil unless match && path.bytesize <= 4096 && File.expand_path(path) == path
+          {"path" => path, "session_id" => match[1], "terminal_id" => row["terminal_id"].to_s}
+        end
+
+        def foreground?(executor, pane, pid)
+          json = executor.pane_process_info(pane).parsed_json
+          info = json.is_a?(Hash) && json["result"].is_a?(Hash) ? json["result"]["process_info"] : nil
+          list = info.is_a?(Hash) ? info["foreground_processes"] : nil
+          list.is_a?(Array) && list.any? { |row| row.is_a?(Hash) && row["pid"] == pid }
+        end
+
+        def branch_for(content)
+          lines = content.lines
+          raise ArgumentError, "session entry limit" unless lines.size.between?(2, MAX_ENTRIES + 1)
+          header = JSON.parse(lines.shift, create_additions: false, max_nesting: 64, allow_duplicate_key: false)
+          raise ArgumentError, "invalid Pi session" unless header.is_a?(Hash) && header["type"] == "session" && header["version"] == 3
+          entries = {}
+          last = nil
+          lines.each do |line|
+            entry = JSON.parse(line, create_additions: false, max_nesting: 64, allow_duplicate_key: false)
+            raise ArgumentError, "invalid session entry" unless entry.is_a?(Hash) && entry["id"].is_a?(String) &&
+              !entry["id"].empty? && !entries.key?(entry["id"]) &&
+              (entry["parentId"].nil? || entries.key?(entry["parentId"]))
+            entries[entry["id"]] = entry
+            last = entry
+          end
+          branch = []
+          while last
+            branch << last
+            last = last["parentId"] && entries.fetch(last["parentId"])
+          end
+          [header, branch.reverse]
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ace/hitl/molecules/event_observation"
+
 module Ace
   module Overseer
     module Molecules
@@ -10,8 +12,14 @@ module Ace
       # until answered — both are the overseer's inbox.
       class HitlInbox
         # @param manager [Ace::Hitl::Organisms::HitlManager, nil]
-        def initialize(manager: nil)
+        def initialize(manager: nil, owner: "overseer", scope: nil)
           @manager = manager || Ace::Hitl::Organisms::HitlManager.new
+          raise ArgumentError, "configured HITL owner is required" if owner.to_s.strip.empty?
+          unless scope.nil? || %w[current all].include?(scope)
+            raise ArgumentError, "HITL scope must be current or all"
+          end
+          @owner, @scope = owner, scope
+          @observation = Ace::Hitl::Molecules::EventObservation.new(manager: @manager)
         end
 
         # @return [Array<Hash>] {"id","type","result","task","assignment",
@@ -19,10 +27,10 @@ module Ace
         #   atom matches on are carried: assignment, then the managing
         #   task's project_task.
         def incoming_events
-          reports = @manager.list(in_folder: "next", type: "report")
-          questions = @manager.list(in_folder: "next", type: "question", status: "pending")
-
-          (reports + questions).sort_by { |event| event.created_at || Time.now }.map { |event| normalize(event) }
+          events = @observation.incoming_events(owner: @owner, scope: @scope).select do |event|
+            event.type == "report" || (event.type == "question" && event.status == "pending")
+          end
+          events.sort_by { |event| event.created_at || Time.now }.map { |event| normalize(event) }
         end
 
         private