ace-hitl-hermes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4748399831bb81daa3c725bed83373df44675fa005410f22e88632073abe839a
+  data.tar.gz: 63d3164afdfb14a1ff5072f553bc9a5c5f9e3a092ebb4088ab0822bf8522fddc
+SHA512:
+  metadata.gz: e6781892f412b2c1ba7798f2725a3c454f7c72844de9c81a68224add320e636539863fba1201bdb15d2753f878f5b932738b0fab1e34eaab8fc3e76a9a342cb7
+  data.tar.gz: '07811266c2c80bf1277575bf6e295b522133ea4f06169cdface8d761b4c2ce9216ae65f22b127b8e3b552df58adc57a7e30be995cc5c82091237838a353e21d9'

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `ace-hitl-hermes` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-27
+
+### Added
+- **Folder-as-interface plugin + registry (spec 8wm.t.vs1)**: new package owning the channel registry, notification texts, and message formats for the shared lab <-> hermes folder. Folder contract `ace.hitl.hermes.folder/v1` + message schema `ace.hitl.hermes.message/v1` (JSON Schema asset shipped at `lib/ace/hitl/hermes/schemas/message.v1.schema.json`): a message is a file named `<id>.json`, the address is `<machine>/<folder>/<id>`, the Captain's answer file carries `answer` / `sender` / `received_at`. Fail-closed filename validation, UTF-8 + 64 KiB bounds, id/filename cross-check, ownership/permissions (files 0640, tmp 0600, quarantine 0750; running as root is refused), atomic same-directory tmp+rename writes, quarantine for invalid files with reason sidecars, bounded collision and undeleted-file retry policies, and the write -> validate -> deliver -> ACK deletion state machine. Canonical shared-contract file location/ownership is settled by A4 (8wm.t.vs2); the lab-config consumer side is 8wm.t.vp9 (separate repo).
+
+### Fixed
+- **PR#336 review hardening (codex astra high)**: `publish` validates the exact serialized envelope bytes through the consumer decode gate (UTF-8 + 64 KiB) before any disk write, so an oversized envelope fails at the producer instead of being terminally quarantined by its own poll; `poll` opens message files with `O_NOFOLLOW` and requires a regular file on the descriptor, quarantining top-level symlinks instead of following them (no re-delivery of quarantined content, no importing foreign content through links); the shipped JSON Schema now rejects the envelopes the Ruby exact-field and body-strip checks reject (mutually exclusive kind fields, nonblank bodies).

data/README.md

@@ -0,0 +1,78 @@
+# 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**
+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);
+- **ACK** is the deletion of the file after delivery.
+
+The Captain's answer is a file `<folder>/<id>.json` with the fields
+`answer` / `sender` / `received_at`, written atomically (same-directory
+tmp file + rename) without root.
+
+## Contract
+
+- Folder contract: `ace.hitl.hermes.folder/v1` (spec `8wm.t.vs1`).
+- Message schema: `ace.hitl.hermes.message/v1`; the machine-readable
+  JSON Schema ships at
+  `lib/ace/hitl/hermes/schemas/message.v1.schema.json`.
+- State machine: write -> validate -> deliver -> ACK deletion, with
+  bounded retries (collision at write time, undeleted after delivery)
+  and quarantine as the terminal branch for invalid files.
+- Canonical shared-contract file location/ownership is settled by A4
+  (`8wm.t.vs2`); the lab-config consumer side is `8wm.t.vp9` (separate
+  repository, intentional cross-repo reference).
+
+## Surface
+
+| Piece | Responsibility |
+|---|---|
+| `Hermes::Molecules::HermesChannels::Registry` | channel registry + `<machine>/<folder>/<id>` addressing, fail closed |
+| `Hermes::Molecules::HermesFormats` | decode gate: UTF-8, 64 KiB bound, JSON object, known schema only |
+| `Hermes::Molecules::HermesMessage` | typed envelope, fail-closed validation, canonical JSON |
+| `Hermes::Molecules::HermesAtomicWriter` | same-directory tmp + rename, no root (euid 0 refused) |
+| `Hermes::Molecules::HermesQuarantine` | quarantine moves + reason sidecars |
+| `Hermes::Molecules::HermesRetryPolicy` | collision + undeleted-file retry decisions |
+| `Hermes::Molecules::HermesNotifications` | deterministic single-line notification texts |
+| `Hermes::Organisms::HermesBox` | folder interface per channel: `publish`, `poll`, `ack`, `age`, `identical?` |
+
+## Usage
+
+```ruby
+require "ace/hitl/hermes"
+
+registry = Ace::Hitl::Hermes::Molecules::HermesChannels::Registry.new
+registry.register("inbox", machine: "lab01", folder: "/run/lab/hermes/inbox")
+registry.default = "inbox"
+
+lines = []
+box = Ace::Hitl::Hermes::Organisms::HermesBox.new(
+  channel: "inbox", registry: registry,
+  notifier: ->(line) { lines << line }
+)
+
+# Write the Captain's answer (atomic, no root, collision-safe):
+message = box.publish(
+  kind: :answer, id: "m-123", body: "Ship it.",
+  sender: "captain", timestamp: "2026-09-24T10:00:00Z"
+)
+
+# Consume (fail closed; invalid files are quarantined, never delivered):
+result = box.poll
+result.messages.each do |msg|
+  deliver(msg)             # push to the target
+  box.ack(msg.id)          # deletion IS the ACK
+end
+```
+
+## Development
+
+```sh
+ace-test atoms      # fast unit tests
+ace-test            # the whole package suite
+```

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/lib/ace/hitl/hermes/atoms/hermes_tokens.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Hermes
+      module Atoms
+        # Token validation for every value that becomes part of a file
+        # name or an address (spec 8wm.t.vs1 §2): ids, senders, channel
+        # names, machine names. Path-traversal safe: no separators, no
+        # leading dot, bounded length.
+        module HermesTokens
+          PATTERN = /\A[A-Za-z0-9][A-Za-z0-9._:-]{0,63}\z/
+
+          module_function
+
+          def valid?(value)
+            value.is_a?(String) && value.match?(PATTERN)
+          end
+
+          # Fail closed: raises ContractError naming the label and the rule.
+          def validate!(value, label)
+            token = value.is_a?(String) ? value.strip : value
+            return token if valid?(token)
+
+            raise ContractError,
+              "hermes #{label} must match #{PATTERN.inspect} " \
+              "(1..64 chars; letters, digits, '.', '_', ':', '-'; " \
+              "no leading dot; got #{value.inspect})"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Hermes
+      # Error model for the folder-as-interface plugin (spec 8wm.t.vs1 §9).
+      class Error < StandardError; end
+
+      # The shared folder or a configuration value violates the folder
+      # contract (missing folder, non-directory, world-writable folder,
+      # invalid channel/token values).
+      class ContractError < Error; end
+
+      # The plugin was invoked as root; writing without root is a pinned
+      # contract property and is refused fail closed.
+      class RootUserError < Error; end
+
+      # The target message file already exists; publish retries with a
+      # fresh id (bounded) instead of overwriting.
+      class CollisionError < Error; end
+
+      # The message declares a schema version this plugin does not support
+      # (only ace.hitl.hermes.message/v1); fail closed, quarantine upstream.
+      class UnknownFormatError < Error; end
+
+      # The message envelope violates schema ace.hitl.hermes.message/v1
+      # (bad filename/id pairing, missing or extra fields, bad sender,
+      # bad timestamp, empty body, wrong encoding or size).
+      class InvalidMessageError < Error; end
+
+      # The channel name is not in the registry.
+      class UnknownChannelError < Error; end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_atomic_writer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "fileutils"
+require_relative "hermes_contract"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        # Atomic write protocol (spec 8wm.t.vs1 §5): same-directory tmp
+        # file (0600) + fsync + chmod 0640 + rename(2) onto the target.
+        # Readers never observe partial content; no root privileges are
+        # required or used - running as root is refused fail closed.
+        module HermesAtomicWriter
+          module_function
+
+          # Writes `bytes` to `final_path` atomically. The target must not
+          # exist (CollisionError otherwise); tmp files are removed on
+          # every failure path. Returns the final path.
+          def write(final_path, bytes, euid_provider: -> { Process.euid })
+            if euid_provider.call.zero?
+              raise RootUserError,
+                "hermes writes without root: refusing atomic write as euid 0 " \
+                "(#{final_path})"
+            end
+
+            folder = File.dirname(final_path)
+            HermesContract.verify_folder!(folder)
+            if File.exist?(final_path)
+              raise CollisionError, "hermes message file already exists: #{final_path}"
+            end
+
+            tmp_path = File.join(
+              folder,
+              "#{HermesContract::TMP_PREFIX}#{Process.pid}-#{SecureRandom.hex(8)}.tmp"
+            )
+            begin
+              File.open(tmp_path, File::WRONLY | File::CREAT | File::EXCL,
+                HermesContract::TMP_MODE) do |file|
+                file.write(bytes)
+                file.fsync
+              end
+              File.chmod(HermesContract::FILE_MODE, tmp_path)
+              File.rename(tmp_path, final_path)
+            rescue
+              File.delete(tmp_path) if File.exist?(tmp_path)
+              raise
+            end
+            final_path
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_channels.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/hermes_tokens"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        module HermesChannels
+          # One shared folder between lab and hermes (spec 8wm.t.vs1 §2).
+          # `folder` is the absolute directory path; the message address
+          # is `<machine>/<name>/<id>` where `<name>` is the channel (and
+          # folder basename) token.
+          Channel = Struct.new(:name, :machine, :folder) do
+            def path
+              folder
+            end
+
+            def address(id)
+              "#{machine}/#{name}/#{id}"
+            end
+          end
+
+          # The channel registry the plugin owns (rejestr kanalow).
+          # Token validation happens here, fail closed; folder existence
+          # and writability are re-verified at every folder operation by
+          # the Box (a channel may be registered before its folder
+          # exists).
+          class Registry
+            def initialize
+              @channels = {}
+              @default_name = nil
+            end
+
+            def register(name, machine:, folder:)
+              name = Atoms::HermesTokens.validate!(name, "channel name")
+              machine = Atoms::HermesTokens.validate!(machine, "machine name")
+              unless folder.is_a?(String) && File.absolute_path?(folder)
+                raise ContractError,
+                  "hermes channel #{name} folder must be an absolute directory path " \
+                  "(got #{folder.inspect})"
+              end
+              base = File.basename(folder)
+              unless Atoms::HermesTokens.valid?(base)
+                raise ContractError,
+                  "hermes channel #{name} folder basename must match " \
+                  "#{Atoms::HermesTokens::PATTERN.inspect} (got #{base.inspect})"
+              end
+              if @channels.key?(name)
+                raise ContractError, "hermes channel already registered: #{name}"
+              end
+
+              @channels[name] = Channel.new(name: name, machine: machine, folder: folder)
+              name
+            end
+
+            def resolve(name)
+              channel = @channels[name]
+              unless channel
+                raise UnknownChannelError,
+                  "unknown hermes channel #{name.inspect} (available: #{available.join(", ")})"
+              end
+              channel
+            end
+
+            def default=(name)
+              resolve(name)
+              @default_name = name
+            end
+
+            def default
+              @default_name
+            end
+
+            def resolve_default
+              unless @default_name
+                raise ContractError, "no default hermes channel registered"
+              end
+              resolve(@default_name)
+            end
+
+            def available
+              @channels.keys.sort
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_contract.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/hermes_tokens"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        # Versioned folder contract constants + folder-level rules
+        # (spec 8wm.t.vs1 §§1-5). The plugin implements contract version
+        # ace.hitl.hermes.folder/v1; the canonical shared-contract file is
+        # settled by A4 (8wm.t.vs2), the lab-config consumer side is
+        # 8wm.t.vp9 (separate repository).
+        module HermesContract
+          FOLDER_CONTRACT = "ace.hitl.hermes.folder/v1"
+          MESSAGE_SCHEMA = "ace.hitl.hermes.message/v1"
+
+          # Content bounds: UTF-8 only, at most 64 KiB per message file.
+          MAX_BYTES = 65_536
+
+          # Permissions: message files 0640, tmp files 0600 during the
+          # atomic write, quarantine directory 0750. No root, ever.
+          FILE_MODE = 0o640
+          TMP_MODE = 0o600
+          QUARANTINE_DIR_MODE = 0o750
+
+          MESSAGE_EXT = ".json"
+          TMP_PREFIX = ".hermes-tmp-"
+          QUARANTINE_DIR = ".quarantine"
+          REASON_EXT = ".reason.txt"
+
+          TMP_BASENAME_PREFIX = "." # every tmp file is a dotfile; poll never sees it
+
+          module_function
+
+          # Fail-closed folder verification before EVERY folder operation:
+          # exists, is a directory, writable by the invoking user, and not
+          # world-writable.
+          def verify_folder!(path)
+            unless File.exist?(path)
+              raise ContractError, "hermes folder does not exist: #{path}"
+            end
+            unless File.directory?(path)
+              raise ContractError, "hermes folder is not a directory: #{path}"
+            end
+            unless File.writable?(path)
+              raise ContractError, "hermes folder is not writable by the invoking user: #{path}"
+            end
+            if File.stat(path).mode & 0o002 != 0
+              raise ContractError, "hermes folder must not be world-writable: #{path}"
+            end
+
+            path
+          end
+
+          def file_name(id)
+            "#{Atoms::HermesTokens.validate!(id, "message id")}#{MESSAGE_EXT}"
+          end
+
+          # `<token>.json` -> id token; anything else is not a message file.
+          def parse_file_name(name)
+            return nil unless name.is_a?(String) && name.end_with?(MESSAGE_EXT)
+
+            id = name.delete_suffix(MESSAGE_EXT)
+            Atoms::HermesTokens.valid?(id) ? id : nil
+          end
+
+          def message_path(folder, id)
+            File.join(folder, file_name(id))
+          end
+
+          def quarantine_path(folder)
+            File.join(folder, QUARANTINE_DIR)
+          end
+
+          # Shipped machine-readable contract artifact (JSON Schema
+          # draft-07) for the message envelope v1.
+          def schema_asset_path
+            File.expand_path("../schemas/message.v1.schema.json", __dir__)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_formats.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "hermes_contract"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        # Message format registry (spec 8wm.t.vs1 §9): the decode gate
+        # every message file passes before any other validation. Supports
+        # exactly ace.hitl.hermes.message/v1; unknown versions and every
+        # encoding/size violation fail closed.
+        module HermesFormats
+          SUPPORTED = [HermesContract::MESSAGE_SCHEMA].freeze
+
+          module_function
+
+          def supported
+            SUPPORTED.dup
+          end
+
+          # bytes -> parsed JSON object (Hash). Raises InvalidMessageError
+          # for size/encoding/JSON violations, UnknownFormatError for an
+          # unsupported or absent schema id.
+          def decode!(bytes)
+            unless bytes.bytesize <= HermesContract::MAX_BYTES
+              raise InvalidMessageError,
+                "message exceeds the #{HermesContract::MAX_BYTES}-byte size bound " \
+                "(#{bytes.bytesize} bytes)"
+            end
+
+            content = bytes.dup.force_encoding(Encoding::UTF_8)
+            unless content.valid_encoding?
+              raise InvalidMessageError, "message is not valid UTF-8"
+            end
+
+            hash =
+              begin
+                JSON.parse(content)
+              rescue JSON::ParserError => e
+                raise InvalidMessageError, "message is not valid JSON: #{e.message}"
+              end
+            unless hash.is_a?(Hash)
+              raise InvalidMessageError, "message must be a JSON object"
+            end
+
+            schema = hash["schema"]
+            unless SUPPORTED.include?(schema)
+              raise UnknownFormatError,
+                "unsupported message schema #{schema.inspect} (supported: " \
+                "#{SUPPORTED.join(", ")})"
+            end
+
+            hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_message.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../atoms/hermes_tokens"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        # Typed message envelope for schema ace.hitl.hermes.message/v1
+        # (spec 8wm.t.vs1 §3). One message per file; the payload id MUST
+        # equal the file name stem. Validation is fail closed and names
+        # every violated rule. The Captain's answer file shape is exactly
+        # {schema, id, kind: "answer", answer, sender, received_at}.
+        class HermesMessage
+          TIMESTAMP_PATTERN = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})Z\z/
+          KINDS = %w[question answer].freeze
+
+          EXPECTED_FIELDS = {
+            "question" => %w[schema id kind sender question created_at],
+            "answer" => %w[schema id kind sender answer received_at]
+          }.freeze
+
+          attr_reader :schema, :id, :kind, :sender, :body, :timestamp_field, :timestamp
+
+          def self.question(id:, question:, sender:, created_at:)
+            new(
+              id: id, kind: :question, sender: sender,
+              body_field: "question", body: question,
+              timestamp_field: "created_at", timestamp: created_at
+            )
+          end
+
+          def self.answer(id:, answer:, sender:, received_at:)
+            new(
+              id: id, kind: :answer, sender: sender,
+              body_field: "answer", body: answer,
+              timestamp_field: "received_at", timestamp: received_at
+            )
+          end
+
+          # Fail-closed parse of an already-decoded envelope Hash.
+          # `filename_id` (when given) must equal the payload id.
+          def self.from_hash(hash, filename_id: nil)
+            # Defense-in-depth format gate (the Box always decodes via
+            # HermesFormats first): from_hash is public, so it pins the
+            # schema value itself instead of trusting its caller.
+            unless hash["schema"] == HermesContract::MESSAGE_SCHEMA
+              raise UnknownFormatError,
+                "unsupported message schema #{hash["schema"].inspect} (supported: " \
+                "#{HermesContract::MESSAGE_SCHEMA})"
+            end
+
+            kind_name = hash["kind"]
+            unless KINDS.include?(kind_name)
+              raise InvalidMessageError,
+                "message kind must be one of #{KINDS.join(", ")} (got #{kind_name.inspect})"
+            end
+
+            expected = EXPECTED_FIELDS.fetch(kind_name)
+            missing = expected - hash.keys
+            extra = hash.keys - expected
+            unless missing.empty? && extra.empty?
+              raise InvalidMessageError,
+                "message fields violate schema #{HermesContract::MESSAGE_SCHEMA} " \
+                "(missing: #{missing.empty? ? "none" : missing.join(", ")}; " \
+                "unexpected: #{extra.empty? ? "none" : extra.join(", ")})"
+            end
+
+            id = Atoms::HermesTokens.validate!(hash["id"], "message id")
+            if filename_id && id != filename_id
+              raise InvalidMessageError,
+                "message id #{id.inspect} does not match file name stem #{filename_id.inspect}"
+            end
+
+            sender = Atoms::HermesTokens.validate!(hash["sender"], "sender")
+
+            body_field = (kind_name == "question") ? "question" : "answer"
+            body = hash[body_field]
+            unless body.is_a?(String) && !body.strip.empty?
+              raise InvalidMessageError, "message #{body_field} must be a non-empty string"
+            end
+
+            timestamp_field = (kind_name == "question") ? "created_at" : "received_at"
+            timestamp = validate_timestamp!(hash[timestamp_field], timestamp_field)
+
+            new(
+              id: id, kind: kind_name.to_sym, sender: sender,
+              body_field: body_field, body: body,
+              timestamp_field: timestamp_field, timestamp: timestamp
+            )
+          end
+
+          def self.validate_timestamp!(value, field)
+            match = value.is_a?(String) && TIMESTAMP_PATTERN.match(value)
+            unless match
+              raise InvalidMessageError,
+                "message #{field} must be UTC ISO-8601 YYYY-MM-DDTHH:MM:SSZ " \
+                "(got #{value.inspect})"
+            end
+
+            begin
+              parsed = Time.iso8601(value)
+            rescue ArgumentError
+              raise InvalidMessageError,
+                "message #{field} is not a real calendar timestamp: #{value.inspect}"
+            end
+
+            # Time.iso8601 silently rolls impossible components (Feb 30,
+            # Apr 31, hour 24) over into the next real instant; the
+            # contract requires the literal calendar date/time, so the
+            # parsed value must round-trip to the source components.
+            source = match.captures.map(&:to_i)
+            round_trip = [parsed.year, parsed.month, parsed.day,
+              parsed.hour, parsed.min, parsed.sec]
+            unless round_trip == source
+              raise InvalidMessageError,
+                "message #{field} is not a real calendar timestamp: #{value.inspect}"
+            end
+
+            value
+          end
+
+          def initialize(id:, kind:, sender:, body_field:, body:, timestamp_field:, timestamp:)
+            @schema = HermesContract::MESSAGE_SCHEMA
+            @id = id
+            @kind = kind
+            @sender = sender
+            @body_field = body_field
+            @body = body
+            @timestamp_field = timestamp_field
+            @timestamp = timestamp
+          end
+
+          def question?
+            @kind == :question
+          end
+
+          def answer?
+            @kind == :answer
+          end
+
+          def to_h
+            {
+              "schema" => @schema,
+              "id" => @id,
+              "kind" => @kind.to_s,
+              "sender" => @sender,
+              @body_field => @body,
+              @timestamp_field => @timestamp
+            }
+          end
+
+          # Canonical serialization: fixed key order, compact JSON.
+          def to_json(*)
+            JSON.generate(to_h)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_notifications.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        # Deterministic single-line notification texts (spec 8wm.t.vs1 §9):
+        # no clock, no colors, only provided values. The address is the
+        # message address `<machine>/<folder>/<id>`. Emission is an
+        # injectable sink (default silent in Box).
+        module HermesNotifications
+          EVENTS = %w[
+            question_received
+            answer_written
+            delivered
+            acked
+            quarantined
+            retry_scheduled
+            retry_exhausted
+          ].freeze
+
+          module_function
+
+          # Builds the notification line for an event. Unknown events fail
+          # closed so a typo cannot silently drop notifications.
+          def emit(event, address:, **details)
+            case event.to_s
+            when "question_received"
+              "hermes: question #{address} received"
+            when "answer_written"
+              "hermes: answer #{address} written"
+            when "delivered"
+              "hermes: #{address} delivered"
+            when "acked"
+              "hermes: #{address} acked (file deleted)"
+            when "quarantined"
+              "hermes: #{address} quarantined (#{details[:reason]})"
+            when "retry_scheduled"
+              "hermes: #{address} retry #{details[:attempt]}/#{details[:max_attempts]} " \
+                "(#{details[:policy]})"
+            when "retry_exhausted"
+              "hermes: #{address} retries exhausted (#{details[:reason]})"
+            else
+              raise ContractError,
+                "unknown hermes notification event #{event.inspect} " \
+                "(known: #{EVENTS.join(", ")})"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_quarantine.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "hermes_contract"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        # Quarantine for invalid message files (spec 8wm.t.vs1 §7): the
+        # file is moved atomically into <folder>/.quarantine/ (0750) with
+        # a <name>.reason.txt sidecar (0640). Quarantined content is never
+        # rewritten, re-validated, or delivered. Like every hermes write
+        # path, running as root is refused fail closed.
+        module HermesQuarantine
+          module_function
+
+          # Moves `path` (inside `folder`) into the quarantine directory
+          # and writes the reason sidecar. Returns the quarantined path.
+          def move(folder, path, reason:, now: -> { Time.now },
+            euid_provider: -> { Process.euid })
+            if euid_provider.call.zero?
+              raise RootUserError,
+                "hermes writes without root: refusing quarantine move as euid 0 " \
+                "(#{path})"
+            end
+
+            quarantine_dir = HermesContract.quarantine_path(folder)
+            unless File.directory?(quarantine_dir)
+              Dir.mkdir(quarantine_dir, HermesContract::QUARANTINE_DIR_MODE)
+              # Modes are FORCED, not inherited from the umask (mirrors
+              # HermesAtomicWriter): the pinned 0750 dir contract holds
+              # under any umask.
+              File.chmod(HermesContract::QUARANTINE_DIR_MODE, quarantine_dir)
+            end
+
+            base = File.basename(path)
+            dest = File.join(quarantine_dir, base)
+            suffix = 0
+            while File.exist?(dest)
+              suffix += 1
+              dest = File.join(quarantine_dir, "#{base}.#{suffix}")
+            end
+
+            sidecar_path = "#{dest}#{HermesContract::REASON_EXT}"
+            File.rename(path, dest)
+            File.open(sidecar_path,
+              File::WRONLY | File::CREAT | File::EXCL,
+              HermesContract::FILE_MODE) do |sidecar|
+              sidecar.write("#{now.call.utc.strftime("%Y-%m-%dT%H:%M:%SZ")} #{reason}\n")
+            end
+            # The open-mode is umask-sensitive; force the pinned 0640.
+            File.chmod(HermesContract::FILE_MODE, sidecar_path)
+            dest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/molecules/hermes_retry_policy.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Hermes
+      module Molecules
+        # Pure retry decisions (spec 8wm.t.vs1 §8). The clock-and-loop
+        # belongs to the transport role (y24 / A4); this module pins the
+        # policy so both sides decide identically.
+        #
+        # - collision retries (write time): bounded fresh-id attempts;
+        # - undeleted-file retries (post-delivery): a delivered file that
+        #   is not ACKed after the stale deadline is redelivered as
+        #   IDENTICAL bytes, bounded, then quarantined (terminal).
+        module HermesRetryPolicy
+          DEFAULT_MAX_ATTEMPTS = 3
+          DEFAULT_BASE_DELAY = 1.0
+          DEFAULT_MAX_DELAY = 60.0
+
+          class << self
+            def collision_retry?(failed_attempts, max_attempts: DEFAULT_MAX_ATTEMPTS)
+              failed_attempts < max_attempts
+            end
+
+            # Exponential backoff for the given 1-based attempt number.
+            def delay_for(attempt, base_delay: DEFAULT_BASE_DELAY, max_delay: DEFAULT_MAX_DELAY)
+              [base_delay * (2**(attempt - 1)), max_delay].min
+            end
+
+            # Decision for a delivered-but-not-acked file.
+            # `attempts` = deliveries already performed (>= 1).
+            def undeleted_decision(age_seconds:, stale_after:, attempts:, max_attempts: DEFAULT_MAX_ATTEMPTS)
+              return :wait if age_seconds < stale_after
+              return :redeliver if attempts < max_attempts
+
+              :quarantine
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require_relative "../molecules/hermes_contract"
+require_relative "../molecules/hermes_formats"
+require_relative "../molecules/hermes_message"
+require_relative "../molecules/hermes_atomic_writer"
+require_relative "../molecules/hermes_quarantine"
+require_relative "../molecules/hermes_retry_policy"
+require_relative "../molecules/hermes_notifications"
+require_relative "../molecules/hermes_channels"
+
+module Ace
+  module Hitl
+    module Hermes
+      module Organisms
+        # The folder interface per channel (spec 8wm.t.vs1 §9): publish
+        # (atomic write + collision retry), poll (validate + quarantine),
+        # ack (deletion IS the ACK), age (retry clock), identical?
+        # (redelivery identity). The Box is role-agnostic: the hermes
+        # side polls for questions, the lab side (labd) polls for answers.
+        class HermesBox
+          QuarantinedFile = Struct.new(:path, :reason)
+          PollResult = Struct.new(:messages, :quarantined)
+
+          attr_reader :channel
+
+          def initialize(channel:, registry: nil, id_generator: -> { SecureRandom.hex(6) },
+            notifier: nil, euid_provider: -> { Process.euid })
+            @channel =
+              if channel.is_a?(Molecules::HermesChannels::Channel)
+                channel
+              elsif registry
+                registry.resolve(channel)
+              else
+                raise ContractError,
+                  "hermes box needs a Channel or a registry to resolve the channel name"
+              end
+            @id_generator = id_generator
+            @notifier = notifier || ->(_line) {}
+            @euid_provider = euid_provider
+          end
+
+          def address(id)
+            @channel.address(id)
+          end
+
+          # Atomic write of a validated message. A GENERATED id is
+          # regenerated (bounded, notified) on a filename collision; an
+          # EXPLICITLY supplied id never gets regenerated - it asserts
+          # correlation (e.g. the answer of question `q-1` is `q-1.json`),
+          # 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)
+            explicit_id = !id.nil?
+            attempts = 0
+            loop do
+              message = build_message(
+                kind: kind, id: id || @id_generator.call,
+                sender: sender, timestamp: timestamp, body: body
+              )
+              # Producer fail-closed gate: the exact BYTES about to be
+              # written must survive the consumers' decode gate (UTF-8 +
+              # 64 KiB cap + schema id), and the decoded envelope must
+              # satisfy the exact message contract, BEFORE any disk
+              # write - so an envelope its own poll would terminally
+              # quarantine can never be published (review 8wq2zttx on
+              # PR#336).
+              envelope = message.to_json
+              Molecules::HermesFormats.decode!(envelope)
+              Molecules::HermesMessage.from_hash(
+                JSON.parse(envelope), filename_id: message.id
+              )
+              begin
+                Molecules::HermesAtomicWriter.write(
+                  Molecules::HermesContract.message_path(@channel.folder, message.id),
+                  envelope,
+                  euid_provider: @euid_provider
+                )
+              rescue CollisionError
+                raise if explicit_id
+
+                attempts += 1
+                unless Molecules::HermesRetryPolicy.collision_retry?(attempts)
+                  raise
+                end
+
+                notify(:retry_scheduled, address(message.id), attempt: attempts,
+                  max_attempts: Molecules::HermesRetryPolicy::DEFAULT_MAX_ATTEMPTS,
+                  policy: "collision")
+                id = nil # force a fresh id on the next iteration
+                next
+              end
+
+              notify(:answer_written, address(message.id)) if message.answer?
+              return message
+            end
+          end
+
+          # Validate + collect everything currently in the folder.
+          # Valid files become Messages; files failing the fail-closed
+          # gate are quarantined (never delivered). Foreign names
+          # (dotfiles, tmp leftovers, non-`<token>.json`) are ignored.
+          def poll
+            Molecules::HermesContract.verify_folder!(@channel.folder)
+            messages = []
+            quarantined = []
+
+            Dir.children(@channel.folder).sort.each do |name|
+              id = Molecules::HermesContract.parse_file_name(name)
+              next if id.nil? # dotfiles, tmp leftovers, foreign names
+
+              path = File.join(@channel.folder, name)
+              # Opened with O_NOFOLLOW and verified regular on the open
+              # descriptor: a top-level symlink must never be followed -
+              # it could import content from outside the channel or
+              # reverse a quarantine's terminal state (review 8wq2ztu3
+              # on PR#336).
+              begin
+                file = File.open(path, File::RDONLY | File::NOFOLLOW)
+              rescue Errno::ENOENT
+                next # concurrently acked between listing and reading
+              rescue Errno::ELOOP
+                quarantined << quarantine(path, id, "message file is a symlink")
+                next
+              end
+
+              begin
+                begin
+                  regular = file.stat.file?
+                rescue Errno::ENOENT
+                  next # concurrently acked after the open
+                end
+                unless regular
+                  quarantined << quarantine(path, id, "message file is not a regular file")
+                  next
+                end
+
+                bytes = file.read(Molecules::HermesContract::MAX_BYTES + 1) || ""
+                hash = Molecules::HermesFormats.decode!(bytes)
+                message = Molecules::HermesMessage.from_hash(hash, filename_id: id)
+              rescue Error => e
+                quarantined << quarantine(path, id, e.message)
+                next
+              ensure
+                file.close
+              end
+
+              notify(:question_received, address(message.id)) if message.question?
+              messages << message
+            end
+
+            PollResult.new(messages: messages, quarantined: quarantined)
+          end
+
+          # Deletion is the ACK; idempotent (an absent file reports
+          # :already_acked, never an error). The delete is a folder write,
+          # so the no-root gate applies exactly like on publish.
+          def ack(id)
+            if @euid_provider.call.zero?
+              raise RootUserError,
+                "hermes writes without root: refusing ack deletion as euid 0 " \
+                "(#{Molecules::HermesContract.message_path(@channel.folder, id)})"
+            end
+            Molecules::HermesContract.verify_folder!(@channel.folder)
+            path = Molecules::HermesContract.message_path(@channel.folder, id)
+            if File.exist?(path)
+              File.delete(path)
+              notify(:acked, address(id))
+              :acked
+            else
+              :already_acked
+            end
+          end
+
+          # Seconds since the message file was written (mtime); nil when
+          # the file is gone (already acked). The undeleted-file retry
+          # clock (spec §8).
+          def age(id)
+            path = Molecules::HermesContract.message_path(@channel.folder, id)
+            File.exist?(path) ? Time.now - File.mtime(path) : nil
+          end
+
+          # True when the file for `id` currently holds exactly `bytes` -
+          # the identity check every redelivery must pass (retries never
+          # duplicate answers).
+          def identical?(id, bytes)
+            path = Molecules::HermesContract.message_path(@channel.folder, id)
+            File.exist?(path) && read_capped(path) == bytes
+          rescue Errno::ENOENT
+            false
+          end
+
+          private
+
+          def build_message(kind:, id:, sender:, timestamp:, body:)
+            case kind.to_s
+            when "question"
+              Molecules::HermesMessage.question(
+                id: id, question: body, sender: sender, created_at: timestamp
+              )
+            when "answer"
+              Molecules::HermesMessage.answer(
+                id: id, answer: body, sender: sender, received_at: timestamp
+              )
+            else
+              raise ContractError,
+                "hermes message kind must be question or answer (got #{kind.inspect})"
+            end
+          end
+
+          # Read at most MAX_BYTES + 1 bytes so an oversized file fails
+          # the size gate without reading the whole file. An empty file
+          # reads as "" (File.read with an explicit length returns nil at
+          # EOF) so the empty payload still fails the formats gate and is
+          # quarantined instead of crashing the poll loop.
+          def read_capped(path)
+            File.read(path, Molecules::HermesContract::MAX_BYTES + 1) || ""
+          end
+
+          def quarantine(path, id, reason)
+            quarantined = Molecules::HermesQuarantine.move(
+              @channel.folder, path, reason: reason,
+              euid_provider: @euid_provider
+            )
+            notify(:quarantined, address(id), reason: reason)
+            QuarantinedFile.new(path: quarantined, reason: reason)
+          end
+
+          def notify(event, address, **details)
+            @notifier.call(
+              Molecules::HermesNotifications.emit(event, address: address, **details)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/hermes/schemas/message.v1.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ace.hitl.hermes.message/v1",
+  "title": "ace-hitl-hermes message envelope v1",
+  "description": "One JSON object per file in the shared lab <-> hermes folder (folder contract ace.hitl.hermes.folder/v1, spec 8wm.t.vs1). File name must be <id>.json with id equal to the payload id.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "id", "kind", "sender"],
+  "properties": {
+    "schema": {
+      "const": "ace.hitl.hermes.message/v1"
+    },
+    "id": {
+      "$ref": "#/definitions/token"
+    },
+    "sender": {
+      "$ref": "#/definitions/token"
+    },
+    "kind": {
+      "enum": ["question", "answer"]
+    },
+    "question": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S",
+      "description": "Required for kind=question; non-empty after strip."
+    },
+    "answer": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S",
+      "description": "Required for kind=answer (the Captain's answer); non-empty after strip."
+    },
+    "created_at": {
+      "$ref": "#/definitions/timestamp",
+      "description": "Required for kind=question."
+    },
+    "received_at": {
+      "$ref": "#/definitions/timestamp",
+      "description": "Required for kind=answer."
+    }
+  },
+  "definitions": {
+    "token": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$"
+    },
+    "timestamp": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "format": "date-time"
+    }
+  },
+  "oneOf": [
+    {
+      "properties": {
+        "kind": {
+          "const": "question"
+        }
+      },
+      "required": ["question", "created_at"],
+      "not": {
+        "anyOf": [
+          { "required": ["answer"] },
+          { "required": ["received_at"] }
+        ]
+      }
+    },
+    {
+      "properties": {
+        "kind": {
+          "const": "answer"
+        }
+      },
+      "required": ["answer", "received_at"],
+      "not": {
+        "anyOf": [
+          { "required": ["question"] },
+          { "required": ["created_at"] }
+        ]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    # Folder-as-interface HITL transport plugin (spec 8wm.t.vs1).
+    module Hermes
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/ace/hitl/hermes.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "hermes/version"
+require_relative "hermes/errors"
+require_relative "hermes/atoms/hermes_tokens"
+require_relative "hermes/molecules/hermes_contract"
+require_relative "hermes/molecules/hermes_formats"
+require_relative "hermes/molecules/hermes_message"
+require_relative "hermes/molecules/hermes_atomic_writer"
+require_relative "hermes/molecules/hermes_quarantine"
+require_relative "hermes/molecules/hermes_retry_policy"
+require_relative "hermes/molecules/hermes_notifications"
+require_relative "hermes/molecules/hermes_channels"
+require_relative "hermes/organisms/hermes_box"
+
+module Ace
+  module Hitl
+    # Folder-as-interface HITL transport plugin (spec 8wm.t.vs1): the
+    # shared folder between lab and hermes IS the transport. A message is
+    # a file, the address is <machine>/<folder>/<id>, delivery is push,
+    # and ACK is the deletion of the file after delivery. The plugin owns
+    # the channel registry, the notification texts, and the message
+    # formats (ace.hitl.hermes.message/v1).
+    module Hermes
+    end
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: ace-hitl-hermes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 2026-09-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-test-helpers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.19'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'ace-hitl-hermes treats the shared lab <-> hermes folder as the HITL
+  transport: a message is a file, the address is <machine>/<folder>/<id>, delivery
+  is push, and ACK is deletion. The plugin owns the channel registry, notification
+  texts, and the versioned message formats (ace.hitl.hermes.message/v1), with atomic
+  same-directory tmp+rename writes, fail-closed validation, quarantine, and bounded
+  retries.'
+email:
+- mc@cs3b.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/ace/hitl/hermes.rb
+- lib/ace/hitl/hermes/atoms/hermes_tokens.rb
+- lib/ace/hitl/hermes/errors.rb
+- lib/ace/hitl/hermes/molecules/hermes_atomic_writer.rb
+- lib/ace/hitl/hermes/molecules/hermes_channels.rb
+- lib/ace/hitl/hermes/molecules/hermes_contract.rb
+- lib/ace/hitl/hermes/molecules/hermes_formats.rb
+- lib/ace/hitl/hermes/molecules/hermes_message.rb
+- lib/ace/hitl/hermes/molecules/hermes_notifications.rb
+- lib/ace/hitl/hermes/molecules/hermes_quarantine.rb
+- lib/ace/hitl/hermes/molecules/hermes_retry_policy.rb
+- lib/ace/hitl/hermes/organisms/hermes_box.rb
+- lib/ace/hitl/hermes/schemas/message.v1.schema.json
+- lib/ace/hitl/hermes/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-hitl-hermes/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-hitl-hermes/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Folder-as-interface HITL transport plugin for the hermes relay
+test_files: []