phronomy 0.27.0 → 0.28.0

data/lib/phronomy/multi_agent/handoff_runner.rb

@@ -4,171 +4,148 @@ require "time"
 
 module Phronomy
   module MultiAgent
-    # Coordinates durable handoffs across Agents using one Persistence instance.
+    # Durable turn coordination using Agent's public exact-execution operations.
     # @api public
     class HandoffRunner
       MAX_HANDOFFS = 20
-
-      # @api public
       attr_reader :main_agent, :handoffs
 
-      # @api public
-      def initialize(main_agent:, handoffs: [])
-        @main_agent, @handoffs = main_agent, Array(handoffs).freeze
-        @persistence = main_agent.persistence
-        raise ArgumentError, "handoffs must contain Agent::Handoff" unless @handoffs.all? { |h| h.is_a?(Phronomy::Agent::Handoff) }
-        @agents = ([main_agent] + @handoffs.flat_map { |edge| [edge.source_agent, edge.target_agent] }).uniq.to_h { |a| [a.agent_id, a] }.freeze
-        unless @agents.values.all? { |a| a.persistence.equal?(@persistence) }
-          raise Phronomy::ConfigurationError, "Durable Handoff graph requires one Persistence instance"
+      def initialize(main_agent:, persistence:, handoffs: [])
+        @main_agent, @persistence, @handoffs = main_agent, persistence, Array(handoffs).freeze
+        raise ArgumentError, "handoffs must contain MultiAgent::Handoff" unless @handoffs.all? { |edge| edge.is_a?(Handoff) }
+        @agents = ([main_agent] + @handoffs.flat_map { |edge| [edge.source_agent, edge.target_agent] }).uniq.to_h { |agent| [agent.agent_id, agent] }.freeze
+        unless @agents.values.all? { |agent| agent.persistence.equal?(@persistence.agent_store) }
+          raise Phronomy::ConfigurationError, "Handoff graph and coordination store must share the same Agent store"
         end
-        if @handoffs.group_by { |h| [h.source_agent.agent_id, h.target_agent.agent_id] }.any? { |_, edges| edges.size > 1 }
+        if @handoffs.group_by { |edge| [edge.source_agent.agent_id, edge.target_agent.agent_id] }.any? { |_, edges| edges.size > 1 }
           raise ArgumentError, "Duplicate Source/Target Handoff edges"
         end
-        @bindings = @handoffs.group_by { |h| h.source_agent.agent_id }.transform_values { |edges| edges.map { |h| Phronomy::Agent::HandoffCapabilityFactory.build(h) }.freeze }.freeze
-        @runtime = Phronomy::Runtime.instance
-        @admissions = Phronomy::MultiAgent::AdmissionRegistry.for(@runtime)
+        @bindings = @handoffs.group_by { |edge| edge.source_agent.agent_id }.transform_values { |edges| edges.map { |edge| HandoffCapabilityFactory.build(edge) }.freeze }.freeze
+        @environment = ExecutionEnvironment.current
+        @admissions = @environment.admissions
       end
 
-      # @api public
       def invoke(input, config: {})
-        trace_handle = Phronomy::Tracing::Automatic.start("multi_agent.turn",
-          input: input, main_agent_id: main_agent.agent_id,
-          **main_agent.send(:_build_caller_meta, config))
-        operation_error = result = nil
-        if Phronomy::Runtime.in_event_loop_context?
-          raise Phronomy::EventLoopReentrancyError, "HandoffRunner#invoke cannot block EventLoop"
-        end
-        unless Phronomy::Runtime.instance.equal?(@runtime)
-          raise Phronomy::RuntimeShutdownError, "HandoffRunner belongs to a previous Runtime"
-        end
+        raise Phronomy::EventLoopReentrancyError, "HandoffRunner#invoke cannot block EventLoop" if Phronomy::WaitPolicy.blocking_forbidden?
+        raise Phronomy::RuntimeShutdownError, "HandoffRunner belongs to a previous Runtime" unless @environment.current?
+        trace = Phronomy::Tracing::Automatic.start("multi_agent.turn", input: input, main_agent_id: main_agent.agent_id)
+        error = result = nil
         config = config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
         @admissions.admit!(main_agent)
         admitted = true
         state = load_state
         count = 0
         loop do
-          active = @agents.fetch(state.active_agent_id) do
-            raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks active Agent #{state.active_agent_id}"
-          end
-          context = state.active_handoff_context_ref && Phronomy::Agent::HandoffContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
-          wiring = config.merge(phronomy_handoff_bindings: @bindings.fetch(active.agent_id, []),
-            phronomy_handoff_context: context,
-            phronomy_coordination: {"kind" => "handoff", "main_agent_id" => main_agent.agent_id, "handoff_revision" => state.handoff_revision}).freeze
-          active.instance_variable_set(:@_phronomy_coordination_config, wiring)
+          active = @agents.fetch(state.active_agent_id) { raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks active Agent #{state.active_agent_id}" }
+          context = state.active_handoff_context_ref && Phronomy::Agent::TransferContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
+          owner = {"kind" => "handoff", "main_agent_id" => main_agent.agent_id}.freeze
+          wiring = config.merge(phronomy_control_bindings: @bindings.fetch(active.agent_id, []), phronomy_transfer_context: context,
+            phronomy_execution_participant: HandoffParticipant.new(persistence: @persistence, main_agent_id: main_agent.agent_id, expected_revision: state.handoff_revision),
+            phronomy_reservation: owner, phronomy_admission: ReservedChildAdmission.new(persistence: @persistence, owner: owner))
           result = if state.phase == "stable"
-            unfinished = @persistence.executions.list_active(active.agent_id)
+            unfinished = @persistence.agent_store.active_executions(agent_id: active.agent_id)
             if unfinished.empty?
               active.invoke(input, config: wiring)
             else
               exact = unfinished.fetch(0)
-              unless unfinished.size == 1 && exact.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-                raise Phronomy::Storage::ConflictError, "Active Agent execution belongs to another coordination turn"
+              unless unfinished.size == 1 && exact.reservation&.correlation == owner
+                raise Phronomy::Persistence::StateConflictError, "Active execution belongs to another turn"
               end
               wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(exact.execution_id)
-              stored_input = @persistence.contents.fetch_text(exact.metadata.fetch("current_input_ref"))
-              Phronomy::Agent::ExactExecution.start(agent: active, execution_id: exact.execution_id, input: stored_input, config: wiring).wait_result
+              active.resume_async(exact.execution_id, config: wiring).wait_result
             end
           else
-            source = @persistence.executions.load(state.pending_source_execution_id)
+            source = @persistence.agent_store.execution_identity(state.pending_source_execution_id)
             unless @handoffs.any? { |edge| edge.source_agent.agent_id == source.agent_id && edge.target_agent.agent_id == state.active_agent_id }
               raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks committed Source/Target edge"
             end
-            definition = state.metadata.fetch("target_definition")
-            unless active.class.agent_definition == definition.transform_keys(&:to_sym)
+            unless active.class.agent_definition == state.metadata.fetch("target_definition").transform_keys(&:to_sym)
               raise Phronomy::ConfigurationError, "Handoff Target definition mismatch"
             end
             wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(state.pending_target_execution_id)
-            Phronomy::Agent::ExactExecution.start(agent: active, execution_id: state.pending_target_execution_id,
-              input: context.responsibility, config: wiring).wait_result
+            reservation = Phronomy::Agent::ReservedExecution.new(agent_id: active.agent_id, execution_id: state.pending_target_execution_id, correlation: owner)
+            active.start_reserved_async(reservation: reservation, input: context.responsibility, config: wiring).wait_result
           end
-          execution = @persistence.executions.load(result.fetch(:execution_id))
-          if execution.status == :handed_off
+          observed = @persistence.agent_store.observe_execution(agent_id: active.agent_id, execution_id: result.fetch(:execution_id))
+          if observed.status == :handed_off
             count += 1
             raise Phronomy::HandoffError, "Exceeded maximum Handoffs in one turn" if count > MAX_HANDOFFS
             state = @persistence.handoff_states.load(main_agent.agent_id)
             next
           end
-          if execution.active?
-            raise Phronomy::ExecutionRehydrationRequiredError, "Handoff execution requires approval or recovery"
-          end
-          raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
+          raise Phronomy::ExecutionRehydrationRequiredError, "Handoff requires approval or recovery" if observed.active?
+          observed.value!
           return result.reject { |key, _| key.to_s.start_with?("_phronomy_") || key == :handoff_request }.merge(agent: active)
         end
-      rescue Phronomy::CancellationError => error
-        operation_error = error
+      rescue Phronomy::CancellationError => caught
+        error = caught
         cancel(state.pending_source_execution_id) if state && state.phase != "stable"
         raise
-      rescue => error
-        operation_error = error
+      rescue => caught
+        error = caught
         raise
       ensure
         @admissions.release!(main_agent) if admitted
-        Phronomy::Tracing::Automatic.finish(trace_handle, output: result && result[:output], error: operation_error)
+        Phronomy::Tracing::Automatic.finish(trace, output: result && result[:output], error: error) if trace
       end
 
-      # Durably scopes cancellation to an exact turn, including a transferred
-      # Target reservation. A completed older turn never cancels a later turn.
-      # @api public
       def cancel(execution_id)
-        if Phronomy::Runtime.in_event_loop_context?
-          raise Phronomy::EventLoopReentrancyError, "HandoffRunner#cancel cannot block EventLoop"
-        end
-        intended = leaf = leaf_id = nil
+        raise Phronomy::EventLoopReentrancyError, "HandoffRunner#cancel cannot block EventLoop" if Phronomy::WaitPolicy.blocking_forbidden?
+        leaf = intended = nil
         begin
-          @persistence.transaction do |tx|
-            first = tx.executions.load(execution_id)
-            unless first.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-              raise Phronomy::Storage::ConflictError, "Execution does not belong to this Handoff anchor"
+          @persistence.transaction do |records, scope|
+            routing = records.handoff_states.load_locked(main_agent.agent_id)
+            # All leaf reads occur after the same guard used by target admission.
+            leaf = @persistence.handoff_leaf(execution_id, main_agent_id: main_agent.agent_id, scope: scope)
+            next if leaf.terminal?
+            unless routing && (leaf.absent? ? routing.pending_target_execution_id == leaf.execution_id : routing.active_agent_id == leaf.agent_id)
+              raise Phronomy::Persistence::StateConflictError, "Handoff no longer owns the requested turn"
             end
-            leaf = first
-            leaf_id = first.execution_id
-            seen = {}
-            while leaf&.status == :handed_off
-              raise Phronomy::Storage::SerializationError, "Cyclic Handoff chain" if seen[leaf_id]
-              seen[leaf_id] = true
-              leaf_id = leaf.metadata.fetch("handoff_target_execution_id")
-              begin
-                leaf = tx.executions.load(leaf_id)
-              rescue Phronomy::Storage::NotFoundError
-                leaf = nil
-              end
-            end
-            next if leaf&.terminal?
-            routing = tx.handoff_states.load(main_agent.agent_id)
-            unless routing && (leaf ? routing.active_agent_id == leaf.agent_id : routing.pending_target_execution_id == leaf_id)
-              raise Phronomy::Storage::ConflictError, "Handoff routing no longer owns the requested turn"
+            @persistence.agent_store.guard_agents(scope, agent_ids: [main_agent.agent_id, leaf.agent_id])
+            @persistence.agent_store.request_cancellation(agent_id: leaf.agent_id, execution_id: leaf.execution_id, scope: scope) unless leaf.absent?
+            ids = (Array(routing.metadata["cancelled_execution_ids"]) + [leaf.execution_id]).uniq
+            intended = routing.with(phase: leaf.absent? ? "stable" : routing.phase, metadata: routing.metadata.merge("cancelled_execution_ids" => ids))
+            records.handoff_states.save(main_agent.agent_id, expected_revision: routing.handoff_revision, state: intended)
+          end
+        rescue => failure
+          raise unless intended
+          proof = Phronomy::Persistence::SaveOutcome.compare(before: nil, after: [intended.to_h, true], original_error: failure) do
+            @persistence.transaction do |records, scope|
+              current = records.handoff_states.load_locked(main_agent.agent_id)
+              cancelled = leaf.absent? || @persistence.agent_store.cancellation_requested?(agent_id: leaf.agent_id, execution_id: leaf.execution_id, scope: scope)
+              [current&.to_h, cancelled]
             end
-            ids = (Array(routing.metadata["cancelled_execution_ids"]) + [leaf_id]).uniq
-            intended = routing.with(phase: leaf ? routing.phase : "stable",
-              metadata: routing.metadata.merge("cancelled_execution_ids" => ids))
-            tx.handoff_states.save(main_agent.agent_id, expected_revision: routing.handoff_revision, state: intended)
           end
-        rescue => error
-          confirmed = @persistence.handoff_states.load(main_agent.agent_id)
-          raise error unless intended && confirmed && Array(confirmed.metadata["cancelled_execution_ids"]).include?(leaf_id)
+          raise failure unless proof.disposition == :committed
         end
-        return @persistence.execution_result(leaf_id) if leaf&.terminal?
-        Phronomy::Agent::ExecutionCancellation.signal(leaf_id, leaf.agent_id) if leaf&.active?
-        {execution_id: leaf_id, cancellation_requested: !leaf&.terminal?}.freeze
+        return leaf.to_result if leaf.terminal?
+        @agents[leaf.agent_id]&.cancel_async(leaf.execution_id)&.wait_result if leaf.active?
+        {execution_id: leaf.execution_id, cancellation_requested: true}.freeze
       end
 
-      # Reads a specified source/Target chain without current graph continuation.
-      # @api public
       def result(execution_id)
         @persistence.handoff_result(execution_id, main_agent_id: main_agent.agent_id)
       end
 
+      # Explicit history removal releases references before Agent purge is allowed.
+      def forget_history!
+        @persistence.forget_handoff(main_agent.agent_id)
+      end
+
       private
 
       def load_state
         state = @persistence.handoff_states.load(main_agent.agent_id)
         return state if state
         now = Time.now.utc.iso8601(6)
-        initial = Phronomy::Agent::HandoffState.new(main_agent_id: main_agent.agent_id, handoff_revision: 1,
-          active_agent_id: main_agent.agent_id, active_handoff_context_ref: nil,
-          phase: "stable", pending_source_execution_id: nil, pending_target_execution_id: nil,
-          created_at: now, updated_at: now, metadata: {})
-        @persistence.transaction { |tx| tx.handoff_states.save(main_agent.agent_id, expected_revision: nil, state: initial) }
+        initial = HandoffState.new(main_agent_id: main_agent.agent_id, handoff_revision: 1,
+          active_agent_id: main_agent.agent_id, active_handoff_context_ref: nil, phase: "stable",
+          pending_source_execution_id: nil, pending_target_execution_id: nil,
+          created_at: now, updated_at: now, metadata: {"retained_agent_ids" => [main_agent.agent_id]})
+        @persistence.transaction do |records, scope|
+          @persistence.agent_store.retain(Phronomy::Agent::Retention.new(agent_id: main_agent.agent_id, owner_key: "handoff:#{main_agent.agent_id}"), scope: scope)
+          records.handoff_states.save(main_agent.agent_id, expected_revision: nil, state: initial)
+        end
       rescue => error
         confirmed = @persistence.handoff_states.load(main_agent.agent_id)
         raise error unless confirmed

data/lib/phronomy/{agent/handoff → multi_agent}/handoff_state.rb

@@ -3,7 +3,7 @@
 require "time"
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Immutable current-format semantic record; contains no Runtime handles.
     # @api private
     class HandoffState

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -9,32 +9,42 @@ module Phronomy
       ParallelChild = Data.define(:index, :agent, :input, :config)
       private_constant :ParallelChild
 
-      # Own one live cancellation token shared with this invocation's static
-      # children, including when Recovery reconstructs the invocation.
-      # @api private
-      def __invocation_config(config)
-        config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
+      attr_reader :coordination_store
+
+      def self.create(coordination_store: nil, **options, &block)
+        new(coordination_store: coordination_store, **options, &block)
       end
 
-      # Resumes retained static child coordination with current class wiring.
-      # @api public
-      def resume(execution_id, config: {})
-        if Phronomy::Runtime.in_event_loop_context?
-          raise Phronomy::EventLoopReentrancyError, "Orchestrator#resume cannot block EventLoop"
+      def self.load(agent_id, persistence:, coordination_store:, **options, &block)
+        participant = DurableSubagentCoordinator.new(agent_class: self, persistence: coordination_store)
+        super(agent_id, persistence: persistence, execution_wiring: {phronomy_execution_participant: participant}, **options, &block)
+      end
+
+      def initialize(coordination_store: nil, execution_wiring: {}, **options, &block)
+        @coordination_store = coordination_store || execution_wiring[:phronomy_execution_participant]&.persistence || Phronomy::MultiAgent::Store.configured
+        super(execution_wiring: execution_wiring, **options, &block)
+        if @coordination_store && !@coordination_store.agent_store.equal?(persistence)
+          raise Phronomy::ConfigurationError, "Orchestrator stores must share the same Agent store"
         end
-        execution = persistence.executions.load(execution_id)
-        raise Phronomy::Storage::ConflictError, "Parent execution owner mismatch" unless execution.agent_id == agent_id
-        input = persistence.contents.fetch_text(execution.metadata.fetch("current_input_ref"))
-        result = Phronomy::Agent::ExactExecution.start(agent: self, execution_id: execution_id, input: input, config: config).wait_result
-        raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
-        result
+        @participant = @coordination_store && DurableSubagentCoordinator.new(agent_class: self.class, persistence: @coordination_store)
+      end
+
+      # Current composition, never serialized in an execution record.
+      def __invocation_config(config)
+        if !self.class.registered_subagents.empty? && !@participant
+          raise Phronomy::ConfigurationError, "Durable subagents require coordination_store:"
+        end
+        config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new,
+          phronomy_execution_participant: @participant).compact
       end
 
       def self.subagent(name, agent_class, on_error: :raise, inherit_knowledge: true)
         # A subagent Tool is logically asynchronous: ToolInvocation starts the
         # child Agent and resumes when its completion TaskResult settles. It must not
         # occupy an OffloadPool worker while waiting for the child.
-        tool_class = Class.new(Phronomy::Tools::Agent) do
+        tool_class = Class.new(Phronomy::Tool::Base) do
+          execution_mode :cooperative
+          param :input, type: :string, desc: "The input to forward to the wrapped Agent"
           def self.__framework_owned_operation? = true
           tool_name "dispatch_to_#{name}"
           description "Dispatch work to the #{name} subagent (#{agent_class.name})"
@@ -53,14 +63,17 @@ module Phronomy
           # cancelled: an already admitted child must be settled, not forgotten.
           define_method(:call_async) do |args, cancellation_token: nil, config: {}|
             if @_orchestrator_context&.fetch(:parent, nil) && config[:phronomy_tool_invocation_id]
-              validated, schema_error = send(:validate_and_coerce, args)
+              validated, schema_error = validate_arguments(args)
               raise Phronomy::ToolError, schema_error if schema_error
               execute_async(**validated, cancellation_token: cancellation_token, config: config)
             else
-              super(args, cancellation_token: cancellation_token, config: config)
+              call_async_operation(args, cancellation_token: cancellation_token,
+                operation_name: "agent-tool-#{self.name}") do |validated_args|
+                execute_async(**validated_args, cancellation_token: cancellation_token, config: config || {})
+              end
             end
           rescue => error
-            Phronomy::TaskResult.deferred(name: "subagent-dispatch-failed").tap { |task| task.fail(error) }
+            Phronomy::TaskResult.failed(error, name: "subagent-dispatch-failed")
           end
 
           define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
@@ -86,29 +99,25 @@ module Phronomy
             agent = agent_class.new
             if inherit_knowledge
               Array(ctx[:knowledge]).each do |entry|
-                agent.add_knowledge(entry.fetch(:content), metadata: entry.fetch(:metadata, {}))
+                agent.add_knowledge(entry.content, metadata: entry.metadata)
               end
             end
-            source = agent.invoke_async(input, config: task_config)
-            result_task = Phronomy::TaskResult.deferred(
-              name: "subagent-tool-#{name}"
-            )
-            source.on_complete do |result, error|
-              if error
-                (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
-              else
-                result_task.complete(result[:output])
-              end
+            Phronomy::AsyncOperation.call(name: "subagent-tool-#{name}",
+              on_error: ->(error) { raise error if on_error == :raise },
+              transform: ->(result) { result[:output] }) do
+              agent.invoke_async(input, config: task_config)
             end
-            result_task
           rescue => error
-            result_task ||= Phronomy::TaskResult.deferred(
-              name: "subagent-tool-#{name}"
-            )
-            (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
-            result_task
+            Phronomy::AsyncOperation.capture(name: "subagent-tool-#{name}",
+              on_error: ->(failure) { raise failure if on_error == :raise }) { raise error }
           end
-          private :execute_async
+          # Recovery requirements retain their Agent meaning across delegation.
+          def async_error_value(error)
+            raise error if error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
+
+            super
+          end
+          private :execute_async, :async_error_value
         end
 
         @_subagent_tool_classes = (@_subagent_tool_classes || []) + [tool_class]
@@ -138,7 +147,7 @@ module Phronomy
         invocation_context: nil,
         inherit_knowledge: true
       )
-        if Phronomy::Runtime.in_event_loop_context?
+        if Phronomy::WaitPolicy.blocking_forbidden?
           raise Phronomy::EventLoopReentrancyError,
             "dispatch_parallel cannot block the EventLoop; use dispatch_parallel_async"
         end
@@ -169,25 +178,17 @@ module Phronomy
           invocation_context: nil,
           inherit_knowledge: inherit_knowledge
         )
-        Phronomy::Execution.send(:__run_async, children,
+        Phronomy::Execution.run_async(children,
           timeout: timeout, cancellation_token: cancellation_token,
-          invocation_context: invocation_context, concurrency_limit: max_concurrency) do |child, execution|
-          # Preserve a child-specific context as well as this dispatch's controls.
-          # Agent admission adds that context's constraints to the supplied token.
-          binding = Phronomy::Concurrency::OperationBinding.new(
-            invocation_context: execution.invocation_context,
-            cancellation_token: child.config[:cancellation_token]
-          )
-          child_context = child.config[:invocation_context] ||
-            execution.invocation_context.merge(parent_task_id: invocation_context&.task_id)
-          begin
-            source = child.agent.invoke_async(child.input,
-              config: child.config.merge(cancellation_token: binding.token),
+          invocation_context: invocation_context, max_concurrency: max_concurrency) do |child, execution|
+          execution.start_child(
+            invocation_context: child.config[:invocation_context],
+            cancellation_token: child.config[:cancellation_token],
+            parent_task_id: invocation_context&.task_id
+          ) do |child_context, token|
+            child.agent.invoke_async(child.input,
+              config: child.config.merge(cancellation_token: token),
               invocation_context: child_context)
-            binding.track(source)
-          rescue
-            binding.close
-            raise
           end
         end.map do |outcomes|
           failure = outcomes.find { |outcome| outcome.status != :completed }
@@ -203,7 +204,7 @@ module Phronomy
         config: nil,
         inherit_knowledge: true
       )
-        if Phronomy::Runtime.in_event_loop_context?
+        if Phronomy::WaitPolicy.blocking_forbidden?
           raise Phronomy::EventLoopReentrancyError,
             "subagent cannot block the EventLoop; use the async Agent API"
         end
@@ -221,12 +222,6 @@ module Phronomy
         self.class.registered_subagents.keys.any? { |key| "dispatch_to_#{key}" == name.to_s }
       end
 
-      # Reserve child identity/input/knowledge in the parent's existing Agent transaction.
-      # @api private
-      def __prepare_coordination_record(execution, tx:)
-        DurableSubagentCoordinator.prepare(self, execution, tx: tx)
-      end
-
       private
 
       def prepare_tool_class(tool_class, invocation: nil)
@@ -263,16 +258,7 @@ module Phronomy
         end
       end
 
-      def active_knowledge_snapshot
-        journal_projection.context_records.filter_map do |record|
-          next unless record.kind == :knowledge
-
-          {
-            content: persistence.contents.fetch_text(record.content_ref),
-            metadata: (record.metadata || {}).dup.freeze
-          }.freeze
-        end.freeze
-      end
+      def active_knowledge_snapshot = knowledge_snapshot
 
       def build_subagent(agent_class, inherit_knowledge: true, knowledge_snapshot: nil)
         agent = agent_class.new
@@ -281,8 +267,8 @@ module Phronomy
         snapshot = knowledge_snapshot || active_knowledge_snapshot
         snapshot.each do |entry|
           agent.add_knowledge(
-            entry.fetch(:content),
-            metadata: entry.fetch(:metadata, {})
+            entry.content,
+            metadata: entry.metadata
           )
         end
         agent

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

@@ -10,6 +10,26 @@ module Phronomy
 
         module_function
 
+        def encode_handoff_state(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::HandoffState.from_h(payload)
+          build_record("phronomy.handoff_state", "0.2", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode HandoffState", error)
+        end
+
+        def decode_handoff_state(record)
+          payload = current_payload!(record, record_type: "phronomy.handoff_state",
+            format_version: "0.2", keys: Phronomy::MultiAgent::HandoffState::ATTRIBUTES, label: "HandoffState")
+          Phronomy::MultiAgent::HandoffState.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode HandoffState", error)
+        end
+
         def encode_team_root(value)
           payload = value.to_h
           Phronomy::MultiAgent::TeamRoot.from_h(payload)

data/lib/phronomy/multi_agent/persistence/handoff_state_repository.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns Handoff state encoding and the initial revision.
+      # @api private
+      class HandoffStateRepository
+        def initialize(view) = @view = view
+
+        def load(main_agent_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::HANDOFF_STATES).read(main_agent_id.to_s)
+              entry && decode(entry, main_agent_id)
+            end
+          end
+        end
+
+        # Lock before inspecting child existence so cancellation cannot decide
+        # that a child is absent using a snapshot from before its admission.
+        def load_locked(main_agent_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.atomic do |bound|
+              bound.check!(guards: [Phronomy::Storage::GuardRef.new(
+                resource: StorageSchema::HANDOFF_STATES, key: main_agent_id.to_s
+              )], conditions: [])
+              self.class.new(bound).load(main_agent_id)
+            end
+          end
+        end
+
+        def save(main_agent_id, expected_revision:, state:)
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = expected_revision.nil? ? nil : Integer(expected_revision)
+            revision = expected.nil? ? 1 : expected + 1
+            unless state.main_agent_id == main_agent_id.to_s && state.handoff_revision == revision
+              raise Phronomy::Storage::SerializationError, "Handoff identity/revision mismatch"
+            end
+            record = Codec.encode_handoff_state(state)
+            @view.atomic do |bound|
+              records = bound.records(StorageSchema::HANDOFF_STATES)
+              values = {key: main_agent_id.to_s, attributes: {active_agent_id: state.active_agent_id}, record: record}
+              entry = if expected.nil?
+                records.insert(**values, revision: revision)
+              else
+                records.replace(**values, expected_revision: expected, next_revision: revision)
+              end
+              decode(entry, main_agent_id, revision: revision)
+            end
+          rescue Phronomy::Storage::NotFoundError => error
+            raise Phronomy::Storage::ConflictError, error.message
+          end
+        end
+
+        def delete(main_agent_id, expected_revision:)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(StorageSchema::HANDOFF_STATES).delete(key: main_agent_id.to_s, expected_revision: Integer(expected_revision))
+          end
+        end
+
+        private
+
+        def decode(entry, main_agent_id, revision: nil)
+          state = Codec.decode_handoff_state(entry.record)
+          valid = entry.key == main_agent_id.to_s && state.main_agent_id == entry.key &&
+            state.handoff_revision == entry.revision && (!revision || revision == entry.revision) &&
+            entry.attributes == {active_agent_id: state.active_agent_id}
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Handoff identity/revision"
+          end
+          state
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/records.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Storage implementation of Team's own record operations.
+      # @api private
+      class Records
+        attr_reader :contents, :teams, :team_executions, :handoff_states
+
+        def initialize(view)
+          @view = view
+          @contents = Phronomy::Persistence::ContentRepository.new(Phronomy::ContentStore::StoredContents.new(view))
+          @teams = TeamRepository.new(view)
+          @team_executions = TeamExecutionRepository.new(view)
+          @handoff_states = HandoffStateRepository.new(view)
+        end
+
+        def guard_team!(team_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS, key: team_id)], conditions: [])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/storage_schema.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Domain-owned Team metadata, independent of coordination runtime loading.
+  # @api private
+  module MultiAgent
+    module Persistence
+      module StorageSchema
+        HANDOFF_STATES = Phronomy::Storage::Resource.new(id: "handoff.states", kind: :records,
+          attributes: {active_agent_id: :string})
+        ROOTS = Phronomy::Storage::Resource.new(id: "team.roots", kind: :records,
+          guard: {resource: "team.roots", via: :key})
+        EXECUTIONS = Phronomy::Storage::Resource.new(id: "team.executions", kind: :records,
+          attributes: {owner: :string, active: :boolean}, immutable_attributes: [:owner],
+          indexes: {owner: [:owner], owner_active: [:owner, :active]},
+          unique: [{name: :one_active_owner, fields: [:owner], where: {active: true}}],
+          guard: {resource: ROOTS.id, via: :owner})
+      end
+    end
+  end
+end