phronomy 0.30.1 → 0.32.0

data/lib/phronomy/agent/execution/invocation_actions.rb

@@ -6,46 +6,48 @@ module Phronomy
     # Session construction and resource selection are supplied by the environment.
     # @api private
     class InvocationActions
-      def self.build_entry_actions(agent, environment, mode:, event_sink:)
+      def self.build_entry_actions(environment, mode:, event_sink:)
+        # Generated machine callbacks can outlive a session through VM method
+        # caches. Resolve the Agent from the current invocation, never capture it.
         calling_action = if mode.to_sym == :stream
-          method(:calling_llm_stream_action).curry.call(agent, environment, event_sink)
+          method(:calling_llm_stream_action).curry.call(environment, event_sink)
         else
-          method(:calling_llm_action).curry.call(agent, environment, event_sink)
+          method(:calling_llm_action).curry.call(environment, event_sink)
         end
 
         {
-          filtering_input: [method(:apply_prepared_input_action).curry.call(agent)],
-          building_context: [method(:prepare_runtime_input_action).curry.call(agent)],
+          filtering_input: [method(:apply_prepared_input_action)],
+          building_context: [method(:prepare_runtime_input_action)],
           calling_llm: [calling_action],
           starting_tools: [method(:starting_tools_action).curry.call(environment, event_sink)],
           dispatching_tools: [method(:dispatching_tools_action).curry.call(environment, event_sink)],
           recording_tool_results: [method(:recording_tool_results_action)],
           suspended: [method(:suspended_action)],
-          output_filtering: [method(:output_filtering_action).curry.call(agent)],
+          output_filtering: [method(:output_filtering_action)],
           failed: [method(:failed_action)]
         }
       end
 
-      def self.apply_prepared_input_action(_agent, invocation)
+      def self.apply_prepared_input_action(invocation)
         invocation.input = invocation.config.fetch(:phronomy_filtered_input)
         invocation
       end
       private_class_method :apply_prepared_input_action
 
-      def self.prepare_runtime_input_action(agent, invocation)
+      def self.prepare_runtime_input_action(invocation)
         projection = invocation.config.fetch(:phronomy_runtime_projection)
-        agent.send(:prepare_runtime_input, projection, invocation: invocation)
+        invocation.agent.send(:prepare_runtime_input, projection, invocation: invocation)
       end
       private_class_method :prepare_runtime_input_action
 
-      def self.calling_llm_action(agent, environment, event_sink, invocation)
-        prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming: false)
+      def self.calling_llm_action(environment, event_sink, invocation)
+        prepare_and_start_llm_call(invocation.agent, environment, event_sink, invocation, streaming: false)
         invocation
       end
       private_class_method :calling_llm_action
 
-      def self.calling_llm_stream_action(agent, environment, event_sink, invocation)
-        prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming: true)
+      def self.calling_llm_stream_action(environment, event_sink, invocation)
+        prepare_and_start_llm_call(invocation.agent, environment, event_sink, invocation, streaming: true)
         invocation
       end
       private_class_method :calling_llm_stream_action
@@ -354,8 +356,8 @@ module Phronomy
       end
       private_class_method :failed_action
 
-      def self.output_filtering_action(agent, invocation)
-        invocation.output = agent.send(:run_output_filters!, invocation.output)
+      def self.output_filtering_action(invocation)
+        invocation.output = invocation.agent.send(:run_output_filters!, invocation.output)
         invocation
       rescue Phronomy::FilterBlockError => error
         invocation.output_blocked = true

data/lib/phronomy/agent/execution_change.rb

@@ -75,6 +75,10 @@ module Phronomy
         return @result if outcome.disposition == :committed
         raise error if outcome.disposition == :not_committed
         raise Phronomy::ExecutionRehydrationRequiredError, "Execution change outcome is unknown: #{(outcome.read_error || error).message}"
+      ensure
+        # A completed synchronous change may remain on a worker's native stack.
+        # Release live execution wiring only after commit/readback has finished.
+        @agent = @write = @participant = nil
       end
 
       private :perform_once

data/lib/phronomy/agent/journal/journal_projection.rb

@@ -37,7 +37,12 @@ module Phronomy
       # clear_transcript! does not remove Knowledge, while knowledge_cleared and
       # context_reset invalidate earlier Knowledge records by Journal position.
       def context_records
-        (transcript_records + active_knowledge_records)
+        rejected_batches = rejected_tool_batches
+        messages = transcript_records.reject do |record|
+          %i[assistant_message tool_message].include?(record.kind) &&
+            record.llm_call_id && rejected_batches[record.execution_id] == record.llm_call_id
+        end
+        (messages + active_knowledge_records)
           .sort_by { |record| [record.sequence || 0, record.record_id] }
           .freeze
       end
@@ -52,6 +57,24 @@ module Phronomy
 
       private
 
+      # Rejection ends the execution at its final provider Tool batch. That
+      # exchange has no complete set of Tool replies to send to a provider.
+      # Identify it from existing journal facts, including pre-upgrade histories.
+      def rejected_tool_batches
+        rejected = {}
+        batches = {}
+        records.reverse_each do |record|
+          if record.kind == :execution_rejected
+            rejected[record.execution_id] = true
+          elsif record.kind == :assistant_message && rejected.delete(record.execution_id)
+            if Array(record.metadata["tool_call_ids"]).any? && record.llm_call_id
+              batches[record.execution_id] = record.llm_call_id
+            end
+          end
+        end
+        batches
+      end
+
       def active_knowledge_records
         reset_sequence = records.filter_map do |record|
           record.sequence if KNOWLEDGE_RESET_KINDS.include?(record.kind)

data/lib/phronomy/agent/lifecycle/hosted_invocation.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # An opt-in host handle. wait_result yields the ordinary terminal result or
+    # an ApprovalWait when the hosted operation itself is detached.
+    class HostedInvocation
+      def initialize(agent, execution_id, task, resumed_from: nil, &child_approval_wait)
+        @agent, @execution_id, @task = agent, execution_id, task
+        @environment = agent.__execution_environment
+        @resumed_from = resumed_from
+        @child_approval_wait = child_approval_wait
+      end
+
+      def wait_result(timeout: nil) = @task.wait_result(timeout: timeout)
+
+      # Supports racing normal completion or failure with an approval event.
+      def on_complete(&callback)
+        @task.on_complete(&callback)
+        self
+      end
+
+      def detach!(approval_request_id:, execution_id: @resumed_from&.execution_id || @execution_id)
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "detach! requires a host thread"
+        end
+        child = execution_id != @execution_id
+        wait = if @resumed_from
+          if execution_id == @resumed_from.execution_id && approval_request_id != @resumed_from.approval_request_id
+            @child_approval_wait.call(execution_id, approval_request_id)
+          end
+        elsif child
+          matching_child_wait(execution_id, approval_request_id)
+        else
+          @agent.persistence.standalone_approval_wait(agent_id: @agent.agent_id, execution_id: @execution_id)
+        end
+        unless wait && wait.approval_request_id == approval_request_id
+          raise Phronomy::AgentBusyError, "No matching hosted approval wait"
+        end
+        completion = Phronomy::TaskResult.deferred(name: "detach-hosted-approval")
+        owner = @environment.registry.agent_execution_owner(execution_id)
+        unless owner && (child ? owner.agent.persistence.equal?(@agent.persistence) : owner.agent.equal?(@agent))
+          raise Phronomy::AgentBusyError, "Hosted execution has no matching local owner"
+        end
+        command = ExecutionCoordinator::DetachHostedWait.new(coordinator: owner.coordinator, wait: wait,
+          task: (child && !@resumed_from) ? nil : @task, parent: child ? @agent : nil, completion: completion)
+        accepted = @environment.registry.post(command, completion: completion)
+        raise Phronomy::RuntimeShutdownError, "EventLoop rejected hosted detach" unless accepted
+        completion.wait_result
+      end
+
+      private
+
+      def matching_child_wait(execution_id, approval_request_id)
+        settled = @task.done?
+        wait = @child_approval_wait&.call(execution_id, approval_request_id)
+        return unless wait
+
+        # The child's event can precede the parent's committed coordination
+        # wait. Physical completion and that exact outcome authorize release.
+        @task.join
+        unless @task.coordination_wait_execution_id == @execution_id && @task.physical_complete?
+          @task.wait_result # Propagate a parent failure other than a committed wait.
+          raise Phronomy::AgentBusyError, "Hosted parent did not reach its coordination wait"
+        end
+        wait if settled || @child_approval_wait.call(execution_id, approval_request_id) == wait
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/lifetime_api.rb

@@ -29,6 +29,36 @@ module Phronomy
 
       private
 
+      # The participant proves which durable retentions are finished history;
+      # Agent controls admission, idleness and release of the local owners.
+      def __unload_with_peer_execution!(execution_id, reserved_by:)
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "Unloading coordinated Agents requires a host thread"
+        end
+        return false if @_phronomy_runtime_owner_state == :unloaded
+        __assert_live_agent!
+        peer = persistence.execution_identity(execution_id)
+        unless peer.correlation&.slice(*reserved_by.keys) == reserved_by
+          raise Phronomy::AgentBusyError, "Execution does not belong to this coordination owner"
+        end
+        environment = __execution_environment
+        environment.ownership.unload_idle_pair(self, peer.agent_id) do |live_peer|
+          ids = [agent_id, peer.agent_id].sort
+          if ids.any? { |id| environment.existing_registry&.agent_execution_admitted?(id) }
+            raise Phronomy::AgentBusyError, "A coordinated Agent has a local execution"
+          end
+          persistence.transaction do |records, scope|
+            unless scope.outermost?
+              raise Phronomy::Persistence::TransactionError, "Releasing local owners requires an outermost transaction"
+            end
+            ids.each { |id| records.executions.assert_idle!(id) }
+            unless yield(peer, live_peer, scope)
+              raise Phronomy::AgentBusyError, "No matching completed coordination history"
+            end
+          end
+        end
+      end
+
       def __with_operation(async: false, read_only: false)
         lease = __acquire_operation!(read_only: read_only)
         followed = false

data/lib/phronomy/agent/lifecycle/operation_lease.rb

@@ -20,6 +20,13 @@ module Phronomy
         ownership&.first&.release_operation(ownership[1], ownership[2])
       end
 
+      def reserve_approval_detach!(transition, parent: nil)
+        @mutex.synchronize do
+          raise Phronomy::AgentBusyError, "Hosted operation has ended" unless @registry
+          @registry.reserve_approval_detach!(@agent, @token, transition, parent: parent)
+        end
+      end
+
       def follow(task)
         if task.respond_to?(:on_physical_complete)
           task.on_physical_complete { release }

data/lib/phronomy/agent/lifecycle/operation_result.rb

@@ -6,6 +6,9 @@ module Phronomy
     # Only the domain runner acknowledges the end of its accepted operation.
     # @api private
     class OperationResult < Phronomy::Concurrency::PhysicalCompletionTask
+      # Published on the EventLoop before the task signals a committed coordination wait.
+      attr_accessor :coordination_wait_execution_id
+
       def initialize(agent:, name:)
         super(name: name)
         @operation_lease = agent.send(:__acquire_operation!)
@@ -20,6 +23,15 @@ module Phronomy
         release_if_quiet
       end
 
+      def reserve_approval_detach!(transition, parent: nil)
+        @lifetime_mutex.synchronize do
+          if @finished || @released || !@work.zero?
+            raise Phronomy::AgentBusyError, "Hosted operation is still busy or has finished"
+          end
+          @operation_lease.reserve_approval_detach!(transition, parent: parent)
+        end
+      end
+
       def track(task)
         @lifetime_mutex.synchronize { @work += 1 }
         task.on_physical_complete do

data/lib/phronomy/agent/lifecycle/ownership_registry.rb

@@ -165,12 +165,38 @@ module Phronomy
         true
       end
 
+      # Transfer only the single outstanding hosting operation, atomically with
+      # the same admission gate used by all other Agent operations.
+      def reserve_approval_detach!(agent, operation_token, transition, parent: nil)
+        @mutex.synchronize do
+          ensure_running!
+          entry = @entries[agent.agent_id]
+          operations = @operations[agent]
+          unless entry&.state == :live && entry.agent.equal?(agent) && !@scope_owners[agent.agent_id] &&
+              operations&.size == 1 && operations.key?(operation_token)
+            raise Phronomy::AgentBusyError, "Agent has another owner or accepted operation"
+          end
+          if parent
+            entry = @entries[parent.agent_id]
+            unless entry&.state == :live && entry.agent.equal?(parent) && !@scope_owners[parent.agent_id]
+              raise Phronomy::AgentBusyError, "Hosted parent no longer owns the local Agent"
+            end
+            assert_no_operations!(parent)
+            @entries[parent.agent_id] = Entry.new(state: :unloading, agent: parent, token: transition)
+          end
+          @entries[agent.agent_id] = Entry.new(state: :unloading, agent: agent, token: transition)
+        end
+      end
+
       # Returns the already accepted transition for duplicate callers.
       def reserve_unload(agent)
         @mutex.synchronize do
           ensure_running!
           entry = @entries[agent.agent_id]
           if entry&.state == :unloading && entry.agent.equal?(agent)
+            unless entry.token.is_a?(UnloadTransition)
+              raise Phronomy::AgentBusyError, "Agent has a coordinated release in progress"
+            end
             return [entry.token, false]
           end
           unless entry&.state == :live && entry.agent.equal?(agent)
@@ -183,22 +209,28 @@ module Phronomy
         end
       end
 
-      def finish_unload(agent, transition, success:)
-        @mutex.synchronize do
-          entry = @entries[agent.agent_id]
-          unless entry&.state == :unloading && entry.agent.equal?(agent) && entry.token.equal?(transition)
-            raise Phronomy::RuntimeShutdownError, "Agent unload reservation is no longer authoritative"
-          end
-          if success
-            agent.send(:__mark_unloaded!)
-            @entries.delete(agent.agent_id)
-            @scope_owners.delete(agent.agent_id)
-          else
-            @entries[agent.agent_id] = Entry.new(state: :live, agent: agent, token: nil)
+      def finish_unload(agent, transition, success:, parent: nil)
+        owners = {agent.agent_id => agent}
+        owners[parent.agent_id] = parent if parent
+        finish_unload_entries(owners, transition, success: success)
+      end
+
+      # Reserve the peer identity even when no instance is loaded. Its absence
+      # is then stable until the caller's durable checks commit or roll back.
+      def unload_idle_pair(parent, peer_id)
+        raise Phronomy::AgentBusyError, "Expected distinct Agent identities" if parent.agent_id == peer_id
+        transition = Object.new.freeze
+        # A host thread may exit during verification. Keep the short two-owner
+        # registry changes indivisible even in the presence of an async interrupt.
+        Thread.handle_interrupt(Object => :never) do
+          owners = reserve_idle_pair!(parent, peer_id, transition)
+          begin
+            Thread.handle_interrupt(Object => :immediate) { yield owners[peer_id] }
+            success = true
+          ensure
+            finish_unload_entries(owners, transition, success: success)
           end
-          @condition.broadcast
         end
-        true
       end
 
       def owned?(agent)
@@ -319,6 +351,46 @@ module Phronomy
 
       private
 
+      def reserve_idle_pair!(parent, peer_id, transition)
+        @mutex.synchronize do
+          ensure_running!
+          owners = {parent.agent_id => parent, peer_id => @entries[peer_id]&.agent}
+          owners.each do |id, agent|
+            entry = @entries[id]
+            raise Phronomy::AgentBusyError, "Agent belongs to a scope" if @scope_owners[id]
+            next if entry.nil? && agent.nil?
+            unless entry&.state == :live && entry.agent.equal?(agent)
+              raise Phronomy::AgentBusyError, "Local Agent owner changed"
+            end
+            assert_no_operations!(agent)
+          end
+          owners.each { |id, agent| @entries[id] = Entry.new(state: :unloading, agent: agent, token: transition) }
+          owners
+        end
+      end
+
+      def finish_unload_entries(owners, transition, success:)
+        @mutex.synchronize do
+          owners.each do |id, owner|
+            entry = @entries[id]
+            unless entry&.state == :unloading && entry.agent.equal?(owner) && entry.token.equal?(transition)
+              raise Phronomy::RuntimeShutdownError, "Agent unload reservation is no longer authoritative"
+            end
+          end
+          owners.each do |id, owner|
+            if success || owner.nil?
+              owner&.send(:__mark_unloaded!)
+              @entries.delete(id)
+              @scope_owners.delete(id)
+            else
+              @entries[id] = Entry.new(state: :live, agent: owner, token: nil)
+            end
+          end
+          @condition.broadcast
+        end
+        true
+      end
+
       def reserve_create!(key, scope_owner: nil)
         token = Object.new.freeze
         @mutex.synchronize do

data/lib/phronomy/agent/output_contract.rb

@@ -9,13 +9,17 @@ module Phronomy
     class OutputContract
       FACTORIES = {}
       private_constant :FACTORIES
-      attr_reader :schema, :digest
+      attr_reader :schema, :digest, :schema_delivery
 
       def self.install_factory(factory)
         FACTORIES.replace(parser: factory).freeze
       end
 
-      def initialize(schema)
+      def initialize(schema, schema_delivery: :native)
+        unless %i[native none].include?(schema_delivery)
+          raise ArgumentError, "schema_delivery must be :native or :none"
+        end
+        @schema_delivery = schema_delivery
         @parser = FACTORIES.fetch(:parser).call(schema)
         @schema = @parser.json_schema
         @digest = Digest::SHA256.hexdigest(JSON.generate(@schema, sort_keys: true)).freeze
@@ -23,20 +27,58 @@ module Phronomy
       end
 
       def metadata(contents)
-        {"output_contract" => {"version" => 1, "schema_ref" => contents.put_text(JSON.generate(schema, sort_keys: true)), "schema_digest" => digest}}
+        {"output_contract" => {"version" => 2, "schema_ref" => contents.put_text(JSON.generate(schema, sort_keys: true)),
+                               "schema_digest" => digest, "schema_delivery" => schema_delivery.to_s}}
       end
 
       def self.restore(execution, contents)
         stored = execution.metadata["output_contract"]
         return nil unless stored
-        raise ArgumentError, "unsupported Agent output contract version" unless stored.fetch("version") == 1
-        contract = new(contents.fetch_json(stored.fetch("schema_ref")))
+        contract = new(contents.fetch_json(stored.fetch("schema_ref")), schema_delivery: delivery(stored))
         unless contract.digest == stored.fetch("schema_digest")
           raise Phronomy::ContentStore::IntegrityError, "Agent output schema digest mismatch"
         end
         contract
       end
 
+      # The schema stays durable even when the provider receives no schema.
+      def self.response_schema_ref(metadata)
+        stored = metadata["output_contract"]
+        stored.fetch("schema_ref") if stored && delivery(stored) == :native
+      end
+
+      def self.delivery(stored)
+        case stored.fetch("version")
+        when 1 then :native
+        when 2
+          value = stored.fetch("schema_delivery")
+          unless %w[native none].include?(value)
+            raise ArgumentError, "unsupported Agent schema delivery"
+          end
+          value.to_sym
+        else
+          raise ArgumentError, "unsupported Agent output contract version"
+        end
+      end
+
+      # Agent owns the final-output contract, including bypass prevention when
+      # no native schema is sent. Provider configuration cannot replace it.
+      def self.validate_model_config!(value)
+        case value
+        when Hash
+          value.each do |key, child|
+            if %w[schema schema_delivery output_schema response_schema response_format responseJsonSchema responseSchema
+              text.format output_config.format].include?(key.to_s) ||
+                (%w[text output_config].include?(key.to_s) && child.is_a?(Hash) && child.keys.any? { |name| name.to_s == "format" })
+              raise ArgumentError, "model configuration cannot override the Agent output contract"
+            end
+            validate_model_config!(child)
+          end
+        when Array
+          value.each { |child| validate_model_config!(child) }
+        end
+      end
+
       def validate(output, response:, execution_id:)
         raw = response&.content
         reason = if response&.refusal || response&.finish_reason == :refusal

data/lib/phronomy/agent/persistence/codec.rb

@@ -12,6 +12,7 @@ module Phronomy
         AGENT_ROOT_FORMAT_VERSION = "0.1"
         AGENT_EXECUTION_RECORD_TYPE = "phronomy.agent_execution"
         AGENT_EXECUTION_FORMAT_VERSION = "0.2"
+        OUTPUT_CONTRACT_FORMAT_VERSION = "0.3"
         JOURNAL_RECORD_TYPE = "phronomy.journal_record"
         JOURNAL_FORMAT_VERSION = "0.1"
         AGENT_ROOT_KEYS = %w[
@@ -88,7 +89,7 @@ module Phronomy
           validate_agent_execution_payload!(payload)
           build_record(
             AGENT_EXECUTION_RECORD_TYPE,
-            AGENT_EXECUTION_FORMAT_VERSION,
+            execution_format_version(payload),
             payload
           )
         rescue Phronomy::Storage::SerializationError
@@ -101,11 +102,15 @@ module Phronomy
           payload = current_payload!(
             record,
             record_type: AGENT_EXECUTION_RECORD_TYPE,
-            format_version: AGENT_EXECUTION_FORMAT_VERSION,
+            format_version: (record.respond_to?(:format_version) && record.format_version == OUTPUT_CONTRACT_FORMAT_VERSION) ?
+              OUTPUT_CONTRACT_FORMAT_VERSION : AGENT_EXECUTION_FORMAT_VERSION,
             keys: AGENT_EXECUTION_KEYS,
             label: "AgentExecution payload"
           )
           validate_agent_execution_payload!(payload)
+          unless record.format_version == execution_format_version(payload)
+            raise Phronomy::Storage::SerializationError, "Agent output contract does not match execution format version"
+          end
           Phronomy::Agent::AgentExecution.from_h(payload)
         rescue Phronomy::Storage::SerializationError
           raise
@@ -113,6 +118,15 @@ module Phronomy
           serialization_error("cannot decode AgentExecution", error)
         end
 
+        # Old readers reject the new envelope before interpreting any execution.
+        # Freeform and version-one records retain their original envelope.
+        def execution_format_version(payload)
+          stored = payload.fetch("metadata")["output_contract"]
+          return AGENT_EXECUTION_FORMAT_VERSION unless stored
+          Phronomy::Agent::OutputContract.delivery(stored)
+          (stored.fetch("version") == 2) ? OUTPUT_CONTRACT_FORMAT_VERSION : AGENT_EXECUTION_FORMAT_VERSION
+        end
+
         def encode_journal_record(journal_record)
           payload = journal_payload(journal_record, require_sequence: true)
           build_record(JOURNAL_RECORD_TYPE, JOURNAL_FORMAT_VERSION, payload)

data/lib/phronomy/agent/recovery/recovery_coordinator/continuation.rb

@@ -28,6 +28,7 @@ module Phronomy
         # operation-local projections transferred to the new invocation, never a
         # shared cache or a second source of continuation decisions.
         def prepare_recovery_material(execution, projection: nil)
+          OutputContract.restore(execution, agent.persistence.contents)
           action = recovery_action(execution)
           suspended = execution.status == :suspended || execution.phase.to_sym == :resuming
           return if !suspended && %i[resolution_required failed_terminal].include?(action)

data/lib/phronomy/agent/recovery/recovery_coordinator/installation.rb

@@ -316,7 +316,7 @@ module Phronomy
           main = agent.send(:execution_coordinator_for, agent.__execution_wiring)
 
           if framework_batch?(execution)
-            internal = Phronomy::TaskResult.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
+            internal = ExecutionCoordinator::FrameworkRecoveryTask.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal, material: material)
             agent.send(:_complete_result_task, completion, agent)
             return

data/lib/phronomy/agent/runtime_binding/engine_session_builder.rb

@@ -9,8 +9,8 @@ module Phronomy
       def self.build(invocation:, environment:, event_loop:, resume_event: nil, resume_phase: nil)
         event_sink = Phronomy::FSMSession::EventSink.new(event_loop: event_loop)
         invocation.bind_event_sink!(event_sink)
-        actions = InvocationActions.build_entry_actions(invocation.agent,
-          environment, mode: invocation.mode, event_sink: event_sink)
+        actions = InvocationActions.build_entry_actions(environment,
+          mode: invocation.mode, event_sink: event_sink)
         phase_machine = PhaseMachineBuilder.new(entry_actions: actions).build
 
         Phronomy::FSMSession.new(

data/lib/phronomy/agent/runtime_input.rb

@@ -54,6 +54,13 @@ module Phronomy
         )
       end
 
+      # One interpretation for execution results and public transcript reads.
+      def materialize_transcript(root:, records:)
+        materialize_journal_records(
+          JournalProjection.new(agent_root: root, records: records).transcript_records
+        )
+      end
+
       def materialize_journal_record(record)
         materialize_segment(segment_from_record(record))
       end

data/lib/phronomy/agent/store.rb

@@ -108,6 +108,58 @@ module Phronomy
         end
       end
 
+      # Read without loading a live Agent. Missing or ineligible waits return nil.
+      def standalone_approval_wait(agent_id:, execution_id:, scope: nil)
+        approval_wait_for(agent_id: agent_id, execution_id: execution_id, correlation: nil, retentions: [], scope: scope)
+      end
+
+      # Participant observation. An active coordinated wait must match both its
+      # exact reservation and every durable retention owned by the participant.
+      # @api private
+      def approval_wait_for(agent_id:, execution_id:, correlation:, retentions:, scope:)
+        with_scope(scope) do |records|
+          begin
+            execution = records.executions.load(execution_id)
+          rescue Phronomy::Persistence::NotFoundError
+            next
+          end
+          assert_execution_owner!(execution, agent_id)
+          next unless execution.status == :suspended && (id = execution.approval_request&.fetch("id", nil))
+          next unless execution.metadata["reservation"] == correlation && !execution.metadata["execution_extension"]
+          next if execution.metadata["cancellation_requested"] || records.cancellations.requested?(agent_id, execution_id)
+          next unless records.retentions.list(agent_id) == retentions
+
+          ApprovalWait.new(execution_id: execution.execution_id.dup.freeze, approval_request_id: id.dup.freeze,
+            execution_revision: execution.execution_revision)
+        end
+      end
+
+      # A native participant can release a root only at a single replayable
+      # Tool dispatch. A mixed batch may still require external Tool evidence.
+      # @api private
+      def single_dispatch_wait?(agent_id:, execution_id:, invocation_id:, name:, scope:, expected_revision: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          next false if expected_revision && execution.execution_revision != expected_revision
+          batch = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
+          execution.status == :active && execution.phase.to_sym == :dispatching_tools &&
+            !execution.metadata["reservation"] && !execution.metadata["cancellation_requested"] &&
+            !records.cancellations.requested?(agent_id, execution_id) &&
+            batch.size == 1 && batch.first.values_at("tool_invocation_id", "tool_name", "status") == [invocation_id, name, "authorized"]
+        end
+      end
+
+      # Check a historical reference without reading its output or error content.
+      # @api private
+      def terminal_execution?(agent_id:, execution_id:, scope:, reservation: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          execution.terminal? && (reservation.nil? || execution.metadata["reservation"] == reservation)
+        end
+      end
+
       def active_executions(agent_id:, scope: nil)
         with_scope(scope) do |records|
           records.executions.list_active(agent_id).map do |execution|