ace-hitl 0.23.1 → 0.23.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9186e91db61d509bafd0c44d8ad023ed208614ad8cbfe749d3b49b0bbf10772
-  data.tar.gz: 151a5ad5cda6dc92256a7f2f604249858c04666c23a5a6ce85c9347dbf4640f4
+  metadata.gz: 973228979e65843573a7dc67bc91566a22478ca762f3751babdbd269e0960ca9
+  data.tar.gz: c4b09f84c60c2bfb225294d56c4bfa4abded7ced7ecc75fe830ecc8987e239ee
 SHA512:
-  metadata.gz: 8f6a6ef440d4404df3868ddc1e416032a09a1b59eb36e9d9a9317f214939677a5c58a724ec8cebd10bf88a7d5d1f412671f724be0957dd54c938b54cf06a1c44
-  data.tar.gz: 6dd4dae6d026e1167dcb7225188f7b5e73fd9fbfc4fde1625e1988daf4fb4922b2e8a477e5f142c68aad6032a806512fc6506ab0ad05eb71aed144627965e137
+  metadata.gz: f08442f7582db2b088cbaa5f0af24d9d81bc7caccdf5e2bdfc9de5feb6a9ee9f5125f541f02e9585f4921933fa08a712fe47e80e8c668dd89330084654e13984
+  data.tar.gz: c3ad787393cc3c045efda84016b9e2783fa8fb5f3696e4a9da9e072840dfb99e12f706c79bafc6b655f90f4ccd35f661d0f3b05932a96d00d17ed563a63b27c1

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/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/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
 
@@ -153,6 +154,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 +424,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 +432,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.23.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.23.1
+  version: 0.23.2
 platform: ruby
 authors:
 - Michal Czyz