ace-overseer 0.26.0 → 0.27.0

data/lib/ace/overseer/atoms/start_contract.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Ace
+  module Overseer
+    module Atoms
+      # Pure validation and normalization of the `start` contract
+      # (task 8xs.t.pu0.1): the `.ace/overseer/config.yml` cascade must
+      # carry an EXPLICIT start section — `scope: project|lab`, a
+      # `profile` reference into the same document's `profiles` map and
+      # an `instructions` source (wfi:// or an absolute file path).
+      # Nothing is guessed: a missing or ambiguous section is an error
+      # BEFORE any session is created, and no interim default model is
+      # applied anywhere. Pure — no IO, value-free messages.
+      class StartContract
+        SCOPES = %w[project lab].freeze
+        SECTION_KEYS = %w[scope profile instructions].freeze
+        PROFILE_KEYS = %w[harness model thinking].freeze
+        INSTRUCTION_PROTOCOLS = %w[wfi:// prompt:// tmpl://].freeze
+
+        # @param config [Hash] resolved overseer config (cascade output)
+        # @return [Hash] normalized start plan fragment:
+        #   {scope:, profile_name:, profile: {harness:, model:,
+        #   thinking:}, instructions:}
+        # @raise [Ace::Overseer::Error] missing/ambiguous/invalid start
+        #   configuration
+        def self.normalize(config)
+          start = config["start"]
+          unless start.is_a?(Hash)
+            raise Ace::Overseer::Error,
+              "ace-overseer start requires an explicit 'start' section in " \
+              ".ace/overseer/config.yml (scope, profile, instructions); " \
+              "none is configured for this directory"
+          end
+
+          unknown = start.keys - SECTION_KEYS
+          unless unknown.empty?
+            raise Ace::Overseer::Error,
+              "start section has unknown key '#{unknown.sort.first}' " \
+              "(allowed: #{SECTION_KEYS.join(', ')})"
+          end
+
+          scope = required(start, "scope")
+          unless SCOPES.include?(scope)
+            raise Ace::Overseer::Error,
+              "start scope must be one of: #{SCOPES.join(', ')} (got '#{scope}')"
+          end
+
+          profile_name = required(start, "profile")
+          profile = profile_for(config, profile_name)
+
+          instructions = required(start, "instructions")
+          unless INSTRUCTION_PROTOCOLS.any? { |prefix| instructions.start_with?(prefix) } ||
+            instructions.start_with?("/")
+            raise Ace::Overseer::Error,
+              "start instructions must be a wfi:// (or prompt://, tmpl://) " \
+                "source or an absolute file path"
+          end
+
+          {"scope" => scope, "profile_name" => profile_name,
+           "profile" => profile, "instructions" => instructions}
+        end
+
+        # The pane/tab label that OWNS this project's overseer session:
+        # derived from the project root so every start from the same
+        # repository (subdirectory, symlink, worktree) converges on the
+        # same owner identity.
+        def self.session_label(project_root)
+          "overseer-#{File.basename(project_root)}"
+        end
+
+        def self.profile_for(config, profile_name)
+          profiles = config["profiles"]
+          unless profiles.is_a?(Hash) && profiles[profile_name].is_a?(Hash)
+            raise Ace::Overseer::Error,
+              "start profile '#{profile_name}' is not configured; declare it " \
+                "under 'profiles' in .ace/overseer/config.yml"
+          end
+
+          raw = profiles[profile_name]
+          unknown = raw.keys - PROFILE_KEYS
+          unless unknown.empty?
+            raise Ace::Overseer::Error,
+              "profile '#{profile_name}' has unknown key '#{unknown.sort.first}' " \
+                "(allowed: #{PROFILE_KEYS.join(', ')})"
+          end
+
+          harness = required_value(raw, "harness", "profile '#{profile_name}'")
+          model = required_value(raw, "model", "profile '#{profile_name}'")
+          thinking = raw["thinking"]
+
+          {"harness" => harness, "model" => model, "thinking" => thinking}
+        end
+
+        def self.required(start, key)
+          value = start[key]
+          unless value.is_a?(String) && !value.strip.empty?
+            raise Ace::Overseer::Error,
+              "start section key '#{key}' is required and must be a non-empty string"
+          end
+
+          value.strip
+        end
+
+        def self.required_value(raw, key, owner)
+          value = raw[key]
+          unless value.is_a?(String) && !value.strip.empty?
+            raise Ace::Overseer::Error, "#{owner} key '#{key}' is required"
+          end
+
+          value.strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        # `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.
+        class Start < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Start or reuse the project overseer session from .ace/overseer/config.yml"
+
+          option :dry_run, type: :boolean, default: false, desc: "Show the start plan without creating a session"
+          option :format, default: "table", desc: "Output format (table, json)"
+          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"
+
+          def initialize(orchestrator: nil, config: nil)
+            super()
+            @orchestrator = orchestrator
+            @config = config
+          end
+
+          def call(dry_run: false, format: "table", **options)
+            report = orchestrator.call(dry_run: dry_run)
+
+            if options[:quiet]
+              # quiet still fails loudly on a blocked start
+            elsif format == "json"
+              puts JSON.pretty_generate(report)
+            else
+              render_table(report)
+            end
+
+            case report["status"]
+            when "started", "reused", "ready", "dry_run" then nil
+            else
+              raise Ace::Support::Cli::Error, report["message"] || "start blocked"
+            end
+          rescue Ace::Support::Cli::Error
+            raise
+          rescue => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+
+          private
+
+          def orchestrator
+            @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config)
+          end
+
+          def render_table(report)
+            puts "ace-overseer start: #{report['status']}"
+            puts "  scope:         #{report['scope'] || '-'}"
+            puts "  root:          #{report['root'] || '-'}"
+            puts "  label:         #{report['label'] || '-'}"
+            puts "  profile:       #{report['profile'] || '-'}"
+            if report["instructions"]
+              puts "  instructions:  #{report['instructions']['source']} -> #{report['instructions']['path']}"
+            end
+            puts "  workspace:     #{report['workspace'] || '-'}"
+            puts "  pane:          #{report['pane'] || '-'}"
+            puts "  agent:         #{report['agent']}"
+            puts "  replaced pane: #{report['replaced_pane'] || '-'}" if report["replaced_pane"]
+            puts "  #{report['message']}" if report["message"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli.rb

@@ -10,6 +10,7 @@ require_relative "cli/commands/observe"
 require_relative "cli/commands/prune"
 require_relative "cli/commands/projects"
 require_relative "cli/commands/agents"
+require_relative "cli/commands/start"
 
 module Ace
   module Overseer
@@ -37,6 +38,7 @@ module Ace
         "ace-overseer prune                    # Clean up finished tasks"
       ].freeze
 
+      register "start", Commands::Start
       register "work-on", Commands::WorkOn
       register "handoff", Commands::Handoff
       register "process-reports", Commands::ProcessReports

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

@@ -1,20 +1,54 @@
 # frozen_string_literal: true
 require "ace/hitl/molecules/event_observation"
+require "digest"
 
 module Ace
   module Overseer
     module Molecules
-      # Read-only adoption filter. HITL owns semantic revisions; the existing
-      # private task tree owns report adoption and continuation, never this view.
+      # 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
+      # events plus LocalSources (project tasks, _overseer tasks,
+      # worktrees, coworker availability, assignment progress) — 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)
+        def initialize(hitl: nil, task_manager: nil, local_sources: nil, remote_sources: nil,
+          config: nil)
           @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
         end
 
         def call(owner:, scope: "current", limit: 500)
-          projection = @hitl.call(owner: owner, scope: scope, limit: limit)
+          projection = nil
+          hitl_error = nil
+          begin
+            projection = @hitl.call(owner: owner, scope: scope, limit: limit)
+          rescue StandardError => e
+            hitl_error = e
+          end
+
+          local = @local_sources.call
+          remote = remote_projection
           managers = @tasks.list(in_folder: "all").select { |task| !task.metadata["project_task"].to_s.empty? }
+
+          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}"}
+            )
+            return {"schema" => "ace.hitl.observation/v1",
+                    "events" => events.sort_by { |row| row["key"] },
+                    "settled" => [], "sources" => sources}
+          end
+
           settled, pending = projection.fetch("events").partition do |event|
             next false unless event["type"] == "report"
             verdict = Atoms::ReportInterpretation.evaluate(event: event, managers: managers)
@@ -25,7 +59,32 @@ module Ace
             # the same attempt. Only completed trees suppress historical reports.
             manager && ([manager] + Array(manager.subtasks)).all? { |task| Ace::Task::Atoms::TaskValidationRules.terminal_status?(task.status.to_s) }
           end
-          projection.merge("events" => pending, "settled" => settled)
+
+          projection.merge("events" => (pending + local.fetch("events") + remote.fetch("events"))
+              .sort_by { |row| row["key"] },
+            "settled" => settled,
+            "sources" => local.fetch("sources").merge(remote.fetch("sources"))
+              .merge("hitl" => {"status" => "ok"}))
+        end
+
+        private
+
+        # 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.
+        def remote_projection
+          entries = Array(@config.dig("observe", "remote", "pull_requests"))
+          return {"events" => [], "sources" => {}} if entries.empty?
+
+          @remote_sources.call(pull_requests: entries)
+        end
+
+        def health_marker(name, error)
+          {"key" => "source:#{name}",
+           "revision" => Digest::SHA256.hexdigest("degraded:#{error.class}"),
+           "type" => "source-health", "status" => "degraded",
+           "error" => "#{error.class}: #{error.message}"}
         end
       end
     end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+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
+      # tasks, private _overseer tasks, worktrees, coworker availability,
+      # assignment progress 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
+      # only when the owner's data changes, so a consumer (eyes) wakes on
+      # real revisions and stays silent on identical state.
+      #
+      # A failing source degrades ONLY itself: it contributes a
+      # `source-health` marker whose revision is stable per error class
+      # (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)
+          @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)
+          }
+        end
+
+        # @return [Hash] {"events" => Array<{key, revision, type, ...}>,
+        #   "sources" => {name => {"status" => "ok"|"degraded", "error"?}}}
+        def call
+          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 }
+
+          {"events" => events, "sources" => sources}
+        end
+
+        private
+
+        def collect(sources, events, name)
+          rows = yield
+          sources[name] = {"status" => "ok"}
+          events.concat(rows)
+        rescue StandardError => e
+          sources[name] = {"status" => "degraded", "error" => "#{e.class}: #{e.message}"}
+          events.concat([health_marker(name, e)])
+        end
+
+        # A degraded source surfaces as missing data — visibly, never as
+        # an empty healthy list. The revision is keyed by error CLASS so
+        # an identical repeated failure keeps the same revision (no
+        # wake spam) while a new failure mode revises once.
+        def health_marker(name, error)
+          {"key" => "source:#{name}",
+           "revision" => Digest::SHA256.hexdigest("degraded:#{error.class}"),
+           "type" => "source-health", "status" => "degraded",
+           "error" => "#{error.class}: #{error.message}"}
+        end
+
+        def revision(payload)
+          Digest::SHA256.hexdigest(JSON.generate(payload))
+        end
+
+        def project_task_events
+          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)
+          tasks.map do |task|
+            payload = {"id" => task.id, "status" => task.status,
+              "dependencies" => Array(task.dependencies).sort,
+              "subtasks" => Array(task.subtasks).map { |sub| [sub.id, sub.status] }.sort}
+            {"key" => "#{type}:#{task.id}", "revision" => revision(payload),
+             "type" => type, "id" => task.id, "status" => task.status,
+             "title" => task.title, "dependencies" => Array(task.dependencies).sort}
+          end
+        end
+
+        def worktree_events
+          result = @worktrees.list_all
+          raise Error, result[:error] || "failed to list worktrees" unless result[:success]
+
+          Array(result[:worktrees]).reject(&:bare).map do |worktree|
+            payload = {"path" => worktree.path, "branch" => worktree.branch}
+            {"key" => "worktree:#{Digest::SHA256.hexdigest(worktree.path)}",
+             "revision" => revision(payload), "type" => "worktree",
+             "path" => worktree.path, "branch" => worktree.branch}
+          end
+        end
+
+        # Coworker availability AND assignment progress in one pass: the
+        # executor probe reads the worktree's commissioned config and the
+        # ace-assign inventory (existing run identifiers — assignment
+        # ids, never pane names), the ActiveExecutorRule decides live vs
+        # stale, and each in-flight assignment projects its own progress
+        # row so a step report revises that assignment only.
+        def coworker_events
+          result = @worktrees.list_all
+          raise Error, result[:error] || "failed to list worktrees" unless result[:success]
+
+          Array(result[:worktrees]).reject(&:bare).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]}
+            assignments = report[:assignments].map do |assignment|
+              {"key" => "assignment:#{assignment["id"]}",
+               "revision" => revision({"id" => assignment["id"], "state" => assignment["state"],
+                                       "progress" => assignment["progress"]}),
+               "type" => "assignment", "id" => assignment["id"],
+               "state" => assignment["state"], "progress" => assignment["progress"]}
+            end
+            [executor] + assignments
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ace
+  module Overseer
+    module Molecules
+      # Canonical project-root resolution for `ace-overseer start`
+      # (task 8xs.t.pu0.1): a subdirectory, a symlinked checkout and a
+      # linked WORKTREE of the same repository all resolve to the same
+      # owning root, so one repository never runs two whole-project
+      # overseers. Worktrees map to the main working tree's root through
+      # Git's own `--git-common-dir`; the resolved root is realpathed.
+      # All Git access runs through an injectable argv runner seam.
+      class ProjectRootResolver
+        def initialize(runner: nil)
+          @runner = runner || method(:run_argv)
+        end
+
+        # @param cwd [String] directory the command was invoked in
+        # @return [String] canonical project root (realpath)
+        # @raise [Ace::Overseer::Error] not a repository, or a bare repo
+        def resolve(cwd:)
+          toplevel = git_output(cwd, ["git", "-C", cwd, "rev-parse", "--show-toplevel"])
+          root = File.realpath(toplevel)
+
+          common = git_output(cwd, ["git", "-C", root, "rev-parse", "--git-common-dir"])
+          common_path = File.expand_path(common, root)
+          if File.realpath(common_path) != File.realpath(File.join(root, ".git"))
+            # a linked worktree: the main working tree owns the project
+            main_root = File.dirname(File.realpath(common_path))
+            root = File.realpath(main_root) if File.directory?(main_root)
+          end
+
+          root
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          raise Ace::Overseer::Error, "cannot resolve the project root: '#{cwd}' does not exist"
+        end
+
+        private
+
+        def git_output(cwd, argv)
+          result = @runner.call(argv)
+          unless result["status"] == "ok"
+            raise Ace::Overseer::Error,
+              "cannot resolve the project root under '#{cwd}': run " \
+                "ace-overseer start inside the configured project repository"
+          end
+
+          line = result["out"].to_s.lines.first.to_s.strip
+          raise Ace::Overseer::Error, "git returned no root for '#{cwd}'" if line.empty?
+
+          line
+        end
+
+        def run_argv(argv)
+          out, err, status = Open3.capture3(*argv)
+          {"status" => status.success? ? "ok" : (status.exitstatus || "signal"),
+           "out" => out, "err" => err}
+        rescue Errno::ENOENT
+          {"status" => "enoent", "out" => "", "err" => ""}
+        rescue SystemCallError => e
+          {"status" => "exec_failed", "out" => "", "err" => e.class.name}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Ace
+  module Overseer
+    module Molecules
+      # Remote PR/repo observation (task 8xs.t.pu0.4): projects configured
+      # pull requests through the EXISTING forge provider adapters
+      # (Ace::Git::Providers.for — Forgejo and GitHub; no separate HTTP
+      # client here). Observed PRs come from the project's own
+      # configuration (`observe.remote.pull_requests` in the overseer
+      # cascade) — never a scan of every accessible account.
+      #
+      # Rows follow the standing-observation contract of LocalSources:
+      # stable key + SEMANTIC revision (state, head SHA, review/comment
+      # identity sets — never poll timestamps or list order), so repeated
+      # reads of identical state project identical revisions (zero model
+      # turns) while a new HEAD, review, approval, comment, merge, close
+      # or reopen revises exactly its row. The row carries the wake
+      # payload: forge, PR number/title, event kind, author, link.
+      #
+      # A failing forge (401/403, rate limit, timeout, malformed payload)
+      # degrades ONLY its source — a marker revision keyed by error
+      # class wakes once per failure mode, never as an empty healthy
+      # list — and recovery re-observes the real state.
+      class RemoteSources
+        def initialize(provider_factory: nil, timeout: nil)
+          @provider_factory = provider_factory || ->(server_name) {
+            server = Ace::Git::ServerRegistry.resolve(server_name)
+            Ace::Git::Providers.for(server, timeout: timeout)
+          }
+        end
+
+        # @param pull_requests [Array<Hash>] {"server" =>, "number" =>}
+        #   entries from the project's observe.remote configuration
+        # @return [Hash] {"events" => Array, "sources" => {name => health}}
+        def call(pull_requests:)
+          sources = {}
+          events = []
+
+          # Validate entries BEFORE grouping: a malformed entry (non-Hash,
+          # missing server/number) must degrade its group to a health
+          # marker, never crash the whole observation pass.
+          valid, invalid = Array(pull_requests).partition do |entry|
+            entry.is_a?(Hash) && !entry["server"].to_s.empty? && !entry["number"].to_s.empty?
+          end
+          invalid.group_by { |entry| entry.is_a?(Hash) ? entry["server"].to_s : "" }.each do |server, entries|
+            if server.empty?
+              # Non-Hash or server-less entries still surface as health
+              # markers, never silently disappear.
+              sources["observe.remote"] ||= {"state" => "degraded",
+                "reason" => "invalid observe.remote.pull_requests entry: #{entries.first.inspect}"}
+            else
+              sources["pr:#{server}"] ||= {"state" => "degraded",
+                "reason" => "invalid observe.remote.pull_requests entry: #{entries.first.inspect}"}
+            end
+          end
+
+          valid.group_by { |entry| entry["server"] }.each do |server, entries|
+            collect(sources, events, "pr:#{server}") do
+              entries.flat_map { |entry| project(server, entry["number"]) }
+            end
+          end
+
+          {"events" => events, "sources" => sources}
+        end
+
+        private
+
+        def collect(sources, events, name)
+          rows = yield
+          sources[name] = {"status" => "ok"}
+          events.concat(rows)
+        rescue StandardError => e
+          sources[name] = {"status" => "degraded", "error" => "#{e.class}: #{e.message}"}
+          events << {"key" => "source:#{name}",
+                     "revision" => Digest::SHA256.hexdigest("degraded:#{e.class}"),
+                     "type" => "source-health", "status" => "degraded",
+                     "error" => "#{e.class}: #{e.message}"}
+        end
+
+        def project(server, number)
+          provider = @provider_factory.call(server)
+          pr = provider.pull_request(number: number)
+          return [] if pr.nil?
+
+          rows = [pr_row(server, pr)]
+          evidence = provider.pull_request_review_evidence(number: number, expected_head: pr.head_sha)
+          rows << activity_row(server, pr, evidence) if evidence
+          rows
+        end
+
+        # The PR's own lifecycle: new HEAD (head_sha), merge, close,
+        # reopen, title/draft changes. Read fresh before any merge
+        # decision — remote data stays data.
+        def pr_row(server, pr)
+          payload = {"number" => pr.number, "state" => pr.state.to_s,
+                     "head_sha" => pr.head_sha, "draft" => pr.draft,
+                     "title" => pr.title, "merged_at" => pr.merged_at,
+                     "merge_commit_sha" => pr.merge_commit_sha}
+          {"key" => "pr:#{server}:#{pr.number}", "revision" => digest(payload),
+           "type" => "pr", "forge" => server, "number" => pr.number,
+           "title" => pr.title, "state" => pr.state.to_s, "head_sha" => pr.head_sha,
+           "author" => pr.author, "url" => pr.url}
+        end
+
+        # Review/comment/approval activity: the revision covers the
+        # SORTED identity set (id, author, state, head binding) of every
+        # review and comment — re-ordered payloads and volatile counters
+        # never revise; a new verdict, approval or comment revises once.
+        # The row's summary names the latest item for the wake payload.
+        def activity_row(server, pr, evidence)
+          reviews = Array(evidence.reviews).map { |review|
+            {"id" => review.id.to_s, "author" => review.author, "state" => review.state.to_s,
+             "head_sha" => review.head_sha, "kind" => "review"}
+          }
+          comments = Array(evidence.comments).map { |comment|
+            {"id" => comment.id.to_s, "author" => comment.author, "state" => nil,
+             "head_sha" => comment.head_sha, "kind" => "comment"}
+          }
+          items = (reviews + comments).sort_by { |item| item["id"] }
+          latest = items.last
+
+          {"key" => "pr-activity:#{server}:#{pr.number}", "revision" => digest(items),
+           "type" => "pr-activity", "forge" => server, "number" => pr.number,
+           "title" => pr.title, "event_kind" => latest && latest["kind"],
+           "event_id" => latest && latest["id"], "author" => latest && latest["author"],
+           "url" => pr.url, "items" => items.size}
+        end
+
+        def digest(payload)
+          Digest::SHA256.hexdigest(JSON.generate(payload))
+        end
+      end
+    end
+  end
+end