ace-overseer 0.25.1 → 0.26.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b30816c99a39ab2dad23a161794764d6ad7fc4eebd5309c0941b1b41972f992
-  data.tar.gz: cfc7f540e1b925733144efbab0c4af6b28b1dfccd79bef2a42152a14f5bc5004
+  metadata.gz: ec144ec980c58f2cf9fde48558e42ffdb7798d45c94897dcd28112d4cf348d1a
+  data.tar.gz: 95a59adbdc0244152f79c0d0cce6f4cd60e4b1a29b84e8a86d18ff3130a2c63c
 SHA512:
-  metadata.gz: 6d2099a61ef60bf8aa0608f5b6d9d122e9e2dd12f99e0c93103c1101acf80b505c77b8db0d3a676dbc53153da40c1bda71f3d8df1404e933b200510b44718d2d
-  data.tar.gz: d6f7b7529144631552459798e2e53ecee291c68cafe32327160606e17f2745161e79d8c8ea73b623ea77679949af81fdecd96cebf601358e5cd5e350e311116a
+  metadata.gz: 30b3626aaf30e4297b6000aa0f00cc32320fb0b0eedbb98c33e26f1f867a60690dfdc6b008bcc737b59b80e0c87b28c616450763ad8c3c7acad22809435aba54
+  data.tar.gz: 397b3f3774a3e3f6d80aacf41bd8b2da542ee7597c08d48ce4d876d89b3dcd852f2a879fcead3f9ee511ea6ae2593ae596fc96ef7a622aa36ba77e5369205c2e

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.1] - 2026-10-25
+
+### Changed
+
+- Add the semantic wake contract for pending delivery answers to the overseer workflow (PR74): scoped watch, end-of-turn wait, wake reconciliation.
+
+## [0.26.0] - 2026-10-23
+
+### Added
+
+- Expose canonical report observation and adoption filtering for event-driven continuation without creating another state owner.
+
 ## [0.25.1] - 2026-10-20
 
 ### Fixed

data/README.md

@@ -98,3 +98,14 @@ or create your own.
 
 ---
 [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)
+
+### Read-only event observation
+
+`ace-overseer observe --owner self --scope all --limit 500` combines the HITL
+owner's semantic incoming-event projection with canonical report adoption from
+the existing private task tree. `self` must be a configured HITL recipient alias.
+The JSON contains `events` requiring reconciliation and `settled` revisions whose
+matched managing tree is fully terminal (including archived managers). Recorded
+reports on active managers remain eligible: adoption does not prove continuation.
+No report, task, assignment, worktree, process or external operation is mutated.
+Pi eyes uses this view, then the agent uses normal `process-reports` gates.

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

@@ -6,8 +6,8 @@ doc-type: workflow
 title: Overseer Workflow
 purpose: Binding process contract for the overseer lifecycle (work-on, status, prune) with executed-check contracts for prune safety and status truth.
 ace-docs:
-  last-updated: '2026-09-29'
-  last-checked: '2026-09-29'
+  last-updated: '2026-10-23'
+  last-checked: '2026-10-23'
 ---
 # Overseer Workflow
 
@@ -145,6 +145,20 @@ candidate:
    operator; never silently drop it and never bypass a failed proof with
    `--force`. Preserve on ambiguity.
 
+### 4) Wait: pending answers use the semantic wake, never polling
+
+While an answer is pending (for example a RubyGems OTP window of ~30-45 s
+during publication), the supervising session registers exactly ONE
+in-process `/watch` scoped to the project ace-hitl transport folder (the
+folder holding that case's reply/request files, e.g. `.ace-local/hitl`),
+then ends its turn. On wake: run the project `ace-hitl-hermes sync` ONCE,
+reconcile the exact case state (`ace-hitl show <id>`: answered, not merely
+replies>0), and act within the answer window or report the precise blocker.
+Never block a model turn with sleep/poll loops, and never introduce
+cron/systemd/external heartbeats - none exists and none may be added.
+Observed defect (eyes-20261023 OTP wait): the supervising session blocked
+its turn with a 36x sleep-8 poll loop.
+
 ## Non-Negotiable Contracts Summary
 
 | Contract     | Claim | Executed proof |

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require "json"
+require_relative "../../molecules/event_observation"
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        class Observe < Ace::Support::Cli::Command
+          desc "Read incoming semantic revisions requiring owner reconciliation; no effects"
+          option :owner, type: :string, required: true, desc: "Configured HITL recipient for this observer"
+          option :scope, type: :string, default: "current", desc: "current or all linked worktrees"
+          option :limit, type: :integer, default: 500, desc: "Maximum canonical events"
+          def call(owner:, scope: "current", limit: 500, **)
+            raise Ace::Support::Cli::Error, "invalid scope" unless %w[current all].include?(scope)
+            puts JSON.generate(Molecules::EventObservation.new.call(owner: owner, scope: scope, limit: limit))
+          rescue ArgumentError, Ace::Hitl::Molecules::HitlAddressResolver::UnknownRecipientError,
+            Ace::Hitl::Molecules::HitlAddressResolver::InvalidAddressError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli.rb

@@ -6,6 +6,7 @@ require_relative "cli/commands/work_on"
 require_relative "cli/commands/handoff"
 require_relative "cli/commands/process_reports"
 require_relative "cli/commands/status"
+require_relative "cli/commands/observe"
 require_relative "cli/commands/prune"
 require_relative "cli/commands/projects"
 require_relative "cli/commands/agents"
@@ -21,6 +22,7 @@ module Ace
         ["work-on", "Start local task work"],
         ["handoff", "Hand the task worktree to the next role"],
         ["process-reports", "Process ace-hitl reports and continue the queue"],
+        ["observe", "Read semantic events needing reconciliation"],
         ["status", "Show status of task worktrees"],
         ["prune", "Remove stale task worktrees"],
         ["projects", "List visible public projects"],
@@ -38,6 +40,7 @@ module Ace
       register "work-on", Commands::WorkOn
       register "handoff", Commands::Handoff
       register "process-reports", Commands::ProcessReports
+      register "observe", Commands::Observe
       register "status", Commands::Status
       register "prune", Commands::Prune
       register "projects", Commands::Projects

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+require "ace/hitl/molecules/event_observation"
+
+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.
+      class EventObservation
+        def initialize(hitl: nil, task_manager: nil)
+          @hitl = hitl || Ace::Hitl::Molecules::EventObservation.new
+          @tasks = task_manager || Ace::Task::Organisms::TaskManager.new
+        end
+
+        def call(owner:, scope: "current", limit: 500)
+          projection = @hitl.call(owner: owner, scope: scope, limit: limit)
+          managers = @tasks.list(in_folder: "all").select { |task| !task.metadata["project_task"].to_s.empty? }
+          settled, pending = projection.fetch("events").partition do |event|
+            next false unless event["type"] == "report"
+            verdict = Atoms::ReportInterpretation.evaluate(event: event, managers: managers)
+            next false unless verdict[:status] == :duplicate
+            manager = managers.find { |task| task.id.to_s == verdict[:manager_ref] }
+            # A persisted report alone is not proof its continuation ran. Keep
+            # active managers eligible after restart; their existing gates reconcile
+            # 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)
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Overseer
-    VERSION = "0.25.1"
+    VERSION = "0.26.1"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-overseer
 version: !ruby/object:Gem::Version
-  version: 0.25.1
+  version: 0.26.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -139,34 +139,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.6.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.6.2
 - !ruby/object:Gem::Dependency
   name: ace-hitl
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.23'
+        version: '0.24'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.23'
+        version: '0.24'
 - !ruby/object:Gem::Dependency
   name: ace-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -235,14 +229,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.62.0
+        version: 0.62.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.62.0
+        version: 0.62.2
 - !ruby/object:Gem::Dependency
   name: ace-support-test-helpers
   requirement: !ruby/object:Gem::Requirement
@@ -337,6 +331,7 @@ files:
 - lib/ace/overseer/cli.rb
 - lib/ace/overseer/cli/commands/agents.rb
 - lib/ace/overseer/cli/commands/handoff.rb
+- lib/ace/overseer/cli/commands/observe.rb
 - lib/ace/overseer/cli/commands/process_reports.rb
 - lib/ace/overseer/cli/commands/projects.rb
 - lib/ace/overseer/cli/commands/prune.rb
@@ -348,6 +343,7 @@ files:
 - lib/ace/overseer/models/work_context.rb
 - lib/ace/overseer/molecules/assignment_launcher.rb
 - lib/ace/overseer/molecules/assignment_prune_safety_checker.rb
+- lib/ace/overseer/molecules/event_observation.rb
 - lib/ace/overseer/molecules/git_preservation_checker.rb
 - lib/ace/overseer/molecules/handoff_probe.rb
 - lib/ace/overseer/molecules/hitl_inbox.rb