ace-hitl-hermes 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4748399831bb81daa3c725bed83373df44675fa005410f22e88632073abe839a
-  data.tar.gz: 63d3164afdfb14a1ff5072f553bc9a5c5f9e3a092ebb4088ab0822bf8522fddc
+  metadata.gz: cea9b0aa8245c024ee39a1aa4a63f55e7513c2d906f5648b3e19f2d70ac8b7b4
+  data.tar.gz: aa9c46cdc21476780ce55d9ab63b7b371c2b454a4e1c08ae22a5a0ec93ec11e0
 SHA512:
-  metadata.gz: e6781892f412b2c1ba7798f2725a3c454f7c72844de9c81a68224add320e636539863fba1201bdb15d2753f878f5b932738b0fab1e34eaab8fc3e76a9a342cb7
-  data.tar.gz: '07811266c2c80bf1277575bf6e295b522133ea4f06169cdface8d761b4c2ce9216ae65f22b127b8e3b552df58adc57a7e30be995cc5c82091237838a353e21d9'
+  metadata.gz: 1d33d3b81a50402c434dd91e62739cd48ff35ae2a807ab937120b51a968dd15a6e0a11d59542565a5fa6dd3db57b98ddcc42198772018aea6ce91d4b1a9082d4
+  data.tar.gz: 32b5352923b92216718c6b5667c3e773a36f108327300427424a5f4f2bf82b5f09fad1849aec1f64c8947594a75e9a3b131cb8b1903664b57a8654a494f10d20

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-05
+
+### Added
+
+- Resolve immutable second-commander proposals through confirmed-delivery sixteen-hour policy and canonical Assign authorization.
+- Installable correlated Telegram transport, explicit Captain/group registry, authenticated HITL IPC and guarded Hermes plugin assets.
+- Durable non-secret submission acknowledgements, ingress receipts, polling offsets and conservative reconciliation checkpoints.
+- Supervised single polling actor with gateway ownership checks and recovery without duplicate lifecycle effects.
+
+### Changed
+
+- Declare the required direct dependencies and minimum producer versions for this coordinated release: `ace-hitl ~> 0.12`, `ace-hitl-contract ~> 0.2`.
+
+- Consume the shared managed binding envelope and publish newly created authenticated pending requests through explicitly registered project channels in the existing single Telegram polling actor.
+- Ordinary answer folder publication requires authenticated request classification; OTP and sensitive answers are refused before any file creation.
+
+### Fixed
+
+- Block later proposal approval behind unresolved earlier ingress and reconcile canonical proposer wakes after the existing transport poll loop establishes coverage.
+- Submit authenticated requests from users named captain; leave unmanaged instructions for their target based on lifecycle authority, not sender labels.
+- Retain the continuous polling owner across transient pending-publication transport outages, report the channel failure and retry without consuming the request.
+
 ## [0.1.0] - 2026-09-27
 
 ### Added

data/README.md

@@ -1,14 +1,14 @@
 # ace-hitl-hermes
 
 Folder-as-interface HITL transport plugin for the hermes relay
-(spec `8wm.t.vs1`). The shared folder between the lab and hermes **is**
+(specs `8wm.t.vs1` and `8wm.t.y24`). The shared folder between the lab and hermes **is**
 the transport:
 
 - a **message** is a file `<id>.json` in the channel folder;
 - the **address** is `<machine>/<folder>/<id>`;
 - **delivery** is push — the consuming side picks the validated file up
-  and takes it to its target (labd pushes answers to the asking agent,
-  hermes surfaces questions to the Captain);
+  and takes it to its target (the explicit HITL live client queues ordinary
+  answers to the exact native owner; Hermes surfaces questions to the Captain);
 - **ACK** is the deletion of the file after delivery.
 
 The Captain's answer is a file `<folder>/<id>.json` with the fields
@@ -17,7 +17,7 @@ tmp file + rename) without root.
 
 ## Contract
 
-- Folder contract: `ace.hitl.hermes.folder/v1` (spec `8wm.t.vs1`).
+- Folder contract: `ace.hitl.hermes.folder/v1` (specs `8wm.t.vs1` and `8wm.t.y24`).
 - Message schema: `ace.hitl.hermes.message/v1`; the machine-readable
   JSON Schema ships at
   `lib/ace/hitl/hermes/schemas/message.v1.schema.json`.
@@ -53,6 +53,7 @@ registry.default = "inbox"
 lines = []
 box = Ace::Hitl::Hermes::Organisms::HermesBox.new(
   channel: "inbox", registry: registry,
+  answer_authorizer: ->(id) { authenticated_hitl_client.read(id) },
   notifier: ->(line) { lines << line }
 )
 
@@ -70,9 +71,25 @@ result.messages.each do |msg|
 end
 ```
 
+## Telegram transport
+
+The installed `ace-hitl-hermes serve` actor owns exact registered-group correlation,
+submission acknowledgements, durable ingress sequencing and conservative checkpoints.
+OTP goes directly through authenticated `ace-hitl` IPC; sensitive folder answers are
+rejected before publication. Ordinary answers require authenticated request classification.
+See [configuration, single polling owner and recovery](docs/usage.md).
+
 ## Development
 
 ```sh
 ace-test atoms      # fast unit tests
 ace-test            # the whole package suite
 ```
+
+The installed `serve` actor also publishes newly created scoped requests from
+authenticated `pending(project:)` into its registered folder channel before
+submitting questions. Ask needs no manual post or hidden Lab watcher. Projects
+without a registered authorized channel remain pending. Folder identity/body
+conflicts refuse publication; repeated runs do not send the same submitted
+question again. This actor remains the sole Telegram polling owner described
+above. Actual installed Telegram acceptance is a separate deployment gate.

data/docs/usage.md

@@ -0,0 +1,89 @@
+# Correlated Hermes Telegram transport
+
+Install `ace-hitl-hermes` and configure the supervised `ace-hitl-hermes serve` actor as the only Telegram polling owner. Lab provides identities and deployment paths; the package owns routing, folder publication, protected IPC, correlation and checkpoint production.
+
+## Configuration
+
+A registry has no inferred default or legacy-file fallback:
+
+```json
+{
+  "schema": "ace.hitl.hermes.channels/v1",
+  "channels": [{
+    "name": "project", "machine": "lab", "folder": "/run/hermes/project",
+    "target": "project-overseer", "projects": ["project"], "chat_id": "-1001234567890",
+    "captain_user_ids": ["123456789"]
+  }]
+}
+```
+
+Every project, group, folder and instruction target maps to exactly one channel. Captain IDs are numeric identities, never usernames. Topics within a group share that registered channel; separate authority requires separate registered groups.
+
+A runtime file supplies concrete deployment configuration:
+
+```json
+{
+  "schema": "ace.hitl.hermes.runtime/v1",
+  "registry": "/etc/ace-hitl-hermes/channels.json",
+  "state": "/var/lib/ace-hitl-hermes",
+  "hitl_socket": "/run/ace-hitl/lifecycle.sock",
+  "hitl_service_uid": 0,
+  "token_file": "/run/hermes-secrets/telegram-bot-token",
+  "polling_owner": "ace-hitl-hermes",
+  "hermes_gateway_config": "/home/hermes/.hermes/gateway.yaml"
+}
+```
+
+Run the actor as the unprivileged transport identity authorized by the `ace-hitl` service. The state directory and token file must belong to that identity and be private (0700/0600). Folder writes reject root and preserve the existing message.v1 0640 contract. `ace-hitl` authenticates both Unix socket peers and independently enforces project/actor authorization, liveness, OTP scope and expiry.
+
+Before starting the actor, disable Telegram in the actual Hermes gateway configuration:
+
+```yaml
+platforms:
+  telegram:
+    enabled: false
+```
+
+Stop/restart the existing gateway to apply that change. `serve` validates this configuration and refuses an enabled or unverifiable Telegram gateway. Its state-directory polling lease excludes a second package actor. During a transient HITL pending-publication transport outage, continuous `serve` reports the unavailable channel on stderr, waits one second, keeps its polling lease and retries on the next cycle without consuming or replacing the request. A single-pass run reports the error to its caller. A Telegram 409/conflicting poll failure invalidates ingress coverage rather than pretending it is connected. Never run the package actor and Hermes gateway against the same bot at the same time.
+
+```sh
+ace-hitl-hermes serve --config /etc/ace-hitl-hermes/runtime.json
+```
+
+The actor sends non-Captain question files only after authenticating their corresponding lifecycle request. It uses the lifecycle attempt as the immutable transport revision. Plain Captain instructions remain question files with sender `captain`, routed to the folder's configured target. The target consumes those files using the existing folder contract and ACKs by deletion.
+
+## Replies and recovery
+
+Use Telegram Reply to the exact submitted request message, or `/hitl-reply REQUEST_ID ANSWER`. The command names an immutable request correlation in the same registered group; a conflicting Reply target is rejected. Plain messages create new instructions and never satisfy a pending request. Unknown Reply, missing registry, bad sender and malformed input fail closed.
+
+```sh
+ace-hitl-hermes delivery --request REQUEST_ID --config /etc/ace-hitl-hermes/runtime.json
+ace-hitl-hermes ingress reconcile --request REQUEST_ID --through 2026-10-04T22:00:00Z --format json --config /etc/ace-hitl-hermes/runtime.json
+```
+
+The `ace.hitl.hermes.delivery/v1` result carries request/revision/channel/chat/message identities, status and trusted `submitted_at` only after Telegram confirms submission. Submission is not a read receipt. `failed` preserves the question and may retry; `uncertain` never automatically resends and starts no decision clock. Investigate uncertain sends before taking any recovery action.
+
+The `ace.hitl.hermes.ingress-checkpoint/v1` result carries `healthy`, `drained`, checkpoint cutoff/sequence and unresolved correlated ingress metadata. Receipt time is stamped by the actor, not copied from Telegram. The actor journals receipt before delivery and advances its durable Telegram offset after processing. Only an empty update batch proves backlog drainage; poll failures, retention gaps, queued replies, uncertain submission and unresolved delivery produce unknown or undrained results. Each coverage break creates a durable generation and retains the prior epoch evidence. A recovered empty poll starts healthy coverage for fresh requests; requests submitted in an older generation remain unknown and cannot gain silence approval across the gap. A silence-based approval consumer must defer on those results and revalidate the checkpoint inside its decision transition.
+
+The private journal retains correlation, ingress and terminal transport metadata for at least 24 hours. Authoritative lifecycle receipts remain in `ace-hitl` beyond that window. A resumed ordinary reply recovers from its protected folder answer; the lifecycle service prevents a repeated effect. Unresolved records remain visible and block drainage.
+
+OTP answers bypass ordinary answer files. The low-level `HermesBox` answer publisher requires an authenticated request-classification callback and rejects OTP/sensitive classification before any file creation. The relay sends the value directly to `ace-hitl` authenticated IPC and records only a sanitized status. No OTP value or derived hash enters the journal, checkpoint, preview logs or target instruction folder. If the endpoint is unavailable or the actor crashes after journaling a secret receipt, `secret-unavailable` discards the transient value and disables further delivery on that original challenge; recover the endpoint and request a fresh authorized challenge/code. Telegram's third-party message history is outside this erasure guarantee.
+
+## Gateway guard plugin
+
+```sh
+ace-hitl-hermes plugin install --path /home/hermes/.hermes/plugins/ace-hitl-hermes
+```
+
+Configure the gateway process with `ACE_HITL_HERMES_CONFIG` pointing to the runtime file, and put the installed executable on PATH (or set `ACE_HITL_HERMES_EXE` to its absolute path). The guard registers `/hitl-reply` and `pre_gateway_dispatch`, intercepting replies before inbound preview logging even when IPC/configuration fails. Its subprocess sends input through stdin and suppresses child output. The guard alone does not prove polling drainage; the supervised actor is the checkpoint producer. Package polling ownership still requires disabling the gateway's Telegram adapter.
+
+## Exit codes and acceptance
+
+Successful commands return 0 and JSON. Rejected input/configuration returns 1 with a sanitized error. SIGINT returns 130. OTP is never accepted as an argument: `receive` takes a bounded JSON event from stdin.
+
+Local acceptance exercises registered controlled identities, real message folders, fsynced state, a real authenticated Unix socket and installed guard assets. Live Telegram channel acceptance and the Lab transport smoke/removal of `hermes-lab-hitl`, `lab-hitl-broker` and `lab-hitl-channels` remain explicit `lab-config:gad.2` delivery gates; local tests do not claim those deployment results.
+
+A lifecycle requester named `captain` is handled like every other authenticated
+requester. Submission authority comes from the scoped lifecycle record and its
+exact project/body binding, not the folder sender label. Unmanaged Captain
+instructions remain in the folder for their target and are not sent as requests.

data/exe/ace-hitl-hermes

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/hitl/hermes/cli"
+trap("INT") { exit 130 }
+begin
+  Ace::Hitl::Hermes::CLI.start(ARGV)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit e.exit_code
+end

data/lib/ace/hitl/hermes/cli.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "optparse"
+require "fileutils"
+require_relative "runtime"
+
+module Ace
+  module Hitl
+    module Hermes
+      module CLI
+        def self.start(argv, input: $stdin, output: $stdout)
+          args = argv.dup
+          operation = args.shift
+          if [nil, "--help", "-h", "help"].include?(operation)
+            output.puts("ace-hitl-hermes serve|submit|receive|delivery|ingress reconcile|plugin install --config FILE")
+            return
+          end
+          if %w[--version version].include?(operation)
+            output.puts(Ace::Hitl::Hermes::VERSION)
+            return
+          end
+          operation = "reconcile" if operation == "ingress" && args.shift == "reconcile"
+          operation = "install" if operation == "plugin" && args.shift == "install"
+          options = {format: "json"}
+          parser = OptionParser.new do |o|
+            o.banner = "ace-hitl-hermes serve|submit|receive|delivery|ingress reconcile|plugin install [options]"
+            %w[config request revision channel through format path].each do |key|
+              o.on("--#{key} VALUE") { |value| options[key.to_sym] = value }
+            end
+            o.on("--once") { options[:once] = true }
+            o.on("--help") { output.puts(o); return }
+          end
+          parser.parse!(args)
+          raise ContractError, "unexpected arguments" unless args.empty?
+          raise ContractError, "only --format json is supported" unless options[:format] == "json"
+          if operation == "install"
+            destination = options.fetch(:path)
+            raise ContractError, "plugin installation requires an absolute path" unless File.absolute_path?(destination)
+            raise ContractError, "plugin destination already exists" if File.exist?(destination)
+            FileUtils.cp_r(File.expand_path("../../../../plugin", __dir__), destination)
+            output.puts(JSON.generate({"installed" => true, "path" => destination}))
+            return
+          end
+          runtime = Runtime.new(options.fetch(:config))
+          result = case operation
+          when "serve" then runtime.serve(once: options[:once]); {"status" => "stopped"}
+          when "submit"
+            runtime.relay.submit(channel: options.fetch(:channel), request: options.fetch(:request),
+              revision: options.fetch(:revision))
+          when "receive"
+            bytes = input.read(16 * 1024 + 1)
+            raise ContractError, "ingress frame too large" if bytes.bytesize > 16 * 1024
+            runtime.relay.receive(JSON.parse(bytes))
+          when "delivery" then runtime.relay.delivery(options.fetch(:request))
+          when "reconcile"
+            runtime.relay.reconcile(request: options.fetch(:request), through: options.fetch(:through))
+          else raise ContractError, "choose serve, submit, receive, delivery, ingress reconcile, or plugin install"
+          end
+          output.puts(JSON.generate(result))
+        rescue ContractError, JSON::ParserError, KeyError, OptionParser::ParseError, SystemCallError
+          # No exception detail: a malformed frame or HTTP error may contain a secret.
+          raise Ace::Support::Cli::Error, "Hermes operation rejected; verify configuration and non-secret delivery status"
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/organisms/hermes_box.rb

@@ -27,7 +27,7 @@ module Ace
           attr_reader :channel
 
           def initialize(channel:, registry: nil, id_generator: -> { SecureRandom.hex(6) },
-            notifier: nil, euid_provider: -> { Process.euid })
+            notifier: nil, euid_provider: -> { Process.euid }, answer_authorizer: nil)
             @channel =
               if channel.is_a?(Molecules::HermesChannels::Channel)
                 channel
@@ -40,6 +40,7 @@ module Ace
             @id_generator = id_generator
             @notifier = notifier || ->(_line) {}
             @euid_provider = euid_provider
+            @answer_authorizer = answer_authorizer
           end
 
           def address(id)
@@ -53,6 +54,16 @@ module Ace
           # so a collision there fails loudly instead of silently breaking
           # the question -> answer pairing. Returns the published Message.
           def publish(kind:, body:, sender:, timestamp:, id: nil)
+            if kind.to_s == "answer"
+              unless id && @answer_authorizer
+                raise ContractError, "answer publication requires authenticated request classification"
+              end
+              facts = @answer_authorizer.call(id)
+              unless facts.is_a?(Hash) && facts["id"] == id && facts["sensitive"] == false &&
+                  !%w[otp secret].include?(facts["kind"])
+                raise ContractError, "sensitive answers must use the protected HITL boundary"
+              end
+            end
             explicit_id = !id.nil?
             attempts = 0
             loop do

data/lib/ace/hitl/hermes/runtime.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/hitl/lifecycle"
+require_relative "../hermes"
+
+module Ace
+  module Hitl
+    module Hermes
+      class Runtime
+        attr_reader :registry, :journal, :relay, :config
+
+        def initialize(path, clock: -> { Time.now.utc })
+          @clock = clock
+          @config = JSON.parse(File.read(path))
+          unless @config.is_a?(Hash) && @config["schema"] == "ace.hitl.hermes.runtime/v1"
+            raise ContractError, "runtime configuration requires runtime/v1"
+          end
+          @registry = Transport::Registry.load(@config.fetch("registry"))
+          @journal = Transport::Journal.new(@config.fetch("state"))
+          @lifecycle = Ace::Hitl::Lifecycle::Client.new(
+            socket_path: @config.fetch("hitl_socket"), service_uid: @config.fetch("hitl_service_uid")
+          )
+          @relay = Transport::Relay.new(registry: @registry, journal: @journal, lifecycle: @lifecycle,
+            sender: ->(channel, question) { telegram.call(channel, question) }, clock: @clock)
+        rescue JSON::ParserError, KeyError, SystemCallError, ArgumentError
+          raise ContractError, "runtime configuration is unavailable or malformed"
+        end
+
+        def serve(once: false)
+          verify_polling_owner!
+          @journal.actor do
+            poller = Transport::Poller.new(relay: @relay, telegram: telegram, journal: @journal,
+              registry: @registry, clock: @clock)
+            # Establish the new coverage epoch before issuing questions, so
+            # a startup submission is never stamped before its coverage begins.
+            begin
+              poller.once
+            rescue ContractError
+              raise if once
+            end
+            loop do
+              # Only an authoritative lifecycle request may be submitted.
+              # A sender label is not authority or a reserved OS username.
+              @registry.channels.each do |channel|
+                box_channel = Molecules::HermesChannels::Channel.new(
+                  name: channel["name"], machine: channel["machine"], folder: channel["folder"]
+                )
+                box = Organisms::HermesBox.new(channel: box_channel)
+                begin
+                  publish_pending(channel, box)
+                rescue Ace::Hitl::Lifecycle::TransportError => e
+                  raise if once
+                  warn "ace-hitl-hermes: pending publication unavailable for #{channel['name']} (#{e.class}); retrying"
+                  sleep 1
+                  next
+                end
+                box.poll.messages.each do |message|
+                  next unless message.question?
+                  begin
+                    facts = @lifecycle.read(message.id)
+                    revision = facts["proposal"] ? facts.fetch("proposal").fetch("revision_id") : facts.fetch("attempt")
+                    @relay.submit(channel: channel["name"], request: message.id, revision: revision)
+                  rescue StandardError
+                    # Pending folder + visible delivery status are retained.
+                  end
+                end
+              end
+              begin
+                poller.once
+              rescue ContractError
+                raise if once
+                sleep 1
+              end
+              reconcile_proposals
+              break if once
+            end
+          end
+        end
+
+        def verify_polling_owner!
+          unless @config["polling_owner"] == "ace-hitl-hermes"
+            raise ContractError, "serve requires explicit polling_owner ace-hitl-hermes"
+          end
+          path = @config.fetch("hermes_gateway_config")
+          gateway = YAML.safe_load_file(path, aliases: false)
+          unless gateway.is_a?(Hash) && gateway.dig("platforms", "telegram", "enabled") == false
+            raise ContractError, "disable Telegram in the configured Hermes gateway before starting serve"
+          end
+        rescue KeyError, SystemCallError, Psych::Exception
+          raise ContractError, "cannot verify Hermes gateway Telegram polling is disabled"
+        end
+
+        private
+
+        # The installed transport owns publication as well as Telegram polling.
+        # Ask writes only scoped lifecycle state; no hidden Lab watcher or
+        # HITL→Hermes dependency is required to get a question into message.v1.
+        def publish_pending(channel, box)
+          channel["projects"].each do |project|
+            @lifecycle.pending(project: project).each do |facts|
+              next unless facts["state"] == "created"
+              envelope = Ace::Hitl::Contract::ManagedEnvelope.load(facts.fetch("envelope"), expected: {
+                request_id: facts["id"], project: project, assignment_id: facts["assignment"], attempt_id: facts["attempt"]
+              })
+              status = @relay.delivery(facts["id"])["status"]
+              next unless %w[unknown failed].include?(status)
+              existing = box.poll.messages.find { |message| message.id == facts["id"] }
+              if existing
+                unless existing.question? && existing.body == facts["question"]
+                  raise ContractError, "managed question folder identity conflicts"
+                end
+                next
+              end
+              box.publish(kind: :question, id: facts["id"], body: facts["question"], sender: envelope["requester"],
+                timestamp: Time.at(Integer(facts["created_at"])).utc.iso8601)
+            end
+          end
+        rescue Ace::Hitl::Contract::InvalidEnvelope, KeyError, ArgumentError => e
+          raise ContractError, "managed pending publication binding is invalid (#{e.class})"
+        end
+
+        def reconcile_proposals
+          after = nil
+          loop do
+            page = @lifecycle.proposal_due(after: after)
+            page.fetch("items").each do |proposal|
+              @relay.reconcile(request: proposal.fetch("request_id"), through: proposal.fetch("deadline"))
+            end
+            cursor = page.fetch("next")
+            break unless cursor
+            raise ContractError, "proposal deadline cursor did not advance" unless cursor.is_a?(String) && (!after || cursor > after)
+            after = cursor
+          end
+        rescue Ace::Hitl::Lifecycle::Error, ContractError => e
+          warn "ace-hitl-hermes: proposal reconciliation unavailable (#{e.class}); deadlines deferred"
+        end
+
+        def telegram
+          @telegram ||= Transport::Telegram.new(token_file: @config.fetch("token_file"))
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/transport/journal.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Transport
+        # Single lock serializes send/receive/checkpoint with durable fsync commits.
+        # No message bodies or secret-derived digests belong in this journal.
+        class Journal
+          def initialize(directory)
+            @directory = File.expand_path(directory)
+            FileUtils.mkdir_p(@directory, mode: 0o700)
+            stat = File.lstat(@directory)
+            unless stat.directory? && !stat.symlink? && stat.uid == Process.euid && (stat.mode & 0o077).zero?
+              raise ContractError, "transport state requires an owned private directory"
+            end
+          end
+
+          def synchronize
+            path = File.join(@directory, "journal.lock")
+            File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+              lock.flock(File::LOCK_EX)
+              state = read
+              yield state, -> { write(state) }
+            ensure
+              lock.flock(File::LOCK_UN)
+            end
+          end
+
+          def actor
+            path = File.join(@directory, "poller.lock")
+            File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+              unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+                raise ContractError, "another Hermes polling actor owns this journal"
+              end
+              yield
+            ensure
+              lock.flock(File::LOCK_UN)
+            end
+          end
+
+          private
+
+          def read
+            path = File.join(@directory, "journal.json")
+            return {"schema" => "ace.hitl.hermes.transport/v1", "requests" => {}, "ingress" => [],
+                    "sequence" => 0, "poll" => {}} unless File.exist?(path)
+
+            File.open(path, File::RDONLY | File::NOFOLLOW) do |file|
+              stat = file.stat
+              unless stat.file? && stat.uid == Process.euid && (stat.mode & 0o077).zero?
+                raise ContractError, "transport journal must be owned and private"
+              end
+              state = JSON.parse(file.read)
+              unless state["schema"] == "ace.hitl.hermes.transport/v1" && state["requests"].is_a?(Hash) &&
+                  state["ingress"].is_a?(Array) && state["sequence"].is_a?(Integer) && state["poll"].is_a?(Hash)
+                raise ContractError, "transport journal is malformed"
+              end
+              state
+            end
+          rescue JSON::ParserError, SystemCallError
+            raise ContractError, "transport journal is unreadable"
+          end
+
+          def write(state)
+            temporary = File.join(@directory, ".journal-#{SecureRandom.hex(8)}")
+            File.open(temporary, File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0o600) do |file|
+              file.write(JSON.generate(state))
+              file.flush
+              file.fsync
+            end
+            File.rename(temporary, File.join(@directory, "journal.json"))
+            File.open(@directory) { |directory| directory.fsync }
+          ensure
+            File.unlink(temporary) if temporary && File.exist?(temporary)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/transport/poller.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Transport
+        # The sole supervised polling actor owns both getUpdates offset and
+        # proof that a batch's ingress has been handled before confirmation.
+        class Poller
+          def initialize(relay:, telegram:, journal:, registry:, clock: -> { Time.now.utc })
+            @relay, @telegram, @journal, @registry, @clock = relay, telegram, journal, registry, clock
+          end
+
+          def once
+            cursor = nil
+            @journal.synchronize do |state, _commit|
+              cursor = state["cursor"] || {"offset" => 0, "through" => stamp, "generation" => 0, "coverage_from" => stamp}
+            end
+            # A durable queued record means a prior actor died with its body
+            # transient. Replay from the unadvanced offset; secret failures
+            # remain status-only and require a fresh challenge.
+            started = stamp
+            if Time.iso8601(started) - Time.iso8601(cursor["through"]) >= 24 * 60 * 60
+              invalidate_coverage(started)
+              cursor["coverage_from"] = started
+              cursor["generation"] += 1
+              @journal.synchronize do |state, commit|
+                state["cursor"] = cursor
+                commit.call
+              end
+            end
+            updates = @telegram.updates(offset: cursor["offset"])
+            ids = updates.map { |u| u.is_a?(Hash) && u["update_id"] }
+            unless ids.all? { |id| id.is_a?(Integer) && id >= cursor["offset"] } && ids == ids.sort && ids.uniq == ids
+              raise ContractError, "malformed Telegram update sequence"
+            end
+            unresolved = false
+            updates.each do |update|
+              message = update["message"]
+              next unless message.is_a?(Hash)
+              chat, from = message["chat"], message["from"]
+              next unless chat.is_a?(Hash) && from.is_a?(Hash)
+              next unless @registry.channels.any? { |c| c["chat_id"] == chat["id"].to_s }
+              event = {"platform" => "telegram", "chat_id" => chat["id"].to_s,
+                       "chat_type" => chat["type"], "user_id" => from["id"].to_s,
+                       "message_id" => message["message_id"].to_s,
+                       "reply_to_message_id" => message.dig("reply_to_message", "message_id").to_s,
+                       "text" => message["text"]}
+              begin
+                result = @relay.receive(event)
+                unresolved ||= %w[queued unresolved].include?(result["status"])
+              rescue ContractError
+                # Authority and malformed correlation are rejected, never
+                # forwarded into an agent pipeline or preview log.
+              end
+            end
+            finished = stamp
+            continuous = Time.iso8601(started) - Time.iso8601(cursor["through"]) < 24 * 60 * 60
+            # The getUpdates backlog is exhausted only on an empty response.
+            # A nonempty batch may have more replies queued on Telegram.
+            if updates.empty?
+              @registry.channels.each do |channel|
+                @relay.poll_complete(channel: channel["name"], started_at: cursor["coverage_from"],
+                  through: started, continuous: continuous)
+              end
+            end
+            return updates.size if unresolved # retain Telegram replay until ordinary handling recovers
+            @journal.synchronize do |state, commit|
+              state["cursor"] = {"offset" => ids.empty? ? cursor["offset"] : ids.last + 1,
+                                  "through" => finished, "generation" => cursor["generation"], "coverage_from" => cursor["coverage_from"]}
+              commit.call
+            end
+            updates.size
+          rescue StandardError
+            at = stamp
+            invalidate_coverage(at)
+            @journal.synchronize do |state, commit|
+              previous = state["cursor"] || cursor || {"offset" => 0, "generation" => 0}
+              state["cursor"] = previous.merge("through" => at, "coverage_from" => at,
+                "generation" => previous.fetch("generation", 0) + 1)
+              commit.call
+            end
+            raise ContractError, "Telegram poll unavailable; ingress coverage is unknown"
+          end
+
+          private
+
+          def invalidate_coverage(at)
+            @registry.channels.each do |channel|
+              @relay.poll_complete(channel: channel["name"], started_at: at, through: at, continuous: false)
+            end
+          end
+
+          def stamp
+            @clock.call.utc.iso8601
+          end
+        end
+      end
+    end
+  end
+end