ace-overseer 0.28.0 → 0.29.0

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
@@ -34,6 +42,7 @@ module Ace
             "result" => event.result,
             "task" => event.metadata["task"],
             "assignment" => event.metadata["assignment"],
+            "role" => event.metadata["role"],
             "title" => event.title
           }
         end

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

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

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

@@ -3,6 +3,9 @@
 require "json"
 require "ace/herdr/molecules/bounded_process"
 require "shellwords"
+require "tempfile"
+require "securerandom"
+require "fileutils"
 require "ace/support/cli/toolchain"
 
 module Ace
@@ -59,19 +62,53 @@ module Ace
         end
 
         def self.shell_setup(root, env: ENV)
+          values = environment(root, env: env).reject { |name, _| %w[HERDR_PANE HERDR_TAB HERDR_PANE_ID HERDR_TAB_ID].include?(name) }
           if Ace::Support::Cli::Toolchain.installed?
             # A server-created shell may contain selectors absent from this
             # caller. Clear the same known selectors before applying the
             # installed closure; never inherit server-side Bundler injection.
             names = BUNDLE_SELECTORS + BUNDLE_SELECTORS.map { |key| "BUNDLER_ORIG_#{key}" }
-            return "unset #{names.map { |name| Shellwords.escape(name) }.join(' ')}; " +
-              Ace::Support::Cli::Toolchain.shell_setup
+            values = names.to_h { |name| [name, nil] }.merge(values)
           end
 
-          values = environment(root, env: env).reject { |name, _| %w[HERDR_PANE HERDR_TAB HERDR_PANE_ID HERDR_TAB_ID].include?(name) }
           cleared, assigned = values.partition { |_, value| value.nil? }
-          "unset #{cleared.map { |name, _| Shellwords.escape(name) }.join(" ")}; export " +
-            assigned.map { |name, value| "#{name}=#{Shellwords.escape(value)}" }.join(" ")
+          # Guard every operation: e.g. a readonly inherited selector must
+          # refuse setup rather than print readiness after a failed unset.
+          commands = cleared.map { |name, _| "unset #{Shellwords.escape(name)}" } +
+            assigned.map { |name, value| "export #{name}=#{Shellwords.escape(value)}" }
+          commands.join(" &&\n")
+        end
+
+        # pane_run types through a terminal: Linux canonical input truncates
+        # a line after 4095 bytes. Keep the environment in a private shared
+        # project file, not /tmp (Herdr can use a different PrivateTmp).
+        # The caller must observe the marker before launching the harness.
+        def self.with_shell_setup(root, env: ENV)
+          directory = root
+          %w[.ace-local overseer runtime-start].each do |part|
+            directory = File.join(directory, part)
+            raise Ace::Overseer::Error, "runtime setup directory is a symlink: #{directory}" if File.symlink?(directory)
+
+            Dir.mkdir(directory, 0o700) unless File.exist?(directory)
+            raise Ace::Overseer::Error, "runtime setup path is not a directory: #{directory}" unless File.directory?(directory)
+          end
+          info = File.stat(directory)
+          unless info.uid == Process.uid && (info.mode & 0o077).zero?
+            raise Ace::Overseer::Error, "runtime setup directory must be private and owned by the current user: #{directory}"
+          end
+          marker = "ACE_OVERSEER_ENV_READY_#{SecureRandom.hex(16)}"
+          Tempfile.create(["environment-", ".sh"], directory) do |file|
+            setup = shell_setup(root, env: env).strip.sub(/;\z/, "")
+            file.write("#{setup} && printf '%s\\n' #{Shellwords.escape(marker)}\n")
+            file.flush
+            file.fsync
+            # The tab is created in root. An explicit ./ prevents dot from
+            # searching PATH; a relative path also keeps terminal input short.
+            relative = "./.ace-local/overseer/runtime-start/#{File.basename(file.path)}"
+            yield ". #{Shellwords.escape(relative)}", marker
+          end
+        rescue SystemCallError => e
+          raise Ace::Overseer::Error, "runtime setup file could not be prepared: #{e.message}"
         end
 
         def initialize(timeout_s: 240)
@@ -97,10 +134,17 @@ module Ace
           raise Ace::Overseer::Error, "project start output exceeded its limit" if result.oversized
           out, err, status = result.stdout, result.stderr, result.status
           report = JSON.parse(out)
+          # Startup can fail before it establishes project scope. Keep that
+          # concrete failure without admitting an unscoped report as ready.
+          if report.is_a?(Hash) && report["status"] == "blocked" &&
+              report.key?("scope") && report["scope"].nil? &&
+              report["message"].is_a?(String) && !report["message"].strip.empty?
+            raise Ace::Overseer::Error, report["message"]
+          end
           unless report.is_a?(Hash) && report["scope"] == "project" && report["status"].is_a?(String)
             raise Ace::Overseer::Error, "project start returned no project-scope report"
           end
-          if !status.success? && %w[started reused ready].include?(report["status"])
+          if !status.success? && %w[started reused ready].include?(report["status"]) && report["prompt_failed"] != true
             raise Ace::Overseer::Error, "project start exited #{status.exitstatus} despite a ready report"
           end
           report

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

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

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

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