ace-hitl 0.23.2 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 973228979e65843573a7dc67bc91566a22478ca762f3751babdbd269e0960ca9
-  data.tar.gz: c4b09f84c60c2bfb225294d56c4bfa4abded7ced7ecc75fe830ecc8987e239ee
+  metadata.gz: 80aaacaa6ef70bbe80b87e00b4edee2f4cf935b679a115fd5e42f001ddb0f60b
+  data.tar.gz: 85b36915a24996df17f1a550f3c5ca017227482472183b0d27ff9b6bc09a65ec
 SHA512:
-  metadata.gz: f08442f7582db2b088cbaa5f0af24d9d81bc7caccdf5e2bdfc9de5feb6a9ee9f5125f541f02e9585f4921933fa08a712fe47e80e8c668dd89330084654e13984
-  data.tar.gz: c3ad787393cc3c045efda84016b9e2783fa8fb5f3696e4a9da9e072840dfb99e12f706c79bafc6b655f90f4ccd35f661d0f3b05932a96d00d17ed563a63b27c1
+  metadata.gz: 387437e8824ee6c94bc89c6c683434c129821527a6cf80dd3983b7bf875551d3e782c59e344294569722cc5531a8862ab6633f4616e46bb46e55c6224bb6d808
+  data.tar.gz: 8035330d8eea2aed94243161bff6e93426befa2beda2e474d1bacd80341363a7777728851d068509b1e69a5472f0f31be9b93fcf9d13c6ae64c68538aa4602d5

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.1] - 2026-10-25
+
+### Changed
+
+- Replace wait-by-polling with the semantic wake contract in the HITL workflow (PR74): one scoped watch per pending answer, end the turn, reconcile on wake.
+
+## [0.24.0] - 2026-10-23
+
+### Added
+
+- Add read-only semantic event observations with configured-owner filtering; exclude delivery metadata and unrelated recipients.
+
 ## [0.23.2] - 2026-10-20
 
 ### Fixed

data/README.md

@@ -78,3 +78,15 @@ bin/ace-test ace-hitl all
 `ace-hitl` owns HITL event semantics and the markdown contract.
 `ace-support-items` remains generic support infrastructure and does not absorb
 HITL-specific behaviour.
+
+### Read semantic event revisions
+
+`ace-hitl observe --scope current --limit 500` prints one JSON object with schema
+`ace.hitl.observation/v1` and a bounded `events` list. `--scope all` includes linked
+worktrees of this repository. Each row contains a hashed canonical file identity,
+event ID, semantic revision hash, type/status and task/assignment references.
+It emits no private message or answer text. It reads active (non-special-folder) canonical events and
+does not import transports, acknowledge, archive, resume or mutate events.
+Delivery/poll timestamps and filesystem mtime are excluded from revisions;
+content, answers and report/status changes are included. Exceeding the configured
+limit refuses the entire projection rather than silently truncating it.

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

@@ -3,8 +3,8 @@ doc-type: workflow
 title: HITL Workflow
 purpose: Standardize human-attention handling for blocked and completed work using ace-hitl events.
 ace-docs:
-  last-updated: '2026-10-18'
-  last-checked: '2026-10-18'
+  last-updated: '2026-10-23'
+  last-checked: '2026-10-23'
 ---
 
 # HITL Workflow
@@ -98,11 +98,19 @@ ace-hitl show <hitl-id>
 ace-hitl update <hitl-id> --answer "<human decision>"
 ```
 
-Polling is the default reliability path for the requesting agent:
-
-```bash
-ace-hitl wait <hitl-id>
-```
+Waiting on a pending answer is semantic, never a blocking poll. While an
+answer is pending (for example a RubyGems OTP window of ~30–45 s), the
+waiting session registers exactly ONE in-process `/watch` scoped to the
+project ace-hitl transport folder (the folder holding that case's
+request/reply 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 <hitl-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 (`ace-hitl wait` blocks the turn — it is a sleep/poll
+command, not a waiting strategy), and never introduce cron, systemd, or any
+external heartbeat — 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.
 
 ### 4b) Remote delivery through configured adapter routes
 

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require "ace/support/cli"
+require_relative "../../molecules/event_observation"
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Observe < Ace::Support::Cli::Command
+          desc "Read bounded semantic event revisions without private message text"
+          option :scope, type: :string, default: "current", desc: "current or all linked worktrees"
+          option :owner, type: :string, desc: "Configured recipient owning incoming events"
+          option :limit, type: :integer, default: 500, desc: "Maximum event count (1..2000)"
+          def call(**options)
+            scope = options[:scope] || "current"
+            raise Ace::Support::Cli::Error, "invalid scope" unless %w[current all].include?(scope)
+            puts JSON.generate(Molecules::EventObservation.new.call(scope: scope, limit: options[:limit] || 500, owner: options[:owner]))
+          rescue ArgumentError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli.rb

@@ -8,6 +8,7 @@ require_relative "cli/commands/operator_question"
 require_relative "cli/commands/read"
 require_relative "cli/commands/show"
 require_relative "cli/commands/list"
+require_relative "cli/commands/observe"
 require_relative "cli/commands/update"
 require_relative "cli/commands/wait"
 require_relative "cli/commands/deliver"
@@ -31,6 +32,7 @@ module Ace
         ["read", "Read authenticated lifecycle request facts"],
         ["show", "Show HITL event details"],
         ["list", "List HITL events"],
+        ["observe", "Read semantic event revisions"],
         ["update", "Update HITL event metadata or answer"],
         ["send", "Send a HITL event through the configured adapter routes"],
         ["wait", "Wait for an answer on a specific HITL event"],
@@ -58,6 +60,7 @@ module Ace
       register "read", CLI::Commands::Read
       register "show", CLI::Commands::Show
       register "list", CLI::Commands::List
+      register "observe", CLI::Commands::Observe
       register "update", CLI::Commands::Update
       register "send", CLI::Commands::Send
       register "wait", CLI::Commands::Wait

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+require "digest"
+require "json"
+
+module Ace
+  module Hitl
+    module Molecules
+      # Read-only semantic projection. No private text is emitted; delivery
+      # timestamps, filesystem metadata and observer acknowledgements are not
+      # decision changes. Canonical HITL remains the only event owner.
+      class EventObservation
+        def initialize(manager: Organisms::HitlManager.new)
+          @manager = manager
+        end
+
+        def call(scope: "current", limit: 500, owner: nil)
+          raise ArgumentError, "invalid observation limit" unless (1..2000).cover?(limit)
+          events = @manager.list(in_folder: "next", scope: scope, limit: limit, strict: true)
+          raise ArgumentError, "observation exceeds configured event budget" if events.size > limit
+          address = owner && Molecules::HitlAddressResolver.new(config: @manager.config).resolve(owner)
+          events = events.select { |event| incoming?(event, address) } if address
+          rows = events.map do |event|
+            semantic = [event.id, event.type, event.status, event.result, event.kind,
+              event.title, event.content, event.answer, event.questions,
+              Array(event.tags).sort, canonical(event.recipient), canonical(event.reply_to),
+              event.metadata.values_at("task", "assignment", "step", "step_name", "resume_instructions")]
+            {"key" => Digest::SHA256.hexdigest(event.file_path.to_s),
+             "id" => event.id, "revision" => Digest::SHA256.hexdigest(JSON.generate(canonical(semantic))),
+             "type" => event.type, "status" => event.status, "result" => event.result,
+             "task" => event.metadata["task"], "assignment" => event.metadata["assignment"]}
+          end
+          {"schema" => "ace.hitl.observation/v1", "events" => rows.sort_by { |row| row["key"] }}
+        end
+
+        private
+
+        # Questions created locally are outbound until actually answered. A
+        # worker's reply belongs to that worker, not every linked-worktree actor.
+        # Native instructions have no recipient; their explicit import root owns them.
+        def incoming?(event, address)
+          local = File.expand_path(event.file_path).start_with?(File.expand_path(@manager.root_dir) + File::SEPARATOR)
+          return local if Array(event.tags).include?("hermes-instruction")
+          if event.question? && event.answered?
+            return local && event.reply_to &&
+              event.reply_to["machine"] == @manager.config.dig("hitl", "machine") &&
+              File.expand_path(event.reply_to["folder"].to_s) == File.expand_path(@manager.root_dir)
+          end
+          recipient = event.recipient
+          recipient && address.all? { |key, value| recipient[key] == value }
+        end
+
+        def canonical(value)
+          case value
+          when Hash then value.sort.to_h.transform_values { |item| canonical(item) }
+          when Array then value.map { |item| canonical(item) }
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/organisms/hitl_manager.rb

@@ -94,10 +94,12 @@ module Ace
           }
         end
 
-        def list(status: nil, kind: nil, type: nil, delivery: nil, in_folder: "next", tags: [], scope: nil)
+        def list(status: nil, kind: nil, type: nil, delivery: nil, in_folder: "next", tags: [], scope: nil, limit: nil, strict: false)
           effective_scope = @scope_resolver.effective_scope(scope)
           scan_results = scan_results_for_scope(effective_scope, in_folder: in_folder)
+          raise ArgumentError, "observation exceeds configured event budget" if limit && scan_results.size > limit
           events = load_events(scan_results)
+          raise ArgumentError, "incomplete HITL observation" if strict && events.size != scan_results.size
 
           events = events.select { |event| event.status == status } if status
           events = events.select { |event| event.kind == kind } if kind

data/lib/ace/hitl/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Hitl
-    VERSION = "0.23.2"
+    VERSION = "0.24.1"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.23.2
+  version: 0.24.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-hitl-contract
@@ -160,6 +160,7 @@ files:
 - lib/ace/hitl/cli/commands/duty.rb
 - lib/ace/hitl/cli/commands/lifecycle_command.rb
 - lib/ace/hitl/cli/commands/list.rb
+- lib/ace/hitl/cli/commands/observe.rb
 - lib/ace/hitl/cli/commands/operator_question.rb
 - lib/ace/hitl/cli/commands/pending.rb
 - lib/ace/hitl/cli/commands/read.rb
@@ -198,6 +199,7 @@ files:
 - lib/ace/hitl/lifecycle/tls_service.rb
 - lib/ace/hitl/live_client.rb
 - lib/ace/hitl/models/hitl_event.rb
+- lib/ace/hitl/molecules/event_observation.rb
 - lib/ace/hitl/molecules/hitl_address_resolver.rb
 - lib/ace/hitl/molecules/hitl_answer_editor.rb
 - lib/ace/hitl/molecules/hitl_config_loader.rb