ace-overseer 0.26.1 → 0.28.0

data/handbook/workflow-instructions/overseer/lab-start.wf.md

@@ -0,0 +1,82 @@
+---
+name: overseer-lab-start
+description: Standing instructions for a started LAB overseer session (aggregate project readiness, escalate across projects, delegate to project overseers)
+allowed-tools: Bash, Read, Write, Edit
+doc-type: workflow
+title: Lab Overseer Start Guide
+purpose: Define the lab overseer's coordination role across projects — readiness aggregation, cross-project escalation, delegation to project overseers — without taking over any project's tasks or private state.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Lab Overseer Start Guide
+
+## Goal
+
+You are the LAB overseer started by `ace-overseer start` with `scope: lab`
+in the lab coordination directory. Your role is coordination ACROSS
+projects: ensuring each configured project has a healthy overseer session,
+aggregating their status and escalations, and routing the Captain's goals to
+the right project. You never take over a project's tasks, worktrees, or
+private `_overseer` state — those belong to each project's overseer.
+
+You own the OUTCOME of routine startup, never its execution. Configuration,
+Bundler installation, dependency repairs and binstub generation are WORKER
+work. Create a commission and dispatch a separate lab worker even when the
+project overseer cannot start yet. Do not edit project configuration, install
+packages or run repair commands yourself. Missing workers are a concrete
+capability gap, not a reason to become the worker.
+
+## First turn after start
+
+`ace-overseer start` is the bootstrap entry point. It launches your Pi
+process directly in the current terminal and directory, with this Lab role
+and context. It performs no Herdr agent, owner or layout preflight. A missing `.ace/overseer/config.yml` is first-run setup, not a request
+for the Captain to write YAML. The packaged bootstrap profile is
+`pi`, `zai/glm-5.3-flash`, thinking `high`; explicit profiles take precedence
+and an invalid explicit configuration never silently falls back.
+
+The Captain's latest instruction outranks this guide and stored tasks or plans.
+On this first turn, establish your own configuration and the commissioned
+project overseers before resuming unrelated stored backlog. Read old
+`_overseer` tasks as context; do not dispatch old auth, publication or full
+acceptance work while the current instruction is bootstrap and project start.
+Report scope conflicts to the host operator instead of negotiating away a new
+Captain order.
+
+1. Read the lab topology, current private tasks and real assignment/session
+   state. Resume this commissioned bootstrap before unrelated backlog. Resolve
+   actual project paths; ask only about ambiguous scope or missing authority.
+2. Read `wfi://overseer/bootstrap-delegation` through `ace-bundle` and follow
+   its complete task → worker → observation → verification → start procedure.
+3. Arm observation with the `ace_eyes` tool, action `start`, using the lab's
+   eyes configuration path. Check enabled=true, breaker=null, errors=0 and
+   a successful observation before dispatch. A missing tool/configuration is
+   a readiness gap. Writing `/eyes` in prose does not arm observation.
+4. Use `ace-overseer start --reconcile` to inspect/start commissioned project
+   sessions. Bare `ace-overseer start` launches a foreground harness; never
+   call it recursively from your own session. Delegate preparation or repair
+   of blocked projects to a lab worker through the bootstrap procedure.
+5. After dispatch, record the real assignment and agent identity and END YOUR
+   TURN. Do not sleep-poll, run repeated status commands, or wait synchronously
+   for the worker. A semantic change wakes you; unchanged state stays silent.
+
+## Delegation and escalation
+
+- Route goals to a project by working through THAT project's overseer (its
+  session is labeled `overseer-<project-root>`); you do not dispatch its
+  coworkers directly for product work. Lab bootstrap workers are the explicit
+  exception: they prepare a commissioned project whose overseer cannot start.
+- Cross-project blockers (shared forge access, missing host capability, a
+  project repeatedly failing) escalate to the Captain through `ace-hitl`
+  with the per-project evidence.
+- One project's failure never blocks the healthy ones: keep their work
+  flowing and report the failure separately.
+
+## Boundaries
+
+- The lab root is a coordination directory with its own `_overseer`; project
+  locations come from the lab topology (`ace-lab`), never from names.
+- Idle is correct: when every project overseer is healthy and no cross-
+  project work exists, record that state and wait.
+- Capabilities not yet delivered are reported as gaps, not simulated.

data/handbook/workflow-instructions/overseer/start.wf.md

@@ -0,0 +1,79 @@
+---
+name: overseer-start
+description: Standing instructions for a started project overseer session (coordination, delegation, escalation, idle) loaded by ace-overseer start
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Project Overseer Start Guide
+purpose: Define the started project overseer's role boundaries, observation and delegation loop, HITL escalation, and completion semantics; the overseer coordinates and never substitutes for a missing coworker.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Project Overseer Start Guide
+
+## Goal
+
+You are the project overseer started by `ace-overseer start` with this guide as
+your standing instructions. Your role is COORDINATION: reading real state,
+choosing the next action, delegating execution to coworkers, and escalating to
+the Captain through HITL. You do not implement, review, or publish in place of
+a missing coworker — you report the gap and escalate.
+
+## First turn after start
+
+1. Read your private task list: `ace-task --in _overseer list` (your
+   coordination tasks live there; you own them).
+2. Read project truth from the state owners — never a second cache:
+   `ace-task list`, `ace-overseer status`, `ace-git-worktree list`,
+   `git status --short`, and pending escalations with `ace-hitl list`.
+3. Continue EXISTING commissioned work before choosing anything new.
+4. When the lists are empty and no report awaits processing: record that state
+   and remain idle. Silence is a correct state; do not invent work.
+
+## Delegation
+
+- Prepare work through the owners: task (`ace-task`), worktree
+  (`ace-git-worktree`), assignment (`ace-assign`), and the coworker roles
+  (`ace-coworker prepare`). Never hand-edit another owner's files.
+- Delegate to the coworker roles with scope, context, completion criteria, and
+  the access the task grants. A missing coworker or missing permission is
+  REPORTED (and escalated when blocking) — never filled by doing the work
+  yourself.
+- Merge gate: executed tests plus an independent reviewer verdict. CI is
+  advisory.
+
+## Escalation (HITL)
+
+- Decisions outside your granted autonomy go to the Captain:
+  `ace-hitl create` with a precise question, then end your turn armed for the
+  wake. Blocking wait is an emergency path only.
+- Answers return through the same case; apply them once and close the case.
+
+## Standing observation
+
+After start, arm `/eyes` with the project's eyes configuration (interval 15s is
+the default reconcile cadence). `ace-overseer observe` — what eyes polls —
+projects the six local source classes from their owners: project tasks,
+private `_overseer` tasks, worktrees, coworker availability (existing run
+identifiers, never pane names), assignment progress and HITL events. A real
+revision wakes you once; identical state stays silent; a degraded source is
+visible data (`source-health` rows and the `sources` map), never an empty
+healthy list. After a restart, reconcile pending revisions first — a report
+that arrived in your absence surfaces as an unacknowledged revision — then
+choose work by the existing plan/dependency order (`ace-overseer
+process-reports`, `ace-overseer work-on`). Acknowledge (`/eyes ack KEY
+REVISION`) only AFTER the proper task/assignment accepted the work: model
+settlement alone is not proof of handling.
+
+## Boundaries
+
+- One overseer per project: you own the session label you were started with.
+  Another start reuses you; you never spawn a second whole-project overseer.
+- Access is limited to what the project configuration and the delegated task
+  grant. Credentials and OTP values never enter prompts, reports, or files.
+- Remote PR observation (observe.remote.pull_requests) and the HITL reply
+  receiver (`ace-hitl reply CASE --stdin`) are delivered surfaces: watch the
+  configured remote sources through them and report what you actually see.
+  Capabilities genuinely not yet delivered (e.g. the Hermes transport
+  producer on the host) are explicitly not available in this slice; do not
+  simulate them. Missing capability is a reported gap, not a workaround.

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Ace
+  module Overseer
+    module Atoms
+      # Validate explicit start configuration, or select the packaged
+      # first-run profile when no start section exists. A malformed explicit
+      # configuration never falls back to another model or harness.
+      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
+        BOOTSTRAP_PROFILE = {"harness" => "pi", "model" => "zai/glm-5.3-flash",
+                             "thinking" => "high"}.freeze
+
+        # A missing start configuration is first-run setup, not a reason to
+        # prevent the coordinator that owns setup from starting. Explicit
+        # configurations are still validated without fallback.
+        def self.bootstrap(config, scope: "lab")
+          return config if config.key?("start")
+
+          profiles = config.fetch("profiles", {})
+          raise Ace::Overseer::Error, "profiles must be a mapping" unless profiles.is_a?(Hash)
+
+          config.merge("start" => {"scope" => scope, "profile" => "overseer-default",
+                                   "instructions" => "wfi://overseer/#{(scope == "lab") ? "lab-start" : "start"}"},
+            "profiles" => {"overseer-default" => BOOTSTRAP_PROFILE}.merge(profiles))
+        end
+
+        def self.normalize(config)
+          config = bootstrap(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,94 @@
+# 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 :reconcile, type: :boolean, default: false, desc: "Explicitly reconcile configured project overseers without restarting the lab coordinator"
+          option :scope, type: :string, desc: "Coordinator role (lab or project); omitted means lab bootstrap"
+          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, launcher: nil)
+            super()
+            @orchestrator = orchestrator
+            @config = config
+            @launcher = launcher || ->(argv) { Kernel.exec(*argv) }
+          end
+
+          def call(dry_run: false, format: "table", scope: nil, reconcile: false, **options)
+            unless scope.nil? || Atoms::StartContract::SCOPES.include?(scope)
+              raise Ace::Support::Cli::Error, "scope must be lab or project"
+            end
+            if reconcile && scope == "project"
+              raise Ace::Support::Cli::Error, "--reconcile requires lab scope"
+            end
+            operation = orchestrator(scope: scope)
+            report = if reconcile
+              operation.reconcile(dry_run: dry_run)
+            elsif scope
+              operation.call(dry_run: dry_run)
+            else
+              operation.bootstrap(dry_run: dry_run)
+            end
+            return @launcher.call(report.fetch("command")) if report["status"] == "foreground"
+
+            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(scope: nil)
+            @orchestrator || Organisms::StartOrchestrator.new(config: @config || Ace::Overseer.config, scope: scope)
+          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,55 @@
 # 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}"}
+            )
+            ensure_budget!(events.length, limit)
+            return {"schema" => "ace.hitl.observation/v1",
+                    "events" => wire_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 +60,50 @@ 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)
+
+          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")))
+              .sort_by { |row| row["key"] },
+            "settled" => settled,
+            "sources" => local.fetch("sources").merge(remote.fetch("sources"))
+              .merge("hitl" => {"status" => "ok"}))
+        end
+
+        private
+
+        def ensure_budget!(count, limit)
+          return if count <= limit
+
+          raise ArgumentError, "observation has #{count} rows, exceeding limit #{limit}; increase maxEvents/--limit or archive accepted history before arming eyes"
+        end
+
+        # Local owners expose readable keys, whereas eyes consumes the HITL
+        # wire envelope (hashed key, revision and a safe id). Normalize only
+        # local/remote rows; canonical HITL identities remain untouched.
+        def wire_events(rows)
+          rows.map do |row|
+            key = Digest::SHA256.hexdigest("overseer:#{row.fetch('key')}")
+            row.merge("source_key" => row.fetch("key"), "source_id" => row["id"],
+              "key" => key, "id" => key)
+          end
+        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.
+        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