ace-hitl 0.23.1 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9186e91db61d509bafd0c44d8ad023ed208614ad8cbfe749d3b49b0bbf10772
-  data.tar.gz: 151a5ad5cda6dc92256a7f2f604249858c04666c23a5a6ce85c9347dbf4640f4
+  metadata.gz: 066770bf07c22e97f6d1571d8d7697a9681df2872102b9454e26dc934d494162
+  data.tar.gz: 398b6537945687a92f34a0284d9e687f7b41cfea777352c9b7046a07ef45cd9a
 SHA512:
-  metadata.gz: 8f6a6ef440d4404df3868ddc1e416032a09a1b59eb36e9d9a9317f214939677a5c58a724ec8cebd10bf88a7d5d1f412671f724be0957dd54c938b54cf06a1c44
-  data.tar.gz: 6dd4dae6d026e1167dcb7225188f7b5e73fd9fbfc4fde1625e1988daf4fb4922b2e8a477e5f142c68aad6032a806512fc6506ab0ad05eb71aed144627965e137
+  metadata.gz: cb37ecff31019de3e8007964a8631e9f8e33c7dd5ba4be5505b84a4172c030e7eadf4580e8e70b962b8d26942a4b1a6221ed9a7641adb8726e4dce408b11c734
+  data.tar.gz: a7ecb1759adaa8e6ae5dae068eb556bc0f094cd905a11b12f30f1f1bd6012ea61f68487eeeddf48298ee92de212b7b5c57c893e371a2234b20b9ca18f1475035

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Select addressed-event routes by configured recipient names resolved to the
+  exact stored address. Unrelated terminal/Telegram routes no longer send or
+  create false delivery failures. Zero matches fail before adapter IO.
+  **Configuration migration:** add `recipients: [name]` to each addressed route;
+  names must exist in `hitl.recipients`. Recipient-less local events retain their
+  explicitly configured route set.
+- Accept native Herdr panel handles such as `w7:p1` without changing machine or
+  folder validation.
+- Provide first-answer-wins `HitlManager#accept_answer` for native transport
+  imports; exact replays preserve bytes and conflicting answers cannot replace
+  an existing answer under the case write lock.
+
 ## [0.23.1] - 2026-10-18
 
 ### 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/docs/usage.md

@@ -88,7 +88,7 @@ ace-hitl create "Blocked on auth" --kind decision --to overseer --task 8xg.t.sbz
   original case and the right agent — task/assignment/step are context,
   never an ID substitute.
 - Route delivery (`send`) requires a panel-form recipient. A folder-form
-  recipient has no shipped delivery route: every route refuses it per-route
+  recipient has no shipped delivery adapter: selected adapters refuse it per-route
   with a clear `failed` reason (the event file already sitting in a folder
   is a local write, not a delivery confirmation). Refusal semantics are
   strict on both axes of the address: the terminal adapter delivers only
@@ -159,11 +159,13 @@ hitl:
   adapters:
     routes:
       - route: overseer-terminal   # display name; defaults to the adapter name
+        recipients: [overseer]     # configured names resolved to the stored destination
         adapter: terminal          # built-in: any ace-runtime terminal
         runtime: herdr             # tmux | herdr
         pane: p5                   # opaque pane handle (runtime-owned)
         machine: lab01             # defaults to hitl.machine; recipient machine must match
       - route: captain-telegram
+        recipients: [captain]
         adapter: hermes            # ships in ace-hitl-hermes
         channel: project
         machine: lab01             # defaults to hitl.machine
@@ -176,14 +178,20 @@ ace-hitl send 8xhkep
 ```
 
 ```
-HITL event 8xhkep sent through 2 route(s):
+HITL event 8xhkep sent through 1 route(s):
   overseer-terminal (terminal): delivered - text pushed to herdr pane p5
-  captain-telegram (hermes): unavailable - ...
 ```
 
 Rules:
 
-- One result line per route; a route's success never hides another route's
+- For an addressed event, only routes whose `recipients` resolve to its exact
+  stored machine and panel/folder are selected. Changing a configured alias does
+  not redirect an existing case. Missing selectors do not match addressed events;
+  no match fails before adapter invocation or delivery-state writes. Recipient-less
+  events use the explicitly configured route set.
+- Several matching routes deliver to the same intended recipient independently.
+  Unmatched routes are not invoked or recorded as failures. One result line per
+  selected route; a route's success never hides another selected route's
   failure. Exit 0 only when every route is `delivered`; exit 1 on any
   `failed`/`unavailable` route, no configured routes (concrete error naming
   `hitl.adapters.routes`), or unknown/ambiguous ref. An unknown adapter on
@@ -199,6 +207,8 @@ Rules:
   on questions only, task/assignment/step context.
 - `delivered` means accepted by the route's transport. An unavailable
   adapter never reroutes to another recipient.
+- Native terminal handles such as `w7:p1` are accepted unchanged as `panel`.
+  This does not relax the machine-token or folder-traversal rules.
 - Adding an adapter requires no ace-hitl change: a gem ships
   `lib/ace/hitl/adapters/<name>.rb` calling `Ace::Hitl::Adapters.register`
   (duck contract: `factory.call(route)` → adapter with

data/lib/ace/hitl/atoms/hitl_address.rb

@@ -11,6 +11,7 @@ module Ace
       # Display strings align with the hermes <machine>/<name>/<id> shape.
       class HitlAddress
         TOKEN_PATTERN = /\A[a-z0-9][a-z0-9_-]*\z/i.freeze
+        PANEL_PATTERN = /\A[a-z0-9][a-z0-9_:-]{0,127}\z/i.freeze
 
         class InvalidAddress < StandardError; end
 
@@ -48,8 +49,8 @@ module Ace
               address["id"] = id.to_s
             end
           else
-            unless panel.to_s.match?(TOKEN_PATTERN)
-              raise InvalidAddress, "address panel '#{panel}' is not a valid token"
+            unless panel.to_s.match?(PANEL_PATTERN)
+              raise InvalidAddress, "address panel '#{panel}' is not a valid terminal handle"
             end
 
             address["panel"] = panel.to_s

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/molecules/hitl_route_loader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "hitl_address_resolver"
+
 module Ace
   module Hitl
     module Molecules
@@ -64,9 +66,37 @@ module Ace
 
           normalized["route"] = route
           normalized["adapter"] = adapter
+          if normalized.key?("recipients") &&
+              (!normalized["recipients"].is_a?(Array) || normalized["recipients"].empty? ||
+               !normalized["recipients"].all? { |name| name.is_a?(String) && !name.strip.empty? })
+            raise InvalidRouteError, "route '#{route}' recipients must be a non-empty list of configured recipient names"
+          end
           normalized
         end
 
+        # Selection happens before adapter construction or delivery-state writes.
+        # Names are configuration references, not labels copied onto an event:
+        # compare their resolved addresses to the event's immutable destination.
+        def self.for_recipient(routes, recipient:, config:)
+          return routes if recipient.nil?
+
+          resolver = HitlAddressResolver.new(config: config)
+          destination = recipient.reject { |key, _| key == "id" }
+          selected = routes.select do |route|
+            addresses = Array(route["recipients"]).map do |name|
+              resolver.resolve(name).reject { |key, _| key == "id" }
+            end
+            addresses.include?(destination)
+          end
+          if selected.empty?
+            raise NoRoutesError, "no adapter route matches recipient #{Atoms::HitlAddress.to_s(recipient)}; " \
+              "set route recipients to configured recipient names in #{CONFIG_LOCATION}"
+          end
+          selected
+        rescue HitlAddressResolver::UnknownRecipientError, HitlAddressResolver::InvalidAddressError => e
+          raise InvalidRouteError, e.message
+        end
+
         def self.stringified(entry)
           entry.each_with_object({}) do |(key, value), memo|
             memo[key.to_s] = value

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

@@ -27,6 +27,7 @@ module Ace
         end
 
         class NotAnswerableError < StandardError; end
+        class AnswerConflictError < StandardError; end
 
         attr_reader :root_dir, :last_list_total, :last_folder_counts, :config
 
@@ -93,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
@@ -153,6 +156,21 @@ module Ace
           loader.load(current_path, id: event.id, special_folder: current_special)
         end
 
+        # Transport imports are first-answer-wins. The case's own write lock
+        # checks the answer again, so replay cannot overwrite a human answer.
+        # Explicit `update --answer` remains an intentional editing operation.
+        def accept_answer(ref, answer:, scope: nil)
+          resolved = resolve_for_mutation(ref, scope: scope)
+          return nil unless resolved
+          event = resolved[:event]
+          raise NotAnswerableError, "reports do not await an answer" if event.report?
+          raise NotAnswerableError, "managed requests require their authenticated lifecycle" if event.metadata["lab_request_id"]
+          raise ArgumentError, "answer is empty" if answer.to_s.strip.empty?
+          apply_field_and_answer_updates(event.file_path, set: {}, add: {}, remove: {},
+            answer: answer, first_answer: true)
+          Molecules::HitlLoader.new.load(event.path, id: event.id, special_folder: event.special_folder)
+        end
+
         def wait_for_answer(ref, scope: nil, poll_every: 600, timeout: 14_400, waiter: {}, now_proc: nil, sleeper: nil)
           poll_every = normalize_poll_seconds(poll_every)
           timeout = normalize_timeout_seconds(timeout)
@@ -408,7 +426,7 @@ module Ace
           File.unlink(tmp_path) if tmp_path && File.exist?(tmp_path)
         end
 
-        def apply_field_and_answer_updates(file_path, set:, add:, remove:, answer:)
+        def apply_field_and_answer_updates(file_path, set:, add:, remove:, answer:, first_answer: false)
           File.open(file_path, File::RDWR) do |file|
             file.flock(File::LOCK_EX)
             file.rewind
@@ -416,6 +434,11 @@ module Ace
             content = file.read
             frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
             body = body.sub(/\A\n/, "")
+            previous = body.match(/^## Answer[ \t]*(?:\n(.*))?\z/m)&.[](1).to_s.strip
+            if first_answer && (frontmatter["answered"] == true || !previous.empty?)
+              raise AnswerConflictError, "case already has a different answer" unless previous == answer.to_s.strip
+              return
+            end
 
             Ace::Support::Items::Molecules::FieldUpdater.apply_set(frontmatter, set)
             Ace::Support::Items::Molecules::FieldUpdater.apply_add(frontmatter, add)

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

@@ -57,6 +57,7 @@ module Ace
           raise Adapters::Error, "HITL event '#{ref}' not found" unless current
 
           event = current[:event]
+          routes = Molecules::HitlRouteLoader.for_recipient(routes, recipient: event.recipient, config: @config)
           text = Atoms::HitlEventText.call(event)
           delivery = event.metadata["delivery"]
 

data/lib/ace/hitl/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Hitl
-    VERSION = "0.23.1"
+    VERSION = "0.24.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.23.1
+  version: 0.24.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-23 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