ace-assign 0.60.0 → 0.61.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a8f387dd91c6da87ca5eb3712cb5fb71051a0326dfa13cf0d9d91e054c1cc00
-  data.tar.gz: 4698ad04a950a1401caec3387ef085e8c66512a07e9dd5af168446d80e7d89eb
+  metadata.gz: 494e61c0842f8930425d12aeee6c0b51b46ce491e829c19401df1296e440ca09
+  data.tar.gz: 614e997a57ea09e7ff83d30ad372514dc0c0abceac7a809cdcb4aea1b630005a
 SHA512:
-  metadata.gz: 89c8df3b2e0823c195dfc3d3b59fbcc58e79c97b3978e0db2e4395c83e86307e8d450a637e633b9aa947efeb79ff94ba78307bc24de577effb8cb55b53e9b8f5
-  data.tar.gz: dd2e0a73591ea2e646c9c8164cb56269ff6353860005acdfb57bc268ca8e2d5c89b77b3a19af8a1b895dcfa8716199ae0272a1705387dc4c5f5bda424c062668
+  metadata.gz: a83405e18f47bdf33cf83619a88b790ad6ed27ff933f8816530931a2eb571c744f8eeca5c25aded6c0c2dacdda5429aec87372aadae63b0393a17a2797d149ea
+  data.tar.gz: c6dba5cc8f2925af84265864bbf4b54e3102f27d0707ee936d0440ec3df28e3acbf67cc7040a103c808461d33cfd77c8dd43f5092bbec6ce0fa362b1920cfc52

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.61.0] - 2026-10-02
+
+### Added
+
+- Journal-backed service request claims, terminal receipts, and uncertainty
+  tracking. Assignment evidence now exposes unresolved service effects and
+  the latest evidence ref commit without changing the candidate head.
+
+### Fixed
+
+- Validate terminal service receipts against the exact claimed request and
+  executor evidence before accepting them in the assignment journal.
+
+### Technical
+
+- Updated the ace-tmux dependency to the 0.18 adapter release line.
+
 ## [0.60.0] - 2026-10-01
 
 ### Fixed

data/docs/usage.md

@@ -124,6 +124,16 @@ ace-assign attempt evidence --attempt ATTEMPT --receipt-digest SHA256 --format j
 
 A check proof requires the live candidate head, intact accepted artifacts, and the matching executed operation: `tests` uses `test`, other explicit check names use that operation name. Review collection requires an accepted `review-collect` operation with a passed `review-execution` outcome and the retained metadata/report/prompt artifacts. Review approval requires an ordinary accepted `review` operation with the approved independent reviewer verdict, exact head and retained report artifacts; collection proof cannot substitute for approval. Both collection and approval support an exact `--historical-head`. Historical review validation exposes `historical: true` and the recorded head; it preserves accepted source authority across head drift and cannot certify live checks. Unknown receipts, changed artifacts, unaccepted/unmanaged history, wrong purposes and stale current queries fail closed. Retain the configured evidence ref alongside durable review campaigns.
 
+### Service effect claims
+
+External service operations (driven through `ace-lab service request`) claim their effect on the assignment journal before dispatch, so a retried or crashed request can never duplicate a side effect. The coordinator owns the trusted surface; callers never append journal events directly.
+
+- `Ace::Assign::Organisms::AttemptCoordinator#claim_service_request(binding)` records the claim and its attempt event atomically under a journal-wide request-ID index: the same request ID cannot be claimed twice, by another assignment, or against a stale candidate head. External-effect operations additionally require accepted review evidence at the current head, like `merge`.
+- `#service_request_status(request_id)` reads the authoritative claim state, including after local cache loss.
+- `#transition_service_request(request_id, state:, receipt:)` moves a claim to `succeeded` or `failed` only with a bound, non-secret receipt (exact request/attempt/project/operation/input digest/target fields, non-negative executor UID, and SHA-256 evidence references); rejected receipts never become approvals.
+- `#reject_service_request(binding, reason:)` durably records an auditable rejection without inventing a valid attempt.
+- Journal commits advance `journal_commit` only; they never change or authorize `candidate_head`, and `base_head` stays fixed at attempt start.
+
 ### Evidence storage and recovery modes
 
 - Task-attached (managed) attempts journal accepted evidence to the configured evidence Git ref (default `refs/ace/execution`) through an isolated, disposable audit checkout, outside the deliverable candidate branch. Journal commits never advance or exempt the reviewed candidate.
@@ -176,11 +186,14 @@ HITL stall behavior:
 - Canonical contract lives in `wfi://hitl` (`ace-hitl` package workflow).
 - If a step is failed with canonical message format `HITL: <id> <path>`, `ace-assign status` prints operator guidance with the matching `ace-hitl show <id>` command and available path hint.
 - Recommended resume flow:
+
   - `ace-hitl show <id>`
   - requester path (default): `ace-hitl wait <id>`
   - fallback path (when waiter inactive): `ace-hitl update <id> --answer "<decision>" --resume`
   - `ace-assign retry <failed-step> --assignment <assignment-id>`
+
 - Completion-attention flow:
+
   - When assignment work is complete but explicit user action is needed, create an approval HITL event (`kind=approval`) and include the resume instruction for `/as-assign-drive <assignment-id>`.
 
 ### `ace-assign step [STEP]`
@@ -284,6 +297,7 @@ Launch modes:
 - `headless`: force the existing provider subprocess path and never create tmux panes
 - `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically. The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`. Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
 - `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically
+
   - This mode consumes the shared `ace-tmux` runtime/control surface for tmux targeting, pane dispatch, and diagnostics.
   - The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`.
   - Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
@@ -355,6 +369,7 @@ When using preset-backed assignment creation (`ace-assign create --task ...`, `/
 - Terminal refs (`done`, `skipped`, `cancelled`) are skipped before queue expansion.
 - Mixed sets continue with remaining non-terminal refs and report skipped terminal refs.
 - If all requested refs are terminal, assignment creation stops with:
+
   - `All requested tasks are already terminal (done/skipped/cancelled): <refs>`
   - `No assignment created.`
 

data/lib/ace/assign/models/evidence_event.rb

@@ -17,6 +17,7 @@ module Ace
         TYPES = %w[
           intent process_start receipt_accepted transition
           candidate_invalidated reconciliation
+          service_claim service_transition
         ].freeze
 
         # Build an event chained to a previous digest.

data/lib/ace/assign/molecules/evidence_calculator.rb

@@ -39,6 +39,24 @@ module Ace
           review_receipt = receipt_currency(receipts, "review", head)
           release_receipt = receipt_currency(receipts, "release", head)
           unresolved_effects = collect_unresolved_effects(attempts)
+          if assignment&.managed?
+            requests = journal.service_requests(assignment.id)
+            # A rejected effect stays unresolved when its claim had been
+            # dispatched (authorization consumed): only attributable evidence
+            # that no effect occurred settles it, never the bare rejection.
+            unresolved_effects.concat(requests
+              .select { |request| unresolved_service_state?(request) }
+              .map { |request| "#{request["request_id"]}:#{request["operation"]}:#{request["state"]}" })
+            # Settled requests keep their authorization only while their
+            # receipt evidence remains intact in the candidate repository:
+            # a deleted or modified artifact drops the outcome back to
+            # unresolved instead of trusting an unverifiable receipt.
+            unresolved_effects.concat(requests
+              .select { |request| request["state"] == "succeeded" || request["state"] == "failed-settled" }
+              .reject { |request| evidence_intact?(request) }
+              .map { |request| "#{request["request_id"]}:#{request["operation"]}:evidence-unavailable" })
+            unresolved_effects.uniq!
+          end
           feedback_state = derive_feedback_state(attempts, receipts, head, unresolved_effects)
 
           # Authorization requires managed evidence, settled work (no active
@@ -67,7 +85,7 @@ module Ace
             base_head: latest&.binding&.base_head,
             candidate_head: latest&.candidate_head,
             evidence_git_ref: evidence_git_ref(assignment),
-            journal_commit: latest&.journal_commit,
+            journal_commit: assignment&.managed? ? journal.ref_value : latest&.journal_commit,
             unresolved_effects: unresolved_effects
           }
           evidence[:decision_digest] = Digest::SHA256.hexdigest(
@@ -78,6 +96,38 @@ module Ace
 
         private
 
+        # Accepted, uncertain, and failed effects are unresolved by
+        # definition; a rejected effect stays unresolved when its claim was
+        # dispatched (authorization consumed), because the effect may have
+        # happened.
+        def unresolved_service_state?(request)
+          %w[accepted uncertain failed].include?(request["state"]) ||
+            (request["state"] == "rejected" && request["consumed"] != false)
+        end
+
+        # Every receipt evidence artifact must still exist in the candidate
+        # repository with its recorded digest; evidence lives in the working
+        # tree, so its integrity is re-checked on every calculation.
+        def evidence_intact?(request)
+          receipt = request["receipt"]
+          return false unless receipt.is_a?(Hash)
+          repo_root = File.realpath(@repo_root)
+          Array(receipt["evidence"]).all? do |item|
+            path = File.expand_path(item["ref"].to_s, repo_root)
+            real = begin
+              File.realpath(path)
+            rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+              next false
+            end
+            begin
+              real.start_with?(repo_root + File::SEPARATOR) &&
+                Digest::SHA256.file(real).hexdigest == item["sha256"]
+            rescue Errno::EACCES, Errno::ELOOP
+              false
+            end
+          end
+        end
+
         def git_facts
           head, _s = Open3.capture2("git", "rev-parse", "HEAD", chdir: @repo_root, stdin_data: "")
           tree, _s = Open3.capture2("git", "rev-parse", "HEAD^{tree}", chdir: @repo_root, stdin_data: "")

data/lib/ace/assign/molecules/evidence_journal.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+require "digest"
 require "fileutils"
 require "json"
 require "open3"
@@ -121,6 +123,215 @@ module Ace
             .compact
         end
 
+        # Reserve a globally unique service request in the same evidence ref
+        # as its owning attempt. The request index and attempt event are one
+        # Git commit, so a ref race cannot admit two effects for one ID. An
+        # exact authorization reference is consumed by its first live claim:
+        # a second request presenting the same operation/project/target
+        # authorization is rejected instead of dispatching a duplicate effect.
+        # Dispatching callers claim directly as +uncertain+ so no commit
+        # window exists where a stranded claim reads as accepted.
+        def claim_service_request(binding, state: "accepted", guard: nil)
+          guard ||= -> { authorization_conflict(binding) }
+          update_service_request(binding.fetch("request_id"), expected: nil,
+            replacement: binding.merge("state" => state, "claimed_at" => Time.now.utc.iso8601(9)),
+            event_type: "service_claim", guard: guard)
+        end
+
+        # Reject a service request. A request not yet on file gets its
+        # auditable rejection claim (which never consumed the authorization);
+        # an existing live claim transitions to rejected but stays consuming:
+        # only attributable evidence that the effect did not occur may free a
+        # dispatched authorization, never a bare rejection.
+        def reject_service_request(binding, reason:)
+          request_id = binding.fetch("request_id")
+          existing = service_request(request_id)
+          if existing
+            unless existing.except("state", "receipt", "reason", "claimed_at", "failed_at") == binding.except("state", "receipt", "reason", "claimed_at", "failed_at")
+              raise AttemptErrors::Conflict, "Service request #{request_id} has different input"
+            end
+            return existing if existing["state"] == "rejected"
+            return update_service_request(request_id, expected: existing,
+              replacement: existing.merge("state" => "rejected", "reason" => reason),
+              event_type: "service_transition")
+          end
+          update_service_request(request_id, expected: nil,
+            replacement: binding.merge("state" => "rejected", "reason" => reason, "consumed" => false),
+            event_type: "service_claim")
+        end
+
+        # Terminal writes are validated HERE at the journal boundary —
+        # receipt schema, binding against the current record, and attested
+        # outcome — so no caller-supplied flag decides trust. The
+        # coordinator additionally performs content-level attestation and
+        # file verification.
+        def transition_service_request(request_id, state:, receipt: nil, validated: false)
+          unless %w[succeeded failed uncertain rejected failed-settled].include?(state)
+            raise ArgumentError, "invalid service request state"
+          end
+          current = service_request(request_id)
+          raise AttemptErrors::NotFound, "Service request #{request_id} not found" unless current
+          # Terminal states are immutable; failed-settled is reached only
+          # from a dispatched (failed, uncertain, or consumed-rejected)
+          # effect with a validated no-effect receipt.
+          consumed_rejected = current["state"] == "rejected" && current["consumed"] != false
+          if %w[succeeded failed-settled].include?(current["state"]) ||
+              (current["state"] == "rejected" && !consumed_rejected) ||
+              (consumed_rejected && state != "failed-settled")
+            raise AttemptErrors::InvalidState, "Service request #{request_id} is terminal"
+          end
+          validate_terminal_receipt!(current, state, receipt) if terminal_state?(state)
+          stamped = current.merge("state" => state, "receipt" => receipt)
+          stamped["failed_at"] = Time.now.utc.iso8601(9) if state == "failed"
+          update_service_request(request_id, expected: current,
+            replacement: stamped,
+            event_type: "service_transition")
+        end
+
+        TERMINAL_RECEIPT_FIELDS = %w[assignment_id attempt_id candidate_head evidence executor_uid
+          input_digest operation outcome project_id request_id target transport].freeze
+        TERMINAL_BINDING_FIELDS = %w[request_id assignment_id attempt_id project_id operation
+          input_digest target candidate_head executor_uid transport].freeze
+
+        def terminal_state?(state)
+          %w[succeeded failed failed-settled].include?(state)
+        end
+
+        def validate_terminal_receipt!(current, state, receipt)
+          unless receipt.is_a?(Hash) && receipt.keys.sort == TERMINAL_RECEIPT_FIELDS.sort
+            raise AttemptErrors::ReceiptRejected,
+              "Service terminal receipt has invalid fields"
+          end
+          TERMINAL_BINDING_FIELDS.each do |key|
+            unless receipt[key] == current[key]
+              raise AttemptErrors::ReceiptRejected, "Service terminal receipt does not match #{key}"
+            end
+          end
+          expected_outcome = (state == "failed-settled") ? "failed" : state
+          evidence_items = receipt["evidence"]
+          valid_evidence = evidence_items.is_a?(Array) && !evidence_items.empty? &&
+            evidence_items.all? do |item|
+              item.is_a?(Hash) && item.keys.sort == %w[ref sha256] &&
+                item["ref"].is_a?(String) && item["ref"].match?(/\A[a-zA-Z0-9_.:\/-]{1,256}\z/) &&
+                item["sha256"].is_a?(String) && item["sha256"].match?(/\A[0-9a-f]{64}\z/)
+            end
+          executor_valid = receipt["executor_uid"].is_a?(Integer) && receipt["executor_uid"] >= 0
+          unless receipt["outcome"] == expected_outcome && executor_valid && valid_evidence
+            raise AttemptErrors::ReceiptRejected, "Service terminal receipt has invalid executor or evidence"
+          end
+          if state == "failed-settled" &&
+              !receipt["evidence"].any? { |item| item["ref"].end_with?("no-effect") }
+            raise AttemptErrors::ReceiptRejected,
+              "Service settlement requires a no-effect attestation artifact"
+          end
+          repo_root = File.realpath(@repo_root)
+          receipt["evidence"].each do |item|
+            path = File.expand_path(item["ref"], repo_root)
+            real = begin
+              File.realpath(path)
+            rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+              raise AttemptErrors::ReceiptRejected,
+                "Service terminal receipt evidence is unverifiable: #{item["ref"]}"
+            end
+            intact = begin
+              real.start_with?(repo_root + File::SEPARATOR) &&
+                Digest::SHA256.file(real).hexdigest == item["sha256"]
+            rescue Errno::EACCES, Errno::ELOOP
+              false
+            end
+            raise AttemptErrors::ReceiptRejected,
+              "Service terminal receipt evidence is unverifiable: #{item["ref"]}" unless intact
+            attestation = /^ace-service-attestation request:#{Regexp.escape(current["request_id"])} \
+input:#{Regexp.escape(current["input_digest"])} outcome:(\S+)( no-effect:(\S+))?$/
+            attested = File.read(real).scan(attestation).first
+            attested_outcome = state == "failed-settled" ? "failed" : state
+            unless attested && attested.first == attested_outcome &&
+                (state == "failed-settled" ? attested[2] == "true" : true)
+              raise AttemptErrors::ReceiptRejected,
+                "Service terminal receipt evidence does not attest #{attested_outcome}: #{item["ref"]}"
+            end
+          end
+        end
+
+        def service_request(request_id)
+          validate_request_id!(request_id)
+          value = ref_value
+          return nil unless value
+          out, stderr, status = git("show", "#{value}:#{service_request_path(request_id)}")
+          return JSON.parse(out) if status.success?
+          return nil if stderr.include?("does not exist") || stderr.include?("exists on disk")
+          raise AttemptErrors::EvidenceUnavailable, "Cannot read service request: #{stderr}"
+        rescue JSON::ParserError
+          raise AttemptErrors::EvidenceUnavailable, "Corrupt service request #{request_id}"
+        end
+
+        # Every service request recorded in this evidence ref, whatever the
+        # owning assignment. Backs the journal-wide request-ID and
+        # authorization-consumption checks.
+        # Another live request holding the same exact authorization for the
+        # same operation, project and target. Only requests that were born
+        # rejected (never claimed, never dispatched) leave the decision
+        # unconsumed: a withdrawn or failed claim keeps it consumed until
+        # attributable evidence proves the effect did not occur.
+        def authorization_conflict(binding)
+          authorization = binding["authorization"]
+          return nil unless authorization.is_a?(String) && !authorization.empty?
+          service_request_records.find do |other|
+            next false if other["request_id"] == binding.fetch("request_id")
+            next false if other["state"] == "rejected" && other["consumed"] == false
+            # A settled failure frees the exact authorization only while its
+            # no-effect evidence remains verifiable in the repository.
+            next false if other["state"] == "failed-settled" && settlement_evidence_intact?(other)
+            other["authorization"] == authorization &&
+              other["operation"] == binding.fetch("operation") &&
+              other["project_id"] == binding.fetch("project_id") &&
+              other["target"] == binding.fetch("target")
+          end
+        end
+
+        def settlement_evidence_intact?(record)
+          receipt = record["receipt"]
+          return false unless receipt.is_a?(Hash)
+          repo_root = File.realpath(@repo_root)
+          Array(receipt["evidence"]).all? do |item|
+            path = File.expand_path(item["ref"].to_s, repo_root)
+            real = begin
+              File.realpath(path)
+            rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+              next false
+            end
+            begin
+              real.start_with?(repo_root + File::SEPARATOR) &&
+                Digest::SHA256.file(real).hexdigest == item["sha256"]
+            rescue Errno::EACCES, Errno::ELOOP
+              false
+            end
+          end
+        end
+
+        def service_request_records
+          value = ref_value
+          return [] unless value
+          paths, stderr, status = git("ls-tree", "-r", "--name-only", value, "--", "execution/requests/")
+          raise AttemptErrors::EvidenceUnavailable, "Cannot read service request index: #{stderr}" unless status.success?
+          paths.lines.map(&:strip).select { |path| path.end_with?(".json") }.filter_map do |path|
+            content, error, read_status = git("show", "#{value}:#{path}")
+            unless read_status.success?
+              raise AttemptErrors::EvidenceUnavailable, "Cannot read service request #{path}: #{error}"
+            end
+            JSON.parse(content)
+          end
+        rescue JSON::ParserError
+          raise AttemptErrors::EvidenceUnavailable, "Corrupt service request index"
+        end
+
+        def service_requests(assignment_id)
+          request_ids = read_events(assignment_id)
+            .select { |event| event["type"] == "service_claim" }
+            .map { |event| event.dig("payload", "request_id") }.compact.uniq
+          request_ids.filter_map { |request_id| service_request(request_id) }
+        end
+
         # All attempts derivable from the journal, reconstructed from intent
         # and process_start facts with journal-authoritative state. The
         # journal is the owner of attempt-state interpretation.
@@ -161,11 +372,80 @@ module Ace
 
           paths, stderr, status = git("ls-tree", "-d", "--name-only", value, "--", "execution/")
           raise AttemptErrors::EvidenceUnavailable, "Cannot discover journal assignments: #{stderr}" unless status.success?
-          paths.lines.map { |path| path.strip.delete_prefix("execution/") }.sort
+          paths.lines.map { |path| path.strip.delete_prefix("execution/") }
+            .reject { |id| id == "requests" }.sort
         end
 
         private
 
+        def update_service_request(request_id, expected:, replacement:, event_type:, guard: nil)
+          validate_request_id!(request_id)
+          with_lock do
+            CAS_ATTEMPTS.times do
+              old = ref_value
+              ensure_checkout!
+              old = ref_value if old.nil?
+              sync_checkout(old)
+              # Guards (for example authorization consumption) re-run inside
+              # the lock against the ref being committed, so a racing claim
+              # cannot slip through between the check and the CAS.
+              if guard
+                conflict = guard.call
+                if conflict
+                  raise AttemptErrors::Conflict,
+                    "Authorization reference already consumed by request #{conflict.fetch("request_id")}"
+                end
+              end
+              path = File.join(checkout_dir, service_request_path(request_id))
+              existing = File.exist?(path) ? JSON.parse(File.read(path)) : nil
+              if expected.nil? && existing
+                return existing if existing.except("state", "receipt", "reason", "claimed_at") ==
+                  replacement.except("state", "receipt", "reason", "claimed_at")
+                raise AttemptErrors::Conflict, "Service request #{request_id} has different input"
+              end
+              if expected && existing != expected
+                raise AttemptErrors::Conflict, "Service request #{request_id} changed during transition"
+              end
+              terminal = existing && %w[succeeded failed rejected].include?(existing["state"])
+              settlement = existing && existing["state"] == "failed" && replacement["state"] == "failed-settled"
+              if expected && existing && terminal && !settlement
+                raise AttemptErrors::InvalidState, "Service request #{request_id} is terminal"
+              end
+
+              FileUtils.mkdir_p(File.dirname(path))
+              File.write(path, JSON.pretty_generate(replacement))
+              assignment_id = replacement.fetch("assignment_id")
+              attempt_id = replacement.fetch("attempt_id")
+              prior = read_events(assignment_id).reverse
+                .find { |entry| entry["attempt_id"] == attempt_id }&.fetch("digest")
+              payload = {"request_id" => request_id, "state" => replacement.fetch("state"),
+                         "input_digest" => replacement.fetch("input_digest"),
+                         "receipt_digest" => replacement["receipt"] &&
+                           Atoms::EvidenceDigest.digest(replacement["receipt"])}
+              event = Models::EvidenceEvent.build(type: event_type, attempt_id: attempt_id,
+                payload: payload, previous_digest: prior)
+              write_event_files(assignment_id, [event])
+              git!("-C", checkout_dir, "add", "--", service_request_path(request_id),
+                "execution/#{assignment_id}/events")
+              state = replacement.fetch("state")
+              git!("-C", checkout_dir, "-c", "user.name=ace-assign", "-c", "user.email=ace-assign@localhost",
+                "commit", "-m", "evidence: service request #{request_id} #{state}")
+              commit = git!("-C", checkout_dir, "rev-parse", "HEAD").first
+              return replacement.merge("journal_commit" => commit) if update_ref_cas(commit, old)
+            end
+            raise AttemptErrors::EvidenceUnavailable, "Service request ref stayed conflicting"
+          end
+        end
+
+        def service_request_path(request_id)
+          "execution/requests/#{request_id}.json"
+        end
+
+        def validate_request_id!(request_id)
+          return if request_id.is_a?(String) && request_id.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/)
+          raise ArgumentError, "invalid service request ID"
+        end
+
         # Latest lifecycle state implied by the events, or nil when the
         # events do not describe a full attempt (intent missing).
         def derive_state(events)
@@ -387,7 +667,7 @@ module Ace
         def git!(*argv)
           out, stderr, status = git(*argv)
           unless status.success?
-            raise AttemptErrors::EvidenceUnavailable, "git #{argv.join(' ')} failed: #{stderr}"
+            raise AttemptErrors::EvidenceUnavailable, "git #{argv.join(" ")} failed: #{stderr}"
           end
 
           [out, stderr, status]

data/lib/ace/assign/organisms/attempt_coordinator.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
 require "open3"
+require "pathname"
 
 module Ace
   module Assign
@@ -21,6 +23,10 @@ module Ace
       # to the candidate revision invalidates prior candidate authorization;
       # `journal_commit` is tracked separately from both.
       class AttemptCoordinator
+        SERVICE_RECEIPT_FIELDS = %w[assignment_id attempt_id candidate_head evidence executor_uid
+          input_digest operation outcome project_id request_id target transport].freeze
+        SERVICE_BINDING_FIELDS = %w[request_id assignment_id attempt_id project_id operation
+          input_digest target candidate_head executor_uid transport].freeze
         # @param cache_base [String, nil] Assignment cache base
         # @param repo_root [String, nil] Candidate repository root (default: project root)
         # @param journal [Molecules::EvidenceJournal, nil] Evidence journal (default built per repo)
@@ -39,6 +45,260 @@ module Ace
 
         attr_reader :store
 
+        # Claim an external service effect before dispatch. Only a managed,
+        # active attempt for the exact project and candidate may own it. The
+        # guard re-runs inside the journal lock per CAS attempt, so a
+        # terminal event landing between validation and commit still blocks
+        # the claim.
+        def claim_service_request(binding)
+          attempt = service_attempt(binding)
+          head = candidate_head!
+          valid_head = binding["candidate_head"] == head && [nil, head].include?(attempt.candidate_head)
+          unless valid_head
+            raise AttemptErrors::ReceiptRejected, "Service request candidate head is stale"
+          end
+          require_review_evidence(attempt, head) if @verifier.external_effect?(binding["operation"])
+          # Dispatching claims record uncertain directly: the effect may
+          # happen as soon as the claim lands, and a crash before the
+          # executor response must leave uncertainty, not a stranded
+          # accepted state that a retry would return without dispatching.
+          journal_for.claim_service_request(binding, state: "uncertain", guard: -> { claim_guard(binding) })
+        end
+
+        # Rechecked against the authoritative ref for every locked claim
+        # attempt: the attempt must still be journal-active and the exact
+        # authorization must still be unconsumed.
+        def claim_guard(binding)
+          derived = journal_for.derived_attempts(binding.fetch("assignment_id"))
+            .find { |candidate| candidate.attempt_id == binding.fetch("attempt_id") }
+          unless derived&.active?
+            raise AttemptErrors::ReceiptRejected, "Attempt is no longer active in the authoritative journal"
+          end
+          journal_for.authorization_conflict(binding)
+        end
+
+        def service_attempt(binding)
+          attempt = authoritative_attempt(binding)
+          raise AttemptErrors::NotFound, "Attempt not found" unless attempt
+          unless attempt.managed? && attempt.active? &&
+              attempt.binding.assignment_id == binding["assignment_id"] &&
+              attempt.binding.project_id == binding["project_id"]
+            raise AttemptErrors::ReceiptRejected, "Service request does not match an active managed attempt"
+          end
+          attempt
+        end
+
+        # The authoritative journal wins for managed assignments, and a
+        # managed service claim REQUIRES the journal-derived attempt: a lost
+        # or unavailable evidence ref fails closed instead of trusting a
+        # local cache record that the journal cannot corroborate.
+        def authoritative_attempt(binding)
+          assignment_id = binding.fetch("assignment_id")
+          assignment = @manager.load(assignment_id)
+          if assignment&.managed?
+            journal_for.derived_attempts(assignment_id)
+              .find { |candidate| candidate.attempt_id == binding.fetch("attempt_id") }
+          else
+            @store.find(binding.fetch("attempt_id")) ||
+              recover_managed_attempt(assignment_id, binding.fetch("attempt_id"))
+          end
+        end
+
+        def reject_service_request(binding, reason:)
+          service_attempt(binding)
+          journal_for.reject_service_request(binding, reason: reason)
+        end
+
+        def service_request_status(request_id)
+          journal_for.service_request(request_id)
+        end
+
+        def transition_service_request(request_id, state:, receipt: nil)
+          if %w[succeeded failed].include?(state)
+            request = journal_for.service_request(request_id)
+            raise AttemptErrors::NotFound, "Service request #{request_id} not found" unless request
+            validate_service_receipt!(request, state, receipt)
+          elsif receipt
+            raise AttemptErrors::ReceiptRejected, "Non-terminal service transition cannot carry a receipt"
+          end
+          journal_for.transition_service_request(request_id, state: state, receipt: receipt, validated: true)
+        end
+
+        # Settle a failed effect as "no effect occurred". The settlement is
+        # evidence-validated like a terminal receipt — the executor must
+        # attest this request with outcome:failed and attributable evidence
+        # — and the original failure event stays in the journal history.
+        def reconcile_service_failure(request_id, receipt:)
+          request = journal_for.service_request(request_id)
+          raise AttemptErrors::NotFound, "Service request #{request_id} not found" unless request
+          unless %w[failed rejected uncertain].include?(request["state"]) &&
+              (request["state"] != "rejected" || request["consumed"] != false)
+            raise AttemptErrors::InvalidState,
+              "Only dispatched (failed, uncertain, or rejected) service requests can be reconciled"
+          end
+          settle_no_effect(request_id, request, receipt)
+        end
+
+        # Settle an uncertain claim whose handler was never invoked (a
+        # pre-dispatch refusal observed by the trusted local service). Same
+        # evidence rules as a failure settlement: a distinct, executor-owned
+        # no-effect attestation bound to this request.
+        def reconcile_service_no_effect(request_id, receipt:)
+          request = journal_for.service_request(request_id)
+          raise AttemptErrors::NotFound, "Service request #{request_id} not found" unless request
+          unless request["state"] == "uncertain"
+            raise AttemptErrors::InvalidState, "Only uncertain service requests can settle as no-effect"
+          end
+          settle_no_effect(request_id, request, receipt)
+        end
+
+        def settle_no_effect(request_id, request, receipt)
+          # The settlement must be a distinct, later executor attestation:
+          # replaying the already-recorded failure receipt proves nothing
+          # about whether the effect took place.
+          if request["receipt"] && Atoms::EvidenceDigest.digest(receipt) ==
+              Atoms::EvidenceDigest.digest(request["receipt"])
+            raise AttemptErrors::ReceiptRejected,
+              "Service failure settlement requires a new attestation, not the recorded receipt"
+          end
+          validate_service_receipt!(request, "failed", receipt, require_no_effect: true)
+          journal_for.transition_service_request(request_id, state: "failed-settled",
+            receipt: receipt, validated: true)
+        end
+
+        def validate_service_receipt!(request, state, receipt, require_no_effect: false)
+          unless receipt.is_a?(Hash) && receipt.keys.sort == SERVICE_RECEIPT_FIELDS.sort
+            raise AttemptErrors::ReceiptRejected, "Service receipt has invalid fields"
+          end
+          SERVICE_BINDING_FIELDS.each do |key|
+            unless receipt[key] == request[key]
+              raise AttemptErrors::ReceiptRejected, "Service receipt does not match #{key}"
+            end
+          end
+          unless receipt["outcome"] == state && receipt["executor_uid"].is_a?(Integer) &&
+              receipt["executor_uid"] >= 0 && valid_service_evidence?(receipt["evidence"])
+            raise AttemptErrors::ReceiptRejected, "Service receipt has invalid executor or evidence"
+          end
+          unless receipt["executor_uid"] == request["executor_uid"]
+            raise AttemptErrors::ReceiptRejected, "Service receipt executor does not match the claimed executor"
+          end
+          # Local transport runs the executor in the submitting process, so
+          # the submitter must be the configured executor identity itself.
+          if request["transport"] == "local" && Process.uid != request["executor_uid"]
+            raise AttemptErrors::ReceiptRejected, "Service receipt submitter is not the configured executor"
+          end
+          verify_service_evidence!(receipt["evidence"], request, state, require_no_effect: require_no_effect)
+        end
+
+        def valid_service_evidence?(evidence)
+          evidence.is_a?(Array) && !evidence.empty? && evidence.all? do |item|
+            item.is_a?(Hash) && item.keys.sort == %w[ref sha256] &&
+              item["ref"].is_a?(String) && item["ref"].match?(/\A[a-zA-Z0-9_.:\/-]{1,256}\z/) &&
+              item["sha256"].is_a?(String) && item["sha256"].match?(/\A[0-9a-f]{64}\z/)
+          end
+        end
+
+        # Evidence must live inside the candidate repository (symlinks
+        # resolved), be owned by — and not writable by anyone but — the
+        # claimed executor identity, postdate the claim, and carry a
+        # structured attestation naming the claimed request, input digest,
+        # and attested outcome. All checks read one open handle, so a swap
+        # on a caller-writable path cannot mix files between checks.
+        def verify_service_evidence!(evidence, request, state, require_no_effect: false)
+          repo_root = File.realpath(@repo_root)
+          claimed_at = parse_claimed_at(request)
+          evidence.each do |item|
+            ref = item["ref"]
+            unless Pathname.new(ref).relative?
+              raise AttemptErrors::ReceiptRejected, "Service receipt evidence must be repository-relative: #{ref}"
+            end
+            path = File.expand_path(ref, repo_root)
+            unless path.start_with?(repo_root + File::SEPARATOR)
+              raise AttemptErrors::ReceiptRejected, "Service receipt evidence must live inside the repository: #{ref}"
+            end
+            begin
+              file = File.open(path, "rb")
+            rescue Errno::ENOENT
+              raise AttemptErrors::ReceiptRejected, "Service receipt evidence is unavailable: #{ref}"
+            end
+            begin
+              real = File.realpath(path)
+              unless real.start_with?(repo_root + File::SEPARATOR)
+                raise AttemptErrors::ReceiptRejected, "Service receipt evidence must live inside the repository: #{ref}"
+              end
+              stat = file.stat
+              # The open handle must still be the file at the validated
+              # location: a swap between resolution and open fails here.
+              opened = File.stat(real)
+              unless opened.dev == stat.dev && opened.ino == stat.ino
+                raise AttemptErrors::ReceiptRejected, "Service receipt evidence changed during verification: #{ref}"
+              end
+              unless stat.uid == request["executor_uid"] && (stat.mode & 0o022).zero?
+                raise AttemptErrors::ReceiptRejected, "Service receipt evidence is not executor-owned: #{ref}"
+              end
+              unless claimed_at.nil? || stat.mtime >= claimed_at
+                raise AttemptErrors::ReceiptRejected, "Service receipt evidence predates the claim: #{ref}"
+              end
+              failed_at = parse_failed_at(request)
+              unless failed_at.nil? || stat.mtime >= failed_at
+                raise AttemptErrors::ReceiptRejected, "Service receipt evidence predates the failure: #{ref}"
+              end
+              content = file.read
+              unless attestation_line(content, request, state, require_no_effect: require_no_effect)
+                raise AttemptErrors::ReceiptRejected,
+                  "Service receipt evidence does not bind the claimed request: #{ref}"
+              end
+              unless Digest::SHA256.hexdigest(content) == item["sha256"]
+                raise AttemptErrors::ReceiptRejected, "Service receipt evidence digest mismatch: #{ref}"
+              end
+            ensure
+              file.close
+            end
+          end
+        end
+
+        # The evidence artifact must carry a structured attestation line
+        # naming the claimed request, input digest, and attested outcome
+        # exactly: an unrelated executor-owned file cannot attest this
+        # effect, prose cannot substitute for the attested outcome, and its
+        # result cannot be recorded under another terminal state.
+        def attestation_line(content, request, state, require_no_effect: false)
+          attestation = /^ace-service-attestation request:#{Regexp.escape(request.fetch("request_id"))} \
+input:#{Regexp.escape(request.fetch("input_digest"))} outcome:(\S+)( no-effect:(\S+))?$/
+          line = content.scan(attestation).first
+          return false unless line
+          return false if require_no_effect && line[2] != "true"
+          %w[succeeded failed].include?(state) ? line.first == state : true
+        end
+
+        def parse_claimed_at(request)
+          return nil if request["claimed_at"].nil?
+          Time.iso8601(request["claimed_at"])
+        rescue ArgumentError
+          raise AttemptErrors::ReceiptRejected, "Service request has an invalid claim timestamp"
+        end
+
+        def parse_failed_at(request)
+          return nil if request["failed_at"].nil?
+          Time.iso8601(request["failed_at"])
+        rescue ArgumentError
+          raise AttemptErrors::ReceiptRejected, "Service request has an invalid failure timestamp"
+        end
+
+        # Read-only eligibility check for dry-run: applies the same review
+        # evidence and candidate-head requirements as the claim without
+        # reserving anything.
+        def request_eligible!(binding)
+          attempt = service_attempt(binding)
+          head = candidate_head!
+          valid_head = binding["candidate_head"] == head && [nil, head].include?(attempt.candidate_head)
+          unless valid_head
+            raise AttemptErrors::ReceiptRejected, "Service request candidate head is stale"
+          end
+          require_review_evidence(attempt, head) if @verifier.external_effect?(binding["operation"])
+          true
+        end
+
         # Start a scoped attempt for an assignment.
         #
         # A repeated identical start returns the existing active attempt; a
@@ -207,13 +467,14 @@ module Ace
           expected_operation = case kind
           when "review-collection" then "review-collect"
           when "review-approval" then "review"
-          else check_name == "tests" ? "test" : check_name
+          else (check_name == "tests") ? "test" : check_name
           end
           unless data["campaign"].nil? && data["operation"] == expected_operation
             raise AttemptErrors::ReceiptRejected, "Accepted receipt operation does not prove #{kind}: #{expected_operation}"
           end
-          required_check = kind == "review-collection" ? "review-execution" : check_name
-          unless kind == "review-approval" || Array(data["checks"]).any? { |check| check["name"] == required_check && check["verdict"] == "passed" }
+          required_check = (kind == "review-collection") ? "review-execution" : check_name
+          has_required_check = Array(data["checks"]).any? { |check| check["name"] == required_check && check["verdict"] == "passed" }
+          unless kind == "review-approval" || has_required_check
             raise AttemptErrors::ReceiptRejected, "Accepted receipt does not prove the required check #{required_check}"
           end
           receipt = Models::ExecutionReceipt.from_h(data)
@@ -319,7 +580,7 @@ module Ace
             return nil if assignment && !assignment.managed?
 
             return journal_for.derived_attempts(assignment_id)
-              .find { |candidate| candidate.attempt_id == attempt_id }
+                .find { |candidate| candidate.attempt_id == attempt_id }
           end
 
           journal_for.assignment_ids.each do |journal_assignment_id|
@@ -407,7 +668,7 @@ module Ace
           recorded = reconciler.recorded_runtime(attempt)
           unless data.dig("producer", "runtime") == recorded
             raise AttemptErrors::ReceiptRejected,
-              "Receipt runtime #{data.dig('producer', 'runtime').inspect} does not match the recorded " \
+              "Receipt runtime #{data.dig("producer", "runtime").inspect} does not match the recorded " \
               "execution boundary #{recorded.inspect}"
           end
 
@@ -449,7 +710,8 @@ module Ace
           @reconciler ||= Molecules::AttemptReconciler.new(journal: journal_for, verifier: @verifier)
         end
 
-        def reserve(assignment, scope, project, identity, base_head, attempt_id)          binding = Models::AttemptBinding.new(
+        def reserve(assignment, scope, project, identity, base_head, attempt_id)
+          binding = Models::AttemptBinding.new(
             attempt_id: attempt_id,
             assignment_id: assignment.id,
             scope: scope,

data/lib/ace/assign/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Assign
-    VERSION = "0.60.0"
+    VERSION = "0.61.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-assign
 version: !ruby/object:Gem::Version
-  version: 0.60.0
+  version: 0.61.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -141,14 +141,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: ace-support-test-helpers
   requirement: !ruby/object:Gem::Requirement