phronomy 0.26.0 → 0.28.0

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

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns execution activity, ownership, admission and durable record encoding.
+      # @api private
+      class TeamExecutionRepository
+        def initialize(view) = @view = view
+
+        def create_active(execution)
+          Phronomy::Persistence::StorageBoundary.call do
+            raise Phronomy::Storage::SerializationError, "create_active requires an active TeamExecution" unless execution.active?
+            record = Codec.encode_team_execution(execution)
+            admission do
+              @view.atomic do |bound|
+                entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).insert(key: execution.team_execution_id.to_s,
+                  revision: Integer(execution.execution_revision), attributes: attributes(execution), record: record)
+                decode(entry, execution.team_execution_id, owner: execution.team_id,
+                  revision: execution.execution_revision, active: true)
+              end
+            end
+          end
+        end
+
+        def load(team_execution_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            value = @view.atomic do |bound|
+              entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).read(team_execution_id.to_s)
+              entry && decode(entry, team_execution_id)
+            end
+            value || raise(Phronomy::Storage::NotFoundError, "TeamExecution not found: #{team_execution_id}")
+          end
+        end
+
+        def save(team_execution_id, expected_revision:, execution:)
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = Integer(expected_revision)
+            revision = Integer(execution.execution_revision)
+            raise Phronomy::Storage::ConflictError, "execution save must advance revision exactly once" unless revision == expected + 1
+            unless execution.team_execution_id.to_s == team_execution_id.to_s
+              raise Phronomy::Storage::SerializationError, "Execution identity mismatch"
+            end
+            record = Codec.encode_team_execution(execution)
+            admission do
+              @view.atomic do |bound|
+                entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).replace(key: team_execution_id.to_s,
+                  expected_revision: expected, next_revision: revision, attributes: attributes(execution),
+                  expected_attributes: execution.active? ? {active: true} : {}, record: record)
+                decode(entry, team_execution_id, owner: execution.team_id, revision: revision, active: execution.active?)
+              end
+            end
+          end
+        end
+
+        def list_active(team_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.atomic do |bound|
+              bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).scan(index: :owner_active,
+                equals: {owner: team_id.to_s, active: true}).map { |entry| decode(entry, entry.key, owner: team_id, active: true) }.freeze
+            end
+          end
+        end
+
+        def list(team_id, after: nil, limit: 100)
+          Phronomy::Persistence::StorageBoundary.call do
+            raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+            @view.atomic do |bound|
+              bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).scan(index: :owner, equals: {owner: team_id.to_s},
+                after: after&.to_s, limit: limit).map { |entry| decode(entry, entry.key, owner: team_id) }.freeze
+            end
+          end
+        end
+
+        def delete(team_execution_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).delete(key: team_execution_id.to_s)
+          end
+        end
+
+        def delete_for_team(team_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).delete_matching(index: :owner, equals: {owner: team_id.to_s})
+          end
+        end
+
+        def assert_idle!(team_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            condition = Phronomy::Storage::Condition::NoRows.new(resource: Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS,
+              index: :owner_active, equals: {owner: team_id.to_s, active: true})
+            @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS, key: team_id.to_s)],
+              conditions: [condition])
+          rescue Phronomy::Storage::ConditionFailedError => error
+            raise unless error.condition.equal?(condition)
+            raise Phronomy::AgentBusyError, error.message
+          end
+        end
+
+        private
+
+        def attributes(execution) = {owner: execution.team_id.to_s, active: execution.active?}
+
+        def admission
+          yield
+        rescue Phronomy::Storage::UniqueConstraintError => error
+          raise unless error.resource == Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
+          raise Phronomy::AgentBusyError, error.message
+        end
+
+        def decode(entry, team_execution_id, owner: nil, revision: nil, active: nil)
+          execution = Codec.decode_team_execution(entry.record)
+          valid = entry.key == team_execution_id.to_s && execution.team_execution_id == entry.key &&
+            execution.execution_revision == entry.revision && attributes(execution) == entry.attributes &&
+            (!owner || execution.team_id == owner.to_s) && (!revision || execution.execution_revision == revision) &&
+            (active.nil? || execution.active? == active)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Team Execution identity/metadata"
+          end
+          execution
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns Team root encoding and validates returned storage metadata.
+      # @api private
+      class TeamRepository
+        def initialize(view) = @view = view
+
+        def create(root)
+          Phronomy::Persistence::StorageBoundary.call do
+            record = Codec.encode_team_root(root)
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS).insert(key: root.team_id.to_s,
+                revision: Integer(root.team_revision), attributes: {}, record: record)
+              decode(entry, root.team_id, revision: root.team_revision)
+            end
+          end
+        end
+
+        def load(team_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            value = @view.atomic do |bound|
+              entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS).read(team_id.to_s)
+              entry && decode(entry, team_id)
+            end
+            value || raise(Phronomy::Storage::NotFoundError, "Team not found: #{team_id}")
+          end
+        end
+
+        def save(team_id, expected_revision:, root:)
+          Phronomy::Persistence::StorageBoundary.call do
+            expected = Integer(expected_revision)
+            revision = Integer(root.team_revision)
+            raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
+            unless root.team_id.to_s == team_id.to_s
+              raise Phronomy::Storage::SerializationError, "Team root identity mismatch"
+            end
+            record = Codec.encode_team_root(root)
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS).replace(key: team_id.to_s,
+                expected_revision: expected, next_revision: revision, attributes: {}, record: record)
+              decode(entry, team_id, revision: revision)
+            end
+          end
+        end
+
+        def delete(team_id)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS).delete(key: team_id.to_s)
+          end
+        end
+
+        private
+
+        def decode(entry, team_id, revision: nil)
+          root = Codec.decode_team_root(entry.record)
+          valid = entry.key == team_id.to_s && root.team_id == entry.key &&
+            root.team_revision == entry.revision && (!revision || revision == entry.revision)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Team identity/revision"
+          end
+          root
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/reserved_child_admission.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # Owns parent reservation checks and joins the Agent's durable admission.
+    # Reconstructed from current coordination wiring, never serialized as a Proc.
+    # @api public
+    class ReservedChildAdmission
+      def initialize(persistence:, owner:)
+        @persistence = persistence
+        @owner = Phronomy::Values::Immutable.copy(owner)
+        raise ArgumentError, "unknown reservation kind" unless %w[team subagent handoff].include?(@owner.fetch("kind"))
+        freeze
+      end
+
+      # Parent lock, current reservation check and child admission share one scope.
+      # No task, runtime owner or live Agent state is published before its commit.
+      # @api public
+      def admit(admission)
+        unless admission.correlation == @owner
+          raise Phronomy::Persistence::StateConflictError, "Child admission correlation mismatch"
+        end
+        @persistence.coordinator.atomic do |scope|
+          @persistence.participate(scope) do |records|
+            case @owner.fetch("kind")
+            when "team" then validate_team!(records, admission)
+            when "subagent" then validate_subagent!(records, admission, scope)
+            when "handoff" then validate_handoff!(records, admission, scope)
+            end
+            admission.accept_in(scope)
+          end
+        end
+        nil
+      end
+
+      private
+
+      def validate_team!(records, admission)
+        records.guard_team!(@owner.fetch("team_id"))
+        team = records.team_executions.load(@owner.fetch("team_execution_id"))
+        unless team.team_id == @owner.fetch("team_id") && team.active? && !team.metadata["cancel_requested"]
+          raise Phronomy::CancellationError, "Team run is no longer dispatchable"
+        end
+        slot = if @owner.fetch("slot") == "coordinator"
+          team.coordinator
+        else
+          assignment = team.assignments.find { |entry| entry.fetch("task_id") == @owner.fetch("slot") }
+          worker = assignment && team.workers.fetch(assignment.fetch("worker"))
+          worker&.merge("execution_id" => assignment.fetch("execution_id"))
+        end
+        unless slot && slot.fetch("execution_id") == admission.execution_id && slot.fetch("agent_id") == admission.agent_id
+          raise Phronomy::Persistence::StateConflictError, "Team reserved child identity mismatch"
+        end
+      end
+
+      def validate_subagent!(records, admission, scope)
+        @persistence.agent_store.guard_agents(scope, agent_ids: [@owner.fetch("parent_agent_id"), admission.agent_id])
+        parent = @persistence.agent_store.observe_execution(agent_id: @owner.fetch("parent_agent_id"),
+          execution_id: @owner.fetch("parent_execution_id"), scope: scope)
+        unless parent.continuable?
+          raise Phronomy::CancellationError, "Parent run is no longer dispatchable"
+        end
+        extension = @persistence.agent_store.execution_extension(agent_id: parent.agent_id, execution_id: parent.execution_id,
+          binding_key: DurableSubagentCoordinator::BINDING_KEY, scope: scope)
+        snapshot = records.contents.fetch_json(extension.state_ref)
+        raise Phronomy::CancellationError, "Parent reservation was cancelled" if snapshot["cancel_requested"]
+        slot = snapshot.fetch("children").find { |entry| entry.fetch("slot") == @owner.fetch("slot") }
+        unless slot && slot.fetch("agent_id") == admission.agent_id && slot.fetch("execution_id") == admission.execution_id
+          raise Phronomy::Persistence::StateConflictError, "Parent reserved child identity mismatch"
+        end
+      end
+
+      def validate_handoff!(records, admission, scope)
+        routing = records.handoff_states.load_locked(@owner.fetch("main_agent_id"))
+        unless routing && routing.active_agent_id == admission.agent_id
+          raise Phronomy::Persistence::StateConflictError, "Handoff responsibility changed before admission"
+        end
+        if Array(routing.metadata["cancelled_execution_ids"]).include?(admission.execution_id)
+          raise Phronomy::CancellationError, "Handoff reservation was cancelled"
+        end
+        @persistence.agent_store.guard_agents(scope, agent_ids: [@owner.fetch("main_agent_id"), admission.agent_id])
+        if routing.phase != "stable" && routing.pending_target_execution_id != admission.execution_id
+          raise Phronomy::Persistence::StateConflictError, "Handoff reserved Target identity mismatch"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/runtime_binding/engine_environment.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # Connects domain registries to the generic Runtime shutdown protocol.
+    # Construction does not register participants or start worker resources.
+    # @api private
+    class EngineEnvironment < ExecutionEnvironment
+      def initialize(runtime: Phronomy::Runtime.instance)
+        @runtime = runtime
+      end
+
+      def admissions
+        @runtime.__register_shutdown_participant(
+          key: AdmissionRegistry, participant: AdmissionRegistry.new
+        )
+      end
+
+      def ownership
+        existing_ownership || @runtime.__register_shutdown_participant(
+          key: TeamOwnershipRegistry, participant: TeamOwnershipRegistry.new
+        )
+      end
+
+      # Lookup must not register a participant, including during shutdown.
+      def existing_ownership = @runtime.__shutdown_participant(key: TeamOwnershipRegistry)
+
+      def current? = @runtime.equal?(Phronomy::Runtime.instance)
+
+      def submit(**options, &operation)
+        Phronomy::Execution.submit(runtime: @runtime, **options, &operation)
+      end
+    end
+  end
+end

data/lib/phronomy/{agent → multi_agent}/shared_state.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
-    # Implements peer coordination through a shared KnowledgeStore.
+  module MultiAgent
+    # Implements peer coordination through an invocation-local KnowledgeStore.
+    # @api public
     class SharedState
       # Semantic revision of the framework-owned SharedState instrumentation
       # applied on top of one specific researcher definition revision.
@@ -13,6 +14,8 @@ module Phronomy
       INSTRUMENTATION_DEFINITION_VERSION = 1
       private_constant :INSTRUMENTATION_DEFINITION_VERSION
 
+      # Findings shared by the sequential members of one invocation.
+      # @api public
       class KnowledgeStore
         def initialize
           @findings = []
@@ -78,8 +81,15 @@ module Phronomy
       # @api public
       def invoke(input, config: {})
         validate_termination!
-
         store = KnowledgeStore.new
+        cycles, terminated_by = coordinate_members(input, store)
+
+        {output: aggregate_findings(store), cycles: cycles, terminated_by: terminated_by}
+      end
+
+      private
+
+      def coordinate_members(input, store)
         max_cycles = self.class._max_cycles
         deadline = self.class._timeout ? Time.now + self.class._timeout : nil
         terminated_by = :max_cycles
@@ -87,15 +97,7 @@ module Phronomy
         cycle_limit = max_cycles || Float::INFINITY
 
         (1..cycle_limit).each do |cycle|
-          self.class._members.each do |member_config|
-            invoke_researcher(
-              member_config[:klass],
-              store,
-              cycle,
-              input,
-              member_config[:instruction]
-            )
-          end
+          invoke_members(input, store, cycle)
           completed_cycles = cycle
 
           if self.class._terminate_when&.call(store)
@@ -109,17 +111,25 @@ module Phronomy
           end
         end
 
-        output = if self.class._aggregator
+        [completed_cycles, terminated_by]
+      end
+
+      def invoke_members(input, store, cycle)
+        self.class._members.each do |member_config|
+          invoke_researcher(
+            member_config[:klass], store, cycle, input, member_config[:instruction]
+          )
+        end
+      end
+
+      def aggregate_findings(store)
+        if self.class._aggregator
           self.class._aggregator.call(store)
         else
           store.read_all
         end
-
-        {output: output, cycles: completed_cycles, terminated_by: terminated_by}
       end
 
-      private
-
       def validate_termination!
         return if self.class._max_cycles || self.class._timeout
 
@@ -148,28 +158,8 @@ module Phronomy
 
       def build_instrumented_researcher(researcher_class, store, cycle)
         agent_key = researcher_class.name&.to_sym || researcher_class.object_id.to_s.to_sym
-
-        read_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
-          tool_name "read_store"
-          description "Read all current findings from the shared knowledge store. " \
-            "Call this to see what other researchers have discovered."
-          execution_mode :cooperative
-
-          define_method(:execute) { store.read_all.to_json }
-        end
-
-        write_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
-          tool_name "write_finding"
-          description "Record a new finding into the shared knowledge store so " \
-            "that other researchers can build on your discovery."
-          execution_mode :cooperative
-          param :content, type: :string, desc: "The finding to record"
-
-          define_method(:execute) do |content:|
-            store.write(agent: agent_key, content: content, cycle: cycle)
-            "Finding recorded."
-          end
-        end
+        read_tool = build_read_tool(store)
+        write_tool = build_write_tool(store, cycle, agent_key)
 
         definitions = researcher_class.tools.to_h do |tool_class|
           [tool_class, researcher_class.tool_aliases[tool_class]]
@@ -197,12 +187,39 @@ module Phronomy
         end
       end
 
+      def build_read_tool(store)
+        Class.new(Phronomy::Tool::Base) do
+          tool_name "read_store"
+          description "Read all current findings from the shared knowledge store. " \
+            "Call this to see what other researchers have discovered."
+          execution_mode :cooperative
+
+          define_method(:execute) { store.read_all.to_json }
+        end
+      end
+
+      def build_write_tool(store, cycle, agent_key)
+        Class.new(Phronomy::Tool::Base) do
+          tool_name "write_finding"
+          description "Record a new finding into the shared knowledge store so " \
+            "that other researchers can build on your discovery."
+          execution_mode :cooperative
+          param :content, type: :string, desc: "The finding to record"
+
+          define_method(:execute) do |content:|
+            store.write(agent: agent_key, content: content, cycle: cycle)
+            "Finding recorded."
+          end
+        end
+      end
+
       def instrumented_definition_for(researcher_class)
         parent_def = researcher_class.agent_definition
         parent_id = parent_def.fetch(:id)
         parent_version = parent_def.fetch(:version)
 
         {
+          # Keep the existing semantic ID across the Ruby namespace migration.
           id: "Phronomy::Agent::SharedState::Instrumented/#{parent_id}@#{parent_version}".freeze,
           version: INSTRUMENTATION_DEFINITION_VERSION
         }.freeze

data/lib/phronomy/multi_agent/store.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # MultiAgent-owned durable operations and observations. An injected record
+    # adapter implements storage; this framework never selects a DB or codec.
+    # @api public
+    class Store
+      # Composition supplies the optional configured store without constructing
+      # a fallback. Team and Orchestrator retain their different fallback rules.
+      # @api private
+      def self.install_configured_provider(&provider)
+        raise ArgumentError, "store provider requires a block" unless provider
+        @configured_provider = provider
+        nil
+      end
+
+      # @api private
+      def self.configured = @configured_provider.call
+
+      attr_reader :coordinator, :agent_store
+
+      # Record protocol for MultiAgent-owned framework operations only.
+      # @api private
+      attr_reader :contents, :teams, :team_executions, :handoff_states
+
+      def initialize(coordinator:, records:, agent_store:)
+        @coordinator, @record_adapter = coordinator, records
+
+        unless agent_store.coordinator.equal?(coordinator)
+          raise Phronomy::Persistence::TransactionError, "Team and Agent stores must share one Persistence coordinator"
+        end
+        @agent_store = agent_store
+        @records = coordinator.bind(records)
+        @contents = @records.contents
+        @teams = @records.teams
+        @team_executions = @records.team_executions
+        @handoff_states = @records.handoff_states
+      end
+
+      # A domain operation owns this short transaction. A coordinating parent
+      # can instead call participate with its existing shared scope.
+      def transaction
+        coordinator.atomic do |scope|
+          participate(scope) { |records| yield records, scope }
+        end
+      end
+
+      def participate(scope, &operation)
+        scope.participate(persistence: coordinator, adapter: @record_adapter, &operation)
+      end
+
+      def handoff_leaf(execution_id, main_agent_id:, scope: nil)
+        return coordinator.atomic { |current| handoff_leaf(execution_id, main_agent_id: main_agent_id, scope: current) } unless scope
+        routing = participate(scope) { |records| records.handoff_states.load(main_agent_id) }
+        raise Phronomy::Persistence::NotFoundError, "Handoff history is absent" unless routing
+        identity = agent_store.execution_identity(execution_id, scope: scope)
+        unless identity.correlation == {"kind" => "handoff", "main_agent_id" => main_agent_id}
+          raise Phronomy::Persistence::StateConflictError, "Execution does not belong to this Handoff anchor"
+        end
+        seen = {}
+        loop do
+          raise Phronomy::Persistence::SerializationError, "Cyclic Handoff chain" if seen[identity.execution_id]
+          seen[identity.execution_id] = true
+          observed = agent_store.observe_execution(agent_id: identity.agent_id, execution_id: identity.execution_id, scope: scope)
+          return observed unless observed.status == :handed_off
+          receipt = observed.transfer_receipt
+          unless receipt && receipt.fetch("owner_key") == "handoff:#{main_agent_id}"
+            raise Phronomy::Persistence::SerializationError, "Invalid transfer receipt"
+          end
+          identity = Phronomy::Agent::ReservedExecution.new(agent_id: receipt.fetch("target_agent_id"), execution_id: receipt.fetch("target_execution_id"))
+        end
+      end
+
+      def handoff_result(execution_id, main_agent_id:)
+        assert_observation_thread!
+        transaction do |records, scope|
+          leaf = handoff_leaf(execution_id, main_agent_id: main_agent_id, scope: scope)
+          next leaf.to_result unless leaf.absent?
+          routing = records.handoff_states.load(main_agent_id)
+          if Array(routing.metadata["cancelled_execution_ids"]).include?(leaf.execution_id)
+            leaf.to_result.merge(status: :cancelled).freeze
+          elsif routing.phase != "stable" && routing.pending_target_execution_id == leaf.execution_id
+            leaf.to_result.merge(status: :active, reserved: true).freeze
+          else
+            raise Phronomy::Persistence::NotFoundError, "Reserved Handoff execution is absent"
+          end
+        end
+      end
+
+      def forget_subagents(agent_id:, execution_id:)
+        transaction do |records, scope|
+          extension = agent_store.execution_extension(agent_id: agent_id, execution_id: execution_id,
+            binding_key: DurableSubagentCoordinator::BINDING_KEY, scope: scope)
+          raise Phronomy::Persistence::NotFoundError, "Subagent history is absent" unless extension&.state_ref
+          snapshot = records.contents.fetch_json(extension.state_ref)
+          children = snapshot.fetch("children")
+          ids = ([agent_id] + children.map { |child| child.fetch("agent_id") }).uniq.sort.select { |id| agent_store.exist?(id) }
+          agent_store.guard_agents(scope, agent_ids: ids)
+          parent = agent_store.observe_execution(agent_id: agent_id, execution_id: execution_id, scope: scope)
+          raise Phronomy::AgentBusyError, "Subagent history retains unfinished parent" unless parent.terminal?
+          children.each do |child|
+            observed = agent_store.observe_execution(agent_id: child.fetch("agent_id"), execution_id: child.fetch("execution_id"), scope: scope)
+            if !observed.terminal? && !(observed.absent? && snapshot["cancel_requested"])
+              raise Phronomy::AgentBusyError, "Subagent history retains unfinished child"
+            end
+          end
+          agent_store.remove_execution_extension(agent_id: agent_id, execution_id: execution_id,
+            binding_key: DurableSubagentCoordinator::BINDING_KEY, scope: scope)
+          ids.each { |id| agent_store.release_retention(agent_id: id, owner_key: "subagent:#{execution_id}", scope: scope) }
+        end
+        true
+      end
+
+      def forget_handoff(main_agent_id)
+        transaction do |records, scope|
+          routing = records.handoff_states.load_locked(main_agent_id)
+          raise Phronomy::Persistence::NotFoundError, "Handoff history is absent" unless routing
+          ids = (Array(routing.metadata["retained_agent_ids"]) + [main_agent_id, routing.active_agent_id]).uniq.sort
+          agent_store.guard_agents(scope, agent_ids: ids)
+          unless routing.phase == "stable" && ids.all? { |id| agent_store.active_executions(agent_id: id, scope: scope).empty? }
+            raise Phronomy::AgentBusyError, "Handoff history retains unfinished work"
+          end
+          records.handoff_states.delete(main_agent_id, expected_revision: routing.handoff_revision)
+          ids.each { |id| agent_store.release_retention(agent_id: id, owner_key: "handoff:#{main_agent_id}", scope: scope) }
+        end
+        true
+      end
+
+      def result(team_execution_id)
+        assert_observation_thread!
+        execution = team_executions.load(team_execution_id)
+        {
+          team_execution_id: execution.team_execution_id, team_id: execution.team_id,
+          status: execution.status, phase: execution.phase,
+          result_ref: execution.result_ref, error_ref: execution.error_ref,
+          result: execution.result_ref && contents.fetch_json(execution.result_ref),
+          error: execution.error_ref && contents.fetch_json(execution.error_ref)
+        }.then { |value| Phronomy::Values::Immutable.copy(value) }
+      end
+
+      def runs(team_id, after: nil, limit: 100)
+        assert_observation_thread!
+        team_executions.list(team_id, after: after, limit: limit)
+      end
+
+      private
+
+      def assert_observation_thread!
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "Durable observation cannot block EventLoop"
+        end
+      end
+    end
+  end
+end